git.stella-ops.org/docs/modules/policy/prep/2025-11-20-policy-engine-30-001-prep.md

Policy Engine · Overlay Projection Prep (POLICY-ENGINE-30-001)

• Date: 2025-11-20
• Depends on: Path/Scope schema (29-002) and observability contract (29-004)
• Working directory: src/Policy/StellaOps.Policy.Engine

Projection contract

• Input: PathScope documents (see 29-002) + PolicyRule definitions.
• Output: OverlayProjection objects stored/snapshotted for replay:
  • tenant (string)
  • ruleId (string)
  • subject (purl/cpe, optional packagePath)
  • scope (copied from input)
  • decision (allow|deny|warn|defer)
  • reasons[] (machine-readable codes; e.g., path-match, severity-threshold, capability-needed)
  • artifacts (hash list) — evidenceHash, treeDigest?, dsseEnvelopeHash? used in evaluation
  • effectiveAt (ISO-8601 UTC) — time projection became active
  • expiresAt? (ISO-8601 UTC) — optional
  • version (int) — monotonic per ruleId

Ordering & determinism

• Projection list sorted by (ruleId, subject.purl|cpe, scope.pathMatch, scope.pattern, effectiveAt).
• Hash for artifacts.evidenceHash reused from input to keep replay stable.

Storage hints

• Persist overlays as NDJSON under overlay/{tenant}/{ruleId}/{version}.ndjson for air-gapped export.
• Snapshots include header line with schema version overlay-projection-v1 followed by sorted projections.

Acceptance for prep completion

• Projection shape, ordering, and filenames are frozen for implementation tasks 30-001..30-003.
• Downstream simulation/change-event work (30-002/30-003) must emit/consume this structure without mutation.