prep docs and service updates

docs/modules/excititor/prep/2025-11-20-graph-21-001-prep.md

@@ -0,0 +1,32 @@
+# 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.
+