ADR 0004: Policy bundles and immutable snapshots
- Status: Proposed
- Date: 2026-10-03
- Approval needed: architecture and policy owners (see OD-011–OD-013)
Context
Policies must be reusable across tenants while remaining deterministic, reviewable, and safe to evaluate in a latency-sensitive service. General-purpose policy languages and request-time dependency resolution expose unnecessary complexity.
Decision
Author versioned YAML conforming to the policy bundle schema. Use CEL only for typed, pure match predicates in a constrained environment. Resolve explicit imports and typed overrides ahead of deployment, compile to canonical JSON, pin dependencies and artefacts by SHA-256 digest, and atomically install a complete immutable snapshot.
Use ordered platform, tenant/workspace, and application/deployment layers. Mandatory platform rules can be non-overridable. Do not support implicit inheritance or general deep merge. Initial composition is deny-wins.
Consequences
- Policy activation can be reproduced, signed, canaried, and rolled back.
- The evaluator performs no remote version resolution or partial activation.
- Authors get less expressiveness than Rego, intentionally.
- Compiler and lockfile formats become important compatibility surfaces.