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:
master
2026-04-19 14:45:09 +03:00
parent ad62ba7f76
commit fdf95e0f46
67 changed files with 590 additions and 360 deletions

View File

@@ -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`).