@volter/world-runtime 2.0.0 → 2.0.2

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') {
@@ -22,7 +23,7 @@ if (!existsSync(definition)) {
     process.exit(2);
 }
 const base = ['compose', '-f', definition];
-const run = (args) => spawnSync('docker', [...base, ...args], {
+const run = (args) => spawnSync('docker', [...base, ...args], { windowsHide: true,
     encoding: 'utf8',
     env: { ...process.env, VOLTER_WORLD_DATA: worldData },
     timeout: 120_000,
@@ -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;
@@ -55,7 +57,7 @@ function selectBacking() {
         process.stderr.write(`managed infrastructure: VOLTER_WORLD_INFRA_BACKING must be docker or pglite (got ${JSON.stringify(forced)})\n`);
         process.exit(2);
     }
-    const probe = spawnSync('docker', ['info', '--format', '{{.ServerVersion}}'], { encoding: 'utf8', timeout: 10_000 });
+    const probe = spawnSync('docker', ['info', '--format', '{{.ServerVersion}}'], { windowsHide: true, encoding: 'utf8', timeout: 10_000 });
     if (probe.status === 0)
         return 'docker';
     // Absence of a container runtime (no binary, no daemon) is a capability
@@ -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.d.ts

@@ -214,7 +214,7 @@ export declare function renderEnvFile(plan: InitPlan): string;
 /** Write the plan's two artifacts. Byte-identical for the same repo + catalog: sorted keys, no
  * timestamps, no absolute paths inside the files. */
 /** What `.volter/.gitignore` says: the story is committed, the running state never is. */
-export declare const STATE_GITIGNORE = "# Volter: the world's running state and live env \u2014 never committed. world.json, handlers/ and seeds/ are the story.\nworlds/\ncurrent\n*.env\ncredentials/\ntoken\n";
+export declare const STATE_GITIGNORE = "# Volter: the world's running state and live env \u2014 never committed. world.json, handlers/ and seeds/ are the story.\nworlds/\ncurrent\n*.env\ncredentials/\ntoken\ntoken.read\nsessions.json\nkeys.json\n";
 export declare function writeWorldInit(plan: InitPlan, options?: {
     force?: boolean;
 }): void;

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;
@@ -937,6 +963,9 @@ current
 *.env
 credentials/
 token
+token.read
+sessions.json
+keys.json
 `;
 export function writeWorldInit(plan, options = {}) {
     // A world already here is refused unless forced; a `.volter/` holding only running state

package/dist/src/local-branches.d.ts

@@ -0,0 +1,37 @@
+import { type BranchDoors, type BranchRow, type MountedWorld } from './served-world.js';
+export type LocalBranchesOptions = {
+    /** where branches live: `<dir>/<org>/<world>/` */
+    dir: string;
+    /** the URL a branch reaches its parent at (the host's own listener, on loopback) */
+    origin: () => string;
+    /** the Worlds the host serves, by served name; branches join it while they live */
+    worlds: Map<string, MountedWorld>;
+    /** mount a World at a root, with its branches doors wired */
+    mount: (root: string) => Promise<MountedWorld>;
+    announce?: (line: string) => void;
+};
+export declare class LocalBranches {
+    private readonly o;
+    private sweeper;
+    constructor(o: LocalBranchesOptions);
+    private record;
+    /** The branches of `parent` this host holds. */
+    list(parent: string): BranchRow[];
+    /** Branches being made, by parent: a parent is not removed mid-clone. */
+    private readonly making;
+    hasBranches(parent: string): boolean;
+    /** A World's branches doors, answered by this host. */
+    doorsFor(parent: string): BranchDoors;
+    private create;
+    private make;
+    /** The parent's frozen clock, when it has one. */
+    private frozenClock;
+    /** Stop a branch and remove its World (a branch's own branches first). */
+    remove(name: string): Promise<void>;
+    /** Remove the branches whose time ran out, now and every minute while the host serves. */
+    resume(): Promise<void>;
+    /** One sweep at a time: a slow one never overlaps the next. */
+    private sweeping;
+    private sweep;
+    stop(): void;
+}

package/dist/src/local-branches.js

@@ -0,0 +1,193 @@
+// LOCAL BRANCHES: the branches a local host makes of the Worlds it serves (docs/contributing/architecture.md,
+// "Viewing a World"). A branch is another World: the parent's config under a new name, cloned from the
+// parent through its own doors (its history cut at an instant, when one is asked), its clock frozen at
+// that instant so no twin's catch-up walks it forward, and removed when its time runs out. world-host
+// and `volter world view` both make them with this; a hosted World's supervisor makes its own.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { stateDirName, withStateRemoval } from '@volter/world-core';
+import { clockFile } from "./runtime.js";
+import { loadWorldConfig } from "./configs.js";
+import { TOKEN_HEADER } from "./served-world.js";
+const RECORD = 'branch.json';
+const SWEEP_MS = 60_000;
+/** A World's manifest under another name, in the manifest's own format: format 2 names a World in
+ *  `metadata.id` and serves it bare at `serving.name`; format 1 in `id` and `bare.name`. */
+function renamed(config, id, name) {
+    if (config.schemaVersion === 2) {
+        return { ...config, metadata: { ...config.metadata, id }, serving: { ...config.serving, mode: 'bare', name } };
+    }
+    return { ...config, id, bare: { ...config.bare, name } };
+}
+export class LocalBranches {
+    o;
+    sweeper = null;
+    constructor(o) {
+        this.o = o;
+    }
+    record(world) {
+        try {
+            return JSON.parse(readFileSync(join(world.root, stateDirName(), RECORD), 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The branches of `parent` this host holds. */
+    list(parent) {
+        const rows = [];
+        for (const [name, world] of this.o.worlds) {
+            const r = this.record(world);
+            if (r?.from === parent)
+                rows.push({ name, from: r.from, at: r.at, createdAt: r.createdAt, expiresAt: r.expiresAt });
+        }
+        return rows.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    }
+    /** Branches being made, by parent: a parent is not removed mid-clone. */
+    making = new Map();
+    hasBranches(parent) { return (this.making.get(parent) ?? 0) > 0 || this.list(parent).length > 0; }
+    /** A World's branches doors, answered by this host. */
+    doorsFor(parent) {
+        return {
+            list: async () => this.list(parent),
+            create: (at, ttl, _origin, parentKey) => this.create(parent, at, ttl, parentKey),
+            remove: async (name) => { const w = this.o.worlds.get(name); if (!w || this.record(w)?.from !== parent)
+                return false; await this.remove(name); return true; },
+        };
+    }
+    async create(parent, at, ttlSeconds, parentKey) {
+        this.making.set(parent, (this.making.get(parent) ?? 0) + 1);
+        try {
+            return await this.make(parent, at, ttlSeconds, parentKey);
+        }
+        finally {
+            const left = (this.making.get(parent) ?? 1) - 1;
+            if (left > 0)
+                this.making.set(parent, left);
+            else
+                this.making.delete(parent);
+        }
+    }
+    async make(parent, at, ttlSeconds, parentKey) {
+        const from = this.o.worlds.get(parent);
+        if (!from)
+            throw new Error(`no world ${parent} here`);
+        const [org, world] = parent.split('/');
+        const stamp = at.instant ? at.instant.replace(/[-:]/g, '').replace(/\.\d+Z$|Z$/, '').toLowerCase().slice(0, 13) : 'now';
+        // a labelled branch (a pull request's preview) is named for its label; the random tail keeps a replacement distinct
+        // a name already taken (a 4-hex tail's rare clash) is passed over for a fresh tail, never made over
+        const free = () => {
+            for (let tries = 0; tries < 8; tries++) {
+                const suffix = `${at.label ? `-${at.label}` : `-at-${stamp}`}-${Buffer.from(crypto.getRandomValues(new Uint8Array(2))).toString('hex')}`;
+                const id = `${world.slice(0, 64 - suffix.length)}${suffix}`;
+                const name = `${org}/${id}`;
+                const root = join(this.o.dir, org, id);
+                if (!this.o.worlds.has(name) && !existsSync(root))
+                    return { id, name, root };
+            }
+            return null;
+        };
+        const picked = free();
+        if (!picked)
+            throw new Error(`no free name for a branch of ${parent}`);
+        const { id, name, root } = picked;
+        // the parent's config under the branch's own name: the same twins, served at the branch's place
+        mkdirSync(join(root, stateDirName()), { recursive: true });
+        writeFileSync(join(root, stateDirName(), 'world.json'), `${JSON.stringify(renamed(JSON.parse(readFileSync(join(from.root, stateDirName(), 'world.json'), 'utf8')), id, name), null, 2)}\n`);
+        let mounted;
+        try {
+            mounted = await this.o.mount(root);
+            await mounted.boot(this.o.origin());
+            this.o.worlds.set(name, mounted);
+            const origin = this.o.origin();
+            // each twin's history cut at the instant, by the parent's own history door
+            let views;
+            if (at.instant) {
+                const cut = await from.handle(new Request(`${origin}/-/${parent}/history?at=${encodeURIComponent(at.instant)}`, { headers: { [TOKEN_HEADER]: from.token } }));
+                if (!cut.ok)
+                    throw new Error(`the history of ${parent} at ${at.instant}: ${await cut.text()}`);
+                views = (await cut.json()).views;
+            }
+            const cloned = await mounted.handle(new Request(`${origin}/-/${name}/origin`, { method: 'PUT', headers: { [TOKEN_HEADER]: mounted.token, 'content-type': 'application/json' }, body: JSON.stringify({ url: `${origin}/${parent}`, token: parentKey ?? from.token, ...(views ? { views } : {}) }) })); // the branch's own key to its parent (the parent's doors make it), never the parent's token
+            if (!cloned.ok)
+                throw new Error(`cloning ${parent}: ${await cloned.text()}`);
+            // the branch's clock stands at its instant, else at the parent's: no twin's catch-up walks it on
+            // (a parent whose clock was never set: the branch's stands at now, frozen there, as http-api says);
+            // a live branch (a pull request's preview) keeps the parent's time: real time, or its simulated clock
+            const clock = at.instant ?? this.frozenClock(from) ?? (at.live ? null : new Date().toISOString());
+            if (clock) {
+                const file = clockFile(root, id);
+                mkdirSync(dirname(file), { recursive: true });
+                writeFileSync(file, `${clock}\n`);
+            }
+            const createdAt = new Date().toISOString();
+            const expiresAt = ttlSeconds === null ? null : new Date(Date.now() + ttlSeconds * 1000).toISOString();
+            writeFileSync(join(root, stateDirName(), RECORD), `${JSON.stringify({ from: parent, at: at.instant ? { instant: at.instant } : null, createdAt, expiresAt }, null, 2)}\n`);
+            this.o.announce?.(`branch   ${name}  of ${parent}${at.instant ? ` as of ${at.instant}` : ''}${expiresAt ? `, until ${expiresAt}` : ''}`);
+            return { name, token: mounted.token, readToken: mounted.readToken, expiresAt };
+        }
+        catch (error) {
+            this.o.worlds.delete(name);
+            try {
+                await mounted?.stop();
+            }
+            catch { /* reported below */ }
+            withStateRemoval(root, () => rmSync(root, { recursive: true, force: true }));
+            throw error;
+        }
+    }
+    /** The parent's frozen clock, when it has one. */
+    frozenClock(world) {
+        try {
+            const held = readFileSync(clockFile(world.root, loadWorldConfig(join(world.root, stateDirName(), 'world.json'), world.root).config.id), 'utf8').trim();
+            return Number.isNaN(Date.parse(held)) ? null : held;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Stop a branch and remove its World (a branch's own branches first). */
+    async remove(name) {
+        const world = this.o.worlds.get(name);
+        if (!world)
+            return;
+        for (const child of this.list(name))
+            await this.remove(child.name);
+        await world.stop();
+        withStateRemoval(world.root, () => rmSync(world.root, { recursive: true, force: true }));
+        this.o.worlds.delete(name);
+        this.o.announce?.(`removed  ${name}`);
+    }
+    /** Remove the branches whose time ran out, now and every minute while the host serves. */
+    async resume() {
+        await this.sweep();
+        this.sweeper = setInterval(() => { void this.sweep(); }, SWEEP_MS);
+        this.sweeper.unref?.();
+    }
+    /** One sweep at a time: a slow one never overlaps the next. */
+    sweeping = false;
+    async sweep() {
+        if (this.sweeping)
+            return;
+        this.sweeping = true;
+        try {
+            const now = Date.now();
+            for (const [name, world] of [...this.o.worlds]) {
+                const r = this.record(world);
+                if (r?.expiresAt && Date.parse(r.expiresAt) <= now && this.o.worlds.has(name)) {
+                    try {
+                        await this.remove(name);
+                    }
+                    catch (error) {
+                        this.o.announce?.(`branch   ${name}: removal failed: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+            }
+        }
+        finally {
+            this.sweeping = false;
+        }
+    }
+    stop() { if (this.sweeper)
+        clearInterval(this.sweeper); this.sweeper = null; }
+}

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>;