# Reachability Evidence – Gap Analysis & Task References

_Last updated: 2025-11-09 (Business Analysis role)._  
_Scope:_ outline the missing functionality required to make binary-level reachability evidence first-class across Scanner, Signals, Policy, Replay, and VEX emission.

## 1. Source Materials

| Area | Reference |
|------|-----------|
| Architecture vision | `docs/reachability/DELIVERY_GUIDE.md`, `docs/modules/platform/architecture-overview.md:145` |
| Active sprints | `docs/implplan/SPRINT_400_runtime_facts_static_callgraph_union.md`, `docs/implplan/SPRINT_401_reachability_evidence_chain.md` |
| Current implementations | `src/Signals/StellaOps.Signals/Program.cs:214-287`, `src/Signals/StellaOps.Signals/Services/CallgraphIngestionService.cs`, `src/Signals/StellaOps.Signals/Services/ReachabilityScoringService.cs`, `src/Scanner/__Libraries/StellaOps.Scanner.Reachability`, `tests/reachability/*` |

Use this document to break down outstanding work into actionable tasks and to keep documentation links synchronized.

## 2. Current Snapshot (11 Nov 2025)

1. **Callgraph ingestion exists** – Signals exposes `/signals/callgraphs` and stores graphs + CAS metadata (`Program.cs`, `CallgraphIngestionService`).
2. **Reachability recompute API exists but is simplistic** – BFS scoring with static confidences, no lattice states, no CAS evidence linking.
3. **Runtime ingestion is a stub** – `/signals/runtime-facts` returns HTTP 501.
4. **Scanner Worker doesn’t emit canonical SymbolIDs/graphs** – `StellaOps.Scanner.Reachability` library exists, yet Worker binaries do not reference it.
5. **Replay manifests record reachability via helpers** – `ReachabilityReplayWriter` can add graph/trace refs, but manifests don’t enforce CAS registration/hashing.
6. **Policy/UI still consume coarse `reachability:*` tags** – no OpenVEX evidence blocks or graph hashes attached to statements/events.

## 3. Gap Breakdown & Tasks

Canonical sprint tracking for these tasks now lives in `docs/implplan/SPRINT_400_runtime_facts_static_callgraph_union.md` and `docs/implplan/SPRINT_401_reachability_evidence_chain.md`. Use the table below as a consolidated reference when planning cross-guild work.

| Task ID | Module / Doc anchor | Description | Dependencies | Deliverables |
|---------|--------------------|-------------|--------------|--------------|
| GAP-SCAN-001 | `src/Scanner/StellaOps.Scanner.Worker`, `docs/modules/scanner/architecture.md` | Implement binary/language Symbolizers that emit `richgraph-v1` payloads with canonical `SymbolID = {file:hash, section, addr, name, linkage}`. Persist graphs to CAS and register them via `ReachabilityGraphBuilder`. | Sprint 400 `SCAN-REACH-201-002` | Analyzer services + config docs updated, sample graph fixtures, regression tests under `tests/reachability/StellaOps.ScannerSignals.IntegrationTests`. |
| GAP-ZAS-002 | `src/Zastava/StellaOps.Zastava.Observer`, `docs/modules/zastava/architecture.md` | Stream runtime NDJSON batches with `SymbolID`, hit counts, CAS URIs to `/signals/runtime-facts`. Capture build-ids + entrypoint context per sprint spec. | Sprint 400 `ZASTAVA-REACH-201-001` | Observer implementation, operator runbook `docs/runbooks/reachability-runtime.md`, fixture updates. |
| GAP-SIG-003 | `src/Signals/StellaOps.Signals/Program.cs`, `ReachabilityScoringService.cs`, `docs/reachability/DELIVERY_GUIDE.md#5.2` | Finish `/signals/runtime-facts`, introduce CAS-backed runtime storage, extend scoring to lattice states (`Unknown/NotPresent/Unreachable/Conditional/Reachable/Observed`) with per-path confidence accumulation. Emit `signals.fact.updated` events. | Sprint 401 `SIGNALS-RUNTIME-401-002`, `SIGNALS-SCORING-401-003` | API schema, Mongo indices, deterministic scoring tests (`tests/reachability/StellaOps.Signals.Reachability.Tests`). |
| GAP-REP-004 | `src/__Libraries/StellaOps.Replay.Core`, `docs/replay/DETERMINISTIC_REPLAY.md` | Enforce CAS registration + BLAKE3 hashing for graphs/traces before manifest writes. Upgrade manifest schema v2 to include analyzer versions + policy thresholds. | Sprint 400 `REPLAY-REACH-201-005`, Sprint 401 `REPLAY-401-004` | Updated schema docs, fixture pack coverage (`tests/reachability/StellaOps.Replay.Core.Tests`). |
| GAP-POL-005 | `src/Policy/StellaOps.Policy.Engine`, `docs/modules/policy/architecture.md` | Ingest Signals reachability facts, expose `reachability.state/confidence` in SPL, and generate OpenVEX evidence blocks referencing graph hashes + runtime facts. Implement policy threshold (e.g., affected if `max_path_conf ≥ 0.6`). | Sprint 401 `POLICY-VEX-401-006` | Updated policy schemas (`policy-scoring-schema@1.json`), OpenVEX templates, backend tests.
| GAP-VEX-006 | `docs/modules/excititor/architecture.md`, `docs/modules/ui/architecture.md`, `docs/implplan/SPRINT_401_reachability_evidence_chain.md` | Wire VEX emission/UI surfaces: CLI/UI explain drawer with call-path visualization, DSSE evidence attachments, `--threshold` and `--evidence=graph` flags. | Sprint 401 `UI-CLI-401-007` | CLI documentation, UI walkthrough, Notify templates referencing reachability evidence. |

## 4. Documentation Actions

1. **Module dossiers** – Once each GAP task lands, update the matching module architecture doc to reflect binary reachability specifics (symbol schema, APIs, thresholds).
2. **Runbooks** – Create `docs/runbooks/reachability-runtime.md` for operators (Zastava deployment, retention, troubleshooting) and extend `docs/runbooks/replay_ops.md` with reachability CAS sections.
3. **API references** – Add `/signals/runtime-facts` and explain reachability fields to `docs/09_API_CLI_REFERENCE.md` and `docs/api/policy.md`.
4. **Sample payloads** – Under `samples/`, add OpenVEX examples that include `facts.type = stella.reachability` with `graph_hash`, entrypoints, and analyzer versions.

## 5. Next Steps for Business Analysis

- Socialize this gap list with module owners; confirm task ownership aligns with the sprint trackers.
- Link this document from `docs/reachability/DELIVERY_GUIDE.md` so engineers can reference the gap tasks quickly.
- Revisit after Sprint 401 midpoint to mark completed tasks and add any newly discovered blockers.