@volter/world-runtime 2.0.0

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@volter/world-runtime",
+  "version": "2.0.0",
+  "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
+  "keywords": [
+    "twin",
+    "world",
+    "local",
+    "fixtures",
+    "testing",
+    "sdk",
+    "api",
+    "localstack"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "known-external-services.json",
+    "client",
+    "test-fixtures",
+    "README.md",
+    "LICENSE",
+    "!test-fixtures/*.SOURCE.md",
+    "!src/host-fault-fixture.ts",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/world-runtime"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/world-runtime#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "volter-world": "dist/src/cli.js",
+    "volter-world-browser-proxy": "dist/src/browser-proxy-cli.js",
+    "volter-world-host": "dist/src/host-cli.js",
+    "volter-world-infra": "dist/src/infra-cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../scripts/publish/build.mjs",
+    "prepack": "node ../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "pg": "8.16.3",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0",
+    "@volter/world-console": "2.0.0"
+  },
+  "dependencies": {
+    "@electric-sql/pglite": "0.5.8",
+    "@volter/world-core": "2.0.0",
+    "pg-gateway": "0.3.0-beta.4",
+    "smol-toml": "^1.8.0"
+  },
+  "peerDependenciesMeta": {
+    "@volter/world-console": {
+      "optional": true
+    }
+  }
+}

package/src/ancestry.ts

@@ -0,0 +1,36 @@
+// Check discoverable legacy pointers before removing retained World storage. New pointers
+// carry parent-side pins, including clones across checkouts, without a global World registry.
+import { existsSync, readdirSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { assertStateRemovable, readBranchMeta, stateDirName, withAncestryLock, withStateRemoval, getActiveWorldStore, worldPaths, worldStateRoot } from '@volter/world-core';
+
+function checkWorldAncestry(root: string, path: string): void {
+  const base = join(root, stateDirName(), 'worlds');
+  if (!existsSync(base)) return;
+  for (const world of readdirSync(base, { withFileTypes: true })) {
+    if (!world.isDirectory() || world.name.startsWith('.')) continue;
+    const data = join(base, world.name, 'data');
+    if (!existsSync(data)) continue;
+    for (const service of readdirSync(data, { withFileTypes: true })) {
+      if (!service.isDirectory()) continue;
+      const control = join(data, service.name); const states = worldStateRoot(control);
+      if (!existsSync(states)) continue;
+      for (const state of readdirSync(states, { withFileTypes: true })) {
+        if (!state.isDirectory()) continue;
+        const meta = readBranchMeta(state.name, control);
+        if (!meta?.parent || /^[a-z][a-z0-9+.-]*:\/\//i.test(meta.parent.at)) continue;
+        const parent = worldPaths(state.name, meta.parent.at).dir;
+        const under = (target: string) => { const rel = relative(getActiveWorldStore().canonicalPath?.(path) ?? resolve(path), getActiveWorldStore().canonicalPath?.(target) ?? resolve(target)); return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep)); };
+        if (under(parent) && !under(control)) throw new Error(`Retained branch parent: dependent World ${world.name} (${control}). Remove dependent branches first; down without purge can still stop compute.`);
+      }
+    }
+  }
+}
+
+export function assertWorldStateRemovable(root: string, path: string): void {
+  withAncestryLock(() => { checkWorldAncestry(root, path); assertStateRemovable(path); });
+}
+
+export function removeWorldState<T>(root: string, path: string, remove: () => T): T {
+  return withStateRemoval(path, remove, () => checkWorldAncestry(root, path));
+}

package/src/app-url.ts

@@ -0,0 +1,253 @@
+// `volter-world app-url` — the recorded, queryable APP endpoint of a world instance.
+//
+// Worlds own the lifecycle of SERVICES; the app under test is usually booted OUTSIDE the world by
+// the caller (the attach pattern), so nothing in the instance knows where the app listens — every
+// consumer (a browser step, a webhook target, a teammate's curl) re-derives it by folklore. The
+// subject pilots hit exactly this: the world's URLs are one `volter-world url` away, the APP's URL
+// is tribal knowledge. This verb makes the app endpoint a first-class instance record:
+//
+//   • the BOOTER writes it once, as the LAST boot step — `--set <url>`, or `--detect <pid|port>`
+//     to read it off the already-listening process instead of typing it;
+//   • any consumer reads it back (`volter-world app-url <world> [--json]`);
+//   • an UNSET read fails LOUDLY with the registration recipe — never a guess, never a default.
+//
+// A world that boots the app itself declares an `app` service (`type: 'process'`) — that existing
+// convention needs no registration: the read falls back to the `app` service's assigned URL.
+//
+// RUNTIME MINIMALISM HOLDS: this is a record, not orchestration. The runtime never boots, probes,
+// supervises, or health-checks the app — `--detect` inspects the caller-named pid/port exactly
+// once, at the caller's request, and stores what it saw. The record lives in the instance dir, so
+// a re-`up` (which wipes the dir) or `down --purge` clears it: a recorded URL never outlives the
+// instance it described.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import net from 'node:net';
+import { instanceDir, statusWorld } from './runtime.ts';
+import { loadInject } from './inject-map.ts';
+import { packFacts } from './pack-facts.ts';
+
+/** Who answered: an explicit `--set`, a `--detect` inspection, or the world's own `app` service. */
+export type AppUrlSource = 'set' | 'detect' | 'service';
+
+export type AppUrlRecord = {
+  world: string;
+  url: string;
+  via: AppUrlSource;
+  /** ISO timestamp of the registration (absent for the `app`-service fallback — nothing was recorded) */
+  recordedAt?: string;
+  /** how the URL was obtained, for the human reading `--json` output later */
+  detail?: string;
+  /** the application's own production hostnames (`--host`), routed to `url` inside the World as DNS routes them to
+   *  its host in production: the injector, the socket backstop and the redirect proxy read them from this record */
+  hosts?: string[];
+};
+
+export function appUrlFile(root: string, name: string): string {
+  return join(instanceDir(root, name), 'app-url.json');
+}
+
+function assertHttpUrl(url: string): URL {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`volter-world app-url: "${url}" is not a URL (want e.g. http://127.0.0.1:3000)`);
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`volter-world app-url: "${url}" must be http(s) — an app endpoint consumers can fetch`);
+  }
+  return parsed;
+}
+
+/** Record `url` as the app endpoint of the RUNNING/booted instance `name`. The instance must
+ * exist (a record for a world that was never upped would describe nothing); the app itself is
+ * deliberately NOT probed — the booter declaring "this is where I put the app" is the truth. */
+export function setAppUrl(name: string, url: string, options: { root?: string; via?: Exclude<AppUrlSource, 'service'>; detail?: string } = {}): AppUrlRecord {
+  const root = options.root ?? process.cwd();
+  const status = statusWorld(name, root); // throws "World instance not found" — the loud path
+  assertHttpUrl(url);
+  // a new URL keeps the hosts recorded for the app (they name the app, not where it listens)
+  const hosts = existsSync(appUrlFile(root, name)) ? (JSON.parse(readFileSync(appUrlFile(root, name), 'utf8')) as AppUrlRecord).hosts : undefined;
+  const record: AppUrlRecord = {
+    world: status.name,
+    url,
+    via: options.via ?? 'set',
+    recordedAt: new Date().toISOString(),
+    ...(options.detail === undefined ? {} : { detail: options.detail }),
+    ...(hosts?.length ? { hosts } : {}),
+  };
+  writeFileSync(appUrlFile(root, name), `${JSON.stringify(record, null, 2)}\n`);
+  return record;
+}
+
+/** A hostname the app may answer as: a DNS name (not an address, not loopback) that no twin serves, and not the
+ *  host of this World's own origin or of a twin it runs (their requests carry the World key). */
+function assertAppHost(host: string, world: string, root: string): string {
+  const name = host.trim().toLowerCase().replace(/\.$/, '');
+  // a wildcard (`*.dub.link`) stands for every name below its parent, as a DNS wildcard record does; its parent has two
+  // labels at least (never a bare TLD). Whether the parent is a public suffix (co.uk, github.io) is the operator's word:
+  // a World keeps no public suffix list
+  const wildcard = name.startsWith('*.');
+  const bare = wildcard ? name.slice(2) : name;
+  if (!/^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,61}[a-z0-9]$/.test(bare) || net.isIP(bare) || bare === 'localhost' || bare.endsWith('.localhost')) {
+    throw new Error(`volter-world app-url: --host "${host}" is not a DNS hostname the app answers as (e.g. app.example.com, or *.example.com)`);
+  }
+  const inject = loadInject();
+  let vendor = Object.keys(inject.VENDOR_HOSTS).find((v) => inject.VENDOR_HOSTS[v]!(bare));
+  if (!vendor && wildcard) {
+    // a wildcard is refused when any name a vendor's rule can give its twin lies under it, or it lies under a vendor's
+    // host suffix: the rules' names, read from the descriptors (a host, a suffix, a pattern's literal tail) and from
+    // the hand table's predicates (their quoted names)
+    const names = vendorNames(inject.VENDOR_HOSTS);
+    const dotted = `.${bare}`;
+    vendor = names.find((n) => n.name === bare || n.name.endsWith(dotted) || (n.suffix && dotted.endsWith(n.name.startsWith('.') ? n.name : `.${n.name}`)))?.vendor;
+  }
+  if (vendor) throw new Error(`volter-world app-url: --host ${name} is ${vendor}'s host, which its twin serves; an app cannot answer as it`);
+  const status = statusWorld(world, root);
+  const own = [status.env.VOLTER_WORLD ?? '', ...Object.values(status.services).map((service) => service.url ?? '')]
+    .flatMap((url) => { try { return [new URL(url).hostname.toLowerCase()]; } catch { return []; } });
+  if (own.some((h) => h === name || (wildcard && h.endsWith(`.${bare}`)))) throw new Error(`volter-world app-url: --host ${name} is this World's own origin or a twin's; an app cannot answer as it`);
+  return name;
+}
+
+/** Every hostname the vendor table can name, with its vendor: a descriptor rule's host, suffix, or a host pattern's
+ *  literal tail (a suffix), and each quoted name in a hand-table predicate (a leading dot marks a suffix). */
+function vendorNames(table: Record<string, (host: string, pathname?: string) => boolean>): Array<{ vendor: string; name: string; suffix: boolean }> {
+  const out: Array<{ vendor: string; name: string; suffix: boolean }> = [];
+  for (const [vendor, facts] of Object.entries(packFacts())) {
+    for (const rule of facts.hosts ?? []) {
+      if (rule.exclude) continue;
+      if (rule.host) out.push({ vendor: rule.key ?? vendor, name: rule.host.toLowerCase(), suffix: false });
+      if (rule.suffix) out.push({ vendor: rule.key ?? vendor, name: rule.suffix.toLowerCase().replace(/^-/, '.'), suffix: true });
+      if (rule.hostPattern) {
+        // the literal tail, and each alternative of a trailing group joined to what precedes it
+        // (`\.(amazonaws\.com|api\.aws)$` names both)
+        const src = rule.hostPattern.replace(/\\\./g, '.').replace(/\$$/, '');
+        const group = /([a-z0-9.-]*)\((?:\?:)?([a-z0-9.|-]+)\)$/i.exec(src);
+        const tails = group ? group[2]!.split('|').map((alt) => `${group[1]}${alt}`) : [/[a-z0-9.-]+$/i.exec(src)?.[0] ?? ''];
+        for (const tail of tails) if (tail.includes('.')) out.push({ vendor: rule.key ?? vendor, name: tail.toLowerCase(), suffix: true });
+      }
+    }
+  }
+  for (const [vendor, predicate] of Object.entries(table)) {
+    for (const m of String(predicate).matchAll(/['"`](\.?[a-z0-9-]+(?:\.[a-z0-9-]+)+)['"`]/gi)) out.push({ vendor, name: m[1]!.toLowerCase(), suffix: m[1]!.startsWith('.') });
+  }
+  return out;
+}
+
+/** Record `hosts` as the app's own production hostnames, beside its recorded URL (or its `app` service's). */
+export function addAppHosts(name: string, hosts: string[], options: { root?: string } = {}): AppUrlRecord {
+  const root = options.root ?? process.cwd();
+  const current = readAppUrl(name, { root });
+  if (!current) throw new Error(appUrlUnsetMessage(name));
+  const all = [...new Set([...(current.hosts ?? []), ...hosts.map((host) => assertAppHost(host, name, root))])].sort();
+  // hosts beside the World's own `app` service keep no URL: they follow the service wherever a boot puts it
+  const record: AppUrlRecord = current.via === 'service' ? { world: current.world, via: 'service', hosts: all } as AppUrlRecord : { ...current, hosts: all };
+  writeFileSync(appUrlFile(root, name), `${JSON.stringify(record, null, 2)}\n`);
+  return current.via === 'service' ? { ...current, hosts: all } : record;
+}
+
+/** The listening TCP ports of a live pid, via lsof (macOS + Linux). */
+function listeningTcpPorts(pid: number): number[] {
+  const result = spawnSync('lsof', ['-a', '-p', String(pid), '-iTCP', '-sTCP:LISTEN', '-P', '-n', '-Fn'], { encoding: 'utf8' });
+  if (result.error) {
+    throw new Error(`volter-world app-url: \`lsof\` is unavailable (${result.error.message}) — pass the port, or --set the URL directly`);
+  }
+  const ports = new Set<number>();
+  for (const line of (result.stdout ?? '').split('\n')) {
+    if (!line.startsWith('n')) continue;
+    const port = Number(line.slice(line.lastIndexOf(':') + 1));
+    if (Number.isInteger(port) && port > 0 && port <= 65535) ports.add(port);
+  }
+  return [...ports].sort((a, b) => a - b);
+}
+
+function pidIsLive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/** One TCP connection attempt to 127.0.0.1:<port> — is anything listening RIGHT NOW? */
+function tcpListening(port: number, timeoutMs = 1500): Promise<boolean> {
+  return new Promise((resolvePromise) => {
+    const socket = net.connect({ port, host: '127.0.0.1' });
+    const done = (ok: boolean): void => {
+      socket.destroy();
+      resolvePromise(ok);
+    };
+    socket.once('connect', () => done(true));
+    socket.once('error', () => done(false));
+    socket.setTimeout(timeoutMs, () => done(false));
+  });
+}
+
+/**
+ *`--detect <pid|port>`: resolve the app URL off what is ALREADY listening and record it.
+ * Disambiguation (both are just numbers): a live pid with listening ports wins — its single
+ * listening port is the app; several listening ports is a loud error (name the port instead).
+ * Otherwise the number is tried as a loopback port and must actually be listening. Detection
+ * that finds nothing refuses loudly rather than recording a URL nothing serves.
+ */
+export async function detectAppUrl(name: string, target: string, options: { root?: string } = {}): Promise<AppUrlRecord> {
+  const numeric = Number(target);
+  if (!Number.isInteger(numeric) || numeric <= 0) {
+    throw new Error(`volter-world app-url: --detect wants a pid or a port, got "${target}"`);
+  }
+  if (pidIsLive(numeric)) {
+    const ports = listeningTcpPorts(numeric);
+    if (ports.length === 1) {
+      return setAppUrl(name, `http://127.0.0.1:${ports[0]}`, { ...options, via: 'detect', detail: `detected from pid ${numeric} (listening on ${ports[0]})` });
+    }
+    if (ports.length > 1) {
+      throw new Error(
+        `volter-world app-url: pid ${numeric} is listening on ${ports.length} ports (${ports.join(', ')}) — `
+        + `ambiguous. Detect the app's port directly (--detect <port>) or record it explicitly (--set <url>).`,
+      );
+    }
+    // a live pid with NO listeners: fall through — the number was probably meant as a port
+  }
+  if (numeric <= 65535 && await tcpListening(numeric)) {
+    return setAppUrl(name, `http://127.0.0.1:${numeric}`, { ...options, via: 'detect', detail: `port ${numeric} is listening on 127.0.0.1` });
+  }
+  throw new Error(
+    `volter-world app-url: nothing to detect from "${target}" — it is not a live pid with a listening TCP port, `
+    + `and nothing is listening on 127.0.0.1:${target}. Boot the app first, then register its URL (--set <url> once it listens).`,
+  );
+}
+
+/**
+ * The recorded app URL of `name`, or the `app` service's assigned URL when nothing was recorded
+ * (the world-boots-the-app convention), or null. Null is the CALLER's loud-error cue — the CLI
+ * turns it into exit 1 with the registration recipe; a library consumer decides for itself.
+ */
+export function readAppUrl(name: string, options: { root?: string } = {}): AppUrlRecord | null {
+  const root = options.root ?? process.cwd();
+  const status = statusWorld(name, root); // loud when the world does not exist at all
+  const file = appUrlFile(root, name);
+  const app = status.services['app'];
+  if (existsSync(file)) {
+    const record = JSON.parse(readFileSync(file, 'utf8')) as AppUrlRecord;
+    // hosts recorded beside the World's own `app` service: its URL is this boot's
+    if (!record.url && app?.url !== undefined) return { world: status.name, url: app.url, via: 'service', detail: 'the world\'s own "app" service', ...(record.hosts ? { hosts: record.hosts } : {}) };
+    if (record.url) return record;
+  }
+  if (app?.url !== undefined) {
+    return { world: status.name, url: app.url, via: 'service', detail: 'the world\'s own "app" service (nothing was recorded)' };
+  }
+  return null;
+}
+
+/** The message the CLI prints when no app URL is known — the registration recipe, not a guess. */
+export function appUrlUnsetMessage(name: string): string {
+  return (
+    `World ${name} has no recorded app URL.\n`
+    + `If the app is booted OUTSIDE the world (the attach pattern), the booter registers it as the LAST boot step:\n`
+    + `  volter-world app-url ${name} --set http://127.0.0.1:<port>    # or: --detect <pid|port>\n`
+    + `A world that boots the app itself can declare an "app" service (type "process") — its URL answers automatically.`
+  );
+}

package/src/attach.ts

@@ -0,0 +1,117 @@
+// The attach surface of the two-part model (docs/guides/route-a-cli-through-the-world.md): resolving a world
+// reference and deriving the world manifest — the single document a world
+// publishes and every attachment mechanism consumes. `world.env` /
+// `instance.json` remain the local renderings; this module derives the manifest
+// FROM them (it invents nothing). Attaching itself stays thin: `--via env`
+// delegates to runWithWorldEnv, `--via direct` prints the manifest. Reflect and
+// remote refs are proposals (docs/guides/route-a-cli-through-the-world.md) and are refused loudly, never
+// silently degraded.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { activeVendorMap } from './redirect-proxy.ts';
+import { statusWorld } from './runtime.ts';
+
+export const WORLD_REF_FILE = '.volter-world';
+
+export type WorldRefSource = 'explicit' | 'env' | 'file';
+
+export interface ResolvedWorldRef {
+  ref: string;
+  source: WorldRefSource;
+  /** set when source === 'file' — the .volter-world file that supplied the ref */
+  file?: string;
+}
+
+/** A world reference is remote when it is a URL; every other ref is a local world name. */
+export function isRemoteWorldRef(ref: string): boolean {
+  return /^https?:\/\//i.test(ref);
+}
+
+/** Find the nearest .volter-world file from `cwd` upward. First non-empty,
+ * non-comment line is the ref (à la .nvmrc). */
+export function findWorldRefFile(cwd: string): { file: string; ref: string } | undefined {
+  let dir = resolve(cwd);
+  for (;;) {
+    const candidate = join(dir, WORLD_REF_FILE);
+    if (existsSync(candidate)) {
+      const line = readFileSync(candidate, 'utf8')
+        .split('\n')
+        .map((entry) => entry.trim())
+        .find((entry) => entry.length > 0 && !entry.startsWith('#'));
+      if (line) return { file: candidate, ref: line };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/** Resolution order (docs/guides/route-a-cli-through-the-world.md): explicit argument → VOLTER_WORLD env var →
+ * nearest committed .volter-world file. No silent machine-default fallback:
+ * a missing ref is an explicit, actionable error. */
+export function resolveWorldRef(
+  explicit: string | undefined,
+  options: { cwd?: string; env?: Record<string, string | undefined> } = {},
+): ResolvedWorldRef {
+  if (explicit !== undefined && explicit.length > 0) return { ref: explicit, source: 'explicit' };
+  const env = options.env ?? process.env;
+  const fromEnv = env.VOLTER_WORLD;
+  if (fromEnv !== undefined && fromEnv.trim().length > 0) return { ref: fromEnv.trim(), source: 'env' };
+  const fromFile = findWorldRefFile(options.cwd ?? process.cwd());
+  if (fromFile) return { ref: fromFile.ref, source: 'file', file: fromFile.file };
+  throw new Error(
+    `no world reference: pass one (volter-world attach <world> …), set VOLTER_WORLD, or commit a ${WORLD_REF_FILE} file`,
+  );
+}
+
+/** The manifest (docs/guides/route-a-cli-through-the-world.md): what a world publishes to its attachers. */
+export interface WorldManifest {
+  name: string;
+  /** vendor host → twin endpoint, exactly the map the injector/proxy redirect */
+  vendors: Record<string, string>;
+  /** session CA (PEM) when the world has one, else null */
+  ca: string | null;
+  /** attachment traffic proxy when present, else null */
+  proxy: string | null;
+  /** suggested fake credentials — the world env minus runtime internals */
+  env: Record<string, string>;
+  /** a hosted world's byte-stream doors, by service id: the WebSocket that carries the protocol and the
+   *  env its client reads, `${host}`/`${port}` being the attacher's loopback bridge
+   *  (@volter/world-core/stream-bridge) */
+  streams?: Record<string, { protocol: string; url: string; env: Record<string, string> }>;
+}
+
+// Internal runtime vars are plumbing, not suggested credentials. CA-trust
+// bundle vars are local renderings of `ca` (they hold machine-local paths), so
+// a manifest never carries them — an attacher re-renders trust from `ca`.
+const MANIFEST_ENV_EXCLUDED =
+  /^(volter_world_|node_options$|twin_inject$|no_proxy$|https?_proxy$|node_extra_ca_certs$|ssl_cert_file$|(aws|curl|requests)_ca_bundle$)/i;
+
+/** Derive the manifest from a world's generated env map (the local rendering).
+ * Pure — the CA is inlined only when its file is readable. */
+export function deriveWorldManifest(name: string, worldEnv: Record<string, string | undefined>): WorldManifest {
+  const vendors = activeVendorMap(worldEnv);
+  const caPath = worldEnv.VOLTER_WORLD_CA;
+  let ca: string | null = null;
+  if (caPath && existsSync(caPath)) {
+    try {
+      ca = readFileSync(caPath, 'utf8');
+    } catch {
+      ca = null;
+    }
+  }
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(worldEnv)) {
+    if (value === undefined) continue;
+    if (MANIFEST_ENV_EXCLUDED.test(key)) continue;
+    if (/_TWIN_URL$/.test(key)) continue; // rendered as `vendors`, not credentials
+    env[key] = value;
+  }
+  return { name, vendors, ca, proxy: worldEnv.VOLTER_WORLD_PROXY ?? null, env };
+}
+
+/** The manifest of a local world instance (name resolved against `root` like every other verb). */
+export function worldManifest(name: string, root = process.cwd()): WorldManifest {
+  const status = statusWorld(name, root);
+  return deriveWorldManifest(name, status.env);
+}

package/src/branch.ts

@@ -0,0 +1,63 @@
+// `volter-world branch` and `checkout` — a branch is a base position in the mirror plus its own
+// log of changes, and a world is a branch with compute attached (docs/concepts/the-model.md).
+// `branch <world> <name>` boots a new world from the base's config and forks every twin's mirror
+// into it (core's `forkTwin`: a POINTER to the base at its current position — the base's whole
+// history, its own entries included, is the branch's parent; nothing is copied). `checkout <name>`
+// brings a stopped world back up from its own instance record, state intact.
+import { existsSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { captureHistory, historyAtInstant, forkTwin, stateGeneration, withAncestryLock, worldPaths, worldStateRoot } from '@volter/world-core';
+import { downWorld, saveWorldInstance, statusWorld, upWorld } from './runtime.ts';
+import type { WorldInstance } from './schema.ts';
+
+export type BranchOptions = { root?: string; envFile?: string; now?: Date; /** branch from a point in the base's history: an instant, or a position per twin (contract "Just like Neon", 3) */ at?: { instant?: string; positions?: Record<string, number>; views?: Record<string, string> } };
+
+function stateServices(controlRoot: string): string[] {
+  const stateRoot = worldStateRoot(controlRoot);
+  if (!existsSync(stateRoot)) return [];
+  return readdirSync(stateRoot, { withFileTypes: true }).filter((e) => e.isDirectory() && ['events.jsonl', 'actions.jsonl', 'branch.json'].some((f) => existsSync(join(stateRoot, e.name, f)))).map((e) => e.name).sort();
+}
+
+/** A new world over the base's mirrors. */
+export async function branchWorld(base: string, name: string, options: BranchOptions = {}): Promise<{ instance: WorldInstance; forked: Record<string, string[]> }> {
+  const root = resolve(options.root ?? process.cwd());
+  const from = statusWorld(base, root);
+  if (name === base) throw new Error(`volter-world branch: the branch needs a name other than the base's ("${base}")`);
+  const envFile = options.envFile ?? join(dirname(from.envFile), `${name}.world.env`);
+  const at = (options.now ?? new Date()).toISOString();
+  // Capture source identity before awaiting child compute. A concurrent reset may win;
+  // in that case forking fails and the task-owned child is torn down, never an empty success.
+  const source = withAncestryLock(() => Object.keys(from.services).sort().map(service => {
+    const fromRoot = join(from.dirs.data, service);
+    return { service, fromRoot, states: stateServices(fromRoot).map(state => {
+      let view = options.at?.views?.[service] ?? options.at?.views?.[state] ?? captureHistory(state, fromRoot).view;
+      const timed = options.at?.instant ? historyAtInstant(state, options.at.instant, fromRoot, view) : undefined;
+      if (timed) view = timed.view;
+      const position = options.at?.positions?.[service] ?? options.at?.positions?.[state] ?? timed?.position;
+      return { state, view, position, generation: stateGeneration(worldPaths(state, fromRoot).dir) };
+    }) };
+  }));
+  const instance = await upWorld(existsSync(from.configPath) ? from.configPath : from.config, { name, root, mode: from.mode, envFile });
+  const forked: Record<string, string[]> = {};
+  try {
+    if (from.origin) { instance.origin = { ...from.origin }; saveWorldInstance(instance); }
+    for (const { service, fromRoot, states } of source) {
+      const toRoot = join(instance.dirs.data, service);
+      for (const { state, generation, view, position: pos } of states) {
+        forkTwin({ service: state, toRoot, fromRoot, view, expectedGeneration: generation, occurredAt: at, ...(pos !== undefined ? { at: pos } : {}) });
+      }
+      if (states.length) forked[service] = states.map(s => s.state);
+    }
+  } catch (error) {
+    await downWorld(name, root, { purge: true, expectedCreatedAt: instance.createdAt });
+    throw error;
+  }
+  return { instance, forked };
+}
+
+/** A stopped world back up, from its own record. */
+export async function checkoutWorld(name: string, options: { root?: string } = {}): Promise<WorldInstance> {
+  const root = resolve(options.root ?? process.cwd());
+  const was = statusWorld(name, root);
+  return upWorld(existsSync(was.configPath) ? was.configPath : was.config, { name, root, mode: was.mode, envFile: was.envFile, keepState: true });
+}

package/src/browser-proxy-cli.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// Browser proxy launcher for fullstack app worlds. This is APP/WORLD orchestration glue
+// (it wires specific app vendors + app URLs from env), so it lives in @volter/world-runtime,
+// NOT in the vendor-agnostic kernel — control-plane must never name a vendor (A2). The kernel
+// only exports the vendor-INDEPENDENT `createTwinProxy` utility; choosing which vendors a given
+// app world proxies is the orchestrator's job.
+import { createTwinProxy } from '@volter/world-core';
+
+const port = Number(process.env.PORT || 0);
+const target = process.env.TARGET_URL;
+if (!target) throw new Error('TARGET_URL is required');
+
+const map = {};
+if (process.env.CLERK_TWIN_URL) {
+  map.clerk = {
+    origin: process.env.CLERK_TWIN_URL,
+    apiPathPrefix: '/v1/',
+    loaderHost: 'https://api.clerk.com',
+  };
+  map.clerkLoader = {
+    origin: process.env.CLERK_TWIN_URL,
+    apiPathPrefix: '/npm/',
+  };
+}
+if (process.env.RUNHUMAN_API_URL || process.env.API_URL) {
+  map.runhumanApi = {
+    origin: process.env.RUNHUMAN_API_URL || process.env.API_URL,
+    apiPathPrefix: '/api',
+  };
+}
+
+const redirectOrigins = [
+  process.env.RUNHUMAN_WEB_URL,
+  process.env.RUNHUMAN_LEARN_URL,
+  process.env.RUNHUMAN_STATIC_URL,
+  process.env.RUNHUMAN_API_URL,
+  process.env.API_URL,
+].filter(Boolean);
+
+const proxy = createTwinProxy({ target, map, redirectOrigins, port });
+process.stdout.write(`[browser-proxy] http://127.0.0.1:${proxy.port} -> ${target} (${Object.keys(map).join(', ') || 'no browser vendors'})\n`);
+await keepProcessAlive();

package/src/ca-trust.ts

@@ -0,0 +1,57 @@
+import { createHash, randomUUID, X509Certificate } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import * as tls from 'node:tls';
+
+export class CaTrustError extends Error {}
+export type CaTrustInputs = NodeJS.ProcessEnv | NodeJS.ProcessEnv[];
+
+/** Per-client trust, materialized only when a caller attaches. Never modify the signing CA. */
+export function sessionTrustEnv(caCertPath: string, inputs: CaTrustInputs = process.env): Record<string, string> {
+  const callers = Array.isArray(inputs) ? inputs : [inputs];
+  const files = new Map<string, string>();
+  const read = (path: string): string => {
+    if (files.has(path)) return files.get(path)!;
+    try {
+      const contents = readFileSync(path, 'utf8');
+      const pattern = /-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g;
+      const certificates = contents.match(pattern) ?? [];
+      if (!certificates.length || /-----BEGIN|-----END/.test(contents.replace(pattern, ''))) throw new Error('expected complete PEM certificates');
+      const pem = certificates.map(cert => new X509Certificate(cert).toString().trim()).join('\n');
+      files.set(path, pem);
+      return pem;
+    }
+    catch (error) { throw new CaTrustError(`Cannot read configured CA file ${path}: ${String(error)}`); }
+  };
+  const session = read(caCertPath);
+  const extra = callers.flatMap(caller => caller.NODE_EXTRA_CA_CERTS ? [read(caller.NODE_EXTRA_CA_CERTS)] : []).join('\n');
+  // getCACertificates is newer than our minimum Node version; bundled roots also cover callers
+  // whose current OpenSSL defaults have already been replaced by a session-only CA file.
+  const defaults = typeof tls.getCACertificates === 'function' ? tls.getCACertificates('default') : [];
+  const publicRoots = [...new Set([...tls.rootCertificates, ...defaults].map(cert => new X509Certificate(cert).toString().trim()))].join('\n');
+  const bundle = (contents: string): string => {
+    const certificates = contents.match(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g) ?? [];
+    const pem = `${[...new Set(certificates.map(cert => cert.trim()))].sort().join('\n')}\n`;
+    const path = join(dirname(caCertPath), `trust-${createHash('sha256').update(pem).digest('hex')}.pem`);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+      if (!existsSync(path) || readFileSync(path, 'utf8') !== pem) {
+        writeFileSync(temporary, pem, { flag: 'wx', mode: 0o600 });
+        renameSync(temporary, path);
+      }
+    } catch (error) {
+      try { rmSync(temporary, { force: true }); }
+      catch (cleanupError) { throw new CaTrustError(`Cannot materialize session trust bundle: ${String(error)}; cleanup: ${String(cleanupError)}`); }
+      throw new CaTrustError(`Cannot materialize session trust bundle: ${String(error)}`);
+    }
+    return path;
+  };
+  const env: Record<string, string> = {
+    NODE_EXTRA_CA_CERTS: extra ? bundle(`${extra}\n${session}`) : caCertPath,
+  };
+  for (const key of ['SSL_CERT_FILE', 'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE', 'AWS_CA_BUNDLE', 'GIT_SSL_CAINFO']) {
+    const configured = callers.flatMap(caller => caller[key] ? [read(caller[key]!)] : []).join('\n');
+    env[key] = bundle(`${publicRoots}\n${extra}\n${configured}\n${session}`);
+  }
+  return env;
+}