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:
@@ -40,14 +40,10 @@ Non-goals: policy authoring UI (handled by Console), ingestion or advisory norma
|
||||
|
||||
### 1.2 · Simulation compatibility contract (Sprint 20260309_011)
|
||||
|
||||
- The Policy Gateway exposes a deterministic compatibility surface for the Console simulation history workflow while the deeper Policy Engine read models continue to evolve.
|
||||
- Compatibility endpoints under `/policy` include:
|
||||
- `GET /policy/simulations/history`
|
||||
- `GET /policy/simulations/compare`
|
||||
- `POST /policy/simulations/{simulationId}/verify`
|
||||
- `PATCH /policy/simulations/{simulationId}`
|
||||
- These endpoints return tenant-scoped history entries, comparison diffs, reproducibility checks, and pin state with stable field names that match the live Console contract (`resultHash`, `findingsBySeverity`, `pinned`, `matchPercentage`, `discrepancies`).
|
||||
- The compatibility layer is intentionally stateful per tenant so operators can exercise history actions end to end in the live shell without client-side mocks.
|
||||
- The legacy compatibility surface under `/policy` no longer fabricates tenant-scoped simulation state in live hosts.
|
||||
- `StellaOps.Policy.Gateway` and the merged `StellaOps.Policy.Engine` gateway surface now return `501 problem+json` for the `/policy` simulation compatibility routes until a durable Policy Registry backend is wired.
|
||||
- This explicitly covers the previous shadow-mode, simulation-history, simulation-compare, exception-compatibility, merge-preview, and batch-evaluation compatibility routes that had been backed by process-local dictionaries.
|
||||
- `StellaOps.Policy.Registry` still contains in-memory store implementations for its internal test harness, but the public runtime DI helper that exposed those registrations was removed. Registry in-memory storage is now testing-only and is no longer advertised as a live host composition path.
|
||||
|
||||
---
|
||||
|
||||
@@ -109,6 +105,12 @@ Key notes:
|
||||
- Orchestrator manages run scheduling/fairness; writes run tickets to queue, leases jobs to worker pool.
|
||||
- Workers evaluate policies using cached IR; join external services via tenant-scoped clients; pull immutable advisories/VEX from the raw stores; write derived overlays to PostgreSQL and optional explain bundles to blob storage.
|
||||
- Observability (metrics/traces/logs) integrated via OpenTelemetry (not shown).
|
||||
- Canonical policy pack runtime state is durable: pack containers, revision activation state, approval history, bundle digests, signed payloads, AOC metadata, and persisted DSL source now live in PostgreSQL (`policy.packs`, `policy.pack_versions`). Runtime reload reconstructs compiled bundle documents by recompiling the persisted source text, so pack activation/evaluation survives host restart without an in-memory bundle cache.
|
||||
- Canonical violation runtime state is also durable: emitted violation events, fused severities, and persisted conflict records now live in PostgreSQL (`policy.violation_events`, `policy.violation_fusion_results`, `policy.conflicts`). Restarted hosts reuse persisted event/fusion/conflict state through the `/policy/violations/*` API instead of rebuilding from an in-memory store.
|
||||
- Additional canonical Policy runtime state is now durable as well: verification policies, attestation reports, risk scoring jobs, console export jobs/executions/bundles, policy-pack bundle imports, and sealed mode state persist in PostgreSQL (`policy.verification_policies`, `policy.attestation_reports`, `policy.risk_scoring_jobs`, `policy.console_export_*`, `policy.policy_pack_bundle_imports`, `policy.sealed_mode_states`) and survive host restart without in-memory recovery logic.
|
||||
- The standalone Policy Gateway no longer uses a process-local outbound token cache. Client-credentials token reuse now flows through `MessagingTokenCache` backed by PostgreSQL transport tables on the Policy DSN, matching the engine's durable messaging-cache pattern.
|
||||
- The merged gateway governance surface is no longer backed by process-local dictionaries. `/api/v1/governance/sealed-mode/status` and `/api/v1/governance/sealed-mode/toggle` resolve through the persisted `ISealedModeService`, `/api/v1/governance/risk-profiles*` now exposes only configuration-backed read-only projections plus stateless validation, and unsupported governance write/trust-weight/staleness/conflict/audit compatibility routes return truthful `501` responses instead of fabricated state.
|
||||
- The standalone Policy Gateway also no longer fabricates governance compatibility state. Its `/api/v1/governance/*` compatibility routes now return truthful `501` responses unless a real governance backend is explicitly wired behind the host.
|
||||
|
||||
---
|
||||
|
||||
@@ -379,7 +381,7 @@ Determinism guard instrumentation wraps the evaluator, rejecting access to forbi
|
||||
- `status`, `justification`, `status_notes`, `impact_statement`, `action_statement`.
|
||||
- `products` (purl) and `evidence` array referencing `reachability.json`, `sbom.cdx.json`, `runtimeFacts`.
|
||||
3. **DSSE signing.** The emitter calls Signer `POST /api/v1/signer/sign/dsse` with predicate `stella.ops/vexDecision@v1`. Signer verifies PoE + scanner integrity and returns a DSSE envelope (`decision.dsse.json`).
|
||||
4. **Transparency (optional).** When Rekor integration is enabled, Attestor logs the DSSE payload and returns `{uuid, logIndex, checkpoint}` which we persist next to the decision.
|
||||
4. **Transparency (optional).** When Rekor integration is enabled, Attestor logs the DSSE payload and returns `{uuid, logIndex, checkpoint}` which we persist next to the decision. Hosts that do not configure Rekor anchoring must fail truthfully with an unsupported submission path; they must never fabricate a successful transparency receipt.
|
||||
5. **Export.** API/CLI endpoints expose `decision.openvex.json`, `decision.dsse.json`, `rekor.txt`, and evidence metadata so Export Center + bench automation can mirror them into `bench/findings/**` as defined in the [VEX Evidence Playbook](../../benchmarks/vex-evidence-playbook.md).
|
||||
|
||||
All payloads are immutable and include analyzer fingerprints (`scanner.native@sha256:...`, `policyEngine@sha256:...`) so replay tooling can recompute identical digests. Determinism tests cover both the OpenVEX JSON and the DSSE payload bytes.
|
||||
@@ -465,6 +467,7 @@ Bypass attempts are logged to `policy.gate_bypass_audit`:
|
||||
- Sync and async gate evaluation now materialize a tenant-scoped target snapshot in `policy.engine_snapshots` before delta computation. The runtime derives that target snapshot from the latest persisted `policy.engine_ledger_exports` document (or the baseline snapshot's export), stamps the artifact digest/repository/tag onto the snapshot row, and then passes the real snapshot identifier into `DeltaComputer`.
|
||||
- `IOrchestratorJobStore` and `IWorkerResultStore` now resolve to persisted adapters over `policy.orchestrator_jobs` and `policy.worker_results`, so Policy export/bootstrap logic survives host recreates instead of depending on process-local completed-job state.
|
||||
- Direct `/policy/orchestrator/jobs` submissions now use a real producer runtime. `OrchestratorJobService.SubmitAsync` signals `PolicyOrchestratorJobWorkerHost`, the host leases the next queued job from `IOrchestratorJobStore`, marks it `running`, executes `PolicyWorkerService`, persists `policy.worker_results`, and records terminal `completed` or `failed` state instead of requiring a separate manual `/policy/worker/run` call.
|
||||
- `IReachabilityFactsOverlayCache` now resolves to `MessagingReachabilityFactsOverlayCache` backed by the PostgreSQL messaging transport on the same Policy DSN. Cache rows survive host restart in transport-owned `messaging.cache_*` tables, and the live invalidation path now uses normalized logical keys instead of the old double-prefixed `rf:rf:*` shape that broke tenant invalidation after cutover.
|
||||
- The deterministic `/api/policy/eval/batch` surface remains stateless by contract. It returns evaluation results to callers but does not populate `policy.orchestrator_jobs` or `policy.worker_results`.
|
||||
- When a gate request omits an explicit baseline reference and the tenant has no persisted baseline snapshot yet, the engine now auto-builds the first ledger export from completed persisted Policy results and auto-creates a baseline snapshot before materializing the target snapshot. Explicit baseline references remain strict: if the caller asks for a missing snapshot ID, the runtime fails instead of inventing one.
|
||||
- `StellaOps.Policy.Persistence` now applies startup migrations for the Policy schema on `policy-engine` boot, and `001_initial_schema.sql` is idempotent on reused local volumes so snapshot/export runtime convergence does not depend on a fresh database.
|
||||
@@ -868,7 +871,7 @@ stella exception status <request-id>
|
||||
|
||||
### Governance Compatibility Endpoints
|
||||
|
||||
The console governance workspaces also depend on a tenant-scoped compatibility surface under `/api/v1/governance/*` that lives in the Policy gateway.
|
||||
The console governance workspaces still target a tenant-scoped compatibility surface under `/api/v1/governance/*`, but that surface is now explicitly split between persisted read paths and truthful unsupported behavior.
|
||||
|
||||
- `GET /api/v1/governance/trust-weights`
|
||||
- `PUT /api/v1/governance/trust-weights/{weightId}`
|
||||
@@ -884,10 +887,15 @@ The console governance workspaces also depend on a tenant-scoped compatibility s
|
||||
Contract requirements:
|
||||
- All requests are tenant-scoped and may include an optional `projectId`.
|
||||
- Console clients must resolve live tenant scope from the active session/context and must not rely on legacy placeholder aliases.
|
||||
- Conflict dashboard/list responses remain deterministic so scratch rebuilds and replayed Playwright sweeps see stable cards, trend buckets, and action affordances.
|
||||
- The merged `StellaOps.Policy.Engine` host serves sealed-mode status/toggle from persisted sealed-mode state and serves `risk-profiles` as configuration-backed read-only data.
|
||||
- Compatibility routes without a durable backend (`trust-weights`, `staleness`, `conflicts`, governance audit/history, risk-budget dashboards, sealed-mode overrides, and risk-profile mutation/lifecycle actions) must return truthful `501 Not Implemented` responses rather than fabricate tenant-local state.
|
||||
- The standalone `StellaOps.Policy.Gateway` host does not own governance state and therefore returns truthful `501` responses across this compatibility surface unless a future sprint wires a real backend.
|
||||
|
||||
Implementation reference:
|
||||
- `src/Policy/StellaOps.Policy.Engine/Endpoints/Gateway/GovernanceEndpoints.cs`
|
||||
- `src/Policy/StellaOps.Policy.Engine/Endpoints/Gateway/GovernanceCompatibilityEndpoints.cs`
|
||||
- `src/Policy/StellaOps.Policy.Gateway/Endpoints/GovernanceCompatibilityEndpoints.cs`
|
||||
- `src/Policy/StellaOps.Policy.Gateway/Endpoints/GovernanceEndpoints.cs`
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user