Skip to main content
Version: v5.8.0

Change record

Included from Basic tier

A change record is one approved change with many pieces of work under it: the upgrade four teams run over a weekend, the release that took five attempts and three by-hand acts. It holds every run under the change — failed attempts and retries included, nested and triggered runs inherited — and every break-glass record taken on it, so "what happened as a result of this change" is one page. Chains stay the unit of a cascade underneath: a retry is still a new chain, now on the same record.

A record is owned by a path — the organisation root / or a project (/projects/<code>) — and names its scope, the nodes the change may touch. A project's record never reaches another project; a root record may span projects.

Served by ChangeRecordService on /api/v2 (opschain docs api-v2) and opschain changes create|list|show|approve|link|unlink|close|cancel|export (opschain docs cli/changes). Records live in the server's store — PostgreSQL or SQLite — and, in the local lane, in the home's store. The record itself is base; with packs:change-governance on the PostgreSQL store an approval policy may hold its approval (below, "Approval under a policy"), and with integrations:jira-service-management on the PostgreSQL store a JSM connection's change mapping links a record to its ITSM change (below, "Linked to an ITSM change").

The v2 OpenAPI document declares this resource's schemas (ChangeRecord, ChangeRecordApproval, ChangeRecordAuthorisations, ChangeRecordExternalApproval, ChangeRecordPendingClose, ChangeRecordRun, ChangeRecordStoryEntry); the resource-field coverage gate holds this page to them.

Attributes (ChangeRecord)​

Timestamps are RFC3339 in UTC.

FieldTypeMeaning
idstringThe record's id (UUIDv7) — the handle runs, events and exports carry.
owner_pathstringThe record's home: / or /projects/<code>. Visibility and authority come from grants on this path.
codestringA short human code, unique under the owner — generated as CHG-<year>-<sequence> per owner when none is given, at most 64 letters, digits, dots, dashes or underscores, never a UUID. Codes are unique per owner, so a project and the root can both hold CHG-2026-001: a reference that matches more than one record you can read is refused by name — narrow it with the owner (owner_path on the request, --owner on the CLI) or name the record by its id. A code without an owner is matched across every owner, at most 1000 records, past which it is refused by name ("the code names too many change records to resolve; give the owner … or the id").
titlestringWhat the change is. Required, at most 200 bytes.
descriptionstringWhy, in free text (at most 8000 bytes).
classstringstandard, normal (the default) or emergency — the governance block's vocabulary.
scopearrayThe nodes the change may touch, every one under owner_path: a node path (exactly that node), or a node path followed by /** (that node and everything under it). At least one, at most 64; no other wildcard.
window_fromtimestampThe planned start, when the record has a window. The window bounds the scope join: a record with a window captures runs by scope only from window_from up to window_to; an explicit --change or a link is never window-bound. "In progress" reads it too.
window_totimestampThe planned end; after window_from. A record still approved a minute past it raises warn:change_record:window_elapsed once (below, "Past its window").
maintenance_window_idstringA maintenance window the record owns, named at creation (PostgreSQL store): its span becomes the record's window when the request gives none, and the window's declared work joins the record through the window (below, "How runs join").
owner_principalstringThe principal id the change is assigned to — the creator unless another is named. A named one must be a principal id (a UUID); a username or an email is refused by name.
referencesarrayTyped external references (system, record_type, id, url, relationship) — the change-governance vocabulary, record_type change for an ITSM change; at most 16.
statestringpending → approved → closed (below).
verdictstringSet at close: completed, completed_with_incidents, rolled_back, abandoned (the verdict for cancelled work) or cancelled.
close_notestringWhy the record closed (required at close, at most 4000 bytes).
created_bystringThe creating principal's id.
created_attimestampWhen the record was opened.
approved_bystringThe approving principal's id; empty while pending.
approved_attimestampWhen it was approved.
closed_bystringThe closing principal's id; empty while open.
closed_attimestampWhen it was closed.
run_countintRead-time (GetChangeRecord and the story): the runs under the record, counted to 1000 from the runs' change-record index without reading a run.
run_countintRead-time (GetChangeRecord, ListChangeRecords and the story): every run under the record — changes and workflow runs, the ones the caller cannot read included (the story withholds those by name). The list counts its whole page in one grouped read keyed by the page's record ids.
active_run_countintRead-time: the runs under the record still pending, queued, running or waiting.
in_progressboolRead-time: the record is approved, has a run under it, and now is inside its window (or it has none). "In progress" is a fact the record shows, never a state.
approvalChangeRecordApprovalThe record's latest approval request under an approval policy (the change-governance pack on the PostgreSQL store): set on GetChangeRecord, ListChangeRecords (the page's requests in one read keyed by its record ids, so a record awaiting approval reads as such whoever is looking), the story and a transition that opened a checklist; unset when no policy ever held the record, and always unset on the SQLite store and in the local lane.
external_approvalChangeRecordExternalApprovalThe ITSM change the record is linked to and the ITSM's half of its approval (below, "Linked to an ITSM change"); unset for a record no ITSM change opened or linked.
heldboolTrue while the ITSM's approval of this approved record is withdrawn (below, "Held: an approval the ITSM withdraws"). The record stays approved — a hold is not a state — but no new run joins it; the runs already under it continue.
pending_closeChangeRecordPendingCloseAn ITSM close the record could not take while a run under it was still running, kept to apply when the last such run finishes (below, "A close deferred until the work finishes"); unset when none is pending.
authorisationsChangeRecordAuthorisationsWhat the caller may do to this record (below), on every record the service returns — the list included.

ChangeRecordAuthorisations​

The caller's standing on one record, decided from its compiled grants on the record's owner path with no store read. These are rights, not the record's state: a verb the state refuses (approving a closed record) is refused by name whatever the flag says, and the server still gates every verb.

FieldTypeMeaning
updateboolUpdate on <owner>/change_records: link and unlink runs, and request the approval of a record an approval policy holds.
approveboolThe approve right: update on <owner>/change_records_approve, and the caller is a human — what approving the record at the baseline tier (TransitionChangeRecord) needs. Requesting the approval of a record an approval policy holds rides update; approving that record's checklist also needs the reviewer to be an approver on the checklist's lines (the approver matching of opschain approvals approve), which this flag does not decide.
closeboolUpdate on <owner>/change_records, and the caller is a human: close or cancel the record.

An agent, a service account or a step's credential reads approve and close false whatever its grants (the human verbs, "Who may" below). The local lane's one principal and the SQLite store's single-node server hold every verb, and the block says so.

ChangeRecordApproval​

FieldTypeMeaning
checklist_idstringThe checklist's id.
request_idstringThe approval request's id — the handle the reviewer verbs take (`opschain approvals show
statusstringpending (awaiting approval), released (it approved the record), rejected, expired or withdrawn (its requester took it back, or a policy change replaced it).
policiesarrayThe matched policies' names.
finalise_reasonstringWhy it was rejected, expired or withdrawn, when it was.
requested_attimestampWhen the approval was requested.
replaced_request_idstringThe request this one replaced because its approval policy changed since it was raised — set only on the answer of the changes approve that replaced it.

ChangeRecordExternalApproval​

FieldTypeMeaning
systemstringThe ITSM: jsm.
connectionstringThe JSM connection the change arrives through.
external_idstringThe ITSM's change id, e.g. CHG-12 — also on references with record_type change.
urlstringThe change's page in the ITSM. The record links to it; it never copies the CAB's decision.
statusstringThe ITSM's status of the change as last applied.
mapped_statestringThe record state the connection's mapping projects status onto: pending, approved or closed.
approvedboolWhether the ITSM has approved the change — its half of the record's approval.
last_event_idstringThe ITSM event id of the last inbound move applied.
last_moved_attimestampThe ITSM's own timestamp of that move; an inbound move stamped earlier is recorded and never applied.
notes_pendingintGetChangeRecord and the story (never the list): outbound work notes not yet delivered to the ITSM (counted to 1000).
delivery_warningstringGetChangeRecord and the story: why the latest undelivered note failed, when the ITSM is unreachable (bounded; never credential material). A warning only — runs never wait on the ITSM.
hold_reasonstringWhile the record is held: the named reason a run is refused, e.g. approval withdrawn by jsm (CHG-12 moved to "Awaiting CAB").
withdrawn_event_idstringWhile the record is held: the ITSM event id that withdrew the approval.
withdrawn_attimestampWhile the record is held: the ITSM's own timestamp of that move.

ChangeRecordPendingClose​

FieldTypeMeaning
verdictstringThe verdict the connection's mapping gives the ITSM's closing status; the record closes with it.
statusstringThe ITSM's closing status.
event_idstringThe ITSM event id of the close.
itsm_attimestampThe ITSM's own timestamp of the close.
deferred_attimestampWhen the close was deferred.
active_runsintThe runs under the record still running when the close arrived.

States​

Three states, deliberately:

  • pending — every state before approval. A pending record never captures a run, so planning a change never swallows unrelated work, and nothing — no run, no break-glass record — joins it.
  • approved — the only state in which runs join. In the baseline tier a holder of the approve grant (below) moves the record here, audited; under an approval policy, the checklist's quorum does; for a record linked to an ITSM change, the ITSM's approval does — together with the checklist when a policy holds the record.
  • closed — with a verdict and a note. A record that was never approved closes only as cancelled. Close is refused by name while a run under the record is still running ("a change record cannot close while a run under it is still running"): cancel the run and close with abandoned, or wait for it. (An ITSM's close in that case is kept as the record's pending close and applies when the work finishes — below.)

How runs join​

  1. Explicitly — runs create … --change <id|code>, runs retry … --change …, change_record_id on the v2 create and retry requests. The record must be approved, owned by the root or the target's project, and its scope must hold the target (a workflow run's effective target, below); an explicit record always wins over the scope join and is never bound by the record's window.
  2. By scope — a run created with no record named joins the one approved record, owned by the root or the target's project, whose scope holds the target and whose window, when it declares one, holds the moment the run is created (from window_from up to, not including, window_to; a record with no window captures whenever it is approved), and the run says so (change_association: scope). A scheduled run created before the window opens or after it has elapsed stays off the record. When two approved records hold the target, at any level, the run is refused by name ("… lies inside the scope of more than one approved change record (CHG-…, CHG-…); name the record with --change") — the creator must say which. The candidates are read from the approved records' index (at most 1000 under the root and the project; more refuses the implicit join by name) and matched by a compiled path test.
  3. Inherited — a nested run (a workflow's change or workflow step) always takes its parent's record, and only it: a nested run never joins by scope on its own. When the parent's record is no longer approved by the time the step is reached (it was closed while the workflow ran), the nested run is refused by name — "this nested run inherits change record CHG-… from its parent, and CHG-… is closed: runs join a change record only while it is approved" — and the step fails with that message. A triggered run takes the triggering event's record, and a retry the retried run's, while that record is approved; when it is closed the scope join decides instead.
  4. Linked — opschain changes link <record> <run> attaches a run that was created without its record (a forgotten --change); the record must be approved, its scope must hold the run's target (a workflow run's effective target), and the run must be under no other record. A link is never window-bound. The nested runs the run has already spawned, at every depth (a workflow's changes and child workflow runs, including those of earlier automatic attempts), join with it as inherited — exactly as the nested runs it spawns after the link do — each with its own …:linked row naming the run the link was made on (via_run_id); a nested run under another record refuses the whole link by name ("nested run … is under another change record …; unlink it there first"), and more than 1000 nested runs refuses it by name too. opschain changes unlink <record> <run> --reason … detaches a mis-joined run while the record is open, and its nested runs under the same record leave with it; the ledger keeps both rows.
  5. Through a maintenance window — a record that owns a maintenance window (maintenance_window_id, PostgreSQL store) takes the window's declared work: the runs the window starts at its scheduled start, and the runs and retries admitted while it is active because they match the allow list of every window covering the target (the gate's rule). Such a run joins the one approved record owning any of those covering windows (change_association: window) whatever the record's scope or declared span — the window's work is the record's — provided the record is owned by the root or the run's project; with nested windows, an outer window's owner takes the work an inner window nobody owns also admits. A run the window starts at its scheduled start joins that window's owner only. A run that overrides the window, or that no window admitted, is not the window's work and joins by scope only; an explicit --change and inheritance still come first. A window whose owning record is pending or closed captures nothing (the scope join decides); more than one approved record owning the covering windows — one window or several nested ones — refuses the run by name ("the maintenance windows covering … are owned by more than one approved change record …"), which for a run the window starts lands as the window's warn:maintenance:declared_run_failed.

A run's creation and a record's close fence each other: creating a run under a record holds the record while it checks it is approved, and close holds it while it counts the runs still running, so whichever commits first decides — a close that comes second is refused by name while the new run runs, and a run that comes second is refused by name because the record is closed.

A workflow run's effective target. A workflow run's own target is its project, but the scope tests (the scope join, --change and changes link) read its effective target: when every change step of the workflow — nested workflows resolved, fan-out templates and error handlers included — targets one and the same node, that node; when the steps target different nodes, when a step's target can only be known once the step is reached (it reads a step's outputs, a fan-out element, the estate or repository content, or a secret input), or when the workflow has no change step, the project path as before; so does a shared node outside the run's own project. A run's effective target is bounded to its own project; cross-project capture would be a dated ruling, not a side effect. Targets read from the run's inputs (for example target: ${{ inputs.target }}) resolve at creation, and a nested workflow's steps resolve through the with: bindings it is called with, and its version is the one the run's creation resolves (the pinned one, or the latest published as of then); its run resolves the version again when the step is reached, so a version published in between changes what runs, not what the run joined. A target read from a secret-typed input is never resolved at creation. So a record scoped /projects/hosted_ops/environments/prod/** holds a hosted-release run whose steps all target /projects/hosted_ops/environments/prod/assets/hosted, while a workflow that touches prod and stage keeps the project path and is not captured. The effective target is frozen with the run at creation, so a retry and a later link test the same node; the run's target_path, its node for authorisation, stays the project.

A run under a record carries change_record_id and change_association (explicit, scope, inherited, linked, window) on its v2 Change / WorkflowRun view, and every event the run writes carries change_record_id on the chain spine beside correlation_id.

Approval under a policy​

With packs:change-governance on the PostgreSQL store, an approval policy whose subjects include change_record and whose path_pattern reaches the record's scope holds the record's move to approved (opschain docs change-governance, "Change records"):

  1. opschain changes approve <record> / TransitionChangeRecord opens the policy's checklist and answers the record still pending with its approval (status pending); its ledger gains audit:change_record:approval_requested. opschain changes show reads Approval: awaiting approval (checklist <id>). Requesting needs update on <owner>/change_records (not the approve right) and a human; asking again answers the open request — unless a policy holding the record changed since the request was raised (updated, disabled or deleted, or a new policy now holds it), when the open request is withdrawn and a fresh one raised under the current version, its answer naming the old one in replaced_request_id. Until a reviewer decides, the requester may withdraw the request (opschain approvals withdraw <id> --reason): not a decision — the self-approval exclusion does not apply — so a sole approver with self-approval off is never stuck; the record stays pending with audit:change_record:approval_withdrawn, written in the transaction that withdraws the checklist.
  2. The request is a change_record row in the approvers' inbox (opschain approvals list) with the record's code, title, owner and scope. A reviewer approves or rejects it with opschain approvals approve|reject <id> — a human holding update on <owner>/change_records_approve and named on the checklist's line; the requester and the record's owner_principal are excluded on a self_approval: false line.
  3. The quorum approves the record in the transaction that releases the checklist: approved_by is the completing reviewer's principal id and the audit:change_record:approved row names the checklist_id. A rejection or an expired quorum leaves the record pending with audit:change_record:approval_rejected, written in the transaction that finalises the checklist — a rejection whose ledger row cannot be written is refused and leaves the checklist open, so the story never shows a rejected request without its row; moving it to approved again opens a fresh checklist.

A policy with require_step_up demands a stepped-up session (change_governance.execute) of the request in step 1: a session that has not elevated is refused (failed_precondition, "change_governance.execute requires a stepped-up session …") and no checklist opens.

A record no policy reaches approves at the baseline tier. A policy carrying require_change_record refuses runs on its path that join no approved record — the record stays the way runs prove they belong to an approved change, and run-level policies still gate each run. A nested run a workflow spawns on such a path is checked again when its step is reached and refused by name with the policy named, even when the workflow was created before the policy existed. The administrators' end-to-end run seam (POST /admin/e2e/runs) crosses the governance funnel: the change-record join, the approval policies that hold runs (a held seam run waits behind its checklist), require_change_record (422 by name) and a policy's require_step_up, decided on the caller's own session (403 naming change_governance.execute for a session that has not stepped up, and for a credential that resolves to no session). It is not the public create path: it skips the maintenance-window stamp, the Ruby-lane entitlement, agent governance, the retry and fan-out freeze and pack pins, and its runs are created by the seam's own admin creator.

Linked to an ITSM change​

A JSM connection carrying a change mapping (opschain docs integrations-jsm, "The ITSM connector contract") links records to the ITSM's changes over the connection's signed inbound webhook:

  • change.created opens a pending record under the mapping's owner — title, description, class, window and scope read from the change through the mapping — with the change on references (record_type change) and on external_approval. An open record under the owner that already references the change on the same connection (system jsm, the change's id and page) is linked instead — only when its scope sits inside the change's mapped scope and its class is the change's; otherwise the link is refused by name and the record is left as it was. created_by is the inbound connection's service account.
  • change.state moves the record by the mapping. A status that stays within pending is a note on the ledger and changes nothing. A status mapped to approved sets external_approval.approved, and the record moves to approved only when its local half also holds — both must hold: with no approval policy reaching it, at once; under a policy, when the policy's checklist has released — in whichever order the two arrive. A status mapped to closed closes the record with the mapped verdict — while a run under an approved record still runs, the close is kept as its pending close (below) — and a record that was never approved closes only as cancelled. A status mapped to pending on an approved record the ITSM had approved holds the record (below); a status mapped to approved on a held record releases it.
  • change.window sets or moves the window.

Every inbound move is a ledger row naming the ITSM's event id and its own timestamp (audit:change_record:itsm_linked, …:itsm_moved); a move stamped earlier than the last one applied is recorded (…:itsm_stale) and not applied; a refusal (a status the mapping does not declare, a scope value it does not map, a never-approved record closed with a verdict other than cancelled) is a warn:change_record:inbound_refused row and is named on the delivery's 202 answer; a failure that is not a refusal answers 503 so the ITSM retries. The inbound lane acts as the inbound connection's named service account — never an ambient admin — decided on the record's owner: update on <owner>/change_records to open, link, move the window and close it, and update on <owner>/change_records_approve to carry the ITSM's approval (404-on-deny, recorded with the missing right). The service account carries the ITSM's decision, it never makes one; approved_by and closed_by name its principal id.

A linked record is approved by the ITSM: changes approve is refused by name when no approval policy reaches it; under a policy it requests the policy's approval, and once the checklist has released the record waits for the ITSM (audit:change_record:approval_awaiting_itsm).

Outbound, the server writes one JSM internal note per event to the linked change — never a customer-visible comment — through the integration's write door: on each run under the record finishing (its id, outcome, duration and page), on each attested step and break-glass act (its evidence class and link), and on close (the verdict, the close note and the coverage summary: runs, incidents — the runs that did not succeed —, attested steps and break-glass acts). Notes carry run ids, outcomes and links, never a username, an email or a secret. Each delivered note is one info:change_record:itsm_note row. An unreachable ITSM delays the notes — queued, retried on the notification ladder (30 s, 2 m, 8 m, 30 m; five attempts), each failure a warn:change_record:itsm_unreachable row and the delivery_warning above — and never blocks a run.

Held: an approval the ITSM withdraws​

A change the CAB pulls back after the record approved — Jira moves it from an approving status to a pending one (rescheduled, re-opened for review) — holds the record. Both halves of the approval must hold, continuously:

  • the record stays approved — there is no fourth state — and held turns true, with external_approval.approved false and the withdrawal named on hold_reason, withdrawn_event_id and withdrawn_at;
  • no new run joins it: the scope join passes it by, a retry or a triggered run does not inherit it, and runs create … --change <record> (change_record_id), runs retry … --change and changes link are refused by name: "change record CHG-… is held: approval withdrawn by jsm (CHG-12 moved to "Awaiting CAB"); runs already under it continue";
  • the runs already under it continue, and so do the runs they start (a workflow's steps, nested runs);
  • a run whose join was decided in the instant before the hold landed is refused when it is written, by the same name, as change_record_id on the create — except a retry or a triggered run resolved that instant before as inherited, which is written under the record exactly as a nested run would be (a sub-second window; it is one more run under a change the ITSM had approved when it was asked);
  • opschain changes list shows the state as approved (held) and opschain changes show names the reason;
  • a renewed ITSM approval (a status mapped to approved) lifts the hold, and the record captures runs again.

The ledger carries audit:change_record:itsm_held (the withdrawing event, its timestamp and the service account's principal id) and audit:change_record:itsm_released (naming the hold it lifted). A record that never had the ITSM's approval (a hand-approved record linked later) is not held by a pending status; only a withdrawn approval holds. Closing the record clears the hold.

A close deferred until the work finishes​

An ITSM close (a status mapped to closed) that arrives while a run under the approved record is still running is kept as the record's pending close, never dropped: pending_close carries the mapped verdict, the ITSM's status, event id and timestamp, when it was deferred and how many runs were running (audit:change_record:itsm_close_deferred). The record stays approved and opschain changes show warns "Pending close: … applies when the last run under the record finishes".

When the record's last running run finishes, the server's connector sweep (every few seconds, on any replica; one replica applies a given record) closes it with the ITSM's verdict, as the service account that sent the close, with a note naming the deferred close — the closed row plus audit:change_record:itsm_close_applied naming the deferred event — and the close note goes to the ITSM like any close. While some runs still run, nothing applies. A later ITSM close replaces the pending one; a later ITSM move off a closing status (back to approved or pending) clears it (pending_close_cleared on its itsm_moved row); a person's changes close in the meantime supersedes it, and the closed row names the pending close it superseded. A pending close applies under the rights that admitted it when it arrived — the inbound service account's update right on the record's owner and the connection's entitlement; they are not re-decided when it applies, and the ledger names the close as deferred (deferred_close on the closed row, …:itsm_close_applied).

Listing (ListChangeRecords, opschain changes list)​

Newest first (created_at desc, id desc), keyset-paged (default 100, at most 1000), filtered by owner_path, state, code and scope_holds; a record under an owner the caller cannot read never appears. Every row carries run_count, active_run_count, in_progress, approval and authorisations, read for the whole page in one grouped count and one approval read keyed by the page's record ids.

scope_holds (--scope-holds on the CLI) keeps the records whose scope holds a target — the same test a run's join uses, answered by the store from the target's holding patterns (the node, each ancestor's /**, and /**) on every store — on PostgreSQL as scope ?| <patterns> over a GIN index on the scope. The target is a node path, or a workflow path /projects/<code>/workflows/<code>: the workflow is tested by its effective target — the one node every change step of its latest published version targets, else its project (below, "How runs join"); it needs read on the project and the workflow, and is refused by name where there is no stored workflow catalog (the SQLite store; the local lane takes node paths only). With state=approved it answers the records a run on the target may join — what the run dialogs' picker offers. The window does not narrow it: a record outside its window still holds the target for an explicit --change.

The workflow path resolves with no inputs. A workflow whose steps need the run's own inputs to name their target (a required input with no default) is tested by its project path, so the picker and the run can differ: a record scoped exactly to the project (/projects/<code>) is offered though the run, resolving to a narrower node from its inputs, will not join it; and a record scoped to that narrower node is not offered though the run would join it. Every other refusal resolving the workflow — an archived project, a version the catalog refuses — answers invalid_argument on scope_holds by name. The read observes nothing (it is not a run creation).

The story (GetChangeRecordStory, opschain changes show)​

The record's page: the record with its read-time facts, then — on the first page — every run under it the caller may read, oldest first (ChangeRecordRun: run_id, kind, node_path, action, status, association, created_at, started_at, finished_at; at most 1000, runs_truncated past that), the count of runs the caller may not read (withheld_runs — counted, never named), the break-glass records attached to the record, and then the entries (ChangeRecordStoryEntry: id, type, run_id, step_id, node_path, created_at, payload_json, kind) — every event of every run under it, of their steps (approvals included), the record's own ledger rows and its break-glass records, in (created_at, id) order, keyset-paged (default 100, at most 1000). payload_json is carried only for the record's audit:change_record:* rows, its ITSM connector's warn:change_record:* and info:change_record:* rows and the security:breakglass:* events, whose payloads carry principal ids only; every other entry names what happened, where and when, and the run page holds the detail. An entry on a node the caller cannot read never appears. The story is one set-based read per page over indexed columns.

Kinds. Every entry carries its story kind, decided by the server from its event type so no client re-derives it, and the request's optional kinds (GetChangeRecordStoryRequest.kinds; opschain changes show --story-kinds) returns only the entries of those kinds — the record page's Story hides the run events behind it. Empty returns every entry; naming all six is the same. The filter is a type predicate on the same indexed walk, applied before the page's limit, so a filtered page holds page_size matching entries and its next_page_token continues the filtered walk (pass the same kinds with it). An unknown kind is refused (invalid_argument on kinds, naming the valid kinds). Authorisation is unchanged: the filter narrows only what the caller may already read. The first page's runs and break-glass records are not filtered, and the export is always the whole story.

kindThe entries
recordThe record's own ledger rows (audit:change_record:*, and its ITSM connector's warn:change_record:* and info:change_record:* rows) other than the approval and link rows below.
approvalaudit:change_record:approval_requested, approved, approval_rejected, approval_withdrawn and approval_awaiting_itsm; every audit:approvals:* event; a step's audit:steps:approve and audit:steps:reject.
linkaudit:change_record:linked and audit:change_record:unlinked.
runEvery other event under a run: the run's and its steps' api:* events and the engine's run and step events.
breakglasssecurity:breakglass:* and warn:approvals:break_glass.
attestationA step's audit:runs:attested and audit:runs:refused.

An event type the table does not name is run when the entry sits under a run and record when it does not, so no entry falls outside the six.

After an unlink. Every event a run writes while it is under the record carries the record's id, and keeps it: an unlinked run's events from its time under the record stay in the story (the ledger keeps both rows, and the story shows the work that was done under the record), while its events after the unlink never enter it. Events a linked run wrote before its link appear while it is under the record and leave with it. Both server stores and the local lane read the story the same way.

Export (ExportChangeRecord, opschain changes export)​

opschain changes export <id|code> [-f file] writes the record and its whole story as NDJSON: the record first (kind change_record), then each run (run), each break-glass record (breakglass_record) and every entry (event). Actors are principal ids; usernames and emails are never written. The runs and break-glass records are the story's first page (at most 1000 each); the entries are unbounded.

On a server the export is one server stream, ExportChangeRecord (ExportChangeRecordRequest: id — the record's id or code — and owner_path, narrowing a code as the other verbs do). Each ExportChangeRecordResponse carries whole newline-terminated lines in ndjson (bytes; about 256 KiB a message, more only for a single larger line); concatenated in order they are the file. The server writes it with the CLI's own writer over the story's pages, so the CLI, which reads this stream, and the GUI's Export produce the same bytes for the same record and caller. What the story withholds the export withholds. Against a server without the stream the CLI walks the story's pages itself, to the same bytes; in the local lane it reads the home's store, on either store.

Who may​

Every verb is deny-by-default on the record's owner path, 404-on-deny:

  • read (GetChangeRecord, ListChangeRecords, GetChangeRecordStory, ExportChangeRecord) — read on <owner>/change_records (/change_records for a root record). Per-run reads are unchanged: a reader of project P who cannot read project Q sees a root record and P's runs, with Q's runs withheld.
  • create (CreateChangeRecord) — update on <owner>/change_records (and read on the owner project).
  • link, unlink, close — update on <owner>/change_records; linking and unlinking also need read on the run. Attaching a break-glass record to a change record is a link: it needs the same update.
  • approve (TransitionChangeRecord to approved) — update on <owner>/change_records_approve, so the right to approve can be held apart from the right to manage. Under an approval policy the transition is a request (update on <owner>/change_records), and approving the record's checklist needs update on <owner>/change_records_approve plus the checklist's approver standing.

An agent, a service account or a step's credential may create a record and link runs to it, and is refused by name on approve and close (permission_denied, "approving or closing a change record is a human verb"). On a server that authenticates, a call carrying no principal at all is refused the same way; the SQLite store's single-node server, which has no users, keeps both verbs.

Events​

audit:change_record:created, …:approved, …:linked, …:unlinked, …:closed and …:cancelled (opschain docs events), each in the same transaction as the move, carrying principal ids only; under an approval policy, …:approval_requested, …:approval_rejected and …:approval_withdrawn too; for a record linked to an ITSM change, …:itsm_linked, …:itsm_moved, …:itsm_stale and …:approval_awaiting_itsm, with warn:change_record:inbound_refused, info:change_record:itsm_note and warn:change_record:itsm_unreachable. A run that joins at creation writes …:linked (with its association) in its creation transaction. A record still approved past its window raises warn:change_record:window_elapsed once (below).

Past its window​

A record still approved one minute past its window_to raises warn:change_record:window_elapsed once, on the record's chain — its story and the events surface both carry it, with the record's id, code, owner, state, window_to and a message naming what to do (close it with a verdict, or move its window). It warns once per window end: the next sweep reads the warning already stamped after the end and raises nothing; a record whose window moves (an ITSM change.window move) warns again at its new end. A record without a window, a pending record and a closed record never warn, and the warning never closes anything. A server sweeps once a minute on the leader (both stores); the local lane, which has no sweep, raises it when a changes verb reads a record. Each sweep warns about at most 100 records, the next takes the rest.

The once-only rule reads the warning from the events table, so it holds for as long as the warning is retained: events age out by age on retention.events_days whatever their type (opschain docs retention), and a record left approved past its window for longer than that warns again once the earlier warning is purged — at most once per retention period. Closing the record (or moving its window) is what stops it.

Retention​

A record is never pruned while pending or approved, however old. Once closed it ages out on the evidence ledger's horizon (retention.evidence_ledger_days, default 730 days), counted from the close and archived before deletion (opschain docs retention) — the archive document carries every field above, the window (window_from, window_to, maintenance_window_id) and approved_at included. A run's change_record_id outlives the record it names. A linked record's ITSM link and its outbound work-note queue go with it (the change_records class).

Postures​

  • Local lane (--local, or no server targeted): records live in the home's store under the lane's one implicit principal (local); the baseline tier only. --change on a local run joins it, the scope join and inheritance apply exactly as on a server, and the story and the export are local reads. A link and an unlink carry the run's nested runs. The window-elapsed warning is raised when a changes verb reads a record. There are no maintenance windows in the local lane, so nothing joins through one.
  • Server on the SQLite store: the baseline tier works — records, every association rule, the story, close and the export. maintenance_window_id needs the PostgreSQL store's windows and is refused by name, so nothing joins through a window here. The window-elapsed sweep runs as on PostgreSQL. Approval policies — and with them the record as an approval subject and require_change_record — are refused by name ("approval policies need the PostgreSQL store"); changes approve approves at the baseline tier. The ITSM connector's inbound lane rides the inbound webhooks, which are refused by name on this store ("inbound webhooks need the PostgreSQL store"); no record here is ever linked, so no work note is written, no record is ever held and no close is ever pending (the store refuses both by name: "the ITSM connector needs the PostgreSQL store"). This posture has no users, so principal fields read anonymous.
  • Server on PostgreSQL: everything on this page.

Not yet​

Not in this release: the ServiceNow connector on the same contract, and the record on the SIEM forwarding lines. A record is never auto-closed.

What changes it​

  • opschain changes create / CreateChangeRecord opens it.
  • opschain changes approve / TransitionChangeRecord approves it — or, under an approval policy, requests its approval; the checklist's quorum (opschain approvals approve) approves it.
  • Run creation joins runs to it (explicit, scope, inherited, through an owned maintenance window); opschain changes link|unlink attach and detach them after the fact, with their nested runs.
  • The window sweep raises warn:change_record:window_elapsed on it once per window end while it stays approved.
  • opschain breakglass record --change attaches a break-glass record.
  • opschain changes close|cancel / CloseChangeRecord closes it.
  • A JSM connection's change mapping opens or links it, and the ITSM's inbound moves approve, close it and set its window (opschain docs integrations-jsm).
  • Retention ages out a closed record past the evidence ledger's horizon.