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, or require-approval.
priority
Integer. Higher priority rules are evaluated first. Ties are resolved by document order.

Invariants

  • match conditions may only reference fields defined by this spec: action.schema, actor.actor_class, actor.actor_id, tenant.organization, tenant.workspace, tenant.environment, and inputs.* 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-approval must name an approval policy: which approver roles may decide, and an expiry after which the request lapses.

Evaluation semantics Stable

  1. Sort rules by priority descending, then document order.
  2. Evaluate rules in order; the first matching rule decides.
  3. If no rule matches, the decision is deny (deny by default).
  4. 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 deny is terminal: it cannot be overridden by a later approval. Only require-approval decisions 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_from timestamp. The effective bundle for an action is the highest version whose effective_from is 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).