@volter/world-runtime 2.0.0 → 2.0.2

package/dist/known-external-services.json

@@ -373,10 +373,6 @@
       "disposition": "demanded",
       "reason": "vendor google-play (Play Developer API), ×1 — ladder classification 2026-09-02"
     },
-    "@googleapis/calendar": {
-      "disposition": "demanded",
-      "reason": "vendor google-calendar, ×1 (plus the GOOGLE_CALENDAR_API_KEY stem, ×1) — ladder classification 2026-09-02"
-    },
     "@googleapis/sheets": {
       "disposition": "demanded",
       "reason": "vendor google-sheets, ×1 — ladder classification 2026-09-02"
@@ -863,10 +859,6 @@
       "disposition": "demanded",
       "reason": "vendor ghost (VITE_PUBLIC_GHOST_CONTENT_API_KEY — the browser-side Content API key), ×1 — ladder classification 2026-09-02"
     },
-    "googlecalendar": {
-      "disposition": "demanded",
-      "reason": "vendor google-calendar (GOOGLE_CALENDAR_API_KEY; the @googleapis/calendar client is the same demand), ×1 — ladder classification 2026-09-02"
-    },
     "googlecloud": {
       "disposition": "demanded",
       "reason": "vendor googlecloud (GOOGLE_CLOUD_API_KEY; the roster's one consumer spends it on the Web Fonts Developer API at www.googleapis.com/webfonts/v1, so the stem is a Google Cloud API key rather than a googleoauth credential), ×1 — ladder classification 2026-09-02"

package/dist/src/app-url.js

@@ -142,7 +142,7 @@ export function addAppHosts(name, hosts, options = {}) {
 }
 /** The listening TCP ports of a live pid, via lsof (macOS + Linux). */
 function listeningTcpPorts(pid) {
-    const result = spawnSync('lsof', ['-a', '-p', String(pid), '-iTCP', '-sTCP:LISTEN', '-P', '-n', '-Fn'], { encoding: 'utf8' });
+    const result = spawnSync('lsof', ['-a', '-p', String(pid), '-iTCP', '-sTCP:LISTEN', '-P', '-n', '-Fn'], { windowsHide: true, encoding: 'utf8' });
     if (result.error) {
         throw new Error(`volter-world app-url: \`lsof\` is unavailable (${result.error.message}) — pass the port, or --set the URL directly`);
     }

package/dist/src/branch.js

@@ -2,12 +2,17 @@
 // log of changes, and a world is a branch with compute attached (docs/concepts/the-model.md).
 // `branch <world> <name>` boots a new world from the base's config and forks every twin's mirror
 // into it (core's `forkTwin`: a POINTER to the base at its current position — the base's whole
-// history, its own entries included, is the branch's parent; nothing is copied). `checkout <name>`
+// history, its own entries included, is the branch's parent; nothing is copied). A managed database (containerless
+// Postgres) keeps no history, so it is the one thing copied: the stopped base's data, as of now. Two branches of one
+// base running at once share the database port its definition names; run one at a time (the SDK does). `checkout <name>`
 // brings a stopped world back up from its own instance record, state intact.
-import { existsSync, readdirSync } from 'node:fs';
+import { cpSync, existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { captureHistory, historyAtInstant, forkTwin, stateGeneration, withAncestryLock, worldPaths, worldStateRoot } from '@volter/world-core';
 import { downWorld, saveWorldInstance, statusWorld, upWorld } from "./runtime.js";
+import { parseInfraDefinition, pgliteDown, pgliteUp } from "./pglite-backing.js";
+import { redisTwinCli, redisTwinDown, redisTwinUp } from "./redis-backing.js";
 function stateServices(controlRoot) {
     const stateRoot = worldStateRoot(controlRoot);
     if (!existsSync(stateRoot))
@@ -35,6 +40,12 @@ export async function branchWorld(base, name, options = {}) {
                 return { state, view, position, generation: stateGeneration(worldPaths(state, fromRoot).dir) };
             }) };
     }));
+    // the base's managed databases (checked before the branch boots: its database would share the base's port)
+    const databases = managedDatabases(from);
+    if (databases.length && (options.at?.instant || options.at?.positions || options.at?.views)) {
+        throw new Error(`volter-world branch: ${base} has a managed database, which keeps no history to branch from at an instant or position; branch from its current state`);
+    }
+    refuseLiveDatabases(from, databases);
     const instance = await upWorld(existsSync(from.configPath) ? from.configPath : from.config, { name, root, mode: from.mode, envFile });
     const forked = {};
     try {
@@ -50,6 +61,7 @@ export async function branchWorld(base, name, options = {}) {
             if (states.length)
                 forked[service] = states.map(s => s.state);
         }
+        await branchManagedDatabases(from, instance, databases);
     }
     catch (error) {
         await downWorld(name, root, { purge: true, expectedCreatedAt: instance.createdAt });
@@ -57,6 +69,71 @@ export async function branchWorld(base, name, options = {}) {
     }
     return { instance, forked };
 }
+/** The base's containerless managed databases: each PGlite `pglite-<kind>-data` and the MongoDB twin's
+ *  `twin-mongodb-data` (pglite-backing.ts), and the redis twin's `redis-twin` tree (redis-backing.ts). A stopped World's
+ *  hosts leave no pid file; a docker-backed World keeps its data under the container's volume, which a branch does not
+ *  carry. */
+function managedDatabases(from) {
+    const data = from.dirs.data;
+    if (!existsSync(data))
+        return [];
+    return readdirSync(data).filter((n) => /^pglite-[a-z0-9_-]+-data$/.test(n) || n === 'twin-mongodb-data' || n === 'redis-twin');
+}
+/** The pid files of the hosts serving one managed database directory. */
+function hostPidFiles(data, db) {
+    if (db === 'redis-twin')
+        return readdirSync(data).filter((n) => /^redis-twin-\d+\.pid$/.test(n)).map((n) => join(data, n));
+    return [join(data, `${db.slice(0, -'-data'.length)}.pid`)];
+}
+/** A copy of a live database directory is not a consistent one, and the branch's database would answer on the base's
+ *  port: the base must be stopped first (`volter world branch` stops it, as a branch replaces its base). */
+function refuseLiveDatabases(from, dbs) {
+    for (const db of dbs) {
+        for (const pidFile of hostPidFiles(from.dirs.data, db)) {
+            const pid = existsSync(pidFile) ? Number(readFileSync(pidFile, 'utf8').trim()) : NaN;
+            let live = false;
+            if (Number.isInteger(pid) && pid > 0) {
+                try {
+                    process.kill(pid, 0);
+                    live = true;
+                }
+                catch {
+                    live = false;
+                }
+            }
+            if (live)
+                throw new Error(`volter-world branch: ${from.name}'s managed ${db} is running (pid ${pid}); stop ${from.name} first so its database can be copied into the branch consistently`);
+        }
+    }
+}
+/** The branch's managed databases as the base holds them: the branch's own, just booted empty by `up`, are stopped,
+ *  replaced by a copy of the base's data, and started again, so a branch of a migrated and seeded World serves that
+ *  data, as its twins serve the base's history. */
+async function branchManagedDatabases(from, instance, dbs) {
+    if (!dbs.length)
+        return;
+    const definition = join(dirname(instance.configPath), 'world.infrastructure.yml');
+    if (!existsSync(definition))
+        return;
+    const services = parseInfraDefinition(readFileSync(definition, 'utf8'));
+    const redis = services.filter((s) => s.kind === 'redis');
+    const hosted = services.filter((s) => s.kind !== 'redis');
+    const redisCli = dbs.includes('redis-twin') && redis.length ? redisTwinCli([dirname(fileURLToPath(import.meta.url)), dirname(instance.configPath)]) : undefined;
+    await pgliteDown(hosted, instance.dirs.data);
+    if (redisCli)
+        await redisTwinDown(redis, instance.dirs.data);
+    for (const db of dbs) {
+        if (db === 'redis-twin' && !redisCli)
+            continue;
+        const to = join(instance.dirs.data, db);
+        rmSync(to, { recursive: true, force: true });
+        cpSync(join(from.dirs.data, db), to, { recursive: true });
+    }
+    if (dbs.some((db) => db !== 'redis-twin'))
+        await pgliteUp(hosted, instance.dirs.data);
+    if (redisCli)
+        await redisTwinUp(redis, instance.dirs.data, redisCli);
+}
 /** A stopped world back up, from its own record. */
 export async function checkoutWorld(name, options = {}) {
     const root = resolve(options.root ?? process.cwd());

package/dist/src/catalog.js

@@ -110,7 +110,7 @@ export function checkoutCatalog(root) {
         packDir: (vendor) => (isPackDir(join(packsDir, vendor)) ? join(packsDir, vendor) : undefined),
         version: (vendor) => packageVersion(join(packsDir, vendor)),
         sha: () => {
-            const proc = spawnSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
+            const proc = spawnSync('git', ['-C', root, 'rev-parse', 'HEAD'], { windowsHide: true, encoding: 'utf8' });
             const sha = proc.status === 0 ? proc.stdout.trim() : '';
             return /^[0-9a-f]{40}$/.test(sha) ? sha : 'unknown';
         },

package/dist/src/cli.js

@@ -2,7 +2,7 @@
 import { sessionTrustEnv } from "./ca-trust.js";
 import { spawn, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from "./index.js";
@@ -568,21 +568,44 @@ async function main() {
         return;
     }
     if (cmd === 'clock') {
-        // THE operator door for world time (physics): show / set <iso> / advance <duration>.
-        // The clock is a frozen instant every twin reads per request (kernel worldNow()); setting
-        // or advancing takes effect live, no restarts. `advance` requires a set clock (advancing
-        // wall-clock would silently freeze time as a side effect).
+        // THE operator door for world time (physics): show / set <iso> / advance <duration> / shift <duration> / clear.
+        // The clock every twin reads per request (kernel worldNow()), and every application process through the injector
+        // (inject.cjs, WORLD TIME); a change takes effect live, no restarts. Its two forms (world-clock.cjs): `set` freezes
+        // time at an instant (scripted time: a life, a seed); `shift` moves a World forward while its time keeps running (a
+        // World serving an application, whose time a frozen instant would stop); `advance` moves either form; `clear`
+        // returns the World to the machine's time. `advance` refuses a World on the machine's time, which it would freeze.
         // argv shape here: cmd='clock', subject=<world>, rest=[action, value?, flags...]
+        const clockForm = createRequire(import.meta.url)('@volter/world-core/world-clock');
         const name = subject;
         const [action, value] = rest;
-        if (!name || !action || (action !== 'show' && action !== 'set' && action !== 'advance')) {
-            console.error('usage: volter-world clock <world> show | set <iso-8601> | advance <N s|m|h|d> [--root <repo>]');
+        if (!name || !action || !['show', 'set', 'advance', 'shift', 'clear'].includes(action)) {
+            console.error('usage: volter-world clock <world> show | set <iso-8601> | advance <N s|m|h|d> | shift <N s|m|h|d> | clear [--root <repo>]');
             process.exit(2);
         }
         const rootDir = resolve(optionValue(rest, '--root') ?? process.cwd());
         const file = clockFile(rootDir, name);
+        const current = existsSync(file) ? clockForm.parseClock(readFileSync(file, 'utf8')) : null;
+        const write = (clock) => {
+            mkdirSync(dirname(file), { recursive: true });
+            writeFileSync(file, `${clockForm.formatClock(clock)}\n`);
+            // the World's time now, bare, as scripts read it (`show` says which form)
+            console.log(new Date(clockForm.clockNowMs(clock, Date.now())).toISOString());
+        };
         if (action === 'show') {
-            console.log(existsSync(file) ? `${readFileSync(file, 'utf8').trim()} (frozen)` : `${new Date().toISOString()} (wall clock — no world clock set)`);
+            if (!current)
+                console.log(`${new Date().toISOString()} (wall clock — no world clock set)`);
+            else if (current.kind === 'frozen')
+                console.log(`${new Date(current.at).toISOString()} (frozen)`);
+            else {
+                const ahead = current.at - current.since;
+                console.log(`${new Date(clockForm.clockNowMs(current, Date.now())).toISOString()} (running, ${ahead >= 0 ? '+' : '-'}${Math.abs(ahead) / 1000}s from the machine's time)`);
+            }
+            return;
+        }
+        if (action === 'clear') {
+            if (existsSync(file))
+                rmSync(file);
+            console.log(`${new Date().toISOString()} (wall clock — no world clock set)`);
             return;
         }
         if (action === 'set') {
@@ -591,25 +614,30 @@ async function main() {
                 console.error(`clock set: ${JSON.stringify(value)} is not an ISO-8601 instant`);
                 process.exit(2);
             }
-            mkdirSync(dirname(file), { recursive: true });
-            writeFileSync(file, `${new Date(parsed).toISOString()}\n`);
-            console.log(new Date(parsed).toISOString());
+            write({ kind: 'frozen', at: parsed });
             return;
         }
         const m = /^(\d+(?:\.\d+)?)(s|m|h|d)$/.exec((value ?? '').trim());
         if (!m) {
-            console.error(`clock advance: ${JSON.stringify(value)} is not <N>(s|m|h|d)`);
+            console.error(`clock ${action}: ${JSON.stringify(value)} is not <N>(s|m|h|d)`);
             process.exit(2);
         }
-        if (!existsSync(file)) {
-            console.error('clock advance: no world clock is set (advance from wall-clock would freeze time as a side effect) — `clock set <iso>` first');
+        const by = Number(m[1]) * { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+        if (action === 'advance') {
+            if (!current) {
+                console.error('clock advance: no world clock is set (advance from wall-clock would freeze time as a side effect) — `clock set <iso>` first, or `clock shift` to move a running World');
+                process.exit(2);
+            }
+            write({ ...current, at: current.at + by });
+            return;
+        }
+        // shift: a World on the machine's time, or already running, moves forward and keeps running
+        if (current?.kind === 'frozen') {
+            console.error('clock shift: this World\'s clock is frozen — `clock advance` moves it, or `clock clear` first');
             process.exit(2);
         }
-        const base = Date.parse(readFileSync(file, 'utf8').trim());
-        const unit = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
-        const next = new Date(base + Number(m[1]) * unit).toISOString();
-        writeFileSync(file, `${next}\n`);
-        console.log(next);
+        const wall = Date.now();
+        write(current ? { ...current, at: current.at + by } : { kind: 'running', at: wall + by, since: wall });
         return;
     }
     if (cmd === 'urls') {
@@ -953,7 +981,7 @@ async function main() {
             // VOLTER_WORLD names the World to the injector: a request addressed to its paths carries its key
             const commandEnv = { ...process.env, ...env, ...bridged.env, VOLTER_WORLD: resolved.ref };
             commandEnv.VOLTER_TWIN_INJECT_QUIET = head.includes('--verbose') ? '0' : commandEnv.VOLTER_TWIN_INJECT_QUIET ?? '1';
-            const child = spawn(command[0], command.slice(1), { env: commandEnv, stdio: 'inherit' });
+            const child = spawn(command[0], command.slice(1), { windowsHide: true, env: commandEnv, stdio: 'inherit' });
             const code = await new Promise((resolveExit) => { child.on('exit', (status) => resolveExit(status ?? 1)); child.on('error', () => resolveExit(127)); });
             // a client that wrote and exited at once still has bytes on their way through a bridge
             await drainStreams();
@@ -979,7 +1007,7 @@ async function main() {
             const compose = splitDockerComposeArgs(command);
             if (compose) {
                 // the consumer's own service names, from its own files, through its own docker
-                const listed = spawnSync(compose.head[0], [...compose.head.slice(1), ...compose.composeFlags, 'config', '--services'], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+                const listed = spawnSync(compose.head[0], [...compose.head.slice(1), ...compose.composeFlags, 'config', '--services'], { windowsHide: true, env, stdio: ['ignore', 'pipe', 'pipe'] });
                 if (listed.status !== 0)
                     throw new Error(`volter-world attach --via reflect: docker compose config --services failed:\n${listed.stderr.toString().trim()}`);
                 const services = listed.stdout.toString().split('\n').map((s) => s.trim()).filter(Boolean);
@@ -988,7 +1016,7 @@ async function main() {
                 toRun = dockerComposeWithOverride(command, overridePath);
                 process.stderr.write(`volter-world attach --via reflect: ${services.length} service(s) attached — dns ${manifest.resolverIp}:53, front ${manifest.targetIp}:443, CA ${ATTACHED_CA_PATH}\n`);
             }
-            const result = spawnSync(toRun[0], toRun.slice(1), { env, stdio: 'inherit' });
+            const result = spawnSync(toRun[0], toRun.slice(1), { windowsHide: true, env, stdio: 'inherit' });
             process.exit(result.status ?? 1);
         }
         if (via !== 'env') {

package/dist/src/console-apart.d.ts

@@ -4,6 +4,7 @@ export type ConsoleMount = {
     handle: (request: Request, base: string, opts?: {
         worlds?: string;
         names?: string[];
+        worldOrigin?: boolean;
     }) => Promise<Response | null>;
 };
 export declare const CONSOLE_BASE = "/-/console";

package/dist/src/console-apart.js

@@ -67,6 +67,9 @@ export async function serveConsoleFor(target, opts = {}) {
         throw error;
     }
     const hostname = opts.hostname ?? '127.0.0.1';
+    // the console's own origin, once it listens: a World that lets only its own origin frame its pages lets this
+    // console frame them too, as they are framed where it serves them itself
+    let consoleOrigin = '';
     const worldsServer = await serveHttp({
         hostname, port: opts.port !== undefined && opts.port !== 0 ? opts.port + 1 : 0, twinRequestJournal: false,
         async fetch(request) {
@@ -87,11 +90,15 @@ export async function serveConsoleFor(target, opts = {}) {
             const location = out.get('location');
             if (location?.startsWith(origin))
                 out.set('location', `${url.origin}${location.slice(origin.length)}`);
+            const csp = out.get('content-security-policy');
+            if (csp && consoleOrigin)
+                out.set('content-security-policy', csp.replace(/frame-ancestors ([^;]*)/, (_all, allowed) => (/'none'/.test(allowed) ? `frame-ancestors ${allowed}` : `frame-ancestors ${allowed} ${consoleOrigin}`)));
             return new Response(answer.body, { status: answer.status, headers: out });
         },
     });
     const worlds = `http://${hostname}:${worldsServer.port}`;
     const consoleServer = await serveConsoleApart(mount, { upstream: origin, worlds, names, hostname, ...(opts.port !== undefined ? { port: opts.port } : {}) });
+    consoleOrigin = new URL(consoleServer.url).origin;
     return { url: consoleServer.url, worlds, servers: [consoleServer.server, worldsServer] };
 }
 /** The host's old console address (`/-/console/…`, a bookmark or a portal's link) sent on to the console's

package/dist/src/covers.js

@@ -450,8 +450,10 @@ function usesOf(signals) {
 export function detectRepoVendors(repoPath) {
     const repo = resolve(repoPath);
     // the platform's own packages — the twins an app installed, the command, the runtime — are
-    // never a vendor signal: an app that installed @volter/twin-slack did not gain a Slack dependency
-    const dependencies = projectDependencies(repo).filter((dep) => !dep.startsWith('@volter/') && !dep.startsWith('pypi:volter'));
+    // never a vendor signal: an app that installed @volter/twin-slack did not gain a Slack dependency.
+    // A Volter package a pack names as its vendor's SDK is one (`@volter/identity`, the Volter identity
+    // service's client, is the volteridentity twin's), as any vendor's SDK is.
+    const dependencies = projectDependencies(repo).filter((dep) => Object.hasOwn(SDK_TWINS, dep) || (!dep.startsWith('@volter/') && !dep.startsWith('pypi:volter')));
     const envNames = projectEnvNames(repo);
     const npmRegistries = projectNpmRegistries(repo);
     // vendor → detection sources

package/dist/src/fixture-env.d.ts

@@ -39,4 +39,7 @@ export declare function isGoogleOAuthClientEnvName(name: string): boolean;
  *  come from fakeGoogleServiceAccountJson instead), and NOT the OAuth-client names above —
  *  those need the `{"web":{...}}` shape, not SA JSON. */
 export declare function isGoogleServiceAccountEnvName(name: string): boolean;
+/** Whether `name` is a key an application parses (APP_KEY_SHAPES): a secret init fakes in its shape, whatever the
+ *  example leaves it (LibreChat's CREDS_IV is empty in its example and not credential-shaped by name). */
+export declare function isAppKeyName(name: string): boolean;
 export declare function fakeEnvValue(name: string): string;

package/dist/src/fixture-env.js

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

package/dist/src/host-worker.js

@@ -1,18 +1,11 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
 // Worker entry for 'worker' isolation: one Worker thread per twin. It owns its event
 // loop + heap, so a CPU hog / leak / hard crash here is contained to this thread — the
 // host does NOT restart it: it gives up on the worker (fires a `gaveup` event → doctor
 // red) without disturbing sibling twins. Posts {type:'ready'} once listening.
 import { parentPort, workerData } from 'node:worker_threads';
+import { importModule } from "./import-module.js";
 const spec = workerData;
-const mod = (await import(__rewriteRelativeImportExtension(spec.module)));
+const mod = await importModule(spec.module);
 const factory = mod[spec.export];
 if (typeof factory !== 'function') {
     throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);

package/dist/src/host.js

@@ -1,11 +1,3 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
 // Co-located twin host — run many twins in ONE process instead of one OS process
 // per twin. The twin core is a pure, transport-agnostic handler (see a pack's
 // `handle<Vendor>TwinRequest`), so nothing requires a process per twin; this host
@@ -29,9 +21,10 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // world config that drives it) stays vendor-agnostic — exactly like `bin` spawning.
 import { Worker } from 'node:worker_threads';
 import { siblingScript } from "./sibling.js";
+import { importModule } from "./import-module.js";
 import { pathToFileURL } from 'node:url';
 async function loadFactory(spec) {
-    const mod = (await import(__rewriteRelativeImportExtension(spec.module)));
+    const mod = await importModule(spec.module);
     const factory = mod[spec.export];
     if (typeof factory !== 'function') {
         throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);

package/dist/src/import-module.d.ts

@@ -0,0 +1 @@
+export declare function importModule<T = Record<string, unknown>>(specifier: string): Promise<T>;

package/dist/src/import-module.js

@@ -0,0 +1,16 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// import() of what a World names a module by: a package name, a file URL, or a file path. Node's ESM loader takes an
+// absolute path only as a file:// URL — on Windows `C:\…` reads as a URL with the scheme `c:` and is refused
+// (ERR_UNSUPPORTED_ESM_URL_SCHEME); Bun takes either. A path becomes its file URL here; anything else is passed on.
+import { isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+export function importModule(specifier) {
+    return import(__rewriteRelativeImportExtension(isAbsolute(specifier) ? pathToFileURL(specifier).href : specifier));
+}

package/dist/src/index.d.ts

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

package/dist/src/index.js

@@ -30,6 +30,9 @@ export { resetWorld, seedEntryFor, seedWorld } from "./placeholder.js";
 export { fetchFromOrigin, worldOrigin } from "./origin.js";
 export { branchWorld, checkoutWorld } from "./branch.js";
 export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from "./root.js";
-export { landReceipts, mountWorld, readServeRecord, refreshSchedule, servedName, serveWorld, TOKEN_HEADER, WorldDoors } from "./served-world.js";
+export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from "./served-world.js";
+export { LocalBranches } from "./local-branches.js";
+export { serveWorldView, VIEW_CONSOLE_BASE } from "./world-view.js";
+export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor } from "./console-apart.js";
 export { assertWorldStateRemovable } from "./ancestry.js";