Graph Parity Rollout Guide

Status: Draft (2025-11-26) — DOCS-GRAPH-24-007. Audience: platform and SRE teams rolling out the new graph stack, plus the UI/CLI guilds cutting clients over.

Goal

Transition from the legacy graph surfaces (Cartographer / UI stubs) to the new Graph API + Indexer stack, with explicit parity checks at every phase and a clean rollback path.

Scope

• Graph API (Sprint 0207) + Graph Indexer (Sprint 0141)
• Consumers: Graph Explorer, Vuln Explorer, Console/CLI, Export Center, Advisory AI overlays
• Tenants: all; pilot recommended with 1–2 tenants first

Phased rollout

1. Pilot
   • Enable new Graph API for pilot tenants behind feature flag graph.api.v2.
   • Run daily parity job: compare node/edge counts and hashes against legacy output for selected snapshots.
2. Shadow
   • Mirror queries from UI/CLI to both legacy and new APIs; log differences.
   • Metrics to track: parity_diff_nodes_total, parity_diff_edges_total, p95 latency deltas.
3. Cutover
   • Switch UI/CLI to new endpoints; keep shadow logging for 1 week.
   • Freeze legacy write paths; keep read-only export for rollback.
4. Cleanup
   • Remove legacy routes; retain archived parity reports and exports.

Parity checks

• Deterministic snapshots: compare SHA256 of nodes.jsonl and edges.jsonl (sorted).
• Query parity: run canned queries (search/query/paths/diff) and compare:
  • Node/edge counts, first/last IDs
  • Presence of overlays (policy/vex)
  • Cursor progression
• Performance: ensure p95 latency within ±20% of legacy baseline during shadow.

Rollback

• Keep legacy service in read-only mode; toggle feature flag back if parity fails.
• Retain last good exports and parity reports for each tenant.
• If overlays mismatch: clear overlay cache and rerun policy overlay ingestion; fall back to legacy overlays temporarily.

Observability

• Dashboards: add panels for parity diff counters and latency delta.
• Alerts:
  • parity_diff_nodes_total > 0 for 10m
  • Latency delta > 20% for 10m
• Logs should include tenant, snapshotId, query type, cursor, hash comparisons.

Owners

• Graph API Guild (API/runtime)
• Graph Indexer Guild (snapshots/ingest)
• Observability Guild (dashboards/alerts)
• UI/CLI Guilds (client cutover)

Checklists

• [ ] Feature flag wired and default off.
• [ ] Canned query set stored in repo (deterministic inputs).
• [ ] Parity job outputs SHA256 comparison and stores reports per tenant/date.
• [ ] Rollback tested in staging.

References

• Graph API
• Graph module architecture index
• Sprint plans (source repo docs/implplan/): SPRINT_0141_0001_0001_graph_indexer.md (Indexer), SPRINT_0207_0001_0001_graph.md (Graph API)