git.stella-ops.org/docs/modules/ui/reachability-witnessing/README.md

# Reachability Witnessing

**Status:** Implemented
**Owner shell:** `Security > Reachability`
**Canonical routes:** `/security/reachability/coverage`, `/security/reachability/witnesses`, `/security/reachability/witnesses/:witnessId`, `/security/reachability/poe`, `/security/reachability/poe/:artifactId`, `/security/reachability/gaps`

## Recommendation

Restore witness and proof-of-exposure UX as a deeper part of `Security > Reachability`, not as a standalone product.

- Canonical mount: `/security/reachability`
- Suggested user-facing title: `Reachability`
- Supporting label inside the shell: `Witnesses & Proof`

This capability should strengthen security investigation, release gating, and evidence review through reusable witness detail pages and proof drawers.

## Why This Is The Right Shape

- `ReachabilityCenterComponent` already owns the top-level reachability posture.
- `WitnessPageComponent` and `PoEDrawerComponent` are evidence and explanation layers of the same capability.
- Reachability proof matters in findings, triage, policy/VEX decisions, and release gates, so it must be reusable from multiple contexts.
- A single shell prevents proof UX from fragmenting across security, evidence, and release flows.

## Operator Modes

### 1. Coverage Review Mode
- Used by security operators checking graph coverage, sensor freshness, and fleet posture.
- Focus: `Coverage` and `Sensor Gaps`.

### 2. Investigation Mode
- Used by analysts validating whether a vulnerable path is reachable and why.
- Focus: `Witnesses` and `PoE / Exposure`.

### 3. Release Context Mode
- Entered from release gates, policy/VEX decisions, or evidence review.
- Focus: witness explanation, proof verification, and return-to-release navigation.

## Recommended IA

### Primary tabs
- `Coverage`
  - fleet and package coverage, recent graph updates, confidence overview
- `Witnesses`
  - searchable witness list and full witness detail page
- `PoE / Exposure`
  - proof-of-exposure artifacts, export, verify, transparency status
- `Sensor Gaps`
  - missing sensors, stale data, unresolved evidence dependencies

### Witness detail sections
- summary
- call path and gates
- confidence and caveats
- related findings and releases
- evidence chain and export actions

## Page Anatomy

### Coverage tab
- summary cards:
  - analyzed artifacts
  - coverage confidence
  - stale witness count
  - open gaps
- tables or cards:
  - per-environment coverage
  - hot CVEs lacking proof

### Witnesses tab
- list filters:
  - artifact
  - package
  - CVE
  - verdict
  - confidence
  - environment
- row preview:
  - witness id
  - subject
  - vulnerability
  - verdict
  - confidence
  - last observed
- witness detail page:
  - proof summary header
  - path explorer
  - gates and confidence
  - related evidence
  - replay/verify/export actions

### PoE / Exposure tab
- proof list with status chips
- right drawer for proof detail by default
- optional permalink route for export and audit deep links

### Sensor Gaps tab
- backlog queues for:
  - missing runtime signals
  - stale graph facts
  - unresolved symbol sources
  - missing environment bindings

## Route Contract

Keep one canonical route family under security reachability.

### Canonical routes
- `/security/reachability`
- `/security/reachability/coverage`
- `/security/reachability/witnesses`
- `/security/reachability/witnesses/:witnessId`
- `/security/reachability/poe`
- `/security/reachability/poe/:artifactId`
- `/security/reachability/gaps`

### Query-param state
- `tab=coverage|witnesses|poe|gaps`
- `panel=poe|evidence|related`
- `returnTo=<encoded route>` for findings, triage, evidence, or releases

### Alias rules
- any future `evidence` or `release` entry points should deep-link here rather than mount duplicate witness pages

## What To Merge

### Merge into `Coverage`
- `ReachabilityCenterComponent`

### Merge into `Witnesses`
- `WitnessPageComponent`

### Merge into `PoE / Exposure`
- `PoEDrawerComponent`

### Preserve as shared behaviors
- export DOT and Mermaid actions
- proof verification actions
- evidence-chain cards

## Single Actions And Supporting Surfaces

### Witness detail
- full page under `Witnesses`
- preserve permalink and return-to-context behavior

### PoE detail
- default to a right drawer from witness detail, finding detail, triage, or release context
- allow a standalone route for exports and audit deep links

### Export or replay verify
- keep as actions on witness or PoE detail
- do not create separate pages per export type

### Related finding navigation
- keep as contextual links in the witness detail sidebar

## Cross-Product Entry Points

- `Security > Findings`
  - open witness detail for a finding
- `Triage > Artifact Workspace`
  - open witness or PoE from artifact detail
- `Evidence > Verify & Replay`
  - open proof verification in the same witness/PoE model
- `Decisioning Studio` or `Releases`
  - open witness and proof for gate verdict explanation

## Shipped Behavior

### Mounted shell
- `Coverage` remains the default entry and keeps the fleet posture summary.
- `Witnesses` ships a searchable, filterable list with confidence and verdict filters.
- `PoE / Exposure` keeps drawer-first inspection and supports direct permalink routes for export and audit use.
- `Sensor Gaps` stays inside the same shell rather than fragmenting into a separate product.

### Witness detail
- Loads the requested witness from the witness API when available.
- Falls back to deterministic reachability fixtures when the backend is unavailable.
- Ships call-path, gate, caveat, evidence-chain, runtime-observation, and related-context sections.
- Supports verify, JSON export, DOT export, Mermaid export, and PoE drill-in actions.

### Proof-of-exposure detail
- Opens by default as a contextual drawer from witness or shell entry points.
- Supports direct navigation through `/security/reachability/poe/:artifactId`.
- Preserves operator context with `returnTo` when launched from findings, triage, evidence replay, or release detail.

### Cross-product handoffs
- `Security > Findings` links into canonical witness routes instead of owning a second proof view.
- `Triage > Artifact Workspace` restores the selected finding and tab when returning from reachability.
- `Evidence > Verify & Replay` links the current request into reachability proof review.
- `Releases > Detail` links release-gate investigation into reachability without branching to a parallel shell.

## UI Standards For Implementation

- Keep witness detail as the canonical deep-link target.
- Default proof detail to a drawer to preserve investigation context.
- Preserve return-to-context links so operators can move back to findings or release flows.
- Reuse evidence cards and path visualizations across security, evidence, and release entry points.
- Keep graph and proof loading deterministic and evidence-first.

## Verification Status

- Angular verification: targeted route, witness-detail, handoff, and release-context tests passed on 2026-03-07.
- Playwright verification: witness detail, PoE drawer/permalink, and Verify & Replay handoff passed on 2026-03-07.
- Checked feature note: `docs/features/checked/web/reachability-witnessing-ui.md`

## Non-Goals

- Do not create a top-level `Witnessing` product.
- Do not split coverage, witness, and proof UX across unrelated sidebar branches.
- Do not leave PoE as a drawer with no canonical parent route.

## Source Inputs

- `docs/contracts/witness-v1.md`
- `docs/architecture/EVIDENCE_PIPELINE_ARCHITECTURE.md`
- `docs/modules/scanner/reachability.md`
- `docs/modules/ui/architecture-rework.md`
- `src/Web/StellaOps.Web/src/app/features/reachability/reachability-center.component.ts`
- `src/Web/StellaOps.Web/src/app/features/reachability/witness-page.component.ts`
- `src/Web/StellaOps.Web/src/app/features/reachability/poe-drawer.component.ts`
- `src/Web/StellaOps.Web/src/app/routes/security-risk.routes.ts`
- `src/Web/StellaOps.Web/src/app/routes/evidence.routes.ts`