@volter/world-runtime 2.0.12 → 2.0.14

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

@@ -11,6 +11,8 @@ export type AppUrlRecord = {
     /** 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[];
+    /** the application's name in the World (`--app`); absent: `app`, the one a command names without it */
+    app?: 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
@@ -20,10 +22,12 @@ export declare function setAppUrl(name: string, url: string, options?: {
     root?: string;
     via?: Exclude<AppUrlSource, 'service'>;
     detail?: string;
+    app?: 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;
+    app?: string;
 }): AppUrlRecord;
 /**
  *`--detect <pid|port>`: resolve the app URL off what is ALREADY listening and record it.
@@ -34,6 +38,7 @@ export declare function addAppHosts(name: string, hosts: string[], options?: {
  */
 export declare function detectAppUrl(name: string, target: string, options?: {
     root?: string;
+    app?: string;
 }): Promise<AppUrlRecord>;
 /**
  * The recorded app URL of `name`, or the `app` service's assigned URL when nothing was recorded
@@ -42,6 +47,7 @@ export declare function detectAppUrl(name: string, target: string, options?: {
  */
 export declare function readAppUrl(name: string, options?: {
     root?: string;
+    app?: 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;
+export declare function appUrlUnsetMessage(name: string, app?: string): string;

package/dist/src/app-url.js

@@ -19,13 +19,53 @@
 // 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 { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { withFileLock } from '@volter/world-core';
 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";
+const APP_NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const DEFAULT_APP = 'app';
+function appName(app) {
+    const name = app ?? DEFAULT_APP;
+    if (!APP_NAME.test(name))
+        throw new Error(`volter-world app-url: --app "${name}" is not an application name (lower-case letters, digits and -)`);
+    return name;
+}
+function readFile(root, name) {
+    const file = appUrlFile(root, name);
+    return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+}
+function entryOf(file, app) {
+    if (app !== DEFAULT_APP)
+        return file.apps && Object.hasOwn(file.apps, app) ? file.apps[app] : undefined;
+    const { apps: _others, ...own } = file;
+    return own.url !== undefined || own.hosts !== undefined ? own : undefined;
+}
+/** Write one application's entry, keeping every other application's: under the record's lock (several booters record
+ *  their applications at once), replaced whole so a reader never meets half a file. */
+function writeEntry(root, name, app, build) {
+    // the whole read, check, merge and write under one lock (withFileLock is not reentrant: nothing inside takes it)
+    return withFileLock(`${appUrlFile(root, name)}.lock`, () => {
+        const file = readFile(root, name);
+        const { entry, result } = build(file);
+        writeEntryLocked(root, name, app, file, entry);
+        return result;
+    });
+}
+function writeEntryLocked(root, name, app, file, entry) {
+    const { app: _name, ...stored } = entry;
+    const next = app === DEFAULT_APP
+        ? { ...stored, ...(file.apps ? { apps: file.apps } : {}) }
+        : { ...Object.fromEntries(Object.entries(file).filter(([k]) => k !== 'apps')), apps: { ...(file.apps ?? {}), [app]: stored } };
+    const target = appUrlFile(root, name);
+    const temp = `${target}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`);
+    renameSync(temp, target);
+}
 export function appUrlFile(root, name) {
     return join(instanceDir(root, name), 'app-url.json');
 }
@@ -47,24 +87,27 @@ function assertHttpUrl(url) {
  * 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 app = appName(options.app);
     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) {
+    return writeEntry(root, name, app, (file) => {
+        // a new URL keeps the hosts recorded for the app (they name the app, not where it listens)
+        const hosts = entryOf(file, app)?.hosts;
+        const record = {
+            world: status.name,
+            url,
+            via: options.via ?? 'set',
+            recordedAt: new Date().toISOString(),
+            ...(options.detail === undefined ? {} : { detail: options.detail }),
+            ...(hosts?.length ? { hosts } : {}),
+        };
+        return { entry: record, result: app === DEFAULT_APP ? record : { ...record, app } };
+    });
+}
+/** A hostname the app may answer as: a DNS name (not an address, not loopback) that no twin the World runs serves,
+ *  not the host of this World's own origin or of a twin it runs (their requests carry the World key), and not one
+ *  another of its applications answers. A vendor the World runs no twin of can be the application itself. */
+function assertAppHost(host, world, root, app, file) {
     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:
@@ -75,18 +118,22 @@ function assertAppHost(host, world, root) {
         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));
+    const status = statusWorld(world, root);
+    // the twins the World runs, by vendor key, as its injector reads them from the World env (a service's id is not its
+    // vendor key: the aws service serves s3, dynamodb and others; a stripe twin may be a service named payments)
+    const twins = inject.readMap(status.env);
+    const runs = (vendor) => Object.hasOwn(twins, vendor);
+    let vendor = Object.keys(inject.VENDOR_HOSTS).find((v) => runs(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;
+        vendor = names.find((n) => runs(n.vendor) && (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);
+        throw new Error(`volter-world app-url: --host ${name} is ${vendor}'s host, which its twin serves in this World; an app cannot answer as it while it runs`);
     const own = [status.env.VOLTER_WORLD ?? '', ...Object.values(status.services).map((service) => service.url ?? '')]
         .flatMap((url) => { try {
         return [new URL(url).hostname.toLowerCase()];
@@ -96,6 +143,17 @@ function assertAppHost(host, world, root) {
     } });
     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`);
+    // one application per hostname: a name, or a wildcard over it, another application already answers
+    for (const other of [DEFAULT_APP, ...Object.keys(file.apps ?? {})]) {
+        if (other === app)
+            continue;
+        const held = entryOf(file, other)?.hosts ?? [];
+        // a wildcard answers every name below its parent and never the parent, as a DNS wildcard does, so `*.example.org`
+        // and `example.org` are two applications' without overlap
+        const clash = held.find((h) => h === name || (h.startsWith('*.') && name.endsWith(h.slice(1)) && name !== h) || (wildcard && h.endsWith(`.${bare}`)));
+        if (clash)
+            throw new Error(`volter-world app-url: --host ${name} overlaps ${clash}, which the application "${other}" answers; a hostname belongs to one application`);
+    }
     return name;
 }
 /** Every hostname the vendor table can name, with its vendor: a descriptor rule's host, suffix, or a host pattern's
@@ -131,14 +189,20 @@ function vendorNames(table) {
 /** 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;
+    const app = appName(options.app);
+    const status = statusWorld(name, root);
+    return writeEntry(root, name, app, (file) => {
+        // checked against the record as it stands under the lock, so two booters never both take one hostname
+        const current = appUrlOf(file, status, app);
+        if (!current)
+            throw new Error(appUrlUnsetMessage(name, app));
+        const all = [...new Set([...(current.hosts ?? []), ...hosts.map((host) => assertAppHost(host, name, root, app, file))])].sort();
+        // hosts beside the World's own service of the application's name keep no URL: they follow the service wherever a
+        // boot puts it
+        const { app: _name, ...stored } = current;
+        const entry = current.via === 'service' ? { world: current.world, via: 'service', hosts: all } : { ...stored, hosts: all };
+        return { entry, result: { ...current, hosts: all } };
+    });
 }
 /** The listening TCP ports of a live pid, via lsof (macOS + Linux). */
 function listeningTcpPorts(pid) {
@@ -214,24 +278,33 @@ export async function detectAppUrl(name, target, options = {}) {
  */
 export function readAppUrl(name, options = {}) {
     const root = options.root ?? process.cwd();
+    const app = appName(options.app);
     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 } : {}) };
+    return appUrlOf(readFile(root, name), status, app);
+}
+/** One application's URL from the record `file` and the instance `status`: the recorded URL, or the World's service
+ *  of the application's name. */
+function appUrlOf(file, status, app) {
+    const named = app === DEFAULT_APP ? {} : { app };
+    const service = status.services[app];
+    const record = entryOf(file, app);
+    if (record) {
+        // hosts recorded beside the World's own service of the application's name: its URL is this boot's
+        if (!record.url && service?.url !== undefined)
+            return { world: status.name, url: service.url, via: 'service', detail: `the world's own "${app}" service`, ...(record.hosts ? { hosts: record.hosts } : {}), ...named };
         if (record.url)
-            return record;
+            return { ...record, world: status.name, ...named };
     }
-    if (app?.url !== undefined) {
-        return { world: status.name, url: app.url, via: 'service', detail: 'the world\'s own "app" service (nothing was recorded)' };
+    if (service?.url !== undefined) {
+        return { world: status.name, url: service.url, via: 'service', detail: `the world's own "${app}" service (nothing was recorded)`, ...named };
     }
     return null;
 }
 /** The message the CLI prints when no app URL is known — the registration recipe, not a guess. */
-export function appUrlUnsetMessage(name) {
+export function appUrlUnsetMessage(name, app = DEFAULT_APP) {
+    if (app !== DEFAULT_APP) {
+        return `World ${name} has no URL for the application "${app}": record it with \`volter-world app-url ${name} --app ${app} --set http://127.0.0.1:<port>\`, or declare a service "${app}" in the World's config.`;
+    }
     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`

package/dist/src/cli.js

@@ -99,7 +99,7 @@ function printHelp() {
   volter-world urls <name> [--json] [--root <repo>]
   volter-world url <name> [service] [--root <repo>]   # the clean base URL of one running service (no world.env parsing);
                                                         # without a service: every service, one \`<id> <url>\` per line
-  volter-world app-url <world> [--set <url>|--detect <pid|port>] [--host <name>...] [--json] [--root <repo>]
+  volter-world app-url <world> [--app <name>] [--set <url>|--detect <pid|port>] [--host <name>...] [--json] [--root <repo>]
                                                   # the recorded APP endpoint of the instance — the attach pattern's
                                                   # missing output. The BOOTER records it as the last boot step
                                                   # (--set, or --detect an already-listening pid/port); consumers
@@ -678,22 +678,26 @@ async function main() {
         if (set && detect)
             throw new Error('volter-world app-url: pass --set OR --detect, not both');
         const json = rest.includes('--json');
+        // --app: which of the World's applications (each with its URL and hostnames); without it, `app`
+        const app = rest.some((arg) => arg === '--app' || arg.startsWith('--app=')) ? optionValue(rest, '--app') : undefined;
+        if (app === '' || app?.startsWith('--'))
+            throw new Error('volter-world app-url: --app needs an application name (--app <name>)');
         // --host (repeatable): a hostname the app answers as in production, routed to it inside the World
         const hosts = rest.flatMap((arg, index) => (arg === '--host' ? [rest[index + 1] ?? ''] : []));
         if (set || detect || hosts.length) {
-            let record = set ? setAppUrl(subject, set, { root }) : detect ? await detectAppUrl(subject, detect, { root }) : undefined;
+            let record = set ? setAppUrl(subject, set, { root, app }) : detect ? await detectAppUrl(subject, detect, { root, app }) : undefined;
             if (hosts.length)
-                record = addAppHosts(subject, hosts, { root });
+                record = addAppHosts(subject, hosts, { root, app });
             if (json)
                 process.stdout.write(`${JSON.stringify(record, null, 2)}\n`);
             else
                 process.stdout.write(`Recorded app URL for world ${subject}: ${record.url}${record.detail ? ` (${record.detail})` : ''}${record.hosts?.length ? `; answering as ${record.hosts.join(', ')}` : ''}\n`);
             return;
         }
-        const record = readAppUrl(subject, { root });
+        const record = readAppUrl(subject, { root, app });
         if (record === null) {
             // LOUD when unset — a consumer must never mistake "nobody registered it" for an endpoint.
-            process.stderr.write(`${appUrlUnsetMessage(subject)}\n`);
+            process.stderr.write(`${appUrlUnsetMessage(subject, app)}\n`);
             if (json)
                 process.stdout.write(`${JSON.stringify({ world: subject, url: null }, null, 2)}\n`);
             process.exit(1);

package/dist/src/redirect-proxy.js

@@ -351,8 +351,12 @@ export async function startRedirectProxy(options) {
                     for (const [k, v] of Object.entries(loadInject().appForwardHeaders(new URL(`https://${req.headers.get('host') ?? vendorHost}`))))
                         headers.set(k, v);
                 }
-                else if (env.VOLTER_TWINS_KEY)
-                    headers.set('x-twins-key', env.VOLTER_TWINS_KEY);
+                else {
+                    if (env.VOLTER_TWINS_KEY)
+                        headers.set('x-twins-key', env.VOLTER_TWINS_KEY);
+                    // the caller reached the vendor's host over TLS, which ends here: the twin renders its own links with https
+                    headers.set('x-forwarded-proto', 'https');
+                }
                 // Hosted namespaces need their transport Host; direct twins can use
                 // the original Host for vendor semantics (for example S3 buckets).
                 if (origin.pathname.replace(/\/$/, '') && twin.vendor !== 'app') {

package/dist/src/served-world.d.ts

@@ -63,7 +63,8 @@ export declare function mountWorld(name: string, opts?: {
     root?: string; /** the host's branches of this World, by its served name */
     branches?: (served: string) => BranchDoors | undefined; /** the origin a browser reaches this World at, when the host gives each World one */
     browserOrigin?: (served: string) => string | null; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */
-    localTrust?: boolean;
+    localTrust?: boolean; /** DoorHost.serveBranch */
+    serveBranch?: (branch: string) => Promise<void>;
 }): Promise<MountedWorld>;
 /** Boot the world (state kept) and serve it on its own port. Announces and returns after boot; `stop` downs the world. */
 export declare function serveWorld(name: string, opts?: {
@@ -143,6 +144,9 @@ export type DoorHost = {
     /** This World's branches, where the host can make them (a branch is another World, so making one
      *  is the host's act); absent, the branches doors answer 404. */
     branches?: BranchDoors;
+    /** Serve another of the World's own named branches in this one's place (`volter world view` does; a host that
+     *  serves one branch leaves it absent): this branch's twins stop, that one's start, under the same served name. */
+    serveBranch?: (branch: string) => Promise<void>;
 };
 /** A branch as its parent lists it. */
 export type BranchRow = {

package/dist/src/served-world.js

@@ -143,6 +143,7 @@ export async function mountWorld(name, opts = {}) {
         ...(opts.branches?.(served) ? { branches: opts.branches(served) } : {}),
         ...(opts.browserOrigin ? { browserOrigin: () => opts.browserOrigin(served), originOf: (other) => opts.browserOrigin(other) } : {}),
         ...(opts.localTrust ? { localTrust: () => true } : {}),
+        ...(opts.serveBranch ? { serveBranch: opts.serveBranch } : {}),
         ...(opts.passIssuers?.length ? { passIssuers: () => opts.passIssuers } : {}),
         // a local twin is its own process: the wire forwards to the port it listens on
         twinFetch: (vendor) => {
@@ -1439,6 +1440,28 @@ export class WorldDoors {
             catch { /* a World with no local branches */ }
             return Response.json({ world: this.served, branches: await branches.list(), checkedOut: this.name, named });
         }
+        // SERVE ANOTHER NAMED BRANCH here (`POST branches/<branch>/serve`): only who may write the World switches what it serves
+        if (rest.length === 2 && rest[1] === 'serve' && request.method === 'POST') {
+            if (!this.host.serveBranch)
+                return Response.json({ error: `this host serves ${this.served} on one branch` }, { status: 404 });
+            if (this.credential(request).scope !== 'write')
+                return Response.json({ error: 'serving another branch needs the World\'s write access' }, { status: 403 });
+            const target = decodeURIComponent(rest[0]);
+            let known = false;
+            try {
+                known = listWorlds(this.worldRoot).some((w) => w.name === target);
+            }
+            catch { /* no local branches */ }
+            if (!known)
+                return Response.json({ error: `no branch ${target} in this World` }, { status: 404 });
+            try {
+                await this.host.serveBranch(target);
+            }
+            catch (error) {
+                return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 409 });
+            }
+            return Response.json({ world: this.served, checkedOut: target });
+        }
         if (rest.length === 0 && request.method === 'POST') {
             const body = (await request.json().catch(() => null));
             const instant = body?.at?.instant;

package/dist/src/world-view.js

@@ -2,7 +2,7 @@
 // ("as of" views) and the console, on one origin (docs/contributing/architecture.md, "Viewing a
 // World"). `volter world view` is this; the runtime's `up` gains no step. A host that serves many
 // Worlds (world-host) answers the same doors; this serves one, and the branches made of it.
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { loadWorldConfig } from "./configs.js";
 import { join, resolve } from 'node:path';
 import { serveHttp, stateDirName } from '@volter/world-core';
@@ -42,7 +42,46 @@ export async function serveWorldView(name, opts = {}) {
     const browserOrigin = origins ? (served) => (port ? localWorldOrigin(served, port) : null) : undefined;
     const mountAt = (at) => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}) });
     const branches = new LocalBranches({ dir: join(root, stateDirName(), 'branches'), origin: () => loopback, worlds, mount: mountAt, ...(opts.announce ? { announce: opts.announce } : {}) });
-    const world = await mountWorld(name, { root, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}) });
+    // THE WORLD'S OWN BRANCHES, one served at a time: serving another stops this one's twins and starts that one's under the
+    // same served name (its tokens and sessions are the World's, so the page stays open); `.volter/current` follows, as
+    // \`volter world checkout\` sets it. While it switches, the World's doors answer 503.
+    let url = '';
+    let switching = false;
+    const serveBranch = async (branch) => {
+        if (switching)
+            throw new Error('already switching branches');
+        if (branch === world.name)
+            return;
+        switching = true;
+        const from = world.name;
+        try {
+            await world.stop();
+            let next;
+            try {
+                next = await mountWorld(branch, mountOpts);
+                await next.boot(url);
+            }
+            catch (error) {
+                const back = await mountWorld(from, mountOpts);
+                await back.boot(url);
+                worlds.set(back.served, back);
+                world = back;
+                throw error;
+            }
+            worlds.set(next.served, next);
+            world = next;
+            const current = join(root, stateDirName(), 'current');
+            if (branch === loadWorldConfig(join(root, stateDirName(), 'world.json'), root).config.id)
+                rmSync(current, { force: true });
+            else
+                writeFileSync(current, `${branch}\n`);
+        }
+        finally {
+            switching = false;
+        }
+    };
+    const mountOpts = { root, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}), serveBranch };
+    let world = await mountWorld(name, mountOpts);
     worlds.set(world.served, world);
     const server = await serveHttp({
         // a pushed blob (a release video) is one PUT: bodies up to 1 GiB, as `serve` takes them
@@ -73,6 +112,8 @@ export async function serveWorldView(name, opts = {}) {
                     return answered;
             }
             const m = /^\/(?:-\/)?([^/]+)\/([^/]+)/.exec(path);
+            if (switching && m && `${m[1]}/${m[2]}` === world.served)
+                return Response.json({ error: `${world.served} is switching branches` }, { status: 503, headers: { 'retry-after': '2' } });
             const target = m ? worlds.get(`${m[1]}/${m[2]}`) : undefined;
             if (!target)
                 return Response.json({ error: `no world at ${path}: this view serves ${[...worlds.keys()].join(', ')}` }, { status: 404 });
@@ -80,7 +121,7 @@ export async function serveWorldView(name, opts = {}) {
         },
     });
     port = server.port ?? 0;
-    const url = `http://${host}:${server.port}`;
+    url = `http://${host}:${server.port}`;
     loopback = `http://${host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host}:${server.port}`;
     // a branch outlives the view that made it until its time runs out: stopping stops its compute only
     const stop = async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "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",
@@ -67,14 +67,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.7",
-    "@volter/world-console": "2.0.7"
+    "@volter/world-core": "2.0.8",
+    "@volter/world-console": "2.0.8"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "2.0.1",
-    "@volter/world-core": "2.0.7",
+    "@volter/world-core": "2.0.8",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -84,6 +84,6 @@
     }
   },
   "optionalDependencies": {
-    "@volter/twin-mongodb": "0.1.7"
+    "@volter/twin-mongodb": "0.1.8"
   }
 }

package/src/app-url.ts

@@ -19,7 +19,8 @@
 // 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 { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { withFileLock } from '@volter/world-core';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import net from 'node:net';
@@ -41,8 +42,56 @@ export type AppUrlRecord = {
   /** 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[];
+  /** the application's name in the World (`--app`); absent: `app`, the one a command names without it */
+  app?: string;
 };
 
+/** `app-url.json`: the application named `app` at the top level (the record's original shape), the others by name. */
+type AppUrlFile = Partial<AppUrlRecord> & { apps?: Record<string, Partial<AppUrlRecord>> };
+
+const APP_NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const DEFAULT_APP = 'app';
+
+function appName(app: string | undefined): string {
+  const name = app ?? DEFAULT_APP;
+  if (!APP_NAME.test(name)) throw new Error(`volter-world app-url: --app "${name}" is not an application name (lower-case letters, digits and -)`);
+  return name;
+}
+
+function readFile(root: string, name: string): AppUrlFile {
+  const file = appUrlFile(root, name);
+  return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) as AppUrlFile : {};
+}
+
+function entryOf(file: AppUrlFile, app: string): Partial<AppUrlRecord> | undefined {
+  if (app !== DEFAULT_APP) return file.apps && Object.hasOwn(file.apps, app) ? file.apps[app] : undefined;
+  const { apps: _others, ...own } = file;
+  return own.url !== undefined || own.hosts !== undefined ? own : undefined;
+}
+
+/** Write one application's entry, keeping every other application's: under the record's lock (several booters record
+ *  their applications at once), replaced whole so a reader never meets half a file. */
+function writeEntry<T>(root: string, name: string, app: string, build: (file: AppUrlFile) => { entry: Partial<AppUrlRecord>; result: T }): T {
+  // the whole read, check, merge and write under one lock (withFileLock is not reentrant: nothing inside takes it)
+  return withFileLock(`${appUrlFile(root, name)}.lock`, () => {
+    const file = readFile(root, name);
+    const { entry, result } = build(file);
+    writeEntryLocked(root, name, app, file, entry);
+    return result;
+  });
+}
+
+function writeEntryLocked(root: string, name: string, app: string, file: AppUrlFile, entry: Partial<AppUrlRecord>): void {
+  const { app: _name, ...stored } = entry;
+  const next: AppUrlFile = app === DEFAULT_APP
+    ? { ...stored, ...(file.apps ? { apps: file.apps } : {}) }
+    : { ...Object.fromEntries(Object.entries(file).filter(([k]) => k !== 'apps')), apps: { ...(file.apps ?? {}), [app]: stored } };
+  const target = appUrlFile(root, name);
+  const temp = `${target}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`);
+  renameSync(temp, target);
+}
+
 export function appUrlFile(root: string, name: string): string {
   return join(instanceDir(root, name), 'app-url.json');
 }
@@ -63,27 +112,30 @@ function assertHttpUrl(url: string): URL {
 /** 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 {
+export function setAppUrl(name: string, url: string, options: { root?: string; via?: Exclude<AppUrlSource, 'service'>; detail?: string; app?: string } = {}): AppUrlRecord {
   const root = options.root ?? process.cwd();
+  const app = appName(options.app);
   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 {
+  return writeEntry(root, name, app, (file) => {
+    // a new URL keeps the hosts recorded for the app (they name the app, not where it listens)
+    const hosts = entryOf(file, app)?.hosts;
+    const record: AppUrlRecord = {
+      world: status.name,
+      url,
+      via: options.via ?? 'set',
+      recordedAt: new Date().toISOString(),
+      ...(options.detail === undefined ? {} : { detail: options.detail }),
+      ...(hosts?.length ? { hosts } : {}),
+    };
+    return { entry: record, result: app === DEFAULT_APP ? record : { ...record, app } };
+  });
+}
+
+/** A hostname the app may answer as: a DNS name (not an address, not loopback) that no twin the World runs serves,
+ *  not the host of this World's own origin or of a twin it runs (their requests carry the World key), and not one
+ *  another of its applications answers. A vendor the World runs no twin of can be the application itself. */
+function assertAppHost(host: string, world: string, root: string, app: string, file: AppUrlFile): 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:
@@ -94,20 +146,33 @@ function assertAppHost(host: string, world: string, root: string): string {
     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));
+  const status = statusWorld(world, root);
+  // the twins the World runs, by vendor key, as its injector reads them from the World env (a service's id is not its
+  // vendor key: the aws service serves s3, dynamodb and others; a stripe twin may be a service named payments)
+  const twins = inject.readMap(status.env);
+  const runs = (vendor: string) => Object.hasOwn(twins, vendor);
+  let vendor = Object.keys(inject.VENDOR_HOSTS).find((v) => runs(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;
+    vendor = names.find((n) => runs(n.vendor) && (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);
+  if (vendor) throw new Error(`volter-world app-url: --host ${name} is ${vendor}'s host, which its twin serves in this World; an app cannot answer as it while it runs`);
   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`);
+  // one application per hostname: a name, or a wildcard over it, another application already answers
+  for (const other of [DEFAULT_APP, ...Object.keys(file.apps ?? {})]) {
+    if (other === app) continue;
+    const held = entryOf(file, other)?.hosts ?? [];
+    // a wildcard answers every name below its parent and never the parent, as a DNS wildcard does, so `*.example.org`
+    // and `example.org` are two applications' without overlap
+    const clash = held.find((h) => h === name || (h.startsWith('*.') && name.endsWith(h.slice(1)) && name !== h) || (wildcard && h.endsWith(`.${bare}`)));
+    if (clash) throw new Error(`volter-world app-url: --host ${name} overlaps ${clash}, which the application "${other}" answers; a hostname belongs to one application`);
+  }
   return name;
 }
 
@@ -137,15 +202,21 @@ function vendorNames(table: Record<string, (host: string, pathname?: string) =>
 }
 
 /** 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 {
+export function addAppHosts(name: string, hosts: string[], options: { root?: string; app?: 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;
+  const app = appName(options.app);
+  const status = statusWorld(name, root);
+  return writeEntry(root, name, app, (file) => {
+    // checked against the record as it stands under the lock, so two booters never both take one hostname
+    const current = appUrlOf(file, status, app);
+    if (!current) throw new Error(appUrlUnsetMessage(name, app));
+    const all = [...new Set([...(current.hosts ?? []), ...hosts.map((host) => assertAppHost(host, name, root, app, file))])].sort();
+    // hosts beside the World's own service of the application's name keep no URL: they follow the service wherever a
+    // boot puts it
+    const { app: _name, ...stored } = current;
+    const entry = current.via === 'service' ? { world: current.world, via: 'service', hosts: all } as AppUrlRecord : { ...stored, hosts: all };
+    return { entry, result: { ...current, hosts: all } };
+  });
 }
 
 /** The listening TCP ports of a live pid, via lsof (macOS + Linux). */
@@ -193,7 +264,7 @@ function tcpListening(port: number, timeoutMs = 1500): Promise<boolean> {
  * 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> {
+export async function detectAppUrl(name: string, target: string, options: { root?: string; app?: 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}"`);
@@ -225,25 +296,35 @@ export async function detectAppUrl(name: string, target: string, options: { root
  * (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 {
+export function readAppUrl(name: string, options: { root?: string; app?: string } = {}): AppUrlRecord | null {
   const root = options.root ?? process.cwd();
+  const app = appName(options.app);
   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;
+  return appUrlOf(readFile(root, name), status, app);
+}
+
+/** One application's URL from the record `file` and the instance `status`: the recorded URL, or the World's service
+ *  of the application's name. */
+function appUrlOf(file: AppUrlFile, status: { name: string; services: Record<string, { url?: string }> }, app: string): AppUrlRecord | null {
+  const named = app === DEFAULT_APP ? {} : { app };
+  const service = status.services[app];
+  const record = entryOf(file, app);
+  if (record) {
+    // hosts recorded beside the World's own service of the application's name: its URL is this boot's
+    if (!record.url && service?.url !== undefined) return { world: status.name, url: service.url, via: 'service', detail: `the world's own "${app}" service`, ...(record.hosts ? { hosts: record.hosts } : {}), ...named };
+    if (record.url) return { ...(record as AppUrlRecord), world: status.name, ...named };
   }
-  if (app?.url !== undefined) {
-    return { world: status.name, url: app.url, via: 'service', detail: 'the world\'s own "app" service (nothing was recorded)' };
+  if (service?.url !== undefined) {
+    return { world: status.name, url: service.url, via: 'service', detail: `the world's own "${app}" service (nothing was recorded)`, ...named };
   }
   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 {
+export function appUrlUnsetMessage(name: string, app = DEFAULT_APP): string {
+  if (app !== DEFAULT_APP) {
+    return `World ${name} has no URL for the application "${app}": record it with \`volter-world app-url ${name} --app ${app} --set http://127.0.0.1:<port>\`, or declare a service "${app}" in the World's config.`;
+  }
   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`

package/src/cli.ts

@@ -100,7 +100,7 @@ function printHelp(): void {
   volter-world urls <name> [--json] [--root <repo>]
   volter-world url <name> [service] [--root <repo>]   # the clean base URL of one running service (no world.env parsing);
                                                         # without a service: every service, one \`<id> <url>\` per line
-  volter-world app-url <world> [--set <url>|--detect <pid|port>] [--host <name>...] [--json] [--root <repo>]
+  volter-world app-url <world> [--app <name>] [--set <url>|--detect <pid|port>] [--host <name>...] [--json] [--root <repo>]
                                                   # the recorded APP endpoint of the instance — the attach pattern's
                                                   # missing output. The BOOTER records it as the last boot step
                                                   # (--set, or --detect an already-listening pid/port); consumers
@@ -608,19 +608,22 @@ async function main(): Promise<void> {
     const detect = optionValue(rest, '--detect');
     if (set && detect) throw new Error('volter-world app-url: pass --set OR --detect, not both');
     const json = rest.includes('--json');
+    // --app: which of the World's applications (each with its URL and hostnames); without it, `app`
+    const app = rest.some((arg) => arg === '--app' || arg.startsWith('--app=')) ? optionValue(rest, '--app') : undefined;
+    if (app === '' || app?.startsWith('--')) throw new Error('volter-world app-url: --app needs an application name (--app <name>)');
     // --host (repeatable): a hostname the app answers as in production, routed to it inside the World
     const hosts = rest.flatMap((arg, index) => (arg === '--host' ? [rest[index + 1] ?? ''] : []));
     if (set || detect || hosts.length) {
-      let record = set ? setAppUrl(subject, set, { root }) : detect ? await detectAppUrl(subject, detect, { root }) : undefined;
-      if (hosts.length) record = addAppHosts(subject, hosts, { root });
+      let record = set ? setAppUrl(subject, set, { root, app }) : detect ? await detectAppUrl(subject, detect, { root, app }) : undefined;
+      if (hosts.length) record = addAppHosts(subject, hosts, { root, app });
       if (json) process.stdout.write(`${JSON.stringify(record, null, 2)}\n`);
       else process.stdout.write(`Recorded app URL for world ${subject}: ${record!.url}${record!.detail ? ` (${record!.detail})` : ''}${record!.hosts?.length ? `; answering as ${record!.hosts.join(', ')}` : ''}\n`);
       return;
     }
-    const record = readAppUrl(subject, { root });
+    const record = readAppUrl(subject, { root, app });
     if (record === null) {
       // LOUD when unset — a consumer must never mistake "nobody registered it" for an endpoint.
-      process.stderr.write(`${appUrlUnsetMessage(subject)}\n`);
+      process.stderr.write(`${appUrlUnsetMessage(subject, app)}\n`);
       if (json) process.stdout.write(`${JSON.stringify({ world: subject, url: null }, null, 2)}\n`);
       process.exit(1);
     }

package/src/redirect-proxy.ts

@@ -373,7 +373,11 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
         if (twin.vendor === 'app') {
           headers.delete('x-twins-key');
           for (const [k, v] of Object.entries(loadInject().appForwardHeaders(new URL(`https://${req.headers.get('host') ?? vendorHost}`)))) headers.set(k, v);
-        } else if (env.VOLTER_TWINS_KEY) headers.set('x-twins-key', env.VOLTER_TWINS_KEY);
+        } else {
+          if (env.VOLTER_TWINS_KEY) headers.set('x-twins-key', env.VOLTER_TWINS_KEY);
+          // the caller reached the vendor's host over TLS, which ends here: the twin renders its own links with https
+          headers.set('x-forwarded-proto', 'https');
+        }
         // Hosted namespaces need their transport Host; direct twins can use
         // the original Host for vendor semantics (for example S3 buckets).
         if (origin.pathname.replace(/\/$/, '') && twin.vendor !== 'app') {

package/src/served-world.ts

@@ -116,7 +116,7 @@ export type MountedWorld = { name: string; served: string; root: string; readonl
 /** A browser session a World keeps: its scope, when it ends, and the person a pass named, when one did. */
 type HeldSession = { scope: 'read' | 'write'; until: number; who?: string; /** the platform whose pass opened it */ issuer?: string; /** the person's subject there */ sub?: string; /** the read key a shared link opened it with: it lasts only while that key does */ key?: string };
 
-export async function mountWorld(name: string, opts: { /** the platforms whose passes open this World */ passIssuers?: TrustedIssuer[]; root?: string; /** the host's branches of this World, by its served name */ branches?: (served: string) => BranchDoors | undefined; /** the origin a browser reaches this World at, when the host gives each World one */ browserOrigin?: (served: string) => string | null; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */ localTrust?: boolean } = {}): Promise<MountedWorld> {
+export async function mountWorld(name: string, opts: { /** the platforms whose passes open this World */ passIssuers?: TrustedIssuer[]; root?: string; /** the host's branches of this World, by its served name */ branches?: (served: string) => BranchDoors | undefined; /** the origin a browser reaches this World at, when the host gives each World one */ browserOrigin?: (served: string) => string | null; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */ localTrust?: boolean; /** DoorHost.serveBranch */ serveBranch?: (branch: string) => Promise<void> } = {}): Promise<MountedWorld> {
   const worldRoot = resolve(opts.root ?? process.cwd());
   const configRef = configRefFor(worldRoot, name);
   if (loadWorldConfig(configRef, worldRoot).config.resources) {
@@ -149,6 +149,7 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
     ...(opts.branches?.(served) ? { branches: opts.branches(served)! } : {}),
     ...(opts.browserOrigin ? { browserOrigin: () => opts.browserOrigin!(served), originOf: (other: string) => opts.browserOrigin!(other) } : {}),
     ...(opts.localTrust ? { localTrust: () => true } : {}),
+    ...(opts.serveBranch ? { serveBranch: opts.serveBranch } : {}),
     ...(opts.passIssuers?.length ? { passIssuers: () => opts.passIssuers! } : {}),
     // a local twin is its own process: the wire forwards to the port it listens on
     twinFetch: (vendor) => {
@@ -304,6 +305,9 @@ export type DoorHost = {
   /** This World's branches, where the host can make them (a branch is another World, so making one
    *  is the host's act); absent, the branches doors answer 404. */
   branches?: BranchDoors;
+  /** Serve another of the World's own named branches in this one's place (`volter world view` does; a host that
+   *  serves one branch leaves it absent): this branch's twins stop, that one's start, under the same served name. */
+  serveBranch?: (branch: string) => Promise<void>;
 };
 
 /** A branch as its parent lists it. */
@@ -1232,6 +1236,17 @@ export class WorldDoors {
       try { named = listWorlds(this.worldRoot).map((w) => ({ name: w.name, running: w.running })); } catch { /* a World with no local branches */ }
       return Response.json({ world: this.served, branches: await branches.list(), checkedOut: this.name, named });
     }
+    // SERVE ANOTHER NAMED BRANCH here (`POST branches/<branch>/serve`): only who may write the World switches what it serves
+    if (rest.length === 2 && rest[1] === 'serve' && request.method === 'POST') {
+      if (!this.host.serveBranch) return Response.json({ error: `this host serves ${this.served} on one branch` }, { status: 404 });
+      if (this.credential(request).scope !== 'write') return Response.json({ error: 'serving another branch needs the World\'s write access' }, { status: 403 });
+      const target = decodeURIComponent(rest[0]!);
+      let known = false;
+      try { known = listWorlds(this.worldRoot).some((w) => w.name === target); } catch { /* no local branches */ }
+      if (!known) return Response.json({ error: `no branch ${target} in this World` }, { status: 404 });
+      try { await this.host.serveBranch(target); } catch (error) { return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 409 }); }
+      return Response.json({ world: this.served, checkedOut: target });
+    }
     if (rest.length === 0 && request.method === 'POST') {
       const body = (await request.json().catch(() => null)) as { at?: { instant?: unknown }; ttl?: unknown; live?: unknown; label?: unknown } | null;
       const instant = body?.at?.instant;

package/src/world-view.ts

@@ -2,7 +2,7 @@
 // ("as of" views) and the console, on one origin (docs/contributing/architecture.md, "Viewing a
 // World"). `volter world view` is this; the runtime's `up` gains no step. A host that serves many
 // Worlds (world-host) answers the same doors; this serves one, and the branches made of it.
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { loadWorldConfig } from './configs.ts';
 import { join, resolve } from 'node:path';
 import { serveHttp, stateDirName } from '@volter/world-core';
@@ -44,7 +44,35 @@ export async function serveWorldView(name: string, opts: { root?: string; port?:
   const browserOrigin = origins ? (served: string) => (port ? localWorldOrigin(served, port) : null) : undefined;
   const mountAt = (at: string): Promise<MountedWorld> => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}) });
   const branches: LocalBranches = new LocalBranches({ dir: join(root, stateDirName(), 'branches'), origin: () => loopback, worlds, mount: mountAt, ...(opts.announce ? { announce: opts.announce } : {}) });
-  const world = await mountWorld(name, { root, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}) });
+  // THE WORLD'S OWN BRANCHES, one served at a time: serving another stops this one's twins and starts that one's under the
+  // same served name (its tokens and sessions are the World's, so the page stays open); `.volter/current` follows, as
+  // \`volter world checkout\` sets it. While it switches, the World's doors answer 503.
+  let url = '';
+  let switching = false;
+  const serveBranch = async (branch: string): Promise<void> => {
+    if (switching) throw new Error('already switching branches');
+    if (branch === world.name) return;
+    switching = true;
+    const from = world.name;
+    try {
+      await world.stop();
+      let next: MountedWorld;
+      try {
+        next = await mountWorld(branch, mountOpts);
+        await next.boot(url);
+      } catch (error) {
+        const back = await mountWorld(from, mountOpts);
+        await back.boot(url);
+        worlds.set(back.served, back); world = back;
+        throw error;
+      }
+      worlds.set(next.served, next); world = next;
+      const current = join(root, stateDirName(), 'current');
+      if (branch === loadWorldConfig(join(root, stateDirName(), 'world.json'), root).config.id) rmSync(current, { force: true }); else writeFileSync(current, `${branch}\n`);
+    } finally { switching = false; }
+  };
+  const mountOpts = { root, branches: (served: string) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}), serveBranch };
+  let world = await mountWorld(name, mountOpts);
   worlds.set(world.served, world);
   const server = await serveHttp({
     // a pushed blob (a release video) is one PUT: bodies up to 1 GiB, as `serve` takes them
@@ -69,13 +97,14 @@ export async function serveWorldView(name: string, opts: { root?: string; port?:
         if (answered) return answered;
       }
       const m = /^\/(?:-\/)?([^/]+)\/([^/]+)/.exec(path);
+      if (switching && m && `${m[1]}/${m[2]}` === world.served) return Response.json({ error: `${world.served} is switching branches` }, { status: 503, headers: { 'retry-after': '2' } });
       const target = m ? worlds.get(`${m[1]}/${m[2]}`) : undefined;
       if (!target) return Response.json({ error: `no world at ${path}: this view serves ${[...worlds.keys()].join(', ')}` }, { status: 404 });
       return target.handle(request);
     },
   });
   port = server.port ?? 0;
-  const url = `http://${host}:${server.port}`;
+  url = `http://${host}:${server.port}`;
   loopback = `http://${host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host}:${server.port}`;
   // a branch outlives the view that made it until its time runs out: stopping stops its compute only
   const stop = async (): Promise<void> => {