@volter/world-runtime 2.0.24 → 2.0.25

package/dist/src/host.js

@@ -23,6 +23,7 @@ import { Worker } from 'node:worker_threads';
 import { siblingScript } from "./sibling.js";
 import { importModule } from "./import-module.js";
 import { pathToFileURL } from 'node:url';
+import { parallelStartup } from "./startup.js";
 async function loadFactory(spec) {
     const mod = await importModule(spec.module);
     const factory = mod[spec.export];
@@ -60,26 +61,50 @@ export async function startColocatedHost(specs, options = {}) {
         process.on('unhandledRejection', onRejection);
         process.on('uncaughtException', onUncaught);
         const servers = [];
-        for (const spec of specs) {
-            const factory = await loadFactory(spec);
-            servers.push(await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}), ...(spec.database !== undefined ? { database: spec.database } : {}) }));
+        const stop = async () => {
+            process.off('unhandledRejection', onRejection);
+            process.off('uncaughtException', onUncaught);
+            const stopped = await Promise.allSettled(servers.map(async (server) => {
+                let timeout;
+                try {
+                    await Promise.race([
+                        Promise.resolve().then(() => server.stop()),
+                        new Promise((_, reject) => { timeout = setTimeout(() => reject(new Error(`Twin on port ${server.port} did not stop within ${STOP_TIMEOUT_MS} ms.`)), STOP_TIMEOUT_MS); }),
+                    ]);
+                }
+                finally {
+                    if (timeout !== undefined)
+                        clearTimeout(timeout);
+                }
+            }));
+            return stopped.filter((result) => result.status === 'rejected').map((result) => result.reason);
+        };
+        try {
+            await parallelStartup(specs, async (spec) => {
+                const factory = await loadFactory(spec);
+                const server = await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}), ...(spec.database !== undefined ? { database: spec.database } : {}) });
+                // Record the handle before validating it, so rollback also owns a bad factory result.
+                servers.push(server);
+                if (!Number.isInteger(server.port) || server.port < 1 || server.port > 65535 || (spec.port !== 0 && server.port !== spec.port)) {
+                    throw new Error(`Twin "${spec.id}" bound port ${server.port}, requested ${spec.port}.`);
+                }
+                ports[spec.id] = server.port;
+            });
+        }
+        catch (error) {
+            const cleanup = await stop();
+            if (cleanup.length)
+                throw new AggregateError([error, ...cleanup], 'Co-located host startup and rollback failed.');
+            throw error;
         }
         return {
             isolation,
             ports,
             stop: async () => {
-                process.off('unhandledRejection', onRejection);
-                process.off('uncaughtException', onUncaught);
-                // EVERY stop is invoked, IN PARALLEL, each under its own timeout, and no outcome —
-                // rejection, hang, or slowness — can prevent the others or wedge host.stop() itself.
-                // The awaited-sequential first cut re-created the SIGKILL escalation it was fixing
-                // through a new door (§9 round two H2, 2026-08-31: one pending/throwing stop — fly's
-                // cleanup throws on a failed container removal — left siblings unstopped and the host
-                // ignoring SIGTERM forever). The bound stays under downWorld's 5s SIGKILL grace.
-                await Promise.allSettled(servers.map((s) => Promise.race([
-                    Promise.resolve().then(() => s.stop()),
-                    new Promise((resolveTimeout) => setTimeout(resolveTimeout, STOP_TIMEOUT_MS).unref?.()),
-                ])));
+                // 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) });
             },
         };
     }
@@ -96,6 +121,11 @@ export async function startColocatedHost(specs, options = {}) {
         let ready = false;
         worker.on('message', (msg) => {
             if (msg?.type === 'ready') {
+                if (typeof msg.port !== 'number' || !Number.isInteger(msg.port) || msg.port < 1 || msg.port > 65535 || (spec.port !== 0 && msg.port !== spec.port)) {
+                    rejectReady(new Error(`Twin "${spec.id}" bound port ${msg.port}, requested ${spec.port}.`));
+                    return;
+                }
+                ports[spec.id] = msg.port;
                 ready = true;
                 resolveReady();
             }
@@ -107,6 +137,8 @@ export async function startColocatedHost(specs, options = {}) {
         });
         worker.on('exit', (code) => {
             workers.delete(spec.id);
+            if (!ready)
+                rejectReady(new Error(`Twin "${spec.id}" exited before readiness (code ${code}).`));
             if (stopping.value || code === 0)
                 return;
             // Minimal-primitive doctrine: no keep-alive supervisor. A crashed worker is NOT
@@ -115,8 +147,17 @@ export async function startColocatedHost(specs, options = {}) {
         });
         workers.set(spec.id, worker);
     });
-    for (const spec of specs)
-        await spawnWorker(spec);
+    try {
+        await parallelStartup(specs, async (spec) => spawnWorker(spec));
+    }
+    catch (error) {
+        stopping.value = true;
+        const stopped = await Promise.allSettled([...workers.values()].map((worker) => worker.terminate()));
+        const cleanup = stopped.filter((result) => result.status === 'rejected').map((result) => result.reason);
+        if (cleanup.length)
+            throw new AggregateError([error, ...cleanup], 'Co-located worker startup and rollback failed.');
+        throw error;
+    }
     return {
         isolation,
         ports,

package/dist/src/runtime.js

@@ -1,5 +1,6 @@
 import { claimEnvOutput, publishEnvOutput } from "./env-output.js";
 import { offSignal } from "./signals.js";
+import { parallelStartup } from "./startup.js";
 import { assertWorldStateRemovable, removeWorldState } from "./ancestry.js";
 import { packCli, packEntry } from "./catalog.js";
 import { spawn, spawnSync } from 'node:child_process';
@@ -1304,6 +1305,8 @@ function versionSatisfies(actual, pin) {
  * all share the host child's pid — so pids/instance.json/downWorld need no special casing.
  */
 async function startColocatedServices(config, colocated, isolation, worldEnv, paths, allocatedPorts, boot) {
+    if (colocated.length === 0)
+        return [];
     const hostCli = siblingScript(import.meta.url, 'host-cli');
     const args = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker'];
     const allocated = [];
@@ -1341,7 +1344,7 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
         exitState.value = { code, signal };
     });
     const command = [process.execPath, ...args];
-    for (const { service, port } of allocated) {
+    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) => {
             if (undeadPids([child.pid]).length)
@@ -1352,8 +1355,8 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
             catch { /* best effort cleanup */ }
             throw new Error(`Co-located twin "${service.id}" failed to start (host isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
         });
-    }
-    for (const [index, { service, port }] of allocated.entries()) {
+    });
+    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)
@@ -1364,7 +1367,7 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
             catch { /* best effort cleanup */ }
             throw error;
         });
-    }
+    });
     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/dist/src/startup.d.ts

@@ -0,0 +1,2 @@
+/** Finite independent boot operations. Stop scheduling on failure and join every operation already begun. */
+export declare function parallelStartup<T>(items: readonly T[], start: (item: T, index: number) => Promise<void>): Promise<void>;

package/dist/src/startup.js

@@ -0,0 +1,24 @@
+/** Finite independent boot operations. Stop scheduling on failure and join every operation already begun. */
+export async function parallelStartup(items, start) {
+    let next = 0;
+    let failed = false;
+    const errors = [];
+    await Promise.all(Array.from({ length: Math.min(8, items.length) }, async () => {
+        while (!failed) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            try {
+                await start(items[index], index);
+            }
+            catch (error) {
+                failed = true;
+                errors.push(error);
+            }
+        }
+    }));
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length > 1)
+        throw new AggregateError(errors, 'Independent World startup operations failed.');
+}

package/package.json

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

@@ -23,6 +23,7 @@ import { Worker } from 'node:worker_threads';
 import { siblingScript } from './sibling.ts';
 import { importModule } from './import-module.ts';
 import { pathToFileURL } from 'node:url';
+import { parallelStartup } from './startup.ts';
 
 /** One twin to mount in the host. `module`/`export` name a `({port,root,readOnly}) => {port,stop}`
  *  factory (every pack ships one, e.g. `createStripeTwinServer`). `module` is anything import()
@@ -104,28 +105,43 @@ export async function startColocatedHost(
     process.on('uncaughtException', onUncaught);
 
     const servers: TwinServer[] = [];
-    for (const spec of specs) {
-      const factory = await loadFactory(spec);
-      servers.push(await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}), ...(spec.database !== undefined ? { database: spec.database } : {}) }));
+    const stop = async (): Promise<unknown[]> => {
+      process.off('unhandledRejection', onRejection);
+      process.off('uncaughtException', onUncaught);
+      const stopped = await Promise.allSettled(servers.map(async (server) => {
+        let timeout: ReturnType<typeof setTimeout> | undefined;
+        try {
+          await Promise.race([
+            Promise.resolve().then(() => server.stop()),
+            new Promise<never>((_, reject) => { timeout = setTimeout(() => reject(new Error(`Twin on port ${server.port} did not stop within ${STOP_TIMEOUT_MS} ms.`)), STOP_TIMEOUT_MS); }),
+          ]);
+        } finally { if (timeout !== undefined) clearTimeout(timeout); }
+      }));
+      return stopped.filter((result): result is PromiseRejectedResult => result.status === 'rejected').map((result) => result.reason);
+    };
+    try {
+      await parallelStartup(specs, async (spec) => {
+        const factory = await loadFactory(spec);
+        const server = await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}), ...(spec.database !== undefined ? { database: spec.database } : {}) });
+        // Record the handle before validating it, so rollback also owns a bad factory result.
+        servers.push(server);
+        if (!Number.isInteger(server.port) || server.port < 1 || server.port > 65535 || (spec.port !== 0 && server.port !== spec.port)) {
+          throw new Error(`Twin "${spec.id}" bound port ${server.port}, requested ${spec.port}.`);
+        }
+        ports[spec.id] = server.port;
+      });
+    } catch (error) {
+      const cleanup = await stop();
+      if (cleanup.length) throw new AggregateError([error, ...cleanup], 'Co-located host startup and rollback failed.');
+      throw error;
     }
     return {
       isolation,
       ports,
       stop: async () => {
-        process.off('unhandledRejection', onRejection);
-        process.off('uncaughtException', onUncaught);
-        // EVERY stop is invoked, IN PARALLEL, each under its own timeout, and no outcome —
-        // rejection, hang, or slowness — can prevent the others or wedge host.stop() itself.
-        // The awaited-sequential first cut re-created the SIGKILL escalation it was fixing
-        // through a new door (§9 round two H2, 2026-08-31: one pending/throwing stop — fly's
-        // cleanup throws on a failed container removal — left siblings unstopped and the host
-        // ignoring SIGTERM forever). The bound stays under downWorld's 5s SIGKILL grace.
-        await Promise.allSettled(servers.map((s) =>
-          Promise.race([
-            Promise.resolve().then(() => s.stop()),
-            new Promise((resolveTimeout) => setTimeout(resolveTimeout, STOP_TIMEOUT_MS).unref?.()),
-          ]),
-        ));
+        // 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) });
       },
     };
   }
@@ -143,8 +159,14 @@ export async function startColocatedHost(
       // below would emit a 2nd `spawn` for the same twin, which the isolation test asserts against.
       onEvent({ twin: spec.id, kind: 'spawn', detail: 'worker started' });
       let ready = false;
-      worker.on('message', (msg: { type?: string }) => {
-        if (msg?.type === 'ready') { ready = true; resolveReady(); }
+      worker.on('message', (msg: { type?: string; port?: number }) => {
+        if (msg?.type === 'ready') {
+          if (typeof msg.port !== 'number' || !Number.isInteger(msg.port) || msg.port < 1 || msg.port > 65535 || (spec.port !== 0 && msg.port !== spec.port)) {
+            rejectReady(new Error(`Twin "${spec.id}" bound port ${msg.port}, requested ${spec.port}.`)); return;
+          }
+          ports[spec.id] = msg.port;
+          ready = true; resolveReady();
+        }
       });
       worker.on('error', (err) => {
         onEvent({ twin: spec.id, kind: 'error', detail: String(err) });
@@ -152,6 +174,7 @@ export async function startColocatedHost(
       });
       worker.on('exit', (code) => {
         workers.delete(spec.id);
+        if (!ready) rejectReady(new Error(`Twin "${spec.id}" exited before readiness (code ${code}).`));
         if (stopping.value || code === 0) return;
         // Minimal-primitive doctrine: no keep-alive supervisor. A crashed worker is NOT
         // respawned — record the give-up (host-cli persists it → doctor red) and stay dead.
@@ -160,7 +183,14 @@ export async function startColocatedHost(
       workers.set(spec.id, worker);
     });
 
-  for (const spec of specs) await spawnWorker(spec);
+  try { await parallelStartup(specs, async (spec) => spawnWorker(spec)); }
+  catch (error) {
+    stopping.value = true;
+    const stopped = await Promise.allSettled([...workers.values()].map((worker) => worker.terminate()));
+    const cleanup = stopped.filter((result): result is PromiseRejectedResult => result.status === 'rejected').map((result) => result.reason);
+    if (cleanup.length) throw new AggregateError([error, ...cleanup], 'Co-located worker startup and rollback failed.');
+    throw error;
+  }
 
   return {
     isolation,

package/src/runtime.ts

@@ -1,5 +1,6 @@
 import { claimEnvOutput, publishEnvOutput } from './env-output.ts';
 import { offSignal } from './signals.ts';
+import { parallelStartup } from './startup.ts';
 import { assertWorldStateRemovable, removeWorldState } from './ancestry.ts';
 import { packCli, packEntry } from './catalog.ts';
 import { spawn, spawnSync } from 'node:child_process';
@@ -1321,6 +1322,7 @@ async function startColocatedServices(
   allocatedPorts: Set<number>,
   boot: BootContext,
 ): 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 allocated: Array<{ service: WorldServiceConfig; port: number; mounted: MountedPackage }> = [];
@@ -1360,22 +1362,22 @@ async function startColocatedServices(
   });
 
   const command = [process.execPath, ...args];
-  for (const { service, port } of allocated) {
+  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) => {
       if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (startup failed)', 'SIGTERM');
       try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
       throw new Error(`Co-located twin "${service.id}" failed to start (host isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
     });
-  }
-  for (const [index, { service, port }] of allocated.entries()) {
+  });
+  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;
     });
-  }
+  });
   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`

package/src/startup.ts

@@ -0,0 +1,16 @@
+/** Finite independent boot operations. Stop scheduling on failure and join every operation already begun. */
+export async function parallelStartup<T>(items: readonly T[], start: (item: T, index: number) => Promise<void>): Promise<void> {
+  let next = 0;
+  let failed = false;
+  const errors: unknown[] = [];
+  await Promise.all(Array.from({ length: Math.min(8, items.length) }, async () => {
+    while (!failed) {
+      const index = next++;
+      if (index >= items.length) return;
+      try { await start(items[index]!, index); }
+      catch (error) { failed = true; errors.push(error); }
+    }
+  }));
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors, 'Independent World startup operations failed.');
+}