d63af51f84
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
# 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`
|