# Graph Parity Rollout Guide

Status: Draft (2025-11-26) — DOCS-GRAPH-24-007.

## Goal
Transition from legacy graph surfaces (Cartographer/UI stubs) to the new Graph API + Indexer stack with clear rollback and parity checks.

## 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
- `docs/api/graph.md`, `docs/modules/graph/architecture-index.md`
- `docs/implplan/SPRINT_0141_0001_0001_graph_indexer.md`
- `docs/implplan/SPRINT_0207_0001_0001_graph.md`