docs consolidation

docs/reproducibility.md

@@ -17,19 +17,64 @@ StellaOps provides **deterministic, reproducible outputs** for all security arti
 
 ### Content-Addressed Verdict ID
 
-All verdicts use content-addressed identifiers computed as:
+All policy verdicts use content-addressed identifiers computed as:
 
 ```
-VerdictId = SHA256(Canonicalize(VerdictPayload))
+VerdictId = "verdict:sha256:" + HexLower(SHA256(CanonicalJson(VerdictPayload)))
 ```
 
-Where `VerdictPayload` includes:
-- **Delta ID**: Content hash of the security delta
-- **Blocking Drivers**: Sorted list of risk-increasing factors
-- **Warning Drivers**: Sorted list of advisory factors
-- **Applied Exceptions**: Sorted list of exception IDs covering findings
-- **Gate Level**: Recommended gate (G0-G4)
-- **Input Stamps**: Hashes of all inputs (see below)
+Where `VerdictPayload` is a JSON object with the following structure:
+
+```json
+{
+  "_canonVersion": "stella:canon:v1",
+  "deltaId": "<content-addressed delta ID>",
+  "blockingDrivers": [
+    {
+      "cveId": "CVE-...",
+      "description": "...",
+      "purl": "pkg:...",
+      "severity": "Critical|High|Medium|Low",
+      "type": "new-reachable-cve|..."
+    }
+  ],
+  "warningDrivers": [...],
+  "appliedExceptions": ["EXCEPTION-001", ...],
+  "gateLevel": "G0|G1|G2|G3|G4"
+}
+```
+
+**Determinism guarantees:**
+- `blockingDrivers` and `warningDrivers` are sorted by `type`, then `cveId`, then `purl`, then `severity`
+- `appliedExceptions` are sorted lexicographically
+- All string comparisons use Ordinal (case-sensitive, lexicographic)
+- Canonical JSON follows RFC 8785 (JCS) with keys sorted alphabetically
+- The `_canonVersion` field ensures hash stability across algorithm evolution
+
+### VerdictIdGenerator Implementation
+
+The `VerdictIdGenerator` class in `StellaOps.Policy.Deltas` computes deterministic verdict IDs:
+
+```csharp
+// Create a verdict with content-addressed ID
+var verdict = new DeltaVerdictBuilder()
+    .AddBlockingDriver(new DeltaDriver
+    {
+        Type = "new-reachable-cve",
+        CveId = "CVE-2024-001",
+        Severity = DeltaDriverSeverity.Critical,
+        Description = "Critical CVE is now reachable"
+    })
+    .Build("delta:sha256:abc123...");
+
+// VerdictId is deterministic:
+// verdict.VerdictId == "verdict:sha256:..."
+
+// Recompute for verification:
+var generator = new VerdictIdGenerator();
+var recomputed = generator.ComputeVerdictId(verdict);
+Debug.Assert(recomputed == verdict.VerdictId);
+```
 
 ### Input Stamps