@volter/world 2.0.0 → 2.0.1

package/dist/src/cli.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export declare const HELP = "volter \u2014 run your app against a world of twins\n\nworld  \u2014 the twins your app needs, running together (the world of the current directory)\n  volter world init [--name <world>] [--allow-unknown]   detect the app's vendors, write .volter/world.json\n  volter world up [--sandbox] [--no-seed]                start the twins on this branch (loads the default data the first time)\n  volter world run [--verbose] -- <command...>           run the app or its tests inside the world\n  volter world activate                                  eval \"$(volter world activate)\": vendor CLIs and curl in this shell reach the twins\n  volter world shell                                     a subshell with the world active\n  volter world init --bare <org>/<world> --twins a,b      a world with no app: a shared world for a team, or one standing in for a vendor\n  volter world serve [--port <p>] [--console-port <c>]   serve this world on a URL under /<org>/<world>/; prints the token and the console (its own origin, port p+1 by default)\n  volter world console [<https://host/org/world>] [--port <p>]  the console on this machine for a World served elsewhere (default: this world's origin); needs @volter/world-console\n  volter world status                                    world, branch, origin, unpushed changes, what is running\n  volter world log [--receipts] [--json]                 every write the app made; --receipts adds each change's receipt\n  volter world diff [--json]                             what changed since the default data (or the last mark)\n  volter world seed                                      load the default data\n  volter world reset                                     back to the default data\n  volter world down [--purge]                            stop the twins (--purge forgets this branch's state)\n  volter world branch [<name>]                           list branches, or make one from here and check it out\n  volter world checkout <name>                           switch branches\n  volter world replay <changeset> --into <branch>        feed a changeset's changes into another branch's twins\n  volter world clock show | set <iso> | advance <N s|m|h|d>   the world's clock: set, not observed\n  volter world clone <url> --token <token> [--admin-token <t>]   connect this world to a remote and fetch its history (the admin token copies the whole tree at once)\n  volter world fetch                                     what the remote observed since the last fetch\n  volter world origin                                    where this world clones from and pushes to\n  volter world changeset [<name>] -m \"<message>\"         cut the unpushed changes into a reviewable changeset\n  volter world pull [--token <token>]                    fetch, then move this branch onto what came in (git's pull)\n  volter world push [<name>] [--token <token>] [--force] push to the remote, which deploys and answers with receipts\n  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved mirror\n  volter world verify <changeset>                        run the world's checks over a changeset and record the result\n  volter world approve <changeset> --as <principal>      sign a changeset's current hash\n  volter world deploy [<changeset>]                      perform landed changes against each twin's root, by its policy\n\ntwin   \u2014 one twin: in this world, or on its own\n  volter twin <vendor>                                   the twin's URL, root, deploy policy, whether a credential is sealed\n  volter twin <vendor> root <url> [--deploy auto|gated|hold] [--scope <path>]   the vendor's real account behind this twin (--none clears it)\n  volter twin <vendor> credential                        seal a credential read from stdin beside the world; never readable back\n  volter twin <vendor> refresh                           observe the root now\n  volter twin <vendor> serve [--port <p>] [--read-only]  serve the twin; your SDK talks to it at http://127.0.0.1:<p>\n  volter twin <vendor> mirror [--port <p>]               the twin's UI mirror\n  volter twin <vendor> conformance                       check the twin against the vendor's spec\n\nremote \u2014 the worlds this one pushes to and fetches from, by name\n  volter login <platform url> --token <personal token>  sign the CLI into the hosted platform (a personal token from the console)\n  volter remote add <name> <url|path|org/world> [--token <token>]  name a remote; org/world resolves through the platform you logged into\n  volter remote remove <name>                            forget it\n  volter remote list                                     every remote, with its URL and whether a token is stored\n  (the hosting product's serve answers here for one release: volter remote serve)\n\n  --world <dir>    the world root, when the cwd is not inside it\n  --branch <name>  act on that branch instead of the checked-out one\n  --json           machine-readable output where offered\n";
+export declare const HELP = "volter \u2014 run your app against a world of twins\n\nworld  \u2014 the twins your app needs, running together (the world of the current directory)\n  volter world init [--name <world>] [--allow-unknown]   detect the app's vendors, write .volter/world.json\n  volter world up [--sandbox] [--no-seed]                start the twins on this branch (loads the default data the first time)\n  volter world run [--verbose] -- <command...>           run the app or its tests inside the world\n  volter world activate                                  eval \"$(volter world activate)\": vendor CLIs and curl in this shell reach the twins\n  volter world shell                                     a subshell with the world active\n  volter world init --bare <org>/<world> --twins a,b      a world with no app: a shared world for a team, or one standing in for a vendor\n  volter world serve [--port <p>] [--console-port <c>]   serve this world on a URL under /<org>/<world>/; prints the token and the console (its own origin, port p+1 by default)\n  volter world console [<https://host/org/world>] [--port <p>]  the console on this machine for a World served elsewhere (default: this world's origin); needs @volter/world-console\n  volter world status                                    world, branch, origin, unpushed changes, what is running\n  volter world log [--receipts] [--json]                 every write the app made; --receipts adds each change's receipt\n  volter world diff [--json]                             what changed since the default data (or the last mark)\n  volter world seed                                      load the default data\n  volter world reset                                     back to the default data\n  volter world down [--purge]                            stop the twins (--purge forgets this branch's state)\n  volter world branch [<name>]                           list branches, or make one from here and check it out\n  volter world checkout <name>                           switch branches\n  volter world replay <changeset> --into <branch>        feed a changeset's changes into another branch's twins\n  volter world clock show | set <iso> | advance <N s|m|h|d> | shift <N s|m|h|d> | clear   the world's clock: set, not observed\n  volter world clone <url> --token <token> [--admin-token <t>]   connect this world to a remote and fetch its history (the admin token copies the whole tree at once)\n  volter world fetch                                     what the remote observed since the last fetch\n  volter world origin                                    where this world clones from and pushes to\n  volter world changeset [<name>] -m \"<message>\"         cut the unpushed changes into a reviewable changeset\n  volter world pull [--token <token>]                    fetch, then move this branch onto what came in (git's pull)\n  volter world push [<name>] [--token <token>] [--force] push to the remote, which deploys and answers with receipts\n  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved mirror\n  volter world verify <changeset>                        run the world's checks over a changeset and record the result\n  volter world approve <changeset> --as <principal>      sign a changeset's current hash\n  volter world deploy [<changeset>]                      perform landed changes against each twin's root, by its policy\n\ntwin   \u2014 one twin: in this world, or on its own\n  volter twin <vendor>                                   the twin's URL, root, deploy policy, whether a credential is sealed\n  volter twin <vendor> root <url> [--deploy auto|gated|hold] [--scope <path>]   the vendor's real account behind this twin (--none clears it)\n  volter twin <vendor> credential                        seal a credential read from stdin beside the world; never readable back\n  volter twin <vendor> refresh                           observe the root now\n  volter twin <vendor> serve [--port <p>] [--read-only]  serve the twin; your SDK talks to it at http://127.0.0.1:<p>\n  volter twin <vendor> mirror [--port <p>]               the twin's UI mirror\n  volter twin <vendor> conformance                       check the twin against the vendor's spec\n\nremote \u2014 the worlds this one pushes to and fetches from, by name\n  volter login <platform url> --token <personal token>  sign the CLI into the hosted platform (a personal token from the console)\n  volter remote add <name> <url|path|org/world> [--token <token>]  name a remote; org/world resolves through the platform you logged into\n  volter remote remove <name>                            forget it\n  volter remote list                                     every remote, with its URL and whether a token is stored\n  (the hosting product's serve answers here for one release: volter remote serve)\n\n  --world <dir>    the world root, when the cwd is not inside it\n  --branch <name>  act on that branch instead of the checked-out one\n  --json           machine-readable output where offered\n";

package/dist/src/cli.js

@@ -32,7 +32,7 @@ world  — the twins your app needs, running together (the world of the current
   volter world branch [<name>]                           list branches, or make one from here and check it out
   volter world checkout <name>                           switch branches
   volter world replay <changeset> --into <branch>        feed a changeset's changes into another branch's twins
-  volter world clock show | set <iso> | advance <N s|m|h|d>   the world's clock: set, not observed
+  volter world clock show | set <iso> | advance <N s|m|h|d> | shift <N s|m|h|d> | clear   the world's clock: set, not observed
   volter world clone <url> --token <token> [--admin-token <t>]   connect this world to a remote and fetch its history (the admin token copies the whole tree at once)
   volter world fetch                                     what the remote observed since the last fetch
   volter world origin                                    where this world clones from and pushes to
@@ -313,12 +313,22 @@ async function worldCommand(verb, args) {
                 out(world.advanceClock(arg));
                 return;
             }
+            if (action === 'shift') {
+                if (!arg)
+                    throw new Error('volter world clock shift <N s|m|h|d>');
+                out(world.shiftClock(arg));
+                return;
+            }
+            if (action === 'clear') {
+                out(world.clearClock());
+                return;
+            }
             if (action === undefined || action === 'show') {
                 const c = world.clock();
-                out(`${c.at}${c.frozen ? '' : ' (wall clock — not set)'}`);
+                out(`${c.at}${c.frozen ? '' : c.running ? ' (running)' : ' (wall clock — not set)'}`);
                 return;
             }
-            throw new Error('volter world clock show | set <iso> | advance <N s|m|h|d>');
+            throw new Error('volter world clock show | set <iso> | advance <N s|m|h|d> | shift <N s|m|h|d> | clear');
         }
         case 'replay': {
             const name = pos[0];

package/dist/src/world.d.ts

@@ -6,8 +6,6 @@ export type WorldRef = {
     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 declare class TwinLog {
     readonly service: string;
     readonly stateService: string;
@@ -164,15 +162,23 @@ export declare class World {
     isMain(): boolean;
     /** What this branch's changes are measured from, as `diff` says it: the branch point, origin, or the story. */
     diffBase(): string;
-    /** The world's clock: the frozen instant every twin stamps from, or the wall clock when unset. */
+    /** The world's clock (world-clock.cjs): its time now, and whether it is frozen at an instant, running (moved with
+     *  `shiftClock`), or the wall clock (unset). */
     clock(): {
         at: string;
         frozen: boolean;
+        running: boolean;
     };
-    /** Set the world's clock to an instant; every twin stamps from it until it moves. */
+    /** Set the world's clock to an instant; every twin, and the World's application, stamps from it until it moves. */
     setClock(iso: string): string;
-    /** Move a set clock forward: `30d`, `12h`, `5m`, `90s`. */
+    /** Move a set clock forward, frozen or running: `30d`, `12h`, `5m`, `90s`. */
     advanceClock(by: string): string;
+    /** Move the World forward while its time keeps running (a World serving an application): from the wall clock, or a
+     *  running clock further. */
+    shiftClock(by: string): string;
+    /** Return the World to the machine's time. */
+    clearClock(): string;
+    private writeClock;
     /** Rebase this branch onto its base's current position, every twin; conflicts named per subject and field. */
     rebaseBranch(): Array<{
         service: string;

package/dist/src/world.js

@@ -4,14 +4,22 @@
 // user reads. The `volter` command is one client of this class and adds nothing.
 import { rebaseChangeset, worldBootMarker, listActions, isTwinBookkeeping, pushablePendingActions, pendingActions, applyTwinWrite, twinResources } from '@volter/world-core';
 import { spawnSync } from 'node:child_process';
+import clockForm from '@volter/world-core/world-clock';
 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, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom, materializeRoots } from '@volter/world-runtime';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { requireToken, storeToken } from "./credentials.js";
 import { currentBranch, findWorldRoot, mainBranch, requireWorldRoot, setCurrentBranch, worldConfigRelative, worldEnvPath, worldSeedPath } from "./locate.js";
 import { parentEntries, rebaseBranch } from '@volter/world-core';
 /** 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. */
+/** `30d`, `12h`, `5m`, `90s` in ms. */
+function durationMs(by) {
+    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)`);
+    return Number(m[1]) * { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+}
 export class TwinLog {
     service;
     stateService;
@@ -248,9 +256,19 @@ export class World {
     async branch(name, opts = {}) {
         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)
+        // this branch stops first (a managed database is copied from a stopped World, and the two would share its port),
+        // and comes back if the new one fails
+        const wasRunning = !!this.instance()?.running;
+        if (wasRunning)
             await downWorld(this.name, this.root);
+        try {
+            await branchWorld(this.name, name, { root: this.root, envFile: worldEnvPath(this.root), ...(opts.at ? { at: opts.at } : {}) });
+        }
+        catch (error) {
+            if (wasRunning)
+                await checkoutWorld(this.name, { root: this.root });
+            throw error;
+        }
         setCurrentBranch(this.root, name);
         return new World(name, this.root);
     }
@@ -283,31 +301,54 @@ export class World {
         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. */
+    /** The world's clock (world-clock.cjs): its time now, and whether it is frozen at an instant, running (moved with
+     *  `shiftClock`), or the wall clock (unset). */
     clock() {
         const file = clockFile(this.root, this.name);
-        return existsSync(file) ? { at: readFileSync(file, 'utf8').trim(), frozen: true } : { at: new Date().toISOString(), frozen: false };
+        if (!existsSync(file))
+            return { at: new Date().toISOString(), frozen: false, running: false };
+        const c = clockForm.parseClock(readFileSync(file, 'utf8'));
+        return { at: new Date(clockForm.clockNowMs(c, Date.now())).toISOString(), frozen: c.kind === 'frozen', running: c.kind === 'running' };
     }
-    /** Set the world's clock to an instant; every twin stamps from it until it moves. */
+    /** Set the world's clock to an instant; every twin, and the World's application, stamps from it until it moves. */
     setClock(iso) {
         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`);
+        this.writeClock({ kind: 'frozen', at: parsed });
         return new Date(parsed).toISOString();
     }
-    /** Move a set clock forward: `30d`, `12h`, `5m`, `90s`. */
+    /** Move a set clock forward, frozen or running: `30d`, `12h`, `5m`, `90s`. */
     advanceClock(by) {
-        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]];
-        return this.setClock(new Date(Date.parse(current.at) + ms).toISOString());
+        const file = clockFile(this.root, this.name);
+        if (!existsSync(file))
+            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 (`volter world clock shift` moves a running World)');
+        const c = clockForm.parseClock(readFileSync(file, 'utf8'));
+        this.writeClock({ ...c, at: c.at + durationMs(by) });
+        return this.clock().at;
+    }
+    /** Move the World forward while its time keeps running (a World serving an application): from the wall clock, or a
+     *  running clock further. */
+    shiftClock(by) {
+        const file = clockFile(this.root, this.name);
+        const c = existsSync(file) ? clockForm.parseClock(readFileSync(file, 'utf8')) : null;
+        if (c?.kind === 'frozen')
+            throw new Error('the clock is frozen — `volter world clock advance` moves it');
+        const wall = Date.now();
+        this.writeClock(c ? { ...c, at: c.at + durationMs(by) } : { kind: 'running', at: wall + durationMs(by), since: wall });
+        return this.clock().at;
+    }
+    /** Return the World to the machine's time. */
+    clearClock() {
+        const file = clockFile(this.root, this.name);
+        if (existsSync(file))
+            rmSync(file);
+        return new Date().toISOString();
+    }
+    writeClock(c) {
+        const file = clockFile(this.root, this.name);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, `${clockForm.formatClock(c)}\n`);
     }
     /** Rebase this branch onto its base's current position, every twin; conflicts named per subject and field. */
     rebaseBranch() { return this.repos().map((r) => ({ service: r.service, ...rebaseBranch(r.stateService, r.root) })); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Run your app against a world of twins. `World` and `Repo` — one method per verb: init, up, run, log, diff, reset, branch, checkout, clone, fetch, changeset, push — and the `volter` command, one client of them.",
   "keywords": [
     "volter",
@@ -13,6 +13,11 @@
   ],
   "author": "Volter (https://github.com/volter-ai)",
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/cli"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -23,8 +28,8 @@
     "dist"
   ],
   "dependencies": {
-    "@volter/world-core": "2.0.0",
-    "@volter/world-runtime": "2.0.0"
+    "@volter/world-core": "2.0.1",
+    "@volter/world-runtime": "2.0.1"
   },
   "bin": {
     "volter": "dist/src/cli.js"

package/src/cli.ts

@@ -34,7 +34,7 @@ world  — the twins your app needs, running together (the world of the current
   volter world branch [<name>]                           list branches, or make one from here and check it out
   volter world checkout <name>                           switch branches
   volter world replay <changeset> --into <branch>        feed a changeset's changes into another branch's twins
-  volter world clock show | set <iso> | advance <N s|m|h|d>   the world's clock: set, not observed
+  volter world clock show | set <iso> | advance <N s|m|h|d> | shift <N s|m|h|d> | clear   the world's clock: set, not observed
   volter world clone <url> --token <token> [--admin-token <t>]   connect this world to a remote and fetch its history (the admin token copies the whole tree at once)
   volter world fetch                                     what the remote observed since the last fetch
   volter world origin                                    where this world clones from and pushes to
@@ -248,8 +248,10 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
       const [action, arg] = pos;
       if (action === 'set') { if (!arg) throw new Error('volter world clock set <iso-8601>'); out(world.setClock(arg)); return; }
       if (action === 'advance') { if (!arg) throw new Error('volter world clock advance <N s|m|h|d>'); out(world.advanceClock(arg)); return; }
-      if (action === undefined || action === 'show') { const c = world.clock(); out(`${c.at}${c.frozen ? '' : ' (wall clock — not set)'}`); return; }
-      throw new Error('volter world clock show | set <iso> | advance <N s|m|h|d>');
+      if (action === 'shift') { if (!arg) throw new Error('volter world clock shift <N s|m|h|d>'); out(world.shiftClock(arg)); return; }
+      if (action === 'clear') { out(world.clearClock()); return; }
+      if (action === undefined || action === 'show') { const c = world.clock(); out(`${c.at}${c.frozen ? '' : c.running ? ' (running)' : ' (wall clock — not set)'}`); return; }
+      throw new Error('volter world clock show | set <iso> | advance <N s|m|h|d> | shift <N s|m|h|d> | clear');
     }
     case 'replay': {
       const name = pos[0]; const into = value(args, '--into');

package/src/world.ts

@@ -4,13 +4,14 @@
 // 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 clockForm from '@volter/world-core/world-clock';
 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 { existsSync, mkdirSync, readFileSync, rmSync, 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';
@@ -21,6 +22,13 @@ 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. */
+/** `30d`, `12h`, `5m`, `90s` in ms. */
+function durationMs(by: string): number {
+  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)`);
+  return Number(m[1]) * { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2] as 's' | 'm' | 'h' | 'd'];
+}
+
 export class TwinLog {
   constructor(readonly service: string, readonly stateService: string, readonly root: string) {}
   /** this branch's own entries, bookkeeping aside */
@@ -233,8 +241,16 @@ export class World {
    */
   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);
+    // this branch stops first (a managed database is copied from a stopped World, and the two would share its port),
+    // and comes back if the new one fails
+    const wasRunning = !!this.instance()?.running;
+    if (wasRunning) await downWorld(this.name, this.root);
+    try {
+      await branchWorld(this.name, name, { root: this.root, envFile: worldEnvPath(this.root), ...(opts.at ? { at: opts.at } : {}) });
+    } catch (error) {
+      if (wasRunning) await checkoutWorld(this.name, { root: this.root });
+      throw error;
+    }
     setCurrentBranch(this.root, name);
     return new World(name, this.root);
   }
@@ -261,28 +277,49 @@ export class World {
   }
 
   // ── the clock ───────────────────────────────────────────────────────────────────────────
-  /** The world's clock: the frozen instant every twin stamps from, or the wall clock when unset. */
-  clock(): { at: string; frozen: boolean } {
+  /** The world's clock (world-clock.cjs): its time now, and whether it is frozen at an instant, running (moved with
+   *  `shiftClock`), or the wall clock (unset). */
+  clock(): { at: string; frozen: boolean; running: boolean } {
     const file = clockFile(this.root, this.name);
-    return existsSync(file) ? { at: readFileSync(file, 'utf8').trim(), frozen: true } : { at: new Date().toISOString(), frozen: false };
+    if (!existsSync(file)) return { at: new Date().toISOString(), frozen: false, running: false };
+    const c = clockForm.parseClock(readFileSync(file, 'utf8'));
+    return { at: new Date(clockForm.clockNowMs(c, Date.now())).toISOString(), frozen: c.kind === 'frozen', running: c.kind === 'running' };
   }
-  /** Set the world's clock to an instant; every twin stamps from it until it moves. */
+  /** Set the world's clock to an instant; every twin, and the World's application, 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`);
+    this.writeClock({ kind: 'frozen', at: parsed });
     return new Date(parsed).toISOString();
   }
-  /** Move a set clock forward: `30d`, `12h`, `5m`, `90s`. */
+  /** Move a set clock forward, frozen or running: `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());
+    const file = clockFile(this.root, this.name);
+    if (!existsSync(file)) 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 (`volter world clock shift` moves a running World)');
+    const c = clockForm.parseClock(readFileSync(file, 'utf8'));
+    this.writeClock({ ...c, at: c.at + durationMs(by) });
+    return this.clock().at;
+  }
+  /** Move the World forward while its time keeps running (a World serving an application): from the wall clock, or a
+   *  running clock further. */
+  shiftClock(by: string): string {
+    const file = clockFile(this.root, this.name);
+    const c = existsSync(file) ? clockForm.parseClock(readFileSync(file, 'utf8')) : null;
+    if (c?.kind === 'frozen') throw new Error('the clock is frozen — `volter world clock advance` moves it');
+    const wall = Date.now();
+    this.writeClock(c ? { ...c, at: c.at + durationMs(by) } : { kind: 'running', at: wall + durationMs(by), since: wall });
+    return this.clock().at;
+  }
+  /** Return the World to the machine's time. */
+  clearClock(): string {
+    const file = clockFile(this.root, this.name);
+    if (existsSync(file)) rmSync(file);
+    return new Date().toISOString();
+  }
+  private writeClock(c: Parameters<typeof clockForm.formatClock>[0]): void {
+    const file = clockFile(this.root, this.name);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${clockForm.formatClock(c)}\n`);
   }
   /** 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) })); }