@volter/world-runtime 3.0.38 → 3.0.40

package/src/schema.ts

@@ -1,3 +1,4 @@
+import { errorMessage } from './error-message.ts';
 import { normalizeWorldNetwork, type WorldNetwork } from '@volter/world-core/network-policy';
 
 export type WorldServiceType = 'twin' | 'process' | 'external';
@@ -188,6 +189,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.
@@ -259,7 +262,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;
@@ -297,6 +300,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[];
@@ -392,6 +397,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;
@@ -406,6 +413,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>;
@@ -423,6 +434,14 @@ export type WorldInstance = {
   packFacts?: string[];
 };
 
+export function isEnvironmentName(value: unknown): value is string {
+  return typeof value === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+
+function environmentMap(value: unknown): boolean {
+  return record(value) && Object.entries(value).every(([name, entry]) => isEnvironmentName(name) && typeof entry === 'string');
+}
+
 function assertStringArray(value: unknown, what: string, path: string): asserts value is string[] {
   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}`);
@@ -433,7 +452,7 @@ function assertValidRegex(pattern: string, what: string, path: string): void {
   try {
     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}`);
   }
 }
 
@@ -530,7 +549,7 @@ function assertLegacyWorldConfig(value: unknown, path: string): WorldConfig {
   }
   if (config.network !== undefined) 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'))) throw new Error(`World config env must be a string→string object in ${path}`);
+  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}`);
   for (const key of ['actors', 'fixtures'] as const) if (config[key] !== undefined && !record(config[key])) throw new Error(`World config ${key} must be an object in ${path}`);
   if (config.bare !== undefined && (typeof config.bare !== 'object' || typeof (config.bare as { name?: unknown }).name !== 'string' || !/^[a-z0-9_-]+\/[a-z0-9_-]+$/i.test((config.bare as { name: string }).name))) {
@@ -568,7 +587,10 @@ function assertLegacyWorldConfig(value: unknown, path: string): WorldConfig {
   for (const service of config.services as Partial<WorldServiceConfig>[]) {
     if (!service || typeof service !== 'object') 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)) throw new Error(`Invalid service id "${service.id}" in ${path}`);
     if (ids.has(service.id)) throw new Error(`Duplicate service id "${service.id}" in ${path}`);
@@ -638,7 +660,7 @@ function assertLegacyWorldConfig(value: unknown, path: string): WorldConfig {
       }
     }
     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'))) throw new Error(`Service "${service.id}" env must be a string→string object in ${path}`);
+    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}`);
     }
@@ -743,7 +765,7 @@ function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
   const bindings = value.bindings === undefined ? {} : value.bindings;
   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;
@@ -795,6 +817,7 @@ function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
     ...(environment.values === undefined ? {} : { env: environment.values as Record<string, string> }),
     ...(execution.preload === undefined ? {} : { preload: execution.preload as string[] }),
     ...(execution.controlPlane === undefined ? {} : { controlPlane: execution.controlPlane as boolean }),
+    ...(execution.branchState === undefined ? {} : { branchState: execution.branchState as WorldServiceConfig['branchState'] }),
     ...(endpoint.port === undefined ? {} : { port: endpoint.port as number | 'auto' }),
     ...(endpoint.portReason === undefined ? {} : { portReason: endpoint.portReason as string }),
     ...(endpoint.ready === undefined ? {} : { ready: endpoint.ready as WorldServiceConfig['ready'] }),
@@ -829,7 +852,7 @@ function normalizeV2(value: Record<string, unknown>, path: string): WorldConfig
   const environment = runtime.environment ?? {};
   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'))) throw new Error(`runtime.environment.values must be a string→string object in ${path}`);
+  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}`);
   if (scenario.fixtures !== undefined && !record(scenario.fixtures)) throw new Error(`scenario.fixtures must be an object in ${path}`);
   const mode = serving.mode ?? 'app';
@@ -897,6 +920,7 @@ function serviceToV2(service: WorldServiceConfig): Record<string, unknown> {
     ...(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/src/served-world.ts

@@ -1,3 +1,4 @@
+import { errorMessage } from './error-message.ts';
 import { boardFrameKey, getActiveWorldStore, withHistoryLocks, captureHistory, historyAtInstant, historyDigest, historyEntries, historyLength, readHistoryView, worldPaths, type HistoryReference } 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
@@ -176,7 +177,7 @@ function configRefFor(worldRoot: string, name: string): string {
 /** A world mounted by a host. `token`/`readToken` read the CURRENT tokens (rotate changes them);
  *  `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 = { name: string; served: string; root: string; readonly token: string; readonly readToken: string; twins: () => string[]; rotate: () => { token: string; readToken: string }; handle: (request: Request) => Promise<Response>; /** a hostname this World's twins answer, as a browser reads it (siteOfHost) */ site: (request: Request, host: string) => Promise<Response>; /** WorldDoors.pagesPass */ pagesPass: (scope: 'read' | 'write', land: string, grant?: { who?: string; framer?: string; asker?: string }) => string | null; branchBoard: (frame?: string) => Promise<Response>; boot: (url: string) => Promise<void>; stop: () => Promise<void> };
+export type MountedWorld = { maxRequestBodySize: number; name: string; served: string; root: string; readonly token: string; readonly readToken: string; twins: () => string[]; rotate: () => { token: string; readToken: string }; handle: (request: Request) => Promise<Response>; /** a hostname this World's twins answer, as a browser reads it (siteOfHost) */ site: (request: Request, host: string) => Promise<Response>; /** WorldDoors.pagesPass */ pagesPass: (scope: 'read' | 'write', land: string, grant?: { who?: string; framer?: string; asker?: string }) => string | null; branchBoard: (frame?: string) => Promise<Response>; boot: (url: string) => Promise<void>; stop: () => Promise<void> };
 /** A browser session a World keeps: its scope, when it ends, and the person a pass named, when one did. */
 /** What a content-plane pass, and the session it opens, carry: its scope; the control session that asked (the content
  *  session ends with it; none when the World's token asked); the person; the console that frames it; and whether it
@@ -235,6 +236,7 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
   let stopping: Promise<void> | null = null;
   const mounted: MountedWorld = {
     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 }; },
@@ -303,9 +305,9 @@ export async function serveWorld(name: string, opts: { root?: string; port?: num
   // stale server on the port must never be mistaken for this one. Until the world is up the
   // doors answer 503.
   let consoleOrigin: string | null = 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); } catch (error) { await server.stop(true); throw error; }
   // the console, when it is installed beside the World, on an origin of its own (console-apart.ts)
@@ -330,7 +332,10 @@ export async function serveWorld(name: string, opts: { root?: string; port?: num
     opts.announce?.({ name: mounted.served, base: `${url}/${mounted.served}`, token: mounted.token, readToken: mounted.readToken, console: consoleUrl });
   } catch (error) {
     // Boot succeeded: this call owns the World, but cannot return its stop handle.
-    try { await stopAll(); } finally { await mounted.stop(); }
+    const errors: unknown[] = [error];
+    try { await stopAll(); } 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(); } };
@@ -581,6 +586,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);
@@ -598,7 +604,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' } });
@@ -729,7 +735,7 @@ export class WorldDoors {
     // a session a revoked key opened ends with it
     if (Object.values(this.sessions()).some((x) => x.key !== undefined && ids.has(x.key))) this.keepSessions(Object.fromEntries(Object.entries(this.sessions()).filter(([, x]) => x.key === undefined || !ids.has(x.key))));
     // 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: unknown) => { console.error(`${this.served}: branch ${k.branch} stays after its key was revoked: ${error instanceof Error ? error.message : String(error)}`); return false; });
+    for (const k of [...gone, ...also]) if (k.branch) await this.host.branches?.remove(k.branch).catch((error: unknown) => { console.error(`${this.served}: branch ${k.branch} stays after its key was revoked: ${errorMessage(error)}`); return false; });
     return [...ids];
   }
   private async keysDoor(request: Request, id: string | undefined, scope: 'read' | 'write', via: 'token' | 'key' | 'session' | null, session?: string): Promise<Response> {
@@ -1196,7 +1202,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 });
     }
   }
 
@@ -1370,7 +1376,7 @@ export class WorldDoors {
     const base = validateRemoteOrigin(origin);
     // opened for this link's origin only: a credential sealed for another destination, or for none, refuses
     let credential: Awaited<ReturnType<typeof openSealedAt>>;
-    try { credential = await openSealedAt(credentialPath(this.worldRoot, name), name, destinationOf(base.origin)); } catch (error) { return Response.json({ error: (error as Error).message }, { status: 409 }); }
+    try { credential = await openSealedAt(credentialPath(this.worldRoot, name), name, destinationOf(base.origin)); } catch (error) { return Response.json({ error: errorMessage(error) }, { status: 409 }); }
     if (credential === null) return Response.json({ error: `the ${name} link has no credential sealed` }, { status: 409 });
     const target = new URL(`${base.origin}/${rest}${url.search}`);
     if (target.origin !== base.origin) return Response.json({ error: 'the path left the link origin' }, { status: 400 });
@@ -1730,7 +1736,7 @@ export class WorldDoors {
     if (kind === 'links' && name && request.method === 'PUT') {
       if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name) || this.up().services[name]) return Response.json({ error: 'a link is named [a-z0-9_-] and is not a twin of this World' }, { status: 400 });
       const body = (await request.json()) as { origin?: string };
-      try { validateRemoteOrigin(body.origin ?? ''); } catch (error) { return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 400 }); }
+      try { validateRemoteOrigin(body.origin ?? ''); } catch (error) { 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 });
     }
@@ -1751,7 +1757,7 @@ export class WorldDoors {
         if (source.length > MAX_BODY) return Response.json({ error: 'too large' }, { status: 413 });
         const path = join(dir, `${name}.js`);
         store.write(path, source);
-        try { await loadCheck(path, name); } catch (error) { store.remove(path); return Response.json({ error: `not a check: ${error instanceof Error ? error.message : String(error)}` }, { status: 400 }); }
+        try { await loadCheck(path, name); } catch (error) { store.remove(path); return Response.json({ error: `not a check: ${errorMessage(error)}` }, { status: 400 }); }
         return Response.json({ check: name });
       }
       if (name && request.method === 'DELETE') { for (const ext of ['js', 'mjs', 'ts']) store.remove(join(dir, `${name}.${ext}`)); return Response.json({ removed: name }); }
@@ -1821,7 +1827,7 @@ export class WorldDoors {
         if (scope !== 'write') return Response.json({ error: 'the rules are changed with write access' }, { status: 403 });
         if (via === 'key') return Response.json({ error: 'a key changes no rules: a person sets them, or the World\'s token' }, { status: 403 });
         const body = (await request.json().catch(() => null)) as { changesets?: unknown } | null;
-        try { assertChangesetRules(body?.changesets, path); } catch (error) { return Response.json({ error: error instanceof Error ? error.message.replace(` in ${path}`, '') : String(error) }, { status: 400 }); }
+        try { assertChangesetRules(body?.changesets, path); } catch (error) { return Response.json({ error: errorMessage(error).replace(` in ${path}`, '') }, { status: 400 }); }
         const { config } = loadWorldConfig(path, this.worldRoot);
         const rules = body!.changesets as WorldChangesetRules;
         const next = { ...config, changesets: { ...(rules.approvals === undefined ? {} : { approvals: rules.approvals }), ...(rules.summary === undefined ? {} : { summary: rules.summary }) } };
@@ -2089,7 +2095,7 @@ export class WorldDoors {
       let known = false;
       try { known = listWorlds(this.worldRoot).some((w) => w.name === target); } catch { /* no local branches */ }
       if (!known) return Response.json({ error: `no branch ${target} in this World` }, { status: 404 });
-      try { await this.host.serveBranch(target); } catch (error) { return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 409 }); }
+      try { await this.host.serveBranch(target); } catch (error) { return Response.json({ error: errorMessage(error) }, { status: 409 }); }
       return Response.json({ world: this.served, checkedOut: target });
     }
     if (rest.length === 0 && request.method === 'POST') {
@@ -2134,7 +2140,7 @@ export class WorldDoors {
         return Response.json({ ...made, ...where }, { status: 201 });
       } 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') {
@@ -2416,7 +2422,7 @@ export class WorldDoors {
       const kept = ((): Changeset | null => { try { return JSON.parse(getActiveWorldStore().read(join(worldChangesetsDir(this.name, this.worldRoot), `${changeset.name}.json`)) ?? 'null') as Changeset | null; } catch { return null; } })();
       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 });
     }
   }
 }
@@ -2529,7 +2535,7 @@ export async function refreshSchedule(worldRoot: string, layout: WorldLayout, lo
 export async function scheduleRefreshes(name: string, worldRoot: string, instance: WorldInstance, log: (line: string) => void = (l) => process.stderr.write(`${l}\n`)): Promise<ReturnType<typeof setInterval>[]> {
   const timers: ReturnType<typeof setInterval>[] = [];
   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: unknown) => log(`${vendor}: refresh failed: ${e instanceof Error ? e.message : String(e)}`)); }, everyMs);
+    const timer = setInterval(() => { refreshTwin({ worldRoot, vendor, controlRoot, root, force: true }).then((r) => { if (!r.refreshed) log(`${vendor}: not refreshed: ${r.reason}`); }, (e: unknown) => log(`${vendor}: refresh failed: ${errorMessage(e)}`)); }, everyMs);
     timer.unref?.();
     timers.push(timer);
   }

package/src/service-recorder.ts

@@ -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.ts';
 import { spawn } from 'node:child_process';
 import { constants } from 'node:os';
 import { appendFileSync, closeSync, fstatSync, openSync, readSync, statSync, truncateSync, writeFileSync } from 'node:fs';
@@ -73,7 +75,7 @@ const watch = setInterval(() => {
 const statSize = (): number => { try { return logPath ? statSync(logPath).size : 0; } catch { return 0; } };
 
 let forwarded: string | null = null;
-for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'] as const) process.on(signal, () => { forwarded = forwarded || signal; try { child.kill('SIGTERM'); } catch { /* already gone */ } });
+for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'] as const) process.on(signal, () => { forwarded = forwarded || signal; try { if (child.pid) signalChild(child, 'SIGTERM'); } catch (error) { process.stderr.write(`${errorMessage(error)}\n`); } });
 let ended = false;
 const done = (status: number, end: Record<string, unknown>): void => {
   if (ended) return;
@@ -82,7 +84,7 @@ const done = (status: number, end: Record<string, unknown>): void => {
   record({ event: 'world.service.exited', status, ...end, pid: child.pid, uptimeMs: Date.now() - started, ...(forwarded ? { stopRequested: forwarded } : {}) }, () => process.exit(status));
 };
 child.once('error', (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/src/signals.d.mts

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

package/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/src/signals.ts

@@ -1,10 +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: NodeJS.Signals, listener: (...args: never[]) => void): void {
-  const rest = process.listeners(signal).filter((l) => l !== listener);
-  process.removeAllListeners(signal);
-  for (const l of rest) process.on(signal, l as (...args: unknown[]) => void);
-}
+export { offSignal } from './signals.mjs';

package/src/tail.ts

@@ -30,7 +30,7 @@ type TailRecord = Record<string, unknown> & {
   subject?: { type?: string; id?: string };
 };
 
-type TailEntry = { service: string; record: TailRecord; source: 'actions' | 'requests' };
+type TailEntry = { service: string; record: TailRecord; source: 'actions' | 'requests' | 'logs' };
 
 export type TailWorldOptions = {
   root?: string;
@@ -45,6 +45,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;
@@ -129,8 +131,9 @@ function entryInstant(entry: TailEntry): string | undefined {
 }
 
 function formatEntry(entry: TailEntry, json: boolean): string {
-  if (json) return JSON.stringify({ ...entry.record, service: entry.service });
+  if (json) 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
@@ -204,6 +207,10 @@ export async function tailWorldActions(name: string, options: TailWorldOptions =
           }
         }
       }
+      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);
   };
@@ -215,7 +222,7 @@ export async function tailWorldActions(name: string, options: TailWorldOptions =
   emit(collect());
   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/src/tcp-port.ts

@@ -17,19 +17,30 @@ export async function allocatePort(excluded: Set<number> = new Set()): Promise<n
   throw new Error('Could not allocate a TCP port after 32 attempts');
 }
 
-function probePort(): Promise<number> {
-  return new Promise((resolvePort, reject) => {
-    const server = createServer();
-    server.once('error', reject);
+async function probePort(): Promise<number> {
+  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<void>((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<void>((resolve, reject) => {
+      ipv6.once('error', (error: NodeJS.ErrnoException) => {
+        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<void>((resolve, reject) => {
+        server.close((error) => error ? reject(error) : resolve());
+      })));
+  }
 }

package/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/src/up-cli.ts

@@ -23,11 +23,14 @@ export async function upCommand(subject: string | undefined, rest: string[], roo
   // 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: Awaited<ReturnType<typeof upWorld>>): void {
   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 +46,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/src/up-task-worker.ts

@@ -1,6 +1,7 @@
 import { recordWorldLifecycleEvent } from './lifecycle-record.ts';
 import { upWorld } from './runtime.ts';
 import { loadWorldConfig } from './configs.ts';
+import { errorMessage } from './error-message.ts';
 
 const worldNameOf = (configId: string, root: string): string => { try { return loadWorldConfig(configId, root).config.id; } catch { return configId; } };
 import type { UpTaskReply, UpTaskRequest } from './up-task.ts';
@@ -25,7 +26,7 @@ process.on('message', async message => {
   started = true;
   let reply: UpTaskReply;
   try { reply = { instance: await upWorld(request.configId, request.options, abort.signal) }; }
-  catch (error) { reply = { error: error instanceof Error ? error.message : String(error) }; }
+  catch (error) { reply = { error: errorMessage(error) }; }
   if (callerLost && 'instance' in reply) {
     try { recordWorldLifecycleEvent(reply.instance.root, reply.instance.name, 'boot completed after its caller went away; the World is up'); } catch { /* the World is up regardless */ }
   }

package/src/websocket-relay.ts

@@ -1,32 +1,39 @@
-import type { ServeHttpOptions } from '@volter/world-core/runtime';
+import { connectWebSocket, type ServeHttpOptions } from '@volter/world-core/runtime';
 
 /** A message relay for the World's TLS fronts. Transport state is connection-local. */
 export function websocketRelay(targetFor: (request: Request) => string | undefined): NonNullable<ServeHttpOptions['upgrade']> {
   type Peer = Parameters<NonNullable<ServeHttpOptions['upgrade']>['open']>[0];
-  const sessions = new WeakMap<Peer, { upstream: WebSocket; pending: Array<string | Uint8Array> }>();
+  const sessions = new WeakMap<Peer, { upstream?: WebSocket; pending: Array<string | Uint8Array> }>();
   return {
     accepts: request => targetFor(request) !== undefined,
     open(peer, request) {
       const target = targetFor(request);
       if (!target) { peer.close(1011, 'no twin for request'); return; }
-      const upstream = new WebSocket(target);
-      upstream.binaryType = 'arraybuffer';
-      const session = { upstream, pending: [] as Array<string | Uint8Array> };
+      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: { upstream?: WebSocket; pending: Array<string | Uint8Array> } = { 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 as ArrayBuffer)); };
-      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 as ArrayBuffer)); };
+        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) session.upstream.send(data); else session.pending.push(data);
+      if (session.upstream?.readyState === WebSocket.OPEN) session.upstream.send(data); else session.pending.push(data);
     },
     close(peer) {
       const session = sessions.get(peer);
       sessions.delete(peer);
-      if (session) { session.pending.length = 0; session.upstream.close(); }
+      if (session) { session.pending.length = 0; session.upstream?.close(); }
     },
   };
 }

package/src/world-view.ts

@@ -94,8 +94,8 @@ export async function serveWorldView(name: string, opts: { /** the person signed
   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) {