prep docs and service updates

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

@@ -0,0 +1,23 @@
+# Excititor · Graph Overlay Prep (GRAPH-21-002)
+
+- **Date:** 2025-11-20
+- **Depends on:** GRAPH-21-001 linkout contract
+- **Working directory:** `src/Excititor/StellaOps.Excititor.WebService`
+
+## Overlay payload
+- Aggregates output of GRAPH-21-001 into overlay items for inspectors:
+  - `purl`
+  - `summary`: `open`, `not_affected`, `under_investigation`, `no_statement` counts
+  - `latestModifiedAt` (ISO-8601 UTC)
+  - `justifications[]` (optional) — unique justification codes present for the PURL
+  - `provenance` — `sources[]` (unique source IDs), `lastEvidenceHash`
+- Endpoint: `GET /v1/graph/overlays?purl=<purl>[&purl=...]&includeJustifications=true|false`
+- Sorting: results ordered by input PURL list; within overlays, `justifications` sorted ascending.
+
+## Caching
+- Cache key: tenant + sorted PURL list + `includeJustifications` flag; ttl 5 minutes default, configurable `excititor:graph:overlayTtlSeconds`.
+- Cache metadata returned: `cached: true|false`, `cacheAgeMs`.
+
+## Acceptance for prep completion
+- Overlay shape and caching contract defined; implementation can proceed once GRAPH-21-001 is available.
+