@volter/world-runtime 2.0.25 → 2.0.26

package/dist/src/host-cli.js

@@ -13,6 +13,7 @@ import { keepProcessAlive } from '@volter/world-core/lifecycle';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { startColocatedHost } from "./host.js";
+import { publishHostReady } from "./host-ready.js";
 const argv = process.argv.slice(2);
 const opt = (name, fb = '') => { const i = argv.indexOf(name); return i >= 0 && argv[i + 1] ? argv[i + 1] : fb; };
 const isolation = opt('--isolation', 'shared');
@@ -85,10 +86,20 @@ const host = await startColocatedHost(specs, {
             recordGaveUp(e.twin, e.exits ?? 0, e.detail ?? '');
     },
 });
-for (const [id, port] of Object.entries(host.ports))
-    process.stdout.write(`ready id=${id} port=${port}\n`);
-process.stdout.write(`host ready (${specs.length} twins, isolation=${isolation})\n`);
 const shutdown = async () => { await host.stop(); process.exit(0); };
 process.on('SIGTERM', shutdown);
 process.on('SIGINT', shutdown);
+const readyFile = opt('--ready-file');
+if (readyFile) {
+    try {
+        publishHostReady(readyFile, process.env.VOLTER_WORLD_BOOT_ID ?? '', host.ports);
+    }
+    catch (error) {
+        await host.stop();
+        throw error;
+    }
+}
+for (const [id, port] of Object.entries(host.ports))
+    process.stdout.write(`ready id=${id} port=${port}\n`);
+process.stdout.write(`host ready (${specs.length} twins, isolation=${isolation})\n`);
 await keepProcessAlive();

package/dist/src/host-ready.d.ts

@@ -0,0 +1,4 @@
+/** Only the host, after all starts have returned and ports were checked, publishes this receipt. */
+export declare function publishHostReady(path: string, boot: string, ports: Record<string, number>): void;
+/** Receipt admission is finite and cancellation-aware; stale or malformed state is never readiness. */
+export declare function waitForHostReady(path: string, boot: string, ports: ReadonlyMap<string, number>, timeoutMs: number, abort: AbortSignal): Promise<void>;

package/dist/src/host-ready.js

@@ -0,0 +1,48 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** Only the host, after all starts have returned and ports were checked, publishes this receipt. */
+export function publishHostReady(path, boot, ports) {
+    if (!boot)
+        throw new Error('A co-located host readiness receipt requires its World boot identity.');
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify({ version: 1, boot, ports })}\n`, { mode: 0o600 });
+    renameSync(temporary, path);
+}
+/** Receipt admission is finite and cancellation-aware; stale or malformed state is never readiness. */
+export async function waitForHostReady(path, boot, ports, timeoutMs, abort) {
+    const started = Date.now();
+    for (;;) {
+        abort.throwIfAborted();
+        let bytes;
+        try {
+            bytes = readFileSync(path);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (bytes) {
+            if (bytes.byteLength > 256 * 1024)
+                throw new Error('The co-located host readiness receipt exceeds its bounds.');
+            const value = JSON.parse(bytes.toString('utf8'));
+            if (!value || value.version !== 1 || value.boot !== boot || !value.ports || typeof value.ports !== 'object' || Array.isArray(value.ports)) {
+                throw new Error('The co-located host readiness receipt does not belong to this boot.');
+            }
+            const answered = value.ports;
+            if (Object.keys(answered).length !== ports.size || [...ports].some(([id, port]) => !Object.hasOwn(answered, id) || answered[id] !== port)) {
+                throw new Error('The co-located host readiness receipt does not cover its declared ports.');
+            }
+            return;
+        }
+        if (Date.now() - started >= timeoutMs)
+            throw new Error(`The co-located host did not complete every declared start within ${timeoutMs} ms.`);
+        await new Promise((resolve, reject) => {
+            const cancel = () => { clearTimeout(timer); abort.removeEventListener('abort', cancel); reject(abort.reason); };
+            const timer = setTimeout(() => { abort.removeEventListener('abort', cancel); resolve(); }, Math.min(25, Math.max(1, timeoutMs - (Date.now() - started))));
+            abort.addEventListener('abort', cancel, { once: true });
+            if (abort.aborted)
+                cancel();
+        });
+    }
+}

package/dist/src/runtime.js

@@ -1,6 +1,7 @@
 import { claimEnvOutput, publishEnvOutput } from "./env-output.js";
 import { offSignal } from "./signals.js";
 import { parallelStartup } from "./startup.js";
+import { waitForHostReady } from "./host-ready.js";
 import { assertWorldStateRemovable, removeWorldState } from "./ancestry.js";
 import { packCli, packEntry } from "./catalog.js";
 import { spawn, spawnSync } from 'node:child_process';
@@ -111,16 +112,25 @@ async function untilReadyOrEnded(wait, ended, boot, what, log) {
  *  port alone (`early`), a twin's answer with this boot's id ends it early: a server of this boot holds the port, and
  *  every port this boot assigns is kept apart from its siblings', so short of the kernel handing the just-probed port
  *  to another of this boot's port-0 listeners, that server is the service just started. A settle standing for several
- *  ports (a co-located host's)
- *  always runs in full: one port's answer says nothing of the others'. Programs that are not twins are never asked. */
-async function confirmOwnPort(port, boot, ended, twin, what, log, early = false) {
+ *  ports runs in full unless an all-started receipt permits each port's own early identity confirmation.
+ *  Programs that are not twins are never asked. A shared settle keeps legacy co-located ports within one guard. */
+async function confirmOwnPort(port, boot, ended, twin, what, log, early = false, sharedSettle) {
     // A twin is asked at once, raced with the settle: a server slow to answer costs no more than the settle did.
     boot.signal.throwIfAborted();
     const answer = twin ? worldBootOf(port, boot.signal) : Promise.resolve(null);
     const own = early && twin ? answer.then((a) => (a && a.boot === boot.bootId ? 'own' : new Promise(() => undefined))) : new Promise(() => undefined);
     // `ended` absent: the process was already settled (a co-located host settles once for all its twins).
     if (ended) {
-        const settled = await Promise.race([own, ended.then(() => 'ended'), new Promise((resolveAlive) => setTimeout(() => resolveAlive('alive'), 300))]);
+        let timer;
+        let settled;
+        try {
+            const settle = sharedSettle ?? new Promise((resolveAlive) => { timer = setTimeout(() => resolveAlive('alive'), 300); });
+            settled = await Promise.race([own, ended.then(() => 'ended'), settle]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
         boot.signal.throwIfAborted();
         if (settled === 'own')
             return;
@@ -1308,7 +1318,8 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
     if (colocated.length === 0)
         return [];
     const hostCli = siblingScript(import.meta.url, 'host-cli');
-    const args = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker'];
+    const readyFile = join(paths.instance, `host-ready-${boot.bootId}.json`);
+    const args = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker', '--ready-file', readyFile];
     const allocated = [];
     for (const service of colocated) {
         const port = service.port === undefined || service.port === 'auto' ? await allocatePort(allocatedPorts) : service.port;
@@ -1344,6 +1355,16 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
         exitState.value = { code, signal };
     });
     const command = [process.execPath, ...args];
+    const hostTimeoutMs = allocated.reduce((timeout, { service }) => Math.max(timeout, typeof service.ready === 'object' ? service.ready.timeoutMs ?? 15_000 : 15_000), 15_000);
+    await untilReadyOrEnded((abort) => waitForHostReady(readyFile, boot.bootId, new Map(allocated.map(({ service, port }) => [service.id, port])), hostTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
+        if (undeadPids([child.pid]).length)
+            recordWorldStop([log], 'world.service.stop', 'up (host startup incomplete)', 'SIGTERM');
+        try {
+            process.kill(-child.pid, 'SIGTERM');
+        }
+        catch { /* best effort cleanup */ }
+        throw new Error(`Co-located host failed to complete startup (isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
+    });
     await parallelStartup(allocated, async ({ service, port }) => {
         const bindTimeoutMs = typeof service.ready === 'object' && service.ready.timeoutMs !== undefined ? Math.max(service.ready.timeoutMs, 15_000) : 15_000;
         await untilReadyOrEnded((abort) => waitForTcp(port, bindTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
@@ -1356,18 +1377,27 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
             throw new Error(`Co-located twin "${service.id}" failed to start (host isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
         });
     });
-    await parallelStartup(allocated, async ({ service, port }, index) => {
-        // A host holding one twin settles for that one port, so its twin may be confirmed early like a lone service's.
-        await confirmOwnPort(port, boot, index === 0 ? ended : undefined, true, `Co-located twin "${service.id}"`, log, allocated.length === 1).catch((error) => {
-            if (undeadPids([child.pid]).length)
-                recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
-            try {
-                process.kill(-child.pid, 'SIGTERM');
-            }
-            catch { /* best effort cleanup */ }
-            throw error;
+    let hostSettleTimer;
+    const hostSettle = new Promise((resolveAlive) => { hostSettleTimer = setTimeout(() => resolveAlive('alive'), 300); });
+    try {
+        await parallelStartup(allocated, async ({ service, port }) => {
+            // The host has completed every start. Each matching boot answer can now
+            // end its own settle; legacy twins share one full host guard.
+            await confirmOwnPort(port, boot, ended, true, `Co-located twin "${service.id}"`, log, true, hostSettle).catch((error) => {
+                if (undeadPids([child.pid]).length)
+                    recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
+                try {
+                    process.kill(-child.pid, 'SIGTERM');
+                }
+                catch { /* best effort cleanup */ }
+                throw error;
+            });
         });
-    });
+    }
+    finally {
+        if (hostSettleTimer !== undefined)
+            clearTimeout(hostSettleTimer);
+    }
     if (exitState.value !== null) {
         throw new Error(`The co-located host ended during startup even though its ports answer, so other/stale processes probably hold them: the host ${endedAccount(log)}\n`
             + `Stop leftover services (e.g. \`volter-world down\`) and retry.\nLog: ${log}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.25",
+  "version": "2.0.26",
   "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",

package/src/host-cli.ts

@@ -13,6 +13,7 @@ import { keepProcessAlive } from '@volter/world-core/lifecycle';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { startColocatedHost, type ColocatedTwinSpec, type HostIsolation } from './host.ts';
+import { publishHostReady } from './host-ready.ts';
 
 const argv = process.argv.slice(2);
 const opt = (name: string, fb = ''): string => { const i = argv.indexOf(name); return i >= 0 && argv[i + 1] ? argv[i + 1]! : fb; };
@@ -83,10 +84,14 @@ const host = await startColocatedHost(specs, {
     if (e.kind === 'gaveup') recordGaveUp(e.twin, e.exits ?? 0, e.detail ?? '');
   },
 });
-for (const [id, port] of Object.entries(host.ports)) process.stdout.write(`ready id=${id} port=${port}\n`);
-process.stdout.write(`host ready (${specs.length} twins, isolation=${isolation})\n`);
-
 const shutdown = async () => { await host.stop(); process.exit(0); };
 process.on('SIGTERM', shutdown);
 process.on('SIGINT', shutdown);
+const readyFile = opt('--ready-file');
+if (readyFile) {
+  try { publishHostReady(readyFile, process.env.VOLTER_WORLD_BOOT_ID ?? '', host.ports); }
+  catch (error) { await host.stop(); throw error; }
+}
+for (const [id, port] of Object.entries(host.ports)) process.stdout.write(`ready id=${id} port=${port}\n`);
+process.stdout.write(`host ready (${specs.length} twins, isolation=${isolation})\n`);
 await keepProcessAlive();

package/src/host-ready.ts

@@ -0,0 +1,41 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/** Only the host, after all starts have returned and ports were checked, publishes this receipt. */
+export function publishHostReady(path: string, boot: string, ports: Record<string, number>): void {
+  if (!boot) throw new Error('A co-located host readiness receipt requires its World boot identity.');
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify({ version: 1, boot, ports })}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+/** Receipt admission is finite and cancellation-aware; stale or malformed state is never readiness. */
+export async function waitForHostReady(path: string, boot: string, ports: ReadonlyMap<string, number>, timeoutMs: number, abort: AbortSignal): Promise<void> {
+  const started = Date.now();
+  for (;;) {
+    abort.throwIfAborted();
+    let bytes: Buffer | undefined;
+    try { bytes = readFileSync(path); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+    if (bytes) {
+      if (bytes.byteLength > 256 * 1024) throw new Error('The co-located host readiness receipt exceeds its bounds.');
+      const value = JSON.parse(bytes.toString('utf8')) as { version?: unknown; boot?: unknown; ports?: unknown } | null;
+      if (!value || value.version !== 1 || value.boot !== boot || !value.ports || typeof value.ports !== 'object' || Array.isArray(value.ports)) {
+        throw new Error('The co-located host readiness receipt does not belong to this boot.');
+      }
+      const answered = value.ports as Record<string, unknown>;
+      if (Object.keys(answered).length !== ports.size || [...ports].some(([id, port]) => !Object.hasOwn(answered, id) || answered[id] !== port)) {
+        throw new Error('The co-located host readiness receipt does not cover its declared ports.');
+      }
+      return;
+    }
+    if (Date.now() - started >= timeoutMs) throw new Error(`The co-located host did not complete every declared start within ${timeoutMs} ms.`);
+    await new Promise<void>((resolve, reject) => {
+      const cancel = (): void => { clearTimeout(timer); abort.removeEventListener('abort', cancel); reject(abort.reason); };
+      const timer = setTimeout(() => { abort.removeEventListener('abort', cancel); resolve(); }, Math.min(25, Math.max(1, timeoutMs - (Date.now() - started))));
+      abort.addEventListener('abort', cancel, { once: true });
+      if (abort.aborted) cancel();
+    });
+  }
+}

package/src/runtime.ts

@@ -1,6 +1,7 @@
 import { claimEnvOutput, publishEnvOutput } from './env-output.ts';
 import { offSignal } from './signals.ts';
 import { parallelStartup } from './startup.ts';
+import { waitForHostReady } from './host-ready.ts';
 import { assertWorldStateRemovable, removeWorldState } from './ancestry.ts';
 import { packCli, packEntry } from './catalog.ts';
 import { spawn, spawnSync } from 'node:child_process';
@@ -105,16 +106,21 @@ async function untilReadyOrEnded<T>(wait: (abort: AbortSignal) => Promise<T>, en
  *  port alone (`early`), a twin's answer with this boot's id ends it early: a server of this boot holds the port, and
  *  every port this boot assigns is kept apart from its siblings', so short of the kernel handing the just-probed port
  *  to another of this boot's port-0 listeners, that server is the service just started. A settle standing for several
- *  ports (a co-located host's)
- *  always runs in full: one port's answer says nothing of the others'. Programs that are not twins are never asked. */
-async function confirmOwnPort(port: number, boot: BootContext, ended: Promise<void> | undefined, twin: boolean, what: string, log: string, early = false): Promise<void> {
+ *  ports runs in full unless an all-started receipt permits each port's own early identity confirmation.
+ *  Programs that are not twins are never asked. A shared settle keeps legacy co-located ports within one guard. */
+async function confirmOwnPort(port: number, boot: BootContext, ended: Promise<void> | undefined, twin: boolean, what: string, log: string, early = false, sharedSettle?: Promise<'alive'>): Promise<void> {
   // A twin is asked at once, raced with the settle: a server slow to answer costs no more than the settle did.
   boot.signal.throwIfAborted();
   const answer = twin ? worldBootOf(port, boot.signal) : Promise.resolve(null);
   const own = early && twin ? answer.then((a) => (a && a.boot === boot.bootId ? 'own' as const : new Promise<never>(() => undefined))) : new Promise<never>(() => undefined);
   // `ended` absent: the process was already settled (a co-located host settles once for all its twins).
   if (ended) {
-    const settled = await Promise.race([own, ended.then(() => 'ended' as const), new Promise<'alive'>((resolveAlive) => setTimeout(() => resolveAlive('alive'), 300))]);
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let settled: 'own' | 'ended' | 'alive';
+    try {
+      const settle = sharedSettle ?? new Promise<'alive'>((resolveAlive) => { timer = setTimeout(() => resolveAlive('alive'), 300); });
+      settled = await Promise.race([own, ended.then(() => 'ended' as const), settle]);
+    } finally { if (timer !== undefined) clearTimeout(timer); }
     boot.signal.throwIfAborted();
     if (settled === 'own') return;
     if (settled === 'ended') throw new Error(`${what} ended right after its port first answered, so another process probably holds the port: the service ${endedAccount(log)}\nLog: ${log}`);
@@ -1324,7 +1330,8 @@ async function startColocatedServices(
 ): Promise<WorldServiceInstance[]> {
   if (colocated.length === 0) return [];
   const hostCli = siblingScript(import.meta.url, 'host-cli');
-  const args: string[] = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker'];
+  const readyFile = join(paths.instance, `host-ready-${boot.bootId}.json`);
+  const args: string[] = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker', '--ready-file', readyFile];
   const allocated: Array<{ service: WorldServiceConfig; port: number; mounted: MountedPackage }> = [];
   for (const service of colocated) {
     const port = service.port === undefined || service.port === 'auto' ? await allocatePort(allocatedPorts) : service.port;
@@ -1362,6 +1369,12 @@ async function startColocatedServices(
   });
 
   const command = [process.execPath, ...args];
+  const hostTimeoutMs = allocated.reduce((timeout, { service }) => Math.max(timeout, typeof service.ready === 'object' ? service.ready.timeoutMs ?? 15_000 : 15_000), 15_000);
+  await untilReadyOrEnded((abort) => waitForHostReady(readyFile, boot.bootId, new Map(allocated.map(({ service, port }) => [service.id, port])), hostTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
+    if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (host startup incomplete)', 'SIGTERM');
+    try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
+    throw new Error(`Co-located host failed to complete startup (isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
+  });
   await parallelStartup(allocated, async ({ service, port }) => {
     const bindTimeoutMs = typeof service.ready === 'object' && service.ready.timeoutMs !== undefined ? Math.max(service.ready.timeoutMs, 15_000) : 15_000;
     await untilReadyOrEnded((abort) => waitForTcp(port, bindTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
@@ -1370,14 +1383,19 @@ async function startColocatedServices(
       throw new Error(`Co-located twin "${service.id}" failed to start (host isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
     });
   });
-  await parallelStartup(allocated, async ({ service, port }, index) => {
-    // A host holding one twin settles for that one port, so its twin may be confirmed early like a lone service's.
-    await confirmOwnPort(port, boot, index === 0 ? ended : undefined, true, `Co-located twin "${service.id}"`, log, allocated.length === 1).catch((error) => {
-      if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
-      try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
-      throw error;
+  let hostSettleTimer: ReturnType<typeof setTimeout> | undefined;
+  const hostSettle = new Promise<'alive'>((resolveAlive) => { hostSettleTimer = setTimeout(() => resolveAlive('alive'), 300); });
+  try {
+    await parallelStartup(allocated, async ({ service, port }) => {
+      // The host has completed every start. Each matching boot answer can now
+      // end its own settle; legacy twins share one full host guard.
+      await confirmOwnPort(port, boot, ended, true, `Co-located twin "${service.id}"`, log, true, hostSettle).catch((error) => {
+        if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
+        try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
+        throw error;
+      });
     });
-  });
+  } finally { if (hostSettleTimer !== undefined) clearTimeout(hostSettleTimer); }
   if (exitState.value !== null) {
     throw new Error(
       `The co-located host ended during startup even though its ports answer, so other/stale processes probably hold them: the host ${endedAccount(log)}\n`