@volter/world-runtime 2.0.55 → 3.0.0

package/dist/src/schema.d.ts

@@ -65,6 +65,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 declare 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 declare 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 declare const APP_URL_ENV = "$app-url";
 export type WorldShareProvider = 'cloudflare-quick' | 'command';
 /**
  * EXTERNAL (self-managed) service type.
@@ -103,6 +110,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;
@@ -159,6 +169,14 @@ 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).
@@ -191,11 +209,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.
@@ -337,6 +350,11 @@ 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;
@@ -454,6 +472,10 @@ export type WorldInstance = {
         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[];
 };
 export declare const DEFAULT_WORLD_SELECTION: WorldSelection;
 export declare const LEGACY_WORLD_SELECTION: WorldSelection;

package/dist/src/schema.js

@@ -3,6 +3,13 @@ export const WORLD_SCHEMA_VERSION = 2;
 export const WORLD_USAGES = ['application', 'dependencies', 'build', 'deployment'];
 /** 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';
 function assertStringArray(value, what, path) {
     if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== 'string')) {
         throw new Error(`${what} must be a non-empty string array in ${path}`);
@@ -74,10 +81,13 @@ function assertExternalServiceConfig(service, 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', 'source', 'jsonPath', 'pattern'], `External service "${id}" discover entry`, path);
+            assertKeys(mapping, ['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) {
@@ -360,7 +370,7 @@ export function assertWorldSelection(value, path) {
 function serviceV2ToLegacy(value, path) {
     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;
@@ -381,13 +391,6 @@ function serviceV2ToLegacy(value, path) {
         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')
@@ -412,7 +415,7 @@ function serviceV2ToLegacy(value, 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;
@@ -446,7 +449,6 @@ function serviceV2ToLegacy(value, path) {
         ...(bindings.injectEnvTemplates === undefined ? {} : { injectEnvTemplates: bindings.injectEnvTemplates }),
         ...(bindings.cliRedirect === undefined ? {} : { cliRedirect: bindings.cliRedirect }),
         ...(value.root === undefined ? {} : { root: value.root }),
-        ...(value.signIn === undefined ? {} : { signIn: { as: value.signIn.as } }),
         ...(external === undefined ? {} : { external }),
     };
     if (type !== 'external' && bindings.discover !== undefined)
@@ -584,7 +586,6 @@ function serviceToV2(service) {
         ...(Object.keys(endpoint).length ? { endpoint } : {}),
         ...(Object.keys(bindings).length ? { bindings } : {}),
         ...(service.root === undefined ? {} : { root: service.root }),
-        ...(service.signIn === undefined ? {} : { signIn: service.signIn }),
     };
 }
 /** Serialize normalized intent as the committed format-2 manifest. */

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

@@ -1,7 +1,7 @@
-import { type HistoryReference } from '@volter/world-core';
-import { type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core';
+import { type HistoryReference } from '@volter/world-core/runtime';
+import { type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core/runtime';
 import { type TrustedIssuer } from '@volter/world-access';
-import { type Changeset, type Receipt } from '@volter/world-core';
+import { type Changeset, type Receipt } from '@volter/world-core/runtime';
 import { rootForControlRoot } from './root.js';
 import { type WorldInstance } from './schema.js';
 export declare const TOKEN_HEADER = "x-volter-token";
@@ -101,7 +101,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, {
@@ -111,22 +111,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
@@ -267,7 +251,7 @@ export declare class WorldDoors {
     private 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. */
@@ -308,18 +292,10 @@ export declare class WorldDoors {
     private controlRoot;
     private stateOf;
     handle(request: Request): Promise<Response>;
-    /** 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 mirror;
-    /** 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;
-    private readonly signInAt;
-    private signedIn;
+    /** 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;
+    private screensOf;
     /** Whether a twin enforces a read-scope request itself (its manifest names `requestScopes: ['read']`):
      *  only then may the read token reach it with anything but GET or HEAD. Asked once per twin. */
     private readonly readEnforced;
@@ -342,7 +318,7 @@ export declare class WorldDoors {
     /** The world's own doors under `/-/<org>/<world>/`. */
     private door;
     /** 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
@@ -364,7 +340,7 @@ export declare class WorldDoors {
     private branchesDoor;
     /** The newest entry's instant across the World's twins (ms), or null when it has none. */
     private newestEntry;
-    /** 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 map;
     /** THE TIMELINE: the entries of every twin's log merged, newest first, by each entry's instant, then
      *  twin, then position. The World keeps no order across twins finer than its clock, and this claims

package/dist/src/served-world.js

@@ -1,4 +1,4 @@
-import { getActiveWorldStore, withAncestryLock, captureHistory, historyAtInstant, historyDigest, historyEntries, readHistoryView, worldPaths } from '@volter/world-core';
+import { getActiveWorldStore, withHistoryLocks, captureHistory, historyAtInstant, historyDigest, historyEntries, readHistoryView, worldPaths } 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,24 +19,25 @@ 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, readFileSync, writeFileSync, rmSync } from 'node:fs';
-import { CALLER_HEADER, newTraceparent, parseTraceparent, traceparentForDelivery, readTwinRequestJournalFrom, assertSafeChangesetName, blobDigest, destinationOf, openSealedAt, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, mirrorShellUnder, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, validateRemoteOrigin } from '@volter/world-core';
+import { CALLER_HEADER, callerForHeader, newTraceparent, parseTraceparent, traceparentForDelivery, readTwinRequestJournalFrom, assertSafeChangesetName, blobDigest, destinationOf, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, openSealedAt, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, validateRemoteOrigin } from '@volter/world-core/runtime';
 import { APP_READ_ENDPOINT_ENV } from "./init.js";
+import { packFacts } from "./pack-facts.js";
 import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass } 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, } from '@volter/world-core';
+import { appendActionIfAbsent, branchEntries, branchLogPath, branchMetaPath, changesetContentHash, changesetReadiness, confirmAction, parentLogPath, readTree, stateDirName, wholeLog, worldNow, parentEntries, readBranchMeta, rebaseBranch, } from '@volter/world-core/runtime';
 import { approveWorldChangeset, createWorldChangeset, diffWorld, findWorldChangeset, listWorldChangesets, pushWorldChangeset, verifyWorldChangeset, worldChangesetsDir } from "./changeset.js";
 import { fetchFromOrigin } from "./origin.js";
 import { CONSOLE_BASE, consoleRedirect, serveConsoleApart } from "./console-apart.js";
 import { loadWorldConfig, worldChangesetRules, writeWorldConfig } from "./configs.js";
-import { adaptersFor, credentialPath, packMirror, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, rewrapTwinCredentials, sealTwinCredential, sealedCredentialInfo, bindLegacyCredentials, setTwinRoot, spanMs } from "./root.js";
+import { adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, rewrapTwinCredentials, sealTwinCredential, sealedCredentialInfo, bindLegacyCredentials, setTwinRoot, spanMs } from "./root.js";
 import { clockFile, downWorld, listWorlds, statusWorld, upWorld } from "./runtime.js";
 import { assertChangesetRules } from "./schema.js";
 export const TOKEN_HEADER = 'x-volter-token';
@@ -131,15 +132,6 @@ export async function mountWorld(name, opts = {}) {
             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) => opts.browserOrigin(other) } : {}),
@@ -151,7 +143,9 @@ export async function mountWorld(name, opts = {}) {
             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' }); };
+            // 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' }); };
         },
     };
     const world = new WorldDoors(name, worldRoot, configRef, served, host, held('token') ?? mintToken('tok_'), held('token.read') ?? mintToken('tok_r_'));
@@ -239,37 +233,6 @@ export async function mountWorld(name, opts = {}) {
     }
     return mounted;
 }
-/** A local World's mirrors: each pack's builders, found once per process, and each client built once. */
-const localMirrors = new Map();
-const builtMirrorFiles = new Map();
-function localMirror(worldRoot, vendor) {
-    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, vendor, file) {
-    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, opts = {}) {
     const mounted = await mountWorld(name, opts);
@@ -362,7 +325,6 @@ export function worldOriginLabel(served) {
 /** 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 };
 /** A W3C traceparent's trace id, or null when the value is not one. */
@@ -399,7 +361,7 @@ export class WorldDoors {
     }
     /** 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, readToken) { this.token = token; this.readToken = readToken; this.endSessions(); this.keepKeys([]); this.signIns.clear(); }
+    retoken(token, readToken) { 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
      *  keeps them; each lasts 30 days from its opening. */
@@ -635,7 +597,7 @@ export class WorldDoors {
     scope(request) { 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. */
@@ -807,15 +769,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 });
@@ -824,71 +792,26 @@ export class WorldDoors {
             return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 500 });
         }
     }
-    /** 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. */
-    async mirror(request, url, vendor, rest, /** answered at the twin's place (the vendor's site) */ atSite = false) {
-        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. */
-    signIns = new Map();
-    signInAt = new Map();
-    signedIn(vendor, as, origin) {
-        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. */
+    workspaces = new Map();
+    async screensOf(vendor) {
+        const known = this.workspaces.get(vendor);
+        if (known !== undefined && Date.now() - known.at < 60_000)
+            return known.screens;
+        let screens = [];
+        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()).screens : undefined;
+            if (Array.isArray(listed))
+                screens = listed.filter((x) => 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']`):
      *  only then may the read token reach it with anything but GET or HEAD. Asked once per twin. */
@@ -951,7 +874,7 @@ export class WorldDoors {
         headers.delete(CALLER_HEADER);
         const who = this.callerOf(request);
         if (who)
-            headers.set(CALLER_HEADER, 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
@@ -972,19 +895,6 @@ export class WorldDoors {
         // 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);
@@ -998,7 +908,8 @@ export class WorldDoors {
         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))) {
@@ -1177,7 +1088,7 @@ export class WorldDoors {
             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);
@@ -1204,7 +1115,8 @@ export class WorldDoors {
             if (Number.isNaN(Date.parse(instant)))
                 return Response.json({ error: 'history?at=<ISO-8601 instant>' }, { status: 400 });
             const views = {};
-            withAncestryLock(() => { for (const vendor of Object.keys(this.up().services))
+            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 });
         }
@@ -1606,7 +1518,7 @@ export class WorldDoors {
                     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);
@@ -1618,7 +1530,7 @@ export class WorldDoors {
         return Response.json({ error: `no such door: ${request.method} /-/${this.served}/${path}` }, { status: 404 });
     }
     /** 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
@@ -1821,7 +1733,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. */
     async map() {
         const twins = [];
         for (const vendor of Object.keys(this.up().services)) {
@@ -1835,7 +1747,7 @@ export class WorldDoors {
                     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 })),
             });
@@ -1987,7 +1899,8 @@ export async function landChangeset(name, worldRoot, instance, changeset, expect
         byTwin.set(item.service, [...(byTwin.get(item.service) ?? []), item.action]);
     }
     const landedByTwin = new Map();
-    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}`);

package/dist/src/tail.js

@@ -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.js";
 /** Every action ledger a world service currently owns. One world service can record actions
  * under one or more STATE services (see runtime.ts `worldServiceStateService`), so this returns

package/dist/src/up-cli.d.ts

@@ -0,0 +1,3 @@
+import type { upWorld } from './runtime.js';
+export declare function upCommand(subject: string | undefined, rest: string[], root: string): Promise<void>;
+export declare function printReady(instance: Awaited<ReturnType<typeof upWorld>>): void;