@volter/world-runtime 2.0.0 → 2.0.2

package/src/fixture-env.ts

@@ -152,6 +152,11 @@ export function isGoogleServiceAccountEnvName(name: string): boolean {
  * world-runtime must not import a pack, and the tests pin every value against the injector's actual
  * VENDOR_HOSTS predicate so either side changing makes the contract fail loudly. */
 const ENDPOINT_SHAPES: Array<{ match: RegExp; value: string; source: string }> = [
+  // the vendor's own API URL, which the World routes to its twin: an app that reads a base-URL override (empty in its
+  // example, the vendor's URL as its default) gets the vendor's URL, never an unreachable fake
+  { match: /^DYNADOT_BASE_URL$/, value: 'https://api.dynadot.com/api3.json', source: 'packages/twin/dynadot/src/index.ts hosts (api.dynadot.com); dubinc/dub apps/web/lib/dynadot/client.ts default' },
+  // Vercel KV's REST URL (the Upstash Redis REST API under Vercel's names): an upstash host the twin serves
+  { match: /(^|_)KV_REST_API_URL$/, value: 'https://twin-fake.upstash.io', source: 'packages/world-core inject VENDOR_HOSTS.upstash; lukevella/rallly KV_REST_API_URL' },
   {
     match: /(^|_)UPSTASH_REDIS_REST_URL$/,
     value: 'https://twin-fake.upstash.io',
@@ -200,6 +205,14 @@ const CREDENTIAL_SHAPES: Array<{ match: RegExp; value: (name: string) => string;
   // (`.clerk.accounts.dev`, packages/twin/clerk/src/index.ts hosts), so the boundary — the injector
   // server-side, the browser proxy browser-side — resolves it to the twin, and an app CSP that
   // allowlists that host stays legal (peak drive 2026-08-26).
+  // Stripe's keys carry their kind in their prefix, and applications check it before calling (Cal.com's Stripe app
+  // refuses a key that is not `sk_…`/`pk_…`); a webhook signing secret is `whsec_…`. Test mode, as a World is.
+  { match: /(^|_)STRIPE_[A-Z0-9_]*WEBHOOK_SECRET$/, value: () => 'whsec_twinfake0000000000000000000000000000', source: 'https://docs.stripe.com/webhooks#verify-events' },
+  { match: /(^|_)STRIPE_[A-Z0-9_]*(SECRET|PRIVATE|API)(_API)?_KEY$/, value: () => 'sk_test_twinfake000000000000000000000000000000', source: 'https://docs.stripe.com/keys (sk_test_)' },
+  { match: /(^|_)STRIPE_[A-Z0-9_]*(PUBLISHABLE|PUBLIC)(_API)?_KEY$/, value: () => 'pk_test_twinfake000000000000000000000000000000', source: 'https://docs.stripe.com/keys (pk_test_)' },
+  // tavily-auth.ts and firecrawl-auth.ts refuse a key without the vendor's prefix with the vendor's 401
+  { match: /(^|_)TAVILY_[A-Z0-9_]*(KEY|TOKEN)$/, value: () => 'tvly-twinfake00000000000000000000', source: 'packages/twin/tavily/src/tavily-auth.ts' },
+  { match: /(^|_)FIRECRAWL_[A-Z0-9_]*(KEY|TOKEN)$/, value: () => 'fc-twinfake00000000000000000000000', source: 'packages/twin/firecrawl/src/firecrawl-auth.ts FIRECRAWL_KEY_PREFIX' },
   { match: /(^|_)CLERK_[A-Z0-9_]*SECRET[A-Z0-9_]*$/, value: () => 'sk_test_twinfake000000000000000000000000000000', source: 'packages/twin/clerk/src/clerk-twin.ts' },
   { match: /(^|_)CLERK_[A-Z0-9_]*PUBLISHABLE[A-Z0-9_]*$/, value: () => `pk_test_${Buffer.from('twin.clerk.accounts.dev$').toString('base64')}`, source: 'packages/twin/clerk/src/index.ts' },
 ];
@@ -211,8 +224,20 @@ const APP_KEY_SHAPES: Array<{ match: RegExp; value: () => string; source: string
   // AES-256-GCM: the key base64-decodes to 32 bytes ("ENCRYPTION_KEY must be 32 bytes (base64-encoded)"); the 32 bytes
   // spell out that they are fake
   { match: /^ENCRYPTION_KEY$/, value: () => Buffer.from('twin-fake-encryption-key-32bytes').toString('base64'), source: "dubinc/dub apps/web/lib/encryption.ts" },
+  // AES-256-CBC as hex: the key is 32 bytes (64 hex characters) and the IV 16 (32); LibreChat refuses to boot on any
+  // other shape; the bytes spell out that they are fake
+  // AES-256 over the key's latin1 bytes: exactly 32 characters (Cal.com's symmetricEncrypt)
+  { match: /^CALENDSO_ENCRYPTION_KEY$/, value: () => 'twin-fake-calendso-key-32-chars!', source: 'calcom/cal.diy packages/lib/crypto.ts' },
+  { match: /^CREDS_KEY$/, value: () => Buffer.from('twin-fake-creds-key-of-32-bytes!').toString('hex'), source: 'LibreChat-AI/LibreChat api/server/utils/crypto.js' },
+  { match: /^CREDS_IV$/, value: () => Buffer.from('twin-fake-iv-16b').toString('hex'), source: 'LibreChat-AI/LibreChat api/server/utils/crypto.js' },
 ];
 
+/** Whether `name` is a key an application parses (APP_KEY_SHAPES): a secret init fakes in its shape, whatever the
+ *  example leaves it (LibreChat's CREDS_IV is empty in its example and not credential-shaped by name). */
+export function isAppKeyName(name: string): boolean {
+  return APP_KEY_SHAPES.some((shape) => shape.match.test(name));
+}
+
 export function fakeEnvValue(name: string): string {
   if (isGoogleOAuthClientEnvName(name)) return fakeGoogleOAuthClientJson();
   for (const shape of APP_KEY_SHAPES) if (shape.match.test(name)) return shape.value();

package/src/host-worker.ts

@@ -4,13 +4,14 @@
 // red) without disturbing sibling twins. Posts {type:'ready'} once listening.
 import { parentPort, workerData } from 'node:worker_threads';
 import type { ColocatedTwinSpec } from './host.ts';
+import { importModule } from './import-module.ts';
 
 const spec = workerData as ColocatedTwinSpec;
 
 type TwinServer = { port: number; stop: () => void | Promise<void> };
 type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean }) => TwinServer | Promise<TwinServer>;
 
-const mod = (await import(spec.module)) as Record<string, unknown>;
+const mod = await importModule(spec.module);
 const factory = mod[spec.export] as TwinServerFactory | undefined;
 if (typeof factory !== 'function') {
   throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);

package/src/host.ts

@@ -21,6 +21,7 @@
 // world config that drives it) stays vendor-agnostic — exactly like `bin` spawning.
 import { Worker } from 'node:worker_threads';
 import { siblingScript } from './sibling.ts';
+import { importModule } from './import-module.ts';
 import { pathToFileURL } from 'node:url';
 
 /** One twin to mount in the host. `module`/`export` name a `({port,root,readOnly}) => {port,stop}`
@@ -57,7 +58,7 @@ type TwinServer = { port: number; stop: () => void | Promise<void> };
 type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean; scenarioPath?: string }) => TwinServer | Promise<TwinServer>;
 
 async function loadFactory(spec: ColocatedTwinSpec): Promise<TwinServerFactory> {
-  const mod = (await import(spec.module)) as Record<string, unknown>;
+  const mod = await importModule(spec.module);
   const factory = mod[spec.export];
   if (typeof factory !== 'function') {
     throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);

package/src/import-module.ts

@@ -0,0 +1,9 @@
+// import() of what a World names a module by: a package name, a file URL, or a file path. Node's ESM loader takes an
+// absolute path only as a file:// URL — on Windows `C:\…` reads as a URL with the scheme `c:` and is refused
+// (ERR_UNSUPPORTED_ESM_URL_SCHEME); Bun takes either. A path becomes its file URL here; anything else is passed on.
+import { isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export function importModule<T = Record<string, unknown>>(specifier: string): Promise<T> {
+  return import(isAbsolute(specifier) ? pathToFileURL(specifier).href : specifier) as Promise<T>;
+}

package/src/index.ts

@@ -163,8 +163,13 @@ export { branchWorld, checkoutWorld } from './branch.ts';
 export type { BranchOptions } from './branch.ts';
 export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.ts';
 export type { DeployTwinOutcome, MaterializedRoot } from './root.ts';
-export { landReceipts, mountWorld, readServeRecord, refreshSchedule, servedName, serveWorld, TOKEN_HEADER, WorldDoors } from './served-world.ts';
-export type { DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.ts';
+export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from './served-world.ts';
+export type { BranchDoors, BranchRow, DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.ts';
+export { LocalBranches } from './local-branches.ts';
+export { serveWorldView, VIEW_CONSOLE_BASE } from './world-view.ts';
+export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from './world-origins.ts';
+export type { ViewConsole, WorldView } from './world-view.ts';
+export type { LocalBranchesOptions } from './local-branches.ts';
 export type { ServedWorld } from './served-world.ts';
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor, type ConsoleMount } from './console-apart.ts';
 

package/src/infra-cli.ts

@@ -4,6 +4,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { infraConnections, parseInfraDefinition } from './pglite-backing.ts';
 
 const phase = process.argv[2];
@@ -25,7 +26,7 @@ if (!existsSync(definition)) {
 }
 
 const base = ['compose', '-f', definition];
-const run = (args: string[]) => spawnSync('docker', [...base, ...args], {
+const run = (args: string[]) => spawnSync('docker', [...base, ...args], { windowsHide: true,
   encoding: 'utf8',
   env: { ...process.env, VOLTER_WORLD_DATA: worldData },
   timeout: 120_000,
@@ -48,8 +49,9 @@ const fail = (result: ReturnType<typeof run>): never => {
 // runtime answers it is private and chosen here, per machine, at each phase:
 //   1. VOLTER_WORLD_INFRA_BACKING=docker|pglite — explicit, for tests/operators;
 //   2. a working container runtime — the compose path, byte-identical to before;
-//   3. no container runtime + a postgres-only definition — the PGlite backing
-//      (pglite-host.ts), announced loudly;
+//   3. no container runtime + a definition of postgres and/or mongodb services —
+//      the containerless backing (pglite-backing.ts: PGlite for postgres, the
+//      MongoDB twin for mongodb), announced loudly;
 //   4. otherwise the honest refusal naming what this machine cannot serve.
 function selectBacking(): 'docker' | 'pglite' {
   const forced = process.env.VOLTER_WORLD_INFRA_BACKING;
@@ -58,7 +60,7 @@ function selectBacking(): 'docker' | 'pglite' {
     process.stderr.write(`managed infrastructure: VOLTER_WORLD_INFRA_BACKING must be docker or pglite (got ${JSON.stringify(forced)})\n`);
     process.exit(2);
   }
-  const probe = spawnSync('docker', ['info', '--format', '{{.ServerVersion}}'], { encoding: 'utf8', timeout: 10_000 });
+  const probe = spawnSync('docker', ['info', '--format', '{{.ServerVersion}}'], { windowsHide: true, encoding: 'utf8', timeout: 10_000 });
   if (probe.status === 0) return 'docker';
   // Absence of a container runtime (no binary, no daemon) is a capability
   // difference: swap backings. A PRESENT runtime failing on resources stays
@@ -71,7 +73,7 @@ function selectBacking(): 'docker' | 'pglite' {
 
 async function runPglite(): Promise<never> {
   const { unsupportedKinds, pgliteUp, pgliteStatus, pgliteDown } = await import('./pglite-backing.ts');
-  const services = parseInfraDefinition(readFileSync(definition, 'utf8'));
+  const services = parseInfraDefinition(readFileSync(definition, 'utf8')).filter((s) => composed === null || composed.includes(s.kind));
   if (services.length === 0) {
     process.stderr.write('managed infrastructure: the declared definition names no services\n');
     process.exit(1);
@@ -82,7 +84,7 @@ async function runPglite(): Promise<never> {
     process.exit(1);
   }
   if (phase === 'up') {
-    process.stdout.write('managed infrastructure backing: pglite (no container runtime)\n');
+    process.stdout.write('managed infrastructure backing: containerless (no container runtime)\n');
     try {
       await pgliteUp(services, worldData!);
     } catch (error) {
@@ -98,7 +100,7 @@ async function runPglite(): Promise<never> {
       process.stderr.write(`managed infrastructure status failed: ${status.ready}/${services.length} declared services are ready\n`);
       process.exit(1);
     }
-    process.stdout.write(`${JSON.stringify({ ok: true, services: services.length, connections: infraConnections(services, process.env) })}\n`);
+    process.stdout.write(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, process.env) })}\n`);
     process.exit(0);
   }
   await pgliteDown(services, worldData!);
@@ -106,12 +108,54 @@ async function runPglite(): Promise<never> {
   process.exit(0);
 }
 
+// ---- redis: the twin, containerless ----------------------------------------
+// A redis service is served by the redis twin (redis-backing.ts) on every machine, container runtime or not,
+// unless the operator forces the container backing; the other services take the backing chosen above. Where the
+// twin is not installed (@volter/twin-redis is not this runtime's dependency), redis goes to that backing too:
+// the container where there is one, else the backing's refusal naming redis.
+const declared = parseInfraDefinition(readFileSync(definition, 'utf8'));
+const { redisTwinCli } = await import('./redis-backing.ts');
+const twinCli = redisTwinCli([dirname(fileURLToPath(import.meta.url)), dirname(worldConfig)]);
+const twinned = process.env.VOLTER_WORLD_INFRA_BACKING === 'docker' || twinCli === undefined ? [] : declared.filter((s) => s.kind === 'redis');
+/** The services the backing below answers for: every one, or those the twin does not serve (by compose service name). */
+const composed = twinned.length === 0 ? null : declared.filter((s) => s.kind !== 'redis').map((s) => s.kind);
+if (twinned.length > 0) await runRedisTwin();
+
+async function runRedisTwin(): Promise<void> {
+  const { redisTwinDown, redisTwinStatus, redisTwinUp } = await import('./redis-backing.ts');
+  const cli = twinCli!;
+  if (phase === 'up') {
+    process.stdout.write('managed infrastructure backing: redis twin (containerless)\n');
+    try {
+      await redisTwinUp(twinned, worldData!, cli);
+    } catch (error) {
+      process.stderr.write(`managed infrastructure up failed: ${String((error as Error).message ?? error)}\n`);
+      process.exit(1);
+    }
+  } else if (phase === 'status') {
+    const ready = await redisTwinStatus(twinned, worldData!);
+    if (ready !== twinned.length) {
+      process.stderr.write(`managed infrastructure status failed: ${ready}/${declared.length} declared services are ready\n`);
+      process.exit(1);
+    }
+  } else {
+    await redisTwinDown(twinned, worldData!);
+  }
+  if (composed!.length === 0) {
+    if (phase === 'up') process.stdout.write('managed infrastructure ready\n');
+    else if (phase === 'status') process.stdout.write(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, process.env) })}\n`);
+    else process.stdout.write('managed infrastructure stopped\n');
+    process.exit(0);
+  }
+}
+
 if (selectBacking() === 'pglite') {
   await runPglite();
 }
 
+const only = composed ?? [];
 if (phase === 'up') {
-  const result = run(['up', '-d', '--wait']);
+  const result = run(['up', '-d', '--wait', ...only]);
   if (result.status !== 0) fail(result);
   process.stdout.write('managed infrastructure ready\n');
 } else if (phase === 'status') {
@@ -119,13 +163,13 @@ if (phase === 'up') {
   if (expected.status !== 0) fail(expected);
   const running = run(['ps', '--status', 'running', '--services']);
   if (running.status !== 0) fail(running);
-  const expectedNames = expected.stdout.split(/\s+/u).filter(Boolean).sort();
-  const runningNames = running.stdout.split(/\s+/u).filter(Boolean).sort();
+  const expectedNames = expected.stdout.split(/\s+/u).filter(Boolean).filter((n) => composed === null || composed.includes(n)).sort();
+  const runningNames = running.stdout.split(/\s+/u).filter(Boolean).filter((n) => composed === null || composed.includes(n)).sort();
   if (expectedNames.length === 0 || expectedNames.join('\0') !== runningNames.join('\0')) {
-    process.stderr.write(`managed infrastructure status failed: ${runningNames.length}/${expectedNames.length} declared services are ready\n`);
+    process.stderr.write(`managed infrastructure status failed: ${runningNames.length + twinned.length}/${expectedNames.length + twinned.length} declared services are ready\n`);
     process.exit(1);
   }
-  process.stdout.write(`${JSON.stringify({ ok: true, services: expectedNames.length, connections: infraConnections(parseInfraDefinition(readFileSync(definition, 'utf8')), process.env) })}\n`);
+  process.stdout.write(`${JSON.stringify({ ok: true, services: expectedNames.length + twinned.length, connections: infraConnections(declared, process.env) })}\n`);
 } else {
   const result = run(['down', '--remove-orphans']);
   if (result.status !== 0) fail(result);

package/src/init.ts

@@ -47,7 +47,7 @@ import {
   registryAcknowledgedReason,
   type CoverageReport,
 } from './covers.ts';
-import { fakeEnvValue, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from './fixture-env.ts';
+import { fakeEnvValue, isAppKeyName, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from './fixture-env.ts';
 import { resolveCatalog, twinPackageName, type Catalog } from './catalog.ts';
 import { projectEnvReads, projectManifestDirs } from './project-inspect.ts';
 import { overlayEndpointEnv, packFacts } from './pack-facts.ts';
@@ -300,6 +300,20 @@ export const APP_READ_ENDPOINT_ENV: Record<string, { injectEnv?: string; injectE
       + 'sends there. Read the mail back over the twin-only inspect sidecar: `world-smtp serve --inspect-port N`, then '
       + 'GET http://127.0.0.1:N/twin/messages/latest.',
   },
+  // RAW PROTOCOL, the gRPC kind. The Temporal SDKs dial the frontend address they are given
+  // (`Connection.connect({ address })`, `NativeConnection.connect({ address })`), conventionally read
+  // from TEMPORAL_ADDRESS — Postiz's temporal.module.ts, the SDK samples and the Temporal CLI all read
+  // that name — and speak gRPC over HTTP/2, which the http/fetch injector never sees. The value is an
+  // address (host:port), not a URL, which is why this lives here as a template and not as the
+  // descriptor's `endpointEnv` (whose `name` receives the twin's URL).
+  temporal: {
+    injectEnvTemplates: {
+      TEMPORAL_ADDRESS: '${host}:${port}',
+    },
+    note: 'no injector entry and none possible: the Temporal SDKs speak gRPC to the address they are configured with. '
+      + 'TEMPORAL_ADDRESS=<host>:<port> points them at the twin (namespace `default` exists); an app that sets '
+      + 'TEMPORAL_API_KEY turns TLS on in the SDK, which this loopback frontend does not speak — leave it unset.',
+  },
 };
 // descriptor-first migration (adding-a-twin.md §3): packs now declare their endpoint-env wiring (with its grounding
 // note) on the descriptor (`endpointEnv` on TwinPack); the table above shrinks toward empty as
@@ -442,7 +456,7 @@ const INFRA_PLACEHOLDER: Record<string, string> = {
 //
 // The subject pilots (dub, cal.com) put the number on it: world-side setup is seconds, and the
 // minutes go to the app side — most avoidably, to hand-writing infrastructure for the Postgres/
-// MySQL/Redis the repo signalled. For the kinds below, `init` upgrades the placeholder to a
+// MySQL/Redis/MongoDB the repo signalled. For the kinds below, `init` upgrades the placeholder to a
 // World-managed service and private definition with env URLs already pointing at it. The helper
 // owns its implementation behind the declared service boundary. Kinds without a recipe keep the
 // placeholder + `//infra` stub.
@@ -479,6 +493,15 @@ const COMPOSE_INFRA: Record<string, {
     volumePath: '/data',
     healthcheck: () => ['CMD', 'redis-cli', 'ping'],
   },
+  // Without a container runtime the containerless backing serves this kind with the MongoDB twin
+  // (@volter/twin-mongodb), at the same loopback port and URL.
+  mongodb: {
+    image: 'mongo:7',
+    containerPort: 27017,
+    memoryMiB: 1024,
+    volumePath: '/data/db',
+    healthcheck: () => ['CMD', 'mongosh', '--quiet', '--eval', "db.adminCommand('ping').ok"],
+  },
 };
 
 /** FNV-1a 32-bit — a tiny, dependency-free stable string hash for port derivation. */
@@ -525,9 +548,12 @@ function composeService(name: string, kind: string, signals: string[], taken: Se
   const recipe = COMPOSE_INFRA[kind]!;
   const hostPort = composePort(name, kind, taken);
   const ident = composeIdent(name);
+  // redis and mongodb run without authentication (no credentials in their images' env), so their URLs carry none
   const url = kind === 'redis'
     ? `redis://127.0.0.1:${hostPort}`
-    : `${kind}://${composeUser(name, kind)}:${ident}@127.0.0.1:${hostPort}/${ident}`;
+    : kind === 'mongodb'
+      ? `mongodb://127.0.0.1:${hostPort}/${ident}`
+      : `${kind}://${composeUser(name, kind)}:${ident}@127.0.0.1:${hostPort}/${ident}`;
   return {
     kind,
     image: recipe.image,
@@ -540,7 +566,7 @@ function composeService(name: string, kind: string, signals: string[], taken: Se
   };
 }
 
-/** The declared env of one compose service (empty for redis). */
+/** The declared env of one compose service (empty for redis and mongodb). */
 function composeEnvironment(name: string, kind: string): Array<[string, string]> {
   const ident = composeIdent(name);
   if (kind === 'postgres') {
@@ -858,7 +884,7 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     // RULE 3: credential-shaped means faked, even when no vendor claims the stem. That covers
     // app-local secrets (JWT_SECRET, ENCRYPTION_KEY) and untwinned vendors alike — and it is the
     // reason a live key committed to `.env.example` can never reach the emitted world.
-    if (isCredentialShapedEnvName(name)) {
+    if (isCredentialShapedEnvName(name) || isAppKeyName(name)) {
       env[name] = fakeEnvValue(name);
       envRows.push({ name, disposition: 'faked', source, reason: 'credential-shaped name — the example value is never copied' });
       continue;
@@ -1138,6 +1164,9 @@ current
 *.env
 credentials/
 token
+token.read
+sessions.json
+keys.json
 `;
 
 export function writeWorldInit(plan: InitPlan, options: { force?: boolean } = {}): void {

package/src/local-branches.ts

@@ -0,0 +1,173 @@
+// LOCAL BRANCHES: the branches a local host makes of the Worlds it serves (docs/contributing/architecture.md,
+// "Viewing a World"). A branch is another World: the parent's config under a new name, cloned from the
+// parent through its own doors (its history cut at an instant, when one is asked), its clock frozen at
+// that instant so no twin's catch-up walks it forward, and removed when its time runs out. world-host
+// and `volter world view` both make them with this; a hosted World's supervisor makes its own.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { stateDirName, withStateRemoval } from '@volter/world-core';
+import { clockFile } from './runtime.ts';
+import { loadWorldConfig } from './configs.ts';
+import { TOKEN_HEADER, type BranchDoors, type BranchRow, type MountedWorld } from './served-world.ts';
+
+/** What a branch records beside itself: whose branch it is, as of when, and until when. */
+type BranchRecord = { from: string; at: { instant?: string; live?: boolean; label?: string } | null; createdAt: string; expiresAt: string | null };
+const RECORD = 'branch.json';
+const SWEEP_MS = 60_000;
+
+/** A World's manifest under another name, in the manifest's own format: format 2 names a World in
+ *  `metadata.id` and serves it bare at `serving.name`; format 1 in `id` and `bare.name`. */
+function renamed(config: Record<string, unknown>, id: string, name: string): Record<string, unknown> {
+  if (config.schemaVersion === 2) {
+    return { ...config, metadata: { ...(config.metadata as Record<string, unknown> | undefined), id }, serving: { ...(config.serving as Record<string, unknown> | undefined), mode: 'bare', name } };
+  }
+  return { ...config, id, bare: { ...(config.bare as Record<string, unknown> | undefined), name } };
+}
+
+export type LocalBranchesOptions = {
+  /** where branches live: `<dir>/<org>/<world>/` */
+  dir: string;
+  /** the URL a branch reaches its parent at (the host's own listener, on loopback) */
+  origin: () => string;
+  /** the Worlds the host serves, by served name; branches join it while they live */
+  worlds: Map<string, MountedWorld>;
+  /** mount a World at a root, with its branches doors wired */
+  mount: (root: string) => Promise<MountedWorld>;
+  announce?: (line: string) => void;
+};
+
+export class LocalBranches {
+  private sweeper: ReturnType<typeof setInterval> | null = null;
+  constructor(private readonly o: LocalBranchesOptions) {}
+
+  private record(world: MountedWorld): BranchRecord | null {
+    try { return JSON.parse(readFileSync(join(world.root, stateDirName(), RECORD), 'utf8')) as BranchRecord; } catch { return null; }
+  }
+
+  /** The branches of `parent` this host holds. */
+  list(parent: string): BranchRow[] {
+    const rows: BranchRow[] = [];
+    for (const [name, world] of this.o.worlds) {
+      const r = this.record(world);
+      if (r?.from === parent) rows.push({ name, from: r.from, at: r.at, createdAt: r.createdAt, expiresAt: r.expiresAt });
+    }
+    return rows.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  }
+
+  /** Branches being made, by parent: a parent is not removed mid-clone. */
+  private readonly making = new Map<string, number>();
+  hasBranches(parent: string): boolean { return (this.making.get(parent) ?? 0) > 0 || this.list(parent).length > 0; }
+
+  /** A World's branches doors, answered by this host. */
+  doorsFor(parent: string): BranchDoors {
+    return {
+      list: async () => this.list(parent),
+      create: (at, ttl, _origin, parentKey) => this.create(parent, at, ttl, parentKey),
+      remove: async (name) => { const w = this.o.worlds.get(name); if (!w || this.record(w)?.from !== parent) return false; await this.remove(name); return true; },
+    };
+  }
+
+  private async create(parent: string, at: { instant?: string; live?: boolean; label?: string }, ttlSeconds: number | null, parentKey?: string): Promise<{ name: string; token: string; readToken: string; expiresAt: string | null }> {
+    this.making.set(parent, (this.making.get(parent) ?? 0) + 1);
+    try { return await this.make(parent, at, ttlSeconds, parentKey); } finally {
+      const left = (this.making.get(parent) ?? 1) - 1;
+      if (left > 0) this.making.set(parent, left); else this.making.delete(parent);
+    }
+  }
+  private async make(parent: string, at: { instant?: string; live?: boolean; label?: string }, ttlSeconds: number | null, parentKey?: string): Promise<{ name: string; token: string; readToken: string; expiresAt: string | null }> {
+    const from = this.o.worlds.get(parent);
+    if (!from) throw new Error(`no world ${parent} here`);
+    const [org, world] = parent.split('/') as [string, string];
+    const stamp = at.instant ? at.instant.replace(/[-:]/g, '').replace(/\.\d+Z$|Z$/, '').toLowerCase().slice(0, 13) : 'now';
+    // a labelled branch (a pull request's preview) is named for its label; the random tail keeps a replacement distinct
+    // a name already taken (a 4-hex tail's rare clash) is passed over for a fresh tail, never made over
+    const free = (): { id: string; name: string; root: string } | null => {
+      for (let tries = 0; tries < 8; tries++) {
+        const suffix = `${at.label ? `-${at.label}` : `-at-${stamp}`}-${Buffer.from(crypto.getRandomValues(new Uint8Array(2))).toString('hex')}`;
+        const id = `${world.slice(0, 64 - suffix.length)}${suffix}`;
+        const name = `${org}/${id}`; const root = join(this.o.dir, org, id);
+        if (!this.o.worlds.has(name) && !existsSync(root)) return { id, name, root };
+      }
+      return null;
+    };
+    const picked = free();
+    if (!picked) throw new Error(`no free name for a branch of ${parent}`);
+    const { id, name, root } = picked;
+    // the parent's config under the branch's own name: the same twins, served at the branch's place
+    mkdirSync(join(root, stateDirName()), { recursive: true });
+    writeFileSync(join(root, stateDirName(), 'world.json'), `${JSON.stringify(renamed(JSON.parse(readFileSync(join(from.root, stateDirName(), 'world.json'), 'utf8')) as Record<string, unknown>, id, name), null, 2)}\n`);
+    let mounted: MountedWorld | undefined;
+    try {
+      mounted = await this.o.mount(root);
+      await mounted.boot(this.o.origin());
+      this.o.worlds.set(name, mounted);
+      const origin = this.o.origin();
+      // each twin's history cut at the instant, by the parent's own history door
+      let views: unknown;
+      if (at.instant) {
+        const cut = await from.handle(new Request(`${origin}/-/${parent}/history?at=${encodeURIComponent(at.instant)}`, { headers: { [TOKEN_HEADER]: from.token } }));
+        if (!cut.ok) throw new Error(`the history of ${parent} at ${at.instant}: ${await cut.text()}`);
+        views = ((await cut.json()) as { views: unknown }).views;
+      }
+      const cloned = await mounted.handle(new Request(`${origin}/-/${name}/origin`, { method: 'PUT', headers: { [TOKEN_HEADER]: mounted.token, 'content-type': 'application/json' }, body: JSON.stringify({ url: `${origin}/${parent}`, token: parentKey ?? from.token, ...(views ? { views } : {}) }) })); // the branch's own key to its parent (the parent's doors make it), never the parent's token
+      if (!cloned.ok) throw new Error(`cloning ${parent}: ${await cloned.text()}`);
+      // the branch's clock stands at its instant, else at the parent's: no twin's catch-up walks it on
+      // (a parent whose clock was never set: the branch's stands at now, frozen there, as http-api says);
+      // a live branch (a pull request's preview) keeps the parent's time: real time, or its simulated clock
+      const clock = at.instant ?? this.frozenClock(from) ?? (at.live ? null : new Date().toISOString());
+      if (clock) { const file = clockFile(root, id); mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, `${clock}\n`); }
+      const createdAt = new Date().toISOString();
+      const expiresAt = ttlSeconds === null ? null : new Date(Date.now() + ttlSeconds * 1000).toISOString();
+      writeFileSync(join(root, stateDirName(), RECORD), `${JSON.stringify({ from: parent, at: at.instant ? { instant: at.instant } : null, createdAt, expiresAt } satisfies BranchRecord, null, 2)}\n`);
+      this.o.announce?.(`branch   ${name}  of ${parent}${at.instant ? ` as of ${at.instant}` : ''}${expiresAt ? `, until ${expiresAt}` : ''}`);
+      return { name, token: mounted.token, readToken: mounted.readToken, expiresAt };
+    } catch (error) {
+      this.o.worlds.delete(name);
+      try { await mounted?.stop(); } catch { /* reported below */ }
+      withStateRemoval(root, () => rmSync(root, { recursive: true, force: true }));
+      throw error;
+    }
+  }
+
+  /** The parent's frozen clock, when it has one. */
+  private frozenClock(world: MountedWorld): string | null {
+    try {
+      const held = readFileSync(clockFile(world.root, loadWorldConfig(join(world.root, stateDirName(), 'world.json'), world.root).config.id), 'utf8').trim();
+      return Number.isNaN(Date.parse(held)) ? null : held;
+    } catch { return null; }
+  }
+
+  /** Stop a branch and remove its World (a branch's own branches first). */
+  async remove(name: string): Promise<void> {
+    const world = this.o.worlds.get(name);
+    if (!world) return;
+    for (const child of this.list(name)) await this.remove(child.name);
+    await world.stop();
+    withStateRemoval(world.root, () => rmSync(world.root, { recursive: true, force: true }));
+    this.o.worlds.delete(name);
+    this.o.announce?.(`removed  ${name}`);
+  }
+
+  /** Remove the branches whose time ran out, now and every minute while the host serves. */
+  async resume(): Promise<void> {
+    await this.sweep();
+    this.sweeper = setInterval(() => { void this.sweep(); }, SWEEP_MS);
+    this.sweeper.unref?.();
+  }
+  /** One sweep at a time: a slow one never overlaps the next. */
+  private sweeping = false;
+  private async sweep(): Promise<void> {
+    if (this.sweeping) return;
+    this.sweeping = true;
+    try {
+      const now = Date.now();
+      for (const [name, world] of [...this.o.worlds]) {
+        const r = this.record(world);
+        if (r?.expiresAt && Date.parse(r.expiresAt) <= now && this.o.worlds.has(name)) {
+          try { await this.remove(name); } catch (error) { this.o.announce?.(`branch   ${name}: removal failed: ${error instanceof Error ? error.message : String(error)}`); }
+        }
+      }
+    } finally { this.sweeping = false; }
+  }
+  stop(): void { if (this.sweeper) clearInterval(this.sweeper); this.sweeper = null; }
+}