# Graph Edge Metadata with Reason/Evidence/Provenance

## Module
Graph

## Status
IMPLEMENTED

## Description
EdgeReason and CallgraphEdge models exist in Signals with persistence projection, and EdgeBundle exists in Scanner reachability. However, the Graph module itself (src/Graph) does not contain EdgeReason/EdgeVia/ExplanationPayload types -- the human-readable explanation layer described in the advisory is not present in the Graph API.

## 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)
- **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`
- Source: Feature matrix scan

## What's Missing
- `EdgeReason`/`EdgeVia`/`ExplanationPayload` types in Graph API -- human-readable explanation layer for why edges exist
- Edge provenance metadata linking back to source evidence (SBOM provenance, scan evidence, attestation references)
- Graph API endpoints to query edge-level metadata (reason, evidence, provenance)

## Implementation Plan
- Add `EdgeReason`, `EdgeVia`, and `ExplanationPayload` types to `src/Graph/StellaOps.Graph.Api/`
- Expose edge metadata through graph query and path APIs
- Link edge metadata to Signals `EdgeReason` and Scanner `EdgeBundle` models
- Add tests for edge metadata query and provenance tracking

## Related Documentation
- Source: See feature catalog