up

docs/api/policy.md

@@ -237,11 +237,83 @@ Slim wrapper used by CLI; returns 204 on success or `ERR_POL_001` payload.
 Policy Engine evaluations may be enriched with reachability facts produced by Signals. These facts are expected to be:
 
 - **Deterministic:** referenced by `metadata.fact.digest` (sha256) and versioned via `metadata.fact.version`.
-- **Evidence-linked:** per-target states include `path[]` and `evidence.runtimeHits[]` (and any future CAS/DSSE pointers).
+- **Evidence-linked:** per-target states include `path[]`, `evidence.static.graphHash`, `evidence.runtime.hitCount`, and CAS/DSSE pointers.
+
+#### 6.0.1 Core Identifiers
+
+| Identifier | Format | Description |
+|------------|--------|-------------|
+| `symbol_id` | `sym:{lang}:{base64url}` | Canonical function identity (SHA-256 of tuple) |
+| `code_id` | `code:{lang}:{base64url}` | Identity for stripped/name-less code blocks |
+| `graph_hash` | `blake3:{hex}` | Content-addressable graph identity |
+| `fact.digest` | `sha256:{hex}` | Canonical reachability fact digest |
+
+#### 6.0.2 Lattice States
+
+Policy gates operate on the 8-state reachability lattice:
+
+| State | Code | Policy Treatment |
+|-------|------|------------------|
+| `Unknown` | `U` | Block `not_affected`, allow `under_investigation` |
+| `StaticallyReachable` | `SR` | Allow `affected`, block `not_affected` |
+| `StaticallyUnreachable` | `SU` | Low-confidence `not_affected` allowed |
+| `RuntimeObserved` | `RO` | `affected` required |
+| `RuntimeUnobserved` | `RU` | Medium-confidence `not_affected` allowed |
+| `ConfirmedReachable` | `CR` | `affected` required, `not_affected` blocked |
+| `ConfirmedUnreachable` | `CU` | `not_affected` allowed |
+| `Contested` | `X` | `under_investigation` required |
+
+#### 6.0.3 Evidence Block Schema
+
+When Policy findings include reachability evidence, the following structure is used:
+
+```json
+{
+  "reachability": {
+    "state": "CR",
+    "confidence": 0.92,
+    "evidence": {
+      "graph_hash": "blake3:a1b2c3d4e5f6...",
+      "graph_cas_uri": "cas://reachability/graphs/a1b2c3d4e5f6...",
+      "dsse_uri": "cas://reachability/graphs/a1b2c3d4e5f6....dsse",
+      "path": [
+        {"symbol_id": "sym:java:...", "code_id": "code:java:...", "display": "main()"},
+        {"symbol_id": "sym:java:...", "code_id": "code:java:...", "display": "Logger.error()"}
+      ],
+      "path_length": 2,
+      "runtime_hits": 47,
+      "fact_digest": "sha256:abc123...",
+      "fact_version": 3
+    }
+  }
+}
+```
+
+#### 6.0.4 Policy Rule Example
+
+```rego
+# Allow not_affected only for confirmed unreachable with high confidence
+allow_not_affected {
+  input.reachability.state == "CU"
+  input.reachability.confidence >= 0.85
+  input.reachability.evidence.fact_digest != ""
+}
+
+# Require affected for confirmed reachable
+require_affected {
+  input.reachability.state == "CR"
+}
+
+# Contested states require investigation
+require_investigation {
+  input.reachability.state == "X"
+}
+```
 
 Signals contract & scoring model:
 - `docs/api/signals/reachability-contract.md`
 - `docs/reachability/lattice.md`
+- `docs/reachability/function-level-evidence.md`
 
 ### 6.1 Trigger Run