save progress

docs/24_OFFLINE_KIT.md

@@ -351,7 +351,98 @@ python ops/offline-kit/mirror_debug_store.py \
 The script mirrors the debug tree into the Offline Kit staging directory, verifies SHA-256 values against the manifest, and writes a summary under `metadata/debug-store.json` for audit logs. If the release pipeline does not populate `out/release/debug`, the tooling now logs a warning (`DEVOPS-REL-17-004`)—treat it as a build failure and re-run the release once symbol extraction is enabled.
 
 ---
+## 2.2 · Reachability & Proof Bundle Extensions
 
+The Offline Kit supports deterministic replay and reachability analysis in air-gapped environments through additional bundle types.
+
+### Reachability Bundle Format
+
+```
+/offline/reachability/<scan-id>/
+  ├── callgraph.json.zst         # Compressed call-graph (cg_node + cg_edge)
+  ├── manifest.json               # Scan manifest with frozen feed hashes
+  ├── manifest.dsse.json          # DSSE signature envelope
+  ├── entrypoints.json            # Discovered entry points
+  └── proofs/
+      ├── score_proof.cbor        # Canonical CBOR proof ledger
+      ├── score_proof.dsse.json   # DSSE signature for proof
+      └── reachability.json       # Reachability verdicts per finding
+```
+
+**Bundle contents:**
+
+| File | Purpose | Format |
+|------|---------|--------|
+| `callgraph.json.zst` | Static call-graph extracted from artifact | Zstd-compressed JSON |
+| `manifest.json` | Scan parameters + frozen Concelier/Excititor snapshot hashes | JSON |
+| `manifest.dsse.json` | DSSE envelope signing the manifest | JSON (in-toto DSSE) |
+| `entrypoints.json` | Discovered entry points (controllers, handlers, etc.) | JSON array |
+| `proofs/score_proof.cbor` | Deterministic proof ledger with Merkle root | CBOR (RFC 8949) |
+| `proofs/score_proof.dsse.json` | DSSE signature attesting to proof integrity | JSON (in-toto DSSE) |
+| `proofs/reachability.json` | Reachability status per CVE/finding | JSON |
+
+### Ground-Truth Corpus Bundle
+
+For validation and regression testing of reachability analysis:
+
+```
+/offline/corpus/ground-truth-v1.tar.zst
+  ├── corpus-manifest.json        # Corpus metadata and sample count
+  ├── dotnet/                     # .NET test cases (10 samples)
+  │   ├── sample-001/
+  │   │   ├── artifact.tar.gz     # Source/binary artifact
+  │   │   ├── expected.json       # Ground-truth reachability verdicts
+  │   │   └── callgraph.json      # Expected call-graph
+  │   └── ...
+  └── java/                       # Java test cases (10 samples)
+      ├── sample-001/
+      └── ...
+```
+
+**Corpus validation:**
+```bash
+stella scan validate-corpus --corpus /offline/corpus/ground-truth-v1.tar.zst
+```
+
+Expected output:
+- Precision ≥ 80% on all samples
+- Recall ≥ 80% on all samples  
+- 100% bit-identical replay when re-running with same manifest
+
+### Proof Replay in Air-Gap Mode
+
+To replay a scan with frozen feeds:
+
+```bash
+# Import the reachability bundle
+stella admin import-reachability-bundle /offline/reachability/<scan-id>/
+
+# Replay the score calculation
+stella score replay --scan <scan-id> --verify-proof
+
+# Expected: "Proof root hash matches: <hash>"
+```
+
+The replay command:
+1. Loads the frozen Concelier/Excititor snapshots from the manifest
+2. Re-executes scoring with the same inputs
+3. Computes a new proof root hash
+4. Verifies it matches the original (bit-identical determinism)
+
+### CLI Commands for Reachability
+
+```bash
+# Extract call-graph from artifact
+stella scan graph --lang dotnet --sln /path/to/solution.sln --output callgraph.json
+
+# Run reachability analysis
+stella scan reachability --callgraph callgraph.json --sbom sbom.json --output reachability.json
+
+# Package for offline transfer
+stella scan export-bundle --scan <scan-id> --output /offline/reachability/<scan-id>/
+```
+
+---
 ## 3 · Delta patch workflow
 
 1. **Connected site** fetches `stella-ouk-YYYY‑MM‑DD.delta.tgz`.