@volter/world 3.0.193 → 3.0.194

package/dist/examples/customer-onboarding/README.md

@@ -13,7 +13,7 @@ You need Node 22.6+, pnpm 12.15.0, Docker Compose and registry access during ins
 Copy this starter into a new folder:
 
 ```console
-$ npx @volter/world@3.0.193 example customer-onboarding --dir onboarding
+$ npx @volter/world@3.0.194 example customer-onboarding --dir onboarding
 $ cd onboarding
 $ pnpm install
 ```

package/dist/examples/customer-onboarding/demo.mjs

@@ -7,22 +7,22 @@ try {
   await initialize();
   switch (process.argv[2]) {
     case 'baseline': {
-      world.setClock(at);
+      await world.setClock(at);
       const rows = await listSignups();
       if (rows.length > 1 || rows.some(r => r.name !== 'Grace')) throw new Error('This demo contains customer work; reset both your disposable application database and demo World explicitly.');
       const grace = rows.find(r => r.name === 'Grace') ?? await onboard({ name: 'Grace', email: 'owner@world.test' });
-      world.advanceClock('5s');
+      await world.advanceClock('5s');
       console.log('Baseline', JSON.stringify(summarize((await listSignups()).find(r => r.customer_id === grace.customer_id)))); break;
     }
     case 'present': {
       const rows = await listSignups();
       if (rows.length !== 1 || rows[0].name !== 'Grace') throw new Error('Prepare the Grace-only baseline first.');
-      world.setClock(new Date(Date.parse(at) + 10_000).toISOString());
+      await world.setClock(new Date(Date.parse(at) + 10_000).toISOString());
       const partial = await onboard({ name: 'Ada', email: 'owner@world.test', from: 'Example <welcome@unverified.world.test>' });
       console.log('Email refusal; customer and SQL row retained', JSON.stringify(summarize(partial)));
       const retry = await retryWelcome(partial.customer_id);
       console.log('Retry accepted on the same customer', JSON.stringify(summarize(retry)));
-      world.advanceClock('5s');
+      await world.advanceClock('5s');
       console.log('Delivered', JSON.stringify((await listSignups()).map(summarize))); break;
     }
     default: throw new Error('Use baseline or present');

package/dist/examples/customer-onboarding/package.json

@@ -11,13 +11,13 @@
     "pg": "8.16.3"
   },
   "devDependencies": {
-    "@volter/world": "3.0.193",
-    "@volter/world-core": "3.0.166",
-    "@volter/world-runtime": "3.0.191",
-    "@volter/world-console": "3.0.161",
+    "@volter/world": "3.0.194",
+    "@volter/world-core": "3.0.167",
+    "@volter/world-runtime": "3.0.192",
+    "@volter/world-console": "3.0.162",
     "@volter/twin-stripe": "3.0.2",
     "@volter/twin-resend": "1.0.1",
-    "@volter/world-ui": "1.0.165"
+    "@volter/world-ui": "1.0.166"
   },
   "packageManager": "pnpm@12.15.0",
   "devEngines": {

package/dist/examples/integration-branches/README.md

@@ -13,7 +13,7 @@ Give two workers the same Stripe baseline, let them change different existing cu
 Use an empty parent folder. Create the baseline starter there:
 
 ```console
-$ npx @volter/world@3.0.193 example integration-branches --dir baseline
+$ npx @volter/world@3.0.194 example integration-branches --dir baseline
 $ cd baseline
 $ pnpm install
 $ ./node_modules/.bin/volter world init --name baseline --twins stripe
@@ -38,9 +38,9 @@ The stopped baseline retains its history and can supply local path remotes. Defa
 Create three more copies in the same parent folder:
 
 ```console
-$ npx @volter/world@3.0.193 example integration-branches --dir integration
-$ npx @volter/world@3.0.193 example integration-branches --dir worker-a
-$ npx @volter/world@3.0.193 example integration-branches --dir worker-b
+$ npx @volter/world@3.0.194 example integration-branches --dir integration
+$ npx @volter/world@3.0.194 example integration-branches --dir worker-a
+$ npx @volter/world@3.0.194 example integration-branches --dir worker-b
 ```
 
 In `integration`, then `worker-a`, then `worker-b`, install dependencies and initialize with the folder's name. Before a first boot or app write, link and pull the baseline:

package/dist/examples/integration-branches/package.json

@@ -9,12 +9,12 @@
     "stripe": "17.7.0"
   },
   "devDependencies": {
-    "@volter/world": "3.0.193",
-    "@volter/world-core": "3.0.166",
-    "@volter/world-runtime": "3.0.191",
-    "@volter/world-console": "3.0.161",
+    "@volter/world": "3.0.194",
+    "@volter/world-core": "3.0.167",
+    "@volter/world-runtime": "3.0.192",
+    "@volter/world-console": "3.0.162",
     "@volter/twin-stripe": "3.0.2",
-    "@volter/world-ui": "1.0.165"
+    "@volter/world-ui": "1.0.166"
   },
   "packageManager": "pnpm@12.15.0",
   "devEngines": {

package/dist/examples/workplace-agent/README.md

@@ -19,7 +19,7 @@ The catalog offers current defaults. Keep this example's manifest and installati
 together; its recorded workflow does not establish behavior for a different release.
 
 ```console
-$ npx @volter/world@3.0.193 example workplace-agent --dir workplace
+$ npx @volter/world@3.0.194 example workplace-agent --dir workplace
 $ cd workplace
 $ pnpm install
 $ ./node_modules/.bin/volter world init --name workplace --twins github,linear,slack

package/dist/examples/workplace-agent/package.json

@@ -11,14 +11,14 @@
     "@slack/web-api": "7.19.0"
   },
   "devDependencies": {
-    "@volter/world": "3.0.193",
-    "@volter/world-core": "3.0.166",
-    "@volter/world-runtime": "3.0.191",
-    "@volter/world-console": "3.0.161",
+    "@volter/world": "3.0.194",
+    "@volter/world-core": "3.0.167",
+    "@volter/world-runtime": "3.0.192",
+    "@volter/world-console": "3.0.162",
     "@volter/twin-github": "3.0.9",
     "@volter/twin-linear": "3.0.5",
     "@volter/twin-slack": "3.0.8",
-    "@volter/world-ui": "1.0.165"
+    "@volter/world-ui": "1.0.166"
   },
   "packageManager": "pnpm@12.15.0",
   "devEngines": {

package/dist/skills/volter-world/AGENTS.md

@@ -117,10 +117,12 @@ Identity comes from credentials in the vendor's manner; inspect `GET /twin` for
 identity and time rules. Use `clock set` and `clock advance` for backdated history. Without a
 frozen World clock, the runtime uses wall time.
 
-Author judgment, stateless lookups and faults in `handlers/<vendor>.json` in the World config
-directory (typically `.volter/handlers/`). These are ordered, first-match scenario rules.
-Edit the file and restart to load changes; a handler must never fake success for a stored
-mutation. `GET /twin/scenario` shows handler matches and misses; `tail` records misses to author.
+Place a vendor's judgment (a decision) and failures (faults) on a scenario's timeline,
+`scenarios/<name>.json` beside `world.json` (typically `.volter/scenarios/`), and run it with
+`volter world play <file>`: it resets to the default data, sets the clock to the scenario's
+`start` and makes the scenario the World's, which every twin reads at each request. A twin turns
+each input into its own answer and records it; nothing in a scenario answers in its place.
+`GET /twin/scenario` shows what is placed on that twin and what it consumed.
 Model twins serve deterministic scripts or labeled stubs, so verify calls and state changes,
 not the quality of prose from an unconfigured model.
 

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 a shared simulated internet (the world of the current directory)\n  volter world init [--install] [--name <world>] [--twins a,b] [--source vendor=package] [--allow-unknown]   detect or select vendors, choose installed publishers, 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 env [--template <file>]                    render deployment .env.world references into dotenv files\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 example list                                   ready application starters included in this CLI release\n  volter example <name> [--dir <path>]                    copy a cookbook starter into an empty directory; does not install or start it\n  volter world serve [--port <p>] [--console-port <c>] [--origin <url>]   serve this world on a URL under /<org>/<world>/ for apps; prints the token and the console (on loopback: view's front, no token in the browser)\n  volter world view [--port <p>] [--host <h>] [--no-open] [--no-origins] [--origin <url>]   step into this world in a browser: its twins' own UIs, timeline, clock, branches (a non-loopback --host serves them on one origin)\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 generate                                  write seed.generated.ts from world.json's people, organizations and accounts\n  volter world browser <name> [url] [--cdp <endpoint>]   open a person's saved World browser, signed in, through the running World (--cdp loads its cookies into a browser already open)\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>] [--remote <remote>] [--token <token>] [--force] send entries to the selected remote (default origin); vendor deployment follows its root policy\n  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved remote\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 submit --source <id> --vendor <vendor> --package <name> --version <exact>  prepare a catalog submission\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\nagents \u2014 your coding agent, driving the same verbs\n  volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]   put the volter-world skill and the MCP server into the agents found here\n  volter mcp                                             the MCP server (stdio) an agent starts: the verbs above as tools\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: approve it in the browser (or a token made under Account, for CI)\n  volter whoami                                          the platform the CLI is signed into, as whom, and its orgs\n  volter logout                                          revoke the CLI's token at the platform and forget it here\n  volter remote add <name> <url|path|org/world> [--token <token>] [--create]  name a remote; org/world (or world, in one org) resolves through the platform you logged into; --create makes it there from this world's twins\n  volter open [<org>/<world>] [--no-open]                a World's dashboard: a hosted one through the platform, else this world's (as view)\n  volter completion bash|zsh|fish|powershell             print a completion script for your shell\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  --version        the command's version\n";
+export declare const HELP = "volter \u2014 run your app against a world of twins\n\nworld  \u2014 a shared simulated internet (the world of the current directory)\n  volter world init [--install] [--name <world>] [--twins a,b] [--source vendor=package] [--allow-unknown]   detect or select vendors, choose installed publishers, 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 env [--template <file>]                    render deployment .env.world references into dotenv files\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 example list                                   ready application starters included in this CLI release\n  volter example <name> [--dir <path>]                    copy a cookbook starter into an empty directory; does not install or start it\n  volter world serve [--port <p>] [--console-port <c>] [--origin <url>]   serve this world on a URL under /<org>/<world>/ for apps; prints the token and the console (on loopback: view's front, no token in the browser)\n  volter world view [--port <p>] [--host <h>] [--no-open] [--no-origins] [--origin <url>]   step into this world in a browser: its twins' own UIs, timeline, clock, branches (a non-loopback --host serves them on one origin)\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 generate                                  write seed.generated.ts from world.json's people, organizations and accounts\n  volter world browser <name> [url] [--cdp <endpoint>]   open a person's saved World browser, signed in, through the running World (--cdp loads its cookies into a browser already open)\n  volter world seed                                      load the default data\n  volter world play <scenario.json>                      reset to the seed, play the scenario's timeline, check its properties\n  volter world mark [<id>]                               a run's position: the twins' logs and the clock (and the app's disk via the fault door)\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>] [--at <mark>|<instant>]   list branches, or make one (from here, or from a mark) 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>] [--remote <remote>] [--token <token>] [--force] send entries to the selected remote (default origin); vendor deployment follows its root policy\n  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved remote\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 submit --source <id> --vendor <vendor> --package <name> --version <exact>  prepare a catalog submission\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\nagents \u2014 your coding agent, driving the same verbs\n  volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]   put the volter-world skill and the MCP server into the agents found here\n  volter mcp                                             the MCP server (stdio) an agent starts: the verbs above as tools\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: approve it in the browser (or a token made under Account, for CI)\n  volter whoami                                          the platform the CLI is signed into, as whom, and its orgs\n  volter logout                                          revoke the CLI's token at the platform and forget it here\n  volter remote add <name> <url|path|org/world> [--token <token>] [--create]  name a remote; org/world (or world, in one org) resolves through the platform you logged into; --create makes it there from this world's twins\n  volter open [<org>/<world>] [--no-open]                a World's dashboard: a hosted one through the platform, else this world's (as view)\n  volter completion bash|zsh|fish|powershell             print a completion script for your shell\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  --version        the command's version\n";

package/dist/src/cli.js

@@ -60,9 +60,11 @@ world  — a shared simulated internet (the world of the current directory)
   volter world generate                                  write seed.generated.ts from world.json's people, organizations and accounts
   volter world browser <name> [url] [--cdp <endpoint>]   open a person's saved World browser, signed in, through the running World (--cdp loads its cookies into a browser already open)
   volter world seed                                      load the default data
+  volter world play <scenario.json>                      reset to the seed, play the scenario's timeline, check its properties
+  volter world mark [<id>]                               a run's position: the twins' logs and the clock (and the app's disk via the fault door)
   volter world reset                                     back to the default data
   volter world down [--purge]                            stop the twins (--purge forgets this branch's state)
-  volter world branch [<name>]                           list branches, or make one from here and check it out
+  volter world branch [<name>] [--at <mark>|<instant>]   list branches, or make one (from here, or from a mark) 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> | shift <N s|m|h|d> | clear   the world's clock: set, not observed
@@ -368,6 +370,32 @@ async function worldCommand(verb, args) {
                 process.exitCode = r.exitCode;
             return;
         }
+        case 'mark': {
+            const m = await world.mark(pos[0]);
+            if (asJson) {
+                json(m);
+                return;
+            }
+            out(`mark ${m.id}  ${m.ledgers.length} twin log${m.ledgers.length === 1 ? '' : 's'}  clock ${m.clock ?? 'the machine\'s'}  ${m.disk ? 'with the app\'s disk' : 'without the app\'s disk (no fault door)'}`);
+            return;
+        }
+        case 'play': {
+            const file = pos[0];
+            if (!file)
+                throw new Error('volter world play <scenario.json>');
+            const r = await world.play(file);
+            if (asJson) {
+                json(r);
+                return;
+            }
+            out(`played ${r.scenario}  ${r.start} → ${r.end}  ${r.calls.length} call${r.calls.length === 1 ? '' : 's'}`);
+            out(r.completeness.total === 0 ? 'complete  the World was the whole internet this run reached' : `incomplete  ${Object.entries(r.completeness.egress).map(([d, n]) => `${d} refused ${n.refused}${n.passed ? ` passed ${n.passed}` : ''}`).concat(Object.entries(r.completeness.unimplemented).flatMap(([v, ops]) => Object.entries(ops).map(([op, n]) => `${v} ${op} unimplemented ${n}`))).concat(Object.entries(r.completeness.machine).map(([f, n]) => `${f} fault refused ${n} (no fault door)`)).join('; ')}`);
+            for (const p of r.properties)
+                out(`${p.verdict.padEnd(8)} ${p.kind.padEnd(10)} ${p.name}${p.step !== undefined ? `  (step ${p.step}, ${p.at})` : ''}`);
+            if (r.properties.some((p) => p.verdict === 'broken'))
+                process.exitCode = 1;
+            return;
+        }
         case 'reset': {
             const r = await world.reset();
             out(`Back to the default data on ${r.world}: ${Object.entries(r.observed).map(([s, n]) => `${s} ${n}`).join(', ') || 'nothing recorded'}`);
@@ -383,13 +411,13 @@ async function worldCommand(verb, args) {
                 return;
             }
             const atText = value(args, '--at');
-            const at = atText === undefined ? undefined : /^\d{4}-\d\d-\d\d/.test(atText) ? { instant: atText } : (() => {
+            const at = atText === undefined ? undefined : /^\d{4}-\d\d-\d\d/.test(atText) ? { instant: atText } : !atText.includes('@') ? { mark: atText } : (() => {
                 const positions = {};
                 const views = {};
                 for (const p of atText.split(',')) {
                     const match = /^([^@]+)@(?:([a-f0-9]{64}):)?(\d+)$/.exec(p);
                     if (!match)
-                        throw new Error('--at takes an instant, twin@position, or twin@view:position');
+                        throw new Error('--at takes an instant, a mark, twin@position, or twin@view:position');
                     positions[match[1]] = Number(match[3]);
                     if (match[2])
                         views[match[1]] = match[2];
@@ -414,23 +442,23 @@ async function worldCommand(verb, args) {
             if (action === 'set') {
                 if (!arg)
                     throw new Error('volter world clock set <iso-8601>');
-                out(world.setClock(arg));
+                out(await 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));
+                out(await 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));
+                out(await world.shiftClock(arg));
                 return;
             }
             if (action === 'clear') {
-                out(world.clearClock());
+                out(await world.clearClock());
                 return;
             }
             if (action === undefined || action === 'show') {

package/dist/src/index.d.ts

@@ -1,3 +1,4 @@
 export { World, parseOriginUrl, worldNameFor, type LogEntry, type WorldMode, type WorldRef, type WorldStatus } from './world.js';
 export { findWorldRoot, requireWorldRoot, currentBranch, setCurrentBranch, mainBranch, worldConfigPath, worldEnvPath, worldSeedPath, WORLD_FILE } from './locate.js';
 export { credentialsPath, requireToken, storeToken, tokenFor } from './credentials.js';
+export { always, sometimes, eventually, type Property, type RunReport } from '@volter/world-runtime';

package/dist/src/index.js

@@ -4,3 +4,5 @@
 export { World, parseOriginUrl, worldNameFor } from "./world.js";
 export { findWorldRoot, requireWorldRoot, currentBranch, setCurrentBranch, mainBranch, worldConfigPath, worldEnvPath, worldSeedPath, WORLD_FILE } from "./locate.js";
 export { credentialsPath, requireToken, storeToken, tokenFor } from "./credentials.js";
+// a scenario's properties (ADR 0036 §7): `export default [always(...), sometimes(...), eventually(...)]`
+export { always, sometimes, eventually } from '@volter/world-runtime';

package/dist/src/world-browser.js

@@ -1,7 +1,9 @@
 // `volter world browser <name> [url] [--cdp <endpoint>]`: a person's saved World browser opened in a real browser
 // (ADR 0016, rows 3 and 4). The profile is read through the World's own record reader and the browser is routed through
 // the World's proxy with its CA trusted, as attach publishes them. Nothing is written back to the World.
-import { deriveWorldManifest, statusWorld, worldBrowser, worldBrowsers } from '@volter/world-runtime';
+import { clockFile, deriveWorldManifest, followWorld, overlayWorldPackFacts, statusWorld, worldBrowser, worldBrowsers } from '@volter/world-runtime';
+import clockForm from '@volter/world-core/world-clock';
+import { existsSync, readFileSync } from 'node:fs';
 export async function openWorldBrowser(world, name, url, cdp, say) {
     const instance = statusWorld(world.name, world.root);
     const record = worldBrowser(instance.dirs.data, name);
@@ -9,6 +11,7 @@ export async function openWorldBrowser(world, name, url, cdp, say) {
         const names = worldBrowsers(instance.dirs.data).map(row => row.name);
         throw new Error(`World "${world.name}" has no browser "${name}" (has: ${names.join(', ') || 'none'})`);
     }
+    overlayWorldPackFacts({ configPath: instance.configPath, root: world.root });
     const manifest = deriveWorldManifest(world.name, instance.env ?? {});
     if (!instance.running || !manifest.browser)
         throw new Error('the World is not running, so it has no proxy to route a browser through: start it with `volter world up`');
@@ -20,10 +23,14 @@ export async function openWorldBrowser(world, name, url, cdp, say) {
         throw new Error('volter world browser needs playwright: npm i playwright');
     }
     const profile = record.state;
+    // the page follows the World (ADR 0036 §6): its clock as the World's stands, its randomness seeded by World and browser
+    const clock = existsSync(clockFile(world.root, world.name)) ? clockForm.parseClock(readFileSync(clockFile(world.root, world.name), 'utf8')) : null;
+    const follow = { now: new Date(clock ? clockForm.clockNowMs(clock, Date.now()) : Date.now()).toISOString(), frozen: clock?.kind === 'frozen', random: `${world.name}:${name}` };
     if (cdp === undefined) {
         const browser = await chromium.launch({ headless: false, args: manifest.browser.args });
         const closed = new Promise(resolve => browser.on('disconnected', () => resolve()));
         const context = await browser.newContext({ ...profile.context, storageState: profile.storageState });
+        await followWorld(context, follow);
         const page = await context.newPage();
         await page.goto(url ?? 'about:blank');
         await closed;
@@ -37,6 +44,7 @@ export async function openWorldBrowser(world, name, url, cdp, say) {
     if (Object.keys(profile.context).length)
         say(`note   ${name}'s context options (${Object.keys(profile.context).join(', ')}) were not applied: an existing browser's default context takes none`);
     await context.addCookies(profile.storageState.cookies);
+    await followWorld(context, follow);
     const page = await context.newPage();
     await page.goto(url ?? 'about:blank');
     await browser.close();

package/dist/src/world.d.ts

@@ -1,12 +1,14 @@
 import { renderDeploymentTemplates, type DeploymentTemplate } from '@volter/world-runtime/deployment-env';
 import { rebaseChangeset, worldBootMarker, type Changeset, type LedgerDelta, type TwinAction, type WorldMarker, type ApplyReceipt, applyTwinWrite, type TwinResource } from '@volter/world-core/runtime';
-import { approveWorldChangeset, createWorldChangeset, downWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, seedServedWorld, seedWorld, statusWorld, writeGeneratedSeed, statusWorldChangeset, verifyWorldChangeset, type ServedWorld, type ViewConsole, type WorldView, rootCredentialInput, type DeployTwinOutcome, type ChangesetLocation, type InitOptions, type InitResult, type WorldInstance } from '@volter/world-runtime';
+import { approveWorldChangeset, createWorldChangeset, downWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, seedServedWorld, seedWorld, playWorld, statusWorld, writeGeneratedSeed, statusWorldChangeset, verifyWorldChangeset, type ServedWorld, type ViewConsole, type WorldView, rootCredentialInput, type DeployTwinOutcome, type ChangesetLocation, type InitOptions, type InitResult, type WorldInstance } from '@volter/world-runtime';
 import { rebaseBranch, type Receipt, type RootConfig } from '@volter/world-core/runtime';
 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 declare class TwinLog {
     readonly service: string;
     readonly stateService: string;
@@ -153,6 +155,8 @@ export declare class World {
     hasSeed(): boolean;
     /** Set up a served World this one is linked to from this world's seed: run there through its own twins, then marked. */
     seedServed(base: string, token: string): ReturnType<typeof seedServedWorld>;
+    /** A run of a scenario (ADR 0036): back to the seed, its timeline played at World times, its properties checked. */
+    play(scenario: string): ReturnType<typeof playWorld>;
     /** Back to the default data: forget this branch's state, boot, seed. */
     reset(opts?: {
         entry?: string;
@@ -168,6 +172,7 @@ export declare class World {
             instant?: string;
             positions?: Record<string, number>;
             views?: Record<string, string>;
+            mark?: string;
         };
     }): Promise<World>;
     /** Switch to a branch: its twins come back with their state; this branch's stop. */
@@ -187,15 +192,17 @@ export declare class World {
         frozen: boolean;
         running: boolean;
     };
-    /** 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, frozen or running: `30d`, `12h`, `5m`, `90s`. */
-    advanceClock(by: string): string;
+    /** Set the world's clock to an instant; every twin, and the World's application, stamps from it until it moves. The
+     *  clock is written at once; the answer comes once every twin has done what the move made due (ADR 0036 §4). */
+    setClock(iso: string): Promise<string>;
+    /** Move a set clock forward, frozen or running: `30d`, `12h`, `5m`, `90s`. Answers as setClock does. */
+    advanceClock(by: string): Promise<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;
+     *  running clock further. Answers as setClock does. */
+    shiftClock(by: string): Promise<string>;
+    /** Return the World to the machine's time. Answers as setClock does: what the move made due is done first. */
+    clearClock(): Promise<string>;
+    private settled;
     private writeClock;
     /** Rebase this branch onto its base's current position, every twin; conflicts named per subject and field. */
     rebaseBranch(): Array<{
@@ -291,7 +298,9 @@ export declare class World {
         token?: string;
         force?: boolean;
     }): Promise<Array<Awaited<ReturnType<typeof pushWorldChangeset>>>>;
-    mark(id?: string, now?: Date): WorldMarker;
+    /** A mark: every twin's position and history view, and the World clock, a run's position (ADR 0036 §5); the app's disk
+     *  joins them where the host gives the World its machine's fault door (`VOLTER_WORLD_MACHINE_DOOR`). */
+    mark(id?: string, now?: Date): Promise<WorldMarker>;
     marks(): WorldMarker[];
     verify(name: string, opts?: {
         into?: string;

package/dist/src/world.js

@@ -7,21 +7,14 @@ import { platformPerson } from "./credentials.js";
 import { rebaseChangeset, worldBootMarker, listActions, inWorldHistory, pushablePendingActions, pendingActions, applyTwinWrite, twinResources } from '@volter/world-core/runtime';
 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, seedServedWorld, seedWorld, shellWorld, materializeBrowserFiles, statusWorld, writeGeneratedSeed, statusWorldChangeset, upWorld, verifyWorldChangeset, worldLedgers, worldOrigin, bindLegacyCredentials, deployWorld, loadWorldConfig, writeWorldConfig, readServeRecord, refreshTwin, serveWorld, serveWorldView, findInstalledPackage, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom, rootCredentialInput, withoutVaultSignIn, materializeRoots, instanceDir, worldChangesetRules } from '@volter/world-runtime';
+import { activateScript, approveWorldChangeset, branchWorld, clockFile, checkoutWorld, createWorldChangeset, diffWorld, downWorld, fetchFromOrigin, findWorldChangeset, initWorld, listWorldChangesets, listWorldMarks, listWorlds, markWorld, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, runWithWorldEnv, seedServedWorld, seedWorld, shellWorld, findWorldMark, machineDoor, materializeBrowserFiles, playWorld, settleLocalWorldTime, statusWorld, writeGeneratedSeed, statusWorldChangeset, upWorld, verifyWorldChangeset, worldLedgers, worldOrigin, bindLegacyCredentials, deployWorld, loadWorldConfig, writeWorldConfig, readServeRecord, refreshTwin, serveWorld, serveWorldView, findInstalledPackage, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom, rootCredentialInput, withoutVaultSignIn, materializeRoots, instanceDir, worldChangesetRules } from '@volter/world-runtime';
 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, worldConfigPath, worldEnvPath, worldSeedPath } from "./locate.js";
-import { destinationOf, parentEntries, rebaseBranch } from '@volter/world-core/runtime';
+import { destinationOf, durationMs, parentEntries, rebaseBranch } from '@volter/world-core/runtime';
 /** 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;
@@ -255,6 +248,8 @@ export class World {
     hasSeed() { return existsSync(worldSeedPath(this.root)); }
     /** Set up a served World this one is linked to from this world's seed: run there through its own twins, then marked. */
     seedServed(base, token) { return seedServedWorld(base, token, { root: this.root, config: this.configRef(), cwd: this.root }); }
+    /** A run of a scenario (ADR 0036): back to the seed, its timeline played at World times, its properties checked. */
+    play(scenario) { return playWorld(this.name, { root: this.root, scenario }); }
     /** Back to the default data: forget this branch's state, boot, seed. */
     reset(opts = {}) { return resetWorld(this.name, { root: this.root, cwd: this.root, ...opts }); }
     // ── branches ────────────────────────────────────────────────────────────────────────────
@@ -264,6 +259,14 @@ export class World {
      * one starts; `checkout` brings it back with its state.
      */
     async branch(name, opts = {}) {
+        // at a mark: from the branch it was taken on, at each twin's view and position there, with its clock (and the app's
+        // disk through the machine's fault door, where the mark took it)
+        const mark = opts.at?.mark !== undefined ? findWorldMark(opts.at.mark, this.root) : undefined;
+        const door = mark?.disk ? machineDoor() : null;
+        if (mark?.disk && !door)
+            throw new Error(`mark "${mark.id}" holds the app's disk, and this host gives no fault door to restore it through (VOLTER_WORLD_MACHINE_DOOR)`);
+        const base = mark?.world ?? this.name;
+        const at = mark ? { positions: Object.fromEntries(mark.ledgers.flatMap((l) => (l.position !== undefined ? [[l.stateService, l.position]] : []))), views: Object.fromEntries(mark.ledgers.flatMap((l) => (l.view !== undefined ? [[l.stateService, l.view]] : []))) } : opts.at;
         if (listWorlds(this.root).some((w) => w.name === name))
             throw new Error(`A branch "${name}" already exists — \`volter world checkout ${name}\` switches to it`);
         this.refuseWhileServed('branch');
@@ -273,7 +276,7 @@ export class World {
         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 } : {}) });
+            await branchWorld(base, name, { root: this.root, envFile: worldEnvPath(this.root), ...(at ? { at } : {}) });
         }
         catch (error) {
             if (wasRunning)
@@ -283,7 +286,16 @@ export class World {
         setCurrentBranch(this.root, name);
         const selected = statusWorld(name, this.root);
         materializeBrowserFiles(selected.dirs.data, this.root, name, selected.config);
-        return new World(name, this.root);
+        const made = new World(name, this.root);
+        if (mark) {
+            if (mark.clock)
+                await made.setClock(mark.clock);
+            else if (mark.clock === null)
+                await made.clearClock();
+            if (door)
+                await door.restorePosition(mark.id);
+        }
+        return made;
     }
     /** Switch to a branch: its twins come back with their state; this branch's stop. */
     async checkout(name) {
@@ -333,25 +345,26 @@ export class World {
         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, and the World's application, 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. The
+     *  clock is written at once; the answer comes once every twin has done what the move made due (ADR 0036 §4). */
     setClock(iso) {
         const parsed = Date.parse(iso);
         if (Number.isNaN(parsed))
             throw new Error(`${JSON.stringify(iso)} is not an ISO-8601 instant`);
         this.writeClock({ kind: 'frozen', at: parsed });
-        return new Date(parsed).toISOString();
+        return this.settled(new Date(parsed).toISOString());
     }
-    /** Move a set clock forward, frozen or running: `30d`, `12h`, `5m`, `90s`. */
+    /** Move a set clock forward, frozen or running: `30d`, `12h`, `5m`, `90s`. Answers as setClock does. */
     advanceClock(by) {
         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;
+        return this.settled(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. */
+     *  running clock further. Answers as setClock does. */
     shiftClock(by) {
         const file = clockFile(this.root, this.name);
         const c = existsSync(file) ? clockForm.parseClock(readFileSync(file, 'utf8')) : null;
@@ -359,14 +372,18 @@ export class World {
             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 this.settled(this.clock().at);
     }
-    /** Return the World to the machine's time. */
+    /** Return the World to the machine's time. Answers as setClock does: what the move made due is done first. */
     clearClock() {
         const file = clockFile(this.root, this.name);
         if (existsSync(file))
             rmSync(file);
-        return new Date().toISOString();
+        return this.settled(new Date().toISOString());
+    }
+    async settled(at) {
+        await settleLocalWorldTime(this.name, this.root);
+        return at;
     }
     writeClock(c) {
         const file = clockFile(this.root, this.name);
@@ -562,7 +579,15 @@ export class World {
         return outcomes;
     }
     // ── review (the operator's verbs, kept on the SDK for the remote and for CI) ────────────
-    mark(id, now) { return markWorld(this.name, { root: this.root, ...(id ? { id } : {}), ...(now ? { now } : {}) }); }
+    /** A mark: every twin's position and history view, and the World clock, a run's position (ADR 0036 §5); the app's disk
+     *  joins them where the host gives the World its machine's fault door (`VOLTER_WORLD_MACHINE_DOOR`). */
+    async mark(id, now) {
+        const door = machineDoor();
+        const marker = markWorld(this.name, { root: this.root, ...(id ? { id } : {}), ...(now ? { now } : {}), ...(door ? { disk: true } : {}) });
+        if (door)
+            await door.takePosition(marker.id);
+        return marker;
+    }
     marks() { return listWorldMarks(this.name, this.root); }
     verify(name, opts = { ephemeral: true }) { return verifyWorldChangeset(name, { root: this.root, world: this.name, ...opts }); }
     approve(name, principal, note) { return approveWorldChangeset(name, { root: this.root, world: this.name, principal, ...(note ? { note } : {}) }); }

package/examples/customer-onboarding/README.md

@@ -13,7 +13,7 @@ You need Node 22.6+, pnpm 12.15.0, Docker Compose and registry access during ins
 Copy this starter into a new folder:
 
 ```console
-$ npx @volter/world@3.0.193 example customer-onboarding --dir onboarding
+$ npx @volter/world@3.0.194 example customer-onboarding --dir onboarding
 $ cd onboarding
 $ pnpm install
 ```

package/examples/customer-onboarding/demo.mjs

@@ -7,22 +7,22 @@ try {
   await initialize();
   switch (process.argv[2]) {
     case 'baseline': {
-      world.setClock(at);
+      await world.setClock(at);
       const rows = await listSignups();
       if (rows.length > 1 || rows.some(r => r.name !== 'Grace')) throw new Error('This demo contains customer work; reset both your disposable application database and demo World explicitly.');
       const grace = rows.find(r => r.name === 'Grace') ?? await onboard({ name: 'Grace', email: 'owner@world.test' });
-      world.advanceClock('5s');
+      await world.advanceClock('5s');
       console.log('Baseline', JSON.stringify(summarize((await listSignups()).find(r => r.customer_id === grace.customer_id)))); break;
     }
     case 'present': {
       const rows = await listSignups();
       if (rows.length !== 1 || rows[0].name !== 'Grace') throw new Error('Prepare the Grace-only baseline first.');
-      world.setClock(new Date(Date.parse(at) + 10_000).toISOString());
+      await world.setClock(new Date(Date.parse(at) + 10_000).toISOString());
       const partial = await onboard({ name: 'Ada', email: 'owner@world.test', from: 'Example <welcome@unverified.world.test>' });
       console.log('Email refusal; customer and SQL row retained', JSON.stringify(summarize(partial)));
       const retry = await retryWelcome(partial.customer_id);
       console.log('Retry accepted on the same customer', JSON.stringify(summarize(retry)));
-      world.advanceClock('5s');
+      await world.advanceClock('5s');
       console.log('Delivered', JSON.stringify((await listSignups()).map(summarize))); break;
     }
     default: throw new Error('Use baseline or present');

package/examples/customer-onboarding/package.json

@@ -11,13 +11,13 @@
     "pg": "8.16.3"
   },
   "devDependencies": {
-    "@volter/world": "3.0.193",
-    "@volter/world-core": "3.0.166",
-    "@volter/world-runtime": "3.0.191",
-    "@volter/world-console": "3.0.161",
+    "@volter/world": "3.0.194",
+    "@volter/world-core": "3.0.167",
+    "@volter/world-runtime": "3.0.192",
+    "@volter/world-console": "3.0.162",
     "@volter/twin-stripe": "3.0.2",
     "@volter/twin-resend": "1.0.1",
-    "@volter/world-ui": "1.0.165"
+    "@volter/world-ui": "1.0.166"
   },
   "packageManager": "pnpm@12.15.0",
   "devEngines": {

package/examples/integration-branches/README.md

@@ -13,7 +13,7 @@ Give two workers the same Stripe baseline, let them change different existing cu
 Use an empty parent folder. Create the baseline starter there:
 
 ```console
-$ npx @volter/world@3.0.193 example integration-branches --dir baseline
+$ npx @volter/world@3.0.194 example integration-branches --dir baseline
 $ cd baseline
 $ pnpm install
 $ ./node_modules/.bin/volter world init --name baseline --twins stripe
@@ -38,9 +38,9 @@ The stopped baseline retains its history and can supply local path remotes. Defa
 Create three more copies in the same parent folder:
 
 ```console
-$ npx @volter/world@3.0.193 example integration-branches --dir integration
-$ npx @volter/world@3.0.193 example integration-branches --dir worker-a
-$ npx @volter/world@3.0.193 example integration-branches --dir worker-b
+$ npx @volter/world@3.0.194 example integration-branches --dir integration
+$ npx @volter/world@3.0.194 example integration-branches --dir worker-a
+$ npx @volter/world@3.0.194 example integration-branches --dir worker-b
 ```
 
 In `integration`, then `worker-a`, then `worker-b`, install dependencies and initialize with the folder's name. Before a first boot or app write, link and pull the baseline:

package/examples/integration-branches/package.json

@@ -9,12 +9,12 @@
     "stripe": "17.7.0"
   },
   "devDependencies": {
-    "@volter/world": "3.0.193",
-    "@volter/world-core": "3.0.166",
-    "@volter/world-runtime": "3.0.191",
-    "@volter/world-console": "3.0.161",
+    "@volter/world": "3.0.194",
+    "@volter/world-core": "3.0.167",
+    "@volter/world-runtime": "3.0.192",
+    "@volter/world-console": "3.0.162",
     "@volter/twin-stripe": "3.0.2",
-    "@volter/world-ui": "1.0.165"
+    "@volter/world-ui": "1.0.166"
   },
   "packageManager": "pnpm@12.15.0",
   "devEngines": {

package/examples/workplace-agent/README.md

@@ -19,7 +19,7 @@ The catalog offers current defaults. Keep this example's manifest and installati
 together; its recorded workflow does not establish behavior for a different release.
 
 ```console
-$ npx @volter/world@3.0.193 example workplace-agent --dir workplace
+$ npx @volter/world@3.0.194 example workplace-agent --dir workplace
 $ cd workplace
 $ pnpm install
 $ ./node_modules/.bin/volter world init --name workplace --twins github,linear,slack

package/examples/workplace-agent/package.json

@@ -11,14 +11,14 @@
     "@slack/web-api": "7.19.0"
   },
   "devDependencies": {
-    "@volter/world": "3.0.193",
-    "@volter/world-core": "3.0.166",
-    "@volter/world-runtime": "3.0.191",
-    "@volter/world-console": "3.0.161",
+    "@volter/world": "3.0.194",
+    "@volter/world-core": "3.0.167",
+    "@volter/world-runtime": "3.0.192",
+    "@volter/world-console": "3.0.162",
     "@volter/twin-github": "3.0.9",
     "@volter/twin-linear": "3.0.5",
     "@volter/twin-slack": "3.0.8",
-    "@volter/world-ui": "1.0.165"
+    "@volter/world-ui": "1.0.166"
   },
   "packageManager": "pnpm@12.15.0",
   "devEngines": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world",
-  "version": "3.0.193",
+  "version": "3.0.194",
   "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",
@@ -31,12 +31,12 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.1",
-    "@volter/world-core": "3.0.166",
-    "@volter/world-runtime": "3.0.191",
+    "@volter/world-core": "3.0.167",
+    "@volter/world-runtime": "3.0.192",
     "zod": "^4.6.5"
   },
   "peerDependencies": {
-    "@volter/world-console": "3.0.161",
+    "@volter/world-console": "3.0.162",
     "playwright": "^1.63.0"
   },
   "peerDependenciesMeta": {
@@ -49,7 +49,7 @@
   },
   "devDependencies": {
     "@volter/twin-anthropic": "1.0.6",
-    "@volter/world-console": "3.0.161"
+    "@volter/world-console": "3.0.162"
   },
   "bin": {
     "volter": "dist/src/cli.js"

package/skills/volter-world/AGENTS.md

@@ -117,10 +117,12 @@ Identity comes from credentials in the vendor's manner; inspect `GET /twin` for
 identity and time rules. Use `clock set` and `clock advance` for backdated history. Without a
 frozen World clock, the runtime uses wall time.
 
-Author judgment, stateless lookups and faults in `handlers/<vendor>.json` in the World config
-directory (typically `.volter/handlers/`). These are ordered, first-match scenario rules.
-Edit the file and restart to load changes; a handler must never fake success for a stored
-mutation. `GET /twin/scenario` shows handler matches and misses; `tail` records misses to author.
+Place a vendor's judgment (a decision) and failures (faults) on a scenario's timeline,
+`scenarios/<name>.json` beside `world.json` (typically `.volter/scenarios/`), and run it with
+`volter world play <file>`: it resets to the default data, sets the clock to the scenario's
+`start` and makes the scenario the World's, which every twin reads at each request. A twin turns
+each input into its own answer and records it; nothing in a scenario answers in its place.
+`GET /twin/scenario` shows what is placed on that twin and what it consumed.
 Model twins serve deterministic scripts or labeled stubs, so verify calls and state changes,
 not the quality of prose from an unconfigured model.
 

package/src/cli.ts

@@ -51,9 +51,11 @@ world  — a shared simulated internet (the world of the current directory)
   volter world generate                                  write seed.generated.ts from world.json's people, organizations and accounts
   volter world browser <name> [url] [--cdp <endpoint>]   open a person's saved World browser, signed in, through the running World (--cdp loads its cookies into a browser already open)
   volter world seed                                      load the default data
+  volter world play <scenario.json>                      reset to the seed, play the scenario's timeline, check its properties
+  volter world mark [<id>]                               a run's position: the twins' logs and the clock (and the app's disk via the fault door)
   volter world reset                                     back to the default data
   volter world down [--purge]                            stop the twins (--purge forgets this branch's state)
-  volter world branch [<name>]                           list branches, or make one from here and check it out
+  volter world branch [<name>] [--at <mark>|<instant>]   list branches, or make one (from here, or from a mark) 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> | shift <N s|m|h|d> | clear   the world's clock: set, not observed
@@ -302,6 +304,23 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
       if (r.exitCode !== 0) process.exitCode = r.exitCode;
       return;
     }
+    case 'mark': {
+      const m = await world.mark(pos[0]);
+      if (asJson) { json(m); return; }
+      out(`mark ${m.id}  ${m.ledgers.length} twin log${m.ledgers.length === 1 ? '' : 's'}  clock ${m.clock ?? 'the machine\'s'}  ${m.disk ? 'with the app\'s disk' : 'without the app\'s disk (no fault door)'}`);
+      return;
+    }
+    case 'play': {
+      const file = pos[0];
+      if (!file) throw new Error('volter world play <scenario.json>');
+      const r = await world.play(file);
+      if (asJson) { json(r); return; }
+      out(`played ${r.scenario}  ${r.start} → ${r.end}  ${r.calls.length} call${r.calls.length === 1 ? '' : 's'}`);
+      out(r.completeness.total === 0 ? 'complete  the World was the whole internet this run reached' : `incomplete  ${Object.entries(r.completeness.egress).map(([d, n]) => `${d} refused ${n.refused}${n.passed ? ` passed ${n.passed}` : ''}`).concat(Object.entries(r.completeness.unimplemented).flatMap(([v, ops]) => Object.entries(ops).map(([op, n]) => `${v} ${op} unimplemented ${n}`))).concat(Object.entries(r.completeness.machine).map(([f, n]) => `${f} fault refused ${n} (no fault door)`)).join('; ')}`);
+      for (const p of r.properties) out(`${p.verdict.padEnd(8)} ${p.kind.padEnd(10)} ${p.name}${p.step !== undefined ? `  (step ${p.step}, ${p.at})` : ''}`);
+      if (r.properties.some((p) => p.verdict === 'broken')) process.exitCode = 1;
+      return;
+    }
     case 'reset': {
       const r = await world.reset();
       out(`Back to the default data on ${r.world}: ${Object.entries(r.observed).map(([s, n]) => `${s} ${n}`).join(', ') || 'nothing recorded'}`);
@@ -312,11 +331,11 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
       const name = pos[0];
       if (!name) { for (const b of world.branches()) out(`${b === world.name ? '* ' : '  '}${b}`); return; }
       const atText = value(args, '--at');
-      const at = atText === undefined ? undefined : /^\d{4}-\d\d-\d\d/.test(atText) ? { instant: atText } : (() => {
+      const at = atText === undefined ? undefined : /^\d{4}-\d\d-\d\d/.test(atText) ? { instant: atText } : !atText.includes('@') ? { mark: atText } : (() => {
         const positions: Record<string, number> = {}; const views: Record<string, string> = {};
         for (const p of atText.split(',')) {
           const match = /^([^@]+)@(?:([a-f0-9]{64}):)?(\d+)$/.exec(p);
-          if (!match) throw new Error('--at takes an instant, twin@position, or twin@view:position');
+          if (!match) throw new Error('--at takes an instant, a mark, twin@position, or twin@view:position');
           positions[match[1]!] = Number(match[3]); if (match[2]) views[match[1]!] = match[2];
         }
         return { positions, views };
@@ -335,10 +354,10 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
     }
     case 'clock': {
       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 === '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 === 'set') { if (!arg) throw new Error('volter world clock set <iso-8601>'); out(await world.setClock(arg)); return; }
+      if (action === 'advance') { if (!arg) throw new Error('volter world clock advance <N s|m|h|d>'); out(await world.advanceClock(arg)); return; }
+      if (action === 'shift') { if (!arg) throw new Error('volter world clock shift <N s|m|h|d>'); out(await world.shiftClock(arg)); return; }
+      if (action === 'clear') { out(await 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');
     }

package/src/index.ts

@@ -4,3 +4,5 @@
 export { World, parseOriginUrl, worldNameFor, type LogEntry, type WorldMode, type WorldRef, type WorldStatus } from './world.ts';
 export { findWorldRoot, requireWorldRoot, currentBranch, setCurrentBranch, mainBranch, worldConfigPath, worldEnvPath, worldSeedPath, WORLD_FILE } from './locate.ts';
 export { credentialsPath, requireToken, storeToken, tokenFor } from './credentials.ts';
+// a scenario's properties (ADR 0036 §7): `export default [always(...), sometimes(...), eventually(...)]`
+export { always, sometimes, eventually, type Property, type RunReport } from '@volter/world-runtime';

package/src/sdk.test.ts

@@ -68,8 +68,8 @@ describe('World — the twins an app needs, running together', () => {
     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)
-    back.setClock(AT);
-    back.advanceClock('1h');
+    await back.setClock(AT);
+    await back.advanceClock('1h');
     const retainedClock = back.clock();
     await back.down();
     expect(back.status().running).toBe(false);

package/src/world-browser.ts

@@ -1,7 +1,9 @@
 // `volter world browser <name> [url] [--cdp <endpoint>]`: a person's saved World browser opened in a real browser
 // (ADR 0016, rows 3 and 4). The profile is read through the World's own record reader and the browser is routed through
 // the World's proxy with its CA trusted, as attach publishes them. Nothing is written back to the World.
-import { deriveWorldManifest, statusWorld, worldBrowser, worldBrowsers } from '@volter/world-runtime';
+import { clockFile, deriveWorldManifest, followWorld, overlayWorldPackFacts, statusWorld, worldBrowser, worldBrowsers } from '@volter/world-runtime';
+import clockForm from '@volter/world-core/world-clock';
+import { existsSync, readFileSync } from 'node:fs';
 
 export async function openWorldBrowser(world: { name: string; root: string }, name: string, url: string | undefined, cdp: string | undefined, say: (line: string) => void): Promise<void> {
   const instance = statusWorld(world.name, world.root);
@@ -10,16 +12,21 @@ export async function openWorldBrowser(world: { name: string; root: string }, na
     const names = worldBrowsers(instance.dirs.data).map(row => row.name);
     throw new Error(`World "${world.name}" has no browser "${name}" (has: ${names.join(', ') || 'none'})`);
   }
+  overlayWorldPackFacts({ configPath: instance.configPath, root: world.root });
   const manifest = deriveWorldManifest(world.name, instance.env ?? {});
   if (!instance.running || !manifest.browser) throw new Error('the World is not running, so it has no proxy to route a browser through: start it with `volter world up`');
   let chromium: typeof import('playwright').chromium;
   try { ({ chromium } = await import('playwright')); }
   catch { throw new Error('volter world browser needs playwright: npm i playwright'); }
   const profile = record.state;
+  // the page follows the World (ADR 0036 §6): its clock as the World's stands, its randomness seeded by World and browser
+  const clock = existsSync(clockFile(world.root, world.name)) ? clockForm.parseClock(readFileSync(clockFile(world.root, world.name), 'utf8')) : null;
+  const follow = { now: new Date(clock ? clockForm.clockNowMs(clock, Date.now()) : Date.now()).toISOString(), frozen: clock?.kind === 'frozen', random: `${world.name}:${name}` };
   if (cdp === undefined) {
     const browser = await chromium.launch({ headless: false, args: manifest.browser.args });
     const closed = new Promise<void>(resolve => browser.on('disconnected', () => resolve()));
     const context = await browser.newContext({ ...profile.context, storageState: profile.storageState } as Parameters<typeof browser.newContext>[0]);
+    await followWorld(context, follow);
     const page = await context.newPage();
     await page.goto(url ?? 'about:blank');
     await closed;
@@ -31,6 +38,7 @@ export async function openWorldBrowser(world: { name: string; root: string }, na
   // An existing default context takes no context options (ADR 0016): its cookies are what is loaded.
   if (Object.keys(profile.context).length) say(`note   ${name}'s context options (${Object.keys(profile.context).join(', ')}) were not applied: an existing browser's default context takes none`);
   await context.addCookies(profile.storageState.cookies as Parameters<typeof context.addCookies>[0]);
+  await followWorld(context, follow);
   const page = await context.newPage();
   await page.goto(url ?? 'about:blank');
   await browser.close();

package/src/world.ts

@@ -9,7 +9,7 @@ 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, seedServedWorld, seedWorld, shellWorld,
-  materializeBrowserFiles, statusWorld, writeGeneratedSeed, statusWorldChangeset, upWorld, verifyWorldChangeset, worldLedgers, worldOrigin,
+  findWorldMark, machineDoor, materializeBrowserFiles, playWorld, settleLocalWorldTime, statusWorld, writeGeneratedSeed, statusWorldChangeset, upWorld, verifyWorldChangeset, worldLedgers, worldOrigin,
   bindLegacyCredentials, deployWorld, loadWorldConfig, writeWorldConfig, readServeRecord, refreshTwin, serveWorld, serveWorldView, findInstalledPackage, type ServedWorld, type ViewConsole, type WorldView, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom, rootCredentialInput, withoutVaultSignIn,
   type DeployTwinOutcome, type MaterializedRoot,
   type ChangesetLocation, type InitOptions, type InitResult, type WorldInstance, materializeRoots, instanceDir, worldChangesetRules } from '@volter/world-runtime';
@@ -17,19 +17,13 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node
 import { dirname, join, resolve } from 'node:path';
 import { requireToken, storeToken } from './credentials.ts';
 import { currentBranch, findWorldRoot, mainBranch, requireWorldRoot, setCurrentBranch, worldConfigPath, worldEnvPath, worldSeedPath } from './locate.ts';
-import { destinationOf, parentEntries, rebaseBranch, type Receipt, type RootConfig } from '@volter/world-core/runtime';
+import { destinationOf, durationMs, parentEntries, rebaseBranch, type Receipt, type RootConfig } from '@volter/world-core/runtime';
 
 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. */
-/** `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) {}
@@ -248,6 +242,8 @@ export class World {
   hasSeed(): boolean { return existsSync(worldSeedPath(this.root)); }
   /** Set up a served World this one is linked to from this world's seed: run there through its own twins, then marked. */
   seedServed(base: string, token: string): ReturnType<typeof seedServedWorld> { return seedServedWorld(base, token, { root: this.root, config: this.configRef(), cwd: this.root }); }
+  /** A run of a scenario (ADR 0036): back to the seed, its timeline played at World times, its properties checked. */
+  play(scenario: string): ReturnType<typeof playWorld> { return playWorld(this.name, { root: this.root, scenario }); }
   /** 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 }); }
 
@@ -257,7 +253,14 @@ export class World {
    * 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> {
+  async branch(name: string, opts: { at?: { instant?: string; positions?: Record<string, number>; views?: Record<string, string>; mark?: string } } = {}): Promise<World> {
+    // at a mark: from the branch it was taken on, at each twin's view and position there, with its clock (and the app's
+    // disk through the machine's fault door, where the mark took it)
+    const mark = opts.at?.mark !== undefined ? findWorldMark(opts.at.mark, this.root) : undefined;
+    const door = mark?.disk ? machineDoor() : null;
+    if (mark?.disk && !door) throw new Error(`mark "${mark.id}" holds the app's disk, and this host gives no fault door to restore it through (VOLTER_WORLD_MACHINE_DOOR)`);
+    const base = mark?.world ?? this.name;
+    const at = mark ? { positions: Object.fromEntries(mark.ledgers.flatMap((l) => (l.position !== undefined ? [[l.stateService, l.position]] : []))), views: Object.fromEntries(mark.ledgers.flatMap((l) => (l.view !== undefined ? [[l.stateService, l.view]] : []))) } : opts.at;
     if (listWorlds(this.root).some((w) => w.name === name)) throw new Error(`A branch "${name}" already exists — \`volter world checkout ${name}\` switches to it`);
     this.refuseWhileServed('branch');
     // this branch stops first (a managed database is copied from a stopped World, and the two would share its port),
@@ -265,7 +268,7 @@ export class World {
     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 } : {}) });
+      await branchWorld(base, name, { root: this.root, envFile: worldEnvPath(this.root), ...(at ? { at } : {}) });
     } catch (error) {
       if (wasRunning) await checkoutWorld(this.name, { root: this.root });
       throw error;
@@ -273,7 +276,12 @@ export class World {
     setCurrentBranch(this.root, name);
     const selected = statusWorld(name, this.root);
     materializeBrowserFiles(selected.dirs.data, this.root, name, selected.config);
-    return new World(name, this.root);
+    const made = new World(name, this.root);
+    if (mark) {
+      if (mark.clock) await made.setClock(mark.clock); else if (mark.clock === null) await made.clearClock();
+      if (door) await door.restorePosition(mark.id);
+    }
+    return made;
   }
   /** Switch to a branch: its twins come back with their state; this branch's stop. */
   async checkout(name: string): Promise<World> {
@@ -315,36 +323,41 @@ export class World {
     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, and the World's application, stamps from it until it moves. */
-  setClock(iso: string): string {
+  /** Set the world's clock to an instant; every twin, and the World's application, stamps from it until it moves. The
+   *  clock is written at once; the answer comes once every twin has done what the move made due (ADR 0036 §4). */
+  setClock(iso: string): Promise<string> {
     const parsed = Date.parse(iso);
     if (Number.isNaN(parsed)) throw new Error(`${JSON.stringify(iso)} is not an ISO-8601 instant`);
     this.writeClock({ kind: 'frozen', at: parsed });
-    return new Date(parsed).toISOString();
+    return this.settled(new Date(parsed).toISOString());
   }
-  /** Move a set clock forward, frozen or running: `30d`, `12h`, `5m`, `90s`. */
-  advanceClock(by: string): string {
+  /** Move a set clock forward, frozen or running: `30d`, `12h`, `5m`, `90s`. Answers as setClock does. */
+  advanceClock(by: string): Promise<string> {
     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;
+    return this.settled(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 {
+   *  running clock further. Answers as setClock does. */
+  shiftClock(by: string): Promise<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 this.settled(this.clock().at);
   }
-  /** Return the World to the machine's time. */
-  clearClock(): string {
+  /** Return the World to the machine's time. Answers as setClock does: what the move made due is done first. */
+  clearClock(): Promise<string> {
     const file = clockFile(this.root, this.name);
     if (existsSync(file)) rmSync(file);
-    return new Date().toISOString();
+    return this.settled(new Date().toISOString());
+  }
+  private async settled(at: string): Promise<string> {
+    await settleLocalWorldTime(this.name, this.root);
+    return at;
   }
   private writeClock(c: Parameters<typeof clockForm.formatClock>[0]): void {
     const file = clockFile(this.root, this.name);
@@ -509,7 +522,14 @@ export class World {
   }
 
   // ── 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 } : {}) }); }
+  /** A mark: every twin's position and history view, and the World clock, a run's position (ADR 0036 §5); the app's disk
+   *  joins them where the host gives the World its machine's fault door (`VOLTER_WORLD_MACHINE_DOOR`). */
+  async mark(id?: string, now?: Date): Promise<WorldMarker> {
+    const door = machineDoor();
+    const marker = markWorld(this.name, { root: this.root, ...(id ? { id } : {}), ...(now ? { now } : {}), ...(door ? { disk: true } : {}) });
+    if (door) await door.takePosition(marker.id);
+    return marker;
+  }
   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 } : {}) }); }

package/src/handlers-in-repo.test.ts

@@ -1,51 +0,0 @@
-// A world in the app repo carries its handlers as ROOT-RELATIVE paths (docs/concepts/worlds.md
-// #the-config-and-the-running-world): init copies a twin's starter handlers to .volter/handlers/<vendor>.json and
-// names that path relative to the world root, so the committed config reads the same on every
-// machine; `up` resolves it against the root on both the spawn path (--scenario) and the colocated
-// host (scenarioPath). Proven against the real anthropic twin, its files linked from the pack repository: its starter
-// handlers are the scripted turns of its own life (journeys/scenario.json).
-import { afterAll, describe, expect, test } from 'bun:test';
-import { copyFileSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { installedPackageDir } from '@volter/world-core/runtime-state';
-import { World } from './index.ts';
-
-function app(): string {
-  const parent = mkdtempSync(join(tmpdir(), 'handlers-in-repo-'));
-  const dir = join(parent, 'agent');
-  mkdirSync(dir);
-  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'agent', dependencies: { '@anthropic-ai/sdk': '^0.30' } }));
-  writeFileSync(join(dir, '.env.example'), 'ANTHROPIC_API_KEY=\n');
-  const installed = join(parent, 'node_modules', '@volter', 'twin-anthropic');
-  mkdirSync(installed, { recursive: true });
-  // the published pack, this package's dev dependency (ADR 0034, decision 6)
-  const pack = installedPackageDir(import.meta.dir, '@volter/twin-anthropic')!;
-  for (const entry of readdirSync(pack)) {
-    if (entry === 'package.json') copyFileSync(join(pack, entry), join(installed, entry));
-    else symlinkSync(join(pack, entry), join(installed, entry));
-  }
-  return dir;
-}
-
-const root = app();
-const world = World.init(root).world;
-afterAll(async () => { await world.down().catch(() => undefined); });
-
-describe('handlers in the app repo', () => {
-  test('init copies the starter handlers and names them relative to the root', () => {
-    expect(readFileSync(join(root, '.volter', 'handlers', 'anthropic.json'), 'utf8')).toContain('"handlers"');
-    const config = JSON.parse(readFileSync(join(root, '.volter', 'world.json'), 'utf8')) as { schemaVersion: number; services: Array<{ id: string; execution?: { process?: { args?: string[] }; colocate?: { scenarioPath?: string } } }> };
-    expect(config.schemaVersion).toBe(2);
-    const anthropic = config.services.find((s) => s.id === 'anthropic')!;
-    expect(anthropic.execution?.process?.args).toEqual(['--scenario', '.volter/handlers/anthropic.json']);
-    expect(anthropic.execution?.colocate?.scenarioPath).toBe('.volter/handlers/anthropic.json');
-  });
-
-  test('up resolves them against the root, and the twin serves them', async () => {
-    const instance = await world.up({ seed: false });
-    const url = instance.services.anthropic!.url!;
-    const scenario = await fetch(`${url}/twin/scenario`).then((r) => r.json()) as { handlers?: Array<{ id: string }> };
-    expect((scenario.handlers ?? []).map((h) => h.id)).toContain('draft-result');
-  });
-});