@volter/world-runtime 2.0.54 → 3.0.0

package/src/schema.ts

@@ -39,6 +39,13 @@ export type WorldManifestV2 = {
 
 /** The env value `init` writes for a name whose fake must be minted per instance (a service-account JSON with a real throwaway key). */
 export const MINT_ENV = '$mint';
+/** An env value `$issue:<service id>`: the credential that service's twin issues through its descriptor's
+ *  `credentialDoor`, asked for at boot once the twin is up (never committed, like `$mint`). */
+export const ISSUE_ENV_PREFIX = '$issue:';
+/** The env value `init` writes for the application's own origin (its base URL, its auth URL): resolved when a command
+ *  attaches, from the application URL the booter recorded (`volter-world app-url <world> --set`), so the app names
+ *  the address it is reached at, which only its booter knows (a browser tab's preview origin, a local port). */
+export const APP_URL_ENV = '$app-url';
 export type WorldShareProvider = 'cloudflare-quick' | 'command';
 
 /**
@@ -80,6 +87,9 @@ export type WorldExternalDiscoverSource = 'status' | 'up';
  */
 export type WorldExternalDiscover = {
   as: string;
+  /** The wire the discovered connection speaks (`postgres`, `mysql`, `mongodb`, `redis`), so a coverage report binds it
+   *  to the application's driver instead of calling it unknown. */
+  protocol?: string;
   source?: WorldExternalDiscoverSource;
   jsonPath?: string;
   pattern?: string;
@@ -142,6 +152,10 @@ export type WorldServiceConfig = {
   '//'?: string;
   id: string;
   type?: WorldServiceType;
+  /** The credential this twin issues the World's applications at boot (its pack's `credentialDoor`, copied by `init`):
+   *  `up` POSTs `body` to `path` on the running twin and sets each name of `fill` whose value is `$issue:<this id>` to
+   *  the answer's field `fill` names for it. */
+  issues?: { path: string; body: Record<string, unknown>; fill: Record<string, string> };
   /**
    * The twin PACKAGE this service boots from (`@volter/twin-<vendor>`), resolved from the world
    * root at boot by node's own `node_modules` walk (docs/concepts/worlds.md#the-config-and-the-running-world).
@@ -174,9 +188,6 @@ export type WorldServiceConfig = {
    * to loopback services directly while presenting a disguised world to the app/user.
    */
   controlPlane?: boolean;
-  /** The account a vendor's own screens (its mirror) open signed in as: its handle, username or email, which the pack
-   *  resolves against the accounts this World holds (`<vendor>MirrorSignIn`). Nothing secret is written here. */
-  signIn?: { as: string };
   injectEnv?: string;
   /**
    * Additional env vars exported into the generated world env after this service starts.
@@ -297,6 +308,8 @@ export type WorldServiceInstance = {
   port?: number;
   /** Absent for 'external' services — their URL is discovered into env vars, not assigned by us. */
   url?: string;
+  /** The twin's side ports (TwinPack.sidePorts: the SMTP twin's mailbox), by name: `volter-world url <world> <id>.<name>`. */
+  sides?: Record<string, { port: number; url: string }>;
   /** 0 for 'external' services — they have no process we own (the external tool manages it). */
   pid: number;
   log: string;
@@ -404,6 +417,10 @@ export type WorldInstance = {
   /** The ORIGIN this world clones from and fetches (docs/concepts/the-model.md): a hosted twin's
    *  namespace — its canonical history. Absent = the placeholder is the only origin. */
   origin?: { url: string; namespace: string; clonedAt?: string; fetchedAt?: string };
+  /** The facts files of the packs this World resolved from installed packages (each released pack carries its own,
+   *  `generated/pack-facts.json`): the kernel's pack-facts loader overlays them on the facts it was built with
+   *  (docs/contributing/architecture.md, "The catalog: where twins come from"). */
+  packFacts?: string[];
 };
 
 function assertStringArray(value: unknown, what: string, path: string): asserts value is string[] {
@@ -471,10 +488,13 @@ function assertExternalServiceConfig(service: Partial<WorldServiceConfig>, path:
       if (!mapping || typeof mapping !== 'object' || Array.isArray(mapping)) {
         throw new Error(`External service "${id}" discover entries must be objects in ${path}`);
       }
-      assertKeys(mapping as unknown as Record<string, unknown>, ['as', 'source', 'jsonPath', 'pattern'], `External service "${id}" discover entry`, path);
+      assertKeys(mapping as unknown as Record<string, unknown>, ['as', 'protocol', 'source', 'jsonPath', 'pattern'], `External service "${id}" discover entry`, path);
       if (!mapping.as || typeof mapping.as !== 'string') {
         throw new Error(`External service "${id}" discover entry must define string "as" in ${path}`);
       }
+      if (mapping.protocol !== undefined && !['postgres', 'mysql', 'mongodb', 'redis', 'http'].includes(mapping.protocol)) {
+        throw new Error(`External service "${id}" discover "${mapping.as}" protocol must be postgres, mysql, mongodb, redis or http in ${path}`);
+      }
       const hasJson = typeof mapping.jsonPath === 'string';
       const hasPattern = typeof mapping.pattern === 'string';
       if (hasJson === hasPattern) {
@@ -716,7 +736,7 @@ export function assertWorldSelection(value: unknown, path: string): asserts valu
 
 function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
   if (!record(value)) throw new Error(`World service must be an object in ${path}`);
-  assertKeys(value, ['id', 'type', 'description', 'source', 'execution', 'endpoint', 'bindings', 'root', 'signIn'], `Service ${String(value.id ?? '')}`, path, true);
+  assertKeys(value, ['id', 'type', 'description', 'source', 'execution', 'endpoint', 'bindings', 'root'], `Service ${String(value.id ?? '')}`, path, true);
   const source = value.source === undefined ? {} : value.source;
   const execution = value.execution === undefined ? {} : value.execution;
   const endpoint = value.endpoint === undefined ? {} : value.endpoint;
@@ -733,11 +753,6 @@ function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
   assertKeys(environment, ['values'], 'service.execution.environment', path);
   if (typeof value.id !== 'string' || value.id === '') throw new Error(`World service must define string id in ${path}`);
   if (value.description !== undefined && typeof value.description !== 'string') throw new Error(`Service "${value.id}" description must be a string in ${path}`);
-  if (value.signIn !== undefined) {
-    if (!record(value.signIn)) throw new Error(`Service "${value.id}" signIn must be an object in ${path}`);
-    assertKeys(value.signIn, ['as'], `Service "${value.id}" signIn`, path);
-    if (typeof value.signIn.as !== 'string' || value.signIn.as.trim() === '') throw new Error(`Service "${value.id}" signIn.as must name an account (a handle, username or email) in ${path}`);
-  }
   if (value.description !== undefined && value['//'] !== undefined) throw new Error(`Service "${value.id}" must not set both description and // in ${path}`);
   if (execution.cwd !== undefined && typeof execution.cwd !== 'string') throw new Error(`Service "${value.id}" execution.cwd must be a string in ${path}`);
   if (execution.controlPlane !== undefined && typeof execution.controlPlane !== 'boolean') throw new Error(`Service "${value.id}" execution.controlPlane must be a boolean in ${path}`);
@@ -754,7 +769,7 @@ function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
     if (!Array.isArray(bindings.discover)) throw new Error(`Service "${value.id}" bindings.discover must be an array in ${path}`);
     for (const mapping of bindings.discover) {
       if (!record(mapping)) throw new Error(`Service "${value.id}" bindings.discover entries must be objects in ${path}`);
-      assertKeys(mapping, ['as', 'source', 'jsonPath', 'pattern'], `Service "${value.id}" bindings.discover entry`, path);
+      assertKeys(mapping, ['as', 'protocol', 'source', 'jsonPath', 'pattern'], `Service "${value.id}" bindings.discover entry`, path);
     }
   }
   const type = value.type;
@@ -787,7 +802,6 @@ function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
     ...(bindings.injectEnvTemplates === undefined ? {} : { injectEnvTemplates: bindings.injectEnvTemplates as Record<string, string> }),
     ...(bindings.cliRedirect === undefined ? {} : { cliRedirect: bindings.cliRedirect as Record<string, string> }),
     ...(value.root === undefined ? {} : { root: value.root as WorldServiceConfig['root'] }),
-    ...(value.signIn === undefined ? {} : { signIn: { as: (value.signIn as { as: string }).as } }),
     ...(external === undefined ? {} : { external }),
   };
   if (type !== 'external' && bindings.discover !== undefined) throw new Error(`Service "${legacy.id}" bindings.discover is only valid for external services in ${path}`);
@@ -908,7 +922,6 @@ function serviceToV2(service: WorldServiceConfig): Record<string, unknown> {
     ...(Object.keys(endpoint).length ? { endpoint } : {}),
     ...(Object.keys(bindings).length ? { bindings } : {}),
     ...(service.root === undefined ? {} : { root: service.root }),
-    ...(service.signIn === undefined ? {} : { signIn: service.signIn }),
   };
 }
 

package/src/served-world.ts

@@ -1,4 +1,4 @@
-import { getActiveWorldStore, withAncestryLock, captureHistory, historyAtInstant, historyDigest, historyEntries, historyLength, readHistoryView, worldPaths, type HistoryReference } from '@volter/world-core';
+import { getActiveWorldStore, withHistoryLocks, captureHistory, historyAtInstant, historyDigest, historyEntries, historyLength, readHistoryView, worldPaths, type HistoryReference } from '@volter/world-core/runtime';
 // 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>/`:
@@ -19,27 +19,28 @@ import { getActiveWorldStore, withAncestryLock, captureHistory, historyAtInstant
 //   GET/PUT clock, POST clock/advance   the frozen instant every twin stamps from, forward only
 //   GET/POST branches, DELETE branches/<org>/<world>   the host's branches of this World ("as of" views)
 //   GET  history?at=<instant>        each twin's history cut at an instant (where such a branch starts)
-//   GET  /<org>/<world>/<vendor>/mirror/   the twin's mirror, keyless: the vendor's own UI over this World's wire
+//   GET  /<org>/<world>/<vendor>/<path>   the vendor's own screens, the pack's workspaces (its `GET /twin` lists them)
 // Tokens ride `x-volter-token`: the token opens everything, the read token only reads — on the vendor
 // wire, a twin that enforces it (`requestScopes: ['read']`) is handed the read token's other requests
 // marked read-only and refuses the writes itself. `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 { CALLER_HEADER, newTraceparent, parseTraceparent, traceparentForDelivery, readTwinRequestJournalFrom, type TwinRequestJournalCursor, assertSafeChangesetName, blobDigest, destinationOf, openSealedAt, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, mirrorShellUnder, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, validateRemoteOrigin, type SealedCredential, type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core';
+import { CALLER_HEADER, callerForHeader, newTraceparent, parseTraceparent, traceparentForDelivery, readTwinRequestJournalFrom, type TwinRequestJournalCursor, assertSafeChangesetName, blobDigest, destinationOf, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, openSealedAt, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, validateRemoteOrigin, type SealedCredential, type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core/runtime';
 import { APP_READ_ENDPOINT_ENV } from './init.ts';
+import { packFacts } from './pack-facts.ts';
 import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass, type TrustedIssuer, type WorldCredentials } from '@volter/world-access';
 import { createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import {
   appendActionIfAbsent, branchEntries, branchLogPath, branchMetaPath, changesetContentHash, changesetReadiness, confirmAction, parentLogPath, readTree, stateDirName, wholeLog, worldNow,
   parentEntries, readBranchMeta, rebaseBranch, type Changeset, type Entry, type Receipt, type RootConfig,
-} from '@volter/world-core';
+} from '@volter/world-core/runtime';
 import { approveWorldChangeset, createWorldChangeset, diffWorld, 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, worldChangesetRules, writeWorldConfig } from './configs.ts';
-import { adaptersFor, credentialPath, packMirror, type PackMirror, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, rewrapTwinCredentials, sealTwinCredential, sealedCredentialInfo, bindLegacyCredentials, setTwinRoot, spanMs } from './root.ts';
+import { adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, rewrapTwinCredentials, sealTwinCredential, sealedCredentialInfo, bindLegacyCredentials, setTwinRoot, spanMs } from './root.ts';
 import { clockFile, downWorld, listWorlds, statusWorld, upWorld } from './runtime.ts';
 import { assertChangesetRules, type WorldChangesetRules, type WorldInstance } from './schema.ts';
 
@@ -143,10 +144,6 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
       const declared = loadWorldConfig(configRef, worldRoot).config.services.find((s) => s.id === vendor)?.colocate?.scenarioPath;
       return declared ? resolve(worldRoot, declared) : null;
     },
-    // a local mirror is the pack's own, built by its builder (at serve under Bun, prebuilt under Node)
-    mirror: (vendor, file) => localMirrorFile(worldRoot, vendor, file),
-    hasMirror: async (vendor) => (await localMirror(worldRoot, vendor)) !== null,
-    mirrorSignIn: async (vendor, as, ctx) => { const mirror = await localMirror(worldRoot, vendor); try { return (await mirror?.signIn?.(as, ctx)) ?? null; } catch { return null; } },
     clockPath: () => clockFile(worldRoot, name),
     ...(opts.branches?.(served) ? { branches: opts.branches(served)! } : {}),
     ...(opts.browserOrigin ? { browserOrigin: () => opts.browserOrigin!(served), originOf: (other: string) => opts.browserOrigin!(other) } : {}),
@@ -157,7 +154,9 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
     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); };
+      // the body as bytes, none when empty: an empty body streamed is sent chunked with no last chunk (Bun 1.2), and the
+      // twin's server reads the next request on the connection as its continuation (HPE_INVALID_CHUNK_SIZE)
+      return async (request) => { const at = new URL(request.url); const body = request.body ? new Uint8Array(await request.arrayBuffer()) : undefined; return fetch(`${target.replace(/\/+$/, '')}${at.pathname}${at.search}`, { method: request.method, headers: request.headers, ...(body?.byteLength ? { body } : {}), redirect: 'manual' } as RequestInit); };
     },
   };
   const world = new WorldDoors(name, worldRoot, configRef, served, host, held('token') ?? mintToken('tok_'), held('token.read') ?? mintToken('tok_r_'));
@@ -222,28 +221,6 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
   return mounted;
 }
 
-/** A local World's mirrors: each pack's builders, found once per process, and each client built once. */
-const localMirrors = new Map<string, Promise<PackMirror | null>>();
-const builtMirrorFiles = new Map<string, Promise<string | null>>();
-function localMirror(worldRoot: string, vendor: string): Promise<PackMirror | null> {
-  const key = `${worldRoot}\0${vendor}`;
-  let held = localMirrors.get(key);
-  if (!held) { held = packMirror(vendor, worldRoot).catch(() => null); localMirrors.set(key, held); }
-  return held;
-}
-async function localMirrorFile(worldRoot: string, vendor: string, file: string): Promise<Response | null> {
-  const mirror = await localMirror(worldRoot, vendor);
-  if (!mirror) return null;
-  if (file === 'index.html') return new Response(mirror.html(), { headers: { 'content-type': 'text/html; charset=utf-8' } });
-  const build = file === 'assets/app.js' ? mirror.client : file === 'assets/styles.css' ? mirror.styles : undefined;
-  if (!build) return null;
-  const key = `${worldRoot}\0${vendor}\0${file}`;
-  let held = builtMirrorFiles.get(key);
-  // a failed build is not kept: the next request builds again
-  if (!held) { held = build().catch(() => { builtMirrorFiles.delete(key); return null; }); builtMirrorFiles.set(key, held); }
-  const body = await held;
-  return body === null ? null : new Response(body, { headers: { 'content-type': file.endsWith('.css') ? 'text/css; charset=utf-8' : 'text/javascript; charset=utf-8' } });
-}
 
 /** 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> {
@@ -306,7 +283,7 @@ export type DoorHost = {
   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),
+  /** The world's byte-stream doors (a TCP protocol a twin serves: smtp's),
    *  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 }>;
@@ -314,16 +291,6 @@ export type DoorHost = {
   /** 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;
-  /** A twin's mirror as its pack builds it: `index.html` (the shell) or `assets/<file>`, or null when
-   *  the twin has none here. Every host answers the same mount (`/<served>/<vendor>/mirror/`); only
-   *  where the files come from differs (built at serve under Bun, prebuilt under Node, static assets
-   *  on Cloudflare). */
-  mirror?: (vendor: string, file: string) => Promise<Response | null>;
-  /** Whether the twin has a mirror on this host, without building it. */
-  hasMirror?: (vendor: string) => boolean | Promise<boolean>;
-  /** The account and token a twin's screens open signed in as, resolved by its pack from the twin's state at `root`
-   *  for the account the World's config names (`signIn.as`); null when the pack cannot, or has no such account. */
-  mirrorSignIn?: (vendor: string, as: string, ctx: { root: string; twin: (path: string, init?: RequestInit) => Promise<Response> }) => Promise<{ account: string; token: string } | null>;
   /** Where this World's clock lives in its store (the file every twin reads `worldNow()` from). */
   clockPath?: () => string;
   /** The origin a browser reaches this World at (`http://<world>--<org>.localhost:<port>`), when the
@@ -375,7 +342,6 @@ export function worldOriginLabel(served: string): string | null {
 /** The header the doors set on a read-scope request to a twin: the twin refuses the caller's writes
  *  and still makes the vendor's own moves. It only restricts, so a twin trusts it without a token. */
 export const READ_ONLY_HEADER = 'x-volter-read-only';
-const MIRROR_ASSET = /^assets\/[A-Za-z0-9._-]+$/;
 const SPAN = /^(\d+(?:\.\d+)?)(s|m|h|d)$/;
 const SPAN_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;
 /** A W3C traceparent's trace id, or null when the value is not one. */
@@ -400,7 +366,7 @@ export class WorldDoors {
   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. */
   // new tokens end everything the old ones reached: every session and every named key
-  retoken(token: string, readToken: string): void { this.token = token; this.readToken = readToken; this.endSessions(); this.keepKeys([]); this.signIns.clear(); }
+  retoken(token: string, readToken: string): void { this.token = token; this.readToken = readToken; this.endSessions(); this.keepKeys([]); }
 
   /** BROWSER SESSIONS: the session cookie carries an opaque id, never a token, so a leaked cookie is one session and
    *  not the World's write token; rotating the tokens ends every session. Kept in the World's store, so a restart
@@ -578,7 +544,7 @@ export class WorldDoors {
   private scope(request: Request): 'write' | 'read' | null { return this.credential(request).scope; }
   /** The request's scope, whether it came by a token the caller presented or by a browser's session
    *  (the cookie `POST …/session` set), and the token that opened it. Every form presented is a
-   *  candidate: a mirror page sends the VENDOR's bearer (the token its sign-in holds) beside the World's
+   *  candidate: a screen's page sends the VENDOR's bearer (the token its sign-in holds) beside the World's
    *  session cookie, and the cookie is what opens the World. With a browser origin of its own
    *  (`browserOrigin`), a World honours its session only on that origin: a session cookie on any other
    *  (a host's shared origin, path-addressed) opens nothing. */
@@ -724,14 +690,21 @@ export class WorldDoors {
         // 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]!]] : []; }));
+        // each twin's endpoint variables as its descriptor declares them (`endpointEnv`, or the app-read table's), at its
+        // place here: the name, and each template on its URL (a template on a listener's host and port is a stream's)
+        const endpoints = Object.fromEntries(Object.keys(vendors).flatMap((v) => {
+          const declared = packFacts()[v]?.endpointEnv;
+          const name = declared?.name ?? APP_READ_ENDPOINT_ENV[v]?.injectEnv;
+          const templates = declared?.templates ?? APP_READ_ENDPOINT_ENV[v]?.injectEnvTemplates ?? {};
+          return [
+            ...(name ? [[name, vendors[v]!]] : []),
+            ...Object.entries(templates).filter(([, t]) => !/\$\{(?:host|port)\}/.test(t)).map(([n, t]) => [n, t.replaceAll('${url}', 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)) {
         const rest = url.pathname.slice(prefix.length);
-        const mirror = /^([a-z0-9_-]+)\/mirror(?:\/(.*))?$/.exec(rest);
-        if (mirror) return await this.mirror(request, url, mirror[1]!, mirror[2] ?? '');
         return await this.wire(request, url, rest);
       }
       return Response.json({ error: `not this world: serving /${this.served}/` }, { status: 404 });
@@ -740,64 +713,21 @@ export class WorldDoors {
     }
   }
 
-  /** THE MIRROR MOUNT: `/<served>/<vendor>/mirror/` and `…/mirror/assets/<file>`, keyless and GET only —
-   *  the pack's own shell and client. The shell's <base> is the twin's place in this World, so the
-   *  mirror reads and writes the World's wire with the browser's session (`POST …/session`); any
-   *  other path under mirror/ is one of the mirror's own routes (a reloaded deep link) and gets the
-   *  shell. A link is not a twin and has no mirror. */
-  private async mirror(request: Request, url: URL, vendor: string, rest: string, /** answered at the twin's place (the vendor's site) */ atSite = false): Promise<Response> {
-    if (request.method !== 'GET' && request.method !== 'HEAD') return Response.json({ error: 'the mirror mount serves the shell and its assets only' }, { status: 405, headers: { allow: 'GET, HEAD' } });
-    const isAsset = MIRROR_ASSET.test(rest);
-    if (rest.startsWith('assets/') && !isAsset) return Response.json({ error: 'no such asset' }, { status: 404 });
-    if (!this.up().services[vendor] || !this.host.mirror) return Response.json({ error: `no mirror for ${vendor} in ${this.served}` }, { status: 404 });
-    const file = await this.host.mirror(vendor, isAsset ? rest : 'index.html');
-    if (!file || file.status !== 200) return Response.json({ error: isAsset ? 'no such asset' : `no mirror for ${vendor} in ${this.served}` }, { status: 404 });
-    if (isAsset) return file;
-    // the shell's own address is the vendor's site at the twin's place (wire, above): a page opened here goes there, so
-    // a mirror that routes by its path sees its home, not `mirror/` (the browser keeps any `#/…` route)
-    if (rest === '' && !atSite && ['document', 'iframe'].includes(request.headers.get('sec-fetch-dest') ?? '')) return new Response(null, { status: 302, headers: { location: `/${this.served}/${vendor}/${url.search}` } });
-    // the shell's <base> is the twin's place under this World (its reads go to the World's wire), its assets stay under
-    // mirror/, and its `#/…` links keep working under that base (world-core mirror-shell.ts)
-    let html = mirrorShellUnder(await file.text(), `/${this.served}/${vendor}/`);
-    // SIGNED IN AS the config says (`signIn.as`): the screens are handed the account and a credential the World minted
-    // for it, before they start. Only to a request that may write this World (a read link signs no one in, and minting
-    // is a write), on the vendor's site (never the keyless mount), at the World's own origin: a shared origin's other
-    // pages, and a rebound name reaching this port, are not this World's pages. Checked here, whoever called.
-    const own = this.host.browserOrigin?.() ?? null;
-    const signs = atSite && own !== null && url.host === new URL(own).host && this.credential(request).scope === 'write';
-    const as = signs ? loadWorldConfig(this.configRef, this.worldRoot).config.services.find((s) => s.id === vendor)?.signIn?.as : undefined;
-    const given = as ? await this.signedIn(vendor, as, url.origin) : null;
-    if (given) {
-      // data, never markup: every character that could end the script or the line is escaped, and the replacement is a
-      // function, so no `$&` or `$'` in a value is expanded into the page
-      const data = JSON.stringify({ account: given.account, token: given.token }).replace(/[<>&\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
-      html = html.replace(/<script/i, (tag) => `<script>window.__VOLTER_SIGN_IN__=${data};</script>${tag}`);
-    }
-    // where the console lives on the World's own origin, only that origin frames the World's pages (no clickjacking);
-    // a page that carries a credential is never stored, and differs by who asked
-    return new Response(html, { status: 200, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': given ? 'no-store, private' : 'no-cache', vary: given ? 'Sec-Fetch-Dest, Cookie, Authorization' : 'Sec-Fetch-Dest', ...(own ? { 'content-security-policy': "frame-ancestors 'self'" } : {}) } });
-  }
-
-  /** A vendor's screens' sign-in (`signIn.as`), once per account every twelve hours while this World is served (rotating the
-   *  tokens forgets them): the pack finds the account and mints its credential through the twin's own doors; a failure
-   *  is not kept, so the next page asks again. An account or credential that is not plain printable text is refused. */
-  private readonly signIns = new Map<string, Promise<{ account: string; token: string } | null>>();
-  private readonly signInAt = new Map<string, number>();
-  private signedIn(vendor: string, as: string, origin: string): Promise<{ account: string; token: string } | null> {
-    const key = `${vendor}\0${as}`;
-    if (Date.now() - (this.signInAt.get(key) ?? 0) > 43_200_000) this.signIns.delete(key);
-    let held = this.signIns.get(key);
-    if (!held) {
-      this.signInAt.set(key, Date.now());
-      const twin = this.host.twinFetch(vendor);
-      held = !twin || !this.host.mirrorSignIn ? Promise.resolve(null) : this.host.mirrorSignIn(vendor, as, {
-        root: this.controlRoot(vendor),
-        twin: (path, init) => twin(new Request(`${origin}${path.startsWith('/') ? path : `/${path}`}`, init)),
-      }).then((given) => (given && /^[\x21-\x7e]{1,512}$/.test(given.token) && /^[^\x00-\x1f\x7f]{1,256}$/.test(given.account) ? given : null)).catch(() => null);
-      this.signIns.set(key, held);
-      void held.then((given) => { if (!given) this.signIns.delete(key); });
-    }
-    return held;
+  /** A twin's workspaces as its discovery door lists them (`GET /twin`'s `screens`: each built workspace screen's id and
+   *  path), which a person is shown at `/<served>/<vendor><path>`. Asked again after a minute, as `enforcesRead` is. */
+  private readonly workspaces = new Map<string, { screens: Array<{ id: string; path: string }>; at: number }>();
+  private async screensOf(vendor: string): Promise<Array<{ id: string; path: string }>> {
+    const known = this.workspaces.get(vendor);
+    if (known !== undefined && Date.now() - known.at < 60_000) return known.screens;
+    let screens: Array<{ id: string; path: string }> = [];
+    const twin = this.host.twinFetch(vendor);
+    try {
+      const answer = twin ? await twin(new Request('http://world.local/twin', { headers: { [READ_ONLY_HEADER]: '1' } })) : null;
+      const listed = answer?.ok ? ((await answer.json()) as { screens?: unknown }).screens : undefined;
+      if (Array.isArray(listed)) screens = listed.filter((x): x is { id: string; path: string } => typeof x?.id === 'string' && typeof x?.path === 'string').map(({ id, path }) => ({ id, path }));
+    } catch { screens = []; }
+    this.workspaces.set(vendor, { screens, at: Date.now() });
+    return screens;
   }
 
   /** Whether a twin enforces a read-scope request itself (its manifest names `requestScopes: ['read']`):
@@ -848,7 +778,7 @@ export class WorldDoors {
     // the request's trace: the caller's trace-id goes on (or a new one), under a parent-id the World mints, which the
     // request's log entries carry, so each entry is joined to its caller by an id no caller chose
     headers.delete(CALLER_HEADER);
-    const who = this.callerOf(request); if (who) headers.set(CALLER_HEADER, who);
+    const who = this.callerOf(request); if (who) headers.set(CALLER_HEADER, callerForHeader(who));
     headers.set('traceparent', traceparentForDelivery(headers.get('traceparent')) ?? newTraceparent());
     // at a twin that enforces the read scope, every request of the read token is marked read-only (a GET
     // that would write for its caller is refused too); at any other, its GET passes as it always has
@@ -863,19 +793,6 @@ export class WorldDoors {
     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;
-    // THE VENDOR'S SITE: a page the twin does not serve as a page itself (it serves an OAuth screen, a redirect) is the
-    // vendor's own screens, the mirror, answered at that very address: the twin's place is the vendor's site, and a
-    // mirror's routes are real URLs, reloadable and linkable, as a dev server falls back to its app for unknown pages
-    const servedAsPage = (answer.status >= 300 && answer.status < 400) || (answer.status < 300 && (answer.headers.get('content-type') ?? '').includes('text/html'));
-    // a credential reached it: the manifest's keyless GET never becomes a page (and never signs anyone in). A resource
-    // the twin answers (a JSON link, a stored file, a PDF: 2xx) opened in a tab is that resource, as the vendor's own
-    // address would be; an address it refuses or has nothing at (a browser brings no vendor token), and the site's
-    // home, are the screens
-    const unanswered = answer.status >= 400 || tail.join('/') === '';
-    if (page && scope !== null && !servedAsPage && unanswered && (await this.host.hasMirror?.(vendor!))) {
-      await answer.body?.cancel().catch(() => undefined);
-      return await this.mirror(request, url, vendor!, '', true);
-    }
     // 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!);
@@ -887,7 +804,8 @@ export class WorldDoors {
     // an origin of its own with no scripts, so it can neither read the session's World nor make it a key
     const type = (answer.headers.get('content-type') ?? '').toLowerCase();
     if (page && answer.status < 300 && /^(image\/svg\+xml|application\/xhtml\+xml|text\/xml|application\/xml)\b/.test(type)) out.set('content-security-policy', 'sandbox');
-    // a page and an API call to one address are answered differently (the vendor's site): caches keep them apart
+    // a page and an API call to one address may be answered differently (a stored file opened as a page is sandboxed
+    // above): caches keep them apart
     out.append('vary', 'Sec-Fetch-Dest');
     const setCookies = answer.headers.getSetCookie();
     if (setCookies.some((c) => /^\s*(?:__Host-)?volter_world=/i.test(c))) {
@@ -1031,7 +949,7 @@ export class WorldDoors {
     if (scope === null) return Response.json({ error: 'token required' }, { status: 401 });
     const parts = path.split('/').filter(Boolean);
     const [kind, name, verb] = parts;
-    // a browser session is opened by either token: the read token's is how a view-only link opens a mirror
+    // a browser session is opened by either token: the read token's is how a view-only link opens a vendor's screens
     // the session gate comes first: a page that holds only the cookie (a sibling World's, the same site) can neither
     // re-issue nor end the session through this door
     const foreign = this.crossOriginSession(request, via);
@@ -1051,7 +969,8 @@ export class WorldDoors {
       const instant = url.searchParams.get('at') ?? '';
       if (Number.isNaN(Date.parse(instant))) return Response.json({ error: 'history?at=<ISO-8601 instant>' }, { status: 400 });
       const views: Record<string, HistoryReference> = {};
-      withAncestryLock(() => { for (const vendor of Object.keys(this.up().services)) views[vendor] = historyAtInstant(this.stateOf(vendor), instant, this.controlRoot(vendor)); });
+      const vendors = Object.keys(this.up().services);
+      withHistoryLocks(vendors.map((vendor) => worldPaths(this.stateOf(vendor), this.controlRoot(vendor)).dir), () => { for (const vendor of vendors) views[vendor] = historyAtInstant(this.stateOf(vendor), instant, this.controlRoot(vendor)); });
       return Response.json({ world: this.served, at: new Date(Date.parse(instant)).toISOString(), views });
     }
     if (kind === 'map' && !name && request.method === 'GET') return Response.json(await this.map());
@@ -1358,7 +1277,7 @@ export class WorldDoors {
         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, mirror: Boolean(await this.host.hasMirror?.(name)), root: root ?? null, credential: sealedCredentialInfo(this.worldRoot, name), refresh, position: wholeLog(state, this.controlRoot(name)).length, lastReceipt: last?.receipt ?? null });
+        return Response.json({ twin: name, state, protocol: this.up().services[name]?.protocol ?? null, screens: await this.screensOf(name), root: root ?? null, credential: sealedCredentialInfo(this.worldRoot, name), refresh, position: wholeLog(state, this.controlRoot(name)).length, lastReceipt: last?.receipt ?? null });
       }
       if (verb === 'refresh' && request.method === 'POST') {
         const root = rootForControlRoot(this.controlRoot(name), name);
@@ -1370,7 +1289,7 @@ export class WorldDoors {
   }
 
   /** 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, in the
+   *  paths, so a page served under it (a vendor's screen) reads the wire as the token's holder, in the
    *  token's scope. */
   /** THE LOCAL SESSION: a World served on this machine's loopback never asks the person at it for a token. Any
    *  website can send requests to 127.0.0.1, so what stands in for the token is proof the request is this World's own
@@ -1536,7 +1455,7 @@ export class WorldDoors {
     return newest;
   }
 
-  /** THE MAP: every twin and what it holds, by resource type, and whether it has a mirror. */
+  /** THE MAP: every twin and what it holds, by resource type, and the workspaces it shows. */
   private async map(): Promise<unknown> {
     const twins: unknown[] = [];
     for (const vendor of Object.keys(this.up().services)) {
@@ -1547,7 +1466,7 @@ export class WorldDoors {
       for (const r of readTree(state, controlRoot)) if (r.deleted !== true && !r.type.startsWith('_')) counts.set(r.type, (counts.get(r.type) ?? 0) + 1);
       twins.push({
         twin: vendor, position: wholeLog(state, controlRoot).length,
-        mirror: Boolean(await this.host.hasMirror?.(vendor)),
+        screens: await this.screensOf(vendor),
         root: rootForControlRoot(controlRoot, vendor) ?? null,
         resources: [...counts].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([type, count]) => ({ type, count })),
       });
@@ -1676,7 +1595,8 @@ export async function landChangeset(name: string, worldRoot: string, instance: W
     byTwin.set(item.service, [...(byTwin.get(item.service) ?? []), item.action as Entry]);
   }
   const landedByTwin = new Map<string, string[]>();
-  withAncestryLock(() => {
+  const pushed = [...new Set([...Object.keys(expected).filter((twin) => instance.services[twin]), ...byTwin.keys()])];
+  withHistoryLocks(pushed.map((twin) => worldPaths(stateOf(twin), join(instance.dirs.data, twin)).dir), () => {
     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));

package/src/tail.ts

@@ -8,7 +8,7 @@
 // notice, never an error.
 import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, statSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
-import { stateDirName } from '@volter/world-core';
+import { stateDirName } from '@volter/world-core/runtime';
 import { statusWorld } from './runtime.ts';
 
 /** The slice of a ledger row `tail` renders. Rows are vendor-recorded TwinActions

package/src/up-cli.ts

@@ -0,0 +1,55 @@
+// `volter-world up`, loaded on its own (./cli.ts): it hands the boot to its owner process (./up-task.ts) before
+// any other command's modules load, so a World's start never waits on them. Where each module is compiled as
+// the process starts (a browser tab's engine compiles every module it loads), those modules were most of the
+// CLI's time before the owner process began.
+import { optionValue, ownerOption } from './cli-args.ts';
+import type { upWorld } from './runtime.ts';
+import { superviseWorldUp } from './up-task.ts';
+
+export async function upCommand(subject: string | undefined, rest: string[], root: string): Promise<void> {
+  if (rest.some(arg => arg === '--env-file' || arg.startsWith('--env-file='))) throw new Error('--env-file is not an input for this command. Use --env-out=<new-output-path>; never pass credentials or custody as an output.');
+  if (!subject) throw new Error('volter-world up: missing config');
+  const envFile = optionValue(rest, '--env-out');
+  if (!envFile) throw new Error('volter-world up: missing required --env-out=<path>');
+  const name = optionValue(rest, '--name') || undefined;
+  const mode = optionValue(rest, '--mode', 'local') as 'local' | 'share' | 'sealed';
+  const isolationArg = optionValue(rest, '--isolation');
+  if (isolationArg && isolationArg !== 'process' && isolationArg !== 'colocated' && isolationArg !== 'worker') {
+    throw new Error(`volter-world up: invalid --isolation "${isolationArg}" (want process|colocated|worker)`);
+  }
+  const isolation = (isolationArg || undefined) as 'process' | 'colocated' | 'worker' | undefined;
+  // The boot runs in its own owner process (./up-task.ts): a closed terminal does not leave it half-done.
+  // --keep-state: boot over the state the World's directory already holds (a World carried somewhere else, e.g. a
+  // browser tab's image, comes up over its data instead of starting empty, as a fresh `up` does)
+  const keepState = rest.includes('--keep-state');
+  const instance = await superviseWorldUp(subject, { name, root, mode, envFile, forceEnvOutput: rest.includes('--force'), owner: ownerOption(rest), ...(isolation ? { isolation } : {}), ...(keepState ? { keepState: true } : {}) });
+  printReady(instance);
+}
+
+export function printReady(instance: Awaited<ReturnType<typeof upWorld>>): void {
+  process.stdout.write(`World ${instance.name} is ready (${instance.config})
+
+Services:
+${Object.values(instance.services).map((service) => `  ${service.id}: ${service.url ?? '(no listener — a World output)'}`).join('\n')}
+
+This instance started CLEAN (a world's state lives only while it runs; the world dir is the
+reproducible story) — set the clock and run your seed now, after every up.
+
+The two moves: if the twin stores it, create it through the vendor's own API (seed as the
+person, move the clock first for history). Everything else — judgment, lookups, faults — is
+a handler in the world dir's handlers/<vendor>.json. EVERY twin explains itself at
+GET <url>/twin; a scripted twin's GET <url>/twin/scenario lists handlers + misses.
+
+Env:
+  ${instance.envFile}
+
+Instance:
+  ${instance.dirs.instance}/instance.json
+
+Stop:
+  volter-world down ${instance.name}
+
+For a bounded job, use volter-world run ... -- <command> to tear down automatically on exit.
+Persistent up does not expire or infer that your sessions are idle.
+`);
+}

package/src/websocket-relay.ts

@@ -1,4 +1,4 @@
-import type { ServeHttpOptions } from '@volter/world-core';
+import type { ServeHttpOptions } from '@volter/world-core/runtime';
 
 /** A message relay for the World's TLS fronts. Transport state is connection-local. */
 export function websocketRelay(targetFor: (request: Request) => string | undefined): NonNullable<ServeHttpOptions['upgrade']> {

package/src/world-origins.ts

@@ -31,7 +31,7 @@ export function worldDoorUnderConsole(path: string, served: (name: string) => bo
   return Boolean(m && served(`${m[1]}/${m[2]}`));
 }
 
-/** Whether a path on a World's origin belongs to that World (its wire, its doors, its mirrors) or to
+/** Whether a path on a World's origin belongs to that World (its wire, its doors, its vendors' screens) or to
  *  what every origin carries (`/-/ping`, the console): a World's origin serves no other World. */
 export function pathOfWorld(path: string, served: string, consoleBase: string): boolean {
   return path === '/-/ping' || path === consoleBase || path.startsWith(`${consoleBase}/`) || path.startsWith(`/${served}/`) || path.startsWith(`/-/${served}/`) || path === `/${served}` || path === `/-/${served}`;

package/src/world-view.ts

@@ -1,11 +1,11 @@
-// THE LOCAL VIEW: one World served for a person to step into — its doors, its mirrors, its branches
+// THE LOCAL VIEW: one World served for a person to step into — its doors, its vendors' screens, its branches
 // ("as of" views) and the console, on one origin (docs/contributing/architecture.md, "Viewing a
 // World"). `volter world view` is this; the runtime's `up` gains no step. A host that serves many
 // Worlds (world-host) answers the same doors; this serves one, and the branches made of it.
 import { existsSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { loadWorldConfig } from './configs.ts';
 import { join, resolve } from 'node:path';
-import { serveHttp, stateDirName } from '@volter/world-core';
+import { serveHttp, stateDirName } from '@volter/world-core/runtime';
 import { LocalBranches } from './local-branches.ts';
 import { mountWorld, type MountedWorld } from './served-world.ts';
 import { localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from './world-origins.ts';
@@ -28,7 +28,7 @@ function branchRoots(dir: string): string[] {
   return out.sort();
 }
 
-export async function serveWorldView(name: string, opts: { /** the person signed in on this machine (`volter login`): this World's own page acts as them */ localPerson?: string; root?: string; port?: number; host?: string; console?: ViewConsole; announce?: (line: string) => void; /** each World a browser steps into at an origin of its own (on by default on loopback) */ origins?: boolean; /** the World's own origin as a browser reaches it through a proxy on this machine (a desktop serving it as an app):
+export async function serveWorldView(name: string, opts: { /** the person signed in on this machine (`volter login`): this World's own page acts as them */ localPerson?: string; root?: string; port?: number; host?: string; console?: ViewConsole; announce?: (line: string) => void; /** each World a browser steps into at an origin of its own (on by default on loopback) */ origins?: boolean; /** the World's own origin as a browser reaches it through a proxy on this machine (an app that serves it as one of its own pages):
    *  a request the proxy forwards from that host (X-Forwarded-Host) is answered as at that origin, its local session included */ origin?: string } = {}): Promise<WorldView> {
   const root = resolve(opts.root ?? process.cwd());
   const host = opts.host ?? '127.0.0.1';