@volter/world-runtime 3.0.87 → 3.0.89

package/dist/src/cli-commands.js

@@ -4,10 +4,10 @@ import { optionValue, ownerOption } from "./cli-args.js";
 import { printReady } from "./up-cli.js";
 import { spawn, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from "./index.js";
+import { join, resolve } from 'node:path';
+import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, writeWorldClock, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from "./index.js";
 import { formatApplication, formatChangeset, formatRebaseReport, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/world-core/runtime';
 import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from "./serve.js";
 import { clockFile, instanceDir, pruneWorlds, withoutVaultSignIn } from "./runtime.js";
@@ -539,8 +539,7 @@ export async function main() {
         const file = clockFile(rootDir, name);
         const current = existsSync(file) ? clockForm.parseClock(readFileSync(file, 'utf8')) : null;
         const write = (clock) => {
-            mkdirSync(dirname(file), { recursive: true });
-            writeFileSync(file, `${clockForm.formatClock(clock)}\n`);
+            writeWorldClock(name, rootDir, clock);
             // the World's time now, bare, as scripts read it (`show` says which form)
             console.log(new Date(clockForm.clockNowMs(clock, Date.now())).toISOString());
         };

package/dist/src/clock.d.ts

@@ -0,0 +1,3 @@
+import type { WorldClock } from '@volter/world-core/world-clock';
+export declare function writeWorldClock(name: string, root: string, clock: WorldClock): void;
+export declare function setWorldClock(name: string, root: string, at: string): void;

package/dist/src/clock.js

@@ -0,0 +1,18 @@
+// The programmatic counterpart of the operator's clock command. Callers own their World root; only invoked
+// operations read or write it. Formatting belongs to the kernel's shared clock contract.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import { clockFile } from "./runtime.js";
+const clockForm = createRequire(import.meta.url)('@volter/world-core/world-clock');
+export function writeWorldClock(name, root, clock) {
+    const file = clockFile(root, name);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${clockForm.formatClock(clock)}\n`);
+}
+export function setWorldClock(name, root, at) {
+    const parsed = Date.parse(at);
+    if (Number.isNaN(parsed))
+        throw new Error(`clock set: ${JSON.stringify(at)} is not an ISO-8601 instant`);
+    writeWorldClock(name, root, { kind: 'frozen', at: parsed });
+}

package/dist/src/index.d.ts

@@ -22,6 +22,7 @@ export type { CoverageReport, CoverageRow, CoverageStatus, CoverageOptions, Repo
 export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from './init.js';
 export { STATE_GITIGNORE } from './init.js';
 export { clockFile, instanceDir } from './runtime.js';
+export { setWorldClock, writeWorldClock } from './clock.js';
 export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, type Catalog, type CatalogKind, packCli, packEntry } from './catalog.js';
 export { ISSUE_ENV_PREFIX, MINT_ENV } from './schema.js';
 export type { EnvDisposition, InitEnvRow, InitInfraStub, InitOptions, InitPlan, InitResult, InitVendorPlan, InitWiring, } from './init.js';

package/dist/src/index.js

@@ -20,6 +20,7 @@ export { coverWorld, detectRepoVendors, envNameVendor, formatCoverageReport, inj
 export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from "./init.js";
 export { STATE_GITIGNORE } from "./init.js";
 export { clockFile, instanceDir } from "./runtime.js";
+export { setWorldClock, writeWorldClock } from "./clock.js";
 export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, packCli, packEntry } from "./catalog.js";
 export { ISSUE_ENV_PREFIX, MINT_ENV } from "./schema.js";
 export { deriveWorldManifest, findWorldRefFile, isRemoteWorldRef, resolveWorldRef, WORLD_REF_FILE, worldManifest, } from "./attach.js";

package/dist/src/init.js

@@ -1158,66 +1158,58 @@ export async function seed(): Promise<void> {
   if ((process.env.VOLTER_SEED_SKIP ?? '').split(',').includes('${vendor}')) return;
   const base = process.env.${stem}_TWIN_URL;
   if (!base) throw new Error('${stem}_TWIN_URL is not set — bring the world up and run the seed with its env (volter-world attach/run)');
-<<<<<<< HEAD
-  // a call dated before the World's time (\`at\`: state the account made then, through the API as it was) is made with
-  // the World's clock frozen at that instant, and the clock is put back as it was found
+  const clients = new Map<string, SeedBrowser>();
+  const snapshots = new Map<string, Awaited<ReturnType<SeedBrowser['state']>>>();
+  let browserHelper: typeof import('@volter/world-core/browser') | undefined;
+  const browserCalls = ('browserSeed' in defaults ? defaults.browserSeed as typeof calls : undefined) ?? [];
+  const requests = [...calls, ...browserCalls];
   const clock = process.env.TWIN_WORLD_CLOCK_FILE;
-  const found = clock && existsSync(clock) ? readFileSync(clock, 'utf8') : undefined;
+  const dated = requests.some(call => call.at !== undefined);
+  const found = dated && clock && existsSync(clock) ? readFileSync(clock, 'utf8') : undefined;
+  const restoreClock = (): void => {
+    if (!dated || !clock) return;
+    if (found === undefined) rmSync(clock, { force: true }); else writeFileSync(clock, found);
+  };
   try {
-    for (const call of calls) {
+    for (const call of requests) {
       if (call.at !== undefined) {
         if (!clock) throw new Error('${vendor} seed: a dated call needs the World clock (TWIN_WORLD_CLOCK_FILE): run the seed attached to the World');
         writeFileSync(clock, \`\${new Date(call.at).toISOString()}\n\`);
+      } else restoreClock();
+      if (call.browser) {
+        if (!snapshots.has(call.browser)) {
+          const door = process.env.VOLTER_WORLD_BROWSER_DOOR;
+          const token = process.env.VOLTER_WORLD_BROWSER_TOKEN;
+          if (!door || !token) throw new Error('browser defaults run in a World seed with its browsers door and credential');
+          const held = await fetch(\`\${door}/\${encodeURIComponent(call.browser)}\`, { headers: { 'x-volter-token': token } });
+          if (!held.ok && held.status !== 404) throw new Error(\`browser \${call.browser}: \${held.status} \${await held.text()}\`);
+          snapshots.set(call.browser, held.ok ? await held.json() as Awaited<ReturnType<SeedBrowser['state']>> : { storageState: { cookies: [], origins: [] }, context: {} });
+        }
+        browserHelper ??= await import('@volter/world-core/browser').catch(error => {
+          throw new Error('Install @volter/world-core 3.0.37 or later in this project to seed browsers.', { cause: error });
+        });
+        const initial = snapshots.get(call.browser)!;
+        const hostname = new URL(call.path).hostname;
+        if (initial.storageState.cookies.some(cookie => browserHelper!.cookieMatchesHost(cookie, hostname))
+          || initial.storageState.origins.some(origin => new URL(origin.origin).hostname === hostname)) continue;
+      }
+      const headers = { ...(call.body !== undefined ? { 'content-type': 'application/json' } : {}), ...(call.headers ?? {}) };
+      const form = /^application\\/x-www-form-urlencoded\\b/i.test(new Headers(headers).get('content-type') ?? '');
+      const body = call.body === undefined ? undefined : form
+        ? new URLSearchParams(Object.entries(call.body as Record<string, unknown>).map(([key, value]) => [key, String(value)]))
+        : JSON.stringify(call.body);
+      if (call.browser && !clients.has(call.browser)) {
+        clients.set(call.browser, await browserHelper!.browser(call.browser));
       }
-      const res = await fetch(\`\${base.replace(/\\/$/, '')}\${call.path}\`, {
+      const client = call.browser ? clients.get(call.browser)! : null;
+      const res = await (client ? client.fetch : fetch)(client ? call.path : \`\${base.replace(/\\/$/, '')}\${call.path}\`, {
         method: call.method,
-        headers: { ...(call.body !== undefined ? { 'content-type': 'application/json' } : {}), ...(call.headers ?? {}) },
-        ...(call.body !== undefined ? { body: JSON.stringify(call.body) } : {}),
+        headers, ...(body === undefined ? {} : { body }),
       });
       if (!res.ok) throw new Error(\`${vendor} seed: \${call.method} \${call.path}: \${res.status} \${await res.text()}\`);
     }
   } finally {
-    if (clock && calls.some((call) => call.at !== undefined)) {
-      if (found === undefined) rmSync(clock, { force: true }); else writeFileSync(clock, found);
-    }
-=======
-  const clients = new Map<string, SeedBrowser>();
-  const snapshots = new Map<string, Awaited<ReturnType<SeedBrowser['state']>>>();
-  let browserHelper: typeof import('@volter/world-core/browser') | undefined;
-  const browserCalls = ('browserSeed' in defaults ? defaults.browserSeed as typeof calls : undefined) ?? [];
-  for (const call of [...calls, ...browserCalls]) {
-    if (call.browser) {
-      if (!snapshots.has(call.browser)) {
-        const door = process.env.VOLTER_WORLD_BROWSER_DOOR;
-        const token = process.env.VOLTER_WORLD_BROWSER_TOKEN;
-        if (!door || !token) throw new Error('browser defaults run in a World seed with its browsers door and credential');
-        const held = await fetch(\`\${door}/\${encodeURIComponent(call.browser)}\`, { headers: { 'x-volter-token': token } });
-        if (!held.ok && held.status !== 404) throw new Error(\`browser \${call.browser}: \${held.status} \${await held.text()}\`);
-        snapshots.set(call.browser, held.ok ? await held.json() as Awaited<ReturnType<SeedBrowser['state']>> : { storageState: { cookies: [], origins: [] }, context: {} });
-      }
-      browserHelper ??= await import('@volter/world-core/browser').catch(error => {
-        throw new Error('Install @volter/world-core 3.0.37 or later in this project to seed browsers.', { cause: error });
-      });
-      const initial = snapshots.get(call.browser)!;
-      const hostname = new URL(call.path).hostname;
-      if (initial.storageState.cookies.some(cookie => browserHelper!.cookieMatchesHost(cookie, hostname))
-        || initial.storageState.origins.some(origin => new URL(origin.origin).hostname === hostname)) continue;
-    }
-    const headers = { ...(call.body !== undefined ? { 'content-type': 'application/json' } : {}), ...(call.headers ?? {}) };
-    const form = /^application\\/x-www-form-urlencoded\\b/i.test(new Headers(headers).get('content-type') ?? '');
-    const body = call.body === undefined ? undefined : form
-      ? new URLSearchParams(Object.entries(call.body as Record<string, unknown>).map(([key, value]) => [key, String(value)]))
-      : JSON.stringify(call.body);
-    if (call.browser && !clients.has(call.browser)) {
-      clients.set(call.browser, await browserHelper!.browser(call.browser));
-    }
-    const client = call.browser ? clients.get(call.browser)! : null;
-    const res = await (client ? client.fetch : fetch)(client ? call.path : \`\${base.replace(/\\/$/, '')}\${call.path}\`, {
-      method: call.method,
-      headers, ...(body === undefined ? {} : { body }),
-    });
-    if (!res.ok) throw new Error(\`${vendor} seed: \${call.method} \${call.path}: \${res.status} \${await res.text()}\`);
->>>>>>> origin/main
+    restoreClock();
   }
 }
 `;

package/dist/src/runtime.d.ts

@@ -67,7 +67,7 @@ export type WorldUrlInfo = {
  * the instance dir — one layout owner, no duplicated path knowledge. */
 /** THE WORLD CLOCK file (TWIN-PROGRAMMING-MODEL P3): a single frozen ISO instant every twin
  *  stamps from (kernel worldNow()); absent → real wall-clock. Written only by the
- *  `volter-world clock` operator door — time is physics, advanced explicitly, never drifting. */
+ *  `volter-world clock` operator door or its runtime API — time is physics, advanced explicitly, never drifting. */
 export declare function clockFile(root: string, name: string): string;
 export declare function instanceDir(root: string, name: string): string;
 export type SharingClaim = {

package/dist/src/runtime.js

@@ -290,7 +290,7 @@ function assertSafeWorldName(name) {
  * the instance dir — one layout owner, no duplicated path knowledge. */
 /** THE WORLD CLOCK file (TWIN-PROGRAMMING-MODEL P3): a single frozen ISO instant every twin
  *  stamps from (kernel worldNow()); absent → real wall-clock. Written only by the
- *  `volter-world clock` operator door — time is physics, advanced explicitly, never drifting. */
+ *  `volter-world clock` operator door or its runtime API — time is physics, advanced explicitly, never drifting. */
 export function clockFile(root, name) {
     return join(instanceDir(root, name), 'clock');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.87",
+  "version": "3.0.89",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -69,14 +69,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.87",
-    "@volter/world-console": "3.0.82"
+    "@volter/world-core": "3.0.89",
+    "@volter/world-console": "3.0.84"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.87",
+    "@volter/world-core": "3.0.89",
     "mongodb": "~6.20.0",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",

package/src/cli-commands.ts

@@ -7,7 +7,7 @@ import { createRequire } from 'node:module';
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve, resolve as resolvePath } from 'node:path';
-import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, upWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from './index.ts';
+import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, writeWorldClock, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, upWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from './index.ts';
 import { formatApplication, formatChangeset, formatRebaseReport, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/world-core/runtime';
 import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from './serve.ts';
 import type { WorldManifest } from './attach.ts';
@@ -491,8 +491,7 @@ export async function main(): Promise<void> {
     const file = clockFile(rootDir, name);
     const current = existsSync(file) ? clockForm.parseClock(readFileSync(file, 'utf8')) : null;
     const write = (clock: Parameters<typeof clockForm.formatClock>[0]) => {
-      mkdirSync(dirname(file), { recursive: true });
-      writeFileSync(file, `${clockForm.formatClock(clock)}\n`);
+      writeWorldClock(name, rootDir, clock);
       // the World's time now, bare, as scripts read it (`show` says which form)
       console.log(new Date(clockForm.clockNowMs(clock, Date.now())).toISOString());
     };

package/src/clock.ts

@@ -0,0 +1,21 @@
+// The programmatic counterpart of the operator's clock command. Callers own their World root; only invoked
+// operations read or write it. Formatting belongs to the kernel's shared clock contract.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import type { WorldClock } from '@volter/world-core/world-clock';
+import { clockFile } from './runtime.ts';
+
+const clockForm = createRequire(import.meta.url)('@volter/world-core/world-clock') as typeof import('@volter/world-core/world-clock');
+
+export function writeWorldClock(name: string, root: string, clock: WorldClock): void {
+  const file = clockFile(root, name);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${clockForm.formatClock(clock)}\n`);
+}
+
+export function setWorldClock(name: string, root: string, at: string): void {
+  const parsed = Date.parse(at);
+  if (Number.isNaN(parsed)) throw new Error(`clock set: ${JSON.stringify(at)} is not an ISO-8601 instant`);
+  writeWorldClock(name, root, { kind: 'frozen', at: parsed });
+}

package/src/index.ts

@@ -100,6 +100,7 @@ export type { CoverageReport, CoverageRow, CoverageStatus, CoverageOptions, Repo
 export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from './init.ts';
 export { STATE_GITIGNORE } from './init.ts';
 export { clockFile, instanceDir } from './runtime.ts';
+export { setWorldClock, writeWorldClock } from './clock.ts';
 export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, type Catalog, type CatalogKind, packCli, packEntry } from './catalog.ts';
 export { ISSUE_ENV_PREFIX, MINT_ENV } from './schema.ts';
 export type {

package/src/init.ts

@@ -1347,66 +1347,58 @@ export async function seed(): Promise<void> {
   if ((process.env.VOLTER_SEED_SKIP ?? '').split(',').includes('${vendor}')) return;
   const base = process.env.${stem}_TWIN_URL;
   if (!base) throw new Error('${stem}_TWIN_URL is not set — bring the world up and run the seed with its env (volter-world attach/run)');
-<<<<<<< HEAD
-  // a call dated before the World's time (\`at\`: state the account made then, through the API as it was) is made with
-  // the World's clock frozen at that instant, and the clock is put back as it was found
+  const clients = new Map<string, SeedBrowser>();
+  const snapshots = new Map<string, Awaited<ReturnType<SeedBrowser['state']>>>();
+  let browserHelper: typeof import('@volter/world-core/browser') | undefined;
+  const browserCalls = ('browserSeed' in defaults ? defaults.browserSeed as typeof calls : undefined) ?? [];
+  const requests = [...calls, ...browserCalls];
   const clock = process.env.TWIN_WORLD_CLOCK_FILE;
-  const found = clock && existsSync(clock) ? readFileSync(clock, 'utf8') : undefined;
+  const dated = requests.some(call => call.at !== undefined);
+  const found = dated && clock && existsSync(clock) ? readFileSync(clock, 'utf8') : undefined;
+  const restoreClock = (): void => {
+    if (!dated || !clock) return;
+    if (found === undefined) rmSync(clock, { force: true }); else writeFileSync(clock, found);
+  };
   try {
-    for (const call of calls) {
+    for (const call of requests) {
       if (call.at !== undefined) {
         if (!clock) throw new Error('${vendor} seed: a dated call needs the World clock (TWIN_WORLD_CLOCK_FILE): run the seed attached to the World');
         writeFileSync(clock, \`\${new Date(call.at).toISOString()}\n\`);
+      } else restoreClock();
+      if (call.browser) {
+        if (!snapshots.has(call.browser)) {
+          const door = process.env.VOLTER_WORLD_BROWSER_DOOR;
+          const token = process.env.VOLTER_WORLD_BROWSER_TOKEN;
+          if (!door || !token) throw new Error('browser defaults run in a World seed with its browsers door and credential');
+          const held = await fetch(\`\${door}/\${encodeURIComponent(call.browser)}\`, { headers: { 'x-volter-token': token } });
+          if (!held.ok && held.status !== 404) throw new Error(\`browser \${call.browser}: \${held.status} \${await held.text()}\`);
+          snapshots.set(call.browser, held.ok ? await held.json() as Awaited<ReturnType<SeedBrowser['state']>> : { storageState: { cookies: [], origins: [] }, context: {} });
+        }
+        browserHelper ??= await import('@volter/world-core/browser').catch(error => {
+          throw new Error('Install @volter/world-core 3.0.37 or later in this project to seed browsers.', { cause: error });
+        });
+        const initial = snapshots.get(call.browser)!;
+        const hostname = new URL(call.path).hostname;
+        if (initial.storageState.cookies.some(cookie => browserHelper!.cookieMatchesHost(cookie, hostname))
+          || initial.storageState.origins.some(origin => new URL(origin.origin).hostname === hostname)) continue;
+      }
+      const headers = { ...(call.body !== undefined ? { 'content-type': 'application/json' } : {}), ...(call.headers ?? {}) };
+      const form = /^application\\/x-www-form-urlencoded\\b/i.test(new Headers(headers).get('content-type') ?? '');
+      const body = call.body === undefined ? undefined : form
+        ? new URLSearchParams(Object.entries(call.body as Record<string, unknown>).map(([key, value]) => [key, String(value)]))
+        : JSON.stringify(call.body);
+      if (call.browser && !clients.has(call.browser)) {
+        clients.set(call.browser, await browserHelper!.browser(call.browser));
       }
-      const res = await fetch(\`\${base.replace(/\\/$/, '')}\${call.path}\`, {
+      const client = call.browser ? clients.get(call.browser)! : null;
+      const res = await (client ? client.fetch : fetch)(client ? call.path : \`\${base.replace(/\\/$/, '')}\${call.path}\`, {
         method: call.method,
-        headers: { ...(call.body !== undefined ? { 'content-type': 'application/json' } : {}), ...(call.headers ?? {}) },
-        ...(call.body !== undefined ? { body: JSON.stringify(call.body) } : {}),
+        headers, ...(body === undefined ? {} : { body }),
       });
       if (!res.ok) throw new Error(\`${vendor} seed: \${call.method} \${call.path}: \${res.status} \${await res.text()}\`);
     }
   } finally {
-    if (clock && calls.some((call) => call.at !== undefined)) {
-      if (found === undefined) rmSync(clock, { force: true }); else writeFileSync(clock, found);
-    }
-=======
-  const clients = new Map<string, SeedBrowser>();
-  const snapshots = new Map<string, Awaited<ReturnType<SeedBrowser['state']>>>();
-  let browserHelper: typeof import('@volter/world-core/browser') | undefined;
-  const browserCalls = ('browserSeed' in defaults ? defaults.browserSeed as typeof calls : undefined) ?? [];
-  for (const call of [...calls, ...browserCalls]) {
-    if (call.browser) {
-      if (!snapshots.has(call.browser)) {
-        const door = process.env.VOLTER_WORLD_BROWSER_DOOR;
-        const token = process.env.VOLTER_WORLD_BROWSER_TOKEN;
-        if (!door || !token) throw new Error('browser defaults run in a World seed with its browsers door and credential');
-        const held = await fetch(\`\${door}/\${encodeURIComponent(call.browser)}\`, { headers: { 'x-volter-token': token } });
-        if (!held.ok && held.status !== 404) throw new Error(\`browser \${call.browser}: \${held.status} \${await held.text()}\`);
-        snapshots.set(call.browser, held.ok ? await held.json() as Awaited<ReturnType<SeedBrowser['state']>> : { storageState: { cookies: [], origins: [] }, context: {} });
-      }
-      browserHelper ??= await import('@volter/world-core/browser').catch(error => {
-        throw new Error('Install @volter/world-core 3.0.37 or later in this project to seed browsers.', { cause: error });
-      });
-      const initial = snapshots.get(call.browser)!;
-      const hostname = new URL(call.path).hostname;
-      if (initial.storageState.cookies.some(cookie => browserHelper!.cookieMatchesHost(cookie, hostname))
-        || initial.storageState.origins.some(origin => new URL(origin.origin).hostname === hostname)) continue;
-    }
-    const headers = { ...(call.body !== undefined ? { 'content-type': 'application/json' } : {}), ...(call.headers ?? {}) };
-    const form = /^application\\/x-www-form-urlencoded\\b/i.test(new Headers(headers).get('content-type') ?? '');
-    const body = call.body === undefined ? undefined : form
-      ? new URLSearchParams(Object.entries(call.body as Record<string, unknown>).map(([key, value]) => [key, String(value)]))
-      : JSON.stringify(call.body);
-    if (call.browser && !clients.has(call.browser)) {
-      clients.set(call.browser, await browserHelper!.browser(call.browser));
-    }
-    const client = call.browser ? clients.get(call.browser)! : null;
-    const res = await (client ? client.fetch : fetch)(client ? call.path : \`\${base.replace(/\\/$/, '')}\${call.path}\`, {
-      method: call.method,
-      headers, ...(body === undefined ? {} : { body }),
-    });
-    if (!res.ok) throw new Error(\`${vendor} seed: \${call.method} \${call.path}: \${res.status} \${await res.text()}\`);
->>>>>>> origin/main
+    restoreClock();
   }
 }
 `;

package/src/runtime.ts

@@ -315,7 +315,7 @@ function assertSafeWorldName(name: string): void {
  * the instance dir — one layout owner, no duplicated path knowledge. */
 /** THE WORLD CLOCK file (TWIN-PROGRAMMING-MODEL P3): a single frozen ISO instant every twin
  *  stamps from (kernel worldNow()); absent → real wall-clock. Written only by the
- *  `volter-world clock` operator door — time is physics, advanced explicitly, never drifting. */
+ *  `volter-world clock` operator door or its runtime API — time is physics, advanced explicitly, never drifting. */
 export function clockFile(root: string, name: string): string {
   return join(instanceDir(root, name), 'clock');
 }