Cartographer Graph Handshake Plan

Status: 2025-10-29

Why this exists

The Concelier/Excititor graph enrichment work (CONCELIER-GRAPH-21-001/002, EXCITITOR-GRAPH-21-001/002/005) and the merge-side coordination tasks (FEEDMERGE-COORD-02-901/902) are blocked on a clear contract with Cartographer and the Policy Engine. This document captures the minimum artefacts each guild owes so we can unblock the graph pipeline and resume implementation without re-scoping every stand-up.

Deliverables by guild

Cartographer Guild

CARTO-GRAPH-21-002 (Inspector contract): publish the inspector payload schema (graph.inspect.v1) including the fields Cartographer needs from Concelier/Excititor (SBOM relationships, advisory/VEX linkouts, justification summaries). Target format: shared Proto/JSON schema stored under src/Cartographer/Contracts/.
CARTO-GRAPH-21-005 (Inspector access patterns): document the query shapes Cartographer will execute (PURL → advisory, PURL → VEX statement, policy scope filters) so storage can project the right indexes/materialized views. Include sample mongosh queries and desired TTL/limit behaviour.
Provide a test harness (e.g., Postman collection or integration fixture) Cartographer will use to validate the Concelier/Excititor endpoints once they land.

Concelier Core Guild

Derive adjacency data from SBOM normalization as described in CONCELIER-GRAPH-21-001 (depends on CONCELIER-POLICY-20-002). Once Cartographer publishes the schema above, implement:
- Node payloads: component metadata, scopes, entrypoint annotations.
- Edge payloads: contains, depends_on, provides, provenance array.
Change events (CONCELIER-GRAPH-21-002): define sbom.relationship.changed event contract with tenant + context metadata, referencing Cartographer’s filter requirements. Include event samples and replay instructions in docs/graph/concelier-events.md.
Coordinate with Cartographer on pagination/streaming expectations (page size, continuation token, retention window).

Excititor Core & Storage Guilds

Inspector linkouts (EXCITITOR-GRAPH-21-001): expose Batched VEX/advisory lookup endpoint that accepts graph node PURLs and responds with raw document slices + justification metadata. Ensure Policy Engine scope enrichment (EXCITITOR-POLICY-20-002) feeds this response so Cartographer does not need to call multiple services.
Overlay enrichment (EXCITITOR-GRAPH-21-002): align the overlay metadata with Cartographer’s schema once it lands (include justification summaries, document versions, and provenance).
Indexes/materialized views (EXCITITOR-GRAPH-21-005): after Cartographer publishes query shapes, create the necessary indexes (PURL + tenant, policy scope) and document migrations in storage runbooks. Provide load testing evidence before enabling in production.

Policy Guild

CONCELIER-POLICY-20-002: publish the enriched linkset schema that powers both Concelier and Excititor payloads. Include enumerations for relationship types and scope tags.
Share the Policy Engine timeline for policy overlay metadata (POLICY-ENGINE-30-001) so Excititor can plan the overlay enrichment delivery.

Shared action items

Owner	Task	Deadline	Notes
Cartographer	Publish inspector schema + query patterns (`CARTO-GRAPH-21-002`/`21-005`)	2025-11-04	Attach schema files + examples to this doc once merged.
Concelier Core	Draft change-event payload with sample JSON	2025-11-06	Blocked until Cartographer schema lands; prepare skeleton PR in `docs/graph/concelier-events.md`.
Excititor Core/Storage	Prototype batch linkout API + index design doc	2025-11-07	Leverage Cartographer query patterns to size indexes; include perf targets.
Policy Guild	Confirm linkset enrichment fields + overlay timeline	2025-11-05	Needed to unblock both Concelier enrichment and Excititor overlay tasks.

Reporting

Track progress in the #cartographer-handshake Slack thread (create once Cartographer posts the schema MR).
During the twice-weekly graph sync, review outstanding checklist items above and update the task notes (TASKS.md) so the backlog reflects real-time status.
Once the schema and query contracts are merged, the Concelier/Excititor teams can flip their tasks from BLOCKED to DOING and attach implementation plans referencing this document.

Appendix: references

CONCELIER-GRAPH-21-001, CONCELIER-GRAPH-21-002 (Concelier Core task board)
EXCITITOR-GRAPH-21-001, EXCITITOR-GRAPH-21-002, EXCITITOR-GRAPH-21-005 (Excititor Core/Storage task boards)
CARTO-GRAPH-21-002, CARTO-GRAPH-21-005 (Cartographer task board)
POLICY-ENGINE-30-001, CONCELIER-POLICY-20-002, EXCITITOR-POLICY-20-002 (Policy Engine roadmap)

4.7 KiB Raw Blame History Unescape Escape