Home / Spec / Policy model
Execution chain · Stage 4 of 6 — Deterministic policy
Deterministic policy model
Stable
Contract version 1.0. This is stage 4 of the execution chain.
Policy is the decision point of the execution chain. A policy bundle declares, in data, which actions may proceed under which conditions. Evaluation is deterministic and pure: the same proposal, actor, tenant, and bundle version always produce the same decision.
Expression Stable
A policy bundle is a versioned JSON document. It contains an ordered list of rules. Each rule has:
id- Stable rule identifier. Used in the evaluation trace.
description- Human-readable intent. Does not affect evaluation.
match- Conditions over the proposal: action schema, actor class or id, tenant scope, input fields. All conditions must hold for the rule to match.
effect- One of
allow,deny, orrequire-approval. priority- Integer. Higher priority rules are evaluated first. Ties are resolved by document order.
Invariants
matchconditions may only reference fields defined by this spec:action.schema,actor.actor_class,actor.actor_id,tenant.organization,tenant.workspace,tenant.environment, andinputs.*paths declared in the action schema.- Conditions are side-effect-free comparisons (equality, set membership, numeric ranges, string prefixes). No function calls, no external lookups.
require-approvalmust name an approval policy: which approver roles may decide, and an expiry after which the request lapses.
Evaluation semantics Stable
- Sort rules by
prioritydescending, then document order. - Evaluate rules in order; the first matching rule decides.
- If no rule matches, the decision is
deny(deny by default). - Record the evaluation trace: bundle version, rules evaluated, the matching rule (if any), and the decision.
Invariants
- Evaluation is a pure function of (proposal, actor, tenant, bundle version, effective date). No network, no randomness, no clock reads except the explicit effective-date input.
- The same inputs always produce the same decision and the same trace.
- A
denyis terminal: it cannot be overridden by a later approval. Onlyrequire-approvaldecisions route to a human.
Versioning Stable
- Policy bundles are versioned with semantic versions (
major.minor.patch). Published versions are immutable. - Each version carries an
effective_fromtimestamp. The effective bundle for an action is the highest version whoseeffective_fromis at or before the action's effective date. - Every policy decision records the bundle version it was evaluated under, so historical actions remain interpretable under the rules that governed them.
- Breaking changes (new required match fields, changed effect semantics) require a major version bump and a migration note.
Example policy document
Illustrative referencePolicy bundle v2.1.0. Field names follow this spec.
{
"bundle": "billing-default",
"version": "2.1.0",
"effective_from": "2026-10-01T00:00:00Z",
"rules": [
{
"id": "deny-refunds-in-production",
"description": "Refunds in production always need a human.",
"priority": 100,
"match": {
"action.schema": "billing.refund.issue",
"tenant.environment": "production"
},
"effect": "require-approval",
"approval": {
"roles": ["billing-approver"],
"expires_after_minutes": 240
}
},
{
"id": "allow-low-value-invoices",
"description": "Service actors may issue invoices under $1,000.",
"priority": 50,
"match": {
"action.schema": "billing.invoice.issue",
"actor.actor_class": "service",
"inputs.amount_cents": { "lte": 100000 }
},
"effect": "allow"
},
{
"id": "deny-cross-environment",
"description": "Nothing may act outside its own environment scope.",
"priority": 10,
"match": {
"tenant.environment": { "not_in": ["production", "staging"] }
},
"effect": "deny"
}
]
}
Example evaluator
Illustrative referenceImplements the evaluation semantics above for equality, lte, and not_in conditions.
// Illustrative reference: deterministic policy evaluator.
function getPath(obj, path) {
return path.split(".").reduce(function (acc, key) {
return acc == null ? undefined : acc[key];
}, obj);
}
function conditionHolds(actual, expected) {
if (expected !== null && typeof expected === "object" && !Array.isArray(expected)) {
if ("lte" in expected) return typeof actual === "number" && actual <= expected.lte;
if ("not_in" in expected) return !expected.not_in.includes(actual);
return false; // unknown operator: condition does not hold
}
return actual === expected;
}
function ruleMatches(rule, proposal) {
return Object.entries(rule.match).every(function ([path, expected]) {
return conditionHolds(getPath(proposal, path), expected);
});
}
function evaluatePolicy(bundle, proposal) {
const rules = [...bundle.rules].sort((a, b) => b.priority - a.priority);
const trace = { bundle: bundle.bundle, version: bundle.version, evaluated: [] };
for (const rule of rules) {
const matched = ruleMatches(rule, proposal);
trace.evaluated.push({ rule: rule.id, matched });
if (matched) {
trace.decision = rule.effect;
trace.matched_rule = rule.id;
return { decision: rule.effect, approval: rule.approval || null, trace };
}
}
trace.decision = "deny"; // deny by default
return { decision: "deny", approval: null, trace };
}
Related: execution chain (stage 4 context), evidence model (the trace becomes evidence), approval-inbox reference (require-approval in code).