@volter/world-runtime 2.0.55 → 3.0.0

package/src/runtime.ts

@@ -4,6 +4,7 @@ import { parallelStartup } from './startup.ts';
 import { waitForHostReady } from './host-ready.ts';
 import { assertWorldStateRemovable, removeWorldState } from './ancestry.ts';
 import { packCli, packEntry } from './catalog.ts';
+import { vendorOfPackModule } from '@volter/world-core/runtime';
 import { spawn, spawnSync } from 'node:child_process';
 import { get as httpGet, type ClientRequest } from 'node:http';
 import { siblingScript } from './sibling.ts';
@@ -21,15 +22,15 @@ import { packFacts } from './pack-facts.ts';
 import { infraConnections, parseInfraDefinition } from './pglite-backing.ts';
 import { describeServiceEnd, readServiceEnd, serviceOutput } from './service-exit.ts';
 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 type { PlanReviewRecord } 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.ts';
 import { createWorldNetworkPolicy, WORLD_NETWORK_POLICY_ENV } from '@volter/world-core/network-policy';
-import { resolveServicePackage } from './catalog.ts';
+import { overlayPackFactsFile, resolveServicePackage } from './catalog.ts';
 import { fakeEnvValue } from './fixture-env.ts';
-import { MINT_ENV } from './schema.ts';
+import { APP_URL_ENV, ISSUE_ENV_PREFIX, MINT_ENV } from './schema.ts';
+import { readAppUrl } from './app-url.ts';
 import { inertInjectEnvWarnings } from './inject-map.ts';
-import { activeVendorMap, ensureCa, opensslAvailable, proxyEnvFor, startRedirectProxy, tearDownCa } from './redirect-proxy.ts';
+import { activeVendorMap, ensureCa, hostHasRawEgress, opensslAvailable, proxyEnvFor, startRedirectProxy, tearDownCa } from './redirect-proxy.ts';
 import { CaTrustError, sessionTrustEnv, type CaTrustInputs } from './ca-trust.ts';
 import type { WorldConfig, WorldExternalReadyWhen, WorldInstance, WorldIsolation, WorldMode, WorldRunOutcome, WorldRunRecord, WorldServiceConfig, WorldServiceInstance } from './schema.ts';
 import { checkedOwner, CONSUMER_HEARTBEAT_MS, createConsumer, refreshConsumer, releaseConsumer, removeConsumerRecord, worldConsumers } from './consumers.ts';
@@ -138,6 +139,7 @@ async function confirmOwnPort(port: number, boot: BootContext, ended: Promise<vo
 function worldBootOf(port: number, abort: AbortSignal): Promise<{ boot?: unknown } | null> {
   return new Promise((resolveBoot) => {
     let request: ClientRequest | undefined;
+    // 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: ReturnType<typeof setTimeout> | undefined;
     let settled = false;
     let responseStarted = false;
@@ -503,6 +505,8 @@ function shellQuote(value: string): string {
 
 function envFileContents(env: Record<string, string>): string {
   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`;
@@ -571,6 +575,25 @@ export function withoutVaultSignIn<T extends Record<string, string | undefined>>
 }
 
 /** 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: string, own: { egress: readonly string[] } | undefined, parentEnv: NodeJS.ProcessEnv = process.env): Record<string, string> | undefined {
+  const serialized = parentEnv[WORLD_NETWORK_POLICY_ENV];
+  let ceiling: readonly string[] | undefined;
+  if (serialized !== undefined) {
+    // an unreadable parent policy closes the child entirely, as it closes the parent
+    try { ceiling = (JSON.parse(serialized) as { egress?: string[] }).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: string[] | undefined, env: NodeJS.ProcessEnv = process.env): Record<string, string> {
   const out: Record<string, string> = {};
   const rules = (strip ?? []).map((s): { prefix: string } | { name: string } => (s.endsWith('*') ? { prefix: s.slice(0, -1) } : { name: s }));
@@ -585,7 +608,20 @@ export function admittedEnv(strip: string[] | undefined, env: NodeJS.ProcessEnv
   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: Record<string, string>): string[] {
+  try { const names: unknown = JSON.parse(instanceEnv[UNISSUED_ENV] ?? '[]'); return Array.isArray(names) ? names.filter((n): n is string => typeof n === 'string') : []; } catch { return []; }
+}
+
 function stripEnvOf(instanceEnv: Record<string, string>): string[] | undefined {
+  const unissued = unissuedOf(instanceEnv);
+  const rules = savedStripEnvOf(instanceEnv);
+  return unissued.length === 0 ? rules : [...(rules ?? []), ...unissued];
+}
+
+function savedStripEnvOf(instanceEnv: Record<string, string>): string[] | undefined {
   // Freeze the admission policy for the instance; editing/removing its source cannot widen it.
   const saved = instanceEnv.VOLTER_WORLD_STRIP_ENV;
   if (saved !== undefined) {
@@ -615,7 +651,16 @@ function serviceProcessEnv(
   if (service.controlPlane) {
     for (const key of CONTROL_PLANE_EGRESS_ENV) delete env[key];
   }
-  return { ...env, ...(service.env ?? {}) };
+  dropUnissued(env);
+  const out: Record<string, string> = { ...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: number, timeoutMs = 15_000, abort?: AbortSignal): Promise<void> {
@@ -701,8 +746,11 @@ function writeOwnedPids(root: string, name: string, pids: number[], fresh: numbe
 function identityPath(root: string, name: string): string {
   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: number[]): Map<number, string> {
   const starts = new Map<number, string>();
   if (!pids.length || process.platform === 'win32') return starts;
@@ -713,10 +761,11 @@ function processStarts(pids: number[]): Map<number, string> {
     }
     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;
 }
@@ -1129,7 +1178,7 @@ async function startService(
   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: MountedPackage = spawnedModule !== undefined ? lockfileCheck(service, spawnedModule) : {};
@@ -1139,6 +1188,8 @@ async function startService(
     const binding = managedDatabaseFor(vendorOfModule(spawnedModule, service.id), worldEnv.VOLTER_WORLD_CONFIG, config.env ?? {});
     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) args.push(service.rootArg ?? '--root', serviceDataDir);
 
@@ -1218,6 +1269,7 @@ async function startService(
     command: [service.command, ...args],
     port,
     url,
+    ...sidesRecord(sides),
     ...(mounted.version !== undefined ? { resolvedVersion: mounted.version } : {}),
     ...(mounted.protocol !== undefined ? { protocol: mounted.protocol } : {}),
     pid: child.pid ?? 0,
@@ -1246,35 +1298,49 @@ function mountedPackage(modulePath: string, serviceId: string): MountedPackage {
     }
     const up = dirname(dir); if (up === dir) break; dir = up;
   }
-  const m = /\/packages\/twin\/([^/]+)\//.exec(modulePath) ?? /@volter\/twin-([^/]+)\//.exec(modulePath);
-  const vendor = m?.[1] ?? serviceId;
-  try { const facts = packFacts()[vendor]; if (facts?.protocol) out.protocol = facts.protocol; } catch { /* no artifact: the standing is unknown, not refused */ }
+  const vendor = vendorOfPackModule(modulePath) ?? serviceId;
+  try { const facts = packFacts()[vendor]; if (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: WorldServiceConfig, modulePath: string): MountedPackage {
   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)`);
+    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}) — 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`);
+  if (mounted.protocol?.standing === 'refused') 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: WorldServiceConfig, root: string): string | undefined {
-  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: string, args: readonly string[], allocatedPorts: Set<number>): Promise<Array<{ name: string; option: string; flag: string; port: number; pinned: boolean; url: string }>> {
+  const declared = packFacts()[vendor]?.sidePorts ?? [];
+  const out: Array<{ name: string; option: string; flag: string; port: number; pinned: boolean; url: string }> = [];
+  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: ReadonlyArray<{ name: string; port: number; url: string }>): { sides?: Record<string, { port: number; url: string }> } =>
+  sides.length ? { sides: Object.fromEntries(sides.map((side) => [side.name, { port: side.port, url: side.url }])) } : {};
+
 function vendorOfModule(modulePath: string | undefined, serviceId: string): string {
-  const m = modulePath === undefined ? null : (/\/packages\/twin\/([^/]+)\//.exec(modulePath) ?? /@volter\/twin-([^/]+)(\/|$)/.exec(modulePath));
-  return m?.[1] ?? serviceId;
+  return (modulePath === undefined ? undefined : vendorOfPackModule(modulePath)) ?? serviceId;
 }
 
 /**
@@ -1297,12 +1363,86 @@ export function managedDatabaseFor(vendor: string, configPath: string | undefine
   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: WorldConfig, root: string): string[] {
+  const files: string[] = [];
+  for (const service of config.services) {
+    if (service.package === undefined) continue;
+    let dir: string;
+    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: Record<string, string>): void {
+  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: Record<string, string>): Map<string, string> {
+  const pending = new Map<string, string>();
+  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: WorldServiceConfig, started: WorldServiceInstance, env: Record<string, string>, pending: Map<string, string>, unissued: Set<string>): Promise<void> {
+  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()) as Record<string, unknown>;
+    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: WorldConfig, root: string): WorldConfig {
   const services = config.services.map((service) => {
     if (service.package === undefined) return service;
@@ -1358,7 +1498,7 @@ async function startColocatedServices(
   const hostCli = siblingScript(import.meta.url, 'host-cli');
   const readyFile = join(paths.instance, `host-ready-${boot.bootId}.json`);
   const args: string[] = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker', '--ready-file', readyFile];
-  const allocated: Array<{ service: WorldServiceConfig; port: number; mounted: MountedPackage }> = [];
+  const allocated: Array<{ service: WorldServiceConfig; port: number; mounted: MountedPackage; sides: Awaited<ReturnType<typeof sidePortsFor>> }> = [];
   for (const service of colocated) {
     const port = service.port === undefined || service.port === 'auto' ? await allocatePort(allocatedPorts) : service.port;
     const serviceDataDir = join(paths.data, service.id);
@@ -1373,8 +1513,9 @@ async function startColocatedServices(
     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');
@@ -1382,6 +1523,9 @@ async function startColocatedServices(
   // services (no injector preload, no ambient proxy): its twins SERVE, they don't call vendors.
   const env: Record<string, string> = { ...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);
@@ -1398,7 +1542,7 @@ async function startColocatedServices(
   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,
@@ -1406,6 +1550,7 @@ async function startColocatedServices(
       command,
       port,
       url,
+      ...sidesRecord(sides),
       ...(mounted.version !== undefined ? { resolvedVersion: mounted.version } : {}),
       ...(mounted.protocol !== undefined ? { protocol: mounted.protocol } : {}),
       pid: child.pid ?? 0,
@@ -1419,7 +1564,7 @@ async function startColocatedServices(
   });
   const ready = (async (): Promise<void> => {
     const hostTimeoutMs = allocated.reduce((timeout, { service }) => Math.max(timeout, typeof service.ready === 'object' ? service.ready.timeoutMs ?? 15_000 : 15_000), 15_000);
-    await untilReadyOrEnded((abort) => waitForHostReady(readyFile, boot.bootId, new Map(allocated.map(({ service, port }) => [service.id, port])), hostTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
+    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 { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
       throw new Error(`Co-located host failed to complete startup (isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
@@ -1435,7 +1580,7 @@ async function startColocatedServices(
     // 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' as const);
     await parallelStartup(allocated, async ({ service, port }) => {
@@ -1462,6 +1607,11 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
   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';
@@ -1508,10 +1658,18 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
   const envFile = resolve(root, options.envFile ?? join(instance, 'world.env'));
   const instanceFile = join(instance, 'instance.json');
   let carriedOrigin: WorldInstance['origin'] | undefined;
-  const priorOutputInstance = existsSync(instanceFile) ? JSON.parse(readFileSync(instanceFile, 'utf8')) as WorldInstance : 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')) as WorldInstance;
+      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);
@@ -1625,7 +1783,7 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       // 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,
@@ -1646,6 +1804,8 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
     };
     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<string>();
     writeProxyEnv(root, name, env);
 
     const worldInstance: WorldInstance = {
@@ -1655,6 +1815,7 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       ...(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);
@@ -1685,8 +1846,9 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       // The co-located host's twins are known by address once their ports are
       // allocated. A twin serves and calls no other service while it starts,
       // so a later twin declaration starts beside the host's startup; any other
-      // service waits until every earlier one is ready, as declared (ADR-0009).
-      let colocatedReady: Promise<void> | undefined;
+      // 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: (() => Promise<void>) | undefined;
       if (isolation !== 'process') {
         const colocated = loaded.config.services.filter((service) => service.colocate && service.type !== 'external');
         const host = await startColocatedServices(loaded.config, colocated, isolation, env, { root, instance, logs, data }, allocatedPorts, boot);
@@ -1694,7 +1856,14 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
           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);
       }
@@ -1706,6 +1875,8 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       // the twins undetected.
       const attemptProxy = (): void => {
         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(
@@ -1726,17 +1897,22 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       };
       for (const service of loaded.config.services) {
         if (services[service.id]) continue; // already up co-located
-        if (colocatedReady && (service.type ?? 'twin') !== 'twin') { await colocatedReady; colocatedReady = undefined; }
+        if (colocatedReady && (service.type ?? 'twin') !== 'twin') { await colocatedReady(); colocatedReady = undefined; }
         attemptProxy();
         boot.signal.throwIfAborted();
         const started = await startService(loaded.config, service, env, { root, instance, logs, data }, allocatedPorts, boot);
         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;
+      if (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
@@ -2937,7 +3113,15 @@ export function urlWorld(name: string, options: { service?: string; root?: strin
   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) {
@@ -3052,26 +3236,42 @@ function worldAttachedCommandEnv(name: string, root: string, verbose = false): {
     const proxy = ensureWorldProxy(name, root, [admittedEnv(stripEnvOf(status.env)), status.env]);
     if (proxy?.url) {
       proxyEnv = proxy.env;
-    } else if (sealed) throw new Error(`world "${name}" requires its network policy proxy: attachment proxy is unavailable; refusing to run the command`);
+    // a host with no raw sockets (a browser tab) runs no proxy: the injector holds the policy there, as at `up`
+    } 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) 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)})`);
+    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<E extends Record<string, string | undefined>>(name: string, root: string, env: E): E {
+  const names = Object.keys(env).filter((key) => env[key] === APP_URL_ENV);
+  if (names.length === 0) return env;
+  const out: Record<string, string | undefined> = { ...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 as E;
 }
 
 /** 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
  *  this one, and the caller sees no difference — stdio is inherited either way. */
-export function runWithWorldEnv(name: string, command: string[], root = process.cwd(), options: { cwd?: string; verbose?: boolean } = {}): Promise<number> {
+export function runWithWorldEnv(name: string, command: string[], root = process.cwd(), options: { cwd?: string; verbose?: boolean; env?: Record<string, string> } = {}): Promise<number> {
   if (command.length === 0) throw new Error('Missing command after --');
   const attached = worldAttachedCommandEnv(name, root, options.verbose);
   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: NodeJS.Signals) => { if (child.exitCode === null && child.signalCode === null) child.kill(signal); };
@@ -3275,7 +3475,7 @@ export function worldShellEnv(name: string, root = process.cwd()): { shell: stri
   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 } as Record<string, string>,
+    env: withAppUrl(name, root, { ...admittedEnv(stripEnvOf(status.env)), ...status.env, VOLTER_WORLD: name } as Record<string, string>),
   };
 }
 
@@ -3290,7 +3490,9 @@ export async function shellWorld(name: string, root = process.cwd()): Promise<nu
   const resolvedRoot = resolve(root);
   let proxy: Awaited<ReturnType<typeof startRedirectProxy>> | null = 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());
@@ -3355,7 +3557,7 @@ function currentProxyState(root: string, name: string): ProxyState | null {
 
 function ensureWorldProxyUnlocked(name: string, root: string, caller: CaTrustInputs): { url: string; caCertPath: string; env: Record<string, string> } | null {
   const resolvedRoot = resolve(root);
-  if (!opensslAvailable()) return null;
+  if (!hostHasRawEgress() || !opensslAvailable()) return null;
   const existing = currentProxyState(resolvedRoot, name);
   if (existing && isAlive(existing.pid)) {
     return { url: existing.url, caCertPath: existing.caCertPath, env: proxyEnvFor(existing.url, existing.caCertPath, caller, existing.guestUrl) };
@@ -3367,7 +3569,7 @@ function ensureWorldProxyUnlocked(name: string, root: string, caller: CaTrustInp
 
 function ensureWorldProxyFromEnv(name: string, root: string, env: Record<string, string>, boot: BootContext): { url: string; caCertPath: string; env: Record<string, string> } | null {
   const resolvedRoot = resolve(root);
-  if (!opensslAvailable()) return null;
+  if (!hostHasRawEgress() || !opensslAvailable()) return null;
   writeProxyEnv(resolvedRoot, name, env);
   const existing = currentProxyState(resolvedRoot, name);
   if (existing && isAlive(existing.pid)) {
@@ -3443,6 +3645,9 @@ function startProxyDaemonOwned(name: string, root: string, caCertPath: string, e
       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: {} };
   } catch (error) {
@@ -3553,12 +3758,13 @@ export function activateScript(name: string, root = process.cwd()): string {
     if (proxy && proxy.url) {
       env = { ...baseEnv, ...proxy.env };
       proxyNote = ` (ambient proxy ${proxy.url})`;
-    } else if (sealed) throw new Error('attachment proxy is unavailable');
+    } else if (sealed && hostHasRawEgress()) throw new Error('attachment proxy is unavailable');
   } catch (error) {
     if (error instanceof CaTrustError) throw error;
-    if (sealed) throw new Error(`world "${name}" requires its network policy proxy: attachment proxy failed; refusing activation (${error instanceof Error ? error.message : String(error)})`);
+    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: string[] = [
     `# volter-world activate ${name} — run:  eval "$(volter-world activate ${name})"`,