# Graph Edge Metadata with Reason/Evidence/Provenance

## Module
Graph

## Status
VERIFIED

## Description
EdgeReason and CallgraphEdge models exist in Signals with persistence projection, and EdgeBundle exists in Scanner reachability. The Graph module (`src/Graph`) implements edge metadata types including `EdgeReason`, `EdgeVia`, and `ExplanationPayload` in `src/Graph/StellaOps.Graph.Api/Contracts/EdgeMetadataContracts.cs` (423 lines), along with the `EdgeMetadataService` for querying, storing, and inferring edge-level metadata.

## What's Implemented
- **Graph API services**: `src/Graph/StellaOps.Graph.Api/Services/` -- query, search, path, diff, export, lineage, overlay services (all with in-memory implementations)
- **Edge metadata contracts**: `src/Graph/StellaOps.Graph.Api/Contracts/EdgeMetadataContracts.cs` -- `EdgeReason`, `EdgeVia`, `ExplanationPayload`, `EdgeMetadataResponse` types (423 lines)
- **Edge metadata service**: `src/Graph/StellaOps.Graph.Api/Services/EdgeMetadataService.cs` -- query, set, and infer edge metadata with tenant isolation
- **Graph snapshot documents**: `src/Graph/StellaOps.Graph.Indexer/Documents/GraphSnapshot.cs`, `GraphSnapshotBuilder.cs` -- graph document model (nodes/edges with metadata)
- **Graph document factory**: `src/Graph/StellaOps.Graph.Indexer/Schema/GraphDocumentFactory.cs` -- creates graph documents with identity
- **Graph identity**: `src/Graph/StellaOps.Graph.Indexer/Schema/GraphIdentity.cs` -- content-addressed graph identity
- **CVE observation nodes**: `src/Graph/__Libraries/StellaOps.Graph.Core/CveObservationNode.cs` -- CVE observation data on graph nodes
- **Advisory linkset**: `src/Graph/StellaOps.Graph.Indexer/Ingestion/Advisory/AdvisoryLinksetProcessor.cs`, `AdvisoryLinksetTransformer.cs` -- advisory evidence linking to graph edges
- **Inspector**: `src/Graph/StellaOps.Graph.Indexer/Ingestion/Inspector/GraphInspectorProcessor.cs`, `GraphInspectorTransformer.cs` -- inspection evidence on edges
- **Postgres persistence**: `src/Graph/__Libraries/StellaOps.Graph.Indexer.Persistence/Postgres/Repositories/PostgresGraphDocumentWriter.cs`, `PostgresGraphSnapshotProvider.cs`
- **Tests**: `src/Graph/__Tests/StellaOps.Graph.Api.Tests/EdgeMetadataServiceTests.cs` -- 14 tests covering roundtrip, tenant isolation, reason inference, overwrite semantics
- Source: Feature matrix scan

## Implementation Plan
- All planned types (`EdgeReason`, `EdgeVia`, `ExplanationPayload`) verified to exist in `EdgeMetadataContracts.cs`
- Edge metadata is exposed through the `EdgeMetadataService` with full CRUD and inference
- Tenant isolation confirmed working
- Further integration with Signals `EdgeReason` and Scanner `EdgeBundle` models may be expanded in future sprints

## Related Documentation
- Source: See feature catalog

## Verification
- **Run ID**: run-002
- **Date**: 2026-02-09T21:43:00Z
- **Tier**: 1 (Source + Build + Test)
- **Result**: PASS
- **Evidence**: 52/52 Graph.Api.Tests pass (including 14/14 EdgeMetadataServiceTests). 108/108 non-persistence tests pass across all Graph test projects. 17 Persistence tests skipped (require Docker/PostgreSQL -- environment limitation, not a regression).
- **Notes**: Required 1 retry cycle. Initial failure due to test fixture edge IDs not matching seeded data. Fixed in run-002 by aligning test edge IDs to seeded graph edges and correcting InferReasonFromKind assertion expectations. Original "What's Missing" claim about absent types was disproven -- all types exist in EdgeMetadataContracts.cs (423 lines).

### Tier 2 Recheck (API Behavior)
- **Run ID**: run-003
- **Date**: 2026-02-10T11:35:00Z
- **Tier**: 2 (End-to-end API verification)
- **Result**: PASS
- **Evidence**: Added endpoint-level auth/scope/tenant regression tests (`EdgeMetadataEndpointsAuthorizationTests`) and revalidated live API behavior. Tier 2 artifact: `docs/qa/feature-checks/runs/graph/graph-edge-metadata-with-reason-evidence-provenance/run-003/tier2-api-check.json`.

### Tier 2 Recheck (Positive Path)
- **Run ID**: run-004
- **Date**: 2026-02-10T11:47:30Z
- **Tier**: 2 (End-to-end API verification)
- **Result**: PASS
- **Evidence**: Verified known edge metadata retrieval returns `200` with explanation payload for authenticated read scope. Artifact: `docs/qa/feature-checks/runs/graph/graph-edge-metadata-with-reason-evidence-provenance/run-004/tier2-api-check.json`.

## Recheck (Run-005)
- **Verified**: 2026-02-10
- **Method**: Tier 2a API replay validated via Graph.Api integration suite.
- **Tests**: PASS (`src/Graph/__Tests/StellaOps.Graph.Api.Tests`: 66/66).
- **Tier 2 Evidence**: `docs/qa/feature-checks/runs/graph/graph-edge-metadata-with-reason-evidence-provenance/run-005/tier2-api-check.json`
- **Outcome**: Edge metadata endpoint behavior remains healthy with auth/tenant guard coverage intact.

## Recheck (Run-006)
- **Verified**: 2026-02-10
- **Method**: Tier 2 replay validated via Graph API/indexer suites.
- **Tests**: PASS (src/Graph/__Tests/StellaOps.Graph.Api.Tests: 66/66; src/Graph/__Tests/StellaOps.Graph.Indexer.Tests: 37/37; src/Graph/__Tests/StellaOps.Graph.Indexer.Persistence.Tests: 17/17).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/graph/graph-edge-metadata-with-reason-evidence-provenance/run-006/tier2-api-check.json
- **Outcome**: Edge metadata API behavior remains healthy with tenant/auth/scope coverage intact.

## Recheck (Run-007)
- **Verified**: 2026-02-10
- **Method**: Tier 2 replay validated via Graph API/indexer suites.
- **Tests**: PASS (src/Graph/__Tests/StellaOps.Graph.Api.Tests: 66/66; src/Graph/__Tests/StellaOps.Graph.Indexer.Tests: 37/37; src/Graph/__Tests/StellaOps.Graph.Indexer.Persistence.Tests: 17/17).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/graph/graph-edge-metadata-with-reason-evidence-provenance/run-007/tier2-api-check.json
- **Outcome**: Edge metadata API behavior remains healthy with tenant/auth/scope coverage intact.

## Recheck (Run-008)
- **Verified**: 2026-02-10
- **Method**: Tier 2 replay validated via Graph API/indexer suites.
- **Tests**: PASS (src/Graph/__Tests/StellaOps.Graph.Api.Tests: 66/66; src/Graph/__Tests/StellaOps.Graph.Indexer.Tests: 37/37; src/Graph/__Tests/StellaOps.Graph.Indexer.Persistence.Tests: 17/17).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/graph/graph-edge-metadata-with-reason-evidence-provenance/run-008/tier2-api-check.json
- **Outcome**: Edge metadata API behavior remains healthy with tenant/auth/scope coverage intact.

## Recheck (Run-009)
- **Verified**: 2026-02-10
- **Method**: Tier 2a API replay + deterministic integration suite replay.
- **Tests**: PASS (Graph.Api.Tests 66/66, Graph.Indexer.Tests 37/37, Graph.Indexer.Persistence.Tests 17/17).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/graph/graph-edge-metadata-with-reason-evidence-provenance/run-009/tier2-api-check.json
- **Outcome**: Checked Graph behavior remains healthy in continued replay.


## Recheck (Run-010)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic integration replay.
- **Tests**: PASS (Graph Api 66/66, Indexer 37/37, Indexer.Persistence 17/17; total 120/120).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/graph/graph-edge-metadata-with-reason-evidence-provenance/run-010/tier2-integration-check.json
- **Outcome**: Checked graph behavior remains healthy in continued replay.
## Recheck (Run-011)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic integration replay.
- **Tests**: PASS (Graph Api 66/66, Indexer 37/37, Indexer.Persistence 17/17; total 120/120).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/graph/graph-edge-metadata-with-reason-evidence-provenance/run-011/tier2-integration-check.json
- **Outcome**: Checked graph behavior remains healthy in continued replay.
## Recheck (Run-012)
- **Verified**: 2026-02-10
- **Method**: Tier 2 replay + deterministic Graph suite replay.
- **Tests**: PASS (Graph.Api 66/66, Graph.Indexer 37/37, Graph.Indexer.Persistence 17/17; total 120/120).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/graph/graph-edge-metadata-with-reason-evidence-provenance/run-012/tier2-api-check.json
- **Outcome**: Checked graph behavior remains healthy in continued replay.

## Recheck (Run-013)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic integration replay with fresh command-output evidence.
- **Tests**: PASS (Graph matrix 120/120: Api 66, Indexer 37, Indexer.Persistence 17.)
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/graph/graph-edge-metadata-with-reason-evidence-provenance/run-013/tier2-integration-check.json
- **Outcome**: Checked Graph behavior remains healthy in continued replay.

## Recheck (Run-016)
- **Verified**: 2026-02-11
- **Method**: Strict Tier 2 API replay for edge metadata routes (known edge, unknown edge, by-reason, auth/scope guards).
- **Tests**: PASS (`src/Graph/StellaOps.Graph.sln`: 120/120).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/graph/graph-edge-metadata-with-reason-evidence-provenance/run-016/tier2-api-check.json
- **Outcome**: Fresh live evidence confirms explanation payloads plus 404/401/403 guard behavior at the API boundary.