@volter/world-runtime 3.0.100 → 3.0.102

package/dist/src/runtime.js

@@ -26,7 +26,7 @@ import { packFacts } from "./pack-facts.js";
 import { assertOwnedRealPath, ownedPath } from "./owned-path.js";
 import { isEnvironmentName } from "./schema.js";
 import { infraConnections, parseInfraDefinition } from "./pglite-backing.js";
-import { describeServiceEnd, readServiceEnd, serviceOutput } from "./service-exit.js";
+import { describeServiceEnd, readServiceEnd } from "./service-exit.js";
 import { Socket } from 'node:net';
 import { getActiveWorldStore, withFileLock, stateDirName, PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding, WORLD_BOOT_PATH, WORLD_DATA_ENV, WORLD_ENV_NAMES_ENV } from '@volter/world-core/runtime';
 import { loadWorldConfig } from "./configs.js";
@@ -57,25 +57,6 @@ function retainSpawn(child) {
 function heldStarts() {
     return Object.fromEntries([...spawnedIdentities].map(([pid, identity]) => [pid, identity.start]));
 }
-/** The latest `limit` bytes of a service log, reaching into its one rotation (`<log>.1`) when the current file is
- *  shorter: a readiness line printed just before a rotation is still found, and a poll never reads 64 MiB files. */
-function readServiceText(log, limit = 4 * 1024 * 1024) {
-    const tailOfFile = (path, bytes) => {
-        if (bytes <= 0 || !existsSync(path))
-            return '';
-        const fd = openSync(path, 'r');
-        try {
-            const size = fstatSync(fd).size, start = Math.max(0, size - bytes), buffer = Buffer.alloc(size - start);
-            readSync(fd, buffer, 0, buffer.length, start);
-            return buffer.toString('utf8');
-        }
-        finally {
-            closeSync(fd);
-        }
-    };
-    const current = tailOfFile(log, limit);
-    return `${tailOfFile(`${log}.1`, limit - Buffer.byteLength(current))}${current}`;
-}
 /** The World's events file: every service's start and end, and the World's own stops, one JSON line each. */
 export function worldEventsPath(logs) {
     return join(logs, 'events.jsonl');
@@ -136,46 +117,25 @@ async function untilReadyOrEnded(wait, ended, boot, what, log) {
         });
     });
 }
-/** That the process answering a service's port is the service. allocatePort closes its probe before the service
- *  binds, so another process can take the port and answer the first connect; the service then fails to bind and ends
- *  at once, which a short settle catches for any program. A World twin also answers WORLD_BOOT_PATH with the boot it
- *  belongs to, so a leftover World's twin on the port is named exactly; a server that does not answer the path (a
- *  twin from before it, a program that is not a twin) is accepted on the settle alone. When the settle guards this
- *  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 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.
+/** That the process answering a service's port is the service, decided by an answer and never by a timed settle
+ *  (architecture D9). A World twin answers WORLD_BOOT_PATH with the boot it belongs to: this boot's id is the proof; another
+ *  boot's is a leftover World on the port, refused by name. A program that answers no boot identity (one that is not a
+ *  twin) is the service when it is still running once its port answers: another process holding the port makes the
+ *  service's own bind fail, which ends it, and its end is named. A co-located host's twins are vouched for by its
+ *  all-started receipt first (ADR 0012, ADR 0014). */
+async function confirmOwnPort(port, boot, ended, twin, what, log) {
     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) {
-        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;
-        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}`);
-    }
-    if (!twin)
-        return;
-    const answered = await answer;
+    const answered = twin ? await worldBootOf(port, boot.signal) : null;
     boot.signal.throwIfAborted();
-    if (answered && typeof answered.boot === 'string' && answered.boot !== boot.bootId) {
+    if (answered && typeof answered.boot === 'string') {
+        if (answered.boot === boot.bootId)
+            return;
         throw new Error(`${what}: its port is answered by a twin of another World boot (${answered.boot}), not this one; a leftover World holds the port. Stop it (\`volter-world list\`, then \`down\`) and retry.\nLog: ${log}`);
     }
+    // Whether the service has already ended, read now: one turn of the event loop, not a wait for it to fail.
+    const endedNow = ended ? await Promise.race([ended.then(() => true), new Promise((resolveNow) => setImmediate(() => resolveNow(false)))]) : false;
+    if (endedNow)
+        throw new Error(`${what} ended right after its port first answered, so another process probably holds the port: the service ${endedAccount(log)}\nLog: ${log}`);
 }
 /** What the server on a loopback port says its World boot is (WORLD_BOOT_PATH), or null. A direct loopback request:
  *  never through a proxy an activated shell's environment names. */
@@ -1237,7 +1197,7 @@ async function runOwnInfrastructureUp(command, serviceId, env, logPath, abort, p
 }
 /** Resolve `${url}`/`${host}`/`${port}` in a readiness probe's httpUrl against an owned loopback
  * service's allocated port (process/twin readiness — the port is auto-assigned, so it can't be a
- * literal in the config). Other probe kinds (command/stdoutMatch) are returned unchanged. */
+ * literal in the config). A command probe is returned unchanged. */
 function resolveReadyProbe(ready, svc) {
     if (ready.httpUrl === undefined)
         return ready;
@@ -1247,7 +1207,7 @@ function resolveReadyProbe(ready, svc) {
         .split('${port}').join(String(svc.port));
     return { ...ready, httpUrl };
 }
-async function awaitReadiness(ready, logPath, cwd, serviceId, env = process.env, abort) {
+async function awaitReadiness(ready, cwd, serviceId, env = process.env, abort) {
     if (!ready)
         return 'no readiness declared';
     const timeoutMs = ready.timeoutMs ?? 60_000;
@@ -1283,12 +1243,6 @@ async function awaitReadiness(ready, logPath, cwd, serviceId, env = process.env,
                 lastError = errorMessage(error);
             }
         }
-        else if (ready.stdoutMatch !== undefined) {
-            const text = serviceOutput(readServiceText(logPath));
-            if (new RegExp(ready.stdoutMatch).test(text))
-                return passed(`the log matched /${ready.stdoutMatch}/`);
-            lastError = `pattern /${ready.stdoutMatch}/ not yet in service log`;
-        }
         // A service that is nearly ready is seen at once; one that is slow is asked at most every intervalMs.
         await sleep(Math.min(intervalMs, 25 * 2 ** attempt));
         attempt += 1;
@@ -1329,7 +1283,7 @@ async function startExternalService(service, paths, worldEnv, stripEnv, boot) {
     const upOutput = await runExternalUp(external.up, cwd, service.id, env, log, boot?.signal, boot?.progress);
     boot?.progress(`${service.id}: up returned`);
     // 2. readiness — Docker-backed externals take seconds to boot.
-    const readiness = await awaitReadiness(external.readyWhen, log, cwd, service.id, env, boot?.signal);
+    const readiness = await awaitReadiness(external.readyWhen, cwd, service.id, env, boot?.signal);
     boot?.progress(`${service.id}: ready (${readiness})`);
     // 3. status — discover connection info (optional; may reuse up output instead).
     let statusOutput = '';
@@ -1465,7 +1419,7 @@ async function startService(config, service, worldEnv, paths, allocatedPorts, bo
         throw new Error(`Service "${service.id}" failed to start: ${errorMessage(error)}\nLog: ${log}`);
     });
     boot.progress(`${service.id}: port ${port} answers`);
-    await confirmOwnPort(port, boot, ended, (service.type ?? 'twin') === 'twin', `Service "${service.id}"`, log, true).catch(async (error) => {
+    await confirmOwnPort(port, boot, ended, (service.type ?? 'twin') === 'twin', `Service "${service.id}"`, log).catch(async (error) => {
         if (undeadPids([child.pid]).length)
             recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
         try {
@@ -1481,10 +1435,10 @@ async function startService(config, service, worldEnv, paths, allocatedPorts, bo
     const host = '127.0.0.1';
     const url = `http://${host}:${port}`;
     boot.progress(`${service.id}: port ${port} is its own`);
-    // Optional readiness probe beyond TCP (httpUrl/command/stdoutMatch): a process can bind its port
+    // Optional readiness probe beyond TCP (httpUrl/command): a process can bind its port
     // before it is actually serving, so this makes `up` wait until the service truly responds.
     if (service.ready && service.ready !== 'tcp') {
-        const readiness = await untilReadyOrEnded((abort) => awaitReadiness(resolveReadyProbe(service.ready, { host, port, url }), log, cwd, service.id, env, abort), ended, boot, 'the service', log).catch(async (error) => {
+        const readiness = await untilReadyOrEnded((abort) => awaitReadiness(resolveReadyProbe(service.ready, { host, port, url }), cwd, service.id, env, abort), ended, boot, 'the service', log).catch(async (error) => {
             if (undeadPids([child.pid]).length)
                 recordWorldStop([log], 'world.service.stop', 'up (startup failed)', 'SIGTERM');
             try {
@@ -1960,11 +1914,10 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
         // 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 0014). A port that
-        // answers with another boot's identity is still refused.
-        const hostSettle = Promise.resolve('alive');
+        // for each port (ADR 0014). A port that answers with another boot's identity
+        // is still refused.
         await parallelStartup(allocated, async ({ service, port }) => {
-            await confirmOwnPort(port, boot, ended, true, `Co-located twin "${service.id}"`, log, true, hostSettle).catch(async (error) => {
+            await confirmOwnPort(port, boot, ended, true, `Co-located twin "${service.id}"`, log).catch(async (error) => {
                 if (undeadPids([child.pid]).length)
                     recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
                 try {
@@ -3103,7 +3056,7 @@ function canonicalDottedIpv4(host) {
 function parseCustomShareOrigin(handshake) {
     const raw = /^https?:\/\/(\[[0-9a-f:.]+\]|[a-z0-9.-]+)(?::([0-9]{1,5}))?\/?$/i.exec(handshake);
     if (!raw) {
-        throw new Error(`Custom tunnel VOLTER_SHARE_URL must be a strict http(s) origin without path, query, fragment, or backslashes: ${handshake}`);
+        throw new Error(`The URL a custom tunnel wrote to VOLTER_SHARE_URL_FILE must be a strict http(s) origin without path, query, fragment, or backslashes: ${handshake}`);
     }
     const rawHost = raw[1];
     const rawPort = raw[2];
@@ -3112,24 +3065,27 @@ function parseCustomShareOrigin(handshake) {
         parsed = new URL(handshake);
     }
     catch {
-        throw new Error(`Custom tunnel emitted an invalid VOLTER_SHARE_URL handshake: ${handshake}`);
+        throw new Error(`A custom tunnel wrote an invalid URL to VOLTER_SHARE_URL_FILE: ${handshake}`);
     }
     const normalizedHostname = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase();
     if (!rawHost.startsWith('[') && isIP(normalizedHostname) === 4
         && (!canonicalDottedIpv4(rawHost) || rawHost !== normalizedHostname)) {
-        throw new Error(`Custom tunnel VOLTER_SHARE_URL must use canonical dotted-decimal IPv4 syntax: ${handshake}`);
+        throw new Error(`The URL a custom tunnel wrote to VOLTER_SHARE_URL_FILE must use canonical dotted-decimal IPv4 syntax: ${handshake}`);
     }
     if (rawPort && rawPort.length > 1 && rawPort.startsWith('0')) {
-        throw new Error(`Custom tunnel VOLTER_SHARE_URL must use canonical decimal port syntax: ${handshake}`);
+        throw new Error(`The URL a custom tunnel wrote to VOLTER_SHARE_URL_FILE must use canonical decimal port syntax: ${handshake}`);
     }
     if ((parsed.protocol !== 'http:' && parsed.protocol !== 'https:') || parsed.username || parsed.password
         || parsed.pathname !== '/' || parsed.search || parsed.hash) {
-        throw new Error(`Custom tunnel VOLTER_SHARE_URL must be a credential-free http(s) origin: ${handshake}`);
+        throw new Error(`The URL a custom tunnel wrote to VOLTER_SHARE_URL_FILE must be a credential-free http(s) origin: ${handshake}`);
     }
     return parsed.origin;
 }
-async function waitForPublicUrl(child, logPath, timeoutMs, requireTryCloudflare) {
-    const urlPattern = /https?:\/\/[^\s"'<>]+/gi;
+/** The tunnel's public URL, from the tunnel's own answer and never its output (architecture D9). cloudflared's metrics
+ *  server answers GET /quicktunnel with {"hostname"} once the quick tunnel is registered (empty before); a custom command
+ *  writes its public URL to VOLTER_SHARE_URL_FILE, ending the line when it is complete, so a half-written URL is never
+ *  read. The process's log is for people. */
+async function waitForPublicUrl(child, source, logPath, timeoutMs) {
     let exited = false;
     let exitSummary = '';
     child.once('exit', (code, signal) => {
@@ -3142,26 +3098,35 @@ async function waitForPublicUrl(child, logPath, timeoutMs, requireTryCloudflare)
     });
     const started = Date.now();
     while (Date.now() - started < timeoutMs) {
-        const text = existsSync(logPath) ? readFileSync(logPath, 'utf8') : '';
-        if (requireTryCloudflare) {
-            for (const candidate of text.match(urlPattern) ?? []) {
-                const parsed = parseCloudflareQuickPublicUrl(candidate);
-                if (parsed)
+        if ('metricsPort' in source) {
+            try {
+                const answer = await fetch(`http://127.0.0.1:${source.metricsPort}/quicktunnel`, { signal: AbortSignal.timeout(1000) });
+                const hostname = answer.ok ? (await answer.json()).hostname : undefined;
+                if (typeof hostname === 'string' && hostname) {
+                    const parsed = parseCloudflareQuickPublicUrl(`https://${hostname}`);
+                    if (!parsed)
+                        throw new Error(`cloudflared answered /quicktunnel with ${JSON.stringify(hostname)}, not a trycloudflare.com hostname. Log: ${logPath}`);
                     return parsed;
+                }
+            }
+            catch (error) {
+                if (error instanceof Error && error.message.startsWith('cloudflared answered'))
+                    throw error;
+                // its metrics server not listening yet: asked again
             }
         }
         else {
-            const handshake = /^VOLTER_SHARE_URL=(\S+)\s*$/m.exec(text)?.[1];
-            if (handshake)
-                return parseCustomShareOrigin(handshake);
+            const text = existsSync(source.urlFile) ? readFileSync(source.urlFile, 'utf8') : '';
+            if (text.endsWith('\n'))
+                return parseCustomShareOrigin(text.trim());
         }
         if (exited)
-            throw new Error(`Tunnel process exited before printing a public URL (${exitSummary}). Log: ${logPath}`);
-        await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+            throw new Error(`Tunnel process exited before answering its public URL (${exitSummary}). Log: ${logPath}`);
+        await new Promise((resolveWait) => setTimeout(resolveWait, 100));
     }
-    throw new Error(requireTryCloudflare
-        ? `Cloudflare tunnel did not print a trycloudflare.com https URL within ${timeoutMs}ms. Log: ${logPath}`
-        : `Custom tunnel did not print VOLTER_SHARE_URL=<http(s)-url> within ${timeoutMs}ms. Log: ${logPath}`);
+    throw new Error('metricsPort' in source
+        ? `cloudflared's metrics server did not answer a trycloudflare.com hostname at /quicktunnel within ${timeoutMs}ms. Log: ${logPath}`
+        : `Custom tunnel did not write its public URL, newline-terminated, to VOLTER_SHARE_URL_FILE within ${timeoutMs}ms. Log: ${logPath}`);
 }
 function sleep(ms) {
     return new Promise((resolveWait) => setTimeout(resolveWait, ms));
@@ -3331,12 +3296,19 @@ async function shareWorldReserved(name, options) {
     }
     const tunnel = shareCommand(options, service.url);
     const log = ownedPath(instance.dirs.logs, `${serviceId}.tunnel.log`);
-    // Each spawned tunnel owns one log generation. Truncating before spawn prevents a repeated
-    // share from accepting the previous process's URL handshake as the new process's endpoint.
+    // The public URL is the tunnel's own answer, never its output (architecture D9): cloudflared's metrics server
+    // answers /quicktunnel with the hostname it registered; a custom command writes its URL to VOLTER_SHARE_URL_FILE.
+    // Each spawned tunnel owns one generation of both, so a repeated share never takes the previous process's URL.
+    const source = tunnel.provider === 'cloudflare-quick'
+        ? { metricsPort: await allocatePort(new Set()) }
+        : { urlFile: ownedPath(instance.dirs.logs, `${serviceId}.tunnel.url`) };
+    if ('urlFile' in source)
+        rmSync(source.urlFile, { force: true });
+    const args = 'metricsPort' in source ? ['tunnel', '--metrics', `127.0.0.1:${source.metricsPort}`, ...tunnel.args.slice(1)] : tunnel.args;
     const out = openPrivateLog(log, 'w');
-    const child = spawn(tunnel.command, tunnel.args, { windowsHide: true,
+    const child = spawn(tunnel.command, args, { windowsHide: true,
         cwd: root,
-        env: withoutVaultSignIn(process.env),
+        env: { ...withoutVaultSignIn(process.env), ...('urlFile' in source ? { VOLTER_SHARE_URL_FILE: source.urlFile } : {}) },
         detached: true,
         stdio: ['ignore', out, out],
     });
@@ -3352,7 +3324,7 @@ async function shareWorldReserved(name, options) {
         if (!identity?.start)
             throw new Error('Tunnel birth capture failed; retiring held child');
         identities[identity.pid] = identity.start;
-        publicUrl = await waitForPublicUrl(child, log, options.timeoutMs ?? 20_000, tunnel.provider === 'cloudflare-quick');
+        publicUrl = await waitForPublicUrl(child, source, log, options.timeoutMs ?? 20_000);
         if (options.verifyPath !== false) {
             publicVerification = await verifyPublicUrl(publicUrl, options.verifyPath ?? '/health', options.timeoutMs ?? 90_000);
         }
@@ -3371,7 +3343,7 @@ async function shareWorldReserved(name, options) {
             provider: tunnel.provider,
             pid: child.pid ?? 0,
             log,
-            command: [tunnel.command, ...tunnel.args],
+            command: [tunnel.command, ...args],
             startedAt: new Date().toISOString(),
         };
         writePidsFromInstance(nextInstance, child.pid ? [child.pid] : []);
@@ -3503,8 +3475,8 @@ const DOCTOR_EXTERNAL_PROBE_TIMEOUT_MS = 3_000;
 /** Run an external service's declared readiness probe exactly ONCE (unlike `awaitReadiness`, which
  * polls until it passes or times out — appropriate at boot, wrong for a doctor health check, which
  * must report the CURRENT state, not wait for it to become healthy). Reuses the same probe shapes
- * (`command`/`httpUrl`/`stdoutMatch`) declared in config for the boot-time `readyWhen`. */
-async function probeExternalOnce(ready, cwd, env, logPath) {
+ * (`command`/`httpUrl`) declared in config for the boot-time `readyWhen`. */
+async function probeExternalOnce(ready, cwd, env) {
     if (ready.command !== undefined) {
         if (!commandExists(ready.command)) {
             return { ok: false, message: `readiness command \`${ready.command}\` not found on PATH` };
@@ -3529,13 +3501,7 @@ async function probeExternalOnce(ready, cwd, env, logPath) {
             return { ok: false, message: `probe failed: ${errorMessage(error)}` };
         }
     }
-    if (ready.stdoutMatch !== undefined) {
-        const text = serviceOutput(readServiceText(logPath));
-        if (new RegExp(ready.stdoutMatch).test(text))
-            return { ok: true, message: 'probe ok (stdoutMatch)' };
-        return { ok: false, message: `probe pattern /${ready.stdoutMatch}/ not found in log` };
-    }
-    return { ok: false, message: 'malformed readiness probe (no command/httpUrl/stdoutMatch)' };
+    return { ok: false, message: 'malformed readiness probe (no command/httpUrl)' };
 }
 /** A stopped service's own account for doctor: how it ended, its last output, and where its whole log is. */
 function stoppedServiceReport(pid, log) {
@@ -3599,7 +3565,7 @@ export async function doctorWorld(name, options = {}) {
             const probeCwd = service.external?.cwd ?? root;
             const probeEnv = { ...admittedEnv(stripEnvOf(instance.env ?? {})), ...(instance.env ?? {}), ...(service.external?.discoveredEnv ?? {}) };
             if (configuredExternal?.readyWhen) {
-                const probe = await probeExternalOnce(configuredExternal.readyWhen, probeCwd, probeEnv, service.log);
+                const probe = await probeExternalOnce(configuredExternal.readyWhen, probeCwd, probeEnv);
                 checks.push({ id: `service:${service.id}:external`, ok: probe.ok, message: `${discoveredMessage}; ${probe.message}` });
             }
             else if (configuredExternal?.status) {
@@ -3637,12 +3603,11 @@ export async function doctorWorld(name, options = {}) {
             checks.push({ id: `service:${service.id}:tcp`, ok: true, message: service.url });
             // A port that accepts is not a service that answers (a stuck event loop still completes the handshake): the
             // readiness probe the service declared is run again, as it was at boot.
-            // A log pattern matched at boot matches forever, so it cannot tell a hung service: only a probe that asks is re-run,
-            // in the service's own cwd and with its PORT, as at boot.
+            // The probe is re-run in the service's own cwd and with its PORT, as at boot.
             const configured = externalProbeConfig?.services.find((candidate) => candidate.id === service.id);
             const declared = configured?.ready;
-            if (pidLive && declared && declared !== 'tcp' && declared.stdoutMatch === undefined) {
-                const probe = await probeExternalOnce(resolveReadyProbe(declared, { host: '127.0.0.1', port: service.port, url: service.url }), configured?.cwd ? resolve(root, configured.cwd) : root, { ...admittedEnv(stripEnvOf(instance.env ?? {})), ...(instance.env ?? {}), ...(configured?.env ?? {}), PORT: String(service.port) }, service.log);
+            if (pidLive && declared && declared !== 'tcp') {
+                const probe = await probeExternalOnce(resolveReadyProbe(declared, { host: '127.0.0.1', port: service.port, url: service.url }), configured?.cwd ? resolve(root, configured.cwd) : root, { ...admittedEnv(stripEnvOf(instance.env ?? {})), ...(instance.env ?? {}), ...(configured?.env ?? {}), PORT: String(service.port) });
                 checks.push({ id: `service:${service.id}:ready`, ok: probe.ok,
                     message: probe.ok ? probe.message : `its port accepts but its declared readiness probe fails (${probe.message}): the service is up but not answering\n      log: ${service.log}` });
             }

package/dist/src/schema.d.ts

@@ -118,16 +118,15 @@ export type WorldExternalDiscover = {
     pattern?: string;
 };
 /**
- * Optional readiness probe, polled after `up` until it passes or `timeoutMs` elapses. Exactly one of:
- *  - `command`/`args`: a command that must exit 0,
- *  - `httpUrl`: an HTTP(S) URL that must return a 2xx/3xx response,
- *  - `stdoutMatch`: a regex that must appear in the `up` command's captured stdout/stderr log.
+ * Optional readiness probe, polled after `up` until it passes or `timeoutMs` elapses: the service answering its own
+ * protocol (architecture D9). Exactly one of:
+ *  - `command`/`args`: a command that asks the service and exits 0 when it answers,
+ *  - `httpUrl`: an HTTP(S) URL that must return a 2xx/3xx response.
  */
 export type WorldExternalReadyWhen = {
     command?: string;
     args?: string[];
     httpUrl?: string;
-    stdoutMatch?: string;
     timeoutMs?: number;
     intervalMs?: number;
 };
@@ -252,7 +251,6 @@ export type WorldServiceConfig = {
      * service truly serves, so `up` returning means "ready" (no post-up re-polling needed):
      *   - `{ httpUrl }`  — poll until 2xx/3xx. `${url}`/`${host}`/`${port}` resolve to the allocated port.
      *   - `{ command, args }` — poll until the command exits 0 (runs with the service env, incl. `PORT`).
-     *   - `{ stdoutMatch }` — poll until a regex matches the service's stdout/stderr log.
      * 'external' services use `external.readyWhen` instead.
      */
     ready?: 'tcp' | WorldExternalReadyWhen;

package/dist/src/schema.js

@@ -31,17 +31,16 @@ function assertValidRegex(pattern, what, path) {
     }
 }
 /** Shared validator for a readiness probe — used by both `external.readyWhen` and a process/twin
- * service's `ready` object. Exactly one of command/httpUrl/stdoutMatch, correct types, and any
- * stdoutMatch regex must compile (so a typo fails at config time, not mid-boot). */
+ * service's `ready` object. Exactly one of command/httpUrl, with correct types. */
 function assertReadyWhen(ready, what, path) {
     if (!ready || typeof ready !== 'object' || Array.isArray(ready)) {
         throw new Error(`${what} must be an object in ${path}`);
     }
-    assertKeys(ready, ['command', 'args', 'httpUrl', 'stdoutMatch', 'timeoutMs', 'intervalMs'], what, path);
+    assertKeys(ready, ['command', 'args', 'httpUrl', 'timeoutMs', 'intervalMs'], what, path);
     const r = ready;
-    const probes = [r.command !== undefined, r.httpUrl !== undefined, r.stdoutMatch !== undefined].filter(Boolean).length;
+    const probes = [r.command !== undefined, r.httpUrl !== undefined].filter(Boolean).length;
     if (probes !== 1) {
-        throw new Error(`${what} must set exactly one of command/httpUrl/stdoutMatch in ${path}`);
+        throw new Error(`${what} must set exactly one of command/httpUrl in ${path}`);
     }
     if (r.command !== undefined && typeof r.command !== 'string')
         throw new Error(`${what}.command must be a string in ${path}`);
@@ -51,11 +50,6 @@ function assertReadyWhen(ready, what, path) {
         throw new Error(`${what}.args requires command in ${path}`);
     if (r.httpUrl !== undefined && typeof r.httpUrl !== 'string')
         throw new Error(`${what}.httpUrl must be a string in ${path}`);
-    if (r.stdoutMatch !== undefined) {
-        if (typeof r.stdoutMatch !== 'string')
-            throw new Error(`${what}.stdoutMatch must be a string in ${path}`);
-        assertValidRegex(r.stdoutMatch, `${what}.stdoutMatch`, path);
-    }
     for (const key of ['timeoutMs', 'intervalMs']) {
         if (r[key] !== undefined && (!Number.isInteger(r[key]) || r[key] <= 0))
             throw new Error(`${what}.${key} must be a positive integer in ${path}`);

package/dist/src/service-exit.d.ts

@@ -24,9 +24,6 @@ export type ServiceEnd = {
     /** The service's own last lines of output in its last run, oldest first. */
     lastOutput: string[];
 };
-/** A log's text as the service wrote it, without the recorder's records: what a `stdoutMatch` readiness pattern is
- *  matched against. */
-export declare function serviceOutput(text: string): string;
 /** The last run's end in a service log: its start, its exit record (absent while it runs, or when its parent was killed
  *  with it), and the output it wrote last. Undefined for a log the parent never wrote to (a co-located twin's host log),
  *  which has no runs to tell apart. A run is bounded by its start record or, for a spawn that failed before starting

package/dist/src/service-exit.js

@@ -74,11 +74,6 @@ function split(line) {
         return { output: line };
     }
 }
-/** A log's text as the service wrote it, without the recorder's records: what a `stdoutMatch` readiness pattern is
- *  matched against. */
-export function serviceOutput(text) {
-    return text.includes(MARK) ? text.split('\n').map((line) => split(line).output).join('\n') : text;
-}
 /** The last run's end in a service log: its start, its exit record (absent while it runs, or when its parent was killed
  *  with it), and the output it wrote last. Undefined for a log the parent never wrote to (a co-located twin's host log),
  *  which has no runs to tell apart. A run is bounded by its start record or, for a spawn that failed before starting

package/dist/src/up-cli.js

@@ -23,7 +23,18 @@ export async function upCommand(subject, rest, root) {
     // --keep-state: boot over the state the World's directory already holds (a World carried somewhere else, e.g. a
     // browser tab's image, comes up over its data instead of starting empty, as a fresh `up` does)
     const keepState = rest.includes('--keep-state');
+    // --app-url: where the booter serves the app, recorded as `volter-world app-url --set` records it, once the World is
+    // up and in this process: a booter that knows the address before the app listens (a browser tab's preview origin)
+    // saves a whole command between up and the app's start.
+    const appUrl = optionValue(rest, '--app-url') || undefined;
+    if (appUrl !== undefined && !(URL.canParse(appUrl) && /^https?:$/.test(new URL(appUrl).protocol)))
+        throw new Error(`volter-world up: --app-url "${appUrl}" must be an http(s) URL`);
     const instance = await superviseWorldUp(subject, { name, root, mode, envFile, forceEnvOutput: rest.includes('--force'), owner: ownerOption(rest), ...(isolation ? { isolation } : {}), ...(keepState ? { keepState: true } : {}) });
+    if (appUrl !== undefined) {
+        const { setAppUrl } = await import("./app-url.js");
+        setAppUrl(instance.name, appUrl, { root });
+        process.stderr.write(`volter-world up ${instance.name}: app url recorded: ${appUrl}\n`);
+    }
     if (rest.includes('--json'))
         process.stdout.write(JSON.stringify(instance, null, 2) + '\n');
     else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.100",
+  "version": "3.0.102",
   "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",
@@ -69,14 +69,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.100",
-    "@volter/world-console": "3.0.95"
+    "@volter/world-core": "3.0.102",
+    "@volter/world-console": "3.0.97"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.100",
+    "@volter/world-core": "3.0.102",
     "mongodb": "~6.20.0",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",

package/src/cli-commands.ts

@@ -61,7 +61,7 @@ function printHelp(): void {
                                                   # emission. Exit 0 = ready to \`up\`; exit 1 = the honest worklist.
                                                   # Deterministic: same repo + same pack catalog => identical bytes.
                                                   # init DIAGNOSES; it never boots — it prints the exact next commands
-  volter-world up <config> --env-out=<path> [--owner <label>] [--name <name>] [--mode local|share|sealed] [--isolation process|colocated|worker] [--keep-state] [--json] [--root <repo>]
+  volter-world up <config> --env-out=<path> [--owner <label>] [--name <name>] [--mode local|share|sealed] [--isolation process|colocated|worker] [--keep-state] [--app-url <url>] [--json] [--root <repo>]
   volter-world outdated <world> [--json]            — each mounted twin: pinned / mounted / catalog-current version and protocol standing (R17)
   volter-world audit <world> [--json]               — each mounted twin's grade, as the catalog records it (R17)
   volter-world down <name> [--grace-ms <ms>] [--purge] [--if-instance <token>] [--root <repo>]   # SIGTERM, then SIGKILL survivors after the grace (default 5000ms)

package/src/configs.ts

@@ -38,7 +38,7 @@ const LEGACY_NESTED = {
   bare: new Set(['name']), resources: new Set(['memoryMiB', 'writableStorageMiB']), catalog: new Set(['sha', 'protocol']),
   root: new Set(['url', 'deploy', 'refresh', 'scope']), refresh: new Set(['every', 'webhook']),
   external: new Set(['up', 'status', 'down', 'discover', 'readyWhen']), discover: new Set(['as', 'source', 'jsonPath', 'pattern']),
-  ready: new Set(['command', 'args', 'httpUrl', 'stdoutMatch', 'timeoutMs', 'intervalMs']), colocate: new Set(['module', 'export', 'scenarioPath']),
+  ready: new Set(['command', 'args', 'httpUrl', 'timeoutMs', 'intervalMs']), colocate: new Set(['module', 'export', 'scenarioPath']),
   share: new Set(['provider', 'command', 'args', 'ephemeral', 'services']), shareService: new Set(['id', 'verifyPath']),
 } as const;
 

package/src/mongodb-backing.ts

@@ -8,14 +8,16 @@ export function mongodbArgv(service: InfraService, data: string): string[] {
     ...(service.replicaSet ? ['--replSet', service.replicaSet] : [])];
 }
 
-/** MongoDB's structured record comes from this child, not a listener already holding the port. */
-export function mongodbListening(log: string, port: number): boolean {
-  return log.split('\n').some((line) => {
-    try {
-      const record = JSON.parse(line);
-      return record.id === 23016 && record.msg === 'Waiting for connections' && record.attr?.port === port;
-    } catch { return false; } // Non-JSON log lines are not the structured readiness record.
-  });
+/** Whether the server answering MongoDB's protocol on the port is this child: its own serverStatus names its pid. A
+ *  listener that is not answering yet, or another process's server on the port, is not. */
+export async function mongodbServes(service: InfraService, pid: number): Promise<boolean> {
+  const { MongoClient } = await import('mongodb');
+  const client = new MongoClient(`mongodb://127.0.0.1:${service.hostPort}`, { directConnection: true, timeoutMS: 1000, serverSelectionTimeoutMS: 1000 });
+  try {
+    await client.connect();
+    const status = await client.db('admin').command({ serverStatus: 1 });
+    return Number(status.pid) === pid;
+  } catch { return false; } finally { await client.close().catch(() => undefined); }
 }
 
 /** Ping the server; initialize only an explicitly declared one-member set and await its primary. */