@volter/world-runtime 3.0.38 → 3.0.39

package/src/host.ts

@@ -1,3 +1,4 @@
+import { errorMessage } from './error-message.ts';
 import { getPack, registerPack, type TwinPack } from '@volter/world-core/runtime';
 // Co-located twin host — run many twins in ONE process instead of one OS process
 // per twin. The twin core is a pure, transport-agnostic handler (see a pack's
@@ -105,8 +106,8 @@ export async function startColocatedHost(
     // the shared process. (A thrown *request* handler is already contained by Bun.serve → 500.)
     // We log and attribute rather than exit — state stays consistent because every kernel write
     // is atomic (temp→rename) and root-keyed, so a swallowed error can't corrupt a sibling.
-    const onRejection = (reason: unknown) => onEvent({ twin: '(host)', kind: 'unhandledRejection', detail: String(reason) });
-    const onUncaught = (err: unknown) => onEvent({ twin: '(host)', kind: 'uncaughtException', detail: String(err) });
+    const onRejection = (reason: unknown) => onEvent({ twin: '(host)', kind: 'unhandledRejection', detail: errorMessage(reason) });
+    const onUncaught = (err: unknown) => onEvent({ twin: '(host)', kind: 'uncaughtException', detail: errorMessage(err) });
     process.on('unhandledRejection', onRejection);
     process.on('uncaughtException', onUncaught);
 
@@ -150,7 +151,7 @@ export async function startColocatedHost(
       stop: async () => {
         // Every stop runs, even when a sibling hangs or throws. Host shutdown
         // still resolves within its budget so the owning runtime can retire it.
-        for (const error of await stop()) onEvent({ twin: '(host)', kind: 'stop-failed', detail: String(error) });
+        for (const error of await stop()) onEvent({ twin: '(host)', kind: 'stop-failed', detail: errorMessage(error) });
       },
     };
   }
@@ -178,7 +179,7 @@ export async function startColocatedHost(
         }
       });
       worker.on('error', (err) => {
-        onEvent({ twin: spec.id, kind: 'error', detail: String(err) });
+        onEvent({ twin: spec.id, kind: 'error', detail: errorMessage(err) });
         if (!ready) rejectReady(err);
       });
       worker.on('exit', (code) => {

package/src/index.ts

@@ -177,5 +177,6 @@ export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor, type
 export { assertWorldStateRemovable } from './ancestry.ts';
 
 export { withoutVaultSignIn } from './runtime.ts';
+export { errorMessage } from './error-message.ts';
 
 export { materializeBrowserFiles, browsersDir, worldBrowser, worldBrowsers, putWorldBrowser, deleteWorldBrowser, inheritWorldBrowsers, type WorldBrowser } from './browsers.ts';

package/src/infra-cli.ts

@@ -2,9 +2,13 @@
 // `volter-world-infra up|status|down`: the World-managed infrastructure's declared lifecycle commands (infra.ts), as
 // a process. World configs invoke this declared service; application agents never operate or diagnose its backing.
 import { runInfrastructure } from './infra.ts';
+import { errorMessage } from './error-message.ts';
 
 const code = await runInfrastructure(process.argv[2] ?? '', process.env, {
   out: (text) => { process.stdout.write(text); },
   err: (text) => { process.stderr.write(text); },
+}).catch(error => {
+  process.stderr.write(`managed infrastructure ${process.argv[2] ?? ''} failed: ${errorMessage(error)}\n`);
+  return 1;
 });
 process.exit(code);

package/src/infra.ts

@@ -9,9 +9,11 @@
 // the moment `volter-world-infra up` returned, and the World's readiness probe never saw it.
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { signalChild } from './process-signal.mjs';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { infraConnections, parseInfraDefinition } from './pglite-backing.ts';
+import { errorMessage } from './error-message.ts';
 
 export interface InfrastructureIo { out: (text: string) => void; err: (text: string) => void }
 
@@ -24,10 +26,14 @@ function runCommand(command: string, args: string[], options: { env: NodeJS.Proc
   return new Promise((resolveRan) => {
     let stdout = ''; let stderr = ''; let settled = false;
     let grace: ReturnType<typeof setTimeout> | undefined;
-    const child = spawn(command, args, { windowsHide: true, env: options.env, stdio: ['ignore', 'pipe', 'pipe'], ...(options.signal ? { signal: options.signal } : {}) });
+    const child = spawn(command, args, { windowsHide: true, env: options.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    const abort = () => {
+      try { if (child.pid) signalChild(child, 'SIGTERM'); }
+      catch (error) { settle({ status: null, stdout, stderr, error: error as Error }); }
+    };
     const settle = (ran: Ran) => {
       if (settled) return;
-      settled = true; clearTimeout(timer); if (grace) clearTimeout(grace);
+      settled = true; options.signal?.removeEventListener('abort', abort); clearTimeout(timer); if (grace) clearTimeout(grace);
       // a grandchild that still holds the pipes does not hold this answer
       child.stdout?.destroy(); child.stderr?.destroy();
       resolveRan(ran);
@@ -35,7 +41,8 @@ function runCommand(command: string, args: string[], options: { env: NodeJS.Proc
     // the timeout is a hard limit and answers as spawnSync's did: the command is killed and the result carries an
     // ETIMEDOUT error (a hung `docker info`, a daemon that never answers, is then no container runtime, as before)
     const timer = setTimeout(() => {
-      child.kill('SIGTERM');
+      try { if (child.pid) signalChild(child, 'SIGTERM'); }
+      catch (error) { settle({ status: null, stdout, stderr, error: error as Error }); return; }
       settle({ status: null, stdout, stderr, error: Object.assign(new Error(`spawn ${command} ETIMEDOUT`), { code: 'ETIMEDOUT' }) });
     }, options.timeout);
     child.stdout?.on('data', (chunk: Buffer) => { stdout += chunk.toString('utf8'); });
@@ -46,6 +53,8 @@ function runCommand(command: string, args: string[], options: { env: NodeJS.Proc
     // answer by at most a moment, never to the timeout
     child.on('exit', (code) => { grace = setTimeout(() => settle({ status: code, stdout, stderr }), 500); });
     child.on('close', (code) => settle({ status: code, stdout, stderr }));
+    options.signal?.addEventListener('abort', abort, { once: true });
+    if (options.signal?.aborted) abort();
   });
 }
 
@@ -83,31 +92,48 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
       : /cannot connect|not running|daemon/iu.test(raw)
         ? 'local execution capacity is unavailable'
         : 'managed infrastructure operation failed';
+  // The existing backend redaction precedes truncation so a cut cannot expose part of a secret.
+  const diagnostic = (raw: string): string => {
+    let detail = raw;
+    const secrets = Object.entries(env).filter(([name, value]) => value && value.length >= 4 && /secret|token|password|credential|api_key|database_url/iu.test(name))
+      .map(([, value]) => value!).sort((a, b) => b.length - a.length);
+    for (const secret of secrets) detail = detail.split(secret).join('[redacted]');
+    detail = detail.replace(/(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/@]+(?::[^\s/@]*)?@/giu, '$1[redacted]@');
+    return detail.split('\n').slice(-40).join('\n').slice(-8192);
+  };
   const fail = (result: Ran): number => {
-    const raw = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
+    const raw = [result.stdout, result.stderr, result.error ? errorMessage(result.error) : undefined].filter(Boolean).join('\n').trim();
+    const detail = diagnostic(raw);
     io.err(`managed infrastructure ${phase} failed: ${classify(raw)}\n`);
+    if (detail) io.err(`backend diagnostic:\n${detail}\n`);
     return result.status && result.status > 0 ? result.status : 1;
   };
 
   // ---- backing selection ------------------------------------------------------
   // The declared service contract (up/status/down) is the boundary; WHICH
   // runtime answers it is private and chosen here, per machine, at each phase:
-  //   1. VOLTER_WORLD_INFRA_BACKING=docker|pglite — explicit, for tests/operators;
+  //   1. VOLTER_WORLD_INFRA_BACKING=docker|pglite|native — explicit, for tests/operators;
   //   2. a working container runtime — the compose path, byte-identical to before;
   //   3. no container runtime + a definition of postgres and/or mongodb services —
   //      the containerless backing (pglite-backing.ts: PGlite for postgres, the
-  //      MongoDB twin for mongodb), announced loudly;
+  //      MongoDB's own server for mongodb), announced loudly;
   //   4. otherwise the honest refusal naming what this machine cannot serve.
-  async function selectBacking(): Promise<'docker' | 'pglite' | number> {
+  async function selectBacking(): Promise<'docker' | 'pglite' | 'native' | number> {
     const forced = env.VOLTER_WORLD_INFRA_BACKING;
-    if (forced === 'docker' || forced === 'pglite') return forced;
+    if (forced === 'docker' || forced === 'pglite' || forced === 'native') return forced;
     if (forced !== undefined) {
-      io.err(`managed infrastructure: VOLTER_WORLD_INFRA_BACKING must be docker or pglite (got ${JSON.stringify(forced)})\n`);
+      io.err(`managed infrastructure: VOLTER_WORLD_INFRA_BACKING must be docker, pglite or native (got ${JSON.stringify(forced)})\n`);
       return 2;
     }
     const probe = await runCommand('docker', ['info', '--format', '{{.ServerVersion}}'], { env, timeout: 10_000, ...(signal ? { signal } : {}) });
     signal?.throwIfAborted();
-    if (probe.status === 0) return 'docker';
+    if (probe.status === 0 && probe.stdout.trim()) return 'docker';
+    if (probe.status === 0) {
+      io.err('managed infrastructure: container runtime probe returned no server version; using containerless backing\n');
+      return 'pglite';
+    }
+    const probeOutput = [probe.stdout, probe.stderr, probe.error ? errorMessage(probe.error) : undefined].filter(Boolean).join('\n').trim();
+    if (probeOutput) io.err(`managed infrastructure: container runtime probe failed\n${probeOutput}\n`);
     // Absence of a container runtime (no binary, no daemon) is a capability
     // difference: swap backings. A PRESENT runtime failing on resources stays
     // on the docker path so the real capacity problem is classified and
@@ -127,7 +153,7 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
       return 1;
     }
     const unsupported = unsupportedKinds(services);
-    if (unsupported.length > 0) {
+    if (phase !== 'down' && unsupported.length > 0) {
       io.err(`managed infrastructure ${phase} failed: local execution capacity is unavailable (no container runtime, and the containerless backing cannot serve: ${unsupported.join(', ')})\n`);
       return 1;
     }
@@ -136,7 +162,7 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
       try {
         await pgliteUp(services, worldData!, launch);
       } catch (error) {
-        io.err(`managed infrastructure up failed: ${String((error as Error).message ?? error)}\n`);
+        io.err(`managed infrastructure up failed: ${diagnostic(errorMessage(error))}\n`);
         return 1;
       }
       io.out('managed infrastructure ready\n');
@@ -166,7 +192,26 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
   const twinCli = redisTwinCli([dirname(fileURLToPath(import.meta.url)), dirname(worldConfig)]);
   const twinned = env.VOLTER_WORLD_INFRA_BACKING === 'docker' || twinCli === undefined ? [] : declared.filter((s) => s.kind === 'redis');
   /** The services the backing below answers for: every one, or those the twin does not serve (by compose service name). */
-  const composed = twinned.length === 0 ? null : declared.filter((s) => s.kind !== 'redis').map((s) => s.kind);
+  const native = declared.filter((s) => s.kind === 'mongodb');
+  const composed = twinned.length === 0 && native.length === 0 ? null : declared.filter((s) => !twinned.includes(s) && !native.includes(s)).map((s) => s.kind);
+  // A database's native wire and storage are its vendor server's. MongoDB never needs a Docker probe or container.
+  if (native.length > 0) {
+    const { pgliteUp, pgliteStatus, pgliteDown } = await import('./pglite-backing.ts');
+    try {
+      if (phase === 'up') {
+        io.out('managed infrastructure backing: MongoDB server (containerless)\n');
+        await pgliteUp(native, worldData!, launch);
+      } else if (phase === 'status') {
+        const status = await pgliteStatus(native, worldData!);
+        if (!status.ok) throw new Error(`${status.ready}/${native.length} MongoDB services are ready`);
+      } else {
+        await pgliteDown(native, worldData!);
+      }
+    } catch (error) {
+      io.err(`managed infrastructure ${phase} failed: ${diagnostic(errorMessage(error))}\n`);
+      return 1;
+    }
+  }
   if (twinned.length > 0) {
     const { redisTwinDown, redisTwinStatus, redisTwinUp } = await import('./redis-backing.ts');
     const cli = twinCli!;
@@ -175,7 +220,7 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
       try {
         await redisTwinUp(twinned, worldData!, cli, launch);
       } catch (error) {
-        io.err(`managed infrastructure up failed: ${String((error as Error).message ?? error)}\n`);
+        io.err(`managed infrastructure up failed: ${diagnostic(errorMessage(error))}\n`);
         return 1;
       }
     } else if (phase === 'status') {
@@ -187,17 +232,53 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
     } else {
       await redisTwinDown(twinned, worldData!);
     }
-    if (composed!.length === 0) {
-      if (phase === 'up') io.out('managed infrastructure ready\n');
-      else if (phase === 'status') io.out(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env) })}\n`);
-      else io.out('managed infrastructure stopped\n');
-      return 0;
-    }
+  }
+  if (composed?.length === 0) {
+    if (phase === 'up') io.out('managed infrastructure ready\n');
+    else if (phase === 'status') io.out(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env) })}\n`);
+    else io.out('managed infrastructure stopped\n');
+    return 0;
   }
 
   const backing = await selectBacking();
   if (typeof backing === 'number') return backing;
   if (backing === 'pglite') return runPglite();
+  if (backing === 'native') {
+    const { nativePostgresUp, nativePostgresStatus, nativePostgresDown } = await import('./native-postgres-backing.ts');
+    const postgres = declared.filter(s => s.kind === 'postgres');
+    const others = declared.filter(s => s.kind !== 'postgres' && !twinned.includes(s));
+    const { unsupportedKinds, pgliteUp, pgliteStatus, pgliteDown } = await import('./pglite-backing.ts');
+    if (postgres.length !== 1 || unsupportedKinds(others).length) {
+      io.err('managed infrastructure native backing requires one postgres and only supported containerless services alongside it\n');
+      return 1;
+    }
+    try {
+      if (phase === 'up') {
+        io.out('managed infrastructure backing: native PostgreSQL (multi-session)\n');
+        await nativePostgresUp(postgres, worldData, readFileSync(definition, 'utf8'), launch);
+        try { await pgliteUp(others, worldData, launch); }
+        catch (error) {
+          try { await nativePostgresDown(worldData); }
+          catch (cleanup) { throw new AggregateError([error, cleanup], 'managed infrastructure startup and native cleanup failed'); }
+          throw error;
+        }
+        io.out('managed infrastructure ready\n');
+      } else if (phase === 'status') {
+        const ready = others.length === 0 || (await pgliteStatus(others, worldData)).ok;
+        if (!ready || !await nativePostgresStatus(worldData)) return 1;
+        io.out(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env) })}\n`);
+      } else {
+        await pgliteDown(others, worldData);
+        await nativePostgresDown(worldData);
+        io.out('managed infrastructure stopped\n');
+      }
+      return 0;
+    } catch (error) {
+      io.err(`managed infrastructure ${phase} failed: ${diagnostic(errorMessage(error))}\n`);
+      return 1;
+    }
+  }
+
 
   const only = composed ?? [];
   if (phase === 'up') {
@@ -212,10 +293,10 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
     const expectedNames = expected.stdout.split(/\s+/u).filter(Boolean).filter((n) => composed === null || composed.includes(n)).sort();
     const runningNames = running.stdout.split(/\s+/u).filter(Boolean).filter((n) => composed === null || composed.includes(n)).sort();
     if (expectedNames.length === 0 || expectedNames.join('\0') !== runningNames.join('\0')) {
-      io.err(`managed infrastructure status failed: ${runningNames.length + twinned.length}/${expectedNames.length + twinned.length} declared services are ready\n`);
+      io.err(`managed infrastructure status failed: ${runningNames.length + twinned.length + native.length}/${expectedNames.length + twinned.length + native.length} declared services are ready\n`);
       return 1;
     }
-    io.out(`${JSON.stringify({ ok: true, services: expectedNames.length + twinned.length, connections: infraConnections(declared, env) })}\n`);
+    io.out(`${JSON.stringify({ ok: true, services: expectedNames.length + twinned.length + native.length, connections: infraConnections(declared, env) })}\n`);
   } else {
     const result = await run(['down', '--remove-orphans']);
     if (result.status !== 0) return fail(result);

package/src/init.ts

@@ -55,12 +55,13 @@ import { overlayEndpointEnv, packFacts } from './pack-facts.ts';
 import { VENDOR_SERVER_BACKINGS } from './backings.ts';
 import { APP_URL_ENV, DEFAULT_WORLD_SELECTION, ISSUE_ENV_PREFIX, MINT_ENV, worldConfigDocument, worldSelectionIncludes, type WorldConfig, type WorldSelection, type WorldServiceConfig } from './schema.ts';
 import { loadWorldConfig } from './configs.ts';
+import { ownedPath } from './owned-path.ts';
 
-/** The names a pack's credential door fills with a file it writes (`file:<field>`, the descriptor's): a path, never a value. */
+/** Credential artifacts (files or directories) hold paths, never invented credential values. */
 function fileCredentialNames(): Set<string> {
   const out = new Set<string>();
   try {
-    for (const facts of Object.values(packFacts())) for (const [name, spec] of Object.entries(facts?.credentialDoor?.fill ?? {})) if (String(spec).startsWith('file:')) out.add(name);
+    for (const facts of Object.values(packFacts())) for (const [name, spec] of Object.entries(facts?.credentialDoor?.fill ?? {})) if (/^(file|directory):/.test(String(spec))) out.add(name);
   } catch { /* no artifact: no file doors known */ }
   return out;
 }
@@ -497,8 +498,8 @@ const COMPOSE_INFRA: Record<string, {
     volumePath: '/data',
     healthcheck: () => ['CMD', 'redis-cli', 'ping'],
   },
-  // Without a container runtime the containerless backing serves this kind with the MongoDB twin
-  // (@volter/twin-mongodb), at the same loopback port and URL.
+  // The runtime serves this kind with MongoDB's own mongod on PATH, without a container,
+  // at the same loopback port and URL; command: ["mongod", "--replSet", "world"] enables transactions.
   mongodb: {
     image: 'mongo:7',
     containerPort: 27017,
@@ -726,10 +727,11 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
   // this catalog lacks
   const indexDir = findInstalledPackage(root, CATALOG_INDEX_PACKAGE);
   const indexDefaults = (() => { try { return indexDir === undefined ? {} : catalogDefaults(indexDir); } catch { return {}; } })();
-  // Pack defaults (defaults/handlers.json, defaults/seed.ts): copied VISIBLY into the world
-  // dir — the author's to edit or delete (copy = ownership; never baked into the pack).
+  // A pack's starters, copied VISIBLY into the world dir: the author's to edit or delete (copy = ownership; never
+  // baked into the pack). Its handlers starter is the answering turns its own life scripts (journeys/scenario.json, the
+  // World's handler format, its faults left out); its default data is src/semantics/seed.ts.
   const defaultsCopies: InitPlan['defaultsCopies'] = [];
-  const signals = options.vendors ? null : detectRepoVendors(repo);
+  const signals = options.vendors ? null : detectRepoVendors(repo, existing?.services);
   const detected = options.vendors
     ? new Map<string, string[]>(options.vendors.map((v) => [v, ['--twins']]))
     : new Map([...signals!.detected].filter(([vendor]) => (signals!.uses.get(vendor) ?? []).some((use) => worldSelectionIncludes(selection, vendor, use.usage))));
@@ -752,6 +754,7 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     for (const name of endpointNames(service)) claimedEnv.set(name, service.id);
   }
   for (const vendor of [...detected.keys()].sort()) {
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(vendor)) throw new Error('Invalid service id');
     const detectedVia = [...(detected.get(vendor) ?? [])].sort();
     const backing = catalog.has(vendor) ? undefined : VENDOR_SERVER_BACKINGS[vendor];
     if (backing !== undefined) {
@@ -788,26 +791,29 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
       : `${wiring.note} CONFLICT: ${wiring.injectEnv} is already claimed by the "${conflict}" service, so this twin is emitted `
         + `without it — one world cannot point ${wiring.injectEnv} at two twins. Decide which vendor that var serves, or run them in separate worlds.`;
     const packDir = catalogSource.packDir(vendor)!;
-    const defaultsHandlersPath = join(packDir, 'defaults', 'handlers.json');
-    const handlersTo = existsSync(defaultsHandlersPath) ? resolve(out, 'handlers', `${vendor}.json`) : null;
-    if (handlersTo !== null) defaultsCopies.push({ vendor, kind: 'handlers', from: defaultsHandlersPath, to: handlersTo });
+    // the starter is the life's handlers that answer; its faults (an overload, a dropped turn) are the life's own tests and
+    // would fail a new World's first calls, so they stay behind
+    const starterHandlers = ((): string | null => {
+      try {
+        const doc = JSON.parse(readFileSync(join(packDir, 'journeys', 'scenario.json'), 'utf8')) as { handlers?: Array<Record<string, unknown>> };
+        const answering = (doc.handlers ?? []).filter((h) => h.fault === undefined);
+        return answering.length ? `${JSON.stringify({ ...doc, handlers: answering }, null, 2)}\n` : null;
+      } catch { return null; }
+    })();
+    const handlersTo = starterHandlers !== null ? ownedPath(out, `handlers/${vendor}.json`) : null;
+    if (handlersTo !== null) defaultsCopies.push({ vendor, kind: 'handlers', content: starterHandlers!, to: handlersTo });
     const handlersArg = handlersTo === null ? null : carried(handlersTo);
-    const defaultsSeedPath = join(packDir, 'defaults', 'seed.ts');
-    // a protocol-3 pack's default data (src/semantics/seed.ts: calls to the vendor's own operations, as data) is copied
-    // beside a runner that makes each call against the twin, both the author's from then on
+    // a pack's default data (src/semantics/seed.ts: calls to the vendor's own operations, as data) is copied beside a
+    // runner that makes each call against the twin, both the author's from then on
     const semanticsSeedPath = join(packDir, 'src', 'semantics', 'seed.ts');
-    if (existsSync(defaultsSeedPath)) defaultsCopies.push({ vendor, kind: 'seed', from: defaultsSeedPath, to: resolve(out, 'seeds', 'defaults', `${vendor}.ts`) });
-    else if (existsSync(semanticsSeedPath)) {
-      defaultsCopies.push({ vendor, kind: 'seed-data', from: semanticsSeedPath, to: resolve(out, 'seeds', 'defaults', `${vendor}.data.ts`) });
-      defaultsCopies.push({ vendor, kind: 'seed', content: seedCallsRunner(vendor), to: resolve(out, 'seeds', 'defaults', `${vendor}.ts`) });
+    if (existsSync(semanticsSeedPath)) {
+      defaultsCopies.push({ vendor, kind: 'seed-data', from: semanticsSeedPath, to: ownedPath(out, `seeds/defaults/${vendor}.data.ts`) });
+      defaultsCopies.push({ vendor, kind: 'seed', content: seedCallsRunner(vendor), to: ownedPath(out, `seeds/defaults/${vendor}.ts`) });
     }
     // COLOCATION (runtime contract R2a): a pack whose serve factory is known (derived into the
     // pack-facts artifact) is emitted with `colocate`, so `up` boots it inside the ONE
     // volter-world-host process instead of spawning a process per twin. The spawn `command`
-    // stays alongside as the process-isolation path. A service carrying a --scenario file
-    // keeps the spawn path for now: the colocate factory contract has no scenarioPath yet,
-    // and silently dropping the world's handlers would be a fake success.
-    // A service carrying a handlers file colocates too (R2a): the colocate contract carries
+    // stays alongside as the process-isolation path. A service carrying a handlers file colocates too (R2a): the colocate contract carries
     // `scenarioPath` and the host hands it to the factory — the same file the spawn path passes
     // as --scenario.
     const serveExport = packFacts()[vendor]?.serveExport;
@@ -898,7 +904,7 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     ...services.filter((service) => !existingIds.has(service.id)),
   ].flatMap(endpointNames));
   // Every name a twin of this World issues (its pack's credentialDoor fill), by the twin: the pack names them, so a name
-  // is issued whatever its stem (PlanetScale's DATABASE_URL, Vercel's TEAM_ID_VERCEL, Upstash's KV_REST_API_TOKEN) once
+  // is issued whatever its stem (Vercel's TEAM_ID_VERCEL, Upstash's KV_REST_API_TOKEN) once
   // that vendor's twin is in the World, and never when it is not.
   const issuedBy = new Map<string, string>();
   for (const service of [...(existing?.services ?? []).map(withIssues), ...services.filter((service) => !existingIds.has(service.id))]) {
@@ -1286,6 +1292,8 @@ export function writeWorldInit(plan: InitPlan, options: { force?: boolean } = {}
       + 'Pass --force to regenerate it, or --out <dir> to emit elsewhere.',
     );
   }
+  // Recheck the planned name-derived paths before any output is written.
+  for (const copy of plan.defaultsCopies) ownedPath(plan.out, relative(plan.out, copy.to));
   mkdirSync(plan.out, { recursive: true });
   writeFileSync(plan.configPath, `${JSON.stringify(worldConfigDocument(plan.config), null, 2)}\n`);
   if (plan.inRepo) writeFileSync(join(plan.out, '.gitignore'), STATE_GITIGNORE);
@@ -1325,6 +1333,7 @@ export function seedCallsRunner(vendor: string): string {
   const stem = vendor.toUpperCase().replace(/[^A-Z0-9]/g, '_');
   return `// ${vendor}'s default data, as its twin's pack declares it (./${vendor}.data.ts: calls to the vendor's own
 // operations), made against the twin in order. Ownership transferred on copy: both files are yours — edit or delete.
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { seed as calls } from './${vendor}.data.ts';
 import * as defaults from './${vendor}.data.ts';
 import type { SeedBrowser } from '@volter/world-core/browser';
@@ -1334,6 +1343,29 @@ 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 clock = process.env.TWIN_WORLD_CLOCK_FILE;
+  const found = clock && existsSync(clock) ? readFileSync(clock, 'utf8') : undefined;
+  try {
+    for (const call of calls) {
+      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\`);
+      }
+      const res = await fetch(\`\${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) } : {}),
+      });
+      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;
@@ -1370,6 +1402,7 @@ export async function seed(): Promise<void> {
       headers, ...(body === undefined ? {} : { body }),
     });
     if (!res.ok) throw new Error(\`${vendor} seed: \${call.method} \${call.path}: \${res.status} \${await res.text()}\`);
+>>>>>>> origin/main
   }
 }
 `;

package/src/lifecycle-record.ts

@@ -1,5 +1,5 @@
 // Durable ownership of one World. This inventory does not allocate or reserve capacity.
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
 import { volterHome } from '@volter/world-core/runtime';
 import { hostname } from 'node:os';
@@ -14,10 +14,14 @@ export type WorldLifecycleRecord = {
 };
 
 const directory = () => join(volterHome(), 'world-lifecycles');
-const identity = (root: string, world: string) => createHash('sha256').update(`${resolve(root)}\0${world}`).digest('hex');
+/** One directory is one root however it is spelled: macOS's /tmp is /private/tmp, and a caller's cwd is the real path
+ *  while its argument may be the alias. An identity hashed from the spelling made doctor report a running World's
+ *  ownership missing when the World was started under /tmp and inspected from /private/tmp. */
+const canonical = (root: string): string => { try { return realpathSync(root); } catch { return resolve(root); } };
+const identity = (root: string, world: string) => createHash('sha256').update(`${canonical(root)}\0${world}`).digest('hex');
 const recordPath = (root: string, world: string) => join(directory(), `${identity(root, world)}.json`);
 const legacyPath = (root: string, world: string) => join(volterHome(), 'world-resource-claims', `${identity(root, world)}.json`);
-export const lifecycleLogPath = (root: string, world: string) => join(resolve(root), stateDirName(), 'worlds', '.lifecycle', `${world}.log`);
+export const lifecycleLogPath = (root: string, world: string) => join(canonical(root), stateDirName(), 'worlds', '.lifecycle', `${world}.log`);
 
 function read(path: string): WorldLifecycleRecord {
   const record = JSON.parse(readFileSync(path, 'utf8')) as WorldLifecycleRecord;
@@ -52,7 +56,7 @@ export function beginWorldLifecycle(root: string, world: string, instanceCreated
   checkedOwner(owner);
   assertLifecycleStartable(root, world);
   const record: WorldLifecycleRecord = {
-    version: 1, world, root: resolve(root), identity: identity(root, world), instanceCreatedAt,
+    version: 1, world, root: canonical(root), identity: identity(root, world), instanceCreatedAt,
     owner, ownerUid: process.getuid?.(), ownerPid: process.pid, hostname: hostname(),
     startedAt: new Date().toISOString(), phase: 'starting', pids: [], log: lifecycleLogPath(root, world),
   };
@@ -87,7 +91,7 @@ export function recordWorldLifecycleEvent(root: string, world: string, message:
 }
 
 /** Called only after verified cleanup. Never touches legacy records. */
-export function releaseWorldLifecycle(root: string, world: string): void {
+export function releaseWorldLifecycle(root: string, world: string, receipt = 'teardown verified; ownership released'): void {
   const path = recordPath(root, world);
   if (!existsSync(path)) return;
   withFileLock(`${path}.lock`, () => {
@@ -96,11 +100,22 @@ export function releaseWorldLifecycle(root: string, world: string): void {
     if (record.identity !== identity(root, world)) throw new Error('World lifecycle identity mismatch');
     // The receipt line is evidence, not a precondition: failing to append it must not keep ownership (and so the next
     // `up`) blocked after a verified teardown.
-    try { recordWorldLifecycleEvent(root, world, 'teardown verified; ownership released'); } catch { /* released regardless */ }
+    try { recordWorldLifecycleEvent(root, world, receipt); } catch { /* released regardless */ }
     rmSync(path);
   });
 }
 
+/** Explicit surrender must prove this generation's complete local inventory has exited. */
+export function exitedWorldLifecyclePids(root: string, world: string, createdAt: string): number[] | undefined {
+  try {
+    const record = read(recordPath(root, world));
+    if (record.hostname !== hostname() || record.instanceCreatedAt !== createdAt
+      || (record.ownerUid !== undefined && record.ownerUid !== process.getuid?.())) return undefined;
+    const pids = [...new Set([record.ownerPid, ...record.pids])];
+    return pids.some(processExists) ? undefined : pids;
+  } catch { return undefined; }
+}
+
 /**
  * Releases the record of a World whose instance metadata is gone when nothing it
  * recorded can still run: the record is this host's and this user's, and its owner

package/src/livekit-backing.mjs

@@ -0,0 +1,37 @@
+import { signalChild } from './process-signal.mjs';
+import { errorMessage } from './error-message.mjs';
+import { spawn } from 'node:child_process';
+import { parse } from 'yaml';
+
+if (!process.env.VOLTER_WORLD) throw new Error('LiveKit backing must run as a World service');
+const port = Number(process.env.PORT);
+if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Missing allocated service port');
+const args = process.argv.slice(2);
+let supplied = {};
+for (let index = 0; index < args.length; index++) {
+  if (args[index] !== '--config-body') continue;
+  const value = parse(args[index + 1]);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid LiveKit config body');
+  supplied = { ...supplied, ...value };
+  args.splice(index, 2); index--;
+}
+// LiveKit's embedded TURN denies restricted peer addresses by default. This relay serves only this local SFU.
+// Source: https://github.com/livekit/livekit/blob/v1.13.1/pkg/config/config.go (TURNConfig).
+const config = {
+  ...supplied, port, bind_addresses: ['127.0.0.1'],
+  rtc: { ...supplied.rtc, node_ip: '127.0.0.1', tcp_port: 0 },
+  turn: { ...supplied.turn, enabled: true, domain: '127.0.0.1', udp_port: port, bind_addresses: ['127.0.0.1'],
+    allow_restricted_peer_cidrs: ['127.0.0.0/8'] },
+};
+const child = spawn('livekit-server', ['--config-body', JSON.stringify(config), ...args], {
+  stdio: 'inherit', env: process.env,
+});
+let stopping = false;
+const stop = () => {
+  stopping = true;
+  try { if (child.pid) signalChild(child, 'SIGTERM'); }
+  catch (error) { console.error(errorMessage(error)); process.exitCode = 1; }
+};
+process.once('SIGINT', stop); process.once('SIGTERM', stop);
+child.once('error', error => { console.error(errorMessage(error)); process.exitCode = 1; });
+child.once('exit', (code, signal) => { process.exitCode = stopping ? 0 : code ?? (signal ? 1 : 0); });

package/src/local-branches.ts

@@ -3,6 +3,7 @@
 // parent through its own doors (its history cut at an instant, when one is asked), its clock frozen at
 // that instant so no twin's catch-up walks it forward, and removed when its time runs out. world-host
 // and `volter world view` both make them with this; a hosted World's supervisor makes its own.
+import { errorMessage } from './error-message.ts';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { readBranchMeta, stateDirName, withHistoryLock, withStateRemoval, worldPaths, worldStateRoot, writeBranchMeta } from '@volter/world-core/runtime';
@@ -189,8 +190,10 @@ export class LocalBranches {
       return { name, token: byKey ? await keyOfBranch(mounted, origin, byKey) : mounted.token, readToken: mounted.readToken, expiresAt };
     } catch (error) {
       this.o.worlds.delete(name);
-      try { await mounted?.stop(); } catch { /* reported below */ }
-      withStateRemoval(root, () => rmSync(root, { recursive: true, force: true }));
+      try { await mounted?.stop(); }
+      catch (cleanup) { throw new AggregateError([error, cleanup], 'Branch startup and host cleanup failed; state retained'); }
+      try { withStateRemoval(root, () => rmSync(root, { recursive: true, force: true })); }
+      catch (cleanup) { throw new AggregateError([error, cleanup], 'Branch startup and state cleanup failed'); }
       throw error;
     }
   }
@@ -230,7 +233,7 @@ export class LocalBranches {
       for (const [name, world] of [...this.o.worlds]) {
         const r = this.record(world);
         if (r?.expiresAt && Date.parse(r.expiresAt) <= now && this.o.worlds.has(name)) {
-          try { await this.remove(name); } catch (error) { this.o.announce?.(`branch   ${name}: removal failed: ${error instanceof Error ? error.message : String(error)}`); }
+          try { await this.remove(name); } catch (error) { this.o.announce?.(`branch   ${name}: removal failed: ${errorMessage(error)}`); }
         }
       }
     } finally { this.sweeping = false; }