docs: module dossier + install/quickstart sync for truthful cutover sprints
- API_CLI_REFERENCE.md, INSTALL_GUIDE.md, quickstart.md, architecture/integrations.md, dev/DEV_ENVIRONMENT_SETUP.md, integrations/LOCAL_SERVICES.md: reflect real-service wiring. - docs/modules/**: module dossier updates across the modules touched by SPRINT_20260415_001..007 + SPRINT_20260416_003..017 + SPRINT_20260417_018..024 + SPRINT_20260418_025 + SPRINT_20260419_026. - docs/features/checked/web/**: update feature notes where UI changed. - docs/qa/feature-checks/runs/web/evidence-presentation-ux/: QA evidence artifacts. - docs/setup/**, docs/technical/**: align with setup wizard contracts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -2,6 +2,12 @@
|
||||
|
||||
Graph Indexer + Graph API build the tenant-scoped knowledge graph that powers blast-radius analysis, provenance timelines, and saved-query automation across StellaOps. Cartographer has been retired as of 2025-10-30 (see `docs/updates/2025-10-30-devops-governance.md`); this module now owns ingestion, storage, overlays, and query surfaces for graph data.
|
||||
|
||||
## Runtime cutover status
|
||||
- Non-testing Graph API hosts now require Graph PostgreSQL configuration; only `Testing` may boot with the deterministic empty in-memory repository.
|
||||
- Saved views are durable in non-testing hosts via `graph.saved_views`; the in-memory saved-view store is harness-only.
|
||||
- Live Graph query/search/path/diff surfaces remain repository-backed, but live overlays, export jobs, and edge-metadata explanations no longer fabricate in-process data. Non-testing hosts return truthful `501` for those routes until durable backends land.
|
||||
- Live audit logging is log-only and no longer keeps in-process request history.
|
||||
|
||||
## Scope & responsibilities
|
||||
- Ingest SBOM snapshots, advisory/VEX events, policy overlays, and runtime signals to maintain a first-party graph representation with deterministic node/edge identities.
|
||||
- Serve APIs and saved-query tooling for impact analysis, dependency traversal, diffing, and policy/VEX overlays with explainable provenance.
|
||||
|
||||
@@ -31,14 +31,14 @@
|
||||
- `POST /graph/diff` — compares `snapshotA` vs `snapshotB`, streaming node/edge added/removed/changed tiles plus stats; budget enforcement mirrors `/graph/query`.
|
||||
- `POST /graph/export` — async job producing deterministic manifests (`sha256`, size, format) for `ndjson/csv/graphml/png/svg`; download via `/graph/export/{jobId}`.
|
||||
- `POST /graph/lineage` - returns SBOM lineage nodes/edges anchored by `artifactDigest` or `sbomDigest`, with optional relationship filters and depth limits.
|
||||
- Runtime repository selection is config-driven at service resolution time: when `Postgres:Graph` is configured, the live `/graph/query`, `/graph/diff`, and shipped `/graphs*` compatibility surfaces materialize persisted rows from `graph.graph_nodes`, `graph.graph_edges`, and `graph.pending_snapshots`; when it is not configured, the runtime fallback is an empty in-memory repository rather than historical demo-seeded graph data.
|
||||
- Runtime repository selection is config-driven at service resolution time: when `Postgres:Graph` is configured, the live `/graph/query`, `/graph/diff`, and shipped `/graphs*` compatibility surfaces materialize persisted rows from `graph.graph_nodes`, `graph.graph_edges`, and `graph.pending_snapshots`; when it is not configured, only the `Testing` environment may use the empty in-memory repository harness.
|
||||
- Compatibility facade for the shipped Angular explorer:
|
||||
- `GET /graphs`, `GET /graphs/{graphId}`, `GET /graphs/{graphId}/tiles`
|
||||
- `GET /search`, `GET /paths`
|
||||
- `GET /graphs/{graphId}/export`, `GET /assets/{assetId}/snapshot`, `GET /nodes/{nodeId}/adjacency`
|
||||
- `GET/POST/DELETE /graphs/{graphId}/saved-views`
|
||||
- The compatibility tile surface emits only `policy`, `vex`, and `aoc` overlays on the shipped web path.
|
||||
- Saved views are persisted in PostgreSQL table `graph.saved_views` when `Postgres:Graph` is configured; the API falls back to an in-memory store only for hosts that do not wire Graph persistence.
|
||||
- Saved views are persisted in PostgreSQL table `graph.saved_views` when `Postgres:Graph` is configured; the API falls back to an in-memory store only in the `Testing` environment.
|
||||
- **Edge Metadata API** (added 2025-01):
|
||||
- `POST /graph/edges/metadata` — batch query for edge explanations; request contains `EdgeIds[]`, response includes `EdgeTileWithMetadata[]` with full provenance.
|
||||
- `GET /graph/edges/{edgeId}/metadata` — single edge metadata with explanation, via, provenance, and evidence references.
|
||||
@@ -47,7 +47,17 @@
|
||||
- `GET /graph/edges/by-evidence?evidenceType=&evidenceRef=` — query edges by evidence reference.
|
||||
- Legacy: `GET /graph/nodes/{id}`, `POST /graph/query/saved`, `GET /graph/impact/{advisoryKey}`, `POST /graph/overlay/policy` remain in spec but should align to the NDJSON surfaces above as they are brought forward.
|
||||
|
||||
### 3.1) Tenant and auth resolution contract (Sprint 20260222.058)
|
||||
### 3.1) Current runtime posture (Sprint 20260416_003)
|
||||
|
||||
- Non-testing Graph hosts require `Postgres:Graph`; startup fails fast when the canonical Graph PostgreSQL connection string is absent.
|
||||
- `Testing` is the only supported environment for the empty in-memory Graph runtime harness.
|
||||
- Non-testing `POST /graph/query` and `POST /graph/paths` no longer fabricate overlays. Requests that ask for overlays return truthful `501 GRAPH_FEATURE_UNAVAILABLE` responses until a durable overlay backend exists.
|
||||
- Non-testing `POST /graph/export` and `GET /graph/export/{jobId}` now return truthful `501 GRAPH_FEATURE_UNAVAILABLE` responses instead of synthesizing in-memory export jobs.
|
||||
- Non-testing edge-metadata surfaces (`/graph/edges/metadata`, `/graph/edges/{edgeId}/metadata`, `/graph/edges/path/...`, `/graph/edges/by-reason/...`, `/graph/edges/by-evidence`) now return truthful `501 GRAPH_FEATURE_UNAVAILABLE` responses until a durable backend exists.
|
||||
- The shipped `/graphs/{graphId}/tiles` compatibility surface no longer emits fabricated overlays outside `Testing`.
|
||||
- Live audit logging is log-only; request history is no longer retained in-process as pretend durable state.
|
||||
|
||||
### 3.2) Tenant and auth resolution contract (Sprint 20260222.058)
|
||||
|
||||
- Graph uses a single tenant resolver path (`GraphRequestContextResolver`) across search/query/paths/diff/lineage/export and edge-metadata endpoints.
|
||||
- Tenant source precedence and compatibility:
|
||||
@@ -61,7 +71,7 @@
|
||||
- Scope checks are policy-driven (`Graph.ReadOrQuery`, `Graph.Query`, `Graph.Export`) and no endpoint directly trusts raw scope headers.
|
||||
- Rate limiting and audit logging use the resolved tenant context; authenticated flows no longer collapse to ambiguous `"unknown"` tenant keys.
|
||||
|
||||
### 3.2) Edge Metadata Contracts
|
||||
### 3.3) Edge Metadata Contracts
|
||||
|
||||
The edge metadata system provides explainability for graph relationships:
|
||||
|
||||
@@ -71,7 +81,7 @@ The edge metadata system provides explainability for graph relationships:
|
||||
- **EdgeProvenanceRef** record: Source system, collection timestamp, SBOM digest, scan digest, attestation ID, event offset.
|
||||
- **EdgeTileWithMetadata** record: Extends `EdgeTile` with `Explanation` property containing the full metadata.
|
||||
|
||||
### 3.3) Localization runtime contract (Sprint 20260224_002)
|
||||
### 3.4) Localization runtime contract (Sprint 20260224_002)
|
||||
|
||||
- Graph API now initializes localization via `AddStellaOpsLocalization(...)`, `AddTranslationBundle(...)`, `AddRemoteTranslationBundles()`, `UseStellaOpsLocalization()`, and `LoadTranslationsAsync()`.
|
||||
- Locale resolution order for API messages is deterministic: `X-Locale` header -> `Accept-Language` header -> default locale (`en-US`).
|
||||
|
||||
@@ -8,7 +8,7 @@ Provide a living plan for Graph deliverables, dependencies, and evidence.
|
||||
- Update this file when new scoped work is approved.
|
||||
|
||||
## Near-term deliverables
|
||||
- TBD (add when sprint is staffed).
|
||||
- `docs/implplan/SPRINT_20260416_003_Graph_graph_api_truthful_runtime_cutover.md` - completed live runtime cleanup for Graph API host fallbacks and fabricated overlay/export/edge-metadata services.
|
||||
|
||||
## Dependencies
|
||||
- `docs/modules/graph/architecture.md`
|
||||
@@ -22,3 +22,4 @@ Provide a living plan for Graph deliverables, dependencies, and evidence.
|
||||
|
||||
## Notes
|
||||
- Keep deterministic and offline-first expectations aligned with module AGENTS.
|
||||
- `Testing` is now the only supported harness environment for in-memory Graph overlays/export/edge metadata. Non-testing hosts require Graph Postgres and return truthful `501` for unsupported live feature slices.
|
||||
|
||||
Reference in New Issue
Block a user