# 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.