stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity

wip: doctor/cli/docs/api to vector db consolidation; api hardening for descriptions, tenant, and scopes; migrations and conversions of all DALs to EF v10

Browse Source
This commit is contained in:
master
2026-02-23 15:30:50 +02:00
parent bd8fee6ed8
commit e746577380
1424 changed files with 81225 additions and 25251 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/modules/graph/README.md
View File

@@ -37,7 +37,14 @@ Graph Indexer + Graph API build the tenant-scoped knowledge graph that powers bl
## Operations & runbook (Sprint 030)
- Dashboards: import `Observability/graph-api-grafana.json` (panels for latency, budget denials, overlay cache ratio, export latency). Apply tenant filter in every panel.
- Health checks: `/healthz` should be 200; search/query/paths/diff/export endpoints require `X-Stella-Tenant`, `Authorization`, and scopes (`graph:read/query/export`).
- Health checks: `/healthz` should be 200; search/query/paths/diff/export endpoints require tenant context, `Authorization`, and graph scopes (`graph:read/query/export`).
- Tenant context resolution:
- Canonical header: `X-StellaOps-Tenant`.
- Compatibility headers: `X-Stella-Tenant`, `X-Tenant-Id` (migration-only).
- Conflicting tenant values across headers/claims are rejected deterministically with `400 GRAPH_VALIDATION_FAILED`.
- Scope enforcement:
- Graph endpoints authorize against claim-based policies (`Graph.ReadOrQuery`, `Graph.Query`, `Graph.Export`).
- Header scope compatibility (`X-StellaOps-Scopes`, `X-Stella-Scopes`) is bridged once at authentication and then evaluated only through policies.
- Key metrics (new):
- `graph_tile_latency_seconds` histogram (label `route`); alert when p95 > 1.5s for 5m.
- `graph_query_budget_denied_total` counter (label `reason`); investigate spikes (>50 in 5m).

24
docs/modules/graph/architecture.md
View File

@@ -35,11 +35,25 @@
- `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.
- `GET /graph/edges/path/{sourceNodeId}/{targetNodeId}` — returns all edges on the shortest path between two nodes, each with metadata.
- `GET /graph/edges/by-reason/{reason}` — query edges by `EdgeReason` enum (e.g., `SbomDependency`, `AdvisoryAffects`, `VexStatement`, `RuntimeTrace`).
- `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) Edge Metadata Contracts
- `GET /graph/edges/by-reason/{reason}` — query edges by `EdgeReason` enum (e.g., `SbomDependency`, `AdvisoryAffects`, `VexStatement`, `RuntimeTrace`).
- `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)
- Graph uses a single tenant resolver path (`GraphRequestContextResolver`) across search/query/paths/diff/lineage/export and edge-metadata endpoints.
- Tenant source precedence and compatibility:
- claim: `stellaops:tenant` (with bounded aliases `tid`, `tenant_id`)
- headers: `X-StellaOps-Tenant` (canonical), then migration headers `X-Stella-Tenant` and `X-Tenant-Id`
- Deterministic failures:
- missing tenant: `400 GRAPH_VALIDATION_FAILED`
- conflicting tenant claim/header values: `400 GRAPH_VALIDATION_FAILED`
- missing auth: `401 GRAPH_UNAUTHORIZED`
- missing scope: `403 GRAPH_FORBIDDEN`
- 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
The edge metadata system provides explainability for graph relationships: