Excititor · Graph Linkouts & Overlays — Implementation Notes

Audience: Excititor Core engineers wiring the graph linkout, overlay, status, and tooltip-observation endpoints. Status: Implementation guidance — storage wiring pending. For the frozen contract these endpoints serve, see the Graph Overlay Contract.

• Date: 2025-11-21
• Scope: EXCITITOR-GRAPH-21-001, EXCITITOR-GRAPH-21-002, EXCITITOR-GRAPH-21-005, EXCITITOR-GRAPH-24-101, EXCITITOR-GRAPH-24-102

Endpoints

1. Linkouts (21-001)

   • POST /internal/graph/linkouts
   • Body: tenant, purls[] (max 500), includeJustifications?, includeProvenance?
   • Response: ordered by input purls; each item includes advisories[] (advisoryId, source, status, justification?, modifiedAt, evidenceHash, connectorId, dsseEnvelopeHash?) plus conflicts[]; notFound[].

2. Overlays (21-002)

   • GET /v1/graph/overlays?purl=<purl>&purl=<purl>&includeJustifications=true|false
   • Response per PURL: summary counts (open, not_affected, under_investigation, no_statement), latestModifiedAt, justifications[] (unique, sorted), provenance (sources[], lastEvidenceHash), cached, cacheAgeMs.

3. Status summaries (24-101)

   • GET /v1/graph/status?purl=<purl>&purl=<purl>
   • Response mirrors overlay summaries but omits justification payloads; includes sources[], lastEvidenceHash, cached, cacheAgeMs. Intended for Vuln Explorer status colouring.

4. Batch observations for tooltips (24-102)

   • GET /v1/graph/observations?purl=<purl>[&purl=...]&includeJustifications=true|false[&limitPerPurl=50][&cursor=<base64>]
   • Response per PURL: ordered observations[] (observationId, advisoryId, status, justification?, providerId, modifiedAt, evidenceHash, dsseEnvelopeHash?) plus truncated; top-level nextCursor, hasMore enable paging. Limits enforced per PURL and globally.

Storage & Indexes (21-005)

• vex_observations indexes:
  • { tenant: 1, component.purl: 1, advisoryId: 1, source: 1, modifiedAt: -1 }
  • Sparse { tenant: 1, component.purl: 1, status: 1 }
• Optional materialized vex_overlays cache: unique { tenant: 1, purl: 1 }, TTL on cachedAt driven by excititor:graph:overlayTtlSeconds (default 300s); payload must validate against vex_overlay.schema.json (schemaVersion 1.0.0). Bundle the sample payload vex-overlay-sample.json in Offline Kits.

Determinism

• Ordering: input PURL order → advisoryId → source for linkouts; overlays follow input order.
• Truncation: max 200 advisories per PURL; when truncated, include truncated: true and nextCursor (advisoryId, source).

Config knobs

• excititor:graph:overlayTtlSeconds (default 300)
• excititor:graph:maxPurls (default 500)
• excititor:graph:maxAdvisoriesPerPurl (default 200)
• excititor:graph:maxTooltipItemsPerPurl (default 50)
• excititor:graph:maxTooltipTotal (default 1000)

Telemetry

• Counter excititor.graph.linkouts.requests tags: tenant, includeJustifications, includeProvenance.
• Counter excititor.graph.overlays.cache tags: tenant, hit (true|false).
• Histogram excititor.graph.linkouts.latency.ms tags: tenant.

Steps to implement

• Bind GraphOptions to Excititor:Graph.
• Add endpoints to WebService with tenant guard; enforce limits.
• Implement overlay cache with deterministic sort; respect TTL; surface cached + cacheAgeMs.
• Backfill Mongo indexes above.
• Integration tests (WebApplicationFactory + Mongo2Go) for ordering, truncation, cache metadata, tenant isolation.