Policy Overlay Projection Contract (Draft) — PREP-POLICY-ENGINE-30-001

Status: Draft (2025-11-20) Owners: Policy Guild · Cartographer Guild · Platform/Observability Guild Scope: Define the overlay projection output that depends on metrics/logging outputs from POLICY-ENGINE-29-004. Intended to unblock POLICY-ENGINE-30-001 and downstream 30-00x tasks.

1) Inputs

• policy_run_id (required)
• tenant_id (required)
• Metrics/logging envelope from 29-004 (pending): expected fields include run duration, rule evaluation counts, fact ingest counts, cache hit/miss, scheduler job metadata.
• Optional: advisory/KB versions, SBOM/VEX digests, risk profile version.

2) Overlay projection shape (proposed)

{
  "overlay_id": "ulid",
  "policy_run_id": "...",
  "tenant_id": "...",
  "generated_at": "2025-11-20T00:00:00Z",
  "schema_version": "policy.overlay.v1",
  "metrics": {
    "duration_ms": 1234,
    "rules_evaluated": 4200,
    "facts_ingested": 98765,
    "cache_hit_rate": 0.92,
    "p95_rule_latency_ms": 8
  },
  "logs_pointer": "bundle://telemetry/logs.ndjson",
  "inputs": {
    "sbom_digest": "sha256:...",
    "advisories_digest": "sha256:...",
    "vex_digest": "sha256:..."
  },
  "provenance": {
    "engine_version": "x.y.z",
    "profile": "policy-default",
    "scheduler_job_id": "..."
  }
}

• Determinism: sorted keys; timestamps UTC; numeric metrics fixed to 3 decimal places where fractional.
• Overlay acts as the query surface for simulation/change events (30-002/30-003) and UI overlays.

3) Storage & API

• Stored as NDJSON under overlays/{tenant_id}/{policy_run_id}.ndjson in policy engine store; referenced by Export/Console bundle.
• API (proposed): GET /policy-runs/{policy_run_id}/overlay with ETag = sha256 of payload; POST /policy-runs/{policy_run_id}/overlay/rebuild for re-projection when metrics contract changes.

4) Open dependencies / decisions

• Need final metrics/logging schema from 29-004 to lock metrics section (owner: Platform/Observability).
• Confirm cache metrics naming and units.
• Confirm whether overlay should embed inline logs vs pointer.
• Clarify retention/GC policy for overlays (suggest 30d, aligned with export bundles).

5) Handoff

Use this document as the PREP artefact for POLICY-ENGINE-30-001. Update once 29-004 publishes metrics/logging outputs; then fix schema_version to overlay.v1 and add JSON Schema under docs/modules/policy/schemas/.