graph.inspect.v1 · Inspector Contract (2025-12-04)

Replaces the archived Cartographer handshake note and grounds the Concelier/Excititor → Graph Indexer/API interface. Use this shape for any inspector payloads that carry SBOM relationships plus advisory/VEX linkouts destined for graph ingestion or replay.

Purpose

• Give Concelier (Link-Not-Merge v1) and Excititor a frozen, deterministic payload so graph nodes/edges can be regenerated or replayed offline.
• Encode the evidence hashes and provenance needed for append-only rebuilds and audit trails.
• Keep ordering stable to avoid hash churn between runs.

Payload shape (summary)

• schemaVersion — must be graph.inspect.v1.
• tenant, artifactDigest, sbomDigest, collectedAt.
• components[] (ordered):
  • purl, optional version, optional sorted scopes[].
  • relationships[] → contains|depends_on|provides|runtime_observed with targetPurl, scope?, source, evidenceHash.
  • advisories[] → advisoryId, source, status, severity?, cvss?, justification?, linksetDigest?, evidenceHash, modifiedAt.
  • vexStatements[] → statementId, source, status, justification, impactStatement?, knownExploited?, issuedAt, expiresAt?, evidenceHash.
  • provenance → source, collectedAt, eventOffset?, linksetDigest?, evidenceHash?.
• Optional links.sbomObservationEventId and links.linksetDigest for traceability.

Full machine-readable schema: docs/modules/graph/contracts/graph.inspect.v1.schema.json.

Determinism rules

• Preserve input order for components[] and relationships[]; sort scopes, advisories, and vexStatements by (source, advisoryId/statementId) before emitting.
• All timestamps UTC ISO-8601; hashes are SHA-256 hex.
• Keep arrays unique where noted (scopes), and avoid null/empty strings.

Graph mapping

• relationships → graph edges: contains/depends_on/provides/runtime_observed align with CONTAINS, DEPENDS_ON, PROVIDES, OBSERVED_RUNTIME.
• advisories → advisory nodes + AFFECTED_BY edges (use linksetDigest and evidenceHash for provenance).
• vexStatements → vex_statement nodes + VEX_EXEMPTS edges (propagate justification, knownExploited, impactStatement).
• provenance fields flow into graph provenance objects and eventOffset becomes the replay cursor.

Validation

# Example (offline-friendly if ajv is already installed locally)
ajv validate -s docs/modules/graph/contracts/graph.inspect.v1.schema.json \
             -d docs/modules/graph/contracts/examples/graph.inspect.v1.sample.json

Use any JSON Schema Draft 2020-12 validator if ajv is unavailable.

Sample

See docs/modules/graph/contracts/examples/graph.inspect.v1.sample.json for a one-component payload that exercises relationships, advisory observations, VEX statements, and provenance fields.

Upstream alignment

• Link-Not-Merge fixtures: docs/modules/concelier/link-not-merge-schema.md.
• Excititor overlay prep: docs/modules/excititor/prep/2025-11-20-graph-21-001-prep.md and ...graph-21-002-prep.md.
• Graph canonical model: docs/modules/graph/schema.md (node/edge taxonomy the inspector feeds).