Policy Engine

Reference Architecture

The Policy Engine is the deterministic boundary for every governed action. It evaluates JsonLogic rules from the active policy bundles and emits a locally versioned PolicyDecision profile that the Compiler, Critic, and Tool Gateway consume. That illustrative standalone shape is distinct from the canonical NormalizedPolicyOutcome, ComposedPolicyOutcome and AuthorizationOutcome execution attachments and the existing rule/risk/gate/record fields.

Definition

A pure function over (rules, eval_context) → policy decision. Stateless. Replayable. Never delegated to the model.

Why it exists

Model self-policing is not a security boundary. The Policy Engine moves allow/deny, required evidence, prohibited claims, native risk checks, and approval obligations outside the model so they remain deterministic.

Inputs

• PolicyBundle[] from the active Context Pack (priority-sorted)
• Guardrails (must_refuse, must_escalate, redaction_rules) from the pack
• Eval context: RunContext + InvokeRequest + structured request context
• Optional capability declaration with ActionRisk plus concrete call arguments, identity, evidence, and freshness state

Outputs

• PolicyDecision:
  • allowed: bool
  • reason: string
  • action_risk_evaluation?: ActionRiskEvaluation
  • effective_approval_mode?: ApprovalMode as the v1 compatibility projection
  • requires_approval_gate?: string
  • requires[] (evidence references the action must produce)
  • prohibits[] (capabilities the rule disallows)
  • policy_decision_id
  • matched_rule_ids[]
• Audit metadata persisted to the trace and the Decision Record

How it works

1. Evaluates independent guardrails; a required denial prevents permission, while applicable obligations remain recorded even when business priority changes the business verdict.
2. Iterates policy bundles in priority order; evaluates each rule’s if against the eval context.
3. For each fired rule, captures then (allow, requires, prohibits, v1 approval projection, gate).
4. Resolves business verdict conflicts: higher numeric priority wins; explicit deny beats allow at equal priority. Guardrail denial/escalation and approval remain independent conjunctive requirements.
5. If a capability declares native ActionRisk, evaluates every dimension conjunctively against action_risk_policy; a single violation denies the capability.
6. Computes the required v1 approval-mode projection for schema compatibility without treating it as the native risk model.
7. Emits policy_decision_id, matched rule ids, obligations, and risk evaluation for audit.

composePolicyOutcomes in the deterministic reference implements composition over normalized applicable outcomes, with explicit guardrail and business categories. Higher-priority business verdicts win; deny wins at equal priority. Guardrail denial/escalation and required approval remain independent of business priority. No applicable business decision defaults to deny. A failed evaluation, malformed outcome or conflicting duplicate produces an error outcome, never permission. Applicable obligations and pinned bundle references remain visible in stable order, including obligations attached to a lower-priority outcome; changing a verdict does not silently discharge those obligations.

This reference function does not execute JsonLogic or authenticate policy inputs. The existing compiler’s tool-surfacing filter conservatively accumulates active prohibits; it does not demonstrate the complete business-priority authorization decision above. That filter remains unchanged. Runtime authority, tenant, containment, data-flow, budget, revocation and approval checks are additional conjunctive conditions: a business allow cannot override any failed required condition. A deployment must verify current observations at dispatch and resume.

Checkpoints in the runtime

• Compile-time — guardrail activation, rule selection.
• Plan-time — Critic verifies plan steps against rules and decision_binding.
• Execute-time — Tool Gateway re-evaluates per ToolCallEnvelope with the latest context.
• Wake/resume-time — validate current support, authority/revocation, exact stored action approval, active boundary, external preconditions and original budget; a historical policy allow cannot authorize changed actions or recovered dispatch.

Failure modes

• An applicable rule throws on malformed JsonLogic — the reference compiler rejects with ContextCompileError (code: "policy_eval_error", stage: "policy_resolution") before returning a CompiledContext. Safe details identify the bundle, rule and if expression path; predicate/request values and dependency stack traces are excluded. A legitimate false predicate may select else; an evaluation error cannot. The current PolicyRule contract has no non_enforcing skip flag.
• Two equal-priority rules conflict — explicit deny wins; otherwise refuse.
• Unsupported native risk dimension or v1 projection outside policy — reject deterministically.
• Stale rule cache after a bundle promotion — mitigated by content-addressed bundle hashing.

Operational concerns

• Policy bundle versioning per environment; promotion is deliberate.
• Per-rule evaluation latency budget; alert on slow rules.
• Lint-on-merge: unreachable rules, unsatisfiable conditions, missing decision_binding.
• Separation of duties for policy authoring vs. approval.
• Protect policy/profile/release administration from self-authorized lowering of mandatory requirements. Evaluate explicit pinned facts/time observations; the pure reference cannot authenticate broker facts or enforce storage atomicity.

Evaluation metrics

• Policy compliance rate (fraction of runs with no guardrail violation).
• Rule-level fire rate; alert on rules that never or always fire.
• Mean time from policy authored → enforced.
• Native risk false-allow/false-deny rate, sliced by dimension.
• V1 approval-projection mismatch rate during migration.