@volter/world-runtime 2.0.55 → 3.0.1

package/dist/src/runtime.js

@@ -4,6 +4,7 @@ import { parallelStartup } from "./startup.js";
 import { waitForHostReady } from "./host-ready.js";
 import { assertWorldStateRemovable, removeWorldState } from "./ancestry.js";
 import { packCli, packEntry } from "./catalog.js";
+import { vendorOfPackModule } from '@volter/world-core/runtime';
 import { spawn, spawnSync } from 'node:child_process';
 import { get as httpGet } from 'node:http';
 import { siblingScript } from "./sibling.js";
@@ -21,14 +22,15 @@ import { packFacts } from "./pack-facts.js";
 import { infraConnections, parseInfraDefinition } from "./pglite-backing.js";
 import { describeServiceEnd, readServiceEnd, serviceOutput } from "./service-exit.js";
 import { Socket } from 'node:net';
-import { getActiveWorldStore, withFileLock, stateDirName, PROTOCOL_VERSION, PROTOCOL_MAJOR, WORLD_BOOT_PATH, WORLD_DATA_ENV, WORLD_ENV_NAMES_ENV } from '@volter/world-core';
+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";
 import { createWorldNetworkPolicy, WORLD_NETWORK_POLICY_ENV } from '@volter/world-core/network-policy';
-import { resolveServicePackage } from "./catalog.js";
+import { overlayPackFactsFile, resolveServicePackage } from "./catalog.js";
 import { fakeEnvValue } from "./fixture-env.js";
-import { MINT_ENV } from "./schema.js";
+import { APP_URL_ENV, ISSUE_ENV_PREFIX, MINT_ENV } from "./schema.js";
+import { readAppUrl } from "./app-url.js";
 import { inertInjectEnvWarnings } from "./inject-map.js";
-import { activeVendorMap, ensureCa, opensslAvailable, proxyEnvFor, startRedirectProxy, tearDownCa } from "./redirect-proxy.js";
+import { activeVendorMap, ensureCa, hostHasRawEgress, opensslAvailable, proxyEnvFor, startRedirectProxy, tearDownCa } from "./redirect-proxy.js";
 import { CaTrustError, sessionTrustEnv } from "./ca-trust.js";
 import { checkedOwner, CONSUMER_HEARTBEAT_MS, createConsumer, refreshConsumer, releaseConsumer, removeConsumerRecord, worldConsumers } from "./consumers.js";
 import { assertLifecycleStartable, beginWorldLifecycle, handoffWorldLifecycle, recordWorldLifecycleEvent, releaseWorldLifecycle, retainWorldLifecycleForCleanup, hasWorldLifecycle, isWorldLifecycleRunning, lifecycleLogPath, releaseAbandonedWorldLifecycle } from "./lifecycle-record.js";
@@ -150,6 +152,7 @@ async function confirmOwnPort(port, boot, ended, twin, what, log, early = false,
 function worldBootOf(port, abort) {
     return new Promise((resolveBoot) => {
         let request;
+        // biome-ignore lint/style/useConst: `finish` reads this, and an already-aborted signal calls `finish` before the timer is armed, where a const would still be in its temporal dead zone
         let deadline;
         let settled = false;
         let responseStarted = false;
@@ -463,6 +466,8 @@ function shellQuote(value) {
 }
 function envFileContents(env) {
     return `${Object.entries(env)
+        // the application's own origin is resolved where a command attaches, never written as the literal marker
+        .filter(([, value]) => value !== APP_URL_ENV)
         .sort(([a], [b]) => a.localeCompare(b))
         .map(([key, value]) => `export ${key}=${shellQuote(value)}`)
         .join('\n')}\n`;
@@ -525,6 +530,30 @@ export function withoutVaultSignIn(env) {
     return out;
 }
 /** The process's environment as the world admits it: what `stripEnv` names stays outside. */
+/**
+ * The network policy a World publishes: its own, under the ceiling of the World it was started inside (docs/contributing/
+ * architecture.md, "Worlds within a World"). A World started by a process of a World whose egress is closed or listed
+ * (the parent's published policy) reaches at most what the parent reaches: its egress is its own list intersected with
+ * the parent's, or the parent's when it declares none. Routing needs no rule: the parent's twin addresses pass through,
+ * so a vendor the inner World does not twin reaches the parent's twin of it.
+ */
+function networkOf(name, own, parentEnv = process.env) {
+    const serialized = parentEnv[WORLD_NETWORK_POLICY_ENV];
+    let ceiling;
+    if (serialized !== undefined) {
+        // an unreadable parent policy closes the child entirely, as it closes the parent
+        try {
+            ceiling = JSON.parse(serialized).egress ?? [];
+        }
+        catch {
+            ceiling = [];
+        }
+    }
+    if (own === undefined && ceiling === undefined)
+        return undefined;
+    const egress = own === undefined ? ceiling : ceiling === undefined ? own.egress : own.egress.filter((origin) => ceiling.includes(origin));
+    return { [WORLD_NETWORK_POLICY_ENV]: JSON.stringify(createWorldNetworkPolicy(name, { egress: [...egress] })) };
+}
 export function admittedEnv(strip, env = process.env) {
     const out = {};
     const rules = (strip ?? []).map((s) => (s.endsWith('*') ? { prefix: s.slice(0, -1) } : { name: s }));
@@ -542,7 +571,24 @@ export function admittedEnv(strip, env = process.env) {
     return withoutVaultSignIn(out);
 }
 // The strip list of a running world, for `env`/`attach`: its config is the one the instance recorded.
+/** The names a twin of this World was to issue and did not (its door failed): kept out of every command's env, so a
+ *  caller's own value (a real key in their shell) never stands in for the credential the World meant to issue. */
+export const UNISSUED_ENV = 'VOLTER_WORLD_UNISSUED';
+function unissuedOf(instanceEnv) {
+    try {
+        const names = JSON.parse(instanceEnv[UNISSUED_ENV] ?? '[]');
+        return Array.isArray(names) ? names.filter((n) => typeof n === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
 function stripEnvOf(instanceEnv) {
+    const unissued = unissuedOf(instanceEnv);
+    const rules = savedStripEnvOf(instanceEnv);
+    return unissued.length === 0 ? rules : [...(rules ?? []), ...unissued];
+}
+function savedStripEnvOf(instanceEnv) {
     // Freeze the admission policy for the instance; editing/removing its source cannot widen it.
     const saved = instanceEnv.VOLTER_WORLD_STRIP_ENV;
     if (saved !== undefined) {
@@ -578,7 +624,19 @@ function serviceProcessEnv(config, service, worldEnv, port) {
         for (const key of CONTROL_PLANE_EGRESS_ENV)
             delete env[key];
     }
-    return { ...env, ...(service.env ?? {}) };
+    dropUnissued(env);
+    const out = { ...env, ...(service.env ?? {}) };
+    // the application's own origin: the World's own application service is reached where it listens (the URL
+    // `volter-world app-url` answers for it); any other service never reads it, and a command resolves it at attach
+    for (const [key, value] of Object.entries(out)) {
+        if (value !== APP_URL_ENV)
+            continue;
+        if (service.id === 'app')
+            out[key] = `http://127.0.0.1:${port}`;
+        else
+            delete out[key];
+    }
+    return out;
 }
 async function waitForTcp(port, timeoutMs = 15_000, abort) {
     const started = Date.now();
@@ -659,8 +717,11 @@ function writeOwnedPids(root, name, pids, fresh = []) {
 function identityPath(root, name) {
     return join(instanceDir(root, name), 'pids.identity');
 }
-/** Each running pid's start time (one call); a pid with no process is absent. Printed in one fixed zone and locale, so
- *  the same process reads the same whoever asks (`lstart` otherwise follows the caller's TZ and language). */
+/** Each running pid's start time; a pid with no process is absent. Printed in one fixed zone and locale, so the same
+ *  process reads the same whoever asks (`lstart` otherwise follows the caller's TZ and language). One `ps` per pid:
+ *  given two or more pids, macOS `ps -p` walks the whole process table (measured 2026-09-30 on Darwin 25.4, 944
+ *  processes: `/usr/bin/time -p ps -o pid=,lstart= -p 1,$$` 0.14–0.35 s, `… -p 1` 0.00 s), which every `status`
+ *  paid. */
 function processStarts(pids) {
     const starts = new Map();
     if (!pids.length || process.platform === 'win32')
@@ -676,11 +737,12 @@ function processStarts(pids) {
         }
         return starts;
     }
-    const result = spawnSync('ps', ['-o', 'pid=,lstart=', '-p', pids.join(',')], { windowsHide: true, encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', env: { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' } });
-    for (const line of (result.stdout ?? '').split('\n')) {
-        const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(line);
-        if (match)
-            starts.set(Number(match[1]), match[2]);
+    const env = { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' };
+    for (const pid of pids) {
+        const result = spawnSync('ps', ['-o', 'pid=,lstart=', '-p', String(pid)], { windowsHide: true, encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', env });
+        const match = /^\s*(\d+)\s+(.+?)\s*$/.exec((result.stdout ?? '').trim());
+        if (match && Number(match[1]) === pid)
+            starts.set(pid, match[2]);
     }
     return starts;
 }
@@ -1108,7 +1170,7 @@ async function startService(config, service, worldEnv, paths, allocatedPorts, bo
     const port = service.port === undefined || service.port === 'auto' ? await allocatePort(allocatedPorts) : service.port;
     const serviceDataDir = join(paths.data, service.id);
     mkdirSync(serviceDataDir, { recursive: true });
-    // R17 — the lockfile holds on the spawn path too: a twin that runs `packages/twin/<vendor>/src/cli.ts`
+    // R17 — the lockfile holds on the spawn path too: a twin that runs a checkout's CLI
     // is checked against its pin and its protocol standing before it is spawned.
     const spawnedModule = (service.type ?? 'twin') === 'twin' ? spawnedTwinModule(service, paths.root) : undefined;
     const mounted = spawnedModule !== undefined ? lockfileCheck(service, spawnedModule) : {};
@@ -1118,6 +1180,10 @@ async function startService(config, service, worldEnv, paths, allocatedPorts, bo
         if (binding !== undefined)
             args.push(binding.arg, binding.url);
     }
+    const sides = (service.type ?? 'twin') === 'twin' ? await sidePortsFor(vendorOfModule(spawnedModule, service.id), args, allocatedPorts) : [];
+    for (const side of sides)
+        if (!side.pinned)
+            args.push(side.flag, String(side.port));
     if (service.portArg !== false)
         args.push(service.portArg ?? '--port', String(port));
     if (service.rootArg !== false)
@@ -1199,6 +1265,7 @@ async function startService(config, service, worldEnv, paths, allocatedPorts, bo
         command: [service.command, ...args],
         port,
         url,
+        ...sidesRecord(sides),
         ...(mounted.version !== undefined ? { resolvedVersion: mounted.version } : {}),
         ...(mounted.protocol !== undefined ? { protocol: mounted.protocol } : {}),
         pid: child.pid ?? 0,
@@ -1235,43 +1302,53 @@ function mountedPackage(modulePath, serviceId) {
             break;
         dir = up;
     }
-    const m = /\/packages\/twin\/([^/]+)\//.exec(modulePath) ?? /@volter\/twin-([^/]+)\//.exec(modulePath);
-    const vendor = m?.[1] ?? serviceId;
+    const vendor = vendorOfPackModule(modulePath) ?? serviceId;
     try {
         const facts = packFacts()[vendor];
         if (facts?.protocol)
-            out.protocol = facts.protocol;
+            out.protocol = { ...protocolStanding(facts.protocol.declared), declared: facts.protocol.declared };
     }
     catch { /* no artifact: the standing is unknown, not refused */ }
     return out;
 }
 /** R17 + R16 at boot, on BOTH paths (the colocated host and the spawned process): the mounted
- *  package must satisfy the pin, its protocol standing must not be refused, and a deprecated one
- *  is said aloud. Returns what to stamp on the instance record. */
+ *  package must satisfy its pin and its recorded declaration must match the kernel. Registration and the host
+ *  check the loaded descriptor again before a factory runs; compiled facts are only preflight evidence. */
 function lockfileCheck(service, modulePath) {
     const mounted = mountedPackage(modulePath, service.id);
     if (service.version !== undefined) {
         if (mounted.version === undefined)
             throw new Error(`Twin "${service.id}" pins version ${service.version} but no package.json was found above ${modulePath} — nothing to hold the pin against`);
         if (!versionSatisfies(mounted.version, service.version))
-            throw new Error(`Twin "${service.id}" pins version ${service.version} and the mounted package is ${mounted.version} (${mounted.packagePath}) — re-pin the world config, or mount the version it names (volter-world outdated lists both)`);
+            throw new Error(`Twin "${service.id}" pins version ${service.version} and the mounted package is ${mounted.version} (${mounted.packagePath}) — install the version the World names (npm install -D @volter/twin-${service.id}@${service.version}, as a committed lockfile does), or move the pin to it: "version" on the service in .volter/world.json (volter-world outdated lists both)`);
     }
     if (mounted.protocol?.standing === 'refused')
-        throw new Error(`Twin "${service.id}" targets protocol major ${mounted.protocol.major}; this platform serves ${PROTOCOL_VERSION} and the previous major only (runtime contract R16)`);
-    if (mounted.protocol?.standing === 'deprecated')
-        process.stderr.write(`volter-world: twin "${service.id}" targets protocol major ${mounted.protocol.major}, one behind this platform's ${PROTOCOL_VERSION} — served for this cycle under deprecation (R16)\n`);
+        throw new Error(`Twin "${service.id}" targets protocol major ${mounted.protocol.major}; this platform serves ${PROTOCOL_VERSION} only (runtime contract R16)`);
     return mounted;
 }
-/** The module a spawned twin runs from: its first arg under packages/twin/<vendor>/ or an installed
+/** The module a spawned twin runs from: its first arg in a vendor package, from a checkout or an installed
  *  @volter/twin-<vendor>/ package, resolved. */
 function spawnedTwinModule(service, root) {
-    const first = (service.args ?? []).find((a) => /packages\/twin\/[^/]+\//.test(a) || /@volter\/twin-[^/]+\//.test(a));
+    const first = (service.args ?? []).find((a) => !a.startsWith('-') && /\.(?:[cm]?js|tsx?)$/.test(a) && vendorOfPackModule(resolve(root, a)) !== undefined);
     return first === undefined ? undefined : (first.startsWith('/') ? first : resolve(root, first));
 }
-/** The vendor a twin module belongs to (`packages/twin/<vendor>/…` or `@volter/twin-<vendor>/…`), else the service id. */
+/** A twin's side ports (TwinPack.sidePorts), each allocated before boot unless the service's own args already name it
+ *  (a World that pins the port keeps its pin), with the URL the World records for it. */
+async function sidePortsFor(vendor, args, allocatedPorts) {
+    const declared = packFacts()[vendor]?.sidePorts ?? [];
+    const out = [];
+    for (const side of declared) {
+        const at = args.indexOf(side.flag);
+        const given = at >= 0 ? Number(args[at + 1]) : Number.NaN;
+        const pinned = Number.isInteger(given) && given > 0;
+        const port = pinned ? given : await allocatePort(allocatedPorts);
+        out.push({ name: side.name, option: side.option, flag: side.flag, port, pinned, url: `http://127.0.0.1:${port}${side.path ?? ''}` });
+    }
+    return out;
+}
+const sidesRecord = (sides) => sides.length ? { sides: Object.fromEntries(sides.map((side) => [side.name, { port: side.port, url: side.url }])) } : {};
 function vendorOfModule(modulePath, serviceId) {
-    const m = modulePath === undefined ? null : (/\/packages\/twin\/([^/]+)\//.exec(modulePath) ?? /@volter\/twin-([^/]+)(\/|$)/.exec(modulePath));
-    return m?.[1] ?? serviceId;
+    return (modulePath === undefined ? undefined : vendorOfPackModule(modulePath)) ?? serviceId;
 }
 /**
  * THE MANAGED-DATABASE BINDING (architecture.md, managed infrastructure: the data plane's declared exception): for a
@@ -1295,12 +1372,107 @@ export function managedDatabaseFor(vendor, configPath, env) {
     const url = Object.keys(connections).sort().map((name) => connections[name])[0];
     return url === undefined ? undefined : { arg: declared.arg, url };
 }
+/** The facts files the World's installed packs carry (a released pack's `generated/pack-facts.json`), which the kernel's
+ *  pack-facts loader reads through the instance file. */
+function packFactsFiles(config, root) {
+    const files = [];
+    for (const service of config.services) {
+        if (service.package === undefined)
+            continue;
+        let dir;
+        try {
+            dir = resolveServicePackage(root, service.package);
+        }
+        catch {
+            continue;
+        }
+        const file = join(dir, 'generated', 'pack-facts.json');
+        if (existsSync(file))
+            files.push(file);
+    }
+    return [...new Set(files)].sort();
+}
 /**
  * The config as the runtime boots it (docs/concepts/worlds.md#the-config-and-the-running-world): a service
  * naming a `package` gets its entry and colocate module resolved from the world root NOW, by
  * node's own walk, and a `$mint` env value becomes a freshly minted throwaway credential for this
  * boot. Everything downstream sees ordinary command/args/module/env.
  */
+/** An env name whose value is still `$issue:<service>` is not set yet: no twin, host or application is handed the
+ *  marker. */
+function dropUnissued(env) {
+    for (const [key, value] of Object.entries(env))
+        if (value.startsWith(ISSUE_ENV_PREFIX))
+            delete env[key];
+}
+/** The names the World's twins issue (`$issue:<service>` in its config), taken out of the boot env until issued. */
+function takeIssued(env) {
+    const pending = new Map();
+    for (const [key, value] of Object.entries(env))
+        if (value.startsWith(ISSUE_ENV_PREFIX))
+            pending.set(key, value.slice(ISSUE_ENV_PREFIX.length));
+    dropUnissued(env);
+    return pending;
+}
+/** How long a twin's credential door has to answer before its names are left unset (a door answers from the twin's
+ *  own store, in milliseconds; this bounds a hung twin, not a slow one). */
+const ISSUE_TIMEOUT_MS = 15_000;
+/** A twin's issued credential (its `issues`, copied from its pack's credentialDoor by init): once it is up, the door is
+ *  asked for one and each pending name of that service is set to it. A twin that answers no credential, or has no
+ *  door, leaves the names unset and says so, rather than handing the application a fixture the twin would refuse. */
+async function issueCredentials(service, started, env, pending, unissued) {
+    const wanted = [...pending].filter(([, id]) => id === service.id).map(([name]) => name);
+    if (wanted.length === 0)
+        return;
+    for (const name of wanted)
+        pending.delete(name);
+    // the pack's door as it stands now (a door the pack fixed since the World was made reaches it), else the saved copy
+    let door = service.issues;
+    try {
+        door = packFacts()[service.id]?.credentialDoor ?? door;
+    }
+    catch { /* no artifact: the saved copy */ }
+    try {
+        if (!door)
+            throw new Error('its service names no credential door');
+        if (!started.url)
+            throw new Error('it has no URL to ask');
+        const res = await fetch(new URL(door.path, started.url), { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(door.body), signal: AbortSignal.timeout(ISSUE_TIMEOUT_MS) });
+        if (!res.ok)
+            throw new Error(`answered ${res.status}`);
+        const answer = (await res.json());
+        for (const name of wanted) {
+            const spec = door.fill[name] ?? '';
+            // `file:<field>`: a credential the application reads from a file (Google's GOOGLE_APPLICATION_CREDENTIALS), written
+            // beside the World's instance file, the name set to its path
+            const field = spec.startsWith('file:') ? spec.slice('file:'.length) : spec;
+            const value = answer[field];
+            if (spec.startsWith('file:')) {
+                if (value === undefined || value === null)
+                    throw new Error(`answered no ${field}`);
+                // beside the World's instance and nowhere else: a credential file in the application's checkout could be committed
+                if (!env.VOLTER_WORLD_INSTANCE)
+                    throw new Error(`cannot write ${name}'s credential file: the World's instance is unknown`);
+                const dir = join(dirname(env.VOLTER_WORLD_INSTANCE), 'credentials');
+                mkdirSync(dir, { recursive: true, mode: 0o700 });
+                const path = join(dir, `${service.id}-${name.toLowerCase()}.json`);
+                writeFileSync(path, typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+                env[name] = path;
+                continue;
+            }
+            if (typeof value !== 'string')
+                throw new Error(`answered no ${field}`);
+            env[name] = value;
+        }
+    }
+    catch (error) {
+        process.stderr.write(`volter-world: ${service.id} did not issue ${wanted.join(', ')} (${error instanceof Error ? error.message : String(error)}); left unset\n`);
+        for (const name of wanted) {
+            delete env[name];
+            unissued.add(name);
+        }
+    }
+}
 function materializeConfig(config, root) {
     const services = config.services.map((service) => {
         if (service.package === undefined)
@@ -1367,8 +1539,9 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
         const mounted = lockfileCheck(service, module);
         const scenario = service.colocate.scenarioPath;
         const binding = managedDatabaseFor(vendorOfModule(module, service.id), worldEnv.VOLTER_WORLD_CONFIG, config.env ?? {});
-        args.push('--spec', [service.id, module, service.colocate.export, String(port), serviceDataDir, ...(scenario ? [`scenario=${scenario.startsWith('/') ? scenario : resolve(paths.root, scenario)}`] : []), ...(binding !== undefined ? [`database=${binding.url}`] : [])].join('|'));
-        allocated.push({ service, port, mounted });
+        const sides = await sidePortsFor(vendorOfModule(module, service.id), [], allocatedPorts);
+        args.push('--spec', [service.id, module, service.colocate.export, String(port), serviceDataDir, ...(scenario ? [`scenario=${scenario.startsWith('/') ? scenario : resolve(paths.root, scenario)}`] : []), ...(binding !== undefined ? [`database=${binding.url}`] : []), ...sides.map((side) => `side.${side.option}=${side.port}`)].join('|'));
+        allocated.push({ service, port, mounted, sides });
     }
     const log = join(paths.logs, 'host.log');
     // The host is world infrastructure, not an app process — same egress hygiene as controlPlane
@@ -1376,6 +1549,11 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
     const env = { ...admittedEnv(config.stripEnv), ...(config.env ?? {}), ...worldEnv };
     for (const key of CONTROL_PLANE_EGRESS_ENV)
         delete env[key];
+    // the twins never read the application's own origin, nor a credential not yet issued
+    for (const [key, value] of Object.entries(env))
+        if (value === APP_URL_ENV)
+            delete env[key];
+    dropUnissued(env);
     env.VOLTER_WORLD_BOOT_ID = boot.bootId;
     // Under the same exit recorder as a process service, so the host's end (and every twin it holds) is in host.log.
     const { child, ended } = spawnRecorded('host', process.execPath, args, paths.root, env, log);
@@ -1390,7 +1568,7 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
     const host = '127.0.0.1';
     // Every twin's address is known once its port is allocated: the records and
     // the environment they inject exist before the host reports its starts.
-    const services = allocated.map(({ service, port, mounted }) => {
+    const services = allocated.map(({ service, port, mounted, sides }) => {
         const url = `http://${host}:${port}`;
         return {
             id: service.id,
@@ -1398,6 +1576,7 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
             command,
             port,
             url,
+            ...sidesRecord(sides),
             ...(mounted.version !== undefined ? { resolvedVersion: mounted.version } : {}),
             ...(mounted.protocol !== undefined ? { protocol: mounted.protocol } : {}),
             pid: child.pid ?? 0,
@@ -1411,7 +1590,12 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
     });
     const ready = (async () => {
         const hostTimeoutMs = allocated.reduce((timeout, { service }) => Math.max(timeout, typeof service.ready === 'object' ? service.ready.timeoutMs ?? 15_000 : 15_000), 15_000);
-        await untilReadyOrEnded((abort) => waitForHostReady(readyFile, boot.bootId, new Map(allocated.map(({ service, port }) => [service.id, port])), hostTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
+        await untilReadyOrEnded((abort) => waitForHostReady(readyFile, boot.bootId, new Map(allocated.map(({ service, port }) => [service.id, port])), hostTimeoutMs, abort, () => { try {
+            return statSync(log).size;
+        }
+        catch {
+            return 0;
+        } }), ended, boot, 'the co-located host', log).catch((error) => {
             if (undeadPids([child.pid]).length)
                 recordWorldStop([log], 'world.service.stop', 'up (host startup incomplete)', 'SIGTERM');
             try {
@@ -1435,7 +1619,7 @@ 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-0008). A port that
+        // 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');
         await parallelStartup(allocated, async ({ service, port }) => {
@@ -1463,6 +1647,12 @@ export async function upWorld(configId, options = {}, abort) {
     abort?.throwIfAborted();
     const root = resolve(options.root ?? process.cwd());
     const found = loadWorldConfig(configId, root);
+    // the facts of the World's installed packs, over the kernel's, for this process and (through the instance file) its own
+    const packFactsPaths = packFactsFiles(found.config, root);
+    for (const file of packFactsPaths)
+        overlayPackFactsFile(file);
+    // and this process's injector host rules, which `up`'s inert-injectEnv warning reads, know them too
+    createRequire(import.meta.url)('@volter/world-core/pack-facts').extendPackFacts(packFactsPaths);
     const loaded = { path: found.path, config: materializeConfig(found.config, root) };
     const name = options.name ?? loaded.config.id;
     const mode = options.mode ?? 'local';
@@ -1510,10 +1700,22 @@ export async function upWorld(configId, options = {}, abort) {
     const envFile = resolve(root, options.envFile ?? join(instance, 'world.env'));
     const instanceFile = join(instance, 'instance.json');
     let carriedOrigin;
-    const priorOutputInstance = existsSync(instanceFile) ? JSON.parse(readFileSync(instanceFile, 'utf8')) : undefined;
-    const priorOutput = priorOutputInstance?.name === name && resolve(priorOutputInstance.root) === root
-        ? { path: resolve(priorOutputInstance.envFile), contents: envFileContents(priorOutputInstance.env) } : undefined;
-    const envOutputClaim = claimEnvOutput(envFile, join(root, stateDirName(), 'env-output-backups'), priorOutput, options.forceEnvOutput);
+    // the outputs this root's Worlds published: a branch and its base share the app's env file (whichever is current
+    // writes it), so a file any of them last wrote is the World's own, never a custody file
+    const siblings = existsSync(worldBaseDir(root)) ? readdirSync(worldBaseDir(root)).filter((world) => world !== name && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(world)) : [];
+    const priorOutputs = [name, ...siblings].flatMap((world) => {
+        const file = world === name ? instanceFile : join(instanceDir(root, world), 'instance.json');
+        if (!existsSync(file))
+            return [];
+        try {
+            const prior = JSON.parse(readFileSync(file, 'utf8'));
+            return prior?.name === world && resolve(prior.root) === root ? [{ path: resolve(prior.envFile), contents: envFileContents(prior.env) }] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+    const envOutputClaim = claimEnvOutput(envFile, join(root, stateDirName(), 'env-output-backups'), priorOutputs, options.forceEnvOutput);
     if (loaded.config.resources)
         process.stderr.write(`World "${name}": config resources is deprecated; declarations are not reservations or enforced limits. Configure limits in the execution backend.\n`);
     checkedOwner(options.owner);
@@ -1649,7 +1851,7 @@ export async function upWorld(configId, options = {}, abort) {
             // the world ref the dormant attach entry (`import '@volter/world-core/attach'`) arms the injector
             // on — what a Bun process, which ignores NODE_OPTIONS, reads to reach the twins inside `run`
             VOLTER_WORLD: name,
-            ...(loaded.config.network ? { [WORLD_NETWORK_POLICY_ENV]: JSON.stringify(createWorldNetworkPolicy(name, mode === 'sealed' ? { egress: [] } : loaded.config.network)) } : {}),
+            ...(networkOf(name, mode === 'sealed' ? { egress: [] } : loaded.config.network) ?? {}),
             VOLTER_WORLD_MODE: mode,
             VOLTER_WORLD_CONFIG: loaded.path,
             VOLTER_WORLD_INSTANCE: instanceFile,
@@ -1670,6 +1872,8 @@ export async function upWorld(configId, options = {}, abort) {
         };
         env.NO_PROXY = `127.0.0.1,localhost${env.NO_PROXY || inheritedEnv.NO_PROXY ? `,${env.NO_PROXY ?? inheritedEnv.NO_PROXY}` : ''}`;
         env.no_proxy = `127.0.0.1,localhost${env.no_proxy || inheritedEnv.no_proxy ? `,${env.no_proxy ?? inheritedEnv.no_proxy}` : ''}`;
+        const issuing = takeIssued(env);
+        const unissued = new Set();
         writeProxyEnv(root, name, env);
         const worldInstance = {
             name, config: loaded.config.id, configPath: loaded.path, root, createdAt, mode,
@@ -1678,6 +1882,7 @@ export async function upWorld(configId, options = {}, abort) {
             ...(loaded.config.actors ? { actors: loaded.config.actors } : {}),
             ...(loaded.config.fixtures ? { fixtures: loaded.config.fixtures } : {}),
             lifecycle: { owner: options.owner, log: lifecycleLogPath(root, name) },
+            ...(packFactsPaths.length ? { packFacts: packFactsPaths } : {}),
             ...(carriedOrigin ? { origin: carriedOrigin } : {}),
         };
         saveWorldInstance(worldInstance);
@@ -1711,7 +1916,8 @@ export async function upWorld(configId, options = {}, abort) {
             // The co-located host's twins are known by address once their ports are
             // allocated. A twin serves and calls no other service while it starts,
             // so a later twin declaration starts beside the host's startup; any other
-            // service waits until every earlier one is ready, as declared (ADR-0009).
+            // service waits until every earlier one is ready, as declared (ADR 0015).
+            // A co-located twin's issued credentials are asked of it once the host is ready: it answers no request before.
             let colocatedReady;
             if (isolation !== 'process') {
                 const colocated = loaded.config.services.filter((service) => service.colocate && service.type !== 'external');
@@ -1720,7 +1926,15 @@ export async function upWorld(configId, options = {}, abort) {
                     services[started.id] = started;
                     Object.assign(env, started.env);
                 }
-                colocatedReady = host.ready;
+                colocatedReady = async () => {
+                    await host.ready;
+                    for (const started of host.services) {
+                        const declared = colocated.find((s) => s.id === started.id);
+                        if (declared)
+                            await issueCredentials(declared, started, env, issuing, unissued);
+                    }
+                    writeProxyEnv(root, name, env);
+                };
                 recordPidsSoFar();
                 writeProxyEnv(root, name, env);
             }
@@ -1733,6 +1947,9 @@ export async function upWorld(configId, options = {}, abort) {
             const attemptProxy = () => {
                 if (proxyForServices || (Object.keys(activeVendorMap(env)).length === 0 && env[WORLD_NETWORK_POLICY_ENV] === undefined))
                     return;
+                // a host with no raw sockets (a browser tab) has nothing for the proxy to intercept; the injector holds the policy
+                if (!hostHasRawEgress())
+                    return;
                 if (!opensslAvailable()) {
                     if (mode === 'sealed' || loaded.config.network !== undefined) {
                         throw new Error(`world "${name}" requires its network policy proxy, but openssl is unavailable; refusing to start. Install openssl.`);
@@ -1754,7 +1971,7 @@ export async function upWorld(configId, options = {}, abort) {
                 if (services[service.id])
                     continue; // already up co-located
                 if (colocatedReady && (service.type ?? 'twin') !== 'twin') {
-                    await colocatedReady;
+                    await colocatedReady();
                     colocatedReady = undefined;
                 }
                 attemptProxy();
@@ -1763,11 +1980,21 @@ export async function upWorld(configId, options = {}, abort) {
                 services[started.id] = started;
                 recordPidsSoFar();
                 Object.assign(env, started.env);
+                await issueCredentials(service, started, env, issuing, unissued);
                 writeProxyEnv(root, name, env);
             }
             if (colocatedReady)
-                await colocatedReady;
+                await colocatedReady();
             detachBootSignals();
+            // a name a service of no twin in this World issues (a config edited after init) is left unset, and said
+            if (issuing.size > 0)
+                process.stderr.write(`volter-world: nothing in this World issues ${[...issuing].map(([n, id]) => `${n} ($issue:${id})`).join(', ')}; left unset\n`);
+            for (const [name] of issuing)
+                unissued.add(name);
+            if (unissued.size > 0) {
+                env[UNISSUED_ENV] = JSON.stringify([...unissued].sort());
+                writeProxyEnv(root, name, env);
+            }
             // Re-evaluate once more after the LAST service: a single/last-twin world's OWN vendor twin
             // only lands in `env` once IT has started, so a check that only runs "before starting the
             // next service" never fires when there is no next service (TWIN-64) — the single-twin sealed
@@ -2989,7 +3216,17 @@ export function urlWorld(name, options = {}) {
     if (options.service === undefined) {
         return Object.values(status.services)
             .filter((service) => service.url)
-            .map((service) => ({ id: service.id, url: service.url }));
+            .flatMap((service) => [{ id: service.id, url: service.url }, ...Object.entries(service.sides ?? {}).map(([side, at]) => ({ id: `${service.id}.${side}`, url: at.url }))]);
+    }
+    // a side port by `<service>.<name>` (the SMTP twin's mailbox: smtp.inspect)
+    const dot = options.service.lastIndexOf('.');
+    if (!status.services[options.service] && dot > 0) {
+        const owner = status.services[options.service.slice(0, dot)];
+        const side = owner?.sides?.[options.service.slice(dot + 1)];
+        if (side)
+            return [{ id: options.service, url: side.url }];
+        if (owner)
+            throw new Error(`Service "${owner.id}" has no side port "${options.service.slice(dot + 1)}"; it has: ${Object.keys(owner.sides ?? {}).join(', ') || 'none'}`);
     }
     const service = status.services[options.service];
     if (!service) {
@@ -3120,19 +3357,38 @@ function worldAttachedCommandEnv(name, root, verbose = false) {
         const proxy = ensureWorldProxy(name, root, [admittedEnv(stripEnvOf(status.env)), status.env]);
         if (proxy?.url) {
             proxyEnv = proxy.env;
+            // a host with no raw sockets (a browser tab) runs no proxy: the injector holds the policy there, as at `up`
         }
-        else if (sealed)
+        else if (sealed && hostHasRawEgress())
             throw new Error(`world "${name}" requires its network policy proxy: attachment proxy is unavailable; refusing to run the command`);
     }
     catch (error) {
         if (error instanceof CaTrustError)
             throw error;
-        if (sealed)
+        if (sealed && hostHasRawEgress())
             throw new Error(`world "${name}" requires its network policy proxy: attachment proxy failed; refusing to run the command (${error instanceof Error ? error.message : String(error)})`);
         // Keep env-only redirect if the ambient proxy cannot start.
     }
-    return { instance: status, env: { ...baseEnv, ...proxyEnv, VOLTER_WORLD: name,
-            VOLTER_TWIN_INJECT_QUIET: verbose ? '0' : baseEnv.VOLTER_TWIN_INJECT_QUIET ?? '1' } };
+    return { instance: status, env: withAppUrl(name, root, { ...baseEnv, ...proxyEnv, VOLTER_WORLD: name,
+            VOLTER_TWIN_INJECT_QUIET: verbose ? '0' : baseEnv.VOLTER_TWIN_INJECT_QUIET ?? '1' }) };
+}
+/** The env with each `$app-url` value made the application URL its booter recorded. Unrecorded, the name is left
+ *  unset (the application's own env files decide) and the command is told how to record it: never a guess. */
+export function withAppUrl(name, root, env) {
+    const names = Object.keys(env).filter((key) => env[key] === APP_URL_ENV);
+    if (names.length === 0)
+        return env;
+    const out = { ...env };
+    const recorded = readAppUrl(name, { root });
+    for (const key of names) {
+        if (recorded)
+            out[key] = recorded.url.replace(/\/+$/, '');
+        else
+            delete out[key];
+    }
+    if (!recorded)
+        process.stderr.write(`world "${name}": ${names.join(', ')} name the application's own address, which is not recorded; left unset. Record it with: volter-world app-url ${name} --set <url>\n`);
+    return out;
 }
 /** Runs the command in the world's env in the foreground and resolves to its exit code. The child is
  *  awaited, not blocked on: a runtime that runs no synchronous child (the browser engine) still runs
@@ -3144,7 +3400,7 @@ export function runWithWorldEnv(name, command, root = process.cwd(), options = {
     return new Promise((resolveExit) => {
         const child = spawn(command[0], command.slice(1), { windowsHide: true,
             cwd: resolve(options.cwd ?? root),
-            env: attached.env,
+            env: { ...attached.env, ...(options.env ?? {}) },
             stdio: 'inherit',
         });
         const forward = (signal) => { if (child.exitCode === null && child.signalCode === null)
@@ -3400,7 +3656,7 @@ export function worldShellEnv(name, root = process.cwd()) {
     return {
         shell: status.env.SHELL || admittedEnv(stripEnvOf(status.env)).SHELL || '/bin/bash',
         cwd: resolve(root),
-        env: { ...admittedEnv(stripEnvOf(status.env)), ...status.env, VOLTER_WORLD: name },
+        env: withAppUrl(name, root, { ...admittedEnv(stripEnvOf(status.env)), ...status.env, VOLTER_WORLD: name }),
     };
 }
 /** Drop into an interactive subshell with the world active — the contained sibling of `activate`
@@ -3414,7 +3670,10 @@ export async function shellWorld(name, root = process.cwd()) {
     const resolvedRoot = resolve(root);
     let proxy = null;
     const sealed = env.VOLTER_WORLD_MODE === 'sealed' || env[WORLD_NETWORK_POLICY_ENV] !== undefined;
-    if (opensslAvailable()) {
+    if (!hostHasRawEgress()) {
+        process.stderr.write(`world '${name}' active in a subshell — vendor calls hit the twins (this host opens no raw sockets; the injector holds the network policy). type 'exit' to leave.\n`);
+    }
+    else if (opensslAvailable()) {
         try {
             proxy = await startRedirectProxy({ env, trustEnv: [admittedEnv(stripEnvOf(env)), env], tlsDir: tlsDir(resolvedRoot, name) });
             Object.assign(env, proxy.proxyEnv());
@@ -3494,7 +3753,7 @@ function currentProxyState(root, name) {
 }
 function ensureWorldProxyUnlocked(name, root, caller) {
     const resolvedRoot = resolve(root);
-    if (!opensslAvailable())
+    if (!hostHasRawEgress() || !opensslAvailable())
         return null;
     const existing = currentProxyState(resolvedRoot, name);
     if (existing && isAlive(existing.pid)) {
@@ -3506,7 +3765,7 @@ function ensureWorldProxyUnlocked(name, root, caller) {
 }
 function ensureWorldProxyFromEnv(name, root, env, boot) {
     const resolvedRoot = resolve(root);
-    if (!opensslAvailable())
+    if (!hostHasRawEgress() || !opensslAvailable())
         return null;
     writeProxyEnv(resolvedRoot, name, env);
     const existing = currentProxyState(resolvedRoot, name);
@@ -3606,6 +3865,10 @@ function startProxyDaemonOwned(name, root, caCertPath, envFile, boot, caller = p
             Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
         }
         retire();
+        // the proxy is confirmed gone: ownership goes back to the World's running processes, as on success (it was retained
+        // for cleanup only while the child's fate was unknown), so the World stays running unsealed, as the warning says
+        if (!boot)
+            handoffWorldLifecycle(root, name, readPids(join(instanceDir(root, name), 'pids')));
         process.stderr.write(`!! WARN: ambient proxy daemon for world "${name}" did not report within ${deadlineMs}ms — world is NOT proxy-sealed; unmodified CLIs will bypass the twins (env-only redirect still active).\n`);
         return { url: '', caCertPath, env: {} };
     }
@@ -3739,16 +4002,17 @@ export function activateScript(name, root = process.cwd()) {
             env = { ...baseEnv, ...proxy.env };
             proxyNote = ` (ambient proxy ${proxy.url})`;
         }
-        else if (sealed)
+        else if (sealed && hostHasRawEgress())
             throw new Error('attachment proxy is unavailable');
     }
     catch (error) {
         if (error instanceof CaTrustError)
             throw error;
-        if (sealed)
+        if (sealed && hostHasRawEgress())
             throw new Error(`world "${name}" requires its network policy proxy: attachment proxy failed; refusing activation (${error instanceof Error ? error.message : String(error)})`);
         // openssl missing or daemon failed — keep env-only redirect; never fabricate proxy success.
     }
+    env = withAppUrl(name, root, env);
     const keys = Object.keys(env).sort();
     const lines = [
         `# volter-world activate ${name} — run:  eval "$(volter-world activate ${name})"`,