@volter/world-runtime 3.0.38 → 3.0.39

package/dist/src/infra.js

@@ -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.js";
+import { errorMessage } from "./error-message.js";
 /** A command run to its end without blocking this process: in the World's own `up` the phase shares the event loop
  *  with the boot's signal handling, where the tool's spawnSync blocked only the tool. Ended by `timeout` (SIGTERM,
  *  as spawnSync's timeout) or by the boot's abort. */
@@ -21,11 +23,21 @@ function runCommand(command, args, options) {
         let stderr = '';
         let settled = false;
         let grace;
-        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 });
+            }
+        };
         const settle = (ran) => {
             if (settled)
                 return;
             settled = true;
+            options.signal?.removeEventListener('abort', abort);
             clearTimeout(timer);
             if (grace)
                 clearTimeout(grace);
@@ -37,7 +49,14 @@ function runCommand(command, args, options) {
         // 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 });
+                return;
+            }
             settle({ status: null, stdout, stderr, error: Object.assign(new Error(`spawn ${command} ETIMEDOUT`), { code: 'ETIMEDOUT' }) });
         }, options.timeout);
         child.stdout?.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
@@ -48,6 +67,9 @@ function runCommand(command, args, options) {
         // 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();
     });
 }
 /** One phase of the World-managed infrastructure. `env` is the infrastructure service's environment, which the
@@ -82,32 +104,52 @@ export async function runInfrastructure(phase, env, io, signal) {
             : /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) => {
+        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) => {
-        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() {
         const forced = env.VOLTER_WORLD_INFRA_BACKING;
-        if (forced === 'docker' || forced === 'pglite')
+        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)
+        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 +169,7 @@ export async function runInfrastructure(phase, env, io, signal) {
             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;
         }
@@ -137,7 +179,7 @@ export async function runInfrastructure(phase, env, io, signal) {
                 await pgliteUp(services, worldData, launch);
             }
             catch (error) {
-                io.err(`managed infrastructure up failed: ${String(error.message ?? error)}\n`);
+                io.err(`managed infrastructure up failed: ${diagnostic(errorMessage(error))}\n`);
                 return 1;
             }
             io.out('managed infrastructure ready\n');
@@ -166,7 +208,30 @@ export async function runInfrastructure(phase, env, io, signal) {
     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.js");
+        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.js");
         const cli = twinCli;
@@ -176,7 +241,7 @@ export async function runInfrastructure(phase, env, io, signal) {
                 await redisTwinUp(twinned, worldData, cli, launch);
             }
             catch (error) {
-                io.err(`managed infrastructure up failed: ${String(error.message ?? error)}\n`);
+                io.err(`managed infrastructure up failed: ${diagnostic(errorMessage(error))}\n`);
                 return 1;
             }
         }
@@ -190,21 +255,66 @@ export async function runInfrastructure(phase, env, io, signal) {
         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.js");
+        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.js");
+        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') {
         const result = await run(['up', '-d', '--wait', ...only]);
@@ -222,10 +332,10 @@ export async function runInfrastructure(phase, env, io, signal) {
         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']);

package/dist/src/init.js

@@ -45,13 +45,14 @@ import { overlayEndpointEnv, packFacts } from "./pack-facts.js";
 import { VENDOR_SERVER_BACKINGS } from "./backings.js";
 import { APP_URL_ENV, DEFAULT_WORLD_SELECTION, ISSUE_ENV_PREFIX, MINT_ENV, worldConfigDocument, worldSelectionIncludes } from "./schema.js";
 import { loadWorldConfig } from "./configs.js";
-/** The names a pack's credential door fills with a file it writes (`file:<field>`, the descriptor's): a path, never a value. */
+import { ownedPath } from "./owned-path.js";
+/** Credential artifacts (files or directories) hold paths, never invented credential values. */
 function fileCredentialNames() {
     const out = new Set();
     try {
         for (const facts of Object.values(packFacts()))
             for (const [name, spec] of Object.entries(facts?.credentialDoor?.fill ?? {}))
-                if (String(spec).startsWith('file:'))
+                if (/^(file|directory):/.test(String(spec)))
                     out.add(name);
     }
     catch { /* no artifact: no file doors known */ }
@@ -297,8 +298,8 @@ const COMPOSE_INFRA = {
         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,
@@ -528,10 +529,11 @@ export function planWorldInit(name, repoPath, options = {}) {
     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 = [];
-    const signals = options.vendors ? null : detectRepoVendors(repo);
+    const signals = options.vendors ? null : detectRepoVendors(repo, existing?.services);
     const detected = options.vendors
         ? new Map(options.vendors.map((v) => [v, ['--twins']]))
         : new Map([...signals.detected].filter(([vendor]) => (signals.uses.get(vendor) ?? []).some((use) => worldSelectionIncludes(selection, vendor, use.usage))));
@@ -554,6 +556,8 @@ export function planWorldInit(name, repoPath, options = {}) {
             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) {
@@ -593,28 +597,33 @@ export function planWorldInit(name, repoPath, options = {}) {
             : `${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;
+        // 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 = (() => {
+            try {
+                const doc = JSON.parse(readFileSync(join(packDir, 'journeys', 'scenario.json'), 'utf8'));
+                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', from: defaultsHandlersPath, to: handlersTo });
+            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;
@@ -710,7 +719,7 @@ export function planWorldInit(name, repoPath, options = {}) {
         ...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();
     for (const service of [...(existing?.services ?? []).map(withIssues), ...services.filter((service) => !existingIds.has(service.id))]) {
@@ -1098,6 +1107,9 @@ export function writeWorldInit(plan, options = {}) {
         throw new Error(`volter init: a world already exists at ${plan.configPath}. `
             + '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)
@@ -1138,6 +1150,7 @@ export function seedCallsRunner(vendor) {
     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';
@@ -1147,6 +1160,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;
@@ -1183,6 +1219,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/dist/src/lifecycle-record.d.ts

@@ -22,7 +22,9 @@ export declare function handoffWorldLifecycle(root: string, world: string, pids:
 export declare function retainWorldLifecycleForCleanup(root: string, world: string): void;
 export declare function recordWorldLifecycleEvent(root: string, world: string, message: string): void;
 /** Called only after verified cleanup. Never touches legacy records. */
-export declare function releaseWorldLifecycle(root: string, world: string): void;
+export declare function releaseWorldLifecycle(root: string, world: string, receipt?: string): void;
+/** Explicit surrender must prove this generation's complete local inventory has exited. */
+export declare function exitedWorldLifecyclePids(root: string, world: string, createdAt: string): number[] | 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/dist/src/lifecycle-record.js

@@ -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';
@@ -7,10 +7,19 @@ import { dirname, join, resolve } from 'node:path';
 import { stateDirName, withFileLock } from '@volter/world-core/runtime';
 import { checkedOwner } from "./consumers.js";
 const directory = () => join(volterHome(), 'world-lifecycles');
-const identity = (root, world) => 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) => { try {
+    return realpathSync(root);
+}
+catch {
+    return resolve(root);
+} };
+const identity = (root, world) => createHash('sha256').update(`${canonical(root)}\0${world}`).digest('hex');
 const recordPath = (root, world) => join(directory(), `${identity(root, world)}.json`);
 const legacyPath = (root, world) => join(volterHome(), 'world-resource-claims', `${identity(root, world)}.json`);
-export const lifecycleLogPath = (root, world) => join(resolve(root), stateDirName(), 'worlds', '.lifecycle', `${world}.log`);
+export const lifecycleLogPath = (root, world) => join(canonical(root), stateDirName(), 'worlds', '.lifecycle', `${world}.log`);
 function read(path) {
     const record = JSON.parse(readFileSync(path, 'utf8'));
     if (record?.version !== 1 || typeof record.world !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(record.world)
@@ -47,7 +56,7 @@ export function beginWorldLifecycle(root, world, instanceCreatedAt, owner) {
     checkedOwner(owner);
     assertLifecycleStartable(root, world);
     const record = {
-        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),
     };
@@ -81,7 +90,7 @@ export function recordWorldLifecycleEvent(root, world, message) {
     writeFileSync(path, `${new Date().toISOString()} ${message}\n`, { flag: 'a', mode: 0o600 });
 }
 /** Called only after verified cleanup. Never touches legacy records. */
-export function releaseWorldLifecycle(root, world) {
+export function releaseWorldLifecycle(root, world, receipt = 'teardown verified; ownership released') {
     const path = recordPath(root, world);
     if (!existsSync(path))
         return;
@@ -94,12 +103,26 @@ export function releaseWorldLifecycle(root, world) {
         // 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');
+            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, world, createdAt) {
+    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/dist/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/dist/src/local-branches.js

@@ -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.js";
 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';
@@ -202,8 +203,15 @@ export class LocalBranches {
             try {
                 await mounted?.stop();
             }
-            catch { /* reported below */ }
-            withStateRemoval(root, () => rmSync(root, { recursive: true, force: true }));
+            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;
         }
     }
@@ -250,7 +258,7 @@ export class LocalBranches {
                         await this.remove(name);
                     }
                     catch (error) {
-                        this.o.announce?.(`branch   ${name}: removal failed: ${error instanceof Error ? error.message : String(error)}`);
+                        this.o.announce?.(`branch   ${name}: removal failed: ${errorMessage(error)}`);
                     }
                 }
             }

package/dist/src/mongodb-backing.d.ts

@@ -0,0 +1,7 @@
+import type { HostLaunch, InfraService } from './pglite-backing.js';
+/** PATH is the binary contract, as for the native PostgreSQL example and LiveKit. No acquisition at boot. */
+export declare function mongodbArgv(service: InfraService, data: string): string[];
+/** MongoDB's structured record comes from this child, not a listener already holding the port. */
+export declare function mongodbListening(log: string, port: number): boolean;
+/** Ping the server; initialize only an explicitly declared one-member set and await its primary. */
+export declare function mongodbReady(service: InfraService, launch: HostLaunch, deadline: number, initialize?: boolean): Promise<void>;