# Sprint 0207-0001-0001 · Graph (Experience & SDKs 180.C)

## Topic & Scope
- Deliver graph API surface (search/query/paths/diff/export) with overlays, RBAC, and deterministic streaming tiles for Experience & SDKs stream 180.C.
- Keep indexer snapshots aligned so ingest emits graph artifacts consumable by the API layer; retain offline/export readiness.
- Instrument metrics/logging, budget enforcement, and job exports to match policy/overlay contracts.
- **Working directory:** `src/Graph/StellaOps.Graph.Api`, `src/Graph/StellaOps.Graph.Indexer`.
- Active items only; completed/historic work moves to `docs/implplan/archived/tasks.md`.

## Dependencies & Concurrency
- Upstream sprints: 120.A (AirGap), 130.A (Scanner), 150.A (Orchestrator), 170.A (Notifier) for feeds, digests, and events.
- GRAPH-API-28-001 → 011 are sequential; do not parallelize past their stated dependencies.
- Overlay integration (GRAPH-API-28-006) depends on POLICY-ENGINE-30-001..003 contracts staying stable.

## Documentation Prerequisites
- `docs/README.md`
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- `docs/modules/platform/architecture-overview.md`
- `docs/modules/graph/architecture.md`
- `docs/modules/graph/implementation_plan.md`
- `src/Graph/AGENTS.md`

## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | GRAPH-API-28-001 | TODO | Kick off OpenAPI/JSON schema draft; align cost + tile schema. | Graph API Guild (`src/Graph/StellaOps.Graph.Api`) | Define OpenAPI + JSON schema for graph search/query/paths/diff/export endpoints, including cost metadata and streaming tile schema. |
| 2 | GRAPH-API-28-002 | TODO | GRAPH-API-28-001 | Graph API Guild (`src/Graph/StellaOps.Graph.Api`) | Implement `/graph/search` with multi-type index lookup, prefix/exact match, RBAC enforcement, and result ranking + caching. |
| 3 | GRAPH-API-28-003 | TODO | GRAPH-API-28-002 | Graph API Guild (`src/Graph/StellaOps.Graph.Api`) | Build query planner + cost estimator for `/graph/query`, stream tiles (nodes/edges/stats) progressively, enforce budgets, provide cursor tokens. |
| 4 | GRAPH-API-28-004 | TODO | GRAPH-API-28-003 | Graph API Guild (`src/Graph/StellaOps.Graph.Api`) | Implement `/graph/paths` with depth ≤6, constraint filters, heuristic shortest path search, and optional policy overlay rendering. |
| 5 | GRAPH-API-28-005 | TODO | GRAPH-API-28-004 | Graph API Guild (`src/Graph/StellaOps.Graph.Api`) | Implement `/graph/diff` streaming added/removed/changed nodes/edges between SBOM snapshots; include overlay deltas and policy/VEX/advisory metadata. |
| 6 | GRAPH-API-28-006 | TODO | GRAPH-API-28-005; POLICY-ENGINE-30-001..003 contracts | Graph API Guild (`src/Graph/StellaOps.Graph.Api`) | Consume Policy Engine overlay contract and surface advisory/VEX/policy overlays with caching, partial materialization, and explain trace sampling for focused nodes. |
| 7 | GRAPH-API-28-007 | TODO | GRAPH-API-28-006 | Graph API Guild (`src/Graph/StellaOps.Graph.Api`) | Implement exports (`graphml`, `csv`, `ndjson`, `png`, `svg`) with async job management, checksum manifests, and streaming downloads. |
| 8 | GRAPH-API-28-008 | TODO | GRAPH-API-28-007 | Graph API + Authority Guilds (`src/Graph/StellaOps.Graph.Api`) | Integrate RBAC scopes (`graph:read`, `graph:query`, `graph:export`), tenant headers, audit logging, and rate limiting. |
| 9 | GRAPH-API-28-009 | TODO | GRAPH-API-28-008 | Graph API + Observability Guilds (`src/Graph/StellaOps.Graph.Api`) | Instrument metrics (`graph_tile_latency_seconds`, `graph_query_budget_denied_total`, `graph_overlay_cache_hit_ratio`), structured logs, and traces per query stage; publish dashboards. |
| 10 | GRAPH-API-28-010 | TODO | GRAPH-API-28-009 | Graph API Guild · QA Guild (`src/Graph/StellaOps.Graph.Api`) | Build unit/integration/load tests with synthetic datasets (500k nodes/2M edges), fuzz query validation, verify determinism across runs. |
| 11 | GRAPH-API-28-011 | TODO | GRAPH-API-28-010 | Graph API Guild (`src/Graph/StellaOps.Graph.Api`) | Provide deployment manifests, offline kit support, API gateway integration docs, and smoke tests. |
| 12 | GRAPH-INDEX-28-011 | DONE (2025-11-04) | Downstream consumption by API once overlays ready | Graph Indexer Guild (`src/Graph/StellaOps.Graph.Indexer`) | Wire SBOM ingest runtime to emit graph snapshot artifacts, add DI factory helpers, and document Mongo/snapshot environment guidance. |

## Wave Coordination
- Wave 1 · API surface and overlays: GRAPH-API-28-001..011 (sequential pipeline).
- Wave 2 · Indexer readiness: GRAPH-INDEX-28-011 (completed; feeds Wave 1 runtime tests).

## Wave Detail Snapshots
- **Wave 1**: waiting on schema draft (GRAPH-API-28-001) to start downstream implementation; observe dependency chain.
- **Wave 2**: snapshot emission ready; monitor for schema drift once Wave 1 schemas finalize.

## Interlocks
- Policy Engine overlays (POLICY-ENGINE-30-001..003) must stay in sync for GRAPH-API-28-006.
- RBAC scopes and audit logging align with Authority module contracts; coordinate during GRAPH-API-28-008.
- Observability dashboards to reuse shared metrics conventions from Observability Guild.

## Upcoming Checkpoints
- 2025-11-24 · Target date to circulate OpenAPI/JSON schema draft (GRAPH-API-28-001). Owner: Graph API Guild.
- 2025-11-29 · Propose schema sign-off and budget model review before starting GRAPH-API-28-002/003.
- 2025-12-03 · Overlay contract validation with Policy Engine Guild ahead of GRAPH-API-28-006.

## Action Tracker
| Action | Owner | Due (UTC) | Status |
| --- | --- | --- | --- |
| Circulate initial schema/tiles draft for review (GRAPH-API-28-001). Evidence: `docs/modules/graph/prep/2025-11-22-graph-api-schema-outline.md`. | Graph API Guild | 2025-11-24 | In progress |
| Confirm POLICY-ENGINE-30-001..003 contract version for overlay consumption. | Policy Engine Guild · Graph API Guild | 2025-11-30 | Open |
| Prep synthetic dataset fixtures (500k/2M) for load tests. | QA Guild · Graph API Guild | 2025-12-05 | Open |

## Decisions & Risks
- Schema and overlay contracts are prerequisites; any drift will stall downstream API tasks.
- Export formats (GRAPH-API-28-007) require deterministic manifests to satisfy offline kit expectations.
- Budget enforcement (GRAPH-API-28-003) risk: rejection without user-friendly explain traces could increase support load; mitigate by sampling explains early.

| Risk | Impact | Mitigation | Owner | Status |
| --- | --- | --- | --- | --- |
| Overlay contract drift vs POLICY-ENGINE-30-001..003 | Blocks GRAPH-API-28-006 overlays; rework schemas | Freeze contract version before coding; joint review on 2025-12-03 checkpoint | Graph API Guild · Policy Engine Guild | Open |
| Export manifest non-determinism | Offline kit validation fails and retries | Enforce checksum manifests + stable ordering in GRAPH-API-28-007 | Graph API Guild | Open |
| Budget enforcement lacks explain traces | User confusion, support load, potential false negatives | Implement sampled explain traces during GRAPH-API-28-003 and validate via QA fixtures | Graph API Guild · QA Guild | Open |

## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-11-22 | Normalized sprint to standard template and renamed file from `SPRINT_207_graph.md` to `SPRINT_0207_0001_0001_graph.md`; no task status changes. | Project Mgmt |
| 2025-11-22 | Added module charter `src/Graph/AGENTS.md` to unblock implementers; no task status changes. | Project Mgmt |
| 2025-11-22 | Drafted schema/tiles outline for GRAPH-API-28-001 at `docs/modules/graph/prep/2025-11-22-graph-api-schema-outline.md`; marked action as In progress. | Project Mgmt |
| 2025-11-22 | Updated `docs/api/graph-gateway-spec-draft.yaml` to encode search/query/paths/diff/export endpoints and shared schemas per outline; evidence for GRAPH-API-28-001. | Project Mgmt |