@volter/world-runtime 2.0.48 → 2.0.50

package/dist/src/runtime.js

@@ -1342,7 +1342,7 @@ function versionSatisfies(actual, pin) {
  */
 async function startColocatedServices(config, colocated, isolation, worldEnv, paths, allocatedPorts, boot) {
     if (colocated.length === 0)
-        return [];
+        return { services: [], ready: Promise.resolve() };
     const hostCli = siblingScript(import.meta.url, 'host-cli');
     const readyFile = join(paths.instance, `host-ready-${boot.bootId}.json`);
     const args = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker', '--ready-file', readyFile];
@@ -1381,55 +1381,10 @@ 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) => {
-            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}`);
-        });
-    });
-    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}`);
-    }
     const host = '127.0.0.1';
-    return allocated.map(({ service, port, mounted }) => {
+    // Every twin's address is known once its port is allocated: the records and
+    // the environment they inject exist before the host reports its starts.
+    const services = allocated.map(({ service, port, mounted }) => {
         const url = `http://${host}:${port}`;
         return {
             id: service.id,
@@ -1448,6 +1403,55 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
             },
         };
     });
+    const ready = (async () => {
+        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) => {
+                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}`);
+            });
+        });
+        // The host's receipt (this boot, every requested port) is published only
+        // after every factory bound its own port; a port another process held fails
+        // its bind and leaves no receipt. The receipt is the host's ownership proof
+        // for each port, so no twin waits out a settle (ADR-0008). A port that
+        // answers with another boot's identity is still refused.
+        const hostSettle = Promise.resolve('alive');
+        await parallelStartup(allocated, async ({ service, port }) => {
+            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;
+            });
+        });
+        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}`);
+        }
+    })();
+    // Observed here so a failure before the caller awaits it is not unhandled;
+    // the caller awaits `ready` before the World is up.
+    ready.catch(() => undefined);
+    return { services, ready };
 }
 export async function upWorld(configId, options = {}, abort) {
     abort?.throwIfAborted();
@@ -1698,12 +1702,19 @@ export async function upWorld(configId, options = {}, abort) {
             const allocatedPorts = new Set(loaded.config.services.flatMap((service) => typeof service.port === 'number' ? [service.port] : []));
             // Non-'process' isolation: boot every colocate-declaring service inside ONE host child
             // first; anything without `colocate` (and externals) still goes through the spawn path.
+            // The co-located host's twins are known by address once their ports are
+            // allocated. A twin serves and calls no other service while it starts,
+            // so a later twin declaration starts beside the host's startup; any other
+            // service waits until every earlier one is ready, as declared (ADR-0009).
+            let colocatedReady;
             if (isolation !== 'process') {
                 const colocated = loaded.config.services.filter((service) => service.colocate && service.type !== 'external');
-                for (const started of await startColocatedServices(loaded.config, colocated, isolation, env, { root, instance, logs, data }, allocatedPorts, boot)) {
+                const host = await startColocatedServices(loaded.config, colocated, isolation, env, { root, instance, logs, data }, allocatedPorts, boot);
+                for (const started of host.services) {
                     services[started.id] = started;
                     Object.assign(env, started.env);
                 }
+                colocatedReady = host.ready;
                 recordPidsSoFar();
                 writeProxyEnv(root, name, env);
             }
@@ -1736,6 +1747,10 @@ export async function upWorld(configId, options = {}, abort) {
             for (const service of loaded.config.services) {
                 if (services[service.id])
                     continue; // already up co-located
+                if (colocatedReady && (service.type ?? 'twin') !== 'twin') {
+                    await colocatedReady;
+                    colocatedReady = undefined;
+                }
                 attemptProxy();
                 boot.signal.throwIfAborted();
                 const started = await startService(loaded.config, service, env, { root, instance, logs, data }, allocatedPorts, boot);
@@ -1744,6 +1759,8 @@ export async function upWorld(configId, options = {}, abort) {
                 Object.assign(env, started.env);
                 writeProxyEnv(root, name, env);
             }
+            if (colocatedReady)
+                await colocatedReady;
             detachBootSignals();
             // Re-evaluate once more after the LAST service: a single/last-twin world's OWN vendor twin
             // only lands in `env` once IT has started, so a check that only runs "before starting the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.48",
+  "version": "2.0.50",
   "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",
@@ -67,14 +67,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.30",
+    "@volter/world-core": "2.0.32",
     "@volter/world-console": "2.0.13"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "2.0.2",
-    "@volter/world-core": "2.0.30",
+    "@volter/world-core": "2.0.32",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -84,6 +84,6 @@
     }
   },
   "optionalDependencies": {
-    "@volter/twin-mongodb": "0.1.30"
+    "@volter/twin-mongodb": "0.1.32"
   }
 }

package/src/runtime.ts

@@ -1347,8 +1347,8 @@ async function startColocatedServices(
   paths: { root: string; instance: string; logs: string; data: string },
   allocatedPorts: Set<number>,
   boot: BootContext,
-): Promise<WorldServiceInstance[]> {
-  if (colocated.length === 0) return [];
+): Promise<{ services: WorldServiceInstance[]; ready: Promise<void> }> {
+  if (colocated.length === 0) return { services: [], ready: Promise.resolve() };
   const hostCli = siblingScript(import.meta.url, 'host-cli');
   const readyFile = join(paths.instance, `host-ready-${boot.bootId}.json`);
   const args: string[] = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker', '--ready-file', readyFile];
@@ -1389,42 +1389,10 @@ 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) => {
-      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}`);
-    });
-  });
-  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`
-      + `Stop leftover services (e.g. \`volter-world down\`) and retry.\nLog: ${log}`,
-    );
-  }
-
   const host = '127.0.0.1';
-  return allocated.map(({ service, port, mounted }) => {
+  // Every twin's address is known once its port is allocated: the records and
+  // the environment they inject exist before the host reports its starts.
+  const services = allocated.map(({ service, port, mounted }) => {
     const url = `http://${host}:${port}`;
     return {
       id: service.id,
@@ -1443,6 +1411,45 @@ async function startColocatedServices(
       },
     };
   });
+  const ready = (async (): Promise<void> => {
+    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) => {
+        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}`);
+      });
+    });
+    // The host's receipt (this boot, every requested port) is published only
+    // after every factory bound its own port; a port another process held fails
+    // its bind and leaves no receipt. The receipt is the host's ownership proof
+    // for each port, so no twin waits out a settle (ADR-0008). A port that
+    // answers with another boot's identity is still refused.
+    const hostSettle = Promise.resolve('alive' as const);
+    await parallelStartup(allocated, async ({ service, port }) => {
+      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;
+      });
+    });
+    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}`,
+      );
+    }
+  })();
+  // Observed here so a failure before the caller awaits it is not unhandled;
+  // the caller awaits `ready` before the World is up.
+  ready.catch(() => undefined);
+  return { services, ready };
 }
 
 export async function upWorld(configId: string, options: UpWorldOptions = {}, abort?: AbortSignal): Promise<WorldInstance> {
@@ -1669,12 +1676,19 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       const allocatedPorts = new Set(loaded.config.services.flatMap((service) => typeof service.port === 'number' ? [service.port] : []));
       // Non-'process' isolation: boot every colocate-declaring service inside ONE host child
       // first; anything without `colocate` (and externals) still goes through the spawn path.
+      // The co-located host's twins are known by address once their ports are
+      // allocated. A twin serves and calls no other service while it starts,
+      // so a later twin declaration starts beside the host's startup; any other
+      // service waits until every earlier one is ready, as declared (ADR-0009).
+      let colocatedReady: Promise<void> | undefined;
       if (isolation !== 'process') {
         const colocated = loaded.config.services.filter((service) => service.colocate && service.type !== 'external');
-        for (const started of await startColocatedServices(loaded.config, colocated, isolation, env, { root, instance, logs, data }, allocatedPorts, boot)) {
+        const host = await startColocatedServices(loaded.config, colocated, isolation, env, { root, instance, logs, data }, allocatedPorts, boot);
+        for (const started of host.services) {
           services[started.id] = started;
           Object.assign(env, started.env);
         }
+        colocatedReady = host.ready;
         recordPidsSoFar();
         writeProxyEnv(root, name, env);
       }
@@ -1706,6 +1720,7 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       };
       for (const service of loaded.config.services) {
         if (services[service.id]) continue; // already up co-located
+        if (colocatedReady && (service.type ?? 'twin') !== 'twin') { await colocatedReady; colocatedReady = undefined; }
         attemptProxy();
         boot.signal.throwIfAborted();
         const started = await startService(loaded.config, service, env, { root, instance, logs, data }, allocatedPorts, boot);
@@ -1714,6 +1729,7 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
         Object.assign(env, started.env);
         writeProxyEnv(root, name, env);
       }
+      if (colocatedReady) await colocatedReady;
       detachBootSignals();
       // Re-evaluate once more after the LAST service: a single/last-twin world's OWN vendor twin
       // only lands in `env` once IT has started, so a check that only runs "before starting the