# Canonical Node-Hash and Path-Hash Recipes for Reachability

## Module
Scanner

## Status
VERIFIED

## Description
Canonical node-hash (PURL/symbol normalization + SHA-256) and path-hash (top-K selection + PathFingerprint) recipes for deterministic static/runtime evidence joins. Extended PathWitness, RichGraph, SARIF export with hash fields.

## Implementation Details
- **Path Witness with Hash Fields**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/PathWitness.cs` - `PathWitness` model with node-hash and path-hash fields
  - `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/PathWitnessBuilder.cs` - `PathWitnessBuilder` computes canonical hashes during witness construction
  - `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/IPathWitnessBuilder.cs` - Interface
- **Rich Graph Integration**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/RichGraph.cs` - RichGraph model extended with hash fields on nodes
  - `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Ordering/DeterministicGraphOrderer.cs` - Deterministic ordering for canonical hash computation
- **Witness Matching & Verification**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/WitnessMatcher.cs` - Matches witnesses using canonical hashes for deterministic joins
  - `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/WitnessSchema.cs` - Schema validation for witness hash fields
- **Slice Integration**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/SliceExtractor.cs` - Slice extraction with path-hash for top-K selection
  - `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/SliceModels.cs` - Slice models with hash fields
- **Subgraph Extraction**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Subgraph/ReachabilitySubgraphModels.cs` - Subgraph models with hash fields

## E2E Test Plan
- [ ] Scan an image and verify PathWitness results include canonical node-hash fields (SHA-256 of normalized PURL/symbol)
- [ ] Verify path-hash is computed using top-K selection and PathFingerprint algorithm
- [ ] Run the same scan twice and verify node-hash and path-hash values are deterministically identical
- [ ] Verify RichGraph response includes hash fields on nodes via `GET /api/v1/scans/{scanId}/reachability`
- [ ] Verify static/runtime evidence join works correctly using canonical hashes as join keys
- [ ] Verify SARIF export includes hash fields in reachability-related results

---

## Verification

| Check | Result |
|-------|--------|
| Tier 0 - Source files exist | PASS |
| Tier 1 - Build + code review | PASS |
| Tier 2 - Integration tests | PASS |
| Verified | 2026-02-13T18:10:00Z |