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

docs: module dossier + install/quickstart sync for truthful cutover sprints

Browse Source 
- 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
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/modules/excititor/architecture.md
View File

@@ -159,7 +159,8 @@ Schema: `vex`
- **Observations/linksets** - use the append-only Postgres linkset schema already defined for `IAppendOnlyLinksetStore` (tables `vex_linksets`, `vex_linkset_observations`, `vex_linkset_disagreements`, `vex_linkset_mutations`) with indexes on `(tenant, vulnerability_id, product_key)` and `updated_at`.
- **Claims** - `vex.claims` stores normalized, queryable claim projections keyed by deterministic `claim_hash`, with JSONB columns for product/document metadata plus indexes on `(tenant, provider_id, vulnerability_id, product_key, last_seen)` and `(tenant, vulnerability_id, last_seen)`.
- **Graph overlays** - materialized cache table `vex_overlays` (tenant, purl, advisory_id, source) storing JSONB payloads that follow `docs/modules/excititor/schemas/vex_overlay.schema.json` (schemaVersion 1.0.0). Cache eviction via `cached_at + ttl_seconds`; overlays regenerate when linkset or observation hashes change.
- **Attestations** - `vex.attestations` stores durable DSSE/VEX attestation envelopes keyed by `(tenant, attestation_id)` with manifest lookup and attested-at indexes. Startup migration `005_vex_attestations.sql` creates the table in the active runtime schema so isolated test schemas and the default `vex` schema use the same contract.
- **Graph overlays** - materialized cache table `vex.graph_overlays` (tenant, purl, advisory_id, source) storing JSONB payloads that follow `docs/modules/excititor/schemas/vex_overlay.schema.json` (schemaVersion 1.0.0). Live WebService runtime resolves `IGraphOverlayStore` to the Postgres-backed store; there is no in-memory production fallback.
**Canonicalisation & hashing**
@@ -178,8 +179,8 @@ List/query `/vex/raw` via `SELECT ... FROM vex.vex_raw_documents WHERE tenant=@t
**Runtime convergence**
1. `StellaOps.Excititor.WebService` and `StellaOps.Excititor.Worker` resolve `IVexProviderStore`, `IVexConnectorStateRepository`, and `IVexClaimStore` from `AddExcititorPersistence`; the live hosts do not register in-memory fallbacks.
2. `StellaOps.Excititor.Persistence` owns startup migrations for the `vex` schema, including `vex.claims` creation and cleanup of historical demo rows from older local installs.
1. `StellaOps.Excititor.WebService` and `StellaOps.Excititor.Worker` resolve `IVexProviderStore`, `IVexConnectorStateRepository`, `IVexClaimStore`, `IVexAttestationStore`, and the WebService graph overlay store from persisted services; the live hosts do not register in-memory fallbacks for these paths.
2. `StellaOps.Excititor.Persistence` owns startup migrations for the active runtime schema, including claims, attestation storage, graph overlays, and cleanup of historical demo rows from older local installs.
3. The Excititor migration assembly embeds only active top-level SQL files. Archived pre-1.0 scripts and demo-seed SQL are excluded so startup/test migration loaders do not replay historical or fake runtime state.
---

10
docs/modules/excititor/graph-overlays.md
View File

@@ -13,11 +13,11 @@ Defines the graph-ready overlay built from Link-Not-Merge observations/linksets
- Provenance: carries `linksetId`, `linksetHash`, `observationHashes[]`, optional `policyHash`, `sbomContextHash`, and `planCacheKey` for replay.
## Postgres materialization (IAppendOnlyLinksetStore)
- Table `vex_overlays` (materialized cache):
- Table `vex.graph_overlays` (materialized cache):
- Primary key: `(tenant, purl, advisory_id, source)`.
- Columns: `status`, `justifications` (jsonb), `conflicts` (jsonb), `observations` (jsonb), `provenance` (jsonb), `cached_at`, `ttl_seconds`, `schema_version`.
- Indexes: unique `(tenant, purl, advisory_id, source)`, plus `(tenant, cached_at)` for TTL sweeps.
- Overlay rows are regenerated when linkset hash or observation hash set changes; cache evictions use `cached_at + ttl_seconds`.
- Columns: `tenant`, `purl`, `advisory_id`, `source`, `generated_at`, `payload` (`jsonb`).
- Indexes: primary key plus `(tenant, generated_at DESC)` for deterministic recency reads.
- Overlay rows are regenerated when linkset hash or observation hash set changes; the latest materialized payload is upserted per `(tenant, purl, advisory_id, source)` key.
- Linksets and observation hashes come from the append-only linkset store (`IAppendOnlyLinksetStore`) to preserve Aggregation-Only Contract guarantees.
## API shape (Graph/Vuln Explorer)
@@ -84,4 +84,4 @@ Defines the graph-ready overlay built from Link-Not-Merge observations/linksets
- Consumers (Console, Vuln Explorer, Policy Engine, Risk) should treat `vex_overlay.schema.json` as the authoritative contract.
- Offline kits must bundle the schema file and sample payloads under `docs/modules/excititor/samples/` with SHA256 manifests.
- Future schema versions must bump `schemaVersion` and add migration notes to this document and `docs/modules/excititor/architecture.md`.
- Policy and Risk surfaces in WebService now read overlays directly (with claim-store fallback for policy tests) to produce lookup and risk feeds; overlay cache/store are selected per tenant (in-memory by default, Postgres `vex.graph_overlays` when configured).
- Policy and Risk surfaces in WebService now read overlays directly (with claim-store fallback for policy tests) to produce lookup and risk feeds; the live WebService binds `IGraphOverlayStore` to the Postgres-backed `vex.graph_overlays` store and does not fall back to an in-memory runtime implementation.