Operations

Release Notes

Operator surface for authoring release notes that accompany each published world-model version. Release notes are not auxiliary marketing copy — they are the restatement mechanism (per ADR-026). When a subsequent version corrects a prior rule, changes a configuration value, or restructures an action, the release notes carry the correction record; prior World Model Cards remain authoritative for their own version and reconcile through the intervening release notes.

Scope

Release-note authoring UI — structured editor for the narrative and the three-category restatement content
Three-category restatement — restatement extends to three categories: configuration restatement (configuration block value changed), rule restatement (rule natural-language form changed or rule retired), and action restatement (action registry entry added, retired, or aggregation mode shifted)
Correction record — explicit linkage from each correction to the rule it corrects and the prior version it restates (per ReleaseNotesCorrection)
Operator-authored content — the operator authors the release-notes narrative and restatement content from a template or blank draft before the parent version is published
No independent lifecycle — release notes follow the publishing state of the parent WorldModel version (see Lifecycle is the version’s, not the notes’)

Governance invariants

Release notes are first-class. They are an authority artifact of the world model, not an auxiliary document per ADR-026.
Corrections live in the correcting version’s release notes. There is no separate restatement protocol, no retroactive card mutation, and no automatic recertification — these absences are deliberate.
Cross-version comparability flows through the world_model_version field on the decision response and the World Model Card per ADR-082 D2. Readers comparing cards across versions reconcile differences by reading the intervening release notes.
Recertification is subject-driven. A downstream subject may choose to evaluate against a new version after reading its release notes; that choice is not automatic.

Lifecycle is the version’s, not the notes’

Release notes have no independent draft / published state machine. Their publishing state follows the parent WorldModel version’s lifecycle:

While the parent version is in draft state, the release notes are mutable — operators create and revise the content.
At version publication, the release notes are locked in alongside the version mint and surfaced on the public WorldModelCard. Edits are rejected from that point forward.

Mutability is enforced at the use-case layer (and by a trigger at the schema layer; Postgres CHECK constraints can’t reference rows in other tables, so the parent-version-state check has to be a trigger); edits are rejected when the parent version is published. Concurrent operator actions on the same release-notes row are serialized at the row level — one wins; the other receives a clean conflict response.

Review-gating lives at the rule-set or publication-trigger gate, not at a release-notes-specific review layer. Peer review of accumulated rule changes happens at the reviewer surface; operator sign-off on the publication decision happens at the publication confirmation step. Release notes are an artifact of that process, not a separately review-gated artifact.

Audit trail

Every operator authoring action on this surface appends a row to the WorldAuthoringAudit record family. The discriminators introduced for release notes are:

target_type = release_notes, action = created — operator creates the initial release-notes draft (HTTP POST)
target_type = release_notes, action = revised — operator edits the release-notes draft (HTTP PATCH; the audit vocabulary names the workflow action, the HTTP verb names the wire semantics — both flow through the same use-case path)

The publication action that locks the release notes in is audited under (target_type = world_model_version, action = version_published) per the publication audit trail.

The audit row is appended alongside the entity-state mutation in the same transaction; it is never appended outside the originating use-case transaction.

UI surfaces

The release-notes editor is the authoring surface for the narrative and restatement content that ships with the staged publication. It surfaces:

Narrative editor — operator authors the narrative content from a template or blank draft
Three-category restatement editor — structured fields per restatement category: configuration restatement (configuration value change), rule restatement (rule natural-language form change or retirement), action restatement (action-registry change). Each entry links to the rule, configuration value, or action it restates.
Lock indicator — when the parent version is published, the editor reads as locked-in; historical release notes for prior versions are inspect-only

Every UI surface has a corresponding API endpoint per the API/UI parity rule — the UI is a thin client over the same routes.

API surfaces

The HTTP routes the UI consumes as an API client (per the parity contract) include:

POST /worlds/:world_id/release-notes — create initial release-notes draft for the in-flight version (idempotent on (operator_id, correlation_id))
PATCH /worlds/:world_id/release-notes/:id — operator edits the draft (idempotent on (operator_id, correlation_id)); rejected with a 409 when the parent version is published
GET /worlds/:world_id/release-notes/:id — read release notes (current and historical)
GET /worlds/:world_id/release-notes/:id/corrections — list of structured correction records

Auth middleware sets app.user_id via SET LOCAL per ADR-041 D4; RLS predicates compare against app.user_id per ADR-039.

What’s next

Architecture — the next cluster in the spine. The three-context library topology + Clean Architecture inside each context; the operations-app surfaces this cluster describes ride atop the layout introduced there.