@volter/world-runtime 2.0.0 → 2.0.1

package/dist/src/redis-backing.js

@@ -0,0 +1,120 @@
+// The containerless backing for a World's managed REDIS: the redis twin (@volter/twin-redis) serving Redis's
+// own protocol on the loopback port the definition declares, its keys held in the World's tree under
+// VOLTER_WORLD_DATA. Chosen by `volter-world-infra` for every redis service unless the operator forces the
+// container backing (VOLTER_WORLD_INFRA_BACKING=docker); the definition, the injected REDIS_URL and the declared
+// service contract are the same either way, as the boundary comment in infra-cli.ts promises.
+//
+// Why the twin and not a container: a World's state branches, checkpoints and rolls back as one tree, and a Redis
+// in a container is state outside it (a branch of the World would share the container's queue and cache). The
+// twin keeps each key a subject of the World (packages/twin/redis/src/redis-storage.ts). It needs nothing
+// installed: no container runtime, no redis-server binary.
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { findInstalledPackage, packCli } from "./catalog.js";
+const PACKAGE = '@volter/twin-redis';
+const READY_TIMEOUT_MS = 60_000;
+/** The redis twin's cli: installed beside this runtime (its node_modules walk), else beside the World's config. */
+export function redisTwinCli(from) {
+    for (const dir of from) {
+        const found = findInstalledPackage(dir, PACKAGE);
+        const cli = found === undefined ? undefined : packCli(found);
+        if (cli !== undefined && existsSync(cli))
+            return cli;
+    }
+    return undefined;
+}
+const pidPath = (dataDir, service) => join(dataDir, `redis-twin-${service.hostPort}.pid`);
+/** Where the service's keys live: the World's tree for the `redis` service, under the World's data. */
+export const redisTwinRoot = (dataDir) => join(dataDir, 'redis-twin');
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function listening(port) {
+    return new Promise((resolve) => {
+        const socket = connect({ host: '127.0.0.1', port, timeout: 1000 });
+        // a port that answers PING with PONG is this service; anything else is not ready (or not ours)
+        socket.once('connect', () => socket.write('PING\r\n'));
+        socket.once('data', (chunk) => { socket.destroy(); resolve(chunk.toString('latin1').startsWith('+PONG')); });
+        socket.on('error', () => resolve(false));
+        socket.on('timeout', () => { socket.destroy(); resolve(false); });
+    });
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function redisTwinUp(services, dataDir, cli) {
+    for (const service of services) {
+        const pidFile = pidPath(dataDir, service);
+        if (existsSync(pidFile) && alive(Number(readFileSync(pidFile, 'utf8').trim())) && await listening(service.hostPort))
+            continue;
+        // a port that already answers is another process's (another World's twin, a redis-server): serving there would
+        // hand this World's app someone else's keys, so it is refused, never taken as ready
+        if (await listening(service.hostPort))
+            throw new Error(`port ${service.hostPort} already serves Redis for another process`);
+        const root = redisTwinRoot(dataDir);
+        mkdirSync(root, { recursive: true });
+        const log = join(dataDir, `redis-twin-${service.hostPort}.log`);
+        mkdirSync(dirname(log), { recursive: true });
+        // a real fd, not a pipe: the server outlives this process untethered
+        const logFd = openSync(log, 'a');
+        // the runtime this runs on: Bun runs the pack's TypeScript as it is; Node (volter-world-infra's shebang) needs
+        // type transformation, not only stripping (the kernel declares constructor parameter properties)
+        const runtime = typeof globalThis.Bun !== 'undefined' || !cli.endsWith('.ts') ? [] : ['--experimental-transform-types', '--no-warnings'];
+        const child = spawn(process.execPath, [...runtime, cli, 'serve', '--port', String(service.hostPort), '--root', root], {
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+        });
+        child.unref();
+        closeSync(logFd);
+        writeFileSync(pidFile, `${child.pid}\n`);
+        const deadline = Date.now() + READY_TIMEOUT_MS;
+        while (!(await listening(service.hostPort)) || !alive(child.pid)) {
+            if (!alive(child.pid))
+                throw new Error(`redis exited before serving — see ${log}`);
+            if (Date.now() > deadline)
+                throw new Error(`redis did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
+            await sleep(200);
+        }
+    }
+}
+export async function redisTwinStatus(services, dataDir) {
+    let ready = 0;
+    for (const service of services) {
+        const pidFile = pidPath(dataDir, service);
+        if (!existsSync(pidFile))
+            continue;
+        if (alive(Number(readFileSync(pidFile, 'utf8').trim())) && await listening(service.hostPort))
+            ready += 1;
+    }
+    return ready;
+}
+export async function redisTwinDown(services, dataDir) {
+    for (const service of services) {
+        const pidFile = pidPath(dataDir, service);
+        if (!existsSync(pidFile))
+            continue;
+        const pid = Number(readFileSync(pidFile, 'utf8').trim());
+        if (alive(pid)) {
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch { /* already gone */ }
+            const deadline = Date.now() + 5000;
+            while (alive(pid) && Date.now() < deadline)
+                await sleep(100);
+            if (alive(pid)) {
+                try {
+                    process.kill(pid, 'SIGKILL');
+                }
+                catch { /* raced */ }
+            }
+        }
+        rmSync(pidFile, { force: true });
+    }
+}

package/dist/src/runtime.d.ts

@@ -122,6 +122,7 @@ export declare function pruneWorlds(options?: {
     entries: WorldCleanupEntry[];
 };
 export declare function parseCloudflareQuickPublicUrl(candidate: string): string | undefined;
+export declare function ownCommand(command: string[]): string[];
 export declare function shareWorld(name: string, options?: ShareWorldOptions): Promise<WorldInstance>;
 export declare function shareWorldServices(name: string, options?: ShareWorldServicesOptions): Promise<WorldInstance>;
 /** TWIN-62: `unshare` must give tunnels the same contract plain `downWorld` already gives owned

package/dist/src/runtime.js

@@ -17,7 +17,7 @@ import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { packFacts } from "./pack-facts.js";
 import { describeServiceEnd, readServiceEnd, serviceOutput } from "./service-exit.js";
 import { Socket } from 'node:net';
-import { getActiveWorldStore, withFileLock, stateDirName, PROTOCOL_VERSION, PROTOCOL_MAJOR, WORLD_BOOT_PATH, WORLD_ENV_NAMES_ENV } from '@volter/world-core';
+import { getActiveWorldStore, withFileLock, stateDirName, PROTOCOL_VERSION, PROTOCOL_MAJOR, WORLD_BOOT_PATH, WORLD_DATA_ENV, WORLD_ENV_NAMES_ENV } from '@volter/world-core';
 import { loadWorldConfig } from "./configs.js";
 import { createWorldNetworkPolicy, WORLD_NETWORK_POLICY_ENV } from '@volter/world-core/network-policy';
 import { resolveServicePackage } from "./catalog.js";
@@ -762,7 +762,7 @@ function getByJsonPath(value, jsonPath) {
     return current;
 }
 async function runExternalCommand(command, cwd, serviceId, phase, env = process.env, abort, timeoutMs = 60_000) {
-    const [bin, ...args] = command;
+    const [bin, ...args] = ownCommand(command);
     if (!bin)
         throw new Error(`External service "${serviceId}": ${phase} command is empty`);
     if (!commandExists(bin))
@@ -803,7 +803,7 @@ async function runExternalCommand(command, cwd, serviceId, phase, env = process.
  * (instead of buffering through spawnSync's 1MB cap, which a large DB restore would overflow). Returns
  * the combined output so `discover` can read it. Throws with a bounded tail on nonzero exit. */
 async function runExternalUp(command, cwd, serviceId, env, logPath, abort) {
-    const [bin, ...args] = command;
+    const [bin, ...args] = ownCommand(command);
     if (!bin)
         throw new Error(`External service "${serviceId}": up command is empty`);
     if (!commandExists(bin)) {
@@ -1453,7 +1453,8 @@ export async function upWorld(configId, options = {}, abort) {
             VOLTER_WORLD_MODE: mode,
             VOLTER_WORLD_CONFIG: loaded.path,
             VOLTER_WORLD_INSTANCE: instanceFile,
-            VOLTER_WORLD_DATA: data,
+            // every service's root is `<data>/<service id>`; the kernel finds another pack's store across them (A3, ownerStoreRoots)
+            [WORLD_DATA_ENV]: data,
             // the live env file this `up` writes: what a service that runs apps elsewhere (world-machine's guest) carries there
             VOLTER_WORLD_ENV_FILE: envFile,
             // THE WORLD CLOCK: every service stamps from this file via the kernel's worldNow();
@@ -2220,8 +2221,23 @@ function sleep(ms) {
 }
 function commandExists(command) {
     // Pass the live env so PATH reflects the current process (some runtimes snapshot env otherwise).
-    const result = spawnSync('which', [command], { stdio: 'ignore', env: process.env });
-    return result.status === 0;
+    return OWN_COMMANDS[command] !== undefined || onPath(command);
+}
+/** A lifecycle command naming this runtime's own bin (`volter-world-infra`, which `init` names in every managed
+ *  infrastructure's lifecycle) runs this runtime's own script with the executable running it, when nothing on PATH
+ *  answers the name: a bare `volter-world down` (no runner that put node_modules/.bin on PATH) failed "not found on
+ *  PATH" and left the infrastructure up. Only the name is mapped — no directory joins PATH — and a same-named
+ *  command on PATH still wins, as before. */
+const OWN_COMMANDS = { 'volter-world-infra': 'infra-cli' };
+export function ownCommand(command) {
+    const [bin, ...args] = command;
+    const stem = bin === undefined ? undefined : OWN_COMMANDS[bin];
+    if (stem === undefined || onPath(bin))
+        return command;
+    return [process.execPath, siblingScript(import.meta.url, stem), ...args];
+}
+function onPath(command) {
+    return spawnSync('which', [command], { stdio: 'ignore', env: process.env }).status === 0;
 }
 function resolveWithPublicDns(hostname) {
     const result = spawnSync('dig', ['+short', '@1.1.1.1', hostname, 'A'], {
@@ -2523,7 +2539,8 @@ async function probeExternalOnce(ready, cwd, env, logPath) {
         if (!commandExists(ready.command)) {
             return { ok: false, message: `readiness command \`${ready.command}\` not found on PATH` };
         }
-        const result = spawnSync(ready.command, ready.args ?? [], {
+        const [probeBin, ...probeArgs] = ownCommand([ready.command, ...(ready.args ?? [])]);
+        const result = spawnSync(probeBin, probeArgs, {
             cwd, encoding: 'utf8', env, timeout: DOCTOR_EXTERNAL_PROBE_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024,
         });
         if (result.status === 0)

package/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -59,6 +59,7 @@
   "devDependencies": {
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
+    "mongodb": "~6.20.0",
     "pg": "8.16.3",
     "typescript": "^5.9.0"
   },
@@ -66,12 +67,13 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.0",
-    "@volter/world-console": "2.0.0"
+    "@volter/world-core": "2.0.1",
+    "@volter/world-console": "2.0.1"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
-    "@volter/world-core": "2.0.0",
+    "@electric-sql/pglite-pgvector": "0.0.9",
+    "@volter/world-core": "2.0.1",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -79,5 +81,8 @@
     "@volter/world-console": {
       "optional": true
     }
+  },
+  "optionalDependencies": {
+    "@volter/twin-mongodb": "0.1.1"
   }
 }

package/src/branch.ts

@@ -2,13 +2,18 @@
 // 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.ts';
 import type { WorldInstance } from './schema.ts';
+import { parseInfraDefinition, pgliteDown, pgliteUp } from './pglite-backing.ts';
+import { redisTwinCli, redisTwinDown, redisTwinUp } from './redis-backing.ts';
 
 export type BranchOptions = { root?: string; envFile?: string; now?: Date; /** branch from a point in the base's history: an instant, or a position per twin (contract "Just like Neon", 3) */ at?: { instant?: string; positions?: Record<string, number>; views?: Record<string, string> } };
 
@@ -37,6 +42,12 @@ export async function branchWorld(base: string, name: string, options: BranchOpt
       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: Record<string, string[]> = {};
   try {
@@ -48,6 +59,7 @@ export async function branchWorld(base: string, name: string, options: BranchOpt
       }
       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 });
     throw error;
@@ -55,6 +67,58 @@ export async function branchWorld(base: string, name: string, options: BranchOpt
   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: WorldInstance): string[] {
+  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: string, db: string): string[] {
+  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: WorldInstance, dbs: string[]): void {
+  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: WorldInstance, instance: WorldInstance, dbs: string[]): Promise<void> {
+  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: string, options: { root?: string } = {}): Promise<WorldInstance> {
   const root = resolve(options.root ?? process.cwd());

package/src/cli.ts

@@ -2,7 +2,7 @@
 import { sessionTrustEnv } from './ca-trust.ts';
 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, resolve as resolvePath } 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, upWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from './index.ts';
@@ -518,39 +518,61 @@ async function main(): Promise<void> {
   }
 
   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') as typeof import('@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: Parameters<typeof clockForm.formatClock>[0]) => {
+      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') {
       const parsed = Date.parse(value ?? '');
       if (Number.isNaN(parsed)) { 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)`); 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'); 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] as 's' | 'm' | 'h' | 'd'];
-    const next = new Date(base + Number(m[1]) * unit).toISOString();
-    writeFileSync(file, `${next}\n`);
-    console.log(next);
+    if (!m) { console.error(`clock ${action}: ${JSON.stringify(value)} is not <N>(s|m|h|d)`); process.exit(2); }
+    const by = Number(m[1]) * { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2] as 's' | 'm' | 'h' | 'd'];
+    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 wall = Date.now();
+    write(current ? { ...current, at: current.at + by } : { kind: 'running', at: wall + by, since: wall });
     return;
   }
 

package/src/fixture-env.ts

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

package/src/infra-cli.ts

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