up

docs/migration/graph-parity.md

@@ -0,0 +1,61 @@
+# 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`