stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/migration/graph-parity.md
StellaOps Bot d63af51f84
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
oas-ci / oas-validate (push) Has been cancelled
Details
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Details
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Details
Policy Simulation / policy-simulate (push) Has been cancelled
Details
devportal-offline / build-offline (push) Has been cancelled
Details
up
2025-11-26 20:23:28 +02:00

2.5 KiB
Raw Permalink Blame History

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