@volter/twin 0.1.0 → 0.1.1

package/src/changeset.ts

@@ -0,0 +1,807 @@
+// The changeset primitive — "commit" for operational reality (docs/OPERATIONAL_VCS.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. Determinism comes for free from a
+// property `applyTwinWrite` already has: its action id is CONTENT-DERIVED
+// (`twin:<service>:<operation>:<subjectId>:<occurredAt>:<hash(content)>[:<uniqueness>]`). Feed
+// back the same occurredAt/operation/subject/fields and the target ledger derives the SAME id,
+// so a re-replay is `appended: false` end to end — idempotent by construction, with no
+// replay-side bookkeeping. The uniqueness seam (billable occurrences that must not collapse)
+// survives because it is 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 { appendActionIfAbsent, checkPrecondition, listActions, projectedPreconditionValue, projectResources } from './actions.ts';
+import type { TwinAction, TwinActionPrecondition, TwinActionPreconditionOp } from './actions.ts';
+import { canonicalJson, hashFieldValue } from './shadow.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/OPERATIONAL_VCS.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[];
+};
+
+/** 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[];
+  /** real-vendor receipt ids after governed push — v2; null until then */
+  applied: unknown | null;
+  /** 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) => {
+      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'>>;
+
+/** 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;
+  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 }): 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 };
+  return {
+    kind: CHANGESET_KIND,
+    ...core,
+    name: opts.name,
+    createdAt: opts.createdAt ?? new Date().toISOString(),
+    verification: null,
+    approvals: [],
+    applied: null,
+    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' : 'yes'}`,
+  ];
+  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. 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}`;
+  if (action.id === prefix) return {};
+  if (action.id.startsWith(`${prefix}:`)) return { uniqueness: action.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 }),
+        },
+        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, shadowBasis: _foreignBasis, ...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`);
+  }
+  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`);
+  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`;
+}