df66ce10c3
Closes SPRINT_20260423_001 — all 3 tasks DONE, sprint archived. Extends
the scalar persisted-settings model (7efa424fe) with an artifact-
reference storage layer for the complex OCI OpenVEX connector, which
carries image subscription lists + cosign keys + TUF roots that don't
fit the flat values/clearKeys shape.
OCI-CFG-001 — Storage model:
- New vex.provider_artifact_refs table via embedded migration
009_vex_provider_artifact_refs.sql (auto-applied per §2.7). Columns:
artifact_id (UUID PK), provider_id, tenant_id, mime_type, size_bytes,
sha256, payload bytea, staged_at, staged_by. RLS via
current_setting('app.tenant_id', TRUE); size_bytes CHECK >= 0.
- Upload / list / meta / delete API under /excititor/providers/{id}/
artifacts. Multipart upload returns { artifactId, sha256, ... };
meta never returns payload. Scopes: read=vex.read, write=vex.admin.
- VexProviderArtifactMaterializer: scoped session writes artifacts to
%TMP%/stella-excititor-artifacts/<guid>/<artifactId>.bin with
chmod 0700/0600 on POSIX; Dispose cleans up the scratch root.
IDisposable + IAsyncDisposable, idempotent cleanup.
- PostgresVexProviderArtifactStore uses raw Npgsql for bytea I/O
(bypasses EF compiled-model cache + change tracking); EF entity
ProviderArtifactRefRow added for future EF-consumer completeness.
OCI-CFG-002 — Config wiring:
- VexProviderConfigurationFieldDefinition.FieldShape extended:
scalar | list<string> | artifactRef | list<artifactRef>.
- list<string> encoded as newline-or-JSON text; artifactRef stored as
the artifact UUID. Snapshot exposes FieldShape for clients.
- OCI-specific blocked sub-codes (all inside PROVIDER_CONFIG_INVALID /
_REQUIRED envelope): PROVIDER_CONFIG_MISSING_IMAGE_SUBSCRIPTIONS,
_INVALID_IMAGE_REFERENCE, _MISSING_COSIGN_KEY, _MISSING_COSIGN_ISSUER,
_MISSING_COSIGN_SUBJECT, _MISSING_TUF_ROOT, _INVALID_COSIGN_MODE,
_HTTP_REGISTRY_BLOCKED.
- Readiness reuses OciOpenVexAttestationConnectorOptions validator.
OCI-CFG-003 — CLI + Web:
- CLI `stella vex providers configure` flags: --image (repeatable),
--upload-artifact <key>=@<path> (repeatable), --clear-artifact,
--list-artifacts, --host-path-compat (CLI-only compatibility mode).
- New subcommand `stella vex providers artifacts <provider>` lists
staged artifacts.
- OciOpenVexConfigurationComponent (Angular standalone): image-
subscription list editor, artifact slots with file upload + staged
meta, scalar fields for cosign mode/issuer/subject/registry auth/
offline bundle, staged-artifact table with delete. Conditionally
rendered in vex-provider-catalog when provider.id == 'excititor:
oci-openvex'.
- docs/modules/excititor/operations/provider-credentials.md §5 OCI
OpenVEX rewritten with 4 canonical setup flows: keyless, keypair,
TUF+offline, private-registry.
Tests: targeted xUnit via scripts/test-targeted-xunit.ps1:
- VexProviderConfigurationServiceTests — 8/8 (regression)
- VexProviderOciOpenVexTests — 13/13 (OCI schema + sub-codes + artifact
service size/quota/tenant-isolation + materializer tempfile lifecycle)
Worker-side wiring of VexProviderArtifactMaterializationSession into
DefaultVexProviderRunner (before cosign/TUF validation) is a natural
follow-up — the resolver + API + store exist; a future sprint ties
the runner into the session lifecycle when the first end-to-end OCI
provider scan lands.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
StellaOps Excititor (Archived -- absorbed into Concelier domain, Sprint 203)
Note: Excititor source code has been moved to
src/Concelier/StellaOps.Excititor.*as part of the advisory domain consolidation (Sprint 203, 2026-03-04). This documentation is kept as a redirect. Full archive atdocs-archived/modules/excititor/. The ADR is recorded indocs/modules/concelier/architecture.md.
Excititor converts heterogeneous VEX feeds into raw observations and linksets that honour the Aggregation-Only Contract.
Latest updates (2025-12-05)
- Chunk API documentation remains blocked until CI is green and a pinned OpenAPI spec + deterministic samples are available.
- Sprint tracker
docs/implplan/SPRINT_0333_0001_0001_docs_modules_excititor.mdand moduleTASKS.mdmirror status. - Observability/runbook assets remain in
operations/observability.mdandobservability/(timeline, locker manifests); dashboards stay offline-import friendly. - Prior updates (2025-11-05): Link-Not-Merge readiness and consensus beta note (
../../implplan/archived/updates/2025-11-05-excitor-consensus-beta.md), observability guide additions, DSSE packaging guidance, and Policy/CLI follow-ups tracked in SPRINT_200. - Link-Not-Merge readiness: release note Excitor consensus beta captures how Excititor feeds power the Excititor consensus beta (sample payload in consensus JSON).
- Added observability guide describing the evidence metrics emitted by
EXCITITOR-AIAI-31-003(request counters, statement histogram, signature status, guard violations) so Ops/Lens can alert on misuse. - README now points policy/UI teams to the upcoming consensus integration work.
- DSSE packaging for consensus bundles and Export Center hooks are documented in the beta release note; operators mirroring Excititor exports must verify detached JWS artefacts (
bundle.json.jws) alongside each bundle. - Follow-ups called out in the release note (Policy weighting knobs
POLICY-ENGINE-30-101, CLI verbCLI-VEX-30-002) remain in-flight and are tracked in/docs/implplan/SPRINT_200_documentation_process.md.
Release references
- Consensus beta payload reference: docs/vex/consensus-json.md
- Export Center offline packaging: docs/modules/export-center/devportal-offline.md
- Historical release log: docs/implplan/archived/updates/
Responsibilities
- Fetch OpenVEX/CSAF/CycloneDX statements via restart-only connectors.
- Store immutable VEX observations with full provenance.
- Publish linksets and events that drive policy suppression decisions.
- Provide deterministic exports for Offline Kit and downstream tooling.
Key components
StellaOps.Excititor.WebServicescheduler/API host.- Connector libraries under
StellaOps.Excititor.Connector.*. - Normalization helpers and exporters in
StellaOps.Excititor.*.
Integrations & dependencies
- Policy Engine for evidence queries.
- UI/CLI for conflict visibility and explanation.
- Notify for VEX-driven alerts.
Operational notes
- PostgreSQL (schema
vex) for observation storage and job metadata. - Offline kit packaging aligned with Concelier merges.
- Connector-specific runbooks (see
docs/modules/concelier/operations/connectors). - Provider control plane inventory and readiness notes:
operations/provider-control-plane.md - Ubuntu CSAF provenance knobs:
operations/ubuntu-csaf.mdcaptures TrustWeight/Tier, cosign, and fingerprint configuration for the sprint 120 enrichment.
Backlog references
- DOCS-LNM-22-006 / DOCS-LNM-22-007 (shared with Concelier).
- CLI-EXC-25-001..002 follow-up for CLI parity.
Epic alignment
- Epic 1 – AOC enforcement: maintain immutable VEX observations, provenance, and AOC verifier coverage.
- Epic 7 – VEX Consensus Lens: supply trustworthy raw inputs, trust metadata, and consensus hooks for the lens computations.
- Epic 8 – Advisory AI: expose citation-ready VEX payloads for the advisory assistant pipeline.
Implementation Status
Objectives
- Maintain deterministic behaviour and offline parity across releases
- Keep documentation, telemetry, and runbooks aligned with the latest sprint outcomes
Key Milestones
- Epic 1 – AOC enforcement: enforce immutable VEX observation schema, provenance capture, and guardrails
- Epic 7 – VEX Consensus Lens: provide lens-ready metadata (issuer trust, temporal scoping) and consensus APIs
- Epic 8 – Advisory AI: guarantee citation-ready payloads and normalized context for AI summaries/explainers
Recent Delivery Status
- Chunk API documentation remains blocked until CI is green and a pinned OpenAPI spec with deterministic samples are available
- Link-Not-Merge readiness and consensus beta completed with DSSE packaging guidance
- Observability guide additions and policy/CLI follow-ups tracked in sprint files
Workstreams
- Backlog grooming: reconcile open stories with module roadmap
- Implementation: collaborate with service owners to land feature work
- Validation: extend tests/fixtures to preserve determinism and provenance requirements
Coordination
- Review ./AGENTS.md before picking up new work
- Sync with cross-cutting teams noted in sprint files
- Update plan whenever scope, dependencies, or guardrails change