# Implementation plan — Graph

## Delivery phases
- **Phase 1 – Graph Indexer foundations**  
  Stand up Graph Indexer service, node/edge schemas, ingestion from SBOM/Concelier/Excititor events, identity stability, and snapshot materialisation.
- **Phase 2 – Graph API service**  
  Expose search, query, path, impact, diff, and overlay endpoints with RBAC, cost controls, and streaming responses.
- **Phase 3 – Console & CLI experiences**  
  Ship Graph Explorer UI (WebGL canvas, filters, diff mode, overlays) and CLI (`stella sbom graph ...`) for automation pipelines.
- **Phase 4 – Advanced analytics**  
  Implement clustering, centrality, saved queries, overlay caching, and Policy Engine explain integration.
- **Phase 5 – Exports & offline**  
  Deliver GraphML/CSV/NDJSON exports, Offline Kit bundles (`nodes.jsonl`, `edges.jsonl`, overlays), and deterministic manifests.
- **Phase 6 – Observability & hardening**  
  Complete dashboards, alerts, runbooks, load/perf testing, and a11y/accessibility review.

## Work breakdown
- **Services**
  - Graph Indexer: event consumers, node/edge builders, snapshot/version handling, aggregate metrics.
  - Graph API: validation, planner/cost guard, streaming tile engine, diff/overlay builder, exports.
  - Worker jobs: clustering, diff, overlay materialisation with backpressure awareness.
- **Data model & storage**
  - Collections/tables (`graph_nodes`, `graph_edges`, `graph_snapshots`, `graph_saved_queries`, `graph_overlays_cache`), indexes, tenant partitioning, append-only change logs.
  - Evaluate document + adjacency vs graph DB abstraction; ensure deterministic serialization for exports.
- **Console**
  - Feature module `graph-explorer` with routes, canvas renderer, panels, diff UI, saved queries, export workflows, a11y pass.
  - Telemetry instrumentation for user interactions and query budgets.
- **CLI & SDK**
  - `stella sbom graph query|diff|impact|export`, with JSON schema and piping support.
  - SDK utilities for automation and CI pipelines.
- **Policy & VEX integration**
  - Fetch explain traces for policy overlays, integrate VEX suppressions, align with Policy Engine & VEX Lens data models.
- **Observability & Ops**
  - Metrics (ingest lag, query latency, cache hit rate), log/traces, dashboards, alerting for runaway queries and OOM.
  - Runbooks for incident classes (query denial, cache poisoning, degraded render).
- **Documentation**
  - Maintain overview, API, query language, console guide, CLI reference, policy/VEX integration docs with compliance checklists.

## Acceptance criteria
- Graph Indexer ingests SBOM/advisory/VEX events deterministically with tenant isolation and append-only provenance.
- Graph API serves search/query/path/diff/overlay endpoints within budgeted latency and enforces cost limits + RBAC.
- Console explorer visualises topology, overlays, diffs, saved queries; CLI commands mirror functionality for automation.
- Exports (GraphML/CSV/NDJSON) and Offline Kit bundles reproduce snapshots and overlays with signed manifests.
- Observability dashboards/alerts detect ingest lag, query failures, cache churn, and memory pressure; runbooks guide remediation.
- Policy/VEX overlays align with Policy Engine explain traces and VEX suppressions.

## Risks & mitigations
- **Graph scale/complexity:** adopt adjacency compression, cached overlays, streaming pagination, enforced query budgets.
- **Tenant bleed:** strict tenant filters, fuzz tests, data masking, compliance reviews.
- **Runaway queries/visualization:** cost planner, query timeout, UI hints, safe mode renders.
- **Cache poisoning:** input validation, schema versioning, eviction policies.
- **Offline parity gaps:** deterministic export pipeline, integration tests for Offline Kit import.

## Test strategy
- **Unit:** node/edge builders, identifier stability, overlay computations, query planner, diff engine.
- **Integration:** end-to-end ingest + query flows across SBOM/advisory/VEX, saved query execution, diff exports.
- **Performance:** large SBOM datasets, concurrency, memory profiling, WebGL rendering.
- **Security:** tenant isolation tests, RBAC, query cost abuse.
- **Offline:** export/import verification, manifest hashing, CLI replay.

## Definition of done
- All phases delivered with telemetry, documentation, runbooks, and Offline Kit parity.
- Console/CLI parity validated; a11y review complete.
- ./TASKS.md and ../../TASKS.md updated; README/architecture/plan kept current with imposed rule references.