stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
d519782a8f0b30f425c9b6ae0f316b19259972a2
git.stella-ops.org/docs/modules/excititor/prep/2025-11-20-graph-21-001-prep.md
master d519782a8f
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
prep docs and service updates
2025-11-21 06:56:36 +00:00

1.5 KiB
Raw Blame History

Excititor · Graph Linkouts Prep (GRAPH-21-001)

  • Date: 2025-11-20
  • Scope: PREP-EXCITITOR-GRAPH-21-001-NEEDS-CARTOGRAPHE
  • Working directory: src/Excititor/__Libraries/StellaOps.Excititor.Core + src/Excititor/StellaOps.Excititor.WebService

Goal

Define the Cartographer-facing contract for batched VEX/advisory reference fetches by PURL to unblock inspector linkouts.

Batch request

  • Endpoint (to be hosted in Excititor WebService): POST /internal/graph/linkouts
  • Body:
    • tenant (string, required)
    • purls (array, required, max 500) — normalized PURL strings.
    • includeJustifications (bool, default false)
    • includeProvenance (bool, default true)
  • Idempotency key: tenant + SHA256 of sorted purls list.

Response shape

  • items[] ordered by input PURL list:
    • purl
    • advisories[] — entries with advisoryId, source, status, justification?, modifiedAt, evidenceHash, connectorId, dsseEnvelopeHash?.
    • conflicts[] — optional disagreements (status/justification) with source, observedAt, evidenceHash.
  • notFound[] — PURLs with no VEX observations.

Determinism & limits

  • Response ordering stable: by input PURL order, then advisoryId, then source.
  • Max rows: cap advisories to 200 per PURL; truncate with truncated: true flag and nextCursor (advisoryId, source).

Acceptance for prep completion

  • Request/response contract frozen; Cartographer can stub to this interface. Downstream GRAPH-21-001 implementation must adhere or update doc + sprint risks.