@volter/world-runtime 2.0.0

package/dist/src/ancestry.d.ts

@@ -0,0 +1,2 @@
+export declare function assertWorldStateRemovable(root: string, path: string): void;
+export declare function removeWorldState<T>(root: string, path: string, remove: () => T): T;

package/dist/src/ancestry.js

@@ -0,0 +1,42 @@
+// 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, path) {
+    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) => { 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, path) {
+    withAncestryLock(() => { checkWorldAncestry(root, path); assertStateRemovable(path); });
+}
+export function removeWorldState(root, path, remove) {
+    return withStateRemoval(path, remove, () => checkWorldAncestry(root, path));
+}

package/dist/src/app-url.d.ts

@@ -0,0 +1,47 @@
+/** 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 declare function appUrlFile(root: string, name: string): string;
+/** 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 declare function setAppUrl(name: string, url: string, options?: {
+    root?: string;
+    via?: Exclude<AppUrlSource, 'service'>;
+    detail?: string;
+}): AppUrlRecord;
+/** Record `hosts` as the app's own production hostnames, beside its recorded URL (or its `app` service's). */
+export declare function addAppHosts(name: string, hosts: string[], options?: {
+    root?: string;
+}): AppUrlRecord;
+/**
+ *`--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 declare function detectAppUrl(name: string, target: string, options?: {
+    root?: string;
+}): Promise<AppUrlRecord>;
+/**
+ * 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 declare function readAppUrl(name: string, options?: {
+    root?: string;
+}): AppUrlRecord | null;
+/** The message the CLI prints when no app URL is known — the registration recipe, not a guess. */
+export declare function appUrlUnsetMessage(name: string): string;

package/dist/src/app-url.js

@@ -0,0 +1,239 @@
+// `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.js";
+import { loadInject } from "./inject-map.js";
+import { packFacts } from "./pack-facts.js";
+export function appUrlFile(root, name) {
+    return join(instanceDir(root, name), 'app-url.json');
+}
+function assertHttpUrl(url) {
+    let parsed;
+    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, url, options = {}) {
+    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')).hosts : undefined;
+    const record = {
+        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, world, root) {
+    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) {
+    const out = [];
+    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, hosts, options = {}) {
+    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 = current.via === 'service' ? { world: current.world, via: 'service', hosts: all } : { ...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) {
+    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();
+    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) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/** One TCP connection attempt to 127.0.0.1:<port> — is anything listening RIGHT NOW? */
+function tcpListening(port, timeoutMs = 1500) {
+    return new Promise((resolvePromise) => {
+        const socket = net.connect({ port, host: '127.0.0.1' });
+        const done = (ok) => {
+            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, target, options = {}) {
+    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, options = {}) {
+    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'));
+        // 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) {
+    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/dist/src/attach.d.ts

@@ -0,0 +1,48 @@
+export declare 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 declare function isRemoteWorldRef(ref: string): boolean;
+/** Find the nearest .volter-world file from `cwd` upward. First non-empty,
+ * non-comment line is the ref (à la .nvmrc). */
+export declare function findWorldRefFile(cwd: string): {
+    file: string;
+    ref: string;
+} | undefined;
+/** 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 declare function resolveWorldRef(explicit: string | undefined, options?: {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+}): ResolvedWorldRef;
+/** 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>;
+    }>;
+}
+/** 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 declare function deriveWorldManifest(name: string, worldEnv: Record<string, string | undefined>): WorldManifest;
+/** The manifest of a local world instance (name resolved against `root` like every other verb). */
+export declare function worldManifest(name: string, root?: string): WorldManifest;

package/dist/src/attach.js

@@ -0,0 +1,87 @@
+// 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.js";
+import { statusWorld } from "./runtime.js";
+export const WORLD_REF_FILE = '.volter-world';
+/** A world reference is remote when it is a URL; every other ref is a local world name. */
+export function isRemoteWorldRef(ref) {
+    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) {
+    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, options = {}) {
+    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`);
+}
+// 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, worldEnv) {
+    const vendors = activeVendorMap(worldEnv);
+    const caPath = worldEnv.VOLTER_WORLD_CA;
+    let ca = null;
+    if (caPath && existsSync(caPath)) {
+        try {
+            ca = readFileSync(caPath, 'utf8');
+        }
+        catch {
+            ca = null;
+        }
+    }
+    const env = {};
+    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, root = process.cwd()) {
+    const status = statusWorld(name, root);
+    return deriveWorldManifest(name, status.env);
+}

package/dist/src/branch.d.ts

@@ -0,0 +1,20 @@
+import type { WorldInstance } from './schema.js';
+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>;
+    };
+};
+/** A new world over the base's mirrors. */
+export declare function branchWorld(base: string, name: string, options?: BranchOptions): Promise<{
+    instance: WorldInstance;
+    forked: Record<string, string[]>;
+}>;
+/** A stopped world back up, from its own record. */
+export declare function checkoutWorld(name: string, options?: {
+    root?: string;
+}): Promise<WorldInstance>;

package/dist/src/branch.js

@@ -0,0 +1,65 @@
+// `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.js";
+function stateServices(controlRoot) {
+    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, name, options = {}) {
+    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 = {};
+    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, options = {}) {
+    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/dist/src/browser-proxy-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/browser-proxy-cli.js

@@ -0,0 +1,41 @@
+#!/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/dist/src/ca-trust.d.ts

@@ -0,0 +1,5 @@
+export declare 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 declare function sessionTrustEnv(caCertPath: string, inputs?: CaTrustInputs): Record<string, string>;