@volter/world 2.0.0

package/src/sdk.test.ts

@@ -0,0 +1,92 @@
+// The vocabulary made executable: a World's
+// verbs over a booted world — every method a name for a core or kernel function.
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { parseOriginUrl, requireToken, storeToken, tokenFor, World } from './index.ts';
+import { useWorldCleanup, worlds } from '../../world-runtime/src/runtime-test-support.ts';
+
+const AT = '2026-09-05T12:00:00.000Z';
+useWorldCleanup();
+
+
+describe('World — the twins an app needs, running together', () => {
+  const SERVER = "require('node:http').createServer((_req,res)=>res.end('ok')).listen(Number(process.env.PORT),'127.0.0.1')";
+  /** An app root holding `.volter/world.json` — what `volter world init` writes, with process twins here. */
+  function appRoot(id: string): string {
+    const root = mkdtempSync(join(tmpdir(), 'sdk-world-'));
+    mkdirSync(join(root, '.volter'), { recursive: true });
+    writeFileSync(join(root, '.volter', 'world.json'), JSON.stringify({ id, services: ['stripe', 'slack'].map((service) => ({ id: service, type: 'process', command: 'node', args: ['-e', SERVER], env: { NODE_OPTIONS: '' }, portArg: false, rootArg: false })) }));
+    return root;
+  }
+
+  test('open from the cwd, up, status, changes through a repo, log, changeset with a message, branch, checkout, down resumes', async () => {
+    const root = appRoot('sdk-w');
+    // the world is found from any directory under the root, on its main branch
+    mkdirSync(join(root, 'src', 'deep'), { recursive: true });
+    expect(World.find(join(root, 'src', 'deep'))?.root).toBe(root);
+    expect(World.find(mkdtempSync(join(tmpdir(), 'sdk-nowhere-')))).toBeNull();
+    const world = World.open({ root });
+    expect(world.name).toBe('sdk-w');
+    expect(world.status()).toMatchObject({ running: false, origin: null, unpushed: 0, branches: [] });
+
+    await world.up({ seed: false });
+    worlds.push({ root, name: 'sdk-w' });
+    expect(world.status()).toMatchObject({ running: true, branch: 'sdk-w', branches: ['sdk-w'] });
+    expect(world.status().services.stripe?.url).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);
+    expect(world.status().envFile).toBe(join(root, '.volter', 'world.env'));
+
+    const stripe = world.repo('stripe');
+    await stripe.change({ operation: 'price.create', subjectType: 'price', subjectId: 'price_annual', fields: { unit_amount: 47000 }, occurredAt: AT, actor: { kind: 'agent' } });
+    expect(world.repos().map((r) => r.service).sort()).toEqual(['stripe']); // a twin appears once it has a ledger
+    expect(world.diff().total).toBe(1);
+    expect(world.log().map((e) => [e.service, e.operation, e.subject.id])).toEqual([['stripe', 'price.create', 'price_annual']]);
+    expect(world.status().unpushed).toBe(1);
+    // the changeset carries the author's message beside the generated summary, outside the hash
+    const cs = world.changeset({ message: 'annual price for the launch' });
+    expect(cs.name).toBe('annual-price-for-the-launch'); expect(cs.message).toBe('annual price for the launch'); // named from the message expect(cs.narration).toContain('price');
+    expect(cs.actions).toHaveLength(1); expect(world.changesets().map((c) => c.changeset.name)).toEqual(['annual-price-for-the-launch']);
+    expect(world.status().changesets).toEqual({ total: 1, pushed: 0 });
+    expect(world.readiness('annual-price-for-the-launch').ready).toBe(false);
+    expect(() => world.repo('nope')).toThrow(/has no twin "nope"/);
+    // the default data is the only origin: nothing to push to, nothing to fetch from
+    expect(world.origin()).toBeNull();
+    await expect(world.push()).rejects.toThrow(/default data cannot be pushed to/);
+    expect(() => world.fetch()).toThrow(/only origin is the default data/);
+
+    // a branch over the same mirrors with its own log, checked out; checkout switches back
+    const feature = await world.branch('feature');
+    worlds.push({ root, name: 'feature' });
+    expect(World.open({ root }).name).toBe('feature'); // .volter/current
+    expect(feature.repo('stripe').unpushed()).toEqual([]); // the base's unpushed change stays on the base
+    await feature.repo('stripe').change({ operation: 'price.update', subjectType: 'price', subjectId: 'price_annual', fields: { unit_amount: 1 }, occurredAt: AT, actor: { kind: 'agent' } });
+    const back = await feature.checkout('sdk-w');
+    expect(back.name).toBe('sdk-w'); expect(World.open({ root }).name).toBe('sdk-w');
+    expect(back.status().running).toBe(true); expect(World.open({ root, name: 'feature' }).status().running).toBe(false);
+    expect(back.unpushed()).toHaveLength(1);
+    await expect(back.checkout('nonesuch')).rejects.toThrow(/No branch "nonesuch"/);
+
+    // down stops compute; up resumes the branch WITH its state (reset is the way back to the defaults)
+    await back.down();
+    expect(back.status().running).toBe(false);
+    await back.up();
+    expect(back.status().running).toBe(true);
+    expect(back.unpushed()).toHaveLength(1);
+    await back.down();
+  });
+
+  test('a remote URL names one world; tokens live in the user\'s config dir, never in the repo', () => {
+    expect(parseOriginUrl('https://twins.example.com/acme/web')).toEqual({ url: 'https://twins.example.com', namespace: 'acme/web' });
+    expect(() => parseOriginUrl('https://twins.example.com/acme')).toThrow(/names one world/);
+    expect(() => parseOriginUrl('not a url')).toThrow(/Not a remote URL/);
+    const store = join(mkdtempSync(join(tmpdir(), 'sdk-cred-')), 'credentials.json');
+    expect(tokenFor('https://twins.example.com', store)).toBeUndefined();
+    expect(() => requireToken('https://twins.example.com', undefined, store)).toThrow(/No token stored/);
+    storeToken('https://twins.example.com/', 'tok_read', store);
+    expect(tokenFor('https://twins.example.com', store)).toBe('tok_read');
+    expect(requireToken('https://twins.example.com', undefined, store)).toBe('tok_read');
+    expect(requireToken('https://twins.example.com', 'tok_ci', store)).toBe('tok_ci'); // an explicit token wins for one call
+    expect((statSync(store).mode & 0o777)).toBe(0o600);
+  });
+});

package/src/serve-shutdown.test.ts

@@ -0,0 +1,40 @@
+import { expect, test } from 'bun:test';
+import { EventEmitter } from 'node:events';
+import { waitForServeShutdown } from './serve-shutdown.ts';
+
+test('repeated signals join one asynchronous shutdown and listeners are removed', async () => {
+  const signals = new EventEmitter();
+  let calls = 0;
+  let release!: () => void;
+  const stopped = new Promise<void>(resolve => { release = resolve; });
+  const shutdown = waitForServeShutdown(() => { calls++; return stopped; }, { signals });
+  let finished = false;
+  shutdown.then(() => { finished = true; });
+  signals.emit('SIGTERM'); signals.emit('SIGHUP'); signals.emit('SIGINT');
+  await Promise.resolve();
+  expect(calls).toBe(1);
+  expect(finished).toBe(false);
+  release(); await shutdown;
+  expect(finished).toBe(true);
+  expect(signals.eventNames()).toEqual([]);
+});
+
+test('a failed stop rejects the awaited shutdown', async () => {
+  const signals = new EventEmitter();
+  const shutdown = waitForServeShutdown(async () => { throw new Error('external teardown failed'); }, { signals });
+  signals.emit('SIGTERM');
+  await expect(shutdown).rejects.toThrow('external teardown failed');
+  expect(signals.eventNames()).toEqual([]);
+});
+
+test('the shutdown deadline fails and a late stop rejection remains handled', async () => {
+  const signals = new EventEmitter();
+  let fail!: (error: Error) => void;
+  const stopped = new Promise<void>((_, reject) => { fail = reject; });
+  const shutdown = waitForServeShutdown(() => stopped, { signals, timeoutMs: 10 });
+  signals.emit('SIGTERM');
+  await expect(shutdown).rejects.toThrow('cleanup incomplete');
+  expect(signals.eventNames()).toEqual([]);
+  fail(new Error('late stop failure'));
+  await Promise.resolve();
+});

package/src/serve-shutdown.ts

@@ -0,0 +1,26 @@
+import type { EventEmitter } from 'node:events';
+
+/** Signals request one shutdown; repeated signals never start a competing World teardown. */
+export async function waitForServeShutdown(stop: () => Promise<void>, options: {
+  signals?: Pick<EventEmitter, 'on' | 'off'>; timeoutMs?: number;
+} = {}): Promise<void> {
+  const signals = options.signals ?? process;
+  const names = ['SIGTERM', 'SIGINT', 'SIGHUP'] as const;
+  let started = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let request!: () => void;
+  try {
+    await new Promise<void>((resolve, reject) => {
+      request = () => {
+        if (started) return;
+        started = true;
+        timer = setTimeout(() => reject(new Error('World serve shutdown timed out; cleanup incomplete, instance and reservation retained for explicit down')), options.timeoutMs ?? 8000);
+        Promise.resolve().then(stop).then(resolve, reject);
+      };
+      for (const name of names) signals.on(name, request);
+    });
+  } finally {
+    if (timer) clearTimeout(timer);
+    for (const name of names) signals.off(name, request);
+  }
+}

package/src/world.ts

@@ -0,0 +1,448 @@
+// WORLD — the twins an app needs, running together (docs/concepts/the-model.md,
+// docs/concepts/worlds.md#the-config-and-the-running-world): a branch with compute attached. `World.open()` finds the world of the cwd the
+// way git finds its repository; every method is a name for a world-runtime verb, in the words a
+// user reads. The `volter` command is one client of this class and adds nothing.
+import { rebaseChangeset, worldBootMarker, type Changeset, type ChangesetApplication, type LedgerDelta, type PerformAction, type RemoteExecute, type TwinAction, type WorldMarker, type ApplyReceipt, listActions, isTwinBookkeeping, pushablePendingActions, pendingActions, applyTwinWrite, twinResources, type TwinResource } from '@volter/world-core';
+import { spawnSync } from 'node:child_process';
+import {
+  activateScript, approveWorldChangeset, branchWorld, clockFile, checkoutWorld, createWorldChangeset, diffWorld, downWorld, fetchFromOrigin, findWorldChangeset, initWorld, listWorldChangesets, listWorldMarks, listWorlds, markWorld, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, runWithWorldEnv, seedWorld, shellWorld,
+  statusWorld, statusWorldChangeset, upWorld, verifyWorldChangeset, worldLedgers, worldOrigin,
+  deployWorld, loadWorldConfig, writeWorldConfig, readServeRecord, refreshTwin, serveWorld, findInstalledPackage, type ServedWorld, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom,
+  type DeployTwinOutcome, type MaterializedRoot,
+  type ChangesetLocation, type InitOptions, type InitResult, type WorldInstance, materializeRoots } from '@volter/world-runtime';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { requireToken, storeToken } from './credentials.ts';
+import { currentBranch, findWorldRoot, mainBranch, requireWorldRoot, setCurrentBranch, worldConfigRelative, worldEnvPath, worldSeedPath } from './locate.ts';
+import { parentEntries, rebaseBranch, type Receipt, type RootConfig } from '@volter/world-core';
+
+export type WorldRef = { name?: string; root?: string };
+export type WorldMode = 'local' | 'share' | 'sealed';
+
+/** One change as `log` shows it: the write, and the receipt the vendor answered with once pushed. */
+/** A twin's branch log as the world reads it: the twin's name, the state service it records under, its control root. */
+export class TwinLog {
+  constructor(readonly service: string, readonly stateService: string, readonly root: string) {}
+  /** this branch's own entries, bookkeeping aside */
+  log(): TwinAction[] { return listActions(this.stateService, this.root).filter((a) => !isTwinBookkeeping(a)); }
+  /** entries the parent does not hold */
+  unpushed(opts: { pushable?: boolean } = {}): TwinAction[] { return opts.pushable ? pushablePendingActions(this.stateService, this.root) : pendingActions(this.stateService, this.root); }
+  /** the tree: this twin's resources as a read sees them */
+  state(): TwinResource[] { return twinResources(this.stateService, this.root); }
+  /** one write through the kernel's write path (the head performs it when this twin's root says so) */
+  change(write: Parameters<typeof applyTwinWrite>[1]): ReturnType<typeof applyTwinWrite> { return applyTwinWrite(this.stateService, write, this.root); }
+}
+
+export type LogEntry = TwinAction & { receipt?: ApplyReceipt; changeset?: string; /** v2: the receipt on the landed copy — deployed, refused, failed, landed */ landed?: Receipt; /** the entry's POSITION in its twin's whole log (contract "Just like Neon", 2): the parent view then the branch, counted from one */ position?: number };
+
+export type WorldStatus = {
+  world: string;
+  root: string;
+  branch: string;
+  branches: string[];
+  running: boolean;
+  /** the URL this world is served at, when a serve process is alive (contract "Just like Neon", 4) */
+  served: { base: string; pid: number; startedAt: string } | null;
+  /** the origin this world clones from and pushes to, or null: the default data is its only origin */
+  origin: { url: string; namespace: string; fetchedAt?: string } | null;
+  unpushed: number;
+  changesets: { total: number; pushed: number };
+  services: Record<string, { url?: string; running: boolean; /** the pack's protocol major and its standing (protocol 1 is deprecated: served under a warning, its vendor half throws) */ protocol?: { major: number; standing: string } }>;
+  envFile?: string;
+};
+
+/** `https://host/org/world` → the remote's base URL and the namespace it addresses. */
+export function parseOriginUrl(url: string): { url: string; namespace: string } {
+  // a PATH is a world on this machine (git's file transport): its directory, and its served name
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) {
+    const root = resolve(url);
+    const configPath = join(root, '.volter', 'world.json');
+    if (!existsSync(configPath)) throw new Error(`Not a remote URL or world directory: ${url} (want https://<host>/<org>/<world>, or a directory holding .volter/world.json)`);
+    const config = loadWorldConfig(configPath, root).config;
+    return { url: root, namespace: config.bare?.name ?? `${config.id}/${config.id}` };
+  }
+  let parsed: URL;
+  try { parsed = new URL(url); } catch { throw new Error(`Not a remote URL: ${url} (want https://<host>/<org>/<world>)`); }
+  const parts = parsed.pathname.split('/').filter(Boolean);
+  if (parts.length !== 2) throw new Error(`A remote URL names one world: https://<host>/<org>/<world>, got ${url}`);
+  return { url: `${parsed.origin}`, namespace: `${parts[0]}/${parts[1]}` };
+}
+
+export class World {
+  /** The branch this handle is on — the instance name in the kernel. */
+  readonly name: string;
+  /** The world root: the app repo. */
+  readonly root: string;
+  private constructor(name: string, root: string) { this.name = name; this.root = root; }
+
+  // ── finding and making worlds ───────────────────────────────────────────────────────────
+  /** The world of the cwd (or of `ref.root`), on its checked-out branch (or `ref.name`). */
+  /** The config `loadWorldConfig` resolves for this world: the in-repo world.json, else the world's name. */
+  private configRef(): string { const inRepo = join(this.root, '.volter', 'world.json'); return existsSync(inRepo) ? inRepo : this.name; }
+
+  static open(ref: WorldRef = {}): World {
+    const root = ref.root === undefined ? requireWorldRoot() : requireWorldRoot(ref.root);
+    return new World(ref.name ?? currentBranch(root), root);
+  }
+  /** Whether `from` (default: the cwd) is inside a world. */
+  static find(from?: string): World | null {
+    const root = findWorldRoot(from);
+    return root === null ? null : new World(currentBranch(root), root);
+  }
+  /** `volter world init --bare <org>/<world> --twins a,b`: a world with no app — a package.json naming the
+   *  twins (installed with bun), then the world over them, served as `/<org>/<world>/`. */
+  static initBare(dir: string, served: string, twins: string[], opts: { install?: boolean; force?: boolean } = {}): { world: World; result: InitResult } {
+    if (!/^[a-z0-9_-]+\/[a-z0-9_-]+$/i.test(served)) throw new Error(`a bare world is named <org>/<world>, got ${served}`);
+    if (twins.length === 0) throw new Error('a bare world needs its twins: --twins github,slack');
+    mkdirSync(dir, { recursive: true });
+    const pkgPath = join(dir, 'package.json');
+    if (!existsSync(pkgPath)) writeFileSync(pkgPath, `${JSON.stringify({ name: served.split('/')[1], private: true, devDependencies: Object.fromEntries(twins.map((t) => [`@volter/twin-${t}`, '*'])) }, null, 2)}\n`);
+    if (opts.install !== false && !twins.every((t) => findInstalledPackage(dir, `@volter/twin-${t}`))) {
+      // the runtime's own installer: bun under Bun, npm under Node — never assumed
+      const cmd = typeof Bun !== 'undefined' ? ['bun', 'add', '-d'] : ['npm', 'install', '--save-dev'];
+      const r = spawnSync(cmd[0]!, [...cmd.slice(1), ...twins.map((t) => `@volter/twin-${t}`)], { cwd: dir, stdio: 'inherit' });
+      if (r.status !== 0) throw new Error(`installing the twins failed (${cmd.join(' ')} exited ${r.status})`);
+    }
+    const name = served.split('/')[1]!;
+    const result = initWorld(name, dir, { root: dir, vendors: twins, bare: served, force: opts.force ?? false });
+    return { world: new World(name, dir), result };
+  }
+  /** `volter world init`: detect the app's vendors and write `.volter/world.json` beside the code. */
+  static init(app: string = process.cwd(), opts: Omit<InitOptions, 'root'> & { name?: string; root?: string } = {}): { world: World; result: InitResult } {
+    const name = opts.name ?? worldNameFor(app);
+    const { name: _n, root: _r, ...rest } = opts;
+    const result = initWorld(name, app, { root: opts.root ?? app, ...rest });
+    return { world: new World(name, opts.root ?? app), result };
+  }
+
+  // ── lifecycle ───────────────────────────────────────────────────────────────────────────
+  /**
+   * Start the twins on this branch. A branch that has run before comes back with its state (down
+   * stops compute, up resumes it — `reset` is the way back to the default data); a fresh branch
+   * boots clean and loads the default data unless `seed: false`.
+   */
+  async up(opts: { mode?: WorldMode; seed?: boolean; cwd?: string } = {}): Promise<WorldInstance> {
+    const existing = this.instance();
+    if (existing?.running) return existing; // already up: nothing to do
+    const instance = await upWorld(worldConfigRelative(), {
+      name: this.name, root: this.root, envFile: worldEnvPath(this.root),
+      ...(opts.mode ? { mode: opts.mode } : existing ? { mode: existing.mode } : {}),
+      ...(existing ? { keepState: true } : {}),
+    });
+    try {
+      if (!existing && opts.seed !== false && existsSync(worldSeedPath(this.root))) {
+        // a story that fails is a loud failure: the world is up, but not the world the app expects
+        const seeded = await seedWorld(this.name, { root: this.root, cwd: opts.cwd ?? this.root });
+        if (seeded.exitCode !== 0) throw new Error(`the story failed (${seeded.entry} exited ${seeded.exitCode}); the world is up without it — fix the seed and \`volter world seed\``);
+      }
+    } finally {
+      // a root set while the world was stopped reaches the twins' state after the default data (which a
+      // fresh boot runs simulated), where the deploy reads it — also when the seed failed
+      materializeRoots(loadWorldConfig(this.configRef(), this.root).config, instance.dirs.data, this.root);
+    }
+    return instance;
+  }
+  /** Stop the twins; the branch's state stays (`up` resumes). `purge` forgets it. */
+  down(opts: { purge?: boolean } = {}): ReturnType<typeof downWorld> { return downWorld(this.name, this.root, opts); }
+  /** Run a command inside the world: the app or its tests, with the twins' URLs and fake credentials in its env. */
+  run(command: string[], opts: { cwd?: string; verbose?: boolean } = {}): Promise<number> { return runWithWorldEnv(this.name, command, this.root, { ...opts, cwd: opts.cwd ?? this.root }); }
+  /** The shell script that activates the world in the current shell: `eval "$(volter world activate)"` — vendor CLIs and curl reach the twins. */
+  activateScript(): string { return activateScript(this.name, this.root); }
+  /** A subshell with the world active; resolves to its exit code. */
+  shell(): Promise<number> { return shellWorld(this.name, this.root); }
+
+  /** The kernel's instance record, or null before the first `up`. */
+  instance(): (WorldInstance & { running: boolean; livePids: number[] }) | null {
+    try { return statusWorld(this.name, this.root); } catch { return null; }
+  }
+  /** The world, the branch, the origin, what is unpushed, what is running. */
+  status(): WorldStatus {
+    const instance = this.instance();
+    const changesets = instance ? this.changesets() : [];
+    const services: WorldStatus['services'] = {};
+    if (instance) for (const [id, s] of Object.entries(instance.services)) services[id] = { ...(s.url ? { url: s.url } : {}), running: s.type === 'external' || instance.livePids.includes(s.pid), ...(s.protocol ? { protocol: { major: s.protocol.major, standing: s.protocol.standing } } : {}) };
+    return {
+      world: this.name, root: this.root, branch: this.name,
+      branches: listWorlds(this.root).map((w) => w.name).sort(),
+      running: instance?.running ?? false,
+      served: (() => { const r = readServeRecord(this.root); return r ? { base: r.base, pid: r.pid, startedAt: r.startedAt } : null; })(),
+      origin: instance?.origin ? { url: instance.origin.url, namespace: instance.origin.namespace, ...(instance.origin.fetchedAt ? { fetchedAt: instance.origin.fetchedAt } : {}) } : null,
+      unpushed: instance ? this.unpushed().length : 0,
+      changesets: { total: changesets.length, pushed: changesets.filter((c) => c.changeset.applied?.outcome === 'applied').length },
+      services,
+      ...(instance ? { envFile: instance.envFile } : {}),
+    };
+  }
+
+  // ── the repos ───────────────────────────────────────────────────────────────────────────
+  /** One twin log per twin the world runs: its branch entries and what is unpushed. */
+  repos(): TwinLog[] { return worldLedgers(this.name, this.root).map((l) => new TwinLog(l.service, l.stateService, l.controlRoot)); }
+  repo(service: string): TwinLog {
+    const found = this.repos().find((r) => r.service === service);
+    if (!found) { const instance = statusWorld(this.name, this.root); if (!instance.services[service]) throw new Error(`World "${this.name}" has no twin "${service}" (has: ${Object.keys(instance.services).sort().join(', ') || 'none'})`); return new TwinLog(service, service, join(instance.dirs.data, service)); }
+    return found;
+  }
+
+  // ── the log ─────────────────────────────────────────────────────────────────────────────
+  /** Every write the app made, across the twins, oldest first, with the receipt against each pushed one. */
+  log(): LogEntry[] {
+    const receipts = new Map<string, { receipt: ApplyReceipt; changeset: string }>();
+    for (const located of this.changesets()) for (const receipt of located.changeset.applied?.receipts ?? []) receipts.set(receipt.actionId, { receipt, changeset: located.changeset.name });
+    const rows: LogEntry[] = [];
+    for (const repo of this.repos()) {
+      // v2 (log.ts): the parent log first — what origin holds, minus the default data (a placeholder
+      // row) and minus this branch's own landed copies (shown once, as the branch entry with its receipt)
+      const landed = new Map<string, Receipt>();
+      const own = new Set(repo.log().map((a) => a.id));
+      // the position of each entry in this twin's whole log: the parent view, then the branch
+      const positionOf = new Map<string, number>();
+      { let n = 0; for (const e of parentEntries(repo.stateService, repo.root)) positionOf.set(e.id, ++n); for (const e of repo.log()) if (!positionOf.has(e.id)) positionOf.set(e.id, ++n); }
+      for (const e of parentEntries(repo.stateService, repo.root)) {
+        // the settled receipt wins over a provisional `landed` one: origin's copy says deployed/refused/failed after this branch's own copy said landed
+        if (e.landsId && e.receipt) { const prior = landed.get(e.landsId); if (!prior || prior.status === 'landed' || e.receipt.status !== 'landed') landed.set(e.landsId, e.receipt); }
+        if (e.landsId && own.has(e.landsId)) continue;
+        if (own.has(e.id)) continue;
+        if (e.provenance === 'placeholder') continue;
+        if (e.op !== 'set' || !e.fields || e.subject.type.startsWith('_')) continue;
+        rows.push({ ...(e as unknown as TwinAction), service: repo.service, ...(e.receipt ? { landed: e.receipt } : {}), ...(positionOf.has(e.id) ? { position: positionOf.get(e.id)! } : {}) });
+      }
+      for (const action of repo.log()) {
+        const r = receipts.get(action.id); const l = landed.get(action.id);
+        // the row names the TWIN (slack), not the state service it records under (chat)
+        const row = { ...action, service: repo.service, ...(positionOf.has(action.id) ? { position: positionOf.get(action.id)! } : {}) };
+        rows.push(l ? { ...row, landed: l } : r ? { ...row, receipt: r.receipt, changeset: r.changeset } : row);
+      }
+    }
+    return rows.sort((a, b) => a.occurredAt.localeCompare(b.occurredAt) || a.id.localeCompare(b.id));
+  }
+  /** Changes not yet pushed (`log origin..HEAD`), across the twins. */
+  unpushed(): TwinAction[] { return this.repos().flatMap((r) => r.unpushed({ pushable: true })).sort((a, b) => a.occurredAt.localeCompare(b.occurredAt)); }
+  diff(base?: string): LedgerDelta { return diffWorld(this.name, { root: this.root, ...(base ? { base } : {}) }); }
+
+  // ── default data ────────────────────────────────────────────────────────────────────────
+  /** Load the default data: the seed runs with every twin recording what it creates as data that was already there. */
+  seed(opts: { entry?: string; cwd?: string } = {}): ReturnType<typeof seedWorld> { return seedWorld(this.name, { root: this.root, cwd: this.root, ...opts }); }
+  /** Back to the default data: forget this branch's state, boot, seed. */
+  reset(opts: { entry?: string; cwd?: string } = {}): ReturnType<typeof resetWorld> { return resetWorld(this.name, { root: this.root, cwd: this.root, ...opts }); }
+
+  // ── branches ────────────────────────────────────────────────────────────────────────────
+  /**
+   * A new branch from here — its own log over this branch's mirrors — checked out. One branch runs
+   * at a time in a world (the app's env names one set of twins), so this branch stops as the new
+   * one starts; `checkout` brings it back with its state.
+   */
+  async branch(name: string, opts: { at?: { instant?: string; positions?: Record<string, number>; views?: Record<string, string> } } = {}): Promise<World> {
+    if (listWorlds(this.root).some((w) => w.name === name)) throw new Error(`A branch "${name}" already exists — \`volter world checkout ${name}\` switches to it`);
+    await branchWorld(this.name, name, { root: this.root, envFile: worldEnvPath(this.root), ...(opts.at ? { at: opts.at } : {}) });
+    if (this.instance()?.running) await downWorld(this.name, this.root);
+    setCurrentBranch(this.root, name);
+    return new World(name, this.root);
+  }
+  /** Switch to a branch: its twins come back with their state; this branch's stop. */
+  async checkout(name: string): Promise<World> {
+    if (name === 'main') name = mainBranch(this.root); // the main branch answers to its name and to `main`
+    if (name === this.name) return this;
+    if (!listWorlds(this.root).some((w) => w.name === name)) throw new Error(`No branch "${name}" in this world (branches: ${listWorlds(this.root).map((w) => w.name).sort().join(', ') || 'none'})`);
+    const wasRunning = this.instance()?.running ?? false;
+    if (wasRunning) await downWorld(this.name, this.root);
+    const target = new World(name, this.root);
+    if (wasRunning && !target.instance()?.running) await checkoutWorld(name, { root: this.root });
+    setCurrentBranch(this.root, name);
+    return target;
+  }
+  branches(): string[] { return listWorlds(this.root).map((w) => w.name).sort(); }
+  /** Is this the main branch? */
+  isMain(): boolean { return this.name === mainBranch(this.root); }
+  /** What this branch's changes are measured from, as `diff` says it: the branch point, origin, or the story. */
+  diffBase(): string {
+    if (!this.isMain()) return `branch ${this.name}`;
+    if (this.remote('origin')) return 'origin';
+    return existsSync(worldSeedPath(this.root)) ? 'the story' : 'the default data';
+  }
+
+  // ── the clock ───────────────────────────────────────────────────────────────────────────
+  /** The world's clock: the frozen instant every twin stamps from, or the wall clock when unset. */
+  clock(): { at: string; frozen: boolean } {
+    const file = clockFile(this.root, this.name);
+    return existsSync(file) ? { at: readFileSync(file, 'utf8').trim(), frozen: true } : { at: new Date().toISOString(), frozen: false };
+  }
+  /** Set the world's clock to an instant; every twin stamps from it until it moves. */
+  setClock(iso: string): string {
+    const parsed = Date.parse(iso);
+    if (Number.isNaN(parsed)) throw new Error(`${JSON.stringify(iso)} is not an ISO-8601 instant`);
+    const file = clockFile(this.root, this.name);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${new Date(parsed).toISOString()}\n`);
+    return new Date(parsed).toISOString();
+  }
+  /** Move a set clock forward: `30d`, `12h`, `5m`, `90s`. */
+  advanceClock(by: string): string {
+    const m = /^(\d+(?:\.\d+)?)(s|m|h|d)$/.exec(by.trim());
+    if (!m) throw new Error(`${JSON.stringify(by)} is not <N>(s|m|h|d)`);
+    const current = this.clock();
+    if (!current.frozen) throw new Error('the clock is not set — `volter world clock set <iso>` first; advancing the wall clock would freeze time as a side effect');
+    const ms = Number(m[1]) * { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2] as 's' | 'm' | 'h' | 'd'];
+    return this.setClock(new Date(Date.parse(current.at) + ms).toISOString());
+  }
+  /** Rebase this branch onto its base's current position, every twin; conflicts named per subject and field. */
+  rebaseBranch(): Array<{ service: string } & ReturnType<typeof rebaseBranch>> { return this.repos().map((r) => ({ service: r.service, ...rebaseBranch(r.stateService, r.root) })); }
+  /** Replay a changeset's changes into another branch's twins, in order, with the same ids. */
+  replay(name: string, into: string): ReturnType<typeof replayWorldChangeset> { return replayWorldChangeset(name, { root: this.root, world: this.name, into }); }
+
+  // ── serving ─────────────────────────────────────────────────────────────────────────────
+  /** Serve this world on a port under `/<org>/<world>/`; returns when listening. */
+  serve(opts: { port?: number; host?: string; consolePort?: number; announce?: (info: { name: string; base: string; token: string; readToken: string; console: string | null }) => void } = {}): Promise<ServedWorld> { return serveWorld(this.name, { root: this.root, ...opts }); }
+
+  // ── remotes ─────────────────────────────────────────────────────────────────────────────
+  /** The remotes named in world.json (`volter remote add`), name → url or path. */
+  remotes(): Record<string, string> { return { ...(loadWorldConfig(this.configRef(), this.root).config.remotes ?? {}) }; }
+  /** Name a remote; `origin` is the one fetch and push use by default. A token given is remembered for it. */
+  addRemote(name: string, target: string, opts: { token?: string } = {}): void {
+    const { path, config } = loadWorldConfig(this.configRef(), this.root);
+    const remotes = { ...(config.remotes ?? {}), [name]: target };
+    writeWorldConfig(path, { ...config, remotes });
+    if (opts.token) storeToken(parseOriginUrl(target).url, opts.token);
+  }
+  removeRemote(name: string): void {
+    const { path, config } = loadWorldConfig(this.configRef(), this.root);
+    const remotes = { ...(config.remotes ?? {}) }; delete remotes[name];
+    writeWorldConfig(path, { ...config, remotes });
+  }
+  /** The remote a verb uses: the named one, else origin from world.json, else the instance's recorded origin. */
+  remote(name = 'origin'): { url: string; namespace: string } | null {
+    const target = this.remotes()[name];
+    if (target) return parseOriginUrl(target);
+    if (name !== 'origin') return null;
+    const recorded = worldOrigin(this.name, this.root);
+    return recorded ? { url: recorded.url, namespace: recorded.namespace } : null;
+  }
+
+  // ── the origin ──────────────────────────────────────────────────────────────────────────
+  /** The origin this world clones from and pushes to, or null: the default data is its only origin. */
+  origin(): WorldInstance['origin'] | null { const r = this.remote('origin'); const recorded = worldOrigin(this.name, this.root); return r ? { ...(recorded ?? {}), url: r.url, namespace: r.namespace } : recorded; }
+  /**
+   * Clone a remote's canonical history into this world: record the origin, remember the token,
+   * fetch everything. With the world's token (namespace or read), the history arrives through the
+   * mirror, from the beginning; with `adminToken` as well, the remote's whole tree is copied in one
+   * move, which is what an admin can do and a reader cannot. Either way one token is remembered:
+   * the world's, which is what `fetch` and `push` use afterwards.
+   */
+  async clone(url: string, opts: { token?: string; adminToken?: string } = {}): Promise<ReturnType<typeof fetchFromOrigin>> {
+    const origin = parseOriginUrl(url);
+    if (opts.token !== undefined && opts.token !== '') storeToken(origin.url, opts.token);
+    if (opts.adminToken !== undefined && opts.adminToken !== '') {
+      if (opts.token === undefined || opts.token === '') storeToken(origin.url, opts.adminToken);
+      return fetchFromOrigin(this.name, { root: this.root, url: origin.url, namespace: origin.namespace, key: opts.adminToken, full: true });
+    }
+    const key = requireToken(origin.url, opts.token);
+    // v2: a clone brings the served world's whole log in from position zero, and names it origin;
+    // a world that has never run is booted first (no story: its history is the origin's)
+    this.addRemote('origin', url);
+    if (!this.instance()) await this.up({ seed: false });
+    return fetchFromOrigin(this.name, { root: this.root, url: origin.url, namespace: origin.namespace, key, full: true });
+  }
+  /** Fetch, then move this branch onto what came in: git's pull. */
+  async pull(opts: { token?: string; services?: string[] } = {}): Promise<{ fetched: Awaited<ReturnType<typeof fetchFromOrigin>>; rebased: ReturnType<World['rebaseBranch']> }> {
+    const fetched = await this.fetch(opts);
+    return { fetched, rebased: this.repos().map((r) => ({ service: r.service, ...rebaseBranch(r.stateService, r.root, { origin: true }) })) };
+  }
+  /** Fetch what the origin observed since the last fetch. */
+  fetch(opts: { token?: string; services?: string[] } = {}): ReturnType<typeof fetchFromOrigin> {
+    const origin = this.origin();
+    if (!origin) throw new Error(`World "${this.name}" has no origin — its only origin is the default data. \`volter world clone <url>\` connects a remote.`);
+    if (opts.token !== undefined && opts.token !== '') storeToken(origin.url, opts.token); // the last token given for a remote is the one remembered
+    return fetchFromOrigin(this.name, { root: this.root, url: origin.url, namespace: origin.namespace, key: requireToken(origin.url, opts.token), ...(opts.services ? { services: opts.services } : {}) });
+  }
+
+  // ── changesets and push ─────────────────────────────────────────────────────────────────
+  /** Cut a changeset from the unpushed changes: the reviewable unit, with the author's message. */
+  changeset(opts: { name?: string; message?: string; base?: string; verifiers?: Parameters<typeof createWorldChangeset>[2] extends infer O ? (O extends { verifiers?: infer V } ? V : never) : never; overwrite?: boolean } = {}): Changeset {
+    const name = opts.name ?? (opts.message ? slugName(opts.message, this.changesets()) : nextChangesetName(this.changesets()));
+    return createWorldChangeset(this.name, name, { root: this.root, ...(opts.message !== undefined ? { message: opts.message } : {}), ...(opts.base ? { base: opts.base } : {}), ...(opts.verifiers ? { verifiers: opts.verifiers } : {}), ...(opts.overwrite ? { overwrite: true } : {}) });
+  }
+  changesets(): ChangesetLocation[] { return listWorldChangesets({ root: this.root, world: this.name }); }
+  /**
+   * Push to the origin, which deploys to the vendor with its own keys and answers with receipts:
+   * the named changeset, or every changeset not yet pushed, oldest first. A local world never
+   * holds a vendor credential.
+   */
+  async push(opts: { name?: string; token?: string; force?: boolean } = {}): Promise<Array<Awaited<ReturnType<typeof pushWorldChangeset>>>> {
+    const origin = this.origin();
+    if (!origin) throw new Error(`World "${this.name}" has no origin to push to — the default data cannot be pushed to. \`volter world clone <url>\` connects a remote.`);
+    if (opts.token !== undefined && opts.token !== '') storeToken(origin.url, opts.token);
+    const key = requireToken(origin.url, opts.token);
+    const to = { to: origin.url, namespace: origin.namespace };
+    const queue = opts.name !== undefined
+      ? [findWorldChangeset(opts.name, { root: this.root, world: this.name })]
+      : this.changesets().filter((c) => c.changeset.applied === null || c.changeset.applied.outcome === 'refused').sort((a, b) => a.changeset.createdAt.localeCompare(b.changeset.createdAt));
+    if (queue.length === 0) throw new Error(this.unpushed().length ? 'Nothing to push: cut a changeset first — `volter world changeset -m "<what and why>"`' : 'Nothing to push: no unpushed changes');
+    const outcomes: Array<Awaited<ReturnType<typeof pushWorldChangeset>>> = [];
+    for (const located of queue) {
+      const outcome = await pushWorldChangeset(located.changeset.name, { root: this.root, world: this.name, ...to, key, ...(opts.force ? { force: true } : {}) });
+      outcomes.push(outcome);
+      if (outcome.application.outcome === 'refused') break;
+    }
+    return outcomes;
+  }
+
+  // ── review (the operator's verbs, kept on the SDK for the remote and for CI) ────────────
+  mark(id?: string, now?: Date): WorldMarker { return markWorld(this.name, { root: this.root, ...(id ? { id } : {}), ...(now ? { now } : {}) }); }
+  marks(): WorldMarker[] { return listWorldMarks(this.name, this.root); }
+  verify(name: string, opts: { into?: string; ephemeral?: boolean } = { ephemeral: true }): ReturnType<typeof verifyWorldChangeset> { return verifyWorldChangeset(name, { root: this.root, world: this.name, ...opts }); }
+  approve(name: string, principal: string, note?: string): ReturnType<typeof approveWorldChangeset> { return approveWorldChangeset(name, { root: this.root, world: this.name, principal, ...(note ? { note } : {}) }); }
+  readiness(name: string): ReturnType<typeof statusWorldChangeset> { return statusWorldChangeset(name, { root: this.root, world: this.name }); }
+  rebase(name: string): ReturnType<typeof rebaseWorldChangeset> { return rebaseWorldChangeset(name, { root: this.root, world: this.name }); }
+  // ── roots (docs/concepts/the-model.md: a twin on a shared world whose root is the vendor) ──
+  /** The twin's root and credential, as `volter twin <vendor>` prints them. */
+  twin(vendor: string): { vendor: string; url?: string; root: RootConfig | null; credential: { placedAt: string; fingerprint: string } | null } {
+    const { config } = loadWorldConfig(this.configRef(), this.root);
+    const service = config.services.find((s) => s.id === vendor);
+    if (!service) throw new Error(`no twin "${vendor}" in this world`);
+    const inst = this.instance();
+    return { vendor, ...(inst?.services[vendor]?.url ? { url: inst.services[vendor]!.url } : {}), root: (service as { root?: RootConfig }).root ?? null, credential: sealedCredentialInfo(this.root, vendor) };
+  }
+  /** Set (or clear) the twin's root: the vendor's API and the deploy policy, in world.json. Takes effect at the next `up` or `serve`, or now when the world runs. */
+  setTwinRoot(vendor: string, root: RootConfig | null): void {
+    setTwinRoot(this.root, vendor, root, { config: this.configRef() });
+    const inst = this.instance();
+    if (inst?.running) { materializeRoots(loadWorldConfig(this.configRef(), this.root).config, inst.dirs.data, this.root); }
+  }
+  /** Seal the vendor's credential beside the world (a bare token, or a JSON payload). Never readable back. */
+  sealTwinCredential(vendor: string, input: string): Promise<{ placedAt: string; fingerprint: string }> { return sealTwinCredential(this.root, vendor, credentialPayloadFrom(input, vendor)); }
+  /** Refresh one twin from its root now. */
+  async refreshTwin(vendor: string, opts: { force?: boolean } = {}): Promise<{ refreshed: boolean; reason?: string; report?: { observed: number; appended: number; unchanged: number; removed: number } }> {
+    const { controlRoot, root } = this.rootOf(vendor);
+    return refreshTwin({ worldRoot: this.root, vendor, controlRoot, root, ...(opts.force ? { force: true } : {}) });
+  }
+  private rootOf(vendor: string): { controlRoot: string; root: MaterializedRoot } {
+    const inst = statusWorld(this.name, this.root);
+    const controlRoot = join(inst.dirs.data, vendor);
+    const root = rootForControlRoot(controlRoot, vendor);
+    if (!root) throw new Error(`the ${vendor} twin has no root — \`volter twin ${vendor} root <url>\` sets one`);
+    return { controlRoot, root };
+  }
+  /** DEPLOY: perform landed entries against each root twin's vendor, by policy (runtime `deployWorld`). */
+  deploy(name?: string): Promise<DeployTwinOutcome[]> { return deployWorld(this.name, { root: this.root, ...(name ? { changeset: name } : {}) }); }
+}
+
+/** The world's name when none is given: the app directory's basename, made safe. */
+export function worldNameFor(app: string): string {
+  const base = app.replace(/[\\/]+$/, '').split(/[\\/]/).pop() ?? 'world';
+  const safe = base.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[^a-z0-9]+/, '');
+  return safe === '' ? 'world' : safe;
+}
+
+/** A name from the message (`Triage acme/web#1 as OPS-1` → `triage-acme-web-1-as-ops-1`), suffixed when taken. */
+function slugName(message: string, existing: ChangesetLocation[]): string {
+  const base = message.toLowerCase().replace(/['’]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'changeset';
+  const taken = new Set(existing.map((c) => c.changeset.name));
+  if (!taken.has(base)) return base;
+  for (let n = 2; ; n += 1) { const name = `${base}-${n}`; if (!taken.has(name)) return name; }
+}
+/** `changeset-1`, `changeset-2`, … — the next free name when the author gives none. */
+function nextChangesetName(existing: ChangesetLocation[]): string {
+  const taken = new Set(existing.map((c) => c.changeset.name));
+  for (let n = existing.length + 1; ; n += 1) { const name = `changeset-${n}`; if (!taken.has(name)) return name; }
+}
+
+export { rebaseChangeset, worldBootMarker };