StellaOps Concelier

Concelier is the StellaOps advisory aggregation service. It fetches vulnerability advisories from a wide catalog of upstream sources and converts every signed advisory into immutable, provenance-tagged observations plus correlation linksets under the Aggregation-Only Contract (AOC) — without making any precedence, merge, or promotion decision. Downstream, the Policy Engine and Export Center consume that evidence.

Audience: operators wiring advisory connectors and offline mirrors, and integrators consuming Concelier exports or the advisory-chunk API.

Catalog at a glance (source of record is the code, not this README — see the references below):

• 71 advisory source definitions — the SourceDefinitions.All array in StellaOps.Concelier.Core/Sources/SourceDefinitions.cs.
• 39 built-in advisory pipeline registrations — source:<id>:fetch entries in JobRegistrationExtensions.cs, each registering a fetch/parse/map trio. A pipeline is mounted at runtime only when its connector assembly is loadable; AddJobIfMissing skips registrations whose JobType resolves to null.
• Beyond the source:* pipelines, the host also registers the export:json, export:trivy-db, federation:bundle:export, and (feature-gated) merge:reconcile jobs.

The two counts above are reconciled against source. connectors.md still quotes 79; the code-of-record catalog now holds 74.

Operator references

• Full advisory inventory and runnable-vs-catalog truth: connectors.md
• Live StellaOps Mirror connector counts, failure split, and seed-export plan: connector-aggregation-state.md
• Dated local setup connector sync snapshot with downloaded-item counts: connector-snapshot-2026-06-03.md
• Ingested advisory catalog and package-lens API semantics: architecture.md
• Unified issue projection skeleton for advisory, distro, VEX, and future finding evidence: unified-issue-projection.md
• Stored credential and endpoint-override entry paths: operations/source-credentials.md
• Per-connector runbooks: operations/connectors/

Responsibilities

• Fetch and normalise vulnerability advisories via restart-time connectors.
• Persist observations and correlation linksets without precedence decisions.
• Emit deterministic exports (JSON, Trivy DB) for downstream policy evaluation.
• Coordinate offline/air-gap updates via Offline Kit bundles.
• Serve paragraph-anchored advisory chunks for Advisory AI consumers without breaking the Aggregation-Only Contract.
• Do not emit promotion PASS/FAIL decisions; promotion gate decisions are owned by Policy Engine.

Key components

• StellaOps.Concelier.WebService orchestration host.
• Connector libraries under StellaOps.Concelier.Connector.*.
• Exporter packages (StellaOps.Concelier.Exporter.*).

Recent updates

• 2026-04-25: Mirror runtime rate limiting now fails closed for sources:mirrorServer:rateLimits:forEnvironment because Concelier.WebService has no durable fail-closed distributed limiter binding. Explicit instance-only mirror limits remain supported for local/test/single-instance throttling.
• 2026-04-24: Reusable Concelier core service registrations no longer provide silent process-local runtime fallbacks. Jobs, orchestrator state, affected-symbol state, observation/linkset sinks, coverage metrics, and advisory field-change notifications now fail closed unless durable implementations are registered first; explicit in-memory helpers are limited to local/test harnesses.
• 2026-04-24: Shared source connector registration now follows the same fail-closed contract. AddSourceCommon no longer supplies an in-memory IDocumentStore default; local/test harnesses must opt in through AddSourceCommonForTesting when they need process-local document storage.
• 2025-11-07: Paragraph-anchored /advisories/{advisoryKey}/chunks endpoint shipped for Advisory AI paragraph retrieval. Details and rollout notes live in 2025-11-07-concelier-advisory-chunks.md.

Integrations & dependencies

• PostgreSQL (schema vuln) for canonical observations and schedules.
• Policy Engine / Export Center / CLI for evidence consumption.
• Notify and UI for advisory deltas.

Operational notes

• Connector runbooks in ./operations/connectors/.
• Mirror operations for Offline Kit parity.
• Grafana dashboards for connector health.
• Authority toggle rollout (2025-10-22 update). Follow the phased table and audit checklist in ../../CONCELIER_CLI_QUICKSTART.md when enabling authority.enabled/authority.allowAnonymousFallback, and cross-check the refreshed ./operations/authority-audit-runbook.md before enforcement.

Related resources

• ./operations/conflict-resolution.md
• ./operations/mirror.md
• ./operations/authority-audit-runbook.md
• …/…/CONCELIER_CLI_QUICKSTART.md (authority integration timeline & smoke tests)

Backlog references

• Connector-specific TODOs in src/Concelier/**/TASKS.md.

Epic alignment

• Epic 1 – AOC enforcement: uphold raw observation invariants, provenance requirements, linkset-only enrichment, and AOC verifier guardrails across every connector.
• Epic 10 – Export Center: expose deterministic advisory exports and metadata required by JSON/Trivy/mirror bundles.

Implementation Status

Delivery Phases:

• Phase 1 (Guardrails & schema) – PostgreSQL validators, AocWriteGuard (namespace StellaOps.Aoc) interceptor, deterministic linkset builders operational
• Phase 2 (API & observability) – Ingestion/verification endpoints with Authority scopes, telemetry, Offline Kit packaging
• Phase 3 (Experience polish) – CLI/Console affordances, Export Center hand-off metadata, CI enforcement

Acceptance Criteria:

• PostgreSQL validators and runtime guards reject forbidden fields and missing provenance with ERR_AOC_00x codes
• Linksets and supersedes chains deterministic; identical payloads yield byte-identical documents
• CLI stella aoc verify exits non-zero on violations, zero on clean datasets
• Export Center consumes advisory datasets without legacy normalized fields
• CI fails on lint violations or guard test regressions

Key Risks & Mitigations:

• Collector drift: guard middleware + CI lint + schema validation; RFC required for linkset changes
• Migration complexity: staged cutover with backup copies, temporary views for Policy Engine parity
• Performance overhead: guard remains O(number of keys), index review for insert latency targets
• Tenancy leakage: tenant required in schema, Authority claims enforced, observability alerts

Recent Milestones:

• Sprint 110 attestation chain validated, evidence bundle tests green
• Link-Not-Merge cache and console consumption docs frozen
• Observation events transport reviewed, NATS/air-gap guidance updated
• Testing-only legacy AddInMemoryStorage() compatibility moved into explicit web-service test harnesses, and runtime observation-event defaults no longer imply an undocumented "inmemory" transport
• Concelier core runtime service defaults now fail closed instead of silently resolving null/no-op/in-memory stores; in-memory job, orchestrator, signal, and risk stores require explicit ForTesting helper registration.
• Feedser signal attachers now require durable/replayable event transport in runtime wiring; AddTimelineSignalEventEmitter uses the shared timeline eventing store, while AddSignalAttachersForTesting is the only process-local event bus path.
• Connector-common source document storage now fails closed in reusable runtime wiring; explicit test/local harnesses use AddSourceCommonForTesting.