Skip to content
Spectral Codex
GitHub
Operations

Version Publication

Operator-driven world-model version-publication workflow: bundle accumulated enshrined rules, mint the EvaluationAuthorityRef, auto-generate the WorldModelCard, and coordinate publication. The world-model version is the unit of authority (per ADR-026); publication is how a version becomes authoritative.

Scope

Section titled “Scope”
  • Version bundling — collect enshrined rules since the last published version into a publication draft
  • EvaluationAuthorityRef minting — the opaque reference (carried between worlds and platform) that links system cards to the authoritative world-model version (per ADR-030)
  • WorldModelCard auto-generation — published version emits worldmodel.version.published; the auto-generation pipeline reacts to the event and produces the card from rule corpus + provenance + coverage metrics
  • Publication coordination — operator review of the draft, final sign-off, release flow
  • Alpha-preview footer — the rendered WorldModelCard carries the footer

Authority invariants

Section titled “Authority invariants”
  • The world-model version is the unit of authority (ADR-026). A published version is authoritative for that version; prior versions are not retroactively invalidated by subsequent corrections.
  • EvaluationAuthorityRef carries authority + version metadata only (ADR-030). Downstream consumers (system cards, audit paths) do not unwrap it — they dereference through public APIs. The wire shape follows the producer-typed-emit + consumer-side-ACL pattern per ADR-065 D2 + D4.
  • System card linkage between worlds and platform flows via event-driven projection per ADR-065 D4 — worlds publishes world_model_card_published; platform projects into a platform-local SystemCardSnapshot and renders its AgentPerformanceCard from the embedded snapshot. There is no SystemCard Protocol in spectral.core spanning worlds and platform; each context owns its own card type and renders independently. See system-card for the full Card Linkage at Render Time pattern.

Governance invariants

Section titled “Governance invariants”
  • Publication is operator-triggered, not enshrinement-triggered. Rules enshrine one at a time through the reviewer surface and accumulate in the world-model’s working state; an operator decides when to cut a new version per evolution-loop / Versioning and Release.
  • Concurrent operator actions on the same publication are serialized at the row level — one wins; the other receives a clean conflict response. Mirrors the row-level serialization on ApprovalDecision and the world-model authoring surfaces.
  • The publish-version mutate API is idempotent on (operator_id, correlation_id). A re-issued request with the same correlation ID returns the original outcome; the dedup anchor is recorded on the corresponding world_authoring_audit row.
  • Prior versions are non-destructively retained. Historical WorldModelCards remain valid content after a new version is published per ADR-026; no retroactive card mutation, no automatic recertification.
  • Version is metadata, never a partition boundary. Per ADR-030, downstream consumers do not reset state on version publication; dashboards render version markers as overlays on continuous data, not as partition boundaries.

Audit trail

Section titled “Audit trail”

Every operator publication action appends a row to the WorldAuthoringAudit record family (per domain-model — WorldAuthoringAudit). The discriminator introduced for publication is:

  • target_type = world_model_version, action = version_published — operator publishes a new world-model version

The audit row is appended alongside the entity-state mutation in the same transaction; it is never appended outside the originating use-case transaction. The (operator_id, target_type, target_id, action, occurred_at, correlation_id) row remains queryable for the full active window per data-retention — operator-action records.

WorldAuthoringAudit is not agent memory (per the records-vs-memory framing). It is operator-scoped (app.user_id) with no workspace RLS, distinct from ApprovalDecision (same identity domain, different action surface — enshrinement-gate decision vs authoring) and from operations_agent_approval (platform-side, Ops-Agent call-time approval). Three operator-action audit families remain stable across the worlds / platform split.

Publication call shape

Section titled “Publication call shape”

The publication call shares the call-flow shape with enshrinement — apps/operations consumes spectral.worlds via HTTP through apps/api per ADR-047. Within Python the operator invokes the use case handler worlds.application.publication.PublishWorldModelVersion directly from apps/api/operator/publications per ADR-070 Tier 1 (single-Python-consumer call flow consumed directly by apps/* per validator rule 7 per ADR-065). The handler is minted in spectral.worlds.application.publication.

The publication transaction is atomic across four artifact mints: (1) the new WorldModel version, (2) the EvaluationAuthorityRef, (3) the WorldModelCard via mint_world_model_card_at_publication, and (4) the outbox row for worlds.world_model_card.published (typed payload at spectral.worlds.contracts.events.world_model_card_published per ADR-065 D2). After commit, the World Agent emits worldmodel.version.published per ADR-030 — signal-shaped; spectral.platform does not subscribe to it for state changes. evaluation_authority_ref stamping happens at scan-time inside OnScanCompletedHandler from the verdict result, independent of this event. The system-card projection pipeline consumes the sibling worlds.world_model_card.published instead — spectral.platform’s system-card projection handler materializes a SystemCardSnapshot keyed by evaluation_authority_ref per ADR-065 D2 + D4.

UI surfaces

Section titled “UI surfaces”

The operator UI surfaces this workflow as three panels:

  1. Publication-draft review — list of enshrined rules accumulated since the last published version; operator-side filter / scan / inspection of the draft set
  2. Release-notes editor — see Release notes; the operator-authored narrative plus correction-record content that ships with the new version
  3. Publication confirmation — final sign-off; operator triggers publish-version with a correlation_id supplied by the UI for idempotency

Every UI surface has a corresponding API endpoint per the dual-occupant API/UI parity rule; the Operations Agent consumes the same endpoints to draft release notes and trigger publication.

API surfaces

Section titled “API surfaces”

The HTTP routes consumed by both the UI and the Operations Agent (per the parity contract) include:

  • POST /worlds/:world_id/publications — operator triggers a new world-model-version publication (idempotent on (operator_id, correlation_id)); request includes the in-flight release-notes reference; response carries the minted world_version and evaluation_authority_ref
  • GET /worlds/:world_id/publications/:id — publication status (draft, in-progress, completed, failed)
  • GET /worlds/:world_id/versions — list of published versions (newest first); each entry links to its WorldModelCard and accompanying release notes

Auth middleware sets app.user_id via SET LOCAL per ADR-041 D4; RLS predicates compare against app.user_id per ADR-039. The apps/operations deployable consumes these routes via HTTP per ADR-047 and never imports spectral.worlds internals; the architecture validator at STRICT=True enforces this.

Section titled “Related reading”