# 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)
```json
{
  "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/`.