@volter/world-host 2.0.0

package/README.md

@@ -0,0 +1,15 @@
+# @volter/world-host — worlds under one URL
+
+The hosting shell mounts bare worlds from `<dir>/<org>/<world>/` under one origin. Each World
+has its own tokens, serve record, vendor roots and credentials. A mounted World exposes the same
+API as `volter world serve`.
+
+`volter-host serve --dir <worlds>` starts the host. Its admin API inventories, provisions,
+rotates tokens and removes worlds without restarting the host. The host admin token does not
+open a World's API, and World tokens do not open the host admin API. When installed,
+`@volter/world-console` supplies the console.
+
+- [Host worlds for a team](../../docs/guides/host-worlds-for-a-team.md) — executed setup guide.
+- [HTTP API](../../docs/reference/http-api.md#the-hosting-product) — host endpoints and tokens.
+- [CLI reference](../../docs/reference/cli.md#the-hosting-product) — command and flags.
+- [The model](../../docs/concepts/the-model.md) — the semantics every hosted World follows.

package/dist/src/cli.d.ts

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

package/dist/src/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// volter-host — worlds under one URL (see twins-host.ts).
+//
+//   volter-host serve --dir <worlds> [--host H] [--port P] [--url <origin reached at>] [--console-port C] [--console-url <console origin reached at; same site as --url, or its mirror links are refused>]
+//
+// `<dir>/<org>/<world>/` is a bare world (`volter world init --bare <org>/<world>`). Each world's
+// token is in its own `.volter/token`; each world's serve record names this host's URL. The admin
+// token (`<dir>/.volter-host/admin`) opens the host's own doors — `/-/worlds` — and is printed once.
+import { createWorldHost } from "./twins-host.js";
+const cmd = process.argv[2];
+const rest = process.argv.slice(3);
+const value = (flag) => { const i = rest.indexOf(flag); return i >= 0 ? rest[i + 1] : undefined; };
+if (cmd === 'serve') {
+    const dir = value('--dir');
+    if (!dir) {
+        process.stderr.write('volter-host serve --dir <worlds> [--host H] [--port P] [--url <origin reached at>] [--console-port C] [--console-url <console origin reached at; same site as --url, or its mirror links are refused>]\n');
+        process.exit(2);
+    }
+    // the console mounts when it is installed beside the host; a host without it serves the doors alone
+    const console = await (async () => {
+        try {
+            const mod = await import('@volter/world-console');
+            return mod.createConsole();
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    const host = await createWorldHost({ dir, ...(value('--host') ? { host: value('--host') } : {}), ...(value('--port') ? { port: Number(value('--port')) } : {}), ...(value('--url') ? { advertise: value('--url') } : {}), ...(value('--console-port') ? { consolePort: Number(value('--console-port')) } : {}), ...(value('--console-url') ? { consoleAdvertise: value('--console-url') } : {}), ...(console ? { console } : {}), announce: (line) => process.stdout.write(`${line}\n`) });
+    process.stdout.write(`host ready  ${host.url}  ${host.worlds.length} world${host.worlds.length === 1 ? '' : 's'}\nadmin token  ${host.adminToken}\n${host.console ? `console      ${host.console}\n` : ''}`);
+    const shutdown = async () => { await host.stop(); process.exit(0); };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+}
+else {
+    process.stderr.write('usage: volter-host serve --dir <worlds> [--host H] [--port P] [--url <origin reached at>] [--console-port C] [--console-url <console origin reached at; same site as --url, or its mirror links are refused>]\n');
+    process.exit(2);
+}

package/dist/src/twins-host.d.ts

@@ -0,0 +1,55 @@
+import { CONSOLE_BASE, type ConsoleMount } from '@volter/world-runtime';
+export type WorldHostOptions = {
+    /** the directory of worlds: `<dir>/<org>/<world>/` is a bare world */
+    dir: string;
+    /** keep the kernel's request journal for every twin served here (layer 8: the world's request report); on unless told otherwise */
+    requestJournal?: boolean;
+    host?: string;
+    port?: number;
+    announce?: (line: string) => void;
+    /** the console, when installed (`@volter/world-console`): served on a listener of its own, its doors
+     *  forwarded here, so no script a twin serves shares its origin (world-runtime console-apart.ts) */
+    console?: ConsoleMount;
+    /** the console's port; the host's port + 1 when absent (a stable address), else one the system picks */
+    consolePort?: number;
+    /** the origin the console is REACHED at, when it differs from its bind address (as `advertise`) */
+    consoleAdvertise?: string;
+    /** The origin this host is REACHED at, when it differs from the bind address — a container binding
+     *  0.0.0.0 behind a port map, a host behind a proxy. Every world's `base`, its serve record and the
+     *  printed URLs use it; without it the bind address stands (loopback runs). */
+    advertise?: string;
+};
+export { CONSOLE_BASE, type ConsoleMount };
+export type WorldHostHandle = {
+    url: string;
+    port: number;
+    adminToken: string;
+    console: string | null;
+    worlds: Array<{
+        name: string;
+        base: string;
+    }>;
+    stop: () => Promise<void>;
+};
+/** One row of the inventory: what the platform records and what the console is handed. */
+export type WorldInventoryRow = {
+    org: string;
+    world: string;
+    name: string;
+    base: string;
+    token: string;
+    readToken: string;
+    twins: Array<{
+        vendor: string;
+        protocol: unknown;
+        root: unknown;
+    }>;
+};
+/** The bare worlds under a directory: `<dir>/<org>/<world>/.volter/world.json`. */
+export declare function worldsUnder(dir: string): Array<{
+    name: string;
+    root: string;
+}>;
+/** The host's admin token: minted once, kept at `<dir>/.volter-host/admin` (0600). */
+export declare function adminTokenFor(dir: string): string;
+export declare function createWorldHost(options: WorldHostOptions): Promise<WorldHostHandle>;

package/dist/src/twins-host.js

@@ -0,0 +1,225 @@
+// THE HOST (company contract "Just like Neon", 4; "The hosted product's doors"): worlds under ONE
+// URL. A directory holds worlds — `<dir>/<org>/<world>/` is a bare world — and the host mounts each
+// on the same port under its served name: `/<org>/<world>/<vendor>/…` is the twin's wire and
+// `/-/<org>/<world>/…` its doors, exactly as `volter world serve` gives one world. Every world keeps
+// its own tokens, its own serve record (the host's URL), its own roots and credentials. A world is
+// served once: a world already served elsewhere refuses to mount here, by name and pid.
+//
+// The host's OWN doors are the hosted product's: an ADMIN token — minted once, kept beside the
+// directory (`<dir>/.volter-host/admin`, 0600), stable across restarts, never an env var — opens
+// `/-/worlds`: the inventory (every world, its address, its tokens, its twins), provision (a new
+// bare world mounted without a restart), rotate (both tokens anew; the old die with the response)
+// and remove. The admin token opens NOTHING under a world, and a world's token opens nothing here:
+// the platform holds the admin token, the console holds world tokens, neither is the other.
+//
+// Nothing of the vendor lives here — no arms, no keys, no folds: the host is the shell; the kernel
+// serves. The v1 host (namespaces, links, the push flip, the R2 shell) left with v1.
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { assertStateRemovable, serveHttp, withAncestryLock, withStateRemoval } from '@volter/world-core';
+import { dirname, join, resolve } from 'node:path';
+import { assertWorldStateRemovable, CONSOLE_BASE, consoleRedirect, initWorld, loadWorldConfig, mountWorld, serveConsoleApart, TOKEN_HEADER } from '@volter/world-runtime';
+export { CONSOLE_BASE };
+const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+/** The bare worlds under a directory: `<dir>/<org>/<world>/.volter/world.json`. */
+export function worldsUnder(dir) {
+    const out = [];
+    const base = resolve(dir);
+    if (!existsSync(base))
+        return out;
+    for (const org of readdirSync(base, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules')) {
+        for (const world of readdirSync(join(base, org.name), { withFileTypes: true }).filter((e) => e.isDirectory())) {
+            const root = join(base, org.name, world.name);
+            if (existsSync(join(root, '.volter', 'world.json')))
+                out.push({ name: `${org.name}/${world.name}`, root });
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** The host's admin token: minted once, kept at `<dir>/.volter-host/admin` (0600). */
+export function adminTokenFor(dir) {
+    const path = join(resolve(dir), '.volter-host', 'admin');
+    try {
+        const t = readFileSync(path, 'utf8').trim();
+        if (t.startsWith('tok_a_'))
+            return t;
+    }
+    catch { /* none yet */ }
+    const token = `tok_a_${Buffer.from(crypto.getRandomValues(new Uint8Array(24))).toString('base64url')}`;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${token}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return token;
+}
+export async function createWorldHost(options) {
+    // the twins this host boots inherit its env: the kernel's journal switch, set by the product, not by an operator
+    if (options.requestJournal !== false)
+        process.env.VOLTER_TWIN_REQUEST_JOURNAL = '1';
+    const dir = resolve(options.dir);
+    const found = worldsUnder(dir);
+    if (found.length === 0)
+        throw new Error(`no worlds under ${dir} — a world is \`<dir>/<org>/<world>/\` with \`.volter/world.json\` (\`volter world init --bare <org>/<world>\` makes one)`);
+    const adminToken = adminTokenFor(dir);
+    const mount = async (w) => {
+        const config = loadWorldConfig(join(w.root, '.volter', 'world.json'), w.root).config;
+        return mountWorld(config.id, { root: w.root });
+    };
+    const byServed = new Map();
+    for (const w of found)
+        byServed.set(w.name, await mount(w));
+    const host = options.host ?? '127.0.0.1';
+    let url = '';
+    const json = (body, status = 200) => Response.json(body, { status });
+    /** One inventory row, the twins read through the world's own status door with its own token. */
+    const row = async (m) => {
+        const [org, world] = m.served.split('/');
+        const twins = [];
+        for (const vendor of m.twins()) {
+            const res = await m.handle(new Request(`${url}/-/${m.served}/twins/${vendor}/status`, { headers: { [TOKEN_HEADER]: m.token } }));
+            const status = res.ok ? (await res.json()) : {};
+            twins.push({ vendor, protocol: status.protocol ?? null, root: status.root ?? null });
+        }
+        return { org, world, name: m.served, base: `${url}/${m.served}`, token: m.token, readToken: m.readToken, twins };
+    };
+    const checkAncestry = (path) => {
+        for (const world of worldsUnder(dir))
+            assertWorldStateRemovable(world.root, path);
+        assertStateRemovable(path);
+    };
+    const admin = async (request, path) => {
+        if (request.headers.get(TOKEN_HEADER) !== adminToken)
+            return json({ error: 'the host\'s doors open to the admin token' }, 401);
+        const m = /^\/-\/worlds(?:\/([^/]+)\/([^/]+)(?:\/(rotate))?)?$/.exec(path);
+        if (!m)
+            return json({ error: `no such door: ${request.method} ${path}` }, 404);
+        const [, org, world, verb] = m;
+        if (!org) {
+            if (request.method === 'GET') {
+                const rows = [];
+                for (const w of byServed.values())
+                    rows.push(await row(w));
+                return json({ worlds: rows });
+            }
+            if (request.method === 'POST') {
+                let body;
+                try {
+                    body = (await request.json());
+                }
+                catch {
+                    return json({ error: 'provision: { org, world, vendors }' }, 400);
+                }
+                const vendors = Array.isArray(body.vendors) ? body.vendors.filter((v) => typeof v === 'string' && NAME.test(v)) : [];
+                if (!body.org || !body.world || !NAME.test(body.org) || !NAME.test(body.world) || vendors.length === 0)
+                    return json({ error: 'provision: { org, world, vendors: [vendor, …] } — names are letters, digits, . _ -' }, 400);
+                const name = `${body.org}/${body.world}`;
+                const root = join(dir, body.org, body.world);
+                if (byServed.has(name) || existsSync(root))
+                    return json({ error: `${name} exists` }, 409);
+                let acquired;
+                try {
+                    mkdirSync(root, { recursive: true });
+                    const result = initWorld(body.world, root, { root, vendors, bare: name });
+                    if (!result.ok)
+                        throw new Error(`init refused: ${JSON.stringify(result.plan)}`);
+                    const mounted = await mount({ name, root });
+                    acquired = mounted;
+                    await mounted.boot(url);
+                    byServed.set(name, mounted);
+                    options.announce?.(`serving  ${name}  ${url}/${name}`);
+                    return json(await row(mounted), 201);
+                }
+                catch (error) {
+                    try {
+                        if (acquired)
+                            await acquired.stop();
+                        withStateRemoval(root, () => rmSync(root, { recursive: true, force: true }));
+                        byServed.delete(name);
+                    }
+                    catch (cleanup) {
+                        if (acquired)
+                            byServed.set(name, acquired);
+                        return json({ error: `provision ${name} failed; cleanup incomplete, World retained: ${cleanup instanceof Error ? cleanup.message : String(cleanup)}` }, 500);
+                    }
+                    return json({ error: `provision ${name}: ${error instanceof Error ? error.message : String(error)}` }, 500);
+                }
+            }
+            return json({ error: `no such door: ${request.method} ${path}` }, 404);
+        }
+        const name = `${org}/${world}`;
+        const mounted = byServed.get(name);
+        if (!mounted)
+            return json({ error: `no world ${name} here` }, 404);
+        if (verb === 'rotate' && request.method === 'POST')
+            return json({ name, ...mounted.rotate() });
+        if (!verb && request.method === 'DELETE') {
+            try {
+                withAncestryLock(() => checkAncestry(mounted.root));
+                await mounted.stop();
+                withStateRemoval(mounted.root, () => rmSync(mounted.root, { recursive: true, force: true }), () => checkAncestry(mounted.root));
+                byServed.delete(name);
+                return json({ removed: name });
+            }
+            catch (error) {
+                return json({ error: error instanceof Error ? error.message : String(error) }, 409);
+            }
+        }
+        return json({ error: `no such door: ${request.method} ${path}` }, 404);
+    };
+    let consoleUrl = null;
+    const server = await serveHttp({
+        hostname: host, port: options.port ?? 0,
+        // This front serves many Worlds and lifecycle doors. Capturing one vendor identity
+        // here misattributes requests and can recreate a removed World after its response.
+        twinRequestJournal: false,
+        async fetch(request) {
+            const path = new URL(request.url).pathname;
+            const moved = consoleRedirect(request, consoleUrl ? consoleUrl.slice(0, -`${CONSOLE_BASE}/`.length) : null);
+            if (moved)
+                return moved;
+            if (path === '/-/ping')
+                return json({ ok: true, worlds: [...byServed.keys()], ...(consoleUrl ? { console: consoleUrl } : {}) });
+            if (path === '/-/worlds' || path.startsWith('/-/worlds/'))
+                return admin(request, path);
+            const m = /^\/(?:-\/)?([^/]+)\/([^/]+)/.exec(path);
+            const world = m ? byServed.get(`${m[1]}/${m[2]}`) : undefined;
+            if (!world)
+                return json({ error: `no world at ${path}: this host serves ${[...byServed.keys()].join(', ')}` }, 404);
+            return world.handle(request);
+        },
+    });
+    url = options.advertise ? options.advertise.replace(/\/+$/, '') : `http://${host}:${server.port}`;
+    let apart = null;
+    try {
+        for (const m of byServed.values()) {
+            await m.boot(url);
+            options.announce?.(`serving  ${m.served}  ${url}/${m.served}`);
+        }
+        if (options.console) {
+            // the console reaches the doors at this host's own address; the pages it serves name the advertised one
+            const internal = `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${server.port}`;
+            const serveApart = (port) => serveConsoleApart(options.console, { upstream: internal, worlds: url, hostname: host, port });
+            if (options.consolePort !== undefined)
+                apart = await serveApart(options.consolePort);
+            else {
+                try {
+                    apart = await serveApart((server.port ?? 0) ? (server.port ?? 0) + 1 : 0);
+                }
+                catch {
+                    apart = await serveApart(0);
+                }
+            }
+            consoleUrl = `${(options.consoleAdvertise ?? apart.url).replace(/\/+$/, '')}${CONSOLE_BASE}/`;
+        }
+    }
+    catch (error) {
+        await server.stop(true);
+        for (const m of byServed.values())
+            await m.stop().catch(() => undefined);
+        throw error;
+    }
+    return {
+        url, port: server.port ?? 0, adminToken, console: consoleUrl,
+        get worlds() { return [...byServed.values()].map((m) => ({ name: m.served, base: `${url}/${m.served}` })); },
+        stop: async () => { await apart?.server.stop(true); await server.stop(true); for (const m of byServed.values())
+            await m.stop(); },
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@volter/world-host",
+  "version": "2.0.0",
+  "description": "The hosted remote: worlds under one URL, each holding the canonical history of a real vendor account and its sealed credential — what a local world clones from and pushes to.",
+  "keywords": [
+    "twin",
+    "host",
+    "router",
+    "api"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "volter-host": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "build": "node ../../scripts/publish/build.mjs",
+    "prepack": "node ../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "@volter/world-core": "2.0.0",
+    "@volter/world-runtime": "2.0.0"
+  },
+  "peerDependencies": {
+    "@volter/world-console": "2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@volter/world-console": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@volter/world-console": "2.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/twins-host.d.ts",
+      "default": "./dist/src/twins-host.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ]
+}

package/src/cli.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// volter-host — worlds under one URL (see twins-host.ts).
+//
+//   volter-host serve --dir <worlds> [--host H] [--port P] [--url <origin reached at>] [--console-port C] [--console-url <console origin reached at; same site as --url, or its mirror links are refused>]
+//
+// `<dir>/<org>/<world>/` is a bare world (`volter world init --bare <org>/<world>`). Each world's
+// token is in its own `.volter/token`; each world's serve record names this host's URL. The admin
+// token (`<dir>/.volter-host/admin`) opens the host's own doors — `/-/worlds` — and is printed once.
+import { createWorldHost, type ConsoleMount } from './twins-host.ts';
+
+const cmd = process.argv[2];
+const rest = process.argv.slice(3);
+const value = (flag: string): string | undefined => { const i = rest.indexOf(flag); return i >= 0 ? rest[i + 1] : undefined; };
+
+if (cmd === 'serve') {
+  const dir = value('--dir');
+  if (!dir) { process.stderr.write('volter-host serve --dir <worlds> [--host H] [--port P] [--url <origin reached at>] [--console-port C] [--console-url <console origin reached at; same site as --url, or its mirror links are refused>]\n'); process.exit(2); }
+  // the console mounts when it is installed beside the host; a host without it serves the doors alone
+  const console = await (async (): Promise<ConsoleMount | undefined> => {
+    try { const mod = await import('@volter/world-console') as { createConsole: () => ConsoleMount }; return mod.createConsole(); } catch { return undefined; }
+  })();
+  const host = await createWorldHost({ dir, ...(value('--host') ? { host: value('--host')! } : {}), ...(value('--port') ? { port: Number(value('--port')) } : {}), ...(value('--url') ? { advertise: value('--url')! } : {}), ...(value('--console-port') ? { consolePort: Number(value('--console-port')) } : {}), ...(value('--console-url') ? { consoleAdvertise: value('--console-url')! } : {}), ...(console ? { console } : {}), announce: (line) => process.stdout.write(`${line}\n`) });
+  process.stdout.write(`host ready  ${host.url}  ${host.worlds.length} world${host.worlds.length === 1 ? '' : 's'}\nadmin token  ${host.adminToken}\n${host.console ? `console      ${host.console}\n` : ''}`);
+  const shutdown = async () => { await host.stop(); process.exit(0); };
+  process.on('SIGTERM', shutdown); process.on('SIGINT', shutdown);
+} else {
+  process.stderr.write('usage: volter-host serve --dir <worlds> [--host H] [--port P] [--url <origin reached at>] [--console-port C] [--console-url <console origin reached at; same site as --url, or its mirror links are refused>]\n');
+  process.exit(2);
+}

package/src/twins-host.test.ts

@@ -0,0 +1,170 @@
+// The host serves worlds under one URL: two bare worlds in a directory, both reachable by their
+// served names, each with its own token and serve record; a world served elsewhere refuses to mount.
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, existsSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { forkTwin, observeResources, readTwinRequestJournal, scrubWorld } from '@volter/world-core';
+import { statusWorld } from '@volter/world-runtime';
+import { createWorldHost, worldsUnder, type WorldHostHandle } from './twins-host.ts';
+
+const CLI = resolve(import.meta.dir, '..', '..', 'cli', 'src', 'cli.ts');
+const PACKS = resolve(import.meta.dir, '..', '..', 'twin');
+let dir: string; let host: WorldHostHandle;
+const init = (name: string) => { const root = join(dir, ...name.split('/')); mkdirSync(root, { recursive: true }); const r = spawnSync(process.execPath, [CLI, 'world', 'init', '--bare', name, '--twins', 'github'], { cwd: root, encoding: 'utf8' }); if (r.status !== 0) throw new Error(r.stderr); return root; };
+
+beforeAll(async () => {
+  dir = mkdtempSync(join(tmpdir(), 'world-host-'));
+  // a provisioned world resolves its twins above it, as the hosted product's directory does
+  mkdirSync(join(dir, 'node_modules', '@volter'), { recursive: true }); symlinkSync(join(PACKS, 'github'), join(dir, 'node_modules', '@volter', 'twin-github'));
+  init('acme/team'); init('acme/staging');
+  host = await createWorldHost({ dir });
+}, 120_000);
+afterAll(async () => { await host.stop(); rmSync(dir, { recursive: true, force: true }); });
+
+describe('the host', () => {
+  test('finds the worlds under the directory and serves each under its name', async () => {
+    expect(worldsUnder(dir).map((w) => w.name)).toEqual(['acme/staging', 'acme/team']);
+    expect(host.worlds.map((w) => w.name)).toEqual(['acme/staging', 'acme/team']);
+    const ping = await (await fetch(`${host.url}/-/ping`)).json() as { worlds: string[] };
+    expect(ping.worlds.sort()).toEqual(['acme/staging', 'acme/team']);
+  });
+  test('each world keeps its own token and its serve record names this host', async () => {
+    for (const name of ['acme/team', 'acme/staging']) {
+      const root = join(dir, ...name.split('/'));
+      const token = readFileSync(join(root, '.volter', 'token'), 'utf8').trim();
+      const record = JSON.parse(readFileSync(join(root, '.volter', 'serve.json'), 'utf8')) as { base: string; pid: number };
+      expect(record.base).toBe(`${host.url}/${name}`);
+      expect(record.pid).toBe(process.pid);
+      const log = await fetch(`${host.url}/-/${name}/log/github`, { headers: { 'x-volter-token': token } });
+      expect(log.status).toBe(200);
+      const wrong = await fetch(`${host.url}/-/${name}/log/github`, { headers: { 'x-volter-token': 'tok_nope' } });
+      expect(wrong.status).toBe(401);
+    }
+  });
+  test('a world not under the host answers 404 by name; a world served here refuses a second mount', async () => {
+    expect((await fetch(`${host.url}/acme/nowhere/github/repos`)).status).toBe(404);
+    await expect(createWorldHost({ dir })).rejects.toThrow(/already served at/);
+  });
+});
+
+describe("the hosted product's doors", () => {
+  const A = () => ({ 'x-volter-token': host.adminToken });
+  const worldToken = (name: string) => readFileSync(join(dir, ...name.split('/'), '.volter', 'token'), 'utf8').trim();
+  test('the admin token is minted once and kept beside the directory', () => {
+    expect(host.adminToken).toMatch(/^tok_a_/);
+    expect(readFileSync(join(dir, '.volter-host', 'admin'), 'utf8').trim()).toBe(host.adminToken);
+    expect(worldsUnder(dir).map((w) => w.name)).toEqual(['acme/staging', 'acme/team']); // the host's own dir is not a world
+  });
+  test('the inventory names every world, its address, its tokens and its twins; only the admin token opens it', async () => {
+    expect((await fetch(`${host.url}/-/worlds`)).status).toBe(401);
+    expect((await fetch(`${host.url}/-/worlds`, { headers: { 'x-volter-token': worldToken('acme/team') } })).status).toBe(401);
+    const { worlds } = await (await fetch(`${host.url}/-/worlds`, { headers: A() })).json() as { worlds: Array<{ name: string; base: string; token: string; readToken: string; twins: Array<{ vendor: string; protocol: { major: number } | null; root: unknown }> }> };
+    expect(worlds.map((w) => w.name)).toEqual(['acme/staging', 'acme/team']);
+    const team = worlds.find((w) => w.name === 'acme/team')!;
+    expect(team.base).toBe(`${host.url}/acme/team`);
+    expect(team.token).toBe(worldToken('acme/team'));
+    expect(team.readToken).toMatch(/^tok_r_/);
+    expect(team.twins).toMatchObject([{ vendor: 'github', protocol: { major: 2 }, root: null }]);
+  });
+  test('the admin token opens nothing under a world', async () => {
+    expect((await fetch(`${host.url}/-/acme/team/log/github`, { headers: A() })).status).toBe(401);
+    expect((await fetch(`${host.url}/acme/team/github/repos`, { headers: A() })).status).toBe(401);
+  });
+  test('provision → the CLI clones it → rotate: the old token refuses, the new one opens → remove', async () => {
+    const bad = await fetch(`${host.url}/-/worlds`, { method: 'POST', headers: { ...A(), 'content-type': 'application/json' }, body: JSON.stringify({ org: 'acme', world: '../x', vendors: ['github'] }) });
+    expect(bad.status).toBe(400);
+    const res = await fetch(`${host.url}/-/worlds`, { method: 'POST', headers: { ...A(), 'content-type': 'application/json' }, body: JSON.stringify({ org: 'acme', world: 'preview', vendors: ['github'] }) });
+    expect(res.status).toBe(201);
+    const made = await res.json() as { name: string; base: string; token: string; readToken: string; twins: Array<{ vendor: string }> };
+    expect(made.name).toBe('acme/preview'); expect(made.base).toBe(`${host.url}/acme/preview`);
+    expect(made.twins.map((t) => t.vendor)).toEqual(['github']);
+    expect(worldToken('acme/preview')).toBe(made.token);
+    const ping = await (await fetch(`${host.url}/-/ping`)).json() as { worlds: string[] };
+    expect(ping.worlds).toContain('acme/preview');
+    expect((await fetch(`${host.url}/-/acme/preview/log/github`, { headers: { 'x-volter-token': made.token } })).status).toBe(200);
+    expect((await fetch(`${host.url}/-/worlds`, { method: 'POST', headers: { ...A(), 'content-type': 'application/json' }, body: JSON.stringify({ org: 'acme', world: 'preview', vendors: ['github'] }) })).status).toBe(409);
+    // a person holding the handed-out token clones the world with the real CLI
+    const app = init('clones/preview'); // a world of one's own, then the clone (share-a-world guide)
+    // a clone boots the world, and its twins stay up the way `volter world up` leaves them — so the
+    // CLI writes to a file, not a pipe the servers would hold open, and `down` follows
+    const volter = async (...args: string[]): Promise<void> => {
+      const log = join(app, `${args[1]}.log`);
+      const proc = Bun.spawn({ cmd: [process.execPath, CLI, ...args], cwd: app, stdout: Bun.file(log), stderr: Bun.file(log) });
+      if (await proc.exited !== 0) throw new Error(`volter ${args.join(' ')} failed:\n${readFileSync(log, 'utf8')}`);
+    };
+    try { await volter('world', 'clone', made.base, '--token', made.token); }
+    finally { await volter('world', 'down'); }
+    // rotate: both tokens anew; the old die with the response
+    const rotated = await (await fetch(`${host.url}/-/worlds/acme/preview/rotate`, { method: 'POST', headers: A() })).json() as { token: string; readToken: string };
+    expect(rotated.token).not.toBe(made.token);
+    expect((await fetch(`${host.url}/-/acme/preview/log/github`, { headers: { 'x-volter-token': made.token } })).status).toBe(401);
+    expect((await fetch(`${host.url}/-/acme/preview/log/github`, { headers: { 'x-volter-token': rotated.token } })).status).toBe(200);
+    expect(worldToken('acme/preview')).toBe(rotated.token);
+    const inventory = await (await fetch(`${host.url}/-/worlds`, { headers: A() })).json() as { worlds: Array<{ name: string; token: string }> };
+    expect(inventory.worlds.find((w) => w.name === 'acme/preview')?.token).toBe(rotated.token);
+    // remove: gone from the host and from disk
+    expect((await fetch(`${host.url}/-/worlds/acme/preview`, { method: 'DELETE', headers: A() })).status).toBe(200);
+    expect((await fetch(`${host.url}/-/acme/preview/log/github`, { headers: { 'x-volter-token': rotated.token } })).status).toBe(404);
+    expect(existsSync(join(dir, 'acme', 'preview'))).toBe(false);
+    expect((await fetch(`${host.url}/-/worlds/acme/preview`, { method: 'DELETE', headers: A() })).status).toBe(404);
+  }, 120_000);
+});
+
+
+test('host deletion refuses a local dependent branch while keeping the parent served', async () => {
+  const headers = { 'x-volter-token': host.adminToken, 'content-type': 'application/json' };
+  const child = mkdtempSync(join(tmpdir(), 'host-lineage-child-'));
+  const response = await fetch(`${host.url}/-/worlds`, { method: 'POST', headers, body: JSON.stringify({ org: 'acme', world: 'lineage', vendors: ['github'] }) });
+  expect(response.status).toBe(201);
+  const made = await response.json() as { token: string };
+  const root = join(dir, 'acme', 'lineage');
+  try {
+    const parent = join(statusWorld('lineage', root).dirs.data, 'github');
+    await fetch(`${host.url}/acme/lineage/github/repos/acme/ancestry/issues`, { headers: { 'x-volter-token': made.token } });
+    expect(readTwinRequestJournal('github', parent).some(entry => entry.path === '/repos/acme/ancestry/issues')).toBe(true);
+    observeResources('github', [{ type: 'issue', id: 'ancestry-one', fields: { title: 'retained' } }], { root: parent, at: '2026-09-11T00:00:00Z' });
+    forkTwin({ service: 'github', fromRoot: parent, toRoot: child, occurredAt: '2026-09-11T00:00:00Z' });
+    const refused = await fetch(`${host.url}/-/worlds/acme/lineage`, { method: 'DELETE', headers });
+    expect(refused.status).toBe(409);
+    expect(await refused.text()).toContain('dependent branch');
+    expect(existsSync(root)).toBe(true);
+    expect((await fetch(`${host.url}/-/acme/lineage/log/github`, { headers: { 'x-volter-token': made.token } })).status).toBe(200);
+    scrubWorld({ root: child, force: true });
+    expect((await fetch(`${host.url}/-/worlds/acme/lineage`, { method: 'DELETE', headers })).status).toBe(200);
+    expect(existsSync(root)).toBe(false);
+  } finally {
+    scrubWorld({ root: child, force: true });
+    await fetch(`${host.url}/-/worlds/acme/lineage`, { method: 'DELETE', headers });
+    rmSync(child, { recursive: true, force: true });
+  }
+}, 60000);
+
+test('a provision failure after boot stops compute before removing its records', async () => {
+  const isolated = mkdtempSync(join(tmpdir(), 'host-provision-failure-'));
+  const baseline = join(isolated, 'acme', 'baseline'); mkdirSync(baseline, { recursive: true });
+  mkdirSync(join(isolated, 'node_modules', '@volter'), { recursive: true });
+  symlinkSync(join(PACKS, 'github'), join(isolated, 'node_modules', '@volter', 'twin-github'));
+  const initialized = spawnSync(process.execPath, [CLI, 'world', 'init', '--bare', 'acme/baseline', '--twins', 'github'], { cwd: baseline, encoding: 'utf8' });
+  expect(initialized.status).toBe(0);
+  let madeRoot = ''; let holderPid = 0;
+  const ownedHost = await createWorldHost({ dir: isolated, announce: (line) => {
+    if (line.includes('acme/rejected')) {
+      madeRoot = join(isolated, 'acme', 'rejected');
+      const status = statusWorld('rejected', madeRoot);
+      holderPid = status.lifecycle?.holderPid ?? status.resources?.holderPid ?? status.livePids[0] ?? Object.values(status.services)[0]?.pid ?? 0;
+      throw new Error('announcement failed after boot');
+    }
+  } });
+  try {
+    const response = await fetch(`${ownedHost.url}/-/worlds`, { method: 'POST', headers: { 'x-volter-token': ownedHost.adminToken, 'content-type': 'application/json' }, body: JSON.stringify({ org: 'acme', world: 'rejected', vendors: ['github'] }) });
+    expect(response.status).toBe(500);
+    expect(await response.text()).toContain('announcement failed');
+    expect(holderPid).toBeGreaterThan(0);
+    expect(existsSync(madeRoot) ? readdirSync(madeRoot, { recursive: true }) : []).toEqual([]);
+    expect(existsSync(madeRoot)).toBe(false);
+    const state = spawnSync('ps', ['-o', 'state=', '-p', String(holderPid)], { encoding: 'utf8' });
+    expect(state.status === 1 || (state.status === 0 && state.stdout.trim().startsWith('Z'))).toBe(true);
+  } finally { await ownedHost.stop(); rmSync(isolated, { recursive: true, force: true }); }
+}, 60000);

package/src/twins-host.ts

@@ -0,0 +1,197 @@
+// THE HOST (company contract "Just like Neon", 4; "The hosted product's doors"): worlds under ONE
+// URL. A directory holds worlds — `<dir>/<org>/<world>/` is a bare world — and the host mounts each
+// on the same port under its served name: `/<org>/<world>/<vendor>/…` is the twin's wire and
+// `/-/<org>/<world>/…` its doors, exactly as `volter world serve` gives one world. Every world keeps
+// its own tokens, its own serve record (the host's URL), its own roots and credentials. A world is
+// served once: a world already served elsewhere refuses to mount here, by name and pid.
+//
+// The host's OWN doors are the hosted product's: an ADMIN token — minted once, kept beside the
+// directory (`<dir>/.volter-host/admin`, 0600), stable across restarts, never an env var — opens
+// `/-/worlds`: the inventory (every world, its address, its tokens, its twins), provision (a new
+// bare world mounted without a restart), rotate (both tokens anew; the old die with the response)
+// and remove. The admin token opens NOTHING under a world, and a world's token opens nothing here:
+// the platform holds the admin token, the console holds world tokens, neither is the other.
+//
+// Nothing of the vendor lives here — no arms, no keys, no folds: the host is the shell; the kernel
+// serves. The v1 host (namespaces, links, the push flip, the R2 shell) left with v1.
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { assertStateRemovable, serveHttp, withAncestryLock, withStateRemoval } from '@volter/world-core';
+import { dirname, join, resolve } from 'node:path';
+import { assertWorldStateRemovable, CONSOLE_BASE, consoleRedirect, initWorld, loadWorldConfig, mountWorld, serveConsoleApart, TOKEN_HEADER, type ConsoleMount, type MountedWorld } from '@volter/world-runtime';
+
+export type WorldHostOptions = {
+  /** the directory of worlds: `<dir>/<org>/<world>/` is a bare world */
+  dir: string;
+  /** keep the kernel's request journal for every twin served here (layer 8: the world's request report); on unless told otherwise */
+  requestJournal?: boolean;
+  host?: string;
+  port?: number;
+  announce?: (line: string) => void;
+  /** the console, when installed (`@volter/world-console`): served on a listener of its own, its doors
+   *  forwarded here, so no script a twin serves shares its origin (world-runtime console-apart.ts) */
+  console?: ConsoleMount;
+  /** the console's port; the host's port + 1 when absent (a stable address), else one the system picks */
+  consolePort?: number;
+  /** the origin the console is REACHED at, when it differs from its bind address (as `advertise`) */
+  consoleAdvertise?: string;
+  /** The origin this host is REACHED at, when it differs from the bind address — a container binding
+   *  0.0.0.0 behind a port map, a host behind a proxy. Every world's `base`, its serve record and the
+   *  printed URLs use it; without it the bind address stands (loopback runs). */
+  advertise?: string;
+};
+export { CONSOLE_BASE, type ConsoleMount };
+export type WorldHostHandle = { url: string; port: number; adminToken: string; console: string | null; worlds: Array<{ name: string; base: string }>; stop: () => Promise<void> };
+/** One row of the inventory: what the platform records and what the console is handed. */
+export type WorldInventoryRow = { org: string; world: string; name: string; base: string; token: string; readToken: string; twins: Array<{ vendor: string; protocol: unknown; root: unknown }> };
+
+const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+
+/** The bare worlds under a directory: `<dir>/<org>/<world>/.volter/world.json`. */
+export function worldsUnder(dir: string): Array<{ name: string; root: string }> {
+  const out: Array<{ name: string; root: string }> = [];
+  const base = resolve(dir);
+  if (!existsSync(base)) return out;
+  for (const org of readdirSync(base, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules')) {
+    for (const world of readdirSync(join(base, org.name), { withFileTypes: true }).filter((e) => e.isDirectory())) {
+      const root = join(base, org.name, world.name);
+      if (existsSync(join(root, '.volter', 'world.json'))) out.push({ name: `${org.name}/${world.name}`, root });
+    }
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** The host's admin token: minted once, kept at `<dir>/.volter-host/admin` (0600). */
+export function adminTokenFor(dir: string): string {
+  const path = join(resolve(dir), '.volter-host', 'admin');
+  try { const t = readFileSync(path, 'utf8').trim(); if (t.startsWith('tok_a_')) return t; } catch { /* none yet */ }
+  const token = `tok_a_${Buffer.from(crypto.getRandomValues(new Uint8Array(24))).toString('base64url')}`;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${token}\n`, { mode: 0o600 }); chmodSync(path, 0o600);
+  return token;
+}
+
+export async function createWorldHost(options: WorldHostOptions): Promise<WorldHostHandle> {
+  // the twins this host boots inherit its env: the kernel's journal switch, set by the product, not by an operator
+  if (options.requestJournal !== false) process.env.VOLTER_TWIN_REQUEST_JOURNAL = '1';
+  const dir = resolve(options.dir);
+  const found = worldsUnder(dir);
+  if (found.length === 0) throw new Error(`no worlds under ${dir} — a world is \`<dir>/<org>/<world>/\` with \`.volter/world.json\` (\`volter world init --bare <org>/<world>\` makes one)`);
+  const adminToken = adminTokenFor(dir);
+  const mount = async (w: { name: string; root: string }): Promise<MountedWorld> => {
+    const config = loadWorldConfig(join(w.root, '.volter', 'world.json'), w.root).config;
+    return mountWorld(config.id, { root: w.root });
+  };
+  const byServed = new Map<string, MountedWorld>();
+  for (const w of found) byServed.set(w.name, await mount(w));
+  const host = options.host ?? '127.0.0.1';
+  let url = '';
+  const json = (body: unknown, status = 200): Response => Response.json(body, { status });
+
+  /** One inventory row, the twins read through the world's own status door with its own token. */
+  const row = async (m: MountedWorld): Promise<WorldInventoryRow> => {
+    const [org, world] = m.served.split('/') as [string, string];
+    const twins: WorldInventoryRow['twins'] = [];
+    for (const vendor of m.twins()) {
+      const res = await m.handle(new Request(`${url}/-/${m.served}/twins/${vendor}/status`, { headers: { [TOKEN_HEADER]: m.token } }));
+      const status = res.ok ? (await res.json()) as { protocol?: unknown; root?: unknown } : {};
+      twins.push({ vendor, protocol: status.protocol ?? null, root: status.root ?? null });
+    }
+    return { org, world, name: m.served, base: `${url}/${m.served}`, token: m.token, readToken: m.readToken, twins };
+  };
+
+  const checkAncestry = (path: string): void => {
+    for (const world of worldsUnder(dir)) assertWorldStateRemovable(world.root, path);
+    assertStateRemovable(path);
+  };
+
+  const admin = async (request: Request, path: string): Promise<Response> => {
+    if (request.headers.get(TOKEN_HEADER) !== adminToken) return json({ error: 'the host\'s doors open to the admin token' }, 401);
+    const m = /^\/-\/worlds(?:\/([^/]+)\/([^/]+)(?:\/(rotate))?)?$/.exec(path);
+    if (!m) return json({ error: `no such door: ${request.method} ${path}` }, 404);
+    const [, org, world, verb] = m;
+    if (!org) {
+      if (request.method === 'GET') { const rows: WorldInventoryRow[] = []; for (const w of byServed.values()) rows.push(await row(w)); return json({ worlds: rows }); }
+      if (request.method === 'POST') {
+        let body: { org?: string; world?: string; vendors?: string[] };
+        try { body = (await request.json()) as typeof body; } catch { return json({ error: 'provision: { org, world, vendors }' }, 400); }
+        const vendors = Array.isArray(body.vendors) ? body.vendors.filter((v): v is string => typeof v === 'string' && NAME.test(v)) : [];
+        if (!body.org || !body.world || !NAME.test(body.org) || !NAME.test(body.world) || vendors.length === 0) return json({ error: 'provision: { org, world, vendors: [vendor, …] } — names are letters, digits, . _ -' }, 400);
+        const name = `${body.org}/${body.world}`; const root = join(dir, body.org, body.world);
+        if (byServed.has(name) || existsSync(root)) return json({ error: `${name} exists` }, 409);
+        let acquired: MountedWorld | undefined;
+        try {
+          mkdirSync(root, { recursive: true });
+          const result = initWorld(body.world, root, { root, vendors, bare: name });
+          if (!result.ok) throw new Error(`init refused: ${JSON.stringify(result.plan)}`);
+          const mounted = await mount({ name, root });
+          acquired = mounted;
+          await mounted.boot(url);
+          byServed.set(name, mounted);
+          options.announce?.(`serving  ${name}  ${url}/${name}`);
+          return json(await row(mounted), 201);
+        } catch (error) {
+          try {
+            if (acquired) await acquired.stop();
+            withStateRemoval(root, () => rmSync(root, { recursive: true, force: true }));
+            byServed.delete(name);
+          } catch (cleanup) {
+            if (acquired) byServed.set(name, acquired);
+            return json({ error: `provision ${name} failed; cleanup incomplete, World retained: ${cleanup instanceof Error ? cleanup.message : String(cleanup)}` }, 500);
+          }
+          return json({ error: `provision ${name}: ${error instanceof Error ? error.message : String(error)}` }, 500);
+        }
+      }
+      return json({ error: `no such door: ${request.method} ${path}` }, 404);
+    }
+    const name = `${org}/${world}`; const mounted = byServed.get(name);
+    if (!mounted) return json({ error: `no world ${name} here` }, 404);
+    if (verb === 'rotate' && request.method === 'POST') return json({ name, ...mounted.rotate() });
+    if (!verb && request.method === 'DELETE') {
+      try {
+        withAncestryLock(() => checkAncestry(mounted.root));
+        await mounted.stop();
+        withStateRemoval(mounted.root, () => rmSync(mounted.root, { recursive: true, force: true }), () => checkAncestry(mounted.root));
+        byServed.delete(name);
+        return json({ removed: name });
+      } catch (error) { return json({ error: error instanceof Error ? error.message : String(error) }, 409); }
+    }
+    return json({ error: `no such door: ${request.method} ${path}` }, 404);
+  };
+
+  let consoleUrl: string | null = null;
+  const server = await serveHttp({
+    hostname: host, port: options.port ?? 0,
+    // This front serves many Worlds and lifecycle doors. Capturing one vendor identity
+    // here misattributes requests and can recreate a removed World after its response.
+    twinRequestJournal: false,
+    async fetch(request) {
+      const path = new URL(request.url).pathname;
+      const moved = consoleRedirect(request, consoleUrl ? consoleUrl.slice(0, -`${CONSOLE_BASE}/`.length) : null);
+      if (moved) return moved;
+      if (path === '/-/ping') return json({ ok: true, worlds: [...byServed.keys()], ...(consoleUrl ? { console: consoleUrl } : {}) });
+      if (path === '/-/worlds' || path.startsWith('/-/worlds/')) return admin(request, path);
+      const m = /^\/(?:-\/)?([^/]+)\/([^/]+)/.exec(path);
+      const world = m ? byServed.get(`${m[1]}/${m[2]}`) : undefined;
+      if (!world) return json({ error: `no world at ${path}: this host serves ${[...byServed.keys()].join(', ')}` }, 404);
+      return world.handle(request);
+    },
+  });
+  url = options.advertise ? options.advertise.replace(/\/+$/, '') : `http://${host}:${server.port}`;
+  let apart: Awaited<ReturnType<typeof serveConsoleApart>> | null = null;
+  try {
+    for (const m of byServed.values()) { await m.boot(url); options.announce?.(`serving  ${m.served}  ${url}/${m.served}`); }
+    if (options.console) {
+      // the console reaches the doors at this host's own address; the pages it serves name the advertised one
+      const internal = `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${server.port}`;
+      const serveApart = (port: number) => serveConsoleApart(options.console!, { upstream: internal, worlds: url, hostname: host, port });
+      if (options.consolePort !== undefined) apart = await serveApart(options.consolePort);
+      else { try { apart = await serveApart((server.port ?? 0) ? (server.port ?? 0) + 1 : 0); } catch { apart = await serveApart(0); } }
+      consoleUrl = `${(options.consoleAdvertise ?? apart.url).replace(/\/+$/, '')}${CONSOLE_BASE}/`;
+    }
+  } catch (error) { await server.stop(true); for (const m of byServed.values()) await m.stop().catch(() => undefined); throw error; }
+  return {
+    url, port: server.port ?? 0, adminToken, console: consoleUrl,
+    get worlds() { return [...byServed.values()].map((m) => ({ name: m.served, base: `${url}/${m.served}` })); },
+    stop: async () => { await apart?.server.stop(true); await server.stop(true); for (const m of byServed.values()) await m.stop(); },
+  };
+}