# Declarative Multi-Modal Policy Engine

## Module
Policy

## Status
IMPLEMENTED

## Description
Policy engine with 12+ gate types, trust lattice merge, OPA adapter integration, policy DSL, evidence-weighted scoring, and determinization gates covering CVSS, EPSS, VEX trust, reachability, unknowns, SBOM presence, and signature requirements.

## Implementation Details
- **Policy Evaluator**: `src/Policy/StellaOps.Policy.Engine/Evaluation/PolicyEvaluator.cs` -- core policy evaluation with expression evaluation
  - `PolicyExpressionEvaluator.cs` -- evaluates policy expressions against findings
  - `PolicyEvaluationContext.cs` -- evaluation context with tenant, snapshot, and environment info
  - `VerdictSummary.cs` -- verdict summary generation
- **Policy Gates**: `src/Policy/StellaOps.Policy.Engine/Gates/`
  - `PolicyGateEvaluator.cs` -- multi-gate orchestrator with 5 gate stages (Evidence, Lattice, VEX Trust, Uncertainty, Confidence)
  - `VexTrustGate.cs` -- VEX trust score and signature verification per environment
  - `DriftGateEvaluator.cs` -- drift-based gate for cross-release delta
  - `StabilityDampingGate.cs` -- stability damping to prevent flapping
  - `IDeterminizationGate.cs` -- interface for determinization gates
  - `Gates/Determinization/` -- determinization gate implementations
- **Trust Lattice**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/`
  - `TrustLatticeEngine.cs` -- K4 four-valued logic evaluation pipeline
  - `ClaimScoreMerger.cs` -- lattice-based merge with conflict penalization
  - VEX normalizers for CycloneDX, OpenVEX, CSAF formats
- **Policy DSL**: `src/Policy/StellaOps.PolicyDsl/` -- declarative policy language compiler
  - Compiles YAML-based policy definitions into executable evaluation rules
- **Scoring Engines**: `src/Policy/StellaOps.Policy.Engine/Scoring/`
  - `SimpleScoringEngine.cs`, `AdvancedScoringEngine.cs`, `ProofAwareScoringEngine.cs`
  - `EvidenceWeightedScore/` -- evidence-weighted scoring with proof integration
  - `ProfileAwareScoringService.cs` -- risk profile-driven scoring
  - `ScoringEngineFactory.cs` -- engine selection based on configuration
- **CVSS Scoring**: `src/Policy/StellaOps.Policy.Scoring/` -- multi-version CVSS engine (v2, v3.x, v4.0)
- **Determinism Guards**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/`
  - `DeterminismGuardService.cs` -- runtime determinism enforcement
  - `ProhibitedPatternAnalyzer.cs` -- static analysis for non-deterministic patterns
  - `GuardedPolicyEvaluator.cs` -- wraps evaluator with determinism checks
- **Policy Compilation**: `src/Policy/StellaOps.Policy.Engine/Compilation/` -- policy pack compilation
  - `PolicyCompilationService` -- compiles policy YAML into evaluation bundles
  - Endpoints: `PolicyCompilationEndpoints.cs`, `PolicyLintEndpoints.cs`
- **Effective Decision Map**: `src/Policy/StellaOps.Policy.Engine/EffectiveDecisionMap/` -- materialized decision lookup
- **Counterfactuals**: `src/Policy/__Libraries/StellaOps.Policy/Counterfactuals/` -- "what-if" analysis for blocked findings
- **Simulation**: `src/Policy/StellaOps.Policy.Engine/Simulation/` -- risk simulation with breakdowns
- **Unknowns Integration**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/` -- unknowns ranking and budget enforcement

## E2E Test Plan
- [ ] Compile a YAML policy with CVSS threshold, EPSS threshold, and VEX trust gates; verify compiled bundle is valid
- [ ] Evaluate a finding against compiled policy; verify verdict includes gate decisions from all applicable gates
- [ ] Evaluate with VEX trust gate; verify per-environment threshold enforcement (production stricter than development)
- [ ] Evaluate with determinism guard enabled; verify GuardedPolicyEvaluator wraps evaluation and reports no violations
- [ ] Submit policy YAML with wall-clock usage; verify ProhibitedPatternAnalyzer detects violation
- [ ] Evaluate finding with evidence-weighted scoring; verify proof-aware score includes evidence references
- [ ] Evaluate finding with ClaimScoreMerger; verify conflicting claims are penalized and winning claim selected
- [ ] Use counterfactual engine on blocked finding; verify paths to pass are returned
- [ ] POST policy lint endpoint with invalid YAML; verify lint errors returned
- [ ] Compile and evaluate same policy+finding twice; verify deterministic verdict (identical results)