@volter/world-core 2.0.0

package/src/changeset.ts

@@ -0,0 +1,1032 @@
+import { resolveReferences } from './references.ts';
+import { withAncestryLock } from './ancestry.ts';
+import { captureParentHistory, historyChanges, historyEntries, historyPrefix, readHistoryView, type HistoryReference } from './history.ts';
+import { worldPaths } from './storage.ts';
+// The changeset primitive — "commit" for operational reality (docs/concepts/the-model.md, v0).
+//
+// Everything upstream of it already exists: worlds are the working copy, forks are branches,
+// and each twin's `actions.jsonl` (actions.ts) is the history. What was missing is the object
+// in between: a NAMED, BOUNDED, REPLAYABLE slice of that history — and the `diff` that shows a
+// human what a session actually did before anything becomes real.
+//
+// Three objects, in dependency order:
+//
+//   MARKER   a cross-service BASE POSITION — per-ledger `{count, lastActionId}` pairs captured
+//            at one instant. Not a global sequence number: a world has N independent append-only
+//            ledgers with no shared clock, so the only honest "where we were" is the tuple of
+//            per-ledger positions. `lastActionId` is what makes it VERIFIABLE — a ledger that was
+//            rewritten, purged, or rebuilt under a marker fails loudly at diff time instead of
+//            silently reporting the wrong delta.
+//
+//   DELTA    every action appended after the marker, across every ledger, ordered by
+//            `occurredAt` (the same causal order `volter-world tail` uses), grouped by vendor
+//            for rendering.
+//
+//   CHANGESET  a delta frozen into a content-addressed object: `{id, world, base, actions,
+//            approvals, applied}` + `contentHash`. The hash covers the IMMUTABLE body only
+//            (id/world/base/actions), so a later approval or push receipt appended to the object
+//            cannot invalidate the hash the approval bound to — the point of content-addressing.
+//
+// REPLAY is the CI primitive. It feeds recorded actions back through `applyTwinWrite` — the
+// KERNEL write path, not HTTP — into another world's twins.
+//
+// Replay is idempotent because it SAYS SO, not because content happens to hash the same. A local
+// vendor write is an OCCURRENCE — two calls are two actions, even byte-identical in the same
+// instant (BRIEFS/TWIN-RUNTIME-CONTRACT.md, "Local writes: occurrence or replay?") — so the old
+// mechanism, "feed back the same content and the target derives the same id", no longer holds and
+// would make a re-replay DOUBLE-APPLY. Instead replay passes the source action's own id as
+// `actionId`, which is at-most-once on an identity it genuinely holds: a replayed world's action
+// ids equal the source's, and replaying twice is `appended: false` end to end. The uniqueness seam
+// (billable occurrences that must not collapse) still survives, recovered from the source id and
+// passed through verbatim.
+//
+// On top of replay sits the OPERATIONAL-PR CONTRACT (v1): VERIFIERS — deterministic checks
+// against post-replay projected state, each one the kernel's own precondition expression
+// evaluated by the kernel's own evaluator (`checkPrecondition`) — whose results are recorded on
+// the object as `verification`; APPROVALS, each bound to the body hash at signing (drift
+// refuses, loudly); and READINESS — recomputed from the object every time, never trusted off a
+// stored boolean. Verification and approvals are ABOUT-the-body metadata: they live on the
+// object but outside `contentHash`, exactly so recording them cannot invalidate the hash they
+// bound to. The verifier SET, by contrast, is authored content and is hashed (when non-empty),
+// so an approval binds to what will be checked as well as what was done. This contract is
+// consumer-agnostic by design: anything that can render a diff, run a replay and record a
+// signature can implement review on top of it.
+//
+// This module is deliberately WORLD-IGNORANT: it takes ledger references (a state service +
+// the control root that holds it) and never learns what a world is. `volter-world` supplies
+// discovery and the CLI verbs; the state-level logic lives here, beside the ledgers it reads.
+import { createHash } from 'node:crypto';
+import { aliasesFrom, parentEntries, type Entry } from './log.ts';
+import { appendActionIfAbsent, checkPrecondition, listActions, projectedPreconditionValue, projectResources, isTwinBookkeeping } from './actions.ts';
+import type { TwinActionRevertSpec } from './actions.ts';
+import { touchedSubjects } from './actions.ts';
+import type { PerformAction } from './head.ts';
+import type { RemoteExecute } from './remote-execute.ts';
+import type { TwinAction, TwinActionPrecondition, TwinActionPreconditionOp } from './actions.ts';
+import { canonicalJson, hashFieldValue } from './hash.ts';
+import { applyTwinWrite } from './serve.ts';
+import type { TwinResource } from './serve.ts';
+
+/** One twin's action ledger, addressed the way the control plane addresses state:
+ *  `worldPaths(stateService, controlRoot)`. `service` is the caller's label for it (in a world:
+ *  the world service id); `stateService` is the control-plane service whose ledger this is.
+ *  They differ whenever a twin records under a different state name than its world service id. */
+export type LedgerRef = {
+  /** the vendor/twin as the operator names it — what `diff` groups by and `replay` matches on */
+  service: string;
+  /** the control-plane state service whose `actions.jsonl` this is (often === service) */
+  stateService: string;
+  /** control root such that `worldPaths(stateService, controlRoot)` resolves the ledger */
+  controlRoot: string;
+};
+
+/** One ledger's recorded position inside a marker. `count` is the row count at capture;
+ *  `lastActionId` is the verification anchor (see the marker note above). */
+export type LedgerPosition = {
+  service: string;
+  stateService: string;
+  count: number;
+  lastActionId: string | null;
+};
+
+export const MARKER_KIND = 'volter.world.marker.v1';
+export const CHANGESET_KIND = 'volter.world.changeset.v1';
+
+/** The base position a diff or changeset is taken against. */
+export type WorldMarker = {
+  kind: typeof MARKER_KIND;
+  id: string;
+  world: string;
+  createdAt: string;
+  /** Every ledger that existed at capture time. A ledger absent here is treated as position 0
+   *  (a twin that recorded its first action AFTER the mark contributes its whole ledger). */
+  ledgers: LedgerPosition[];
+};
+
+/** The id reserved for the synthetic "everything this world has ever recorded" base. */
+export const WORLD_BOOT_MARKER_ID = 'world-boot';
+
+/** An action inside a delta/changeset, bound to the twin whose ledger recorded it. The raw
+ *  `TwinAction` is kept verbatim (provenance); `service`/`stateService` are the binding replay
+ *  needs to route it into the right twin of another world. */
+export type ChangesetAction = {
+  service: string;
+  stateService: string;
+  action: TwinAction;
+};
+
+/** Per-vendor rollup of a delta, in first-occurrence order — the shape `diff` renders. */
+export type VendorSummary = {
+  service: string;
+  count: number;
+  operations: Array<{ operation: string; count: number; subjectIds: string[] }>;
+};
+
+export type LedgerDelta = {
+  world: string;
+  base: WorldMarker;
+  /** every action after `base`, across every ledger, ordered by `occurredAt` */
+  actions: ChangesetAction[];
+  vendors: VendorSummary[];
+  total: number;
+};
+
+/** A verifier: one deterministic check against post-replay projected state — the CI assertion
+ *  of the operational PR (docs/concepts/the-model.md v1). The `assert` is the kernel's ONE check
+ *  expression (`TwinActionPrecondition`: subject/field/op/value, evaluated by
+ *  `checkPrecondition`), the same shape write-time preconditions and plan conflicts already
+ *  use — a verifier is that check pointed at a replay target instead of the authoring world. */
+export type ChangesetVerifier = {
+  /** caller-chosen handle, unique within the changeset (results key on it) */
+  id: string;
+  /** the world service (twin) whose post-replay state the assert reads */
+  service: string;
+  assert: TwinActionPrecondition;
+};
+
+/** One verifier's outcome against a replay target. `assert` is repeated verbatim so the result
+ *  is readable on its own; `actual` is what the projected state held (omitted when undefined —
+ *  which is itself what `exists`/`not_exists` distinguish). */
+export type ChangesetVerifierResult = {
+  id: string;
+  service: string;
+  assert: TwinActionPrecondition;
+  passed: boolean;
+  actual?: unknown;
+};
+
+/** The recorded outcome of `changeset verify` — ABOUT-the-body metadata, like approvals: it
+ *  lives on the object but is outside `contentHash`, and each verify REPLACES the previous
+ *  record (the provenance fields say exactly which run this is). */
+export type ChangesetVerification = {
+  at: string;
+  /** where the replay landed — a world name, or 'ephemeral' for a throwaway target */
+  into: string;
+  /** the body hash at verification time; a later body edit makes this visibly stale */
+  contentHash: string;
+  /** sha256 over the post-replay projected state of every replay target — two verifies that
+   *  produced the same world state produce the same digest (the determinism receipt) */
+  worldDigest: string;
+  passed: boolean;
+  results: ChangesetVerifierResult[];
+  /** the world's checks (state-system.ts) that refused an entry — CI on deployment, run at verify */
+  refusals?: Array<{ actionId: string; service: string; check: string; reason: string }>;
+};
+
+/** One signature: who approved, when, against exactly which body hash. The hash-at-signing is
+ *  the point — an approval is meaningless without the bytes it bound to. */
+export type ChangesetApproval = {
+  principal: string;
+  at: string;
+  contentHash: string;
+  note?: string;
+};
+
+export type Changeset = {
+  kind: typeof CHANGESET_KIND;
+  id: string;
+  name: string;
+  /** the world it was authored in */
+  world: string;
+  /** the marker id it forked from */
+  base: string;
+  createdAt: string;
+  actions: ChangesetAction[];
+  /** deterministic checks that must pass on replay — part of the hashed body when present,
+   *  so an approval also binds to WHAT was checked, not just what was done */
+  verifiers: ChangesetVerifier[];
+  /** latest verify run (replaced, never accumulated) — outside the hash, like approvals */
+  verification: ChangesetVerification | null;
+  /** who signed, against `contentHash` */
+  approvals: ChangesetApproval[];
+  /** the governed push's outcome (v2) — receipts and, on a partial apply, the compensation report; null until applied */
+  applied: ChangesetApplication | null;
+  /** v4 — the CHECKABLE NARRATION: the human summary rendered deterministically from `actions`
+   *  at authoring (`narrateActions`). Outside the hash — it is DERIVED from the hashed actions, so
+   *  an approval already binds to it — and re-rendered on every read: a hand-edited narration no
+   *  longer equals its re-render, and the object is neither approvable nor applicable until
+   *  re-authored. Absent on objects authored before v4. */
+  narration?: string;
+  /** The author's own words for the changeset (git's commit message) — what `volter changeset -m`
+   *  records. Outside the hash, like the narration; a reviewer reads both. */
+  message?: string;
+  /** v3 — set by `rebaseChangeset`: the hash this object was rebased from, and when. Outside the hash. */
+  rebasedFrom?: { contentHash: string; at: string };
+  /** PROTOCOL 2 — where the parent log stood when this was cut, per state service (its entry count):
+   *  a rebase reads the parent's entries since here to name what moved under the changeset. Outside
+   *  the hash (metadata of the cut, not of the change). */
+  cut?: Record<string, HistoryReference>;
+  /** sha256 over the canonical JSON of `{id, world, base, actions}` (+ `verifiers` when any) */
+  contentHash: string;
+};
+
+/** Names that address a file on disk (markers, changesets): no separators, no traversal. */
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export function assertSafeChangesetName(name: string, what = 'changeset'): string {
+  if (!SAFE_NAME.test(name)) {
+    throw new Error(`Invalid ${what} name: ${JSON.stringify(name)} (letters, digits, '.', '_' and '-' only, starting with a letter or digit)`);
+  }
+  return name;
+}
+
+// ── markers ────────────────────────────────────────────────────────────────────────────────────
+
+/** The "everything ever recorded in this world" base: zero ledgers, so every ledger diffs from
+ *  position 0. Used when a world has no marks yet — `diff` must still answer, not refuse. */
+export function worldBootMarker(world: string, createdAt: string): WorldMarker {
+  return { kind: MARKER_KIND, id: WORLD_BOOT_MARKER_ID, world, createdAt, ledgers: [] };
+}
+
+/** Capture the current position of every ledger — the cross-service base marker. */
+export function captureMarker(opts: { id: string; world: string; ledgers: LedgerRef[]; createdAt?: string }): WorldMarker {
+  const ledgers = opts.ledgers.map((ledger) => {
+    const rows = listActions(ledger.stateService, ledger.controlRoot);
+    return {
+      service: ledger.service,
+      stateService: ledger.stateService,
+      count: rows.length,
+      lastActionId: rows.length ? rows[rows.length - 1]!.id : null,
+    } satisfies LedgerPosition;
+  });
+  return { kind: MARKER_KIND, id: opts.id, world: opts.world, createdAt: opts.createdAt ?? new Date().toISOString(), ledgers };
+}
+
+function positionKey(service: string, stateService: string): string {
+  return `${service}${stateService}`;
+}
+
+/** A marker taken in world A says nothing about world B's ledgers — comparing them would
+ *  produce a confident, wrong delta. Refuse. */
+export function assertMarkerBelongsTo(marker: WorldMarker, world: string): void {
+  if (marker.world !== world) {
+    throw new Error(`Marker "${marker.id}" was captured in world "${marker.world}", not "${world}" — a base marker only means something in the world it came from`);
+  }
+}
+
+// ── diff ───────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Every action appended after `base`, across `ledgers`, in `occurredAt` order.
+ *
+ * A ledger is verified against its recorded position before any of it is reported: fewer rows
+ * than the marker counted, or a different action id at that position, means the ledger was
+ * rewritten (scrub/purge/rebuild) and the marker no longer addresses anything real. That is a
+ * loud error — quietly re-basing on a rewritten ledger is how a diff lies.
+ */
+export function diffLedgers(opts: { world: string; ledgers: LedgerRef[]; base: WorldMarker }): LedgerDelta {
+  assertMarkerBelongsTo(opts.base, opts.world);
+  const positions = new Map(opts.base.ledgers.map((p) => [positionKey(p.service, p.stateService), p]));
+
+  type Ordered = { entry: ChangesetAction; ledgerIndex: number; rowIndex: number };
+  const ordered: Ordered[] = [];
+  const seen = new Set<string>();
+
+  opts.ledgers.forEach((ledger, ledgerIndex) => {
+    const key = positionKey(ledger.service, ledger.stateService);
+    seen.add(key);
+    const rows = listActions(ledger.stateService, ledger.controlRoot);
+    const position = positions.get(key);
+    const from = position?.count ?? 0;
+    if (position && from > 0) {
+      if (rows.length < from) {
+        throw new Error(`Ledger ${ledger.service}/${ledger.stateService} has ${rows.length} action(s) but marker "${opts.base.id}" recorded ${from} — the ledger was rewritten or purged since the mark`);
+      }
+      const anchor = rows[from - 1]!;
+      if (anchor.id !== position.lastActionId) {
+        throw new Error(`Ledger ${ledger.service}/${ledger.stateService} no longer matches marker "${opts.base.id}": expected action "${position.lastActionId}" at position ${from}, found "${anchor.id}" — the ledger was rewritten since the mark`);
+      }
+    }
+    rows.slice(from).forEach((action, offset) => {
+      if (isTwinBookkeeping(action)) return; // the twin's own store, never a change the app made
+      ordered.push({ entry: { service: ledger.service, stateService: ledger.stateService, action }, ledgerIndex, rowIndex: from + offset });
+    });
+  });
+
+  // A ledger the marker recorded that has since vanished entirely is the same corruption as a
+  // short ledger — the marker's anchor is unverifiable, so the delta cannot be trusted.
+  for (const position of opts.base.ledgers) {
+    if (position.count > 0 && !seen.has(positionKey(position.service, position.stateService))) {
+      throw new Error(`Ledger ${position.service}/${position.stateService} recorded by marker "${opts.base.id}" (${position.count} action(s)) no longer exists in world "${opts.world}" — the ledger was rewritten or purged since the mark`);
+    }
+  }
+
+  ordered.sort((a, b) => {
+    const at = a.entry.action.occurredAt ?? '';
+    const bt = b.entry.action.occurredAt ?? '';
+    if (at !== bt) return at < bt ? -1 : 1;
+    // ties keep discovery order (ledger, then row) — the same stable rule `tail` uses
+    if (a.ledgerIndex !== b.ledgerIndex) return a.ledgerIndex - b.ledgerIndex;
+    return a.rowIndex - b.rowIndex;
+  });
+
+  const actions = ordered.map((o) => o.entry);
+  return { world: opts.world, base: opts.base, actions, vendors: summarizeByVendor(actions), total: actions.length };
+}
+
+/** Group a delta by vendor, then by operation — both in FIRST-OCCURRENCE order, so the rollup
+ *  reads in the same causal order as the actions themselves. */
+export function summarizeByVendor(actions: ChangesetAction[]): VendorSummary[] {
+  const vendors = new Map<string, VendorSummary>();
+  for (const { service, action } of actions) {
+    let vendor = vendors.get(service);
+    if (!vendor) {
+      vendor = { service, count: 0, operations: [] };
+      vendors.set(service, vendor);
+    }
+    vendor.count += 1;
+    const name = action.operation ?? action.op ?? '?';
+    let operation = vendor.operations.find((o) => o.operation === name);
+    if (!operation) {
+      operation = { operation: name, count: 0, subjectIds: [] };
+      vendor.operations.push(operation);
+    }
+    operation.count += 1;
+    operation.subjectIds.push(action.subject?.id ?? '?');
+  }
+  return [...vendors.values()];
+}
+
+/** How many subject ids a rendered operation lists before eliding the rest. */
+const MAX_RENDERED_IDS = 4;
+
+function renderIds(ids: string[]): string {
+  if (ids.length === 0) return '';
+  const shown = ids.slice(0, MAX_RENDERED_IDS);
+  return ` (${shown.join(', ')}${ids.length > shown.length ? ', …' : ''})`;
+}
+
+/** The human rendering of a delta — one line per vendor plus a total. Shared by `diff` and
+ *  `changeset show` so a frozen changeset reads exactly like the diff it was cut from. */
+export function formatLedgerDelta(delta: LedgerDelta, opts: { title?: string } = {}): string {
+  const title = opts.title ?? `World ${delta.world}`;
+  const since = `since ${delta.base.id}${delta.base.createdAt ? ` (${delta.base.createdAt})` : ''}`;
+  if (delta.total === 0) return `${title} — no actions ${since}\n`;
+  const lines = [`${title} — ${plural(delta.total, 'action')} ${since}`, ''];
+  for (const vendor of delta.vendors) {
+    const parts = vendor.operations.map((o) => `${o.count} ${o.operation}${renderIds(o.subjectIds)}`);
+    lines.push(`  ${vendor.service}: ${parts.join(', ')}`);
+  }
+  lines.push('', `  ${plural(delta.total, 'action')} across ${plural(delta.vendors.length, 'twin')}`);
+  return `${lines.join('\n')}\n`;
+}
+
+function plural(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+
+// ── the changeset object ───────────────────────────────────────────────────────────────────────
+
+/** What `changesetContentHash` needs to see — the immutable fields, with `verifiers` optional
+ *  so a v0 object (authored before verifiers existed) hashes exactly as it always did. */
+export type ChangesetHashable = Pick<Changeset, 'id' | 'world' | 'base' | 'actions'> & Partial<Pick<Changeset, 'verifiers' | 'cut'>>;
+
+/** The IMMUTABLE body a `contentHash` covers. `approvals`/`verification`/`applied`/`createdAt`
+ *  are excluded on purpose: an approval or a verify run must not invalidate the hash it bound
+ *  to — content-addressing is about the actions, not the object's lifecycle. `verifiers` ARE
+ *  in the body (when any exist): they are authored content, and an approval must bind to what
+ *  will be checked, not just what was done. An empty verifier set is omitted so every v0
+ *  changeset keeps the hash it was signed under. */
+function changesetBody(changeset: ChangesetHashable): Record<string, unknown> {
+  const body: Record<string, unknown> = { id: changeset.id, world: changeset.world, base: changeset.base, actions: changeset.actions };
+  if (changeset.verifiers?.length) body.verifiers = changeset.verifiers;
+  // the cut is part of what an approval binds to: a rebase moves it, and with it the hash — a rebase is a re-review
+  if (changeset.cut && Object.keys(changeset.cut).length) body.cut = changeset.cut;
+  return body;
+}
+
+export function changesetContentHash(changeset: ChangesetHashable): string {
+  return `sha256:${createHash('sha256').update(canonicalJson(changesetBody(changeset))).digest('hex')}`;
+}
+
+const PRECONDITION_OPS: readonly TwinActionPreconditionOp[] = ['exists', 'not_exists', 'eq', 'neq', 'version_eq'];
+
+/** A verifier that cannot be evaluated deterministically is refused at authoring time, not
+ *  discovered at verify time. */
+export function assertValidVerifiers(verifiers: ChangesetVerifier[]): ChangesetVerifier[] {
+  const seen = new Set<string>();
+  for (const verifier of verifiers) {
+    if (!verifier.id?.trim()) throw new Error('Invalid verifier: every verifier needs an id');
+    if (seen.has(verifier.id)) throw new Error(`Invalid verifier: duplicate id "${verifier.id}"`);
+    seen.add(verifier.id);
+    if (!verifier.service?.trim()) throw new Error(`Invalid verifier "${verifier.id}": missing service (the twin whose state it checks)`);
+    const assert = verifier.assert;
+    if (!assert?.subject?.type || !assert.subject.id || !assert.field) {
+      throw new Error(`Invalid verifier "${verifier.id}": assert needs subject {type, id} and a field`);
+    }
+    if (!PRECONDITION_OPS.includes(assert.op)) {
+      throw new Error(`Invalid verifier "${verifier.id}": unknown op ${JSON.stringify(assert.op)} (want ${PRECONDITION_OPS.join('|')})`);
+    }
+    if ((assert.op === 'eq' || assert.op === 'neq' || assert.op === 'version_eq') && assert.value === undefined) {
+      throw new Error(`Invalid verifier "${verifier.id}": op "${assert.op}" needs a value`);
+    }
+  }
+  return verifiers;
+}
+
+/**
+ * Parse the CLI spelling of a verifier: `<service> <type>:<id> <field> <op> [<value>]`, e.g.
+ * `stripe price:price_annual unit_amount eq 47000`. The value is JSON when it parses as JSON
+ * (numbers, booleans, quoted strings) and a bare string otherwise, so `eq active` and
+ * `eq "active"` mean the same thing.
+ */
+export function parseVerifierExpression(expression: string, id: string): ChangesetVerifier {
+  const usage = `want "<service> <type>:<id> <field> <op> [<value>]" with op ${PRECONDITION_OPS.join('|')}`;
+  const parts = expression.trim().split(/\s+/);
+  const [service, subject, field, op] = parts;
+  if (!service || !subject || !field || !op) throw new Error(`Invalid verifier expression ${JSON.stringify(expression)} — ${usage}`);
+  const colon = subject.indexOf(':');
+  if (colon <= 0 || colon === subject.length - 1) {
+    throw new Error(`Invalid verifier expression ${JSON.stringify(expression)}: subject ${JSON.stringify(subject)} is not <type>:<id> — ${usage}`);
+  }
+  const raw = parts.slice(4).join(' ');
+  let value: unknown;
+  if (raw) {
+    try { value = JSON.parse(raw); } catch { value = raw; }
+  }
+  const assert: TwinActionPrecondition = {
+    subject: { type: subject.slice(0, colon), id: subject.slice(colon + 1) },
+    field,
+    op: op as TwinActionPreconditionOp,
+    ...(value === undefined ? {} : { value }),
+  };
+  return assertValidVerifiers([{ id, service, assert }])[0]!;
+}
+
+/** Freeze a delta into a named, content-addressed changeset. */
+export function buildChangeset(opts: { name: string; world: string; base: string; actions: ChangesetAction[]; verifiers?: ChangesetVerifier[]; createdAt?: string; message?: string; cut?: Record<string, HistoryReference> }): Changeset {
+  assertSafeChangesetName(opts.name);
+  const verifiers = assertValidVerifiers(opts.verifiers ?? []);
+  const core = { id: `chg_${opts.name}`, world: opts.world, base: opts.base, actions: opts.actions, verifiers, ...(opts.cut === undefined ? {} : { cut: opts.cut }) };
+  return {
+    kind: CHANGESET_KIND,
+    ...core,
+    name: opts.name,
+    createdAt: opts.createdAt ?? new Date().toISOString(),
+    verification: null,
+    approvals: [],
+    applied: null,
+    narration: narrateActions(opts.actions),
+    ...(opts.message === undefined ? {} : { message: opts.message }),
+    contentHash: changesetContentHash(core),
+  };
+}
+
+/** Fill the lifecycle fields a changeset authored before v1 lacks on disk, without touching
+ *  its hash (absent and empty `verifiers` hash identically by construction). */
+export function normalizeChangeset(changeset: Changeset): Changeset {
+  return {
+    ...changeset,
+    verifiers: changeset.verifiers ?? [],
+    verification: changeset.verification ?? null,
+    approvals: changeset.approvals ?? [],
+    applied: changeset.applied ?? null,
+  };
+}
+
+/** Recompute and compare — a changeset whose bytes were edited after authoring is not the
+ *  object anyone approved. Callers render this as a warning or a hard failure as suits. */
+export function changesetHashMatches(changeset: Changeset): boolean {
+  return changeset.contentHash === changesetContentHash(changeset);
+}
+
+/** One verifier's assert as a readable expression — the same spelling `parseVerifierExpression` accepts. */
+function renderAssert(verifier: { service: string; assert: TwinActionPrecondition }): string {
+  const { assert } = verifier;
+  return `${verifier.service} ${assert.subject.type}:${assert.subject.id} ${assert.field} ${assert.op}${assert.value === undefined ? '' : ` ${JSON.stringify(assert.value)}`}`;
+}
+
+function renderVerificationLines(changeset: Changeset): string[] {
+  const lines: string[] = [];
+  const verification = changeset.verification;
+  if (!verification) {
+    lines.push(`  verified: no${changeset.verifiers.length ? ` (${plural(changeset.verifiers.length, 'verifier')} defined)` : ''}`);
+  } else {
+    const passed = verification.results.filter((result) => result.passed).length;
+    const stale = verification.contentHash !== changeset.contentHash ? ' ** STALE: recorded against a different body hash **' : '';
+    lines.push(`  verified: ${verification.passed ? 'yes' : 'FAILED'} — ${passed}/${verification.results.length} passed, into ${verification.into} at ${verification.at}${stale}`);
+    for (const result of verification.results.filter((entry) => !entry.passed)) {
+      lines.push(`    FAIL ${result.id}: ${renderAssert(result)} — actual ${result.actual === undefined ? 'undefined' : JSON.stringify(result.actual)}`);
+    }
+  }
+  if (changeset.approvals.length === 0) {
+    lines.push('  approvals: none');
+  } else {
+    for (const approval of changeset.approvals) {
+      const binds = approval.contentHash === changeset.contentHash ? '' : ' ** signed a DIFFERENT body hash **';
+      lines.push(`  approved by ${approval.principal} at ${approval.at}${approval.note ? ` — ${approval.note}` : ''}${binds}`);
+    }
+  }
+  return lines;
+}
+
+/** Render a changeset exactly like the diff it was cut from. */
+export function formatChangeset(changeset: Changeset): string {
+  const delta: LedgerDelta = {
+    world: changeset.world,
+    // `show` renders against the recorded base ID; the marker object itself lives in the
+    // authoring world and is not needed to read the changeset.
+    base: { kind: MARKER_KIND, id: changeset.base, world: changeset.world, createdAt: '', ledgers: [] },
+    actions: changeset.actions,
+    vendors: summarizeByVendor(changeset.actions),
+    total: changeset.actions.length,
+  };
+  const lines = [
+    `Changeset ${changeset.name} (${changeset.id})`,
+    `  world: ${changeset.world}`,
+    `  base: ${changeset.base}`,
+    `  hash: ${changeset.contentHash}${changesetHashMatches(changeset) ? '' : '  ** MISMATCH: the recorded contentHash does not match the body **'}`,
+    ...changeset.verifiers.map((verifier) => `  verifier ${verifier.id}: ${renderAssert(verifier)}`),
+    ...renderVerificationLines(changeset),
+    `  applied: ${changeset.applied === null ? 'no' : changeset.applied.outcome}`,
+    ...(changeset.rebasedFrom ? [`  rebased from ${changeset.rebasedFrom.contentHash} at ${changeset.rebasedFrom.at}`] : []),
+    ...(changeset.narration === undefined ? [] : [`  narration${narrationDrift(changeset) ? '  ** DRIFTED: this text no longer describes the actions **' : ''}:`, ...changeset.narration.split('\n').map((line) => `    ${line}`)]),
+  ];
+  return `${lines.join('\n')}\n\n${formatLedgerDelta(delta, { title: `  ${plural(changeset.actions.length, 'action')}` })}`;
+}
+
+// ── replay ─────────────────────────────────────────────────────────────────────────────────────
+
+export type ReplayTarget = {
+  /** the changeset service this target satisfies */
+  service: string;
+  /** the state service to write into (may differ from the source's) */
+  stateService: string;
+  controlRoot: string;
+};
+
+export type ReplayActionResult = {
+  service: string;
+  sourceActionId: string;
+  /** the action id in the TARGET ledger — identical to `sourceActionId` whenever the target
+   *  state service matches the source's, which is what makes replay verifiable */
+  actionId: string;
+  /** 'write' = through `applyTwinWrite` (the kernel write path); 'append' = recorded verbatim */
+  via: 'write' | 'append';
+  status: 'performed' | 'replayed';
+};
+
+export type ReplayReport = {
+  changeset: string;
+  contentHash: string;
+  /** the authoring world */
+  world: string;
+  into: string;
+  total: number;
+  performed: number;
+  replayed: number;
+  services: string[];
+  actions: ReplayActionResult[];
+};
+
+/**
+ * Recover the `uniqueness` value `applyTwinWrite` folded into an action id, or report that the
+ * id is not twin-write-shaped at all (a hand-written or pack-appended action).
+ *
+ * The id format is `twin:<service>:<operation>:<subjectId>:<occurredAt>:<contentHash>[:<uniqueness>]`
+ * and both `operation` and `subjectId` may themselves contain ':', so the id cannot be split
+ * field-wise. A repeated write additionally carries an occurrence ordinal (`…#1`), stripped below. Instead the deterministic prefix is REBUILT from the action's own recorded parts —
+ * if it matches, whatever follows is exactly the uniqueness seam. Getting this right is what
+ * keeps billable occurrences (two identical AI completions in one millisecond) from collapsing
+ * into one action on replay.
+ */
+export function twinWriteShape(action: TwinAction): { uniqueness?: string } | null {
+  if (action.op !== 'set' || !action.operation || !action.fields) return null;
+  const hash = hashFieldValue({ operation: action.operation, subjectId: action.subject.id, fields: action.fields });
+  const prefix = `twin:${action.service}:${action.operation}:${action.subject.id}:${action.occurredAt}:${hash}`;
+  // A REPEAT carries an occurrence ordinal (`…#1`). Strip it before matching, or every repeated
+  // write falls out of the write path and replays through the `append` fallback — which is
+  // reserved for actions the write path cannot EXPRESS, and which the report labels accordingly.
+  // The ruling makes repeats ordinary, so without this the first changeset containing one flips a
+  // replay assertion that has nothing to do with it. The ordinal is digits after a trailing '#',
+  // and a content hash is hex, so this cannot eat a real id's tail.
+  const id = action.id.replace(/#\d+$/, '');
+  if (id === prefix) return {};
+  if (id.startsWith(`${prefix}:`)) return { uniqueness: id.slice(prefix.length + 1) };
+  return null;
+}
+
+/**
+ * Replay a changeset's actions, in order, into `targets`.
+ *
+ * Two paths, and the split is about EXPRESSIVENESS, not preference:
+ *   - `write`  — the default and the point: back through `applyTwinWrite`, the same kernel entry
+ *     an SDK call lands on. The target re-derives the action id from content, so it matches the
+ *     source id and a second replay is a total no-op.
+ *   - `append` — the honest fallback for actions the write path cannot express: multi-resource
+ *     `projection` transactions (applyTwinWrite carries only flat `fields`, so routing them
+ *     through it would silently DROP the creates/deletes/emits) and `revert`/`confirm`
+ *     bookkeeping rows. These are appended verbatim under `appendActionIfAbsent`, which is
+ *     id-keyed — so they are idempotent on re-replay too.
+ *
+ * `preconditions` are deliberately NOT replayed. They were evaluated against the authoring
+ * world's state at author time; re-evaluating them against a different base would fail replays
+ * that are perfectly valid recordings. Verifying a changeset against a target's state is v1's
+ * job (verifiers), not a silent side effect of replay. Dropping them cannot change any action
+ * id — preconditions are not part of the content hash.
+ */
+export async function replayChangeset(
+  changeset: Changeset,
+  opts: { into: string; targets: ReplayTarget[]; available?: string[] },
+): Promise<ReplayReport> {
+  const byService = new Map(opts.targets.map((t) => [t.service, t]));
+  const needed = [...new Set(changeset.actions.map((a) => a.service))];
+  const missing = needed.filter((service) => !byService.has(service));
+  if (missing.length) {
+    const have = opts.available ?? opts.targets.map((t) => t.service);
+    throw new Error(`Cannot replay changeset "${changeset.name}" into world "${opts.into}": it touches ${missing.length === 1 ? 'a twin' : 'twins'} that world does not have — ${missing.join(', ')} (world "${opts.into}" has: ${have.length ? have.join(', ') : 'no services'})`);
+  }
+
+  const results: ReplayActionResult[] = [];
+  for (const entry of changeset.actions) {
+    const target = byService.get(entry.service)!;
+    const action = entry.action;
+    const shape = action.projection ? null : twinWriteShape(action);
+    if (shape) {
+      const { result } = await applyTwinWrite(
+        target.stateService,
+        {
+          operation: action.operation!,
+          subjectType: action.subject.type,
+          subjectId: action.subject.id,
+          fields: action.fields!,
+          occurredAt: action.occurredAt,
+          ...(action.actor ? { actor: action.actor } : {}),
+          ...(action.correlationId ? { correlationId: action.correlationId } : {}),
+          ...(shape.uniqueness === undefined ? {} : { uniqueness: shape.uniqueness }),
+          // AT MOST ONCE, AND THE SOURCE'S IDENTITY. Replay re-materializes an action that
+          // already has an id, and the target must keep it — a replayed world's action ids equal
+          // the source's, which the CI primitive pins. Local vendor writes are occurrences by
+          // default and no longer collapse on content, which is what silently dropped a write
+          // returning a value to what it was one instant earlier; replay is the caller that
+          // genuinely wants dedupe and is the one that can say so honestly, because it holds the
+          // identity. See the runtime contract, "Local writes: occurrence or replay?".
+          actionId: action.id,
+        },
+        target.controlRoot,
+      );
+      results.push({ service: entry.service, sourceActionId: action.id, actionId: result.actionId, via: 'write', status: result.status });
+      continue;
+    }
+    // Drop preconditions (evaluated in the source world) AND the source world's shadowBasis
+    // (refs into the SOURCE's event log — meaningless against the target's mirror; carrying
+    // it verbatim would poison the target's non-fast-forward check, R14). The appender
+    // re-stamps against the target; replay identity excludes the basis, so re-stamping
+    // cannot conflict with a prior copy.
+    const { preconditions: _dropped, ...rest } = action;
+    const { appended } = appendActionIfAbsent({ ...rest, service: target.stateService }, target.controlRoot);
+    results.push({ service: entry.service, sourceActionId: action.id, actionId: action.id, via: 'append', status: appended ? 'performed' : 'replayed' });
+  }
+
+  return {
+    changeset: changeset.name,
+    contentHash: changeset.contentHash,
+    world: changeset.world,
+    into: opts.into,
+    total: results.length,
+    performed: results.filter((r) => r.status === 'performed').length,
+    replayed: results.filter((r) => r.status === 'replayed').length,
+    services: needed,
+    actions: results,
+  };
+}
+
+export function formatReplayReport(report: ReplayReport): string {
+  const lines = [
+    `Replayed changeset ${report.changeset} (${report.world} → ${report.into})`,
+    `  ${plural(report.total, 'action')}: ${report.performed} performed, ${report.replayed} already replayed`,
+    `  twins: ${report.services.join(', ') || 'none'}`,
+    `  hash: ${report.contentHash}`,
+  ];
+  return `${lines.join('\n')}\n`;
+}
+
+// ── verify / approve / status — the operational-PR contract (v1) ───────────────────────────────
+
+/**
+ * Run a changeset's verifiers against post-replay state. Deterministic on purpose: each assert
+ * reads the target's PROJECTED state (`projectResources` — the same projection the kernel's
+ * preconditions and plan conflicts read) and is evaluated by `checkPrecondition` — the same
+ * evaluator, so a verifier means exactly what a precondition means. The `worldDigest` is a
+ * receipt over everything the verifiers could have seen: two runs that produced the same
+ * post-replay state produce the same digest.
+ *
+ * `targets` are the same references replay wrote through — a verifier is only honest against
+ * the ledgers the replay actually landed in. A verifier naming a service with no target is a
+ * loud error (there is nothing real to check it against), never a silent pass.
+ */
+export function runChangesetVerifiers(
+  changeset: Changeset,
+  targets: ReplayTarget[],
+  opts: { at: string; into: string },
+): ChangesetVerification {
+  const resourcesByService = new Map<string, TwinResource[]>();
+  const digestInput: Array<{ service: string; stateService: string; resources: unknown }> = [];
+  for (const target of [...targets].sort((a, b) => (a.service === b.service ? (a.stateService < b.stateService ? -1 : 1) : a.service < b.service ? -1 : 1))) {
+    const resources = projectResources(target.stateService, target.controlRoot);
+    // one world service may record under several state services (aws → s3 + dynamodb):
+    // its verifiers see the union
+    resourcesByService.set(target.service, [...(resourcesByService.get(target.service) ?? []), ...resources]);
+    digestInput.push({ service: target.service, stateService: target.stateService, resources });
+  }
+
+  const results: ChangesetVerifierResult[] = changeset.verifiers.map((verifier) => {
+    const resources = resourcesByService.get(verifier.service);
+    if (!resources) {
+      const have = [...resourcesByService.keys()].sort();
+      throw new Error(`Verifier "${verifier.id}" checks twin "${verifier.service}" but the replay target has no such twin (targets: ${have.join(', ') || 'none'})`);
+    }
+    const { assert } = verifier;
+    const actual = projectedPreconditionValue(assert, resources);
+    const passed = checkPrecondition(assert, actual);
+    return { id: verifier.id, service: verifier.service, assert, passed, ...(actual === undefined ? {} : { actual }) };
+  });
+
+  return {
+    at: opts.at,
+    into: opts.into,
+    contentHash: changesetContentHash(changeset),
+    worldDigest: `sha256:${createHash('sha256').update(canonicalJson(digestInput)).digest('hex')}`,
+    passed: results.every((result) => result.passed),
+    results,
+  };
+}
+
+/** Record `verification` on the object — REPLACING any prior run (the provenance fields carry
+ *  which run this is), never touching the hash the body is addressed by. */
+export function withVerification(changeset: Changeset, verification: ChangesetVerification): Changeset {
+  return { ...changeset, verification };
+}
+
+/**
+ * Append an approval bound to the changeset's CURRENT body hash. Refuses when the stored
+ * `contentHash` no longer matches the body: an object whose bytes moved after authoring is not
+ * the object anyone reviewed, and signing it would launder the drift. Loud, never silent.
+ */
+export function approveChangeset(
+  changeset: Changeset,
+  opts: { principal: string; at?: string; note?: string },
+): { changeset: Changeset; approval: ChangesetApproval } {
+  if (!opts.principal?.trim()) throw new Error('Approval requires a principal (--as <principal>)');
+  const bodyHash = changesetContentHash(changeset);
+  if (changeset.contentHash !== bodyHash) {
+    throw new Error(`Refusing to approve changeset "${changeset.name}": its stored contentHash (${changeset.contentHash}) does not match its body (${bodyHash}) — the object drifted after authoring, and an approval must bind to exactly what was reviewed`);
+  }
+  if (narrationDrift(changeset)) throw new Error(`Refusing to approve changeset "${changeset.name}": its narration no longer describes its actions — a hand-edited summary cannot be signed; re-author it`);
+  const approval: ChangesetApproval = {
+    principal: opts.principal.trim(),
+    at: opts.at ?? new Date().toISOString(),
+    contentHash: bodyHash,
+    ...(opts.note ? { note: opts.note } : {}),
+  };
+  return { changeset: { ...changeset, approvals: [...changeset.approvals, approval] }, approval };
+}
+
+/** Everything `changeset status` reports — recomputed from the object, never trusted off
+ *  stored booleans (the same rule `planRequiresApproval` follows). */
+export type ChangesetReadiness = {
+  name: string;
+  world: string;
+  contentHash: string;
+  /** stored hash matches the body */
+  hashOk: boolean;
+  /** a verification exists, binds to the current hash, and every verifier passed */
+  verified: boolean;
+  verification: ChangesetVerification | null;
+  /** every approval on the object */
+  approvals: number;
+  /** approvals whose hash-at-signing is the current body hash — the only ones that count */
+  bindingApprovals: number;
+  ready: boolean;
+  /** empty exactly when ready */
+  reasons: string[];
+};
+
+export function changesetReadiness(changeset: Changeset): ChangesetReadiness {
+  const bodyHash = changesetContentHash(changeset);
+  const hashOk = changeset.contentHash === bodyHash;
+  const verification = changeset.verification;
+  const binding = changeset.approvals.filter((approval) => approval.contentHash === changeset.contentHash);
+
+  const reasons: string[] = [];
+  if (!hashOk) reasons.push(`contentHash mismatch: stored ${changeset.contentHash}, body hashes to ${bodyHash} — the object was edited after authoring`);
+  const drift = narrationDrift(changeset);
+  if (drift) reasons.push('narration drifted from the actions — the summary a reviewer reads no longer describes what would be done; re-author');
+  if (!verification) {
+    reasons.push('never verified — run `changeset verify`');
+  } else if (verification.contentHash !== changeset.contentHash) {
+    reasons.push(`verification is stale: it ran against ${verification.contentHash} — re-run \`changeset verify\``);
+  } else if (!verification.passed) {
+    const failed = verification.results.filter((result) => !result.passed);
+    reasons.push(`verification FAILED: ${failed.map((result) => result.id).join(', ')} (${failed.length} of ${verification.results.length})`);
+  }
+  if (binding.length === 0) {
+    reasons.push(changeset.approvals.length ? 'no approval binds to the current body hash' : 'no approvals — run `changeset approve --as <principal>`');
+  }
+
+  const verified = Boolean(hashOk && verification && verification.contentHash === changeset.contentHash && verification.passed);
+  return {
+    name: changeset.name,
+    world: changeset.world,
+    contentHash: changeset.contentHash,
+    hashOk,
+    verified,
+    verification,
+    approvals: changeset.approvals.length,
+    bindingApprovals: binding.length,
+    ready: reasons.length === 0,
+    reasons,
+  };
+}
+
+/** The single honest line `changeset status` prints. No push here — v2's job; this line only
+ *  tells the truth about the object. */
+export function formatChangesetStatus(readiness: ChangesetReadiness): string {
+  const verdict = readiness.ready ? 'ready' : `not-ready (${readiness.reasons.join('; ')})`;
+  return `${readiness.name} ${readiness.contentHash} verified=${readiness.verified ? 'yes' : 'no'} approvals=${readiness.bindingApprovals} ${verdict}\n`;
+}
+
+/** The verify verb's report — the verification plus the replay that produced it. */
+export function formatVerification(name: string, verification: ChangesetVerification, report: ReplayReport): string {
+  const lines = [
+    `Verified changeset ${name} → ${verification.into}`,
+    `  replay: ${plural(report.total, 'action')} (${report.performed} performed, ${report.replayed} already replayed)`,
+    verification.results.length === 0
+      ? '  verifiers: none (replay itself is the only check)'
+      : `  verifiers: ${verification.results.filter((result) => result.passed).length}/${verification.results.length} passed`,
+    ...verification.results.map((result) => `    ${result.passed ? 'PASS' : 'FAIL'} ${result.id}: ${renderAssert(result)}${result.passed ? '' : ` — actual ${result.actual === undefined ? 'undefined' : JSON.stringify(result.actual)}`}`),
+    `  worldDigest: ${verification.worldDigest}`,
+    `  verdict: ${verification.passed ? 'PASSED' : 'FAILED'}`,
+  ];
+  return `${lines.join('\n')}\n`;
+}
+
+// ── v2: governed push — apply ───────────────────────────────────────────────────────────────
+//
+
+/** The object with its application recorded — `applied` is outside the hash. */
+export function withApplication(changeset: Changeset, application: ChangesetApplication): Changeset {
+  return { ...changeset, applied: application };
+}
+
+export function formatApplication(name: string, application: ChangesetApplication): string {
+  const lines = [`Applied changeset ${name}: ${application.outcome}${application.forced ? ' (forced past the readiness gate)' : ''}`];
+  if (application.refusal) for (const r of application.refusal) lines.push(`  refused: ${r}`);
+  for (const r of application.receipts) lines.push(`  ${r.status.padEnd(9)} ${r.service} ${r.actionId}${r.externalId ? ` → ${r.externalId}` : ''}${r.error ? ` — ${r.error}` : ''}`);
+  if (application.compensation.length) {
+    lines.push('  COMPENSATION — what crossed before the failure, and the inverse each one would take:');
+    for (const c of application.compensation) lines.push(`    ${c.service} ${c.subject.type}:${c.subject.id}${c.externalId ? ` (vendor id ${c.externalId})` : ''}: ${c.revert.strategy}${'operation' in c.revert && c.revert.operation ? ` ${c.revert.operation}` : ''}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+// ── v4: the checkable narration ────────────────────────────────────────────────────────────
+//
+// The narration is what a reviewer READS; the actions are what would be DONE. They are the same
+// thing only if the narration is a pure function of the actions — so it is: rendered here at
+// authoring, inside the hash, and re-rendered on every read. A narration that no longer equals
+// its re-render (a hand edit, a stale copy) makes the object not-ready: neither approvable nor
+// applicable until re-authored. Deterministic by construction — causal order, full subject
+// lists, the field names each write sets, no clock, no elision.
+
+function narrateFields(action: TwinAction): string {
+  const names = Object.keys(action.fields ?? {}).sort();
+  if (names.length === 0) return '';
+  return ` setting ${names.join(', ')}`;
+}
+/** One deterministic paragraph per twin, one sentence per operation, in first-occurrence order. */
+export function narrateActions(actions: ChangesetAction[]): string {
+  if (actions.length === 0) return 'Does nothing: the changeset carries no actions.';
+  const paragraphs: string[] = [];
+  for (const vendor of summarizeByVendor(actions)) {
+    const sentences = vendor.operations.map((operation) => {
+      const rows = actions.filter((entry) => entry.service === vendor.service && (entry.action.operation ?? entry.action.op ?? '?') === operation.operation);
+      const fieldSets = [...new Set(rows.map((entry) => narrateFields(entry.action)))];
+      const fields = fieldSets.length === 1 ? fieldSets[0]! : '';
+      return `${operation.count} × ${operation.operation} on ${rows.map((entry) => `${entry.action.subject.type}:${entry.action.subject.id}`).join(', ')}${fields}.`;
+    });
+    paragraphs.push(`${vendor.service}: ${sentences.join(' ')}`);
+  }
+  return paragraphs.join('\n');
+}
+/** The recorded narration against its re-render — null when they agree or when the object carries none. */
+export function narrationDrift(changeset: Pick<Changeset, 'actions'> & Partial<Pick<Changeset, 'narration'>>): { recorded: string; expected: string } | null {
+  if (changeset.narration === undefined) return null;
+  const expected = narrateActions(changeset.actions);
+  return expected === changeset.narration ? null : { recorded: changeset.narration, expected };
+}
+
+// ── v3: rebase onto a moved mirror ──────────────────────────────────────────────────────────
+//
+// Every `set` action carries its merge base (`shadowBasis`: the remote ref of each subject it
+// touches, stamped at append) and push refuses on drift against it. A changeset authored before
+// the mirror moved is therefore unapplicable after a fetch — correct, and until v3 terminal.
+// `rebaseChangeset` is the merge: per action, the current refs of its subjects are read in the
+// authoring world; an unmoved basis is carried; a moved basis has the action's preconditions
+// re-evaluated against the world's current projected state — pass: re-stamped and carried;
+// fail: a CONFLICT by subject, field, expected and actual, and the object is not rewritten. A
+// moved basis with no precondition is carried re-stamped and reported `rebased-blind`. The
+// rebased object keeps id, name, base and every action id; its hash moves (the actions moved),
+// so approvals drop and the verification is stale — a rebase is a re-review.
+
+
+export type ApplyReceipt = {
+  actionId: string;
+  service: string;
+  stateService: string;
+  status: 'confirmed' | 'replayed' | 'failed' | 'skipped';
+  pushId?: string;
+  externalId?: string;
+  url?: string;
+  error?: string;
+};
+export type CompensationEntry = {
+  service: string;
+  actionId: string;
+  subject: { type: string; id: string };
+  externalId?: string;
+  /** the action's own revert spec when it carries one, else the inverse on the vendor id */
+  revert: TwinActionRevertSpec | { strategy: 'inverse' };
+};
+/** How a push went: the receipts origin answered, recorded on the changeset object. */
+export type ChangesetApplication = {
+  at: string;
+  contentHash: string;
+  outcome: 'applied' | 'partial' | 'refused';
+  forced?: boolean;
+  refusal?: string[];
+  receipts: ApplyReceipt[];
+  compensation: CompensationEntry[];
+};
+
+export type RebaseTarget = { service: string; stateService: string; controlRoot: string };
+export type RebaseActionResult = {
+  actionId: string;
+  service: string;
+  status: 'unchanged' | 'rebased' | 'rebased-blind' | 'conflict';
+  moved?: Record<string, { base: string | null; current: string | null }>;
+  conflicts?: Array<{ subject: { type: string; id: string }; field: string; op: string; expected?: unknown; actual: unknown }>;
+};
+export type RebaseReport = { changeset: string; from: string; to: string | null; at: string; outcome: 'unchanged' | 'rebased' | 'conflict'; actions: RebaseActionResult[] };
+
+export function rebaseChangeset(changeset: Changeset, opts: { targets: RebaseTarget[]; at?: string }): { changeset: Changeset; report: RebaseReport } {
+  return withAncestryLock(() => rebaseChangesetLocked(changeset, opts));
+}
+function rebaseChangesetLocked(changeset: Changeset, opts: { targets: RebaseTarget[]; at?: string }): { changeset: Changeset; report: RebaseReport } {
+  const at = opts.at ?? new Date().toISOString();
+  const targetFor = new Map(opts.targets.map((t) => [t.service, t]));
+  // PROTOCOL 2: what the parent did since the cut, per service — the entries past the cut position.
+  // A set action conflicts where the parent set the same field of the same subject to something
+  // else; a subject the parent touched otherwise is rebased; the rest is unchanged.
+  const sinceCut = new Map<string, Entry[]>();
+  const aliases = new Map<string, Map<string, string>>();
+  for (const t of opts.targets) {
+    const cut = changeset.cut?.[t.service] ?? changeset.cut?.[t.stateService];
+    if (!cut) continue;
+    const directory = worldPaths(t.stateService, t.controlRoot).dir;
+    const current = captureParentHistory(t.stateService, t.controlRoot);
+    aliases.set(t.service, aliasesFrom(historyEntries(readHistoryView(directory, current.view))));
+    sinceCut.set(t.service, historyChanges(t.stateService, historyPrefix(readHistoryView(directory, cut.view), cut.position), readHistoryView(directory, current.view)));
+  }
+  const stable = (v: unknown): string => JSON.stringify(v) ?? 'undefined';
+  // a field both sides set to an INSTANT is when each wrote, not what: never a conflict
+  const instant = (v: unknown): boolean => typeof v === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d/.test(v) && Number.isFinite(Date.parse(v));
+  const missing = [...new Set(changeset.actions.map((e) => e.service))].filter((s) => !targetFor.has(s));
+  if (missing.length) throw new Error(`Cannot rebase changeset "${changeset.name}": no target for ${missing.join(', ')}`);
+  const results: RebaseActionResult[] = [];
+  const actions: ChangesetAction[] = [];
+  for (const entry of changeset.actions) {
+    const target = targetFor.get(entry.service)!;
+    const action = entry.action;
+    const since = sinceCut.get(entry.service);
+    if (action.op === 'set' && since !== undefined) {
+      const mine = resolveReferences(target.stateService, action.subject.type, action.fields ?? {}, aliases.get(entry.service) ?? new Map());
+      const touching = since.filter((e) => e.op === 'set' && e.subject.type === action.subject.type && (e.subject.id === action.subject.id || e.aliasOf === action.subject.id));
+      const conflicts: NonNullable<RebaseActionResult['conflicts']> = [];
+      for (const e of touching) if (e.fields?.deleted === true && mine.deleted !== true) conflicts.push({ subject: action.subject, field: 'deleted', op: 'exists', expected: true, actual: false });
+      for (const e of touching) for (const [field, value] of Object.entries(e.fields ?? {})) if (field in mine && stable(mine[field]) !== stable(value) && !(instant(value) && instant(mine[field]))) conflicts.push({ subject: action.subject, field, op: 'set', expected: mine[field], actual: value });
+      if (conflicts.length) { actions.push(entry); results.push({ actionId: action.id, service: entry.service, status: 'conflict', conflicts }); continue; }
+      if (touching.length) { actions.push(entry); results.push({ actionId: action.id, service: entry.service, status: 'rebased' }); continue; }
+    }
+    actions.push(entry); results.push({ actionId: action.id, service: entry.service, status: 'unchanged' });
+  }
+  const conflict = results.some((r) => r.status === 'conflict');
+  const movedAny = results.some((r) => r.status === 'rebased' || r.status === 'rebased-blind');
+  if (conflict || !movedAny) {
+    return { changeset, report: { changeset: changeset.name, from: changeset.contentHash, to: null, at, outcome: conflict ? 'conflict' : 'unchanged', actions: results } };
+  }
+  // the cut moves to where the parent stands now: the hash moves with it
+  const cut = Object.fromEntries(opts.targets.map((t) => [t.service, captureParentHistory(t.stateService, t.controlRoot)]));
+  const core = { id: changeset.id, world: changeset.world, base: changeset.base, actions, verifiers: changeset.verifiers, cut };
+  const rebased: Changeset = { ...changeset, ...core, ...(changeset.narration === undefined ? {} : { narration: narrateActions(actions) }), contentHash: changesetContentHash(core), approvals: [], verification: null, rebasedFrom: { contentHash: changeset.contentHash, at } };
+  return { changeset: rebased, report: { changeset: changeset.name, from: changeset.contentHash, to: rebased.contentHash, at, outcome: 'rebased', actions: results } };
+}
+
+export function formatRebaseReport(report: RebaseReport): string {
+  const lines = [`Rebase of changeset ${report.changeset}: ${report.outcome}${report.to ? ` (${report.from} → ${report.to}; approvals dropped, verification stale — re-review)` : ''}`];
+  for (const r of report.actions) {
+    lines.push(`  ${r.status.padEnd(13)} ${r.service} ${r.actionId}${r.moved ? ` — moved: ${Object.keys(r.moved).join(', ')}` : ''}`);
+    for (const c of r.conflicts ?? []) lines.push(`      CONFLICT ${c.subject.type}:${c.subject.id}.${c.field} ${c.op}${'expected' in c ? ` ${JSON.stringify(c.expected)}` : ''} — actual ${JSON.stringify(c.actual)}`);
+  }
+  return `${lines.join('\n')}\n`;
+}