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:
@@ -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`).
|
||||
|
||||
Reference in New Issue
Block a user