@volter/world-runtime 2.0.0

package/src/changeset.ts

@@ -0,0 +1,627 @@
+import { blobDigest, captureHistory, captureParentHistory, getActiveBlobStore, getActiveWorldStore, originHead, withAncestryLock, worldPaths, type HistoryReference } from '@volter/world-core';
+// `volter-world mark` / `diff` / `changeset` — the WORLD-side verbs over the changeset
+// primitive (docs/concepts/the-model.md v0). Thin, exactly like `covers` and `tail` are thin: all
+// the state logic (markers, deltas, content hashing, replay) lives in @volter/world-core's
+// control-plane, beside the `actions.jsonl` ledgers it reads. What lives HERE is the only thing
+// the control plane cannot know — where a world keeps its twins' data, and where a world keeps
+// its own marks and changesets.
+//
+// Discovery mirrors `tail.ts`: a world service's ledgers are
+// `<data>/<service>/<state-dir>/world/<state-service>/actions.jsonl`, and one world service may
+// record under more than one state service. Re-discovered on every call, because a twin's ledger
+// dir does not exist until its first action.
+//
+// STORAGE. Marks and changesets are the world's own artifacts, so they live in the world's state
+// dir beside `instance.json`: `.volter/worlds/<world>/{marks,changesets}/<name>.json`. That makes
+// a changeset share its world's lifecycle — `down --purge` takes the twin data AND the changesets
+// cut from it, which is the honest coupling (a changeset whose ledgers were purged is a fossil).
+// `changeset show|replay|list` take a bare name because a changeset is world-scoped but
+// world-PORTABLE: they scan every world's changeset dir, and an ambiguous name is a loud error
+// asking for `--world`, never a silent pick.
+//
+// Read-only over the twins' data at rest, like `tail` — except `replay`, which is the one verb
+// here that WRITES, and it writes only through the control plane's kernel write path.
+import { tmpdir } from 'node:os';
+import { join, relative, resolve } from 'node:path';
+import {
+  approveChangeset,
+  rebaseChangeset,
+  buildChangeset,
+  captureMarker,
+  changesetHashMatches,
+  changesetReadiness,
+  diffLedgers,
+  normalizeChangeset,
+  replayChangeset,
+  runChangesetVerifiers,
+  stateDirName,
+  withApplication,
+  withVerification,
+  worldBootMarker,
+  assertSafeChangesetName,
+  assertMarkerBelongsTo,
+  CHANGESET_KIND,
+  MARKER_KIND,
+  WORLD_BOOT_MARKER_ID,
+} from '@volter/world-core';
+import type { ApplyReceipt, Receipt, ChangesetApplication, RebaseReport, RebaseTarget, Changeset, ChangesetApproval, ChangesetReadiness, ChangesetVerification, ChangesetVerifier, LedgerDelta, LedgerRef, ReplayReport, ReplayTarget, WorldMarker } from '@volter/world-core';
+import { instanceDir, listWorlds, saveWorldInstance, statusWorld } from './runtime.ts';
+import { fetchFromOrigin } from './origin.ts';
+import type { WorldInstance } from './schema.ts';
+import { fetchReady, isPathRemote, landChangeset, landReceipts, localWorld, TOKEN_HEADER } from './served-world.ts';
+import { loadWorldChecks } from './root.ts';
+import { originEntries, parentEntries, readBranchMeta, readTree, rebaseBranch, runChecks, wholeLog, writeBranchMeta } from '@volter/world-core';
+
+export type WorldRootOptions = { root?: string };
+
+function resolveRoot(root?: string): string {
+  return resolve(root ?? process.cwd());
+}
+
+/** The world instance, or a loud error that names what this repo actually has. `statusWorld`'s
+ *  own "not found" is correct but bare; a verb an operator reaches for by name should say which
+ *  names exist. */
+function requireWorld(name: string, root: string): WorldInstance {
+  try {
+    return statusWorld(name, root);
+  } catch (error) {
+    if (!/World instance not found/.test(String((error as Error).message))) throw error;
+    const known = listWorlds(root).map((world) => world.name);
+    throw new Error(`World "${name}" not found in ${root}${known.length ? ` (known worlds: ${known.join(', ')})` : ' (no worlds here)'} — boot it with \`volter-world up <config> --env-file <path> --name ${name}\``);
+  }
+}
+
+/** Every state service a world service currently records actions under (often exactly one). */
+function stateServicesFor(controlRoot: string): string[] {
+  const stateRoot = join(controlRoot, stateDirName(), 'world');
+  const store = getActiveWorldStore();
+  return store.list(stateRoot)
+    .filter((name) => store.stat(join(stateRoot, name))?.isDirectory && ['actions.jsonl', 'events.jsonl', 'branch.json'].some((f) => store.exists(join(stateRoot, name, f))))
+    .sort();
+}
+
+/** Every action ledger in a world, as control-plane ledger references. */
+export function worldLedgers(name: string, root?: string): LedgerRef[] {
+  const resolvedRoot = resolveRoot(root);
+  const instance = requireWorld(name, resolvedRoot);
+  const ledgers: LedgerRef[] = [];
+  for (const service of Object.keys(instance.services).sort()) {
+    const controlRoot = join(instance.dirs.data, service);
+    for (const stateService of stateServicesFor(controlRoot)) {
+      ledgers.push({ service, stateService, controlRoot });
+    }
+  }
+  return ledgers;
+}
+
+// ── marks ──────────────────────────────────────────────────────────────────────────────────────
+
+export function worldMarksDir(name: string, root?: string): string {
+  return join(instanceDir(resolveRoot(root), name), 'marks');
+}
+
+export function worldChangesetsDir(name: string, root?: string): string {
+  return join(instanceDir(resolveRoot(root), name), 'changesets');
+}
+
+/** `mark-<compact-utc>-<rand>` — sortable by name, collision-free within a millisecond. */
+function defaultMarkerId(now: Date): string {
+  const stamp = now.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+  return `mark-${stamp}-${Math.random().toString(36).slice(2, 6)}`;
+}
+
+/** Capture a cross-service base marker for `world` and persist it. */
+/** A world mark with the note it was taken with, if any: what the moment was, in words (a commit's message). The
+ *  note is the runtime's, beside world-core's marker, which reads no field of it. */
+export type NotedMarker = WorldMarker & { note?: string };
+
+/** The longest note a mark keeps; a longer one is cut. */
+export const MARK_NOTE_MAX = 600;
+
+export function markWorld(name: string, options: WorldRootOptions & { id?: string; now?: Date; note?: string } = {}): NotedMarker {
+  const root = resolveRoot(options.root);
+  requireWorld(name, root);
+  const now = options.now ?? new Date();
+  const id = options.id ?? defaultMarkerId(now);
+  assertSafeChangesetName(id, 'marker');
+  const captured = captureMarker({ id, world: name, ledgers: worldLedgers(name, root), createdAt: now.toISOString() });
+  const note = options.note?.trim().slice(0, MARK_NOTE_MAX);
+  const marker: NotedMarker = note ? { ...captured, note } : captured;
+  getActiveWorldStore().writeAtomic(join(worldMarksDir(name, root), `${id}.json`), `${JSON.stringify(marker, null, 2)}\n`);
+  return marker;
+}
+
+/** Every mark recorded in a world, oldest first. */
+export function listWorldMarks(name: string, root?: string): NotedMarker[] {
+  const dir = worldMarksDir(name, root);
+  return getActiveWorldStore().list(dir)
+    .filter((file) => file.endsWith('.json'))
+    .map((file) => readMarkerFile(join(dir, file)))
+    .sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : a.id < b.id ? -1 : 1));
+}
+
+function readMarkerFile(path: string): NotedMarker {
+  const marker = JSON.parse(readStored(path)) as NotedMarker;
+  if (marker.kind !== MARKER_KIND) throw new Error(`${path}: not a world marker (kind=${JSON.stringify(marker.kind)})`);
+  return marker;
+}
+
+/**
+ * The base a diff/changeset is taken against:
+ *   explicit `--base <id>` → that mark (which must belong to THIS world),
+ *   otherwise the world's most recent mark,
+ *   otherwise `world-boot` — position 0 on every ledger, i.e. everything this world recorded.
+ *
+ * `--base world-boot` is spellable explicitly, so "show me the whole session" never requires
+ * deleting marks.
+ */
+export function resolveBaseMarker(name: string, options: WorldRootOptions & { base?: string } = {}): WorldMarker {
+  const root = resolveRoot(options.root);
+  const instance = requireWorld(name, root);
+  const boot = (): WorldMarker => worldBootMarker(name, instance.createdAt);
+  if (options.base === WORLD_BOOT_MARKER_ID) return boot();
+  if (options.base) {
+    // A marker id may address a mark in ANOTHER world — read it wherever it lives so the
+    // cross-world case fails with "captured in world X, not Y" rather than "no such mark".
+    const found = findMarkerAnywhere(root, options.base);
+    if (!found) {
+      const known = listWorldMarks(name, root).map((mark) => mark.id);
+      throw new Error(`No marker "${options.base}" (world "${name}" has: ${known.length ? known.join(', ') : 'no marks yet — run `volter-world mark ' + name + '`'})`);
+    }
+    assertMarkerBelongsTo(found, name);
+    return found;
+  }
+  const marks = listWorldMarks(name, root);
+  return marks.length ? marks[marks.length - 1]! : boot();
+}
+
+/** Look for a marker id in every world under `root` — the seam that makes a wrong-world base a
+ *  precise error instead of a confusing "not found". */
+function findMarkerAnywhere(root: string, id: string): WorldMarker | null {
+  for (const world of listWorlds(root)) {
+    const path = join(worldMarksDir(world.name, root), `${id}.json`);
+    if (getActiveWorldStore().exists(path)) return readMarkerFile(path);
+  }
+  return null;
+}
+
+// ── diff ───────────────────────────────────────────────────────────────────────────────────────
+
+/** The world's ledger delta since `base` (default: the last mark, else world-boot). */
+export function diffWorld(name: string, options: WorldRootOptions & { base?: string } = {}): LedgerDelta {
+  const root = resolveRoot(options.root);
+  const base = resolveBaseMarker(name, { root, ...(options.base === undefined ? {} : { base: options.base }) });
+  return diffLedgers({ world: name, ledgers: worldLedgers(name, root), base });
+}
+
+// ── changesets ─────────────────────────────────────────────────────────────────────────────────
+
+export type ChangesetLocation = { changeset: Changeset; world: string; path: string };
+
+/** Freeze the current delta into `<world>/changesets/<name>.json`. */
+export function createWorldChangeset(
+  world: string,
+  name: string,
+  options: WorldRootOptions & { base?: string; verifiers?: ChangesetVerifier[]; now?: Date; overwrite?: boolean; message?: string } = {},
+): Changeset {
+  const root = resolveRoot(options.root);
+  assertSafeChangesetName(name);
+  const dir = worldChangesetsDir(world, root);
+  const path = join(dir, `${name}.json`);
+  if (getActiveWorldStore().exists(path) && !options.overwrite) {
+    throw new Error(`Changeset "${name}" already exists in world "${world}" (${path}) — pick another name, or pass --force to replace it`);
+  }
+  // re-cutting an existing name (overwrite) starts from that changeset's own base, not from its cut
+  const base = options.base ?? (getActiveWorldStore().exists(path) ? readChangesetFile(path).base : undefined);
+  const delta = diffWorld(world, { root, ...(base === undefined ? {} : { base }) });
+  // where the parent log stands for each twin the changeset touches (PROTOCOL 2: the cut position a rebase reads from)
+  const cutInstance = requireWorld(world, root);
+  const cut: Record<string, HistoryReference> = {};
+  for (const a of delta.actions) if (!(a.service in cut)) { const cr = join(cutInstance.dirs.data, a.service); const st = a.stateService ?? a.service; cut[a.service] = captureParentHistory(st, cr); }
+  const changeset = buildChangeset({
+    name,
+    world,
+    base: delta.base.id,
+    actions: delta.actions,
+    cut,
+    ...(options.verifiers ? { verifiers: options.verifiers } : {}),
+    ...(options.now ? { createdAt: options.now.toISOString() } : {}),
+    ...(options.message === undefined ? {} : { message: options.message }),
+  });
+  getActiveWorldStore().write(path, `${JSON.stringify(changeset, null, 2)}\n`);
+  // a changeset records where the log was cut (contract "The model"): the next one starts here
+  markWorld(world, { root, id: `cut-${name}`, ...(options.now ? { now: options.now } : {}) });
+  return changeset;
+}
+
+function readChangesetFile(path: string): Changeset {
+  const changeset = JSON.parse(readStored(path)) as Changeset;
+  if (changeset.kind !== CHANGESET_KIND) throw new Error(`${path}: not a changeset (kind=${JSON.stringify(changeset.kind)})`);
+  // a v0 object lacks the v1 lifecycle fields on disk; filling them is hash-neutral
+  return normalizeChangeset(changeset);
+}
+
+/** Persist a changeset back where it was found — verify/approve write THROUGH this, so the
+ *  object on disk is always the object the verbs returned. */
+function writeChangesetFile(path: string, changeset: Changeset): void {
+  getActiveWorldStore().write(path, `${JSON.stringify(changeset, null, 2)}\n`);
+}
+
+/** A world file's content through the active store; a missing file is an error naming it. */
+function readStored(path: string): string {
+  const text = getActiveWorldStore().read(path);
+  if (text === null) throw new Error(`ENOENT: no such file, open '${path}'`);
+  return text;
+}
+
+/** Every changeset in every world under `root` (or one world with `world`), newest first. */
+export function listWorldChangesets(options: WorldRootOptions & { world?: string } = {}): ChangesetLocation[] {
+  const root = resolveRoot(options.root);
+  const worldNames = options.world ? [options.world] : listWorlds(root).map((world) => world.name);
+  const found: ChangesetLocation[] = [];
+  for (const world of worldNames) {
+    const dir = worldChangesetsDir(world, root);
+    for (const file of getActiveWorldStore().list(dir).filter((entry) => entry.endsWith('.json')).sort()) {
+      const path = join(dir, file);
+      found.push({ changeset: readChangesetFile(path), world, path });
+    }
+  }
+  return found.sort((a, b) => (a.changeset.createdAt > b.changeset.createdAt ? -1 : a.changeset.createdAt < b.changeset.createdAt ? 1 : 0));
+}
+
+/** Resolve a bare changeset name across worlds. Ambiguity is an error, never a guess. */
+export function findWorldChangeset(name: string, options: WorldRootOptions & { world?: string } = {}): ChangesetLocation {
+  const root = resolveRoot(options.root);
+  assertSafeChangesetName(name);
+  const matches = listWorldChangesets({ root, ...(options.world ? { world: options.world } : {}) }).filter((entry) => entry.changeset.name === name);
+  if (matches.length === 1) return matches[0]!;
+  if (matches.length > 1) {
+    throw new Error(`Changeset "${name}" exists in more than one world (${matches.map((m) => m.world).sort().join(', ')}) — disambiguate with --world <name>`);
+  }
+  const known = listWorldChangesets({ root, ...(options.world ? { world: options.world } : {}) });
+  const scope = options.world ? `world "${options.world}"` : `${root}`;
+  throw new Error(`No changeset "${name}" in ${scope} (have: ${known.length ? known.map((entry) => `${entry.changeset.name} [${entry.world}]`).join(', ') : 'none — create one with `volter-world changeset create <world> <name>`'})`);
+}
+
+// ── replay ─────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Which state service a replayed action lands in for a given target world service:
+ * the changeset's own state service when the target already records under it (or records
+ * nothing yet — a fresh world, the CI case), the target's single existing state service when
+ * it uses a different name, and a loud error when the target records under several and none of
+ * them is the one the changeset names (there is no correct guess there).
+ */
+function resolveTargetStateService(into: string, service: string, controlRoot: string, wanted: string): string {
+  const existing = stateServicesFor(controlRoot);
+  if (existing.length === 0 || existing.includes(wanted)) return wanted;
+  if (existing.length === 1) return existing[0]!;
+  throw new Error(`World "${into}" service "${service}" records actions under multiple state services (${existing.join(', ')}) and none is "${wanted}" — cannot decide where to replay`);
+}
+
+/** The replay targets a changeset needs inside an existing world (services the world lacks are
+ *  left out — `replayChangeset` reports them loudly by name). */
+function worldReplayTargets(changeset: Changeset, into: string, root: string): { targets: ReplayTarget[]; available: string[]; dataDir: string } {
+  const instance = requireWorld(into, root);
+  const available = Object.keys(instance.services).sort();
+  const targets: ReplayTarget[] = [];
+  for (const service of [...new Set(changeset.actions.map((entry) => entry.service))]) {
+    if (!instance.services[service]) continue; // reported as a missing twin by replayChangeset
+    const controlRoot = join(instance.dirs.data, service);
+    const wanted = changeset.actions.find((entry) => entry.service === service)!.stateService;
+    targets.push({ service, stateService: resolveTargetStateService(into, service, controlRoot, wanted), controlRoot });
+  }
+  return { targets, available, dataDir: instance.dirs.data };
+}
+
+/** Replay a changeset into `into`'s twins, through the control plane's kernel write path. */
+export async function replayWorldChangeset(
+  name: string,
+  options: WorldRootOptions & { into: string; world?: string },
+): Promise<ReplayReport> {
+  const root = resolveRoot(options.root);
+  const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+  const { targets, available } = worldReplayTargets(located.changeset, options.into, root);
+  return replayChangeset(located.changeset, { into: options.into, targets, available });
+}
+
+// ── verify / approve / status — the operational-PR contract (v1) ───────────────────────────────
+
+export type VerifyWorldOutcome = {
+  changeset: Changeset;
+  verification: ChangesetVerification;
+  report: ReplayReport;
+  world: string;
+  path: string;
+};
+
+/** The label a throwaway verify target reports as `into` — not a world name on purpose. */
+export const EPHEMERAL_VERIFY_TARGET = 'ephemeral';
+
+/**
+ * `volter-world changeset verify <name> --into <world> | --ephemeral`: replay the changeset
+ * into a clean target, run its verifiers against the post-replay projected state, and record
+ * the outcome ON the object as `verification` — REPLACING any prior run (the record carries
+ * its own provenance: when, into what, against which body hash and world digest). The body
+ * hash never moves: verification is about-the-body metadata, like approvals.
+ *
+ * `--ephemeral` builds a throwaway replay target (fresh empty ledgers per twin, no world
+ * booted), verifies against it, and removes it — the zero-setup CI check. `--into` verifies
+ * inside an existing world, whose twins must cover the changeset AND its verifiers.
+ */
+export async function verifyWorldChangeset(
+  name: string,
+  options: WorldRootOptions & { into?: string; ephemeral?: boolean; world?: string; now?: Date },
+): Promise<VerifyWorldOutcome> {
+  const root = resolveRoot(options.root);
+  if (Boolean(options.into) === Boolean(options.ephemeral)) {
+    throw new Error('volter-world changeset verify: pass exactly one of --into <world> (verify inside an existing world) or --ephemeral (a throwaway replay target)');
+  }
+  const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+  const changeset = located.changeset;
+  if (!changesetHashMatches(changeset)) {
+    throw new Error(`Refusing to verify changeset "${name}": its stored contentHash does not match its body — the object drifted after authoring, and a verification would launder that drift`);
+  }
+
+  const intoLabel = options.into ?? EPHEMERAL_VERIFY_TARGET;
+  let scratch: string | null = null;
+  let targets: ReplayTarget[];
+  let available: string[] | undefined;
+  if (options.into) {
+    const resolved = worldReplayTargets(changeset, options.into, root);
+    targets = resolved.targets;
+    available = resolved.available;
+    // a verifier may check a twin the actions never touched — it still needs a real target
+    for (const verifier of changeset.verifiers) {
+      if (targets.some((target) => target.service === verifier.service)) continue;
+      if (!available.includes(verifier.service)) {
+        throw new Error(`Cannot verify changeset "${name}" in world "${options.into}": verifier "${verifier.id}" checks twin "${verifier.service}", which that world does not have (world "${options.into}" has: ${available.join(', ') || 'no services'})`);
+      }
+      const controlRoot = join(resolved.dataDir, verifier.service);
+      targets.push({ service: verifier.service, stateService: resolveTargetStateService(options.into, verifier.service, controlRoot, verifier.service), controlRoot });
+    }
+  } else {
+    scratch = join(tmpdir(), `volter-world-verify-${crypto.randomUUID()}`);
+    const pairs = new Map<string, ReplayTarget>();
+    for (const entry of changeset.actions) {
+      pairs.set(`${entry.service} ${entry.stateService}`, { service: entry.service, stateService: entry.stateService, controlRoot: join(scratch, entry.service) });
+    }
+    for (const verifier of changeset.verifiers) {
+      if (![...pairs.values()].some((target) => target.service === verifier.service)) {
+        pairs.set(`${verifier.service} ${verifier.service}`, { service: verifier.service, stateService: verifier.service, controlRoot: join(scratch, verifier.service) });
+      }
+    }
+    targets = [...pairs.values()];
+  }
+
+  try {
+    const report = await replayChangeset(changeset, { into: intoLabel, targets, ...(available ? { available } : {}) });
+    const at = (options.now ?? new Date()).toISOString();
+    const verification = runChangesetVerifiers(changeset, targets, { at, into: intoLabel });
+    // the world's checks (CI on deployment): every entry, against the replayed tree
+    const checks = await loadWorldChecks(root);
+    const refusals: NonNullable<ChangesetVerification['refusals']> = [];
+    for (const entry of changeset.actions) {
+      const target = targets.find((t) => t.service === entry.service && t.stateService === entry.stateService) ?? targets.find((t) => t.service === entry.service);
+      const verdict = await runChecks(checks, entry.action, target ? readTree(target.stateService, target.controlRoot) : []);
+      if (verdict) refusals.push({ actionId: entry.action.id, service: entry.service, check: verdict.name, reason: verdict.reason });
+    }
+    if (refusals.length) { verification.refusals = refusals; verification.passed = false; }
+    const updated = withVerification(changeset, verification);
+    writeChangesetFile(located.path, updated);
+    return { changeset: updated, verification, report, world: located.world, path: located.path };
+  } finally {
+    if (scratch) getActiveWorldStore().remove(scratch);
+  }
+}
+
+export type ApproveWorldOutcome = {
+  changeset: Changeset;
+  approval: ChangesetApproval;
+  world: string;
+  path: string;
+};
+
+/** `volter-world changeset approve <name> --as <principal>`: append an approval bound to the
+ *  current body hash. The control plane refuses a drifted object loudly. */
+export function approveWorldChangeset(
+  name: string,
+  options: WorldRootOptions & { principal: string; note?: string; world?: string; now?: Date },
+): ApproveWorldOutcome {
+  const root = resolveRoot(options.root);
+  const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+  const { changeset, approval } = approveChangeset(located.changeset, {
+    principal: options.principal,
+    ...(options.note ? { note: options.note } : {}),
+    ...(options.now ? { at: options.now.toISOString() } : {}),
+  });
+  writeChangesetFile(located.path, changeset);
+  return { changeset, approval, world: located.world, path: located.path };
+}
+
+/** `volter-world changeset status <name>`: the apply-readiness gate, recomputed from the
+ *  object. Truth only — pushing is v2's job. */
+export function statusWorldChangeset(
+  name: string,
+  options: WorldRootOptions & { world?: string } = {},
+): ChangesetReadiness {
+  const root = resolveRoot(options.root);
+  const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+  return changesetReadiness(located.changeset);
+}
+
+// ── governed push: `volter-world changeset push` ─────────────────────────────────────────
+//
+// A local world never holds a vendor credential (docs/concepts/the-model.md: a deployment exists
+// only where the sealed credential lives). A push goes to the REMOTE — the hosted twin, the
+// world's origin — through its push door with a twins key; the remote refreshes, deploys the
+// changeset to the vendor with its own keys, and answers with the receipts, which are recorded on
+// the object here.
+
+export type PushWorldOptions = WorldRootOptions & {
+  world?: string;
+  /** the remote's twins url and namespace; default to the world's recorded origin */
+  to?: string;
+  namespace?: string;
+  /** the namespace key (a push is a write; the read key is refused) */
+  key: string;
+  force?: boolean;
+};
+export type PushWorldOutcome = { application: ChangesetApplication; changeset: Changeset; world: string; path: string; remote: { url: string; namespace: string }; /** the entries landed; these named records did not follow them (a warning, not a refusal) */ unsent?: string };
+
+export async function pushWorldChangeset(name: string, options: PushWorldOptions): Promise<PushWorldOutcome> {
+  // PUSH (docs/concepts/the-model.md): the changeset goes to the served world's push door; its
+  // entries land on that world's log, and each receipt (landed under gated/hold, deployed/refused/
+  // failed under auto) is landed here on the parent log too, so `log --receipts` shows it and the
+  // entry stops being unpushed. The changeset object records the application as before.
+  const root = resolveRoot(options.root);
+  const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+  const instance = requireWorld(located.world, root);
+  const url = (options.to ?? instance.origin?.url)?.replace(/\/+$/, '');
+  const namespace = options.namespace ?? instance.origin?.namespace;
+  if (!url || !namespace) throw new Error(`World "${located.world}" has no origin to push to — \`volter remote add origin <url> --token <token>\` names one`);
+  // over http to a served world's push door, or straight into a world at a path (git's file transport)
+  let res: { ok: boolean; status: number }; let body: { receipts?: Array<{ actionId: string; twin: string } & Receipt>; error?: string; refusal?: string[]; position?: Record<string, number>; snapshots?: Record<string, HistoryReference> };
+  const expect: Record<string, HistoryReference> = {};
+  for (const a of located.changeset.actions) {
+    const meta = readBranchMeta(a.stateService ?? a.service, join(instance.dirs.data, a.service));
+    const pointer = meta?.origin ?? meta?.parent;
+    if (meta?.origin?.incomplete) throw new Error('The branch cuts through its tracked origin; pull and rebase before pushing');
+    const view = isPathRemote(url) ? pointer?.view : pointer?.remoteView;
+    if (pointer && view) expect[a.service] = { view, position: pointer.position };
+  }
+  // THE RESOURCE PAYLOADS the entries name (uploaded media, file bytes), in two phases. Content-addressed
+  // blobs (a key segment that IS a sha256) never change, so they go before the entries: a refused push
+  // leaves only bytes nothing names yet. Records kept by name (an upload's status, a media record) are the
+  // branch's state moving forward and go only after the entries landed, so a push the origin refuses
+  // (drift) never overwrites the origin's newer records.
+  const blobs = getActiveBlobStore();
+  const twins = [...new Map(located.changeset.actions.map((a) => [a.service, a.stateService ?? a.service])).entries()];
+  const ownBlobs = async (twin: string, state: string): Promise<Array<{ key: string; path: string }>> => {
+    const dir = worldPaths(state, join(instance.dirs.data, twin)).resources;
+    return (await blobs.list(dir)).map((path) => ({ key: relative(dir, path).split('\\').join('/'), path }));
+  };
+  // content-addressed means a segment of the key IS the digest of the bytes it holds: such bytes never
+  // change. A name built on a digest of something else (a record keyed by a hash of an action id, a
+  // type keyed by its blob's digest) may change, so it is a record kept by name.
+  // each blob is read and hashed once per push, and a key with no 64-hex segment is never read to classify it
+  const digests = new Map<string, string | null>();
+  const digestOf = async (path: string): Promise<string | null> => {
+    if (!digests.has(path)) { const bytes = await blobs.get(path); digests.set(path, bytes === null ? null : blobDigest(bytes)); }
+    return digests.get(path)!;
+  };
+  const contentAddressed = async (key: string, path: string): Promise<boolean> => {
+    if (!key.split('/').some((seg) => /^[0-9a-f]{64}$/.test(seg))) return false;
+    const digest = await digestOf(path);
+    return digest !== null && key.split('/').includes(digest);
+  };
+  const sendBlobs = async (phase: 'content' | 'named'): Promise<void> => {
+    const wanted = async (key: string, path: string): Promise<boolean> => (phase === 'content') === (await contentAddressed(key, path));
+    if (isPathRemote(url)) {
+      const target = localWorld(url);
+      for (const [twin, state] of twins) {
+        const there = worldPaths(state, join(target.instance.dirs.data, twin)).resources;
+        for (const { key, path } of await ownBlobs(twin, state)) {
+          if (!(await wanted(key, path))) continue;
+          const held = await blobs.get(join(there, key));
+          if (held !== null && blobDigest(held) === (await digestOf(path))) continue;
+          const bytes = await blobs.get(path);
+          if (bytes) await blobs.put(join(there, key), bytes);
+        }
+      }
+      return;
+    }
+    for (const [twin, state] of twins) {
+      for (const { key, path } of await ownBlobs(twin, state)) {
+        if (!(await wanted(key, path))) continue;
+        const at = `${url}/-/${namespace}/blobs/${twin}/${key.split('/').map(encodeURIComponent).join('/')}`;
+        const head = await fetch(at, { method: 'HEAD', headers: { [TOKEN_HEADER]: options.key } });
+        // no blobs door for this twin there (older code, or the twin is not in that World): it takes entries only
+        if (head.status === 404 && head.headers.get('x-volter-blob') !== 'absent') break;
+        if (head.status === 200 && head.headers.get('x-volter-blob-sha256') === (await digestOf(path))) continue;
+        const bytes = await blobs.get(path);
+        if (!bytes) continue;
+        const put = await fetch(at, { method: 'PUT', headers: { [TOKEN_HEADER]: options.key, 'content-type': 'application/octet-stream' }, body: new Blob([bytes as Uint8Array<ArrayBuffer>]) });
+        if (!put.ok) throw new Error(`push: the origin refused ${twin}'s ${key} (${put.status} ${(await put.text()).slice(0, 200)})`);
+      }
+    }
+  };
+  await sendBlobs('content');
+  if (isPathRemote(url)) {
+    try { const target = localWorld(url);
+      const receipts = await landChangeset(target.name, target.root, target.instance, located.changeset, expect); const position = Object.fromEntries([...new Set(located.changeset.actions.map((a) => a.service))].map((twin) => { const st = located.changeset.actions.find((e) => e.service === twin)?.stateService ?? twin; return [twin, wholeLog(st, join(target.instance.dirs.data, twin)).length]; })); const snapshots = Object.fromEntries(Object.keys(position).map(twin => { const state = located.changeset.actions.find(a => a.service === twin)?.stateService ?? twin; const head = captureHistory(state, join(target.instance.dirs.data, twin)); return [twin, { view: head.view, position: head.position }]; })); body = { receipts, position, snapshots }; res = { ok: true, status: 200 }; }
+    catch (error) { body = { error: error instanceof Error ? error.message : String(error) }; res = { ok: false, status: 409 }; }
+  } else {
+    // the client's position on each twin rides along (its fetch cursor): the door refuses when origin moved past it
+    const answer = await fetchReady(`${url}/-/${namespace}/push`, { method: 'POST', headers: { [TOKEN_HEADER]: options.key, 'content-type': 'application/json' }, body: JSON.stringify({ changeset: located.changeset, expect }) });
+    body = (await answer.json()) as typeof body; res = { ok: answer.ok, status: answer.status };
+  }
+  const at = new Date().toISOString();
+  if (!res.ok || !body.receipts) {
+    const refusal = body.refusal ?? [body.error ?? `the remote answered ${res.status}`];
+    const application: ChangesetApplication = { at, contentHash: located.changeset.contentHash, outcome: 'refused', refusal, receipts: [], compensation: [] };
+    writeChangesetFile(located.path, withApplication(located.changeset, application));
+    return { application, changeset: withApplication(located.changeset, application), world: located.world, path: located.path, remote: { url, namespace } };
+  }
+
+  // the entries landed: the records they name follow (retried; a failure is reported only after this
+  // push's application and receipts are recorded, so the entries that landed are never forgotten here)
+  let namedFailure: unknown = null;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try { await sendBlobs('named'); namedFailure = null; break; } catch (error) { namedFailure = error; }
+  }
+  // origin advanced by what landed (and what it performed): the cursor moves with it, so the next
+  // fetch and the next push start from where origin now stands
+  if (body.snapshots && instance.origin) {
+    const twins = Object.keys(body.snapshots);
+    const fetched = await fetchFromOrigin(located.world, { root, url, namespace, key: options.key, services: twins, views: body.snapshots });
+    for (const twin of twins) {
+      const st = located.changeset.actions.find(e => e.service === twin)?.stateService ?? twin; const cr = join(instance.dirs.data, twin);
+      const meta = readBranchMeta(st, cr); if (!meta?.parent) continue;
+      if (meta.origin) rebaseBranch(st, cr, { origin: true });
+      else {
+        const snapshot = fetched.snapshots[twin]!;
+        writeBranchMeta(st, { ...meta, parent: { ...meta.parent, ...snapshot } }, cr);
+      }
+    }
+  }
+  // land each receipt on this world's parent log, per twin's state service
+  const byTwin = new Map<string, Array<{ actionId: string } & Receipt>>();
+  for (const r of body.receipts) byTwin.set(r.twin, [...(byTwin.get(r.twin) ?? []), r]);
+  for (const [twin, receipts] of byTwin) {
+    const entry = located.changeset.actions.find((e) => e.service === twin);
+    const state = entry?.stateService ?? twin;
+    landReceipts(join(instance.dirs.data, twin), state, receipts, at);
+  }
+  const statusOf = (s: Receipt['status']): ApplyReceipt['status'] => (s === 'deployed' ? 'confirmed' : s === 'landed' ? 'replayed' : s === 'refused' || s === 'failed' ? 'failed' : 'skipped');
+  const receipts: ApplyReceipt[] = body.receipts.map((r) => ({ actionId: r.actionId, service: r.twin, stateService: located.changeset.actions.find((e) => e.service === r.twin)?.stateService ?? r.twin, status: statusOf(r.status), ...(r.externalId ? { externalId: r.externalId } : {}), ...(r.reason ? { error: r.reason } : {}) }));
+  const outcome: ChangesetApplication['outcome'] = receipts.every((r) => r.status !== 'failed') ? 'applied' : receipts.some((r) => r.status === 'confirmed') ? 'partial' : 'refused';
+  const application: ChangesetApplication = { at, contentHash: located.changeset.contentHash, outcome, receipts, compensation: [], ...(outcome === 'refused' ? { refusal: receipts.filter((r) => r.error).map((r) => r.error!) } : {}) };
+  const changeset = withApplication(located.changeset, application);
+  writeChangesetFile(located.path, changeset);
+  const unsent = namedFailure ? `records the landed entries name did not reach the origin (${namedFailure instanceof Error ? namedFailure.message : String(namedFailure)}); the next push from this branch that touches ${twins.map(([t]) => t).join(', ')} sends them` : undefined;
+  return { ...(unsent ? { unsent } : {}), application, changeset, world: located.world, path: located.path, remote: { url, namespace } };
+}
+
+// ── v3: rebase ─────────────────────────────────────────────────────────────────────────────
+export type RebaseWorldOutcome = { changeset: Changeset; report: RebaseReport; world: string; path: string };
+/** `volter-world changeset rebase <name>`: the merge onto the authoring world's moved mirror. */
+export function rebaseWorldChangeset(name: string, options: WorldRootOptions & { world?: string; now?: Date } = {}): RebaseWorldOutcome {
+  const root = resolveRoot(options.root);
+  const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+  // the branch first: its pointer moves to the parent's current position (what a fetch brought in)
+  withAncestryLock(() => {
+    const inst = requireWorld(located.world, root);
+    for (const service of new Set(located.changeset.actions.map((e) => e.service))) {
+      const st = located.changeset.actions.find((e) => e.service === service)?.stateService ?? service;
+      const controlRoot = join(inst.dirs.data, service);
+      rebaseBranch(st, controlRoot, { origin: Boolean(readBranchMeta(st, controlRoot)?.origin) });
+    }
+  });
+  if (!changesetHashMatches(located.changeset)) throw new Error(`Refusing to rebase changeset "${name}": its stored contentHash does not match its body — the object drifted after authoring`);
+  const instance = requireWorld(located.world, root);
+  const targets: RebaseTarget[] = [...new Set(located.changeset.actions.map((entry) => entry.service))].map((service) => ({ service, stateService: located.changeset.actions.find((entry) => entry.service === service)!.stateService, controlRoot: join(instance.dirs.data, service) }));
+  const { changeset, report } = rebaseChangeset(located.changeset, { targets, ...(options.now ? { at: options.now.toISOString() } : {}) });
+  if (report.outcome === 'rebased') writeChangesetFile(located.path, changeset);
+  return { changeset, report, world: located.world, path: located.path };
+}