@volter/world-runtime 2.0.0 → 2.0.1

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/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/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') {

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/infra-cli.js

@@ -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.js";
 const phase = process.argv[2];
 if (phase !== 'up' && phase !== 'status' && phase !== 'down') {
@@ -44,8 +45,9 @@ const fail = (result) => {
 // 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() {
     const forced = process.env.VOLTER_WORLD_INFRA_BACKING;
@@ -69,7 +71,7 @@ function selectBacking() {
 }
 async function runPglite() {
     const { unsupportedKinds, pgliteUp, pgliteStatus, pgliteDown } = await import("./pglite-backing.js");
-    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);
@@ -80,7 +82,7 @@ async function runPglite() {
         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);
         }
@@ -97,18 +99,65 @@ async function runPglite() {
             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);
     process.stdout.write('managed infrastructure stopped\n');
     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.js");
+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() {
+    const { redisTwinDown, redisTwinStatus, redisTwinUp } = await import("./redis-backing.js");
+    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.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');
@@ -120,13 +169,13 @@ else if (phase === 'status') {
     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']);

package/dist/src/init.js

@@ -37,7 +37,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { PROTOCOL_MAJOR, stateDirName } from '@volter/world-core';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { coverWorld, detectRepoVendors, envNameVendor, formatCoverageReport, injectorEnvNameForKey, injectorVendorKeysFor, isCredentialShapedEnvName, registryAcknowledgedReason, } from "./covers.js";
-import { fakeEnvValue, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from "./fixture-env.js";
+import { fakeEnvValue, isAppKeyName, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from "./fixture-env.js";
 import { resolveCatalog, twinPackageName } from "./catalog.js";
 import { projectEnvReads, projectManifestDirs } from "./project-inspect.js";
 import { overlayEndpointEnv, packFacts } from "./pack-facts.js";
@@ -119,6 +119,20 @@ export const APP_READ_ENDPOINT_ENV = {
             + 'sends there. Read the mail back over the twin-only inspect sidecar: `world-smtp serve --inspect-port N`, then '
             + 'GET http://127.0.0.1:N/twin/messages/latest.',
     },
+    // RAW PROTOCOL, the gRPC kind. The Temporal SDKs dial the frontend address they are given
+    // (`Connection.connect({ address })`, `NativeConnection.connect({ address })`), conventionally read
+    // from TEMPORAL_ADDRESS — Postiz's temporal.module.ts, the SDK samples and the Temporal CLI all read
+    // that name — and speak gRPC over HTTP/2, which the http/fetch injector never sees. The value is an
+    // address (host:port), not a URL, which is why this lives here as a template and not as the
+    // descriptor's `endpointEnv` (whose `name` receives the twin's URL).
+    temporal: {
+        injectEnvTemplates: {
+            TEMPORAL_ADDRESS: '${host}:${port}',
+        },
+        note: 'no injector entry and none possible: the Temporal SDKs speak gRPC to the address they are configured with. '
+            + 'TEMPORAL_ADDRESS=<host>:<port> points them at the twin (namespace `default` exists); an app that sets '
+            + 'TEMPORAL_API_KEY turns TLS on in the SDK, which this loopback frontend does not speak — leave it unset.',
+    },
 };
 // descriptor-first migration (adding-a-twin.md §3): packs now declare their endpoint-env wiring (with its grounding
 // note) on the descriptor (`endpointEnv` on TwinPack); the table above shrinks toward empty as
@@ -257,7 +271,7 @@ const INFRA_PLACEHOLDER = {
 //
 // The subject pilots (dub, cal.com) put the number on it: world-side setup is seconds, and the
 // minutes go to the app side — most avoidably, to hand-writing infrastructure for the Postgres/
-// MySQL/Redis the repo signalled. For the kinds below, `init` upgrades the placeholder to a
+// MySQL/Redis/MongoDB the repo signalled. For the kinds below, `init` upgrades the placeholder to a
 // World-managed service and private definition with env URLs already pointing at it. The helper
 // owns its implementation behind the declared service boundary. Kinds without a recipe keep the
 // placeholder + `//infra` stub.
@@ -285,6 +299,15 @@ const COMPOSE_INFRA = {
         volumePath: '/data',
         healthcheck: () => ['CMD', 'redis-cli', 'ping'],
     },
+    // Without a container runtime the containerless backing serves this kind with the MongoDB twin
+    // (@volter/twin-mongodb), at the same loopback port and URL.
+    mongodb: {
+        image: 'mongo:7',
+        containerPort: 27017,
+        memoryMiB: 1024,
+        volumePath: '/data/db',
+        healthcheck: () => ['CMD', 'mongosh', '--quiet', '--eval', "db.adminCommand('ping').ok"],
+    },
 };
 /** FNV-1a 32-bit — a tiny, dependency-free stable string hash for port derivation. */
 function fnv1a(text) {
@@ -326,9 +349,12 @@ function composeService(name, kind, signals, taken) {
     const recipe = COMPOSE_INFRA[kind];
     const hostPort = composePort(name, kind, taken);
     const ident = composeIdent(name);
+    // redis and mongodb run without authentication (no credentials in their images' env), so their URLs carry none
     const url = kind === 'redis'
         ? `redis://127.0.0.1:${hostPort}`
-        : `${kind}://${composeUser(name, kind)}:${ident}@127.0.0.1:${hostPort}/${ident}`;
+        : kind === 'mongodb'
+            ? `mongodb://127.0.0.1:${hostPort}/${ident}`
+            : `${kind}://${composeUser(name, kind)}:${ident}@127.0.0.1:${hostPort}/${ident}`;
     return {
         kind,
         image: recipe.image,
@@ -340,7 +366,7 @@ function composeService(name, kind, signals, taken) {
         signals,
     };
 }
-/** The declared env of one compose service (empty for redis). */
+/** The declared env of one compose service (empty for redis and mongodb). */
 function composeEnvironment(name, kind) {
     const ident = composeIdent(name);
     if (kind === 'postgres') {
@@ -661,7 +687,7 @@ export function planWorldInit(name, repoPath, options = {}) {
         // RULE 3: credential-shaped means faked, even when no vendor claims the stem. That covers
         // app-local secrets (JWT_SECRET, ENCRYPTION_KEY) and untwinned vendors alike — and it is the
         // reason a live key committed to `.env.example` can never reach the emitted world.
-        if (isCredentialShapedEnvName(name)) {
+        if (isCredentialShapedEnvName(name) || isAppKeyName(name)) {
             env[name] = fakeEnvValue(name);
             envRows.push({ name, disposition: 'faked', source, reason: 'credential-shaped name — the example value is never copied' });
             continue;

package/dist/src/pglite-backing.d.ts

@@ -11,6 +11,14 @@ export declare function parseInfraDefinition(text: string): InfraService[];
 /** Endpoints of the declared infrastructure, published through external.discover. Only URLs
  * whose protocol and loopback port match a declared service belong to this lifecycle. */
 export declare function infraConnections(services: InfraService[], env: Record<string, string | undefined>): Record<string, string>;
+/** The MongoDB twin's cli: the package installed above the World's config (an app repo), else the one
+ *  this runtime was installed with (its dependency, or the checkout's workspace link). */
+export declare function mongodbTwinCli(worldConfig?: string, froms?: string[]): string;
+/** The runtime a twin's cli runs under. A published package's cli is JavaScript and runs under this
+ *  process's own runtime; a checkout's is TypeScript whose kernel needs more than Node's type
+ *  stripping, so it runs under Bun (this process's, or the one on PATH) — the repository's toolchain —
+ *  and without Bun it is refused by name rather than started to fail. */
+export declare function twinRunner(cli: string, bunOnPath?: () => boolean, underBun?: boolean): string;
 /** The kinds this backing cannot serve, or [] when it can serve the world. */
 export declare function unsupportedKinds(services: InfraService[]): string[];
 export declare function pgliteUp(services: InfraService[], dataDir: string): Promise<void>;