# Implementation plan — Policy Engine

## Delivery phases
- **Phase 1 – Deterministic evaluation core**  
  Finalise DSL compiler, runtime guardrails, evaluation workers, change-stream integration (advisories, VEX, SBOM), and append-only effective findings.
- **Phase 2 – Orchestration & incremental runs**  
  Implement run scheduler, incremental deltas, change-stream replay, simulation hooks, and determinism hashing.
- **Phase 3 – Policy Studio workflows**  
  Deliver policy registry, versioning, approvals, explain trace API, client editor integration, and signed promotion pipelines.
- **Phase 4 – Simulation & approvals**  
  Provide diff/simulation APIs, approval queues, change management, and integration with CLI/Console.
- **Phase 5 – Exports & offline parity**  
  Produce policy bundles, explain archives, Offline Kit assets, and deterministic manifests; integrate with Export Center.
- **Phase 6 – Observability & hardening**  
  Ship metrics, logs, traces, incident response runbooks, guardrail analyzers, and compliance attestations.

## Work breakdown
- **Evaluation engine**
  - DSL compiler with caching, static analysis, and guard rails (no wall-clock/random/network outside allowlist).
  - Batch evaluator with deterministic ordering, change-stream inputs, policy IR caching.
  - Explain trace generation, evidence linking, storage in object store.
- **Run orchestration**
  - Scheduler for incremental runs, job leasing, fair-share per tenant/policy.
  - Determinism hash + replay verification, time-travel snapshots, resume cursors.
  - Simulation endpoints returning diff summaries, rationale breakdown, exit codes.
- **Policy Studio**
  - Policy registry (draft→review→approved), signed promotion pipeline, approvals workflow (multi-step).
  - Console integration (editor, simulation, approvals, explain viewer) and CLI parity.
- **Integrations**
  - Inputs: Concelier, Excititor, SBOM Service, VEX Lens, runtime signals.
  - Outputs: Findings ledger, Vuln Explorer, Notify (policy events), Export Center (policy bundles).
  - Authority scopes, tenancy enforcement, RBAC for policy author/reviewer/operator.
- **Observability & compliance**
  - Metrics: run duration, evaluation verdict counts, simulation latency, guard violations.
  - Logs/traces with trace ID propagation, policy version references, tenant scoping.
  - Guard analyzers (static + runtime), unit/property tests, compliance reports.
- **Docs & tooling**
  - Update DSL guide, policy lifecycle/runbooks, simulation manual, CLI reference, Offline Kit instructions.
  - Provide sample policies, fixtures, and analyzer rules.

## Acceptance criteria
- Evaluation engine deterministic across runs; effective findings materialised only by Policy Engine; guardrails prevent forbidden IO.
- Incremental runs handle advisory/VEX/SBOM deltas within ≤5 min SLA; determinism hash and replay verification succeed.
- Policy Studio supports draft/review/approval, signed promotions, simulation diffing, and explain traces in UI/CLI.
- Exports (policy bundles, explain archives) reproducible with signed manifests; Offline Kit packages deliver same tooling.
- Observability dashboards show run metrics, guard violations, simulation usage; alerts trigger on determinism hash mismatch or backlog.
- CLI/Console parity for policy management, simulation, approvals, and export workflows.

## Risks & mitigations
- **Non-determinism:** strict static analysis, runtime guard, determinism hash, replay tests.
- **Policy drift vs reality:** simulation diff previews, approval workflow, history/audit trail.
- **Scaling evaluations:** sharded workers, incremental deltas, caching, job queue fairness.
- **Guard bypass:** analyzers integrated into CI, runtime guard rejects forbidden operations.
- **Offline compliance:** deterministic exports, manifest verification, documentation for sealed-mode deployments.

## Test strategy
- **Unit:** DSL parsing, guard analyzer, evaluation pipeline, simulation diff calculations.
- **Property:** randomised policy inputs verifying determinism and guard enforcement.
- **Integration:** Concelier/Excititor/SBOM feeds → Policy Engine → findings ledger, simulation, approvals.
- **Performance:** evaluation throughput, change-stream backlog recovery, simulation under load.
- **Security/compliance:** RBAC/tenancy, analyzer enforcement, audit logging, signed promotions.
- **Offline:** export/import of policy bundles, explain archives, CLI verification.

## Definition of done
- Policy Engine core, orchestration, Policy Studio workflows, exports, and observability delivered with runbooks and Offline Kit parity.
- Documentation suite (overview, architecture, DSL, lifecycle, Studio, simulation, CLI) updated with imposed rule statements.
- ./TASKS.md and ../../TASKS.md reflect status; analyzers integrated into CI; compliance evidence captured.