@volter/world-runtime 2.0.0

package/src/served-world.ts

@@ -0,0 +1,812 @@
+import { getActiveWorldStore, withAncestryLock, captureHistory, historyDigest, historyEntries, historyLength, readHistoryView, worldPaths, type HistoryReference } from '@volter/world-core';
+// A SERVED WORLD (docs/reference/http-api.md#a-served-world): `volter world serve` puts a world at
+// `http://<host>:<port>/<org>/<world>/`. Each twin's vendor API is under its vendor id — the
+// addressed grammar RH2 depends on — and the world's own doors are under `/-/<org>/<world>/`:
+//   GET  log/<twin>?after=<n>        the twin's whole log from a position (what fetch reads)
+//   GET  checkpoint/<twin>           the tree, and the position it stands at (what clone starts from)
+//   GET  changesets[/<name>]         what landed, with receipts, verification and approvals
+//   POST push                        a changeset: its entries land on the world's log if its base is
+//                                    current (else 409 with the drift); under deploy: auto the
+//                                    receipts are in the answer, otherwise each entry is `landed`
+//   POST changesets/<name>/verify    run the world's checks over it and record the result
+//   POST changesets/<name>/approve   { as, note? } sign its current hash
+//   POST deploy[/<name>]             perform landed entries against each root, by policy
+//   GET/PUT twins/<vendor>/root      the vendor's real account behind the twin (PUT null clears)
+//   PUT  twins/<vendor>/credential   seal the credential; GET answers only that one is sealed
+//   POST twins/<vendor>/refresh      observe the root now
+// Tokens ride `x-volter-token`: the token opens everything, the read token only GET. `serve` mints
+// both, prints them once and writes them to `.volter/token` and `.volter/token.read` (0600).
+// One writer per world by construction: the doors run in this process, serialized per twin.
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync , rmSync} from 'node:fs';
+import { blobDigest, getActiveBlobStore, loadCheck, mirrorShellUnder, openSealedCredential, readTwinRequestJournal, sealingKey, serveHttp, TWIN_PREFIX_HEADER, validateRemoteOrigin, type SealedCredential, type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core';
+import { APP_READ_ENDPOINT_ENV } from './init.ts';
+import { dirname, join, resolve } from 'node:path';
+import {
+  appendActionIfAbsent, branchEntries, confirmAction, readTree, stateDirName, wholeLog, worldNow,
+  parentEntries, rebaseBranch, type Changeset, type Entry, type Receipt, type RootConfig,
+} from '@volter/world-core';
+import { approveWorldChangeset, createWorldChangeset, findWorldChangeset, listWorldChangesets, pushWorldChangeset, verifyWorldChangeset, worldChangesetsDir } from './changeset.ts';
+import { fetchFromOrigin } from './origin.ts';
+import { CONSOLE_BASE, consoleRedirect, serveConsoleApart, type ConsoleMount } from './console-apart.ts';
+import { loadWorldConfig } from './configs.ts';
+import { adaptersFor, packMirrorExports, credentialPath, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, spanMs } from './root.ts';
+import { downWorld, statusWorld, upWorld } from './runtime.ts';
+import type { WorldInstance } from './schema.ts';
+
+export const TOKEN_HEADER = 'x-volter-token';
+/** The header the injector carries a hosted World's token in (inject.cjs, VOLTER_TWINS_KEY). */
+export const TWINS_KEY_HEADER = 'x-twins-key';
+class Booting extends Error { constructor() { super('the world is still booting'); } }
+
+/** fetch that waits out a world still booting: a refused connection is retried for `forMs`. */
+export async function fetchReady(input: string, init: RequestInit, forMs = 8000): Promise<Response> {
+  const started = Date.now();
+  for (;;) {
+    try { return await fetch(input, init); } catch (error) {
+      if (Date.now() - started > forMs) throw error;
+      await new Promise((r) => setTimeout(r, 250));
+    }
+  }
+}
+const MAX_BODY = 4 * 1024 * 1024;
+
+/** The serve record beside a world, when the process it names is alive; a stale record (its serving
+ *  process gone) is removed and reads as none. */
+export type ServeRecord = { name: string; url: string; base: string; port: number; pid: number; startedAt: string };
+export function readServeRecord(worldRoot: string): ServeRecord | null {
+  const path = join(resolve(worldRoot), stateDirName(), 'serve.json');
+  if (!existsSync(path)) return null;
+  let rec: ServeRecord;
+  try { rec = JSON.parse(readFileSync(path, 'utf8')) as ServeRecord; } catch { rmSync(path, { force: true }); return null; }
+  try { process.kill(rec.pid, 0); } catch { rmSync(path, { force: true }); return null; }
+  return rec;
+}
+
+export type ServedWorld = { url: string; base: string; name: string; port: number; token: string; readToken: string; console: string | null; stop: () => Promise<void> };
+
+function mintToken(prefix: string): string { return `${prefix}${Buffer.from(crypto.getRandomValues(new Uint8Array(24))).toString('base64url')}`; }
+function writeSecret(path: string, value: string): void { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, `${value}\n`, { mode: 0o600 }); chmodSync(path, 0o600); }
+
+/** The served name: `bare.name` (`acme/team`), else `<id>/<id>`. */
+export function servedName(worldRoot: string, configRef: string): string {
+  const { config } = loadWorldConfig(configRef, worldRoot);
+  return config.bare?.name ?? `${config.id}/${config.id}`;
+}
+
+function configRefFor(worldRoot: string, name: string): string {
+  const inRepo = join(worldRoot, stateDirName(), 'world.json');
+  return existsSync(inRepo) ? inRepo : name;
+}
+
+/** A world MOUNTED for serving: its doors, its tokens, and a boot that writes the serve record once the
+ *  URL is known. `serveWorld` mounts one world on its own port; the host mounts many under one URL
+ *  (contract "Just like Neon", 4: one URL per served world, solid and discoverable). */
+/** A world mounted by a host. `token`/`readToken` read the CURRENT tokens (rotate changes them);
+ *  `twins()` names the world's twins once booted; `rotate()` mints both tokens anew — the old die
+ *  with the call — and keeps them beside the world like `boot` does. */
+export type MountedWorld = { name: string; served: string; root: string; readonly token: string; readonly readToken: string; twins: () => string[]; rotate: () => { token: string; readToken: string }; handle: (request: Request) => Promise<Response>; boot: (url: string) => Promise<void>; stop: () => Promise<void> };
+export async function mountWorld(name: string, opts: { root?: string } = {}): Promise<MountedWorld> {
+  const worldRoot = resolve(opts.root ?? process.cwd());
+  const configRef = configRefFor(worldRoot, name);
+  if (loadWorldConfig(configRef, worldRoot).config.resources) {
+    throw new Error('Hosted World has legacy capacity declarations. Review and migrate its hosting limits before adopting runtime v3; no declared bound was silently removed.');
+  }
+  const served = servedName(worldRoot, configRef);
+  // a world is served once: the serve record beside it names the URL, port and pid serving it; a live
+  // one refuses this mount before anything is bound
+  const record = join(worldRoot, stateDirName(), 'serve.json');
+  const live = readServeRecord(worldRoot);
+  if (live) throw new Error(`${served} is already served at ${live.base} (pid ${live.pid}) — use it, or \`volter world down\` there first`);
+  // the world's tokens are STABLE across restarts: a world that comes back is the same world to
+  // everyone holding its token (a clone's origin, a root's sealed credential); minted once, kept
+  const held = (file: string): string | null => { try { const t = readFileSync(join(worldRoot, stateDirName(), file), 'utf8').trim(); return t.startsWith('tok_') ? t : null; } catch { return null; } };
+  let instance: WorldInstance | null = null;
+  const host: DoorHost = {
+    ready: () => instance !== null,
+    layout: () => { if (!instance) throw new Booting(); return instance; },
+    reload: () => { instance = statusWorld(name, worldRoot); return instance; },
+    // a local twin reads the scenario its service declares (colocate.scenarioPath), if any
+    scenarioPath: (vendor) => {
+      const declared = loadWorldConfig(configRef, worldRoot).config.services.find((s) => s.id === vendor)?.colocate?.scenarioPath;
+      return declared ? resolve(worldRoot, declared) : null;
+    },
+    // a local twin is its own process: the wire forwards to the port it listens on
+    twinFetch: (vendor) => {
+      const target = instance?.services[vendor]?.url;
+      if (!target) return null;
+      return (request) => { const at = new URL(request.url); return fetch(`${target.replace(/\/+$/, '')}${at.pathname}${at.search}`, { method: request.method, headers: request.headers, ...(request.body ? { body: request.body, duplex: 'half' } : {}), redirect: 'manual' } as RequestInit); };
+    },
+  };
+  const world = new WorldDoors(name, worldRoot, configRef, served, host, held('token') ?? mintToken('tok_'), held('token.read') ?? mintToken('tok_r_'));
+  const keep = (): void => { writeSecret(join(worldRoot, stateDirName(), 'token'), world.token); writeSecret(join(worldRoot, stateDirName(), 'token.read'), world.readToken); };
+  let timers: ReturnType<typeof setInterval>[] = [];
+  return {
+    name, served, root: worldRoot,
+    get token() { return world.token; }, get readToken() { return world.readToken; },
+    twins: () => world.twins(),
+    rotate: () => { world.retoken(mintToken('tok_'), mintToken('tok_r_')); keep(); return { token: world.token, readToken: world.readToken }; },
+    handle: (request) => world.handle(request),
+    async boot(url) {
+      keep();
+      const port = Number(new URL(url).port) || 0;
+      writeFileSync(record, `${JSON.stringify({ name: served, url, base: `${url}/${served}`, port, pid: process.pid, startedAt: new Date().toISOString() }, null, 2)}\n`);
+      const booted = await upWorld(configRef, { name, root: worldRoot, keepState: true });
+      instance = booted;
+      // a root set in the config while the world was stopped reaches the twins' state now, where the deploy reads it
+      materializeRoots(loadWorldConfig(configRef, worldRoot).config, booted.dirs.data, worldRoot);
+      timers = await scheduleRefreshes(name, worldRoot, booted);
+    },
+    async stop() {
+      for (const t of timers) clearInterval(t);
+      try { rmSync(record, { force: true }); } catch { /* already gone */ }
+      const result = await downWorld(name, worldRoot);
+      if (result.externalErrors.length) throw new Error(`World "${name}" shutdown incomplete; instance and reservation retained: ${result.externalErrors.join('; ')}`);
+    },
+  };
+}
+
+/** Boot the world (state kept) and serve it on its own port. Announces and returns after boot; `stop` downs the world. */
+export async function serveWorld(name: string, opts: { root?: string; port?: number; host?: string; consolePort?: number; announce?: (info: { name: string; base: string; token: string; readToken: string; console: string | null }) => void } = {}): Promise<ServedWorld> {
+  const mounted = await mountWorld(name, opts);
+  const host = opts.host ?? '127.0.0.1';
+  // THE PORT FIRST: a port already taken fails here, loudly, before any token is written — a
+  // stale server on the port must never be mistaken for this one. Until the world is up the
+  // doors answer 503.
+  let consoleOrigin: string | null = null;
+  // a pushed blob (a release video) is one PUT: bodies up to 1 GiB, past a vendor's own media limits
+  const server = await serveHttp({ hostname: host, port: opts.port ?? 0, maxRequestBodySize: 1024 * 1024 * 1024, fetch: (request) => consoleRedirect(request, consoleOrigin) ?? mounted.handle(request) });
+  const url = `http://${host}:${server.port}`;
+  try { await mounted.boot(url); } catch (error) { await server.stop(true); throw error; }
+  // the console, when it is installed beside the World, on an origin of its own (console-apart.ts)
+  const mount = await (async (): Promise<ConsoleMount | undefined> => {
+    try { const mod = (await import('@volter/world-console')) as { createConsole: () => ConsoleMount }; return mod.createConsole(); } catch { return undefined; }
+  })();
+  let consoleServer: { url: string; server: { stop: (force?: boolean) => Promise<void> | void } } | null = null;
+  if (mount) {
+    // a stable address for a bookmark: the port asked for, else the World's port + 1 when that is free
+    const wanted = opts.consolePort ?? (server.port ? server.port + 1 : 0);
+    try { consoleServer = await serveConsoleApart(mount, { upstream: url, hostname: host, port: wanted }); }
+    catch (error) {
+      if (opts.consolePort !== undefined) { await server.stop(true); await mounted.stop(); throw error; }
+      try { consoleServer = await serveConsoleApart(mount, { upstream: url, hostname: host, port: 0 }); }
+      catch (again) { await server.stop(true); await mounted.stop(); throw again; }
+    }
+  }
+  const consoleUrl = consoleServer ? `${consoleServer.url}${CONSOLE_BASE}/` : null;
+  consoleOrigin = consoleServer?.url ?? null;
+  const stopAll = async (): Promise<void> => { await consoleServer?.server.stop(true); await server.stop(true); };
+  try {
+    opts.announce?.({ name: mounted.served, base: `${url}/${mounted.served}`, token: mounted.token, readToken: mounted.readToken, console: consoleUrl });
+  } catch (error) {
+    // Boot succeeded: this call owns the World, but cannot return its stop handle.
+    try { await stopAll(); } finally { await mounted.stop(); }
+    throw error;
+  }
+  return { url, base: `${url}/${mounted.served}`, name: mounted.served, port: server.port ?? 0, token: mounted.token, readToken: mounted.readToken, console: consoleUrl, stop: async () => { await stopAll(); await mounted.stop(); } };
+}
+
+/** The env an attacher's client reads for a stream: the protocol's own conventional names (smtp's
+ *  SMTP_HOST/SMTP_PORT…), else the service's `<ID>_TWIN_URL` as a connection URL. */
+function streamEnv(id: string, protocol: string): Record<string, string> {
+  const own = APP_READ_ENDPOINT_ENV[id]?.injectEnvTemplates;
+  if (own) return own;
+  return { [`${id.toUpperCase().replace(/-/g, '_')}_TWIN_URL`]: `${protocol}://twin:twin@\${host}:\${port}/twin` };
+}
+
+/** What the doors need of a world: where each twin's state lives and which twins it has. A booted
+ *  local instance is one; a hosted World describes itself. */
+export type WorldLayout = { dirs: { data: string }; services: Record<string, { url?: string; protocol?: unknown }> };
+/** The host a world's doors run in: its layout, and how a request reaches a twin's wire — a local
+ *  host forwards to the twin's own port, a hosted World calls the pack in-process. */
+export type DoorHost = {
+  ready: () => boolean;
+  layout: () => WorldLayout;
+  /** The layout re-read before a write lands (a local world may have been re-booted). */
+  reload: () => WorldLayout;
+  /** The twin's wire for a request whose path is the twin's own; null when the world has no such twin. */
+  twinFetch: (vendor: string) => ((request: Request) => Promise<Response>) | null;
+  /** The world's byte-stream doors (a TCP protocol a twin serves: smtp's own, planetscale's mysql),
+   *  by the id a local World gives that listener's service, when this host carries bytes over a
+   *  WebSocket (a hosted World takes no inbound TCP). */
+  streams?: () => Record<string, { protocol: string }>;
+  openStream?: (id: string, sink: TwinStreamSink, peer: string) => TwinStreamConnection | null;
+  /** Where this host reads a twin's scenario (the handlers document a generative twin serves from,
+   *  re-read on every request), or null when the twin takes none here. */
+  scenarioPath?: (vendor: string) => string | null;
+};
+
+export class WorldDoors {
+  private readonly queues = new Map<string, Promise<unknown>>();
+  token: string; readToken: string;
+  constructor(readonly name: string, readonly worldRoot: string, readonly configRef: string, readonly served: string, private readonly host: DoorHost, token: string, readToken: string) { this.token = token; this.readToken = readToken; }
+  /** New tokens; a request presenting the old ones is refused from the next call on. */
+  retoken(token: string, readToken: string): void { this.token = token; this.readToken = readToken; }
+  /** The world's twins, by vendor, once booted. */
+  twins(): string[] { return Object.keys(this.up().services); }
+  private up(): WorldLayout { return this.host.layout(); }
+
+  /** The world's token, presented the way the app's SDK presents a credential: the world's own header,
+   *  the injector's `x-twins-key` (a zero-edit app keeps its SDK's own Authorization), `Bearer <token>`,
+   *  GitHub's `token <token>`, or the password half of `Basic` (Jira's email:token). */
+  private scope(request: Request): 'write' | 'read' | null { return this.match(request)?.scope ?? null; }
+  /** The World token the request presented, in whichever form, and the scope it opens. */
+  private match(request: Request): { scope: 'write' | 'read'; token: string; fromSession: boolean } | null {
+    const authorization = request.headers.get('authorization') ?? '';
+    const bearer = /^(?:Bearer|token)\s+(\S+)$/i.exec(authorization)?.[1];
+    const basic = /^Basic\s+(\S+)$/i.exec(authorization)?.[1];
+    const basicSecret = basic ? (() => { try { const text = Buffer.from(basic, 'base64').toString('utf8'); const i = text.indexOf(':'); return i >= 0 ? text.slice(i + 1) : text; } catch { return undefined; } })() : undefined;
+    // a browser holding a session for this World (POST …/session): what a mirror page reads the wire with
+    const cookie = /(?:^|;\s*)volter_world=([^;]+)/.exec(request.headers.get('cookie') ?? '')?.[1];
+    // every form presented is a candidate: a mirror page sends the VENDOR's bearer (the X token its
+    // sign-in holds) beside the World's session cookie, and the cookie is what opens the World
+    const headed = [request.headers.get(TOKEN_HEADER), request.headers.get(TWINS_KEY_HEADER), bearer, basicSecret];
+    const session = cookie ? decodeURIComponent(cookie) : null;
+    for (const [scope, token] of [['write', this.token], ['read', this.readToken]] as const) {
+      if (headed.includes(token)) return { scope, token, fromSession: false };
+      if (session === token) return { scope, token, fromSession: true };
+    }
+    return null;
+  }
+  /** Open one connection on a byte-stream door for the holder of the World's (write) token; null when
+   *  the token is not the World's or the World has no such stream. */
+  openStream(token: string, id: string, sink: TwinStreamSink, peer: string): TwinStreamConnection | null {
+    if (token !== this.token || !this.host.openStream || !(id in (this.host.streams?.() ?? {}))) return null;
+    return this.host.openStream(id, sink, peer);
+  }
+  private serialized<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    const prior = this.queues.get(key) ?? Promise.resolve();
+    const next = prior.then(fn, fn);
+    this.queues.set(key, next.then(() => undefined, () => undefined));
+    return next;
+  }
+  private refresh(): WorldLayout { return this.host.reload(); }
+  private controlRoot(vendor: string): string { return join(this.up().dirs.data, vendor); }
+  private stateOf(vendor: string): string {
+    return stateServiceOf(this.controlRoot(vendor), vendor);
+  }
+
+  async handle(request: Request): Promise<Response> {
+    try {
+      if (!this.host.ready() && !new URL(request.url).pathname.startsWith('/-/ping')) return Response.json({ error: 'booting', world: this.served }, { status: 503, headers: { 'retry-after': '1' } });
+      const url = new URL(request.url);
+      const prefix = `/${this.served}/`;
+      if (url.pathname === '/-/ping') return Response.json({ ok: true, world: this.served, worlds: [this.served] });
+      if (url.pathname.startsWith(`/-/${this.served}/`)) return await this.door(request, url, url.pathname.slice(`/-/${this.served}/`.length));
+      // the attach manifest (@volter/world-core/attach, VOLTER_WORLD=<this World's URL>): every twin at its
+      // place under this World, and the token the injector carries to them — the presented one
+      if (url.pathname === `${prefix}.well-known/volter-world` && request.method === 'GET') {
+        // the manifest hands its caller the token it presented; a session's token is HttpOnly, never echoed to script
+        const matched = this.match(request);
+        if (matched === null || matched.fromSession) return Response.json({ error: 'token required' }, { status: 401 });
+        const presented = matched.token;
+        const vendors = Object.fromEntries(Object.keys(this.up().services).map((v) => [v, `${url.origin}/${this.served}/${v}`]));
+        // a stream is reached through the attacher's loopback bridge (@volter/world-core/stream-bridge):
+        // its env is what the client reads, with ${host}/${port} the bridge's listener
+        const ws = url.origin.replace(/^http/, 'ws');
+        const streams = Object.fromEntries(Object.entries(this.host.streams?.() ?? {}).map(([id, { protocol }]) => [id, { protocol, url: `${ws}/-/${this.served}/streams/${id}`, env: streamEnv(id, protocol) }]));
+        // a twin whose SDK is pointed by an app-read endpoint (TUNNEL_SERVER_URL, QSTASH_URL): that name, at its place here
+        const endpoints = Object.fromEntries(Object.keys(vendors).flatMap((v) => { const name = APP_READ_ENDPOINT_ENV[v]?.injectEnv; return name ? [[name, vendors[v]!]] : []; }));
+        return Response.json({ name: this.served, vendors, ca: null, proxy: null, env: { ...endpoints, VOLTER_TWINS_KEY: presented }, ...(Object.keys(streams).length ? { streams } : {}) });
+      }
+      if (url.pathname.startsWith(prefix)) return await this.wire(request, url, url.pathname.slice(prefix.length));
+      return Response.json({ error: `not this world: serving /${this.served}/` }, { status: 404 });
+    } catch (error) {
+      return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 500 });
+    }
+  }
+
+  /** The vendor wire: `/<org>/<world>/<vendor>/<rest>` → the twin's own URL. */
+  private async wire(request: Request, url: URL, rest: string): Promise<Response> {
+    const [vendor, ...tail] = rest.split('/');
+    if (tail[0] === 'mirror') return await this.mirror(request, vendor!, tail.slice(1).join('/'));
+    const scope = this.scope(request);
+    const manifestAsk = request.method === 'GET' && tail.join('/').replace(/\/+$/, '') === 'twin';
+    if (scope === null && !manifestAsk) return Response.json({ error: 'token required' }, { status: 401 });
+    if (scope === 'read' && request.method !== 'GET' && request.method !== 'HEAD') return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
+    // A LINK: a path of this World that forwards to the vendor itself with the credential sealed beside
+    // the World (the World holds the key; its callers hold the World's token). Stateless, no log.
+    // a person's browser landing on a twin's root (a mirror that moved to a `#/…` route by assigning
+    // location, which resolves against the twin's <base>) is sent to the mirror; the browser keeps the hash
+    if (request.method === 'GET' && tail.join('/') === '' && request.headers.get('sec-fetch-dest') === 'document' && this.up().services[vendor!] && (await this.hasMirror(vendor!))) {
+      return new Response(null, { status: 302, headers: { location: `/${this.served}/${vendor}/mirror/` } });
+    }
+    const link = this.link(vendor!);
+    if (link) return await this.forward(request, url, tail.join('/'), vendor!, link.origin);
+    const twin = this.host.twinFetch(vendor!);
+    if (!twin) return Response.json({ error: `no twin "${vendor}" in ${this.served}` }, { status: 404 });
+    const headers = new Headers(request.headers); headers.delete(TOKEN_HEADER); headers.delete(TWINS_KEY_HEADER); headers.delete('host');
+    // the browser's World session is the World's credential, never the twin's (a tunnel would hand it on)
+    const cookies = (headers.get('cookie') ?? '').split(/;\s*/).filter((c) => c && !c.startsWith('volter_world='));
+    if (cookies.length) headers.set('cookie', cookies.join('; ')); else headers.delete('cookie');
+    // the twin is mounted under this World's path: live URLs it mints must carry it (twinPublicBase)
+    headers.set(TWIN_PREFIX_HEADER, `/${this.served}/${vendor}`);
+    headers.set('x-forwarded-host', url.host); headers.set('x-forwarded-proto', url.protocol.replace(':', ''));
+    const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
+    const answer = await twin(new Request(`${url.origin}/${tail.join('/')}${url.search}`, { method: request.method, headers, ...(body === undefined ? {} : { body }), redirect: 'manual' }));
+    // an upgrade the twin answered (a tunnel's control or visitor socket) goes back as it is
+    if (answer.status === 101) return answer;
+    // staleness is a fact on the wire: a twin with a root says when the vendor was last observed
+    const out = new Headers(answer.headers);
+    const observedAt = this.observedAt(vendor!);
+    if (observedAt) out.set('x-volter-observed-at', observedAt);
+    return new Response(answer.body, { status: answer.status, headers: out });
+  }
+
+  /** Whether the twin's pack ships a mirror (its vendor's UI over this World's state). */
+  private async hasMirror(vendor: string): Promise<boolean> {
+    const mod = await packMirrorExports(vendor, this.worldRoot).catch(() => null);
+    return !!mod && Object.keys(mod).some((n) => /^\w+MirrorHtml$/.test(n)) && Object.keys(mod).some((n) => /^build\w+MirrorClient$/.test(n));
+  }
+
+  /** THE MIRROR MOUNT, as the hosted World serves it (apps/cloud supervisor.ts): `/<org>/<world>/<vendor>/mirror/`
+   *  and `…/mirror/assets/*`, keyless, GET only — the pack's own shell and bundle. The shell's <base> is the
+   *  twin's place under this World, so its reads go to the keyed wire with the browser's World session. */
+  private async mirror(request: Request, vendor: string, rest: string): Promise<Response> {
+    if (request.method !== 'GET') return Response.json({ error: 'the mirror mount serves the shell and its assets only' }, { status: 404 });
+    const isAsset = /^assets\/[A-Za-z0-9._-]+$/.test(rest);
+    if (rest.startsWith('assets/') && !isAsset) return Response.json({ error: 'no such asset' }, { status: 404 });
+    if (!this.up().services[vendor]) return Response.json({ error: 'no mirror for this twin' }, { status: 404 });
+    const mod = await packMirrorExports(vendor, this.worldRoot);
+    const pick = (re: RegExp) => { const k = mod && Object.keys(mod).find((n) => re.test(n) && typeof mod[n] === 'function'); return k ? (mod![k] as () => string | Promise<string>) : undefined; };
+    const html = pick(/^\w+MirrorHtml$/); const client = pick(/^build\w+MirrorClient$/); const styles = pick(/^\w+MirrorStyles$/);
+    if (!html || !client) return Response.json({ error: 'no mirror for this twin' }, { status: 404 });
+    if (rest === 'assets/app.js') return new Response(await client(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } });
+    if (rest === 'assets/styles.css' && styles) return new Response(await styles(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+    if (isAsset) return Response.json({ error: 'no such asset' }, { status: 404 });
+    const shell = mirrorShellUnder(await html(), `/${this.served}/${vendor}/`);
+    return new Response(shell, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+  }
+
+  private linksPath(): string { return join(this.worldRoot, stateDirName(), 'links.json'); }
+  /** The World's links: name → the vendor origin it forwards to. */
+  links(): Record<string, { origin: string }> {
+    const held = getActiveWorldStore().read(this.linksPath());
+    return held === null ? {} : (JSON.parse(held) as Record<string, { origin: string }>);
+  }
+  private link(name: string): { origin: string } | null { return this.links()[name] ?? null; }
+
+  /** Forward to the link's origin: the path under the link, the caller's headers with the World's
+   *  token removed and the sealed credential's headers replacing any of the same name. The vendor's
+   *  answer (status, headers, body) is streamed back as it arrives. */
+  private async forward(request: Request, url: URL, rest: string, name: string, origin: string): Promise<Response> {
+    const sealed = getActiveWorldStore().read(credentialPath(this.worldRoot, name));
+    if (sealed === null) return Response.json({ error: `the ${name} link has no credential sealed` }, { status: 409 });
+    const credential = await openSealedCredential(sealingKey(), JSON.parse(sealed) as SealedCredential, name);
+    const base = validateRemoteOrigin(origin);
+    const target = new URL(`${base.origin}/${rest}${url.search}`);
+    if (target.origin !== base.origin) return Response.json({ error: 'the path left the link origin' }, { status: 400 });
+    const headers = new Headers(request.headers);
+    for (const h of [TOKEN_HEADER, TWINS_KEY_HEADER, TWIN_PREFIX_HEADER, 'host', 'x-forwarded-host', 'x-forwarded-proto', 'cookie']) headers.delete(h);
+    for (const [k, v] of Object.entries(credential.headers)) headers.set(k, v);
+    const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 30_000);
+    try {
+      return await fetch(target, { method: request.method, headers, ...(body === undefined ? {} : { body }), redirect: 'manual', signal: controller.signal });
+    } finally { clearTimeout(timer); }
+  }
+
+  /** The instant of the twin's last completed refresh (its marker's `observedAt`), when it has a root. */
+  private observedAt(vendor: string): string | undefined {
+    try {
+      if (!rootForControlRoot(this.controlRoot(vendor), vendor)) return undefined;
+      const held = getActiveWorldStore().read(join(this.controlRoot(vendor), stateDirName(), 'world', vendor, 'refresh.json'));
+      if (held === null) return undefined;
+      const parsed = JSON.parse(held) as { observedAt?: string };
+      return typeof parsed.observedAt === 'string' ? parsed.observedAt : undefined;
+    } catch { return undefined; }
+  }
+
+  /** The world's own doors under `/-/<org>/<world>/`. */
+  private async door(request: Request, url: URL, path: string): Promise<Response> {
+    // INGEST is keyless by necessity (a vendor sends no world token): the vendor's own signature
+    // is the credential, verified by the pack's adapter with the secret sealed beside the world;
+    // without one the door does not exist for that vendor — 403, never an unverified fold.
+    const ingestMatch = /^twins\/([a-z0-9_-]+)\/ingest$/.exec(path);
+    if (ingestMatch && request.method === 'POST') {
+      const vendor = ingestMatch[1]!;
+      if (!this.up().services[vendor]) return Response.json({ error: `no twin "${vendor}" in ${this.served}` }, { status: 404 });
+      const secret = await twinSigningSecret(this.worldRoot, vendor);
+      if (secret === null) return Response.json({ error: `ingest for ${vendor} needs a signingSecret sealed with its credential` }, { status: 403 });
+      const adapters = await adaptersFor(vendor, this.worldRoot);
+      if (!adapters.ingest) return Response.json({ error: `the ${vendor} twin has no ingest adapter` }, { status: 404 });
+      return await this.serialized(`ingest:${vendor}`, () => Promise.resolve(adapters.ingest!(request, { root: this.controlRoot(vendor), secret })));
+    }
+    // ending a browser's session needs no token: it only clears the caller's own cookie, which never
+    // reaches these /-/ paths, so a page holding just the session could not otherwise sign out
+    const sessionPath = path.replace(/\/+$/, '');
+    // a person signing in from a page (the console's form, posted to this origin): the token in the
+    // form body, the session set here, then on to a page of this World
+    // a form or beacon from another site never opens or ends a session here (the console, on this host's
+    // next port, is same-site)
+    const crossSite = request.headers.get('sec-fetch-site') === 'cross-site';
+    if (sessionPath === 'session' && request.method === 'POST' && (request.headers.get('content-type') ?? '').startsWith('application/x-www-form-urlencoded')) {
+      if (crossSite) return new Response('A session is opened from this host\'s own pages.', { status: 403, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+      const form = new URLSearchParams(await request.text());
+      const token = form.get('token') ?? '';
+      if (token !== this.token && token !== this.readToken) return new Response('That token does not open this World.', { status: 401, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+      const next = form.get('next') ?? '';
+      // the path the browser would land on, normalized (%2e%2e resolves), and only inside this World
+      const landing = (() => { try { const at = new URL(next, url.origin); return at.origin === url.origin ? at.pathname : ''; } catch { return ''; } })();
+      const to = next.startsWith('/') && !next.startsWith('//') && !/[\\\s]/.test(next) && landing.startsWith(`/${this.served}/`) ? landing : `/${this.served}/`;
+      const secure = url.protocol === 'https:' ? '; Secure' : '';
+      return new Response(null, { status: 303, headers: { location: to, 'set-cookie': `volter_world=${encodeURIComponent(token)}; Path=/${this.served}/; HttpOnly; SameSite=Strict${secure}` } });
+    }
+    if (((sessionPath === 'session' && request.method === 'DELETE') || (sessionPath === 'session/end' && request.method === 'POST')) && !crossSite) {
+      const secure = url.protocol === 'https:' ? '; Secure' : '';
+      return new Response(JSON.stringify({ world: this.served, ended: true }), { status: 200, headers: { 'content-type': 'application/json', 'set-cookie': `volter_world=; Path=/${this.served}/; HttpOnly; SameSite=Strict; Max-Age=0${secure}` } });
+    }
+    const scope = this.scope(request);
+    if (scope === null) return Response.json({ error: 'token required' }, { status: 401 });
+    if (scope === 'read' && request.method !== 'GET') return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
+    const parts = path.split('/').filter(Boolean);
+    const [kind, name, verb] = parts;
+
+    if (kind === 'log' && name && request.method === 'GET') {
+      const state = this.stateOf(name);
+      const after = Number(url.searchParams.get('after') ?? '0');
+      const limit = Math.min(Number(url.searchParams.get('limit') ?? '500'), 2000);
+      if (!Number.isInteger(after) || after < 0 || !Number.isInteger(limit) || limit < 1) return Response.json({ error: 'Invalid history page bounds' }, { status: 400 });
+      const controlRoot = this.controlRoot(name);
+      const view = url.searchParams.get('view') ?? captureHistory(state, controlRoot).view;
+      const descriptor = readHistoryView(worldPaths(state, controlRoot).dir, view);
+      const entries = historyEntries(descriptor);
+      if (after > entries.length) return Response.json({ error: 'History cursor exceeds the selected view' }, { status: 400 });
+      let page = entries.slice(after, after + limit);
+      // ?receipts=1: each entry with the receipt its landing carries (a landed copy in the parent log,
+      // as the status door reads lastReceipt), for a reader showing an entry's standing; after the digest
+      if (url.searchParams.get('receipts') === '1') {
+        const landed = new Map<string, unknown>();
+        for (const e of parentEntries(state, controlRoot)) if (e.landsId && e.receipt) landed.set(e.landsId, e.receipt);
+        page = page.map((e) => (e.receipt || !landed.has(e.id) ? e : { ...e, receipt: landed.get(e.id) as typeof e.receipt }));
+      }
+      return Response.json({ twin: name, state, view, layout: descriptor.layout, digest: historyDigest({ layout: descriptor.layout, entries }), position: entries.length, after, entries: page });
+    }
+    if (kind === 'checkpoint' && name && request.method === 'GET') {
+      const state = this.stateOf(name);
+      const controlRoot = this.controlRoot(name); const cut = captureHistory(state, controlRoot);
+      return Response.json({ twin: name, state, view: cut.view, position: cut.position, tree: readTree(state, controlRoot, { view: cut.view }) });
+    }
+    if (kind === 'changesets' && request.method === 'GET') {
+      if (name) { const l = findWorldChangeset(name, { root: this.worldRoot, world: this.name }); return Response.json(l.changeset); }
+      return Response.json({ changesets: listWorldChangesets({ root: this.worldRoot, world: this.name }).map((l) => l.changeset) });
+    }
+    if (kind === 'changesets' && name && verb === 'verify' && request.method === 'POST') {
+      const outcome = await this.serialized('changesets', () => verifyWorldChangeset(name, { root: this.worldRoot, world: this.name, ephemeral: true }));
+      return Response.json(outcome);
+    }
+    if (kind === 'changesets' && name && verb === 'approve' && request.method === 'POST') {
+      const body = (await request.json()) as { as?: string; note?: string };
+      if (!body.as) return Response.json({ error: 'approve: { as, note? }' }, { status: 400 });
+      return Response.json(approveWorldChangeset(name, { root: this.worldRoot, world: this.name, principal: body.as, ...(body.note ? { note: body.note } : {}) }));
+    }
+    // a browser session for this World: the presented token as an HttpOnly cookie scoped to the World's
+    // paths, so a page served under it (a twin's mirror) reads the wire as the token's holder
+    if (kind === 'session' && !name && request.method === 'POST') {
+      const presented = this.match(request)!.token;
+      const secure = url.protocol === 'https:' ? '; Secure' : '';
+      return new Response(JSON.stringify({ world: this.served, scope }), { status: 200, headers: { 'content-type': 'application/json', 'set-cookie': `volter_world=${encodeURIComponent(presented)}; Path=/${this.served}/; HttpOnly; SameSite=Strict${secure}` } });
+    }
+    if (kind === 'links' && !name && request.method === 'GET') return Response.json({ links: this.links() });
+    if (kind === 'links' && name && request.method === 'PUT') {
+      if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name) || this.up().services[name]) return Response.json({ error: 'a link is named [a-z0-9_-] and is not a twin of this World' }, { status: 400 });
+      const body = (await request.json()) as { origin?: string };
+      try { validateRemoteOrigin(body.origin ?? ''); } catch (error) { return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 400 }); }
+      getActiveWorldStore().write(this.linksPath(), `${JSON.stringify({ ...this.links(), [name]: { origin: body.origin! } }, null, 2)}\n`);
+      return Response.json({ link: name, origin: body.origin });
+    }
+    if (kind === 'links' && name && request.method === 'DELETE') {
+      const rest = this.links(); delete rest[name];
+      getActiveWorldStore().write(this.linksPath(), `${JSON.stringify(rest, null, 2)}\n`);
+      return Response.json({ removed: name });
+    }
+    if (kind === 'checks') {
+      // the world's checks (CI on deployment): what a World without a repo is given its checks through;
+      // a check is JavaScript exporting `check` (or default) as { name, run(entry, tree) }
+      const dir = join(this.worldRoot, stateDirName(), 'checks');
+      const store = getActiveWorldStore();
+      if (!name && request.method === 'GET') return Response.json({ checks: store.list(dir).filter((f) => /\.(ts|js|mjs)$/.test(f)).map((f) => f.replace(/\.(ts|js|mjs)$/, '')).sort() });
+      if (name && !/^[a-z0-9][a-z0-9-]{0,63}$/.test(name)) return Response.json({ error: 'a check is named [a-z0-9-]' }, { status: 400 });
+      if (name && request.method === 'PUT') {
+        const source = await request.text();
+        if (source.length > MAX_BODY) return Response.json({ error: 'too large' }, { status: 413 });
+        const path = join(dir, `${name}.js`);
+        store.write(path, source);
+        try { await loadCheck(path, name); } catch (error) { store.remove(path); return Response.json({ error: `not a check: ${error instanceof Error ? error.message : String(error)}` }, { status: 400 }); }
+        return Response.json({ check: name });
+      }
+      if (name && request.method === 'DELETE') { for (const ext of ['js', 'mjs', 'ts']) store.remove(join(dir, `${name}.${ext}`)); return Response.json({ removed: name }); }
+    }
+    // THE ORIGIN, through doors (the CLI's clone, pull, changeset and push, for a World with no shell of
+    // its own): the World this one branches from, at a URL, with the token that opens it
+    if (kind === 'origin') {
+      const tokenPath = join(this.worldRoot, stateDirName(), 'origin.token');
+      const store = getActiveWorldStore();
+      const key = (): string => { const t = store.read(tokenPath)?.trim(); if (!t) throw new Error(`${this.served} has no origin — PUT /-/${this.served}/origin { url, token }`); return t; };
+      if (!name && request.method === 'GET') return Response.json({ origin: statusWorld(this.name, this.worldRoot).origin ?? null });
+      if (!name && request.method === 'PUT') {
+        const body = (await request.json()) as { url?: string; token?: string };
+        const at = /^(https?:\/\/[^/]+)\/([a-z0-9][a-z0-9_-]*\/[a-z0-9][a-z0-9_-]*)\/?$/i.exec(body.url ?? '');
+        if (!at || !body.token) return Response.json({ error: 'PUT origin: { url: "https://<host>/<org>/<world>", token }' }, { status: 400 });
+        store.write(tokenPath, `${body.token}\n`, { secret: true });
+        const fetched = await this.serialized('push', () => fetchFromOrigin(this.name, { root: this.worldRoot, url: at[1]!, namespace: at[2]!, key: body.token!, full: true }));
+        return Response.json({ origin: fetched.origin, appended: fetched.appended });
+      }
+      if (name === 'pull' && request.method === 'POST') {
+        return Response.json(await this.serialized('push', async () => {
+          const fetched = await fetchFromOrigin(this.name, { root: this.worldRoot, key: key() });
+          const rebased = Object.keys(this.up().services).map((twin) => ({ twin, ...rebaseBranch(this.stateOf(twin), this.controlRoot(twin), { origin: true }) }));
+          return { appended: fetched.appended, rebased };
+        }));
+      }
+      if (name === 'push' && request.method === 'POST') {
+        return Response.json(await this.serialized('push', async () => {
+          const queue = listWorldChangesets({ root: this.worldRoot, world: this.name }).filter((l) => l.changeset.applied === null || l.changeset.applied.outcome === 'refused').sort((a, b) => a.changeset.createdAt.localeCompare(b.changeset.createdAt));
+          const pushed = [];
+          for (const l of queue) {
+            const outcome = await pushWorldChangeset(l.changeset.name, { root: this.worldRoot, world: this.name, key: key() });
+            pushed.push({ changeset: l.changeset.name, outcome: outcome.application.outcome, receipts: outcome.application.receipts, ...(outcome.application.refusal ? { refusal: outcome.application.refusal } : {}), ...(outcome.unsent ? { unsent: outcome.unsent } : {}) });
+            if (outcome.application.outcome === 'refused') break;
+          }
+          return { pushed };
+        }));
+      }
+    }
+    if (kind === 'changesets' && !name && request.method === 'POST') {
+      const body = (await request.json().catch(() => ({}))) as { name?: string; message?: string };
+      const slug = body.message ? body.message.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) : '';
+      const cut = body.name ?? (slug || `changeset-${Date.now()}`);
+      return Response.json(await this.serialized('push', async () => createWorldChangeset(this.name, cut, { root: this.worldRoot, ...(body.message ? { message: body.message } : {}) })));
+    }
+    // THE BLOBS DOOR: a twin's resource payloads (uploaded media, file bytes) by their key under its
+    // resources directory. A push sends the ones its branch holds and this World lacks before the
+    // entries that name them, so what landed can be served and performed here. A key naming a sha256
+    // must hold those bytes (a segment that is exactly a 64-hex digest).
+    if (kind === 'blobs' && name && (request.method === 'HEAD' || request.method === 'PUT')) {
+      const key = parts.slice(2).join('/');
+      if (!key || key.split('/').some((seg) => seg === '' || seg === '.' || seg === '..') || /[\\\0]/.test(key)) return Response.json({ error: 'a blob key is a relative path' }, { status: 400 });
+      // a digest-shaped segment is lowercase, so a case-insensitive filesystem can't take unchecked bytes for it
+      if (key.split('/').some((seg) => /^[0-9a-fA-F]{64}$/.test(seg) && seg !== seg.toLowerCase())) return Response.json({ error: 'a digest in a blob key is lowercase hex' }, { status: 400 });
+      if (!this.up().services[name]) return Response.json({ error: `no twin "${name}" in ${this.served}` }, { status: 404 });
+      const path = join(worldPaths(this.stateOf(name), this.controlRoot(name)).resources, key);
+      const store = getActiveBlobStore();
+      // HEAD names the blob's own digest, so a push can tell the same key holding other bytes from the same blob
+      if (request.method === 'HEAD') {
+        const held = await store.get(path);
+        return new Response(null, { status: held === null ? 404 : 200, headers: held === null ? { 'x-volter-blob': 'absent' } : { 'x-volter-blob-sha256': blobDigest(held) } });
+      }
+      const bytes = new Uint8Array(await request.arrayBuffer());
+      // a segment that IS a digest names these bytes; a name built on one (`<sha>.json`, a blob's metadata) does not
+      const named = key.split('/').find((seg) => /^[0-9a-f]{64}$/.test(seg));
+      if (named && blobDigest(bytes) !== named) return Response.json({ error: 'the bytes do not match the sha256 the key names' }, { status: 400 });
+      await store.put(path, bytes);
+      return new Response(null, { status: 204 });
+    }
+    if (kind === 'push' && request.method === 'POST') return await this.serialized('push', () => this.push(request));
+    if (kind === 'deploy' && request.method === 'POST') {
+      const outcomes = await this.serialized('push', () => deployWorld(this.name, { root: this.worldRoot, instance: this.up(), ...(name ? { changeset: name } : {}) }));
+      return Response.json({ deployed: outcomes.map((o) => ({ twin: o.service, pushed: o.report.pushed, ...(o.report.refused ? { refused: o.report.refused } : {}), ...(o.report.failed ? { failed: o.report.failed } : {}) })) });
+    }
+    if (kind === 'requests' && !name && request.method === 'GET') {
+      // the world's request report (layer 8: Supabase's API report): the kernel's request journal per twin, summed over a period —
+      // requests by twin and status class, the response time's p50/p95, the top routes
+      const sinceMs = Number(url.searchParams.get('hours') ?? '24') * 3_600_000; const since = Date.now() - sinceMs;
+      const twins: Array<{ twin: string; requests: number; byStatus: Record<string, number>; p50Ms: number | null; p95Ms: number | null; topRoutes: Array<{ route: string; requests: number }> }> = [];
+      for (const vendor of Object.keys(this.up().services)) {
+        const entries = readTwinRequestJournal(vendor, this.controlRoot(vendor)).filter((e) => !e.at || Date.parse(e.at) >= since);
+        const byStatus: Record<string, number> = {}; const routes = new Map<string, number>(); const times: number[] = [];
+        for (const e of entries) { const cls = `${String(e.status)[0]}xx`; byStatus[cls] = (byStatus[cls] ?? 0) + 1; const route = `${e.method} ${e.path.replace(/\/[0-9]+(?=\/|$)/g, '/{id}')}`; routes.set(route, (routes.get(route) ?? 0) + 1); if (typeof e.ms === 'number') times.push(e.ms); }
+        times.sort((a, b) => a - b); const pct = (p: number): number | null => (times.length ? times[Math.min(times.length - 1, Math.floor((p / 100) * times.length))]! : null);
+        twins.push({ twin: vendor, requests: entries.length, byStatus, p50Ms: pct(50), p95Ms: pct(95), topRoutes: [...routes.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10).map(([route, requests]) => ({ route, requests })) });
+      }
+      return Response.json({ world: this.served, hours: sinceMs / 3_600_000, twins, requests: twins.reduce((n, t) => n + t.requests, 0) });
+    }
+    if (kind === 'twins' && !name && request.method === 'GET') {
+      // every twin of the world as a consumer sees it — the status door mapped over the world; what a
+      // console renders first, and what a holder of a world token (never the admin's) can ask
+      const twins: unknown[] = [];
+      for (const vendor of Object.keys(this.up().services)) {
+        const res = await this.handle(new Request(`${url.origin}/-/${this.served}/twins/${vendor}/status`, { headers: request.headers }));
+        if (res.ok) twins.push(await res.json());
+      }
+      return Response.json({ world: this.served, twins });
+    }
+    if (kind === 'twins' && name) {
+      if (verb === 'root' && request.method === 'GET') return Response.json({ twin: name, root: rootForControlRoot(this.controlRoot(name), name) ?? null, credential: sealedCredentialInfo(this.worldRoot, name) });
+      if (verb === 'root' && request.method === 'PUT') {
+        const body = (await request.json()) as RootConfig | null;
+        setTwinRoot(this.worldRoot, name, body, { config: this.configRef });
+        materializeRoots(loadWorldConfig(this.configRef, this.worldRoot).config, this.up().dirs.data, this.worldRoot);
+        return Response.json({ twin: name, root: body });
+      }
+      if (verb === 'credential' && request.method === 'PUT') {
+        const text = await request.text();
+        if (text.length > MAX_BODY) return Response.json({ error: 'too large' }, { status: 413 });
+        const info = await sealTwinCredential(this.worldRoot, name, credentialPayloadFrom(text, name));
+        return Response.json({ twin: name, sealed: true, ...info });
+      }
+      if (verb === 'credential' && request.method === 'GET') return Response.json({ twin: name, credential: sealedCredentialInfo(this.worldRoot, name) });
+      // the twin's scenario: the handlers document it serves its generative surface from, where this
+      // host reads it; the twin re-reads it on every request, so a PUT is live on the next call
+      if (verb === 'scenario') {
+        const at = this.host.scenarioPath?.(name) ?? null;
+        if (at === null) return Response.json({ error: `the ${name} twin takes no scenario on this world (a generative twin does; locally, its service declares colocate.scenarioPath)` }, { status: 404 });
+        const store = getActiveWorldStore();
+        if (request.method === 'GET') {
+          const held = store.read(at);
+          return held === null ? Response.json({ error: `the ${name} twin has no scenario` }, { status: 404 }) : new Response(held, { headers: { 'content-type': 'application/json' } });
+        }
+        if (request.method === 'PUT') {
+          const text = await request.text();
+          if (text.length > MAX_BODY) return Response.json({ error: 'too large' }, { status: 413 });
+          let doc: unknown;
+          try { doc = JSON.parse(text); } catch { return Response.json({ error: 'a scenario is a JSON document' }, { status: 400 }); }
+          if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) return Response.json({ error: 'a scenario is a JSON object' }, { status: 400 });
+          store.writeAtomic(at, text);
+          return Response.json({ twin: name, scenario: true, bytes: text.length });
+        }
+        if (request.method === 'DELETE') { store.remove(at); return Response.json({ twin: name, scenario: false }); }
+      }
+      if (verb === 'status' && request.method === 'GET') {
+        const state = this.stateOf(name);
+        // what a consumer asks a served world about a twin: its root, whether a credential is sealed,
+        // when the vendor was last asked, and how the last performed entry went
+        const root = rootForControlRoot(this.controlRoot(name), name);
+        const marker = getActiveWorldStore().read(join(this.controlRoot(name), stateDirName(), 'world', name, 'refresh.json'));
+        let refresh: unknown = null; try { if (marker !== null) refresh = JSON.parse(marker); } catch { refresh = null; }
+        const last = [...parentEntries(state, this.controlRoot(name))].reverse().find((e) => e.landsId && e.receipt);
+        return Response.json({ twin: name, state, protocol: this.up().services[name]?.protocol ?? null, root: root ?? null, credential: sealedCredentialInfo(this.worldRoot, name), refresh, position: wholeLog(state, this.controlRoot(name)).length, lastReceipt: last?.receipt ?? null, mirror: await this.hasMirror(name) });
+      }
+      if (verb === 'refresh' && request.method === 'POST') {
+        const root = rootForControlRoot(this.controlRoot(name), name);
+        if (!root) return Response.json({ error: `the ${name} twin has no root` }, { status: 409 });
+        return Response.json(await refreshTwin({ worldRoot: this.worldRoot, vendor: name, controlRoot: this.controlRoot(name), root, ...(url.searchParams.get('force') === '1' ? { force: true } : {}) }));
+      }
+    }
+    return Response.json({ error: `no such door: ${request.method} /-/${this.served}/${path}` }, { status: 404 });
+  }
+
+  /** PUSH: see `landChangeset` — the door hands the body to it. */
+  private async push(request: Request): Promise<Response> {
+    const body = (await request.json()) as Changeset | { changeset: Changeset; expect?: Record<string, HistoryReference> };
+    const changeset = 'changeset' in body && !('actions' in body) ? body.changeset : (body as Changeset);
+    if (!changeset || !Array.isArray(changeset.actions)) return Response.json({ error: 'push: a changeset object' }, { status: 400 });
+    this.refresh();
+    // fast-forward only: the client says where it last saw each twin's log (its fetch cursor); a
+    // twin that moved past it refuses with the drift — fetch, rebase, push again
+    const expect = 'expect' in body && body.expect ? body.expect : {};
+    const positionOf = (twin: string): number => wholeLog(this.stateOf(twin), this.controlRoot(twin)).length;
+    try {
+      const receipts = await landChangeset(this.name, this.worldRoot, this.up(), changeset, expect);
+      const position = Object.fromEntries([...new Set(changeset.actions.map((a) => a.service))].map((twin) => [twin, positionOf(twin)]));
+      const snapshots = Object.fromEntries(Object.keys(position).map(twin => { const head = captureHistory(this.stateOf(twin), this.controlRoot(twin)); return [twin, { view: head.view, position: head.position }]; }));
+      return Response.json({ world: this.served, changeset: changeset.name, receipts, position, snapshots });
+    } catch (error) {
+      return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 409 });
+    }
+  }
+}
+
+/**
+ * LAND a pushed changeset in a world: its entries go onto the world's branch log for each twin, in
+ * order, each by its own id (landing twice is a no-op). Under `deploy: auto` each landed entry is
+ * performed at once and its receipt answered; under `gated`/`hold` the entry waits (`landed`). The
+ * changeset object is kept beside the world's own, so verify/approve/deploy can name it. The push
+ * door and the path transport both come here.
+ */
+export async function landChangeset(name: string, worldRoot: string, instance: WorldLayout, changeset: Changeset, expected: Record<string, HistoryReference> = {}): Promise<Array<{ actionId: string; twin: string } & Receipt>> {
+  const receipts: Array<{ actionId: string; twin: string } & Receipt> = [];
+  const checks = await loadWorldChecks(worldRoot);
+  const stateOf = (twin: string): string => stateServiceOf(join(instance.dirs.data, twin), twin);
+  const byTwin = new Map<string, Entry[]>();
+  for (const item of changeset.actions) {
+    if (!instance.services[item.service]) throw new Error(`no twin "${item.service}" in this world`);
+    byTwin.set(item.service, [...(byTwin.get(item.service) ?? []), item.action as Entry]);
+  }
+  const landedByTwin = new Map<string, string[]>();
+  withAncestryLock(() => {
+    for (const [twin, at] of Object.entries(expected)) {
+      if (!instance.services[twin]) throw new Error(`Unknown expected twin ${twin}`);
+      const head = captureHistory(stateOf(twin), join(instance.dirs.data, twin));
+      if (!at || head.view !== at.view || head.position !== at.position) throw new Error(`origin moved on ${twin}; fetch and rebase before pushing`);
+    }
+    for (const [twin, entries] of byTwin) {
+      const controlRoot = join(instance.dirs.data, twin); const state = stateOf(twin);
+      const ids: string[] = [];
+      for (const entry of entries) {
+        const { shadowBasis: _basis, ...rest } = entry as Entry & { shadowBasis?: unknown };
+        const { action } = appendActionIfAbsent({ ...rest, service: state } as Parameters<typeof appendActionIfAbsent>[0], controlRoot);
+        ids.push(action.id);
+      }
+      landedByTwin.set(twin, ids);
+    }
+  });
+  for (const [twin, landedIds] of landedByTwin) {
+    const controlRoot = join(instance.dirs.data, twin); const state = stateOf(twin);
+    const root = rootForControlRoot(controlRoot, twin);
+    if (root?.deploy === 'auto') {
+      const outcome = await deployTwin({ worldRoot, vendor: twin, controlRoot, state, root, actionIds: landedIds, checks });
+      const done = new Map(outcome.report.deployed.map((d) => [d.actionId, d]));
+      const replayed = new Set(outcome.report.replayed);
+      for (const id of landedIds) {
+        const r = done.get(id);
+        if (r) receipts.push({ actionId: id, twin, status: 'deployed', at: r.at, ...(r.externalId ? { externalId: r.externalId } : {}) });
+        else if (replayed.has(id)) receipts.push({ actionId: id, twin, status: 'deployed', at: worldNow() });
+        else if (outcome.report.refused?.actionId === id) receipts.push({ actionId: id, twin, status: 'refused', at: worldNow(), reason: `${outcome.report.refused.check}: ${outcome.report.refused.reason}` });
+        else if (outcome.report.failed?.actionId === id) receipts.push({ actionId: id, twin, status: 'failed', at: worldNow(), reason: outcome.report.failed.error });
+        else receipts.push({ actionId: id, twin, status: 'skipped', at: worldNow() });
+      }
+    } else {
+      for (const id of landedIds) receipts.push({ actionId: id, twin, status: 'landed', at: worldNow() });
+    }
+  }
+  const path = join(worldChangesetsDir(name, worldRoot), `${changeset.name}.json`);
+  const store = getActiveWorldStore();
+  if (!store.exists(path)) store.write(path, `${JSON.stringify(changeset, null, 2)}\n`);
+  return receipts;
+}
+
+/** The state service a twin records under: its own id, else its single state dir, else its id. */
+function stateServiceOf(controlRoot: string, vendor: string): string {
+  const store = getActiveWorldStore();
+  const stateRoot = join(controlRoot, stateDirName(), 'world');
+  if (store.exists(join(stateRoot, vendor))) return vendor;
+  const dirs = store.list(stateRoot).filter((entry) => store.stat(join(stateRoot, entry))?.isDirectory);
+  return dirs.length === 1 ? dirs[0]! : vendor;
+}
+
+/** Confirm locally what a served world answered: each receipt lands the entry's copy on the parent
+ *  log with that receipt, so `log --receipts` shows it and the entry stops being unpushed. */
+export function landReceipts(controlRoot: string, state: string, receipts: Array<{ actionId: string } & Receipt>, at: string = worldNow()): void {
+  const entries = new Map(branchEntries(state, controlRoot).map((e) => [e.id, e]));
+  for (const r of receipts) {
+    const entry = entries.get(r.actionId);
+    if (!entry) continue; // not this branch's entry (a changeset pushed from elsewhere)
+    confirmAction({ service: state, actionId: r.actionId, subject: entry.subject, fields: entry.fields ?? {}, occurredAt: at, root: controlRoot, receipt: { status: r.status, at: r.at, ...(r.externalId ? { externalId: r.externalId } : {}), ...(r.reason ? { reason: r.reason } : {}) }, ...(r.externalId ? { vendorSubjectId: r.externalId } : {}) });
+  }
+}
+
+/** The twins of a world that refresh on a cadence: each rooted twin with `root.refresh.every` ("15m",
+ *  "1h", "30s"), else its pack's declared posture ("Refresh is the kernel's fold", 2). What a local
+ *  host puts on timers and a hosted World on its object's alarm. */
+export async function refreshSchedule(worldRoot: string, layout: WorldLayout, log: (line: string) => void = () => {}): Promise<Array<{ vendor: string; controlRoot: string; root: NonNullable<ReturnType<typeof rootForControlRoot>>; everyMs: number }>> {
+  const out: Array<{ vendor: string; controlRoot: string; root: NonNullable<ReturnType<typeof rootForControlRoot>>; everyMs: number }> = [];
+  for (const vendor of Object.keys(layout.services)) {
+    const controlRoot = join(layout.dirs.data, vendor);
+    const root = rootForControlRoot(controlRoot, vendor);
+    if (!root) continue;
+    const every = root.refresh?.every ?? (await refreshPosture(vendor, worldRoot))?.every;
+    if (!every) continue;
+    const ms = spanMs(every);
+    if (ms === null) { log(`${vendor}: refresh.every ${JSON.stringify(every)} is not <N>(s|m|h|d); not scheduled`); continue; }
+    out.push({ vendor, controlRoot, root, everyMs: Math.max(ms, 1_000) });
+  }
+  return out;
+}
+
+/** Observe each scheduled twin's root on its cadence while the world serves locally. A failed refresh
+ *  is logged, never fatal; the next tick tries again. */
+export async function scheduleRefreshes(name: string, worldRoot: string, instance: WorldInstance, log: (line: string) => void = (l) => process.stderr.write(`${l}\n`)): Promise<ReturnType<typeof setInterval>[]> {
+  const timers: ReturnType<typeof setInterval>[] = [];
+  for (const { vendor, controlRoot, root, everyMs } of await refreshSchedule(worldRoot, instance, log)) {
+    const timer = setInterval(() => { refreshTwin({ worldRoot, vendor, controlRoot, root, force: true }).then((r) => { if (!r.refreshed) log(`${vendor}: not refreshed: ${r.reason}`); }, (e: unknown) => log(`${vendor}: refresh failed: ${e instanceof Error ? e.message : String(e)}`)); }, everyMs);
+    timer.unref?.();
+    timers.push(timer);
+  }
+  return timers;
+}
+
+/** A remote given as a PATH: the world in that directory, on its checked-out branch, as `fetch` and
+ *  `push` reach it with no server between — git's file transport. The world must have booted at
+ *  least once (its logs live in its instance); `serve` or `up` makes that so. */
+export function isPathRemote(target: string): boolean { return !/^[a-z][a-z0-9+.-]*:\/\//i.test(target); }
+export function localWorld(target: string): { root: string; name: string; served: string; instance: WorldInstance } {
+  const root = resolve(target);
+  const configRef = existsSync(join(root, stateDirName(), 'world.json')) ? join(root, stateDirName(), 'world.json') : null;
+  if (!configRef) throw new Error(`${root} is not a world (no .volter/world.json)`);
+  const { config } = loadWorldConfig(configRef, root);
+  const current = join(root, stateDirName(), 'current');
+  const name = existsSync(current) && readFileSync(current, 'utf8').trim() !== '' ? readFileSync(current, 'utf8').trim() : config.id;
+  const instance = statusWorld(name, root);
+  return { root, name, served: config.bare?.name ?? `${config.id}/${config.id}`, instance };
+}