@volter/world-runtime 3.0.38 → 3.0.39

package/dist/src/schema.d.ts

@@ -209,6 +209,8 @@ export type WorldServiceConfig = {
      * to loopback services directly while presenting a disguised world to the app/user.
      */
     controlPlane?: boolean;
+    /** Refuse branching before child compute when this service cannot carry its state to a branch. */
+    branchState?: 'unsupported';
     injectEnv?: string;
     /**
      * Additional env vars exported into the generated world env after this service starts.
@@ -293,7 +295,7 @@ export type WorldConfig = {
     id: string;
     /** How changesets are made and readied here; omitted: one approval, a summary required. */
     changesets?: WorldChangesetRules;
-    /** Real external origins; omitted preserves legacy routing, [] explicitly closes egress. */
+    /** HTTPS origin/exact-path/subtree grants with declared phase and explicit build passthrough; [] closes real egress. */
     network?: WorldNetwork;
     /** Internal normalized source format and saved discovery selection. */
     manifestVersion?: 1 | 2;
@@ -335,6 +337,8 @@ export type WorldConfig = {
     };
 };
 export type WorldServiceInstance = {
+    /** Explicit boot permission survives config edits and missing-field refusals. */
+    branchState?: 'supported' | 'unsupported';
     id: string;
     type: WorldServiceType;
     command: string[];
@@ -434,6 +438,8 @@ export type WorldRunRecord = WorldRunOutcome | {
 };
 export type WorldInstance = {
     name: string;
+    /** Unique boot identity, independent of the World clock; ordinary reading completes older records. */
+    instance: string;
     /** Snapshot of the selection in force when this instance booted. */
     selection?: WorldSelection;
     config: string;
@@ -448,6 +454,10 @@ export type WorldInstance = {
     };
     services: Record<string, WorldServiceInstance>;
     env: Record<string, string>;
+    /** Always written at boot; optional only so cleanup can read incomplete legacy records. */
+    networkCeiling?: WorldNetwork | 'unrestricted';
+    bootServices?: string[];
+    bootOwner?: string | null;
     envFile: string;
     pidsFile: string;
     actors?: Record<string, unknown>;
@@ -477,6 +487,7 @@ export type WorldInstance = {
      *  (docs/contributing/architecture.md, "The catalog: where twins come from"). */
     packFacts?: string[];
 };
+export declare function isEnvironmentName(value: unknown): value is string;
 export declare const DEFAULT_WORLD_SELECTION: WorldSelection;
 export declare const LEGACY_WORLD_SELECTION: WorldSelection;
 export declare function assertWorldSelection(value: unknown, path: string): asserts value is WorldSelection;

package/dist/src/schema.js

@@ -1,3 +1,4 @@
+import { errorMessage } from "./error-message.js";
 import { normalizeWorldNetwork } from '@volter/world-core/network-policy';
 export const WORLD_SCHEMA_VERSION = 2;
 export const WORLD_USAGES = ['application', 'dependencies', 'build', 'deployment'];
@@ -10,6 +11,12 @@ export const ISSUE_ENV_PREFIX = '$issue:';
  *  attaches, from the application URL the booter recorded (`volter-world app-url <world> --set`), so the app names
  *  the address it is reached at, which only its booter knows (a browser tab's preview origin, a local port). */
 export const APP_URL_ENV = '$app-url';
+export function isEnvironmentName(value) {
+    return typeof value === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function environmentMap(value) {
+    return record(value) && Object.entries(value).every(([name, entry]) => isEnvironmentName(name) && typeof entry === 'string');
+}
 function assertStringArray(value, what, path) {
     if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== 'string')) {
         throw new Error(`${what} must be a non-empty string array in ${path}`);
@@ -20,7 +27,7 @@ function assertValidRegex(pattern, what, path) {
         new RegExp(pattern);
     }
     catch (error) {
-        throw new Error(`${what} has an invalid regex (${error instanceof Error ? error.message : String(error)}) in ${path}`);
+        throw new Error(`${what} has an invalid regex (${errorMessage(error)}) in ${path}`);
     }
 }
 /** Shared validator for a readiness probe — used by both `external.readyWhen` and a process/twin
@@ -125,7 +132,7 @@ function assertLegacyWorldConfig(value, path) {
         config.network = normalizeWorldNetwork(config.network);
     if (config.description !== undefined && typeof config.description !== 'string')
         throw new Error(`World config description must be a string in ${path}`);
-    if (config.env !== undefined && (!record(config.env) || Object.values(config.env).some((entry) => typeof entry !== 'string')))
+    if (config.env !== undefined && !environmentMap(config.env))
         throw new Error(`World config env must be a string→string object in ${path}`);
     if (config.env?.VOLTER_WORLD_NETWORK_POLICY !== undefined)
         throw new Error(`World network permission belongs in runtime.network, not environment values in ${path}`);
@@ -173,7 +180,13 @@ function assertLegacyWorldConfig(value, path) {
             throw new Error(`Invalid service in ${path}`);
         if (!service.id || typeof service.id !== 'string')
             throw new Error(`Service must define string id in ${path}`);
+        if (service.branchState !== undefined && service.branchState !== 'unsupported')
+            throw new Error(`Service ${service.id} branchState must be unsupported in ${path}`);
         const exports = [service.injectEnv, ...Object.keys(service.injectEnvTemplates ?? {}), ...Object.keys(service.cliRedirect ?? {}), ...(Array.isArray(service.external?.discover) ? service.external.discover.map(entry => entry?.as) : [])];
+        if (exports.some(name => name !== undefined && !isEnvironmentName(name)))
+            throw new Error(`Service ${service.id} bindings must name environment variables in ${path}`);
+        if (service.issues !== undefined && (!record(service.issues) || typeof service.issues.path !== 'string' || !record(service.issues.body) || !environmentMap(service.issues.fill)))
+            throw new Error(`Service ${service.id} issues must define path, body and string→string fill in ${path}`);
         if (service.env?.VOLTER_WORLD_NETWORK_POLICY !== undefined || exports.includes('VOLTER_WORLD_NETWORK_POLICY'))
             throw new Error(`Service ${service.id} cannot replace World network permission in ${path}`);
         if (!/^[a-z0-9][a-z0-9._-]*$/.test(service.id))
@@ -265,7 +278,7 @@ function assertLegacyWorldConfig(value, path) {
         }
         if (service.version !== undefined && !(typeof service.version === 'string' && /^\^?\d+\.\d+(\.\d+)?$/.test(service.version)))
             throw new Error(`Service "${service.id}" version must pin the twin package as "major.minor.patch" or "^major.minor" in ${path}`);
-        if (service.env !== undefined && (!record(service.env) || Object.values(service.env).some((entry) => typeof entry !== 'string')))
+        if (service.env !== undefined && !environmentMap(service.env))
             throw new Error(`Service "${service.id}" env must be a string→string object in ${path}`);
         if (service.injectEnv !== undefined && typeof service.injectEnv !== 'string') {
             throw new Error(`Service "${service.id}" injectEnv must be a string in ${path}`);
@@ -378,7 +391,7 @@ function serviceV2ToLegacy(value, path) {
     if (!record(source) || !record(execution) || !record(endpoint) || !record(bindings))
         throw new Error(`Service "${String(value.id ?? '')}" sections must be objects in ${path}`);
     assertKeys(source, ['package', 'version'], 'service.source', path);
-    assertKeys(execution, ['process', 'colocate', 'lifecycle', 'cwd', 'environment', 'preload', 'controlPlane'], 'service.execution', path);
+    assertKeys(execution, ['process', 'colocate', 'lifecycle', 'cwd', 'environment', 'preload', 'controlPlane', 'branchState'], 'service.execution', path);
     assertKeys(endpoint, ['port', 'portReason', 'ready'], 'service.endpoint', path);
     assertKeys(bindings, ['injectEnv', 'injectEnvTemplates', 'cliRedirect', 'discover'], 'service.bindings', path);
     const process = execution.process === undefined ? {} : execution.process;
@@ -442,6 +455,7 @@ function serviceV2ToLegacy(value, path) {
         ...(environment.values === undefined ? {} : { env: environment.values }),
         ...(execution.preload === undefined ? {} : { preload: execution.preload }),
         ...(execution.controlPlane === undefined ? {} : { controlPlane: execution.controlPlane }),
+        ...(execution.branchState === undefined ? {} : { branchState: execution.branchState }),
         ...(endpoint.port === undefined ? {} : { port: endpoint.port }),
         ...(endpoint.portReason === undefined ? {} : { portReason: endpoint.portReason }),
         ...(endpoint.ready === undefined ? {} : { ready: endpoint.ready }),
@@ -488,7 +502,7 @@ function normalizeV2(value, path) {
     if (!record(environment))
         throw new Error(`runtime.environment must be an object in ${path}`);
     assertKeys(environment, ['values', 'strip'], 'runtime.environment', path);
-    if (environment.values !== undefined && (!record(environment.values) || Object.values(environment.values).some((entry) => typeof entry !== 'string')))
+    if (environment.values !== undefined && !environmentMap(environment.values))
         throw new Error(`runtime.environment.values must be a string→string object in ${path}`);
     if (scenario.actors !== undefined && !record(scenario.actors))
         throw new Error(`scenario.actors must be an object in ${path}`);
@@ -561,6 +575,7 @@ function serviceToV2(service) {
         ...(service.env === undefined ? {} : { environment: { values: service.env } }),
         ...(service.preload === undefined ? {} : { preload: service.preload }),
         ...(service.controlPlane === undefined ? {} : { controlPlane: service.controlPlane }),
+        ...(service.branchState === undefined ? {} : { branchState: service.branchState }),
     };
     const endpoint = {
         ...(service.port === undefined ? {} : { port: service.port }),

package/dist/src/served-world.d.ts

@@ -46,6 +46,7 @@ export declare function servedName(worldRoot: string, configRef: string): string
  *  `twins()` names the world's twins once booted; `rotate()` mints both tokens anew — the old die
  *  with the call — and keeps them beside the world like `boot` does. */
 export type MountedWorld = {
+    maxRequestBodySize: number;
     name: string;
     served: string;
     root: string;

package/dist/src/served-world.js

@@ -1,3 +1,4 @@
+import { errorMessage } from "./error-message.js";
 import { boardFrameKey, getActiveWorldStore, withHistoryLocks, captureHistory, historyAtInstant, historyDigest, historyEntries, readHistoryView, worldPaths } from '@volter/world-core/runtime';
 // A SERVED WORLD (docs/reference/http-api.md#a-served-world): `volter world serve` puts a world at
 // `http://<host>:<port>/<org>/<world>/`. Each twin's vendor API is under its vendor id — the
@@ -227,6 +228,7 @@ export async function mountWorld(name, opts = {}) {
     let stopping = null;
     const mounted = {
         name, served, root: worldRoot,
+        maxRequestBodySize: Math.max(1024 * 1024 * 1024, ...loadWorldConfig(configRef, worldRoot).config.services.map((service) => packFacts()[service.package?.replace(/^@volter\/twin-/, '') ?? service.id]?.maxRequestBodySize ?? 0)),
         get token() { return world.token; }, get readToken() { return world.readToken; },
         twins: () => world.twins(),
         rotate: () => { world.retoken(mintToken('tok_'), mintToken('tok_r_')); keep(); return { token: world.token, readToken: world.readToken }; },
@@ -317,9 +319,9 @@ export async function serveWorld(name, opts = {}) {
     // stale server on the port must never be mistaken for this one. Until the world is up the
     // doors answer 503.
     let consoleOrigin = null;
-    // a pushed blob (a release video) is one PUT: bodies up to 1 GiB, past a vendor's own media limits
+    // Keep the 1 GiB front baseline unless a served twin declares a larger transport cap.
     // a front for the whole World: its twins and links keep their own journals (architecture: a multiplexing front journals nothing)
-    const server = await serveHttp({ hostname: host, port: opts.port ?? 0, maxRequestBodySize: 1024 * 1024 * 1024, twinRequestJournal: false, fetch: (request) => consoleRedirect(request, consoleOrigin) ?? mounted.handle(request) });
+    const server = await serveHttp({ hostname: host, port: opts.port ?? 0, maxRequestBodySize: mounted.maxRequestBodySize, twinRequestJournal: false, fetch: (request) => consoleRedirect(request, consoleOrigin) ?? mounted.handle(request) });
     const url = `http://${host}:${server.port}`;
     try {
         await mounted.boot(url);
@@ -369,12 +371,21 @@ export async function serveWorld(name, opts = {}) {
     }
     catch (error) {
         // Boot succeeded: this call owns the World, but cannot return its stop handle.
+        const errors = [error];
         try {
             await stopAll();
         }
-        finally {
+        catch (cleanup) {
+            errors.push(cleanup);
+        }
+        try {
             await mounted.stop();
         }
+        catch (cleanup) {
+            errors.push(cleanup);
+        }
+        if (errors.length > 1)
+            throw new AggregateError(errors, 'World announcement and host cleanup failed');
         throw error;
     }
     return { url, base: `${url}/${mounted.served}`, name: mounted.served, port: server.port ?? 0, token: mounted.token, readToken: mounted.readToken, console: consoleUrl, stop: async () => { await stopAll(); await mounted.stop(); } };
@@ -591,6 +602,7 @@ export class WorldDoors {
         }
         if (door === 'open.js' && request.method === 'GET') {
             const script = `(() => {
+  const errorMessage = (${errorMessage.toString()});
   const world = document.body.dataset.world;
   const carried = new URLSearchParams(location.hash.slice(1));
   history.replaceState(null, '', location.pathname);
@@ -608,7 +620,7 @@ export class WorldDoors {
       if (!r.ok) throw new Error(opened.error || 'This World did not open.');
       location.replace(to);
     })
-    .catch((e) => { document.body.textContent = e.message || 'This World did not answer.'; });
+    .catch((e) => { document.body.textContent = errorMessage(e) || 'This World did not answer.'; tell({ error: document.body.textContent }); });
 })();
 `;
             return new Response(script, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' } });
@@ -770,7 +782,7 @@ export class WorldDoors {
         // the keys are gone whatever a removal answers; a branch that stays is said, not hidden (its parent key no longer opens this World)
         for (const k of [...gone, ...also])
             if (k.branch)
-                await this.host.branches?.remove(k.branch).catch((error) => { console.error(`${this.served}: branch ${k.branch} stays after its key was revoked: ${error instanceof Error ? error.message : String(error)}`); return false; });
+                await this.host.branches?.remove(k.branch).catch((error) => { console.error(`${this.served}: branch ${k.branch} stays after its key was revoked: ${errorMessage(error)}`); return false; });
         return [...ids];
     }
     async keysDoor(request, id, scope, via, session) {
@@ -1347,7 +1359,7 @@ export class WorldDoors {
             return Response.json({ error: `not this world: serving /${this.served}/` }, { status: 404 });
         }
         catch (error) {
-            return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 500 });
+            return Response.json({ error: errorMessage(error) }, { status: 500 });
         }
     }
     /** A twin's workspaces as its discovery door lists them (`GET /twin`'s `screens`: each built workspace screen's id and
@@ -1561,7 +1573,7 @@ export class WorldDoors {
             credential = await openSealedAt(credentialPath(this.worldRoot, name), name, destinationOf(base.origin));
         }
         catch (error) {
-            return Response.json({ error: error.message }, { status: 409 });
+            return Response.json({ error: errorMessage(error) }, { status: 409 });
         }
         if (credential === null)
             return Response.json({ error: `the ${name} link has no credential sealed` }, { status: 409 });
@@ -2039,7 +2051,7 @@ export class WorldDoors {
                 validateRemoteOrigin(body.origin ?? '');
             }
             catch (error) {
-                return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 400 });
+                return Response.json({ error: errorMessage(error) }, { status: 400 });
             }
             getActiveWorldStore().write(this.linksPath(), `${JSON.stringify({ ...this.links(), [name]: { origin: body.origin } }, null, 2)}\n`);
             return Response.json({ link: name, origin: body.origin });
@@ -2070,7 +2082,7 @@ export class WorldDoors {
                 }
                 catch (error) {
                     store.remove(path);
-                    return Response.json({ error: `not a check: ${error instanceof Error ? error.message : String(error)}` }, { status: 400 });
+                    return Response.json({ error: `not a check: ${errorMessage(error)}` }, { status: 400 });
                 }
                 return Response.json({ check: name });
             }
@@ -2160,7 +2172,7 @@ export class WorldDoors {
                     assertChangesetRules(body?.changesets, path);
                 }
                 catch (error) {
-                    return Response.json({ error: error instanceof Error ? error.message.replace(` in ${path}`, '') : String(error) }, { status: 400 });
+                    return Response.json({ error: errorMessage(error).replace(` in ${path}`, '') }, { status: 400 });
                 }
                 const { config } = loadWorldConfig(path, this.worldRoot);
                 const rules = body.changesets;
@@ -2506,7 +2518,7 @@ export class WorldDoors {
                 await this.host.serveBranch(target);
             }
             catch (error) {
-                return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 409 });
+                return Response.json({ error: errorMessage(error) }, { status: 409 });
             }
             return Response.json({ world: this.served, checkedOut: target });
         }
@@ -2562,7 +2574,7 @@ export class WorldDoors {
             }
             catch (error) {
                 this.keepKeys(this.keys().filter((k) => k.id !== keyId)); // no branch, no key
-                return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 409 });
+                return Response.json({ error: errorMessage(error) }, { status: 409 });
             }
         }
         if (rest.length === 2 && request.method === 'DELETE') {
@@ -2914,7 +2926,7 @@ export class WorldDoors {
             return Response.json({ world: this.served, changeset: changeset.name, receipts, position, snapshots, ...(kept?.owner ? { owner: kept.owner } : {}), ...(kept?.pushedBy ? { pushedBy: kept.pushedBy } : {}) });
         }
         catch (error) {
-            return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 409 });
+            return Response.json({ error: errorMessage(error) }, { status: 409 });
         }
     }
 }
@@ -3044,7 +3056,7 @@ export async function scheduleRefreshes(name, worldRoot, instance, log = (l) =>
     const timers = [];
     for (const { vendor, controlRoot, root, everyMs } of await refreshSchedule(worldRoot, instance, log)) {
         const timer = setInterval(() => { refreshTwin({ worldRoot, vendor, controlRoot, root, force: true }).then((r) => { if (!r.refreshed)
-            log(`${vendor}: not refreshed: ${r.reason}`); }, (e) => log(`${vendor}: refresh failed: ${e instanceof Error ? e.message : String(e)}`)); }, everyMs);
+            log(`${vendor}: not refreshed: ${r.reason}`); }, (e) => log(`${vendor}: refresh failed: ${errorMessage(e)}`)); }, everyMs);
         timer.unref?.();
         timers.push(timer);
     }

package/dist/src/service-recorder.js

@@ -15,6 +15,8 @@
 //   service's own lines carry none: lines between two marks were written between those times;
 // - forwards TERM/INT/HUP to the service and exits with its status (128+n for a signal).
 // The World's NODE_OPTIONS (the injector) is for the service, not this parent: it arrives renamed and is restored.
+import { signalChild } from './process-signal.mjs';
+import { errorMessage } from "./error-message.js";
 import { spawn } from 'node:child_process';
 import { constants } from 'node:os';
 import { appendFileSync, closeSync, fstatSync, openSync, readSync, statSync, truncateSync, writeFileSync } from 'node:fs';
@@ -102,9 +104,12 @@ catch {
 let forwarded = null;
 for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'])
     process.on(signal, () => { forwarded = forwarded || signal; try {
-        child.kill('SIGTERM');
+        if (child.pid)
+            signalChild(child, 'SIGTERM');
     }
-    catch { /* already gone */ } });
+    catch (error) {
+        process.stderr.write(`${errorMessage(error)}\n`);
+    } });
 let ended = false;
 const done = (status, end) => {
     if (ended)
@@ -114,7 +119,7 @@ const done = (status, end) => {
     record({ event: 'world.service.exited', status, ...end, pid: child.pid, uptimeMs: Date.now() - started, ...(forwarded ? { stopRequested: forwarded } : {}) }, () => process.exit(status));
 };
 child.once('error', (error) => {
-    const message = String(error?.message || error);
+    const message = errorMessage(error);
     process.stderr.write(`${message}\n`);
     done(127, { code: null, signal: null, error: message });
 });

package/dist/src/signals.d.mts

@@ -0,0 +1 @@
+export function offSignal(signal: NodeJS.Signals, listener: (...args: never[]) => void): void;

package/dist/src/signals.d.ts

@@ -1 +1 @@
-export declare function offSignal(signal: NodeJS.Signals, listener: (...args: never[]) => void): void;
+export { offSignal } from './signals.mjs';

package/dist/src/signals.js

@@ -1,11 +1 @@
-// Removing a signal listener without removing the others. Under Bun (measured on 1.3.10),
-// `process.off('SIGINT', fn)` uninstalls the process's OS handler even while other listeners remain
-// (`listenerCount` still answers 1): the next SIGINT then takes the default action and kills the
-// process, so a caller's own handler (a harness's teardown) never runs. Re-registering the remaining
-// listeners reinstalls the handler. Node keeps it either way.
-export function offSignal(signal, listener) {
-    const rest = process.listeners(signal).filter((l) => l !== listener);
-    process.removeAllListeners(signal);
-    for (const l of rest)
-        process.on(signal, l);
-}
+export { offSignal } from './signals.mjs';

package/dist/src/signals.mjs

@@ -0,0 +1,10 @@
+// Removing a signal listener without removing the others. Under Bun (measured on 1.3.10),
+// `process.off('SIGINT', fn)` uninstalls the process's OS handler even while other listeners remain
+// (`listenerCount` still answers 1): the next SIGINT then takes the default action and kills the
+// process, so a caller's own handler (a harness's teardown) never runs. Re-registering the remaining
+// listeners reinstalls the handler. Node keeps it either way.
+export function offSignal(signal, listener) {
+  const rest = process.listeners(signal).filter((l) => l !== listener);
+  process.removeAllListeners(signal);
+  for (const l of rest) process.on(signal, l);
+}

package/dist/src/tail.d.ts

@@ -11,6 +11,8 @@ export type TailWorldOptions = {
      * status}` rows; world-core/src/serve.ts). Reads are otherwise invisible here: an
      * empty-catalog GET that 404s leaves no trace in an actions-only tail. */
     requests?: boolean;
+    /** Also read existing service process logs verbatim. These are vendor output, not shape-only journals. */
+    logs?: boolean;
     /** Poll interval while following (ledger appends are cross-process, so this polls rather than
      * fs.watch — watch descriptors can't see a file that doesn't exist yet). */
     pollMs?: number;

package/dist/src/tail.js

@@ -108,8 +108,10 @@ function entryInstant(entry) {
 }
 function formatEntry(entry, json) {
     if (json)
-        return JSON.stringify({ ...entry.record, service: entry.service });
+        return JSON.stringify({ ...entry.record, service: entry.service, ...(entry.source === 'logs' ? { source: 'logs' } : {}) });
     const { record } = entry;
+    if (entry.source === 'logs')
+        return `${entry.service} stdout ${record.message}`;
     if (entry.source === 'requests') {
         // a served request, not an action: `HH:MM:SS.mmm <service> <METHOD> <path> <status> in <ms>ms`, and —
         // when the caller presented one — which credential arrived, named and fingerprinted. The
@@ -181,6 +183,11 @@ export async function tailWorldActions(name, options = {}) {
                     }
                 }
             }
+            const log = instance.services[service]?.log;
+            if (options.logs && log) {
+                for (const line of readNewLines(log, offsets))
+                    entries.push({ service, record: { message: line }, source: 'logs' });
+            }
         }
         return entries.sort(byOccurredAt);
     };
@@ -192,7 +199,7 @@ export async function tailWorldActions(name, options = {}) {
     for (const service of services) {
         if (links.includes(service) && !instance.services[service])
             continue; // a link records requests, never actions
-        if (serviceLedgers(instance.dirs.data, service).length === 0) {
+        if (serviceLedgers(instance.dirs.data, service).length === 0 && !(options.logs && instance.services[service]?.log)) {
             notice(`World ${name}: service "${service}" has no action ledger yet${follow
                 ? ' — watching; drive the app (or a vendor SDK) through the world to record actions'
                 : '; drive the app (or a vendor SDK) through the world to record actions, then tail again'}`);

package/dist/src/tcp-port.js

@@ -18,19 +18,33 @@ export async function allocatePort(excluded = new Set()) {
     }
     throw new Error('Could not allocate a TCP port after 32 attempts');
 }
-function probePort() {
-    return new Promise((resolvePort, reject) => {
-        const server = createServer();
-        server.once('error', reject);
+async function probePort() {
+    const ipv4 = createServer();
+    const ipv6 = createServer();
+    try {
         // Match serveHttp's default scope; a loopback-only probe can miss a wildcard listener.
-        server.listen(0, '0.0.0.0', () => {
-            const address = server.address();
-            if (!address || typeof address === 'string') {
-                server.close(() => reject(new Error('Could not allocate a TCP port')));
-                return;
-            }
-            const port = address.port;
-            server.close((error) => error ? reject(error) : resolvePort(port));
+        await new Promise((resolve, reject) => {
+            ipv4.once('error', reject);
+            ipv4.listen(0, '0.0.0.0', resolve);
         });
-    });
+        const address = ipv4.address();
+        if (!address || typeof address === 'string')
+            throw new Error('Could not allocate a TCP port');
+        // Hold the IPv4 probe while checking the same port on IPv6, without a dual-stack bind.
+        await new Promise((resolve, reject) => {
+            ipv6.once('error', (error) => {
+                if (['EAFNOSUPPORT', 'EADDRNOTAVAIL', 'EPROTONOSUPPORT'].includes(error.code ?? ''))
+                    resolve();
+                else
+                    reject(error);
+            });
+            ipv6.listen({ port: address.port, host: '::', ipv6Only: true }, resolve);
+        });
+        return address.port;
+    }
+    finally {
+        await Promise.all([ipv6, ipv4].filter((server) => server.listening).map((server) => new Promise((resolve, reject) => {
+            server.close((error) => error ? reject(error) : resolve());
+        })));
+    }
 }

package/dist/src/temporal-backing.mjs

@@ -0,0 +1,28 @@
+import { signalChild } from './process-signal.mjs';
+import { errorMessage } from './error-message.mjs';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+
+if (!process.env.VOLTER_WORLD) throw new Error('Temporal backing must run as a World service');
+const port = Number(process.env.PORT);
+if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Missing allocated service port');
+const health = process.argv.includes('--health');
+const root = process.argv[process.argv.indexOf('--root') + 1];
+if (!health && (!process.argv.includes('--root') || !root)) throw new Error('Missing World service data directory');
+// Source: https://github.com/temporalio/cli/releases/tag/v1.9.1 (server start-dev --help).
+// SQLite pragma DSNs: https://github.com/temporalio/temporal/blob/v1.32.0/common/persistence/sql/sqlplugin/sqlite/plugin.go
+// The runtime creates --root; SQLite's file and sidecars stay in that owned directory.
+const args = health
+  ? ['--address', `127.0.0.1:${port}`, 'operator', 'cluster', 'health']
+  : ['server', 'start-dev', '--ip', '127.0.0.1', '--port', String(port), '--headless',
+    '--db-filename', join(root, 'temporal.sqlite'), '--sqlite-pragma', 'synchronous=FULL'];
+const child = spawn('temporal', args, { stdio: 'inherit', env: process.env });
+let stopping = false;
+const stop = () => {
+  stopping = true;
+  try { if (child.pid) signalChild(child, 'SIGTERM'); }
+  catch (error) { console.error(errorMessage(error)); process.exitCode = 1; }
+};
+process.once('SIGINT', stop); process.once('SIGTERM', stop);
+child.once('error', error => { console.error(errorMessage(error)); process.exitCode = 1; });
+child.once('exit', (code, signal) => { process.exitCode = stopping ? 0 : code ?? (signal ? 1 : 0); });

package/dist/src/up-cli.js

@@ -24,10 +24,15 @@ export async function upCommand(subject, rest, root) {
     // browser tab's image, comes up over its data instead of starting empty, as a fresh `up` does)
     const keepState = rest.includes('--keep-state');
     const instance = await superviseWorldUp(subject, { name, root, mode, envFile, forceEnvOutput: rest.includes('--force'), owner: ownerOption(rest), ...(isolation ? { isolation } : {}), ...(keepState ? { keepState: true } : {}) });
-    printReady(instance);
+    if (rest.includes('--json'))
+        process.stdout.write(JSON.stringify(instance, null, 2) + '\n');
+    else
+        printReady(instance);
 }
 export function printReady(instance) {
     process.stdout.write(`World ${instance.name} is ready (${instance.config})
+Instance: ${instance.instance}
+Created: ${instance.createdAt}
 
 Services:
 ${Object.values(instance.services).map((service) => `  ${service.id}: ${service.url ?? '(no listener — a World output)'}`).join('\n')}
@@ -43,11 +48,11 @@ GET <url>/twin; a scripted twin's GET <url>/twin/scenario lists handlers + misse
 Env:
   ${instance.envFile}
 
-Instance:
+Record:
   ${instance.dirs.instance}/instance.json
 
 Stop:
-  volter-world down ${instance.name}
+  volter-world down ${instance.name} --if-instance ${instance.instance}
 
 For a bounded job, use volter-world run ... -- <command> to tear down automatically on exit.
 Persistent up does not expire or infer that your sessions are idle.

package/dist/src/up-task-worker.js

@@ -1,6 +1,7 @@
 import { recordWorldLifecycleEvent } from "./lifecycle-record.js";
 import { upWorld } from "./runtime.js";
 import { loadWorldConfig } from "./configs.js";
+import { errorMessage } from "./error-message.js";
 const worldNameOf = (configId, root) => { try {
     return loadWorldConfig(configId, root).config.id;
 }
@@ -36,7 +37,7 @@ process.on('message', async (message) => {
         reply = { instance: await upWorld(request.configId, request.options, abort.signal) };
     }
     catch (error) {
-        reply = { error: error instanceof Error ? error.message : String(error) };
+        reply = { error: errorMessage(error) };
     }
     if (callerLost && 'instance' in reply) {
         try {

package/dist/src/websocket-relay.d.ts

@@ -1,3 +1,3 @@
-import type { ServeHttpOptions } from '@volter/world-core/runtime';
+import { type ServeHttpOptions } from '@volter/world-core/runtime';
 /** A message relay for the World's TLS fronts. Transport state is connection-local. */
 export declare function websocketRelay(targetFor: (request: Request) => string | undefined): NonNullable<ServeHttpOptions['upgrade']>;

package/dist/src/websocket-relay.js

@@ -1,3 +1,4 @@
+import { connectWebSocket } from '@volter/world-core/runtime';
 /** A message relay for the World's TLS fronts. Transport state is connection-local. */
 export function websocketRelay(targetFor) {
     const sessions = new WeakMap();
@@ -9,21 +10,33 @@ export function websocketRelay(targetFor) {
                 peer.close(1011, 'no twin for request');
                 return;
             }
-            const upstream = new WebSocket(target);
-            upstream.binaryType = 'arraybuffer';
-            const session = { upstream, pending: [] };
+            const headers = Object.fromEntries(request.headers);
+            const protocols = (headers['sec-websocket-protocol'] ?? '').split(',').map(p => p.trim()).filter(Boolean);
+            headers['x-volter-twin-original-host'] ??= new URL(request.url).host;
+            for (const name of ['host', 'connection', 'upgrade', 'sec-websocket-key', 'sec-websocket-version', 'sec-websocket-extensions', 'sec-websocket-protocol', 'proxy-connection'])
+                delete headers[name];
+            const session = { pending: [] };
             sessions.set(peer, session);
-            upstream.onopen = () => { for (const message of session.pending)
-                upstream.send(message); session.pending.length = 0; };
-            upstream.onmessage = event => { peer.send(typeof event.data === 'string' ? event.data : new Uint8Array(event.data)); };
-            upstream.onclose = event => { peer.close(event.code === 1006 ? 1011 : event.code, event.reason); };
-            upstream.onerror = () => { peer.close(1011, 'twin websocket error'); };
+            void connectWebSocket(target, headers, protocols).then(upstream => {
+                if (sessions.get(peer) !== session) {
+                    upstream.onerror = () => { };
+                    upstream.close();
+                    return;
+                }
+                session.upstream = upstream;
+                upstream.binaryType = 'arraybuffer';
+                upstream.onopen = () => { for (const message of session.pending)
+                    upstream.send(message); session.pending.length = 0; };
+                upstream.onmessage = event => { peer.send(typeof event.data === 'string' ? event.data : new Uint8Array(event.data)); };
+                upstream.onclose = event => { peer.close(event.code === 1006 ? 1011 : event.code, event.reason); };
+                upstream.onerror = () => { peer.close(1011, 'twin websocket error'); };
+            }).catch(() => peer.close(1011, 'twin websocket connection failed'));
         },
         message(peer, data) {
             const session = sessions.get(peer);
             if (!session)
                 return;
-            if (session.upstream.readyState === WebSocket.OPEN)
+            if (session.upstream?.readyState === WebSocket.OPEN)
                 session.upstream.send(data);
             else
                 session.pending.push(data);
@@ -33,7 +46,7 @@ export function websocketRelay(targetFor) {
             sessions.delete(peer);
             if (session) {
                 session.pending.length = 0;
-                session.upstream.close();
+                session.upstream?.close();
             }
         },
     };

package/dist/src/world-view.js

@@ -104,8 +104,8 @@ export async function serveWorldView(name, opts = {}) {
     base = world.served;
     worlds.set(world.served, world);
     const server = await serveHttp({
-        // a pushed blob (a release video) is one PUT: bodies up to 1 GiB, as `serve` takes them
-        hostname: host, port: opts.port ?? 0, maxRequestBodySize: 1024 * 1024 * 1024,
+        // The front retains its 1 GiB baseline and honors the served twins' declared caps.
+        hostname: host, port: opts.port ?? 0, maxRequestBodySize: world.maxRequestBodySize,
         // this front serves a World and its branches; each World's own twins journal their requests
         twinRequestJournal: false,
         async fetch(incoming) {