@volter/world-runtime 2.0.0

package/dist/src/host.js

@@ -0,0 +1,135 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// Co-located twin host — run many twins in ONE process instead of one OS process
+// per twin. The twin core is a pure, transport-agnostic handler (see a pack's
+// `handle<Vendor>TwinRequest`), so nothing requires a process per twin; this host
+// mounts N of them behind their own ports/URLs (the world env + instance.json are
+// byte-identical to the spawned path — only the process model changes).
+//
+// Isolation is a DIAL, not a binary (the runtime stays minimal — this is still just
+// "bring services up / tear them down", one child process):
+//   - 'shared' : all twins share one event loop + heap. Lightest. A thrown request
+//                handler is isolated (Bun.serve returns 500; siblings serve on), but a
+//                CPU hog / OOM / process.exit in one twin hits all. Default for CI/dev.
+//   - 'worker' : one Worker thread per twin → own event loop + own heap, independently
+//                isolated. A sibling can spin, leak, or hard-exit without taking the
+//                host down — but a crashed twin stays down (doctor red), it is never
+//                respawned. Still ONE OS process to the orchestrator.
+// ('process' isolation — one OS process per twin — is the world runtime's existing
+//  spawn path; it remains the oracle and the choice for share/sealed/hosted worlds.)
+//
+// ARCHITECTURE: the runtime never imports vendor packs. A twin is named by a module
+// SPECIFIER + export resolved with dynamic import() at boot, so this host (and the
+// world config that drives it) stays vendor-agnostic — exactly like `bin` spawning.
+import { Worker } from 'node:worker_threads';
+import { siblingScript } from "./sibling.js";
+import { pathToFileURL } from 'node:url';
+async function loadFactory(spec) {
+    const mod = (await import(__rewriteRelativeImportExtension(spec.module)));
+    const factory = mod[spec.export];
+    if (typeof factory !== 'function') {
+        throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);
+    }
+    return factory;
+}
+const workerEntry = () => pathToFileURL(siblingScript(import.meta.url, 'host-worker'));
+/** Per-twin stop budget inside host.stop(). Must stay comfortably under downWorld's 5s
+ *  SIGTERM→SIGKILL grace (DOWN_GRACE_MS_DEFAULT): the host must reach process.exit(0) even
+ *  when a twin's stop hangs, or the whole co-located world dies by SIGKILL. */
+const STOP_TIMEOUT_MS = 3000;
+/**
+ * Start a co-located host. Resolves once every twin is listening. The returned `stop()`
+ * tears the whole host down (all servers / all workers).
+ *
+ * `onEvent` is an optional observability hook (logged by the CLI) — it surfaces a twin
+ * worker crashing (and being given up on), and stray rejections swallowed in shared mode,
+ * so a degraded twin is never a silent fake-success.
+ */
+export async function startColocatedHost(specs, options = {}) {
+    const isolation = options.isolation ?? 'shared';
+    const onEvent = options.onEvent ?? (() => { });
+    const ports = {};
+    for (const spec of specs)
+        ports[spec.id] = spec.port;
+    if (isolation === 'shared') {
+        // Keep one twin's stray async rejection / uncaught throw from killing every other twin in
+        // the shared process. (A thrown *request* handler is already contained by Bun.serve → 500.)
+        // We log and attribute rather than exit — state stays consistent because every kernel write
+        // is atomic (temp→rename) and root-keyed, so a swallowed error can't corrupt a sibling.
+        const onRejection = (reason) => onEvent({ twin: '(host)', kind: 'unhandledRejection', detail: String(reason) });
+        const onUncaught = (err) => onEvent({ twin: '(host)', kind: 'uncaughtException', detail: String(err) });
+        process.on('unhandledRejection', onRejection);
+        process.on('uncaughtException', onUncaught);
+        const servers = [];
+        for (const spec of specs) {
+            const factory = await loadFactory(spec);
+            servers.push(await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}) }));
+        }
+        return {
+            isolation,
+            ports,
+            stop: async () => {
+                process.off('unhandledRejection', onRejection);
+                process.off('uncaughtException', onUncaught);
+                // EVERY stop is invoked, IN PARALLEL, each under its own timeout, and no outcome —
+                // rejection, hang, or slowness — can prevent the others or wedge host.stop() itself.
+                // The awaited-sequential first cut re-created the SIGKILL escalation it was fixing
+                // through a new door (§9 round two H2, 2026-08-31: one pending/throwing stop — fly's
+                // cleanup throws on a failed container removal — left siblings unstopped and the host
+                // ignoring SIGTERM forever). The bound stays under downWorld's 5s SIGKILL grace.
+                await Promise.allSettled(servers.map((s) => Promise.race([
+                    Promise.resolve().then(() => s.stop()),
+                    new Promise((resolveTimeout) => setTimeout(resolveTimeout, STOP_TIMEOUT_MS).unref?.()),
+                ])));
+            },
+        };
+    }
+    // worker isolation — one Worker thread per twin, given up on crash — never respawned.
+    const stopping = { value: false };
+    const workers = new Map();
+    const spawnWorker = (spec) => new Promise((resolveReady, rejectReady) => {
+        const worker = new Worker(workerEntry(), { workerData: spec });
+        // Pure observability, symmetric with `gaveup` below — NOT a supervision hook. Fired exactly
+        // once per spawnWorker() call (there's no counter/timer/keep-alive here), so it doubles as a
+        // direct tamper guard: a stealth respawn re-adding `spawnWorker(spec)` in the exit handler
+        // below would emit a 2nd `spawn` for the same twin, which the isolation test asserts against.
+        onEvent({ twin: spec.id, kind: 'spawn', detail: 'worker started' });
+        let ready = false;
+        worker.on('message', (msg) => {
+            if (msg?.type === 'ready') {
+                ready = true;
+                resolveReady();
+            }
+        });
+        worker.on('error', (err) => {
+            onEvent({ twin: spec.id, kind: 'error', detail: String(err) });
+            if (!ready)
+                rejectReady(err);
+        });
+        worker.on('exit', (code) => {
+            workers.delete(spec.id);
+            if (stopping.value || code === 0)
+                return;
+            // Minimal-primitive doctrine: no keep-alive supervisor. A crashed worker is NOT
+            // respawned — record the give-up (host-cli persists it → doctor red) and stay dead.
+            onEvent({ twin: spec.id, kind: 'gaveup', detail: `exit code ${code} — not restarted`, exits: 1 });
+        });
+        workers.set(spec.id, worker);
+    });
+    for (const spec of specs)
+        await spawnWorker(spec);
+    return {
+        isolation,
+        ports,
+        stop: async () => {
+            stopping.value = true;
+            await Promise.all([...workers.values()].map((w) => w.terminate()));
+        },
+    };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,48 @@
+export type { WorldConfig, WorldInstance, WorldIsolation, WorldMode, WorldServiceConfig, WorldServiceType, WorldExternalServiceConfig, WorldExternalDiscover, WorldExternalDiscoverSource, WorldExternalReadyWhen, WorldRunOutcome, WorldRunRecord, WorldResourceRequirements, WorldManifestV2, WorldSelection, WorldSelectionSelector, WorldUsage, } from './schema.js';
+export { DEFAULT_WORLD_SELECTION, LEGACY_WORLD_SELECTION, WORLD_SCHEMA_VERSION, WORLD_USAGES, worldConfigDocument, worldSelectionIncludes } from './schema.js';
+export { loadWorldConfig, migrateWorldConfig, resolveConfigPath, writeWorldConfig } from './configs.js';
+export type { WorldConfigMigration } from './configs.js';
+export { upWorld, downWorld, pruneWorlds, listWorlds, statusWorld, doctorWorld, runWithWorldEnv, attachWorld, retireWorldConsumers, activateScript, shellWorld, worldShellEnv, ensureWorldProxy, runProxyDaemon, runWorld, shareWorld, shareWorldServices, unshareWorld, urlsWorld, urlWorld, } from './runtime.js';
+export type { WorldCleanupEntry } from './runtime.js';
+export { worldResourceReport } from './resources.js';
+export { appUrlFile, appUrlUnsetMessage, detectAppUrl, readAppUrl, setAppUrl } from './app-url.js';
+export type { AppUrlRecord, AppUrlSource } from './app-url.js';
+export { tailWorldActions } from './tail.js';
+export type { TailWorldOptions } from './tail.js';
+export { pushWorldChangeset, rebaseWorldChangeset, approveWorldChangeset, createWorldChangeset, diffWorld, EPHEMERAL_VERIFY_TARGET, findWorldChangeset, listWorldChangesets, listWorldMarks, markWorld, MARK_NOTE_MAX, replayWorldChangeset, resolveBaseMarker, statusWorldChangeset, verifyWorldChangeset, worldChangesetsDir, worldLedgers, worldMarksDir, } from './changeset.js';
+export type { NotedMarker, PushWorldOptions, PushWorldOutcome, RebaseWorldOutcome, ApproveWorldOutcome, ChangesetLocation, VerifyWorldOutcome, WorldRootOptions } from './changeset.js';
+export { checkLocalExecution, checkPrerequisites, formatPrerequisiteChecks, } from './prerequisites.js';
+export { inspectProject, formatProjectInspection, projectDependencies, projectEnvNames, SDK_TWINS, workspaceDirs } from './project-inspect.js';
+export type { ProjectInspection } from './project-inspect.js';
+export { fakeEnvValue, fakeGoogleOAuthClientJson, fakeGoogleServiceAccountJson, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from './fixture-env.js';
+export type { FakeServiceAccountOptions } from './fixture-env.js';
+export { coverWorld, detectRepoVendors, envNameVendor, formatCoverageReport, injectorVendorKeysFor, isCredentialShapedEnvName, worldTwinInventory, } from './covers.js';
+export type { CoverageReport, CoverageRow, CoverageStatus, CoverageOptions, RepoVendorSignals } from './covers.js';
+export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from './init.js';
+export { STATE_GITIGNORE } from './init.js';
+export { clockFile } from './runtime.js';
+export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, type Catalog, type CatalogKind, packCli, packEntry } from './catalog.js';
+export { MINT_ENV } from './schema.js';
+export type { EnvDisposition, InitEnvRow, InitInfraStub, InitOptions, InitPlan, InitResult, InitVendorPlan, InitWiring, } from './init.js';
+export { deriveWorldManifest, findWorldRefFile, isRemoteWorldRef, resolveWorldRef, WORLD_REF_FILE, worldManifest, } from './attach.js';
+export type { ResolvedWorldRef, WorldManifest, WorldRefSource } from './attach.js';
+export { parseSni, readReflectRoutes, reflectRoutesPath, reflectManifestPath, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, CA_TRUST_ENV, ATTACHED_CA_PATH, startReflectFront, startReflectResolver, writeReflectRoutes, } from './reflect.js';
+export type { ReflectFrontHandle, ReflectFrontOptions, ReflectManifest, ReflectResolverHandle, ReflectResolverOptions } from './reflect.js';
+export type { PrerequisiteCheck, PrerequisiteId, } from './prerequisites.js';
+export { startColocatedHost } from './host.js';
+export type { ColocatedTwinSpec, ColocatedHost, HostIsolation } from './host.js';
+export { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer, } from './serve.js';
+export type { ManifestServerHandle, ManifestServerOptions } from './serve.js';
+export { resetWorld, seedEntryFor, seedWorld } from './placeholder.js';
+export type { SeedWorldOptions, SeedWorldOutcome } from './placeholder.js';
+export { fetchFromOrigin, worldOrigin } from './origin.js';
+export type { FetchOptions, FetchOutcome } from './origin.js';
+export { branchWorld, checkoutWorld } from './branch.js';
+export type { BranchOptions } from './branch.js';
+export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.js';
+export type { DeployTwinOutcome, MaterializedRoot } from './root.js';
+export { landReceipts, mountWorld, readServeRecord, refreshSchedule, servedName, serveWorld, TOKEN_HEADER, WorldDoors } from './served-world.js';
+export type { DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.js';
+export type { ServedWorld } from './served-world.js';
+export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor, type ConsoleMount } from './console-apart.js';
+export { assertWorldStateRemovable } from './ancestry.js';

package/dist/src/index.js

@@ -0,0 +1,35 @@
+export { DEFAULT_WORLD_SELECTION, LEGACY_WORLD_SELECTION, WORLD_SCHEMA_VERSION, WORLD_USAGES, worldConfigDocument, worldSelectionIncludes } from "./schema.js";
+export { loadWorldConfig, migrateWorldConfig, resolveConfigPath, writeWorldConfig } from "./configs.js";
+export { upWorld, downWorld, pruneWorlds, listWorlds, statusWorld, doctorWorld, runWithWorldEnv, attachWorld, retireWorldConsumers, activateScript, shellWorld, worldShellEnv, ensureWorldProxy, runProxyDaemon, runWorld, shareWorld, shareWorldServices, unshareWorld, urlsWorld, urlWorld, } from "./runtime.js";
+export { worldResourceReport } from "./resources.js";
+// `volter-world app-url` — the recorded, queryable app endpoint of an instance (see app-url.ts).
+export { appUrlFile, appUrlUnsetMessage, detectAppUrl, readAppUrl, setAppUrl } from "./app-url.js";
+export { tailWorldActions } from "./tail.js";
+// the changeset primitive + the diff verb (docs/concepts/the-model.md v0) and the operational-PR
+// contract over it (v1: verify/approve/status). World-side glue only — markers, deltas, content
+// hashing, replay, verifier evaluation and approval binding live in @volter/world-core's control plane.
+export { pushWorldChangeset, rebaseWorldChangeset, approveWorldChangeset, createWorldChangeset, diffWorld, EPHEMERAL_VERIFY_TARGET, findWorldChangeset, listWorldChangesets, listWorldMarks, markWorld, MARK_NOTE_MAX, replayWorldChangeset, resolveBaseMarker, statusWorldChangeset, verifyWorldChangeset, worldChangesetsDir, worldLedgers, worldMarksDir, } from "./changeset.js";
+export { checkLocalExecution, checkPrerequisites, formatPrerequisiteChecks, } from "./prerequisites.js";
+export { inspectProject, formatProjectInspection, projectDependencies, projectEnvNames, SDK_TWINS, workspaceDirs } from "./project-inspect.js";
+// Structurally valid fake credentials for world configs (fixture env) — see fixture-env.ts
+// for the pattern (a fake a client SDK parses/signs with must be structurally real).
+export { fakeEnvValue, fakeGoogleOAuthClientJson, fakeGoogleServiceAccountJson, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from "./fixture-env.js";
+export { coverWorld, detectRepoVendors, envNameVendor, formatCoverageReport, injectorVendorKeysFor, isCredentialShapedEnvName, worldTwinInventory, } from "./covers.js";
+// `volter-world init` — the deterministic front door: detect the repo's vendors (covers), emit a
+// world config + env file OUTSIDE the repo (fixture-env), and prove the emission with `covers`.
+export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from "./init.js";
+export { STATE_GITIGNORE } from "./init.js";
+export { clockFile } from "./runtime.js";
+export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, packCli, packEntry } from "./catalog.js";
+export { MINT_ENV } from "./schema.js";
+export { deriveWorldManifest, findWorldRefFile, isRemoteWorldRef, resolveWorldRef, WORLD_REF_FILE, worldManifest, } from "./attach.js";
+export { parseSni, readReflectRoutes, reflectRoutesPath, reflectManifestPath, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, CA_TRUST_ENV, ATTACHED_CA_PATH, startReflectFront, startReflectResolver, writeReflectRoutes, } from "./reflect.js";
+export { startColocatedHost } from "./host.js";
+export { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer, } from "./serve.js";
+export { resetWorld, seedEntryFor, seedWorld } from "./placeholder.js";
+export { fetchFromOrigin, worldOrigin } from "./origin.js";
+export { branchWorld, checkoutWorld } from "./branch.js";
+export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from "./root.js";
+export { landReceipts, mountWorld, readServeRecord, refreshSchedule, servedName, serveWorld, TOKEN_HEADER, WorldDoors } from "./served-world.js";
+export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor } from "./console-apart.js";
+export { assertWorldStateRemovable } from "./ancestry.js";

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

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/infra-cli.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// Private implementation for infrastructure emitted by `volter-world init`. World configs invoke
+// this declared service; application agents never operate or diagnose its backing mechanism.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { infraConnections, parseInfraDefinition } from "./pglite-backing.js";
+const phase = process.argv[2];
+if (phase !== 'up' && phase !== 'status' && phase !== 'down') {
+    process.stderr.write('managed infrastructure: expected up, status, or down\n');
+    process.exit(2);
+}
+const worldConfig = process.env.VOLTER_WORLD_CONFIG;
+const worldData = process.env.VOLTER_WORLD_DATA;
+if (!worldConfig || !worldData) {
+    process.stderr.write('managed infrastructure: missing World lifecycle context\n');
+    process.exit(2);
+}
+const definition = join(dirname(worldConfig), 'world.infrastructure.yml');
+if (!existsSync(definition)) {
+    process.stderr.write('managed infrastructure: declared definition is missing\n');
+    process.exit(2);
+}
+const base = ['compose', '-f', definition];
+const run = (args) => spawnSync('docker', [...base, ...args], {
+    encoding: 'utf8',
+    env: { ...process.env, VOLTER_WORLD_DATA: worldData },
+    timeout: 120_000,
+});
+const classify = (raw) => /no space left on device|enospc/iu.test(raw)
+    ? 'insufficient writable storage'
+    : /out of memory|cannot allocate memory|killed/iu.test(raw)
+        ? 'insufficient memory'
+        : /cannot connect|not running|daemon/iu.test(raw)
+            ? 'local execution capacity is unavailable'
+            : 'managed infrastructure operation failed';
+const fail = (result) => {
+    const raw = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
+    process.stderr.write(`managed infrastructure ${phase} failed: ${classify(raw)}\n`);
+    process.exit(result.status && result.status > 0 ? result.status : 1);
+};
+// ---- backing selection ------------------------------------------------------
+// The declared service contract (up/status/down) is the boundary; WHICH
+// 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;
+//   4. otherwise the honest refusal naming what this machine cannot serve.
+function selectBacking() {
+    const forced = process.env.VOLTER_WORLD_INFRA_BACKING;
+    if (forced === 'docker' || forced === 'pglite')
+        return forced;
+    if (forced !== undefined) {
+        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 });
+    if (probe.status === 0)
+        return 'docker';
+    // Absence of a container runtime (no binary, no daemon) is a capability
+    // difference: swap backings. A PRESENT runtime failing on resources stays
+    // on the docker path so the real capacity problem is classified and
+    // surfaced — a full disk starves every backing equally.
+    if (probe.error !== undefined)
+        return 'pglite';
+    const reason = classify(`${probe.stdout ?? ''}\n${probe.stderr ?? ''}`);
+    return reason === 'local execution capacity is unavailable' ? 'pglite' : 'docker';
+}
+async function runPglite() {
+    const { unsupportedKinds, pgliteUp, pgliteStatus, pgliteDown } = await import("./pglite-backing.js");
+    const services = parseInfraDefinition(readFileSync(definition, 'utf8'));
+    if (services.length === 0) {
+        process.stderr.write('managed infrastructure: the declared definition names no services\n');
+        process.exit(1);
+    }
+    const unsupported = unsupportedKinds(services);
+    if (unsupported.length > 0) {
+        process.stderr.write(`managed infrastructure ${phase} failed: local execution capacity is unavailable (no container runtime, and the containerless backing cannot serve: ${unsupported.join(', ')})\n`);
+        process.exit(1);
+    }
+    if (phase === 'up') {
+        process.stdout.write('managed infrastructure backing: pglite (no container runtime)\n');
+        try {
+            await pgliteUp(services, worldData);
+        }
+        catch (error) {
+            process.stderr.write(`managed infrastructure up failed: ${String(error.message ?? error)}\n`);
+            process.exit(1);
+        }
+        process.stdout.write('managed infrastructure ready\n');
+        process.exit(0);
+    }
+    if (phase === 'status') {
+        const status = await pgliteStatus(services, worldData);
+        if (!status.ok) {
+            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.exit(0);
+    }
+    await pgliteDown(services, worldData);
+    process.stdout.write('managed infrastructure stopped\n');
+    process.exit(0);
+}
+if (selectBacking() === 'pglite') {
+    await runPglite();
+}
+if (phase === 'up') {
+    const result = run(['up', '-d', '--wait']);
+    if (result.status !== 0)
+        fail(result);
+    process.stdout.write('managed infrastructure ready\n');
+}
+else if (phase === 'status') {
+    const expected = run(['config', '--services']);
+    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();
+    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.exit(1);
+    }
+    process.stdout.write(`${JSON.stringify({ ok: true, services: expectedNames.length, connections: infraConnections(parseInfraDefinition(readFileSync(definition, 'utf8')), process.env) })}\n`);
+}
+else {
+    const result = run(['down', '--remove-orphans']);
+    if (result.status !== 0)
+        fail(result);
+    process.stdout.write('managed infrastructure stopped\n');
+}

package/dist/src/init.d.ts

@@ -0,0 +1,227 @@
+import { type CoverageReport } from './covers.js';
+import { type WorldConfig, type WorldServiceConfig } from './schema.js';
+/** How a twin service in the emitted world is reached by the app's traffic. */
+export type InitWiring = 
+/** the injector redirects the vendor's real hosts; `injectEnv` is a var it genuinely reads */
+'injector'
+/** no injector entry, but the SDK reads a documented endpoint env var (INNGEST_BASE_URL, …) */
+ | 'app-read'
+/** no injector entry and no endpoint env: the SDK is pointed at the twin by explicit client config */
+ | 'explicit-config'
+/** detected vendor with no `packages/twin/<vendor>` pack in the catalog — nothing to emit */
+ | 'no-pack';
+export type InitVendorPlan = {
+    vendor: string;
+    /** the catalog pack backing it, or null for 'no-pack' */
+    pack: string | null;
+    /** how the repo betrayed it, verbatim from the coverage proof's detection */
+    detectedVia: string[];
+    wiring: InitWiring;
+    /** the emitted service, or null when nothing could be emitted */
+    service: WorldServiceConfig | null;
+    /** why this wiring — printed in the report and embedded in the service's `//` note */
+    note: string;
+};
+/** What `init` did with one env NAME found in the repo's example env files. */
+export type EnvDisposition = 
+/** credential-shaped → replaced by a structurally valid fake (never the committed value) */
+'faked'
+/** non-credential app config → the example value copied verbatim */
+ | 'kept'
+/** infra connection string → points at a World-managed infrastructure service */
+ | 'compose'
+/** infra connection string → a documented placeholder the operator fills in */
+ | 'placeholder'
+/** neither credential-shaped nor valued: the operator has to decide */
+ | 'unknown';
+export type InitEnvRow = {
+    name: string;
+    disposition: EnvDisposition;
+    /** repo-relative env file the name came from */
+    source: string;
+    reason: string;
+    /** an example key with no value: declared, and left unset in the World so the app's own env files provide it */
+    unset?: true;
+};
+/** An example env name that is EMPTY yet read directly by production source. This does not pretend
+ * to know the app's validator; it is ranked separately because it may stop the app before listen. */
+export type InitBootRisk = {
+    name: string;
+    /** example env file carrying the empty value */
+    source: string;
+    /** production source reads (`path:line`) */
+    readAt: string[];
+};
+/** Infra the repo signals through its env (Postgres, MySQL, Redis, …) but that no twin models:
+ * emitted as a DOCUMENTED `external`-service stub the operator fills in and moves into `services`. */
+export type InitInfraStub = {
+    kind: string;
+    /** the env names that betrayed it */
+    signals: string[];
+    /** the stub object written under the config's `//infra` key */
+    stub: Record<string, unknown>;
+};
+/** One service in the private managed-infrastructure definition — detected infra `init` can
+ * declare under the World lifecycle instead of leaving a placeholder for an operator. */
+export type InitComposeService = {
+    kind: string;
+    image: string;
+    /** deterministic host port, derived from the world name (see composePort) */
+    hostPort: number;
+    containerPort: number;
+    memoryMiB: number;
+    /** compose volume key, or null (the on-disk docker volume is `<project>_<key>` — the compose
+     * project name carries the world name, so volumes are named per world) */
+    volume: string | null;
+    /** the connection URL emitted for every env name that signalled this kind */
+    url: string;
+    /** the env names that betrayed it */
+    signals: string[];
+};
+export type InitPlan = {
+    name: string;
+    repo: string;
+    out: string;
+    /** the world lives in the app repo (`<repo>/.volter`), not in a pilot directory elsewhere */
+    inRepo: boolean;
+    /** where the twins came from: this checkout, or the packages installed above the root */
+    catalog: 'checkout' | 'installed';
+    configPath: string;
+    envPath: string;
+    config: WorldConfig;
+    /** the env block, identical to the config's `env` — `app.env` is rendered from this same map */
+    env: Record<string, string>;
+    vendors: InitVendorPlan[];
+    envRows: InitEnvRow[];
+    envSources: string[];
+    /** empty example values read by production source — prominent warning, not vendor-coverage fact */
+    bootRisks: InitBootRisk[];
+    infra: InitInfraStub[];
+    /** the services emitted into the private managed-infrastructure definition */
+    compose: InitComposeService[];
+    /** private managed-infrastructure definition, or null when no detected infra has a recipe */
+    composePath: string | null;
+    /** external-service-shaped signals with no vendor mapping AND no standing registry
+     *  acknowledgment — the real worklist (registry-acknowledged signals are partitioned into
+     *  `acknowledgedExternal` below, never silently dropped). */
+    unknown: string[];
+    /** signals the packless-vendor registry carries a STANDING acknowledgment for (census-
+     *  adjudicated acceptable) — separated from `unknown` so the worklist stays real, but
+     *  never silently dropped: each carries its recorded reason. */
+    acknowledgedExternal: Array<{
+        name: string;
+        reason: string;
+    }>;
+    /** pack `defaults/` files copied into the world dir (TWIN-PROGRAMMING-MODEL: default
+     *  reasonable — visible starter seeds/handlers, ownership transfers on copy). */
+    defaultsCopies: Array<{
+        vendor: string;
+        kind: 'handlers' | 'seed';
+        from: string;
+        to: string;
+    }>;
+    /** emitted when any pack ships a default seed: the one explicit entry point + story skeleton */
+    seedEntry: {
+        entryPath: string;
+        storyPath: string;
+    } | null;
+    /** Explicit wiring for new default seeds when the existing entry point is operator-owned. */
+    seedAdditions: Array<{
+        vendor: string;
+        import: string;
+        call: string;
+    }>;
+    /**
+     * THE ONE DOCUMENTED EXCEPTION TO BYTE-IDENTICAL OUTPUT. Every other byte `init` emits is a pure
+     * function of (repo, catalog, world name). These names hold FRESHLY MINTED cryptographic material
+     * — today, the real throwaway RSA key inside a Google service-account JSON, which google-auth-
+     * library signs its assertion with locally before the twin ever sees a request (see fixture-env.ts).
+     * It is non-deterministic BY CONSTRUCTION: a throwaway key that never changes is a committed key,
+     * and fixture-env's whole rule is that keys are minted per process and never committed. So init
+     * names them here (and in the report, and in a comment in the env file) instead of quietly
+     * breaking the determinism claim — an operator diffing two pilots knows exactly which lines may
+     * legitimately differ, and every other line differing is a real change.
+     *
+     * Scope of the exception, exactly: fixture-env mints ONCE PER PROCESS and reuses it, so two inits
+     * in the SAME process (a room initing several repos in one run) are byte-identical even here.
+     * Only separate invocations differ. Both halves are pinned in init.test.ts.
+     */
+    mintedEnv: string[];
+};
+export type InitResult = {
+    plan: InitPlan;
+    coverage: CoverageReport;
+    /** the vendor-coverage proof's verdict — `init`'s exit code IS this; bootRisks stay separate */
+    ok: boolean;
+    /** the exact commands to run next; `init` never runs them itself */
+    next: string[];
+};
+export type InitOptions = {
+    /** the WORLD root: where the emitted config boots from, and where the catalog is resolved —
+     *  this checkout's `packages/twin` when init runs here, else the `@volter/twin-<vendor>`
+     *  packages installed above it (docs/concepts/worlds.md#the-config-and-the-running-world). Defaults to the
+     *  application repo. */
+    root?: string;
+    out?: string;
+    force?: boolean;
+    allowUnknown?: boolean;
+    acknowledge?: Record<string, string>;
+    /** The twins, named outright instead of detected from the repo (a bare world: `init --bare
+     *  <org>/<world> --twins a,b`). */
+    vendors?: string[];
+    /** A world with no app: served as `/<org>/<world>/`. */
+    bare?: string;
+};
+/** The twins available at `root`, sorted — a deterministic input (catalog.ts: this checkout's
+ * `packages/twin/<vendor>/` dirs, or the `@volter/twin-<vendor>` packages installed above root). */
+export declare function packCatalog(root: string): string[];
+/**
+ * The REAL endpoint env names for packs the injector cannot intercept — the other half of
+ * `scripts/vendor-hosts.test.ts`'s descriptor hostsNone ruling. That allowlist states WHY each pack
+ * has no VENDOR_HOSTS entry; this table states WHAT to wire instead, using the env var the vendor's
+ * own SDK documents. Every entry is grounded in the SDK, not invented:
+ *
+ *   inngest                   `INNGEST_BASE_URL` (+ `INNGEST_EVENT_API_BASE_URL` for the event API)
+ *                             — inngest@4's own apiBaseUrl/eventBaseUrl getters.
+ *   ai-gateway                `AI_GATEWAY_BASE_URL` — `@ai-sdk/gateway`'s baseURL env.
+ *   supabase                  `SUPABASE_MGMT_TWIN_URL` — the MANAGEMENT (control-plane) twin only,
+ *                             which is what this pack is; the DATA plane is the real local Supabase
+ *                             stack and is emitted as an infra stub, not faked.
+ *   livekit                   `LIVEKIT_URL` as a ws:// template — the media plane is a WebSocket
+ *                             URL the SDK takes as its first constructor argument.
+ *
+ * A pack that is base-URL-configurable but has NO conventional env var (algolia, pinecone,
+ * replicate, fal, twilio, sendblue, figma, notion) is deliberately ABSENT: it gets a service
+ * with no endpoint env at all, and the proof reports it UNINTERCEPTABLE. Inventing a
+ * `<VENDOR>_BASE_URL` for it would make `covers` call the world covered (any app-read env counts)
+ * while the app, which reads no such var, still talks to the real vendor — the exact class of lie
+ * the proof exists to catch.
+ */
+export declare const APP_READ_ENDPOINT_ENV: Record<string, {
+    injectEnv?: string;
+    injectEnvTemplates?: Record<string, string>;
+    note: string;
+}>;
+/** Render the private managed-infrastructure definition — deterministic, with no absolute paths.
+ * Only meaningful when `plan.compose` is non-empty (writeWorldInit skips it otherwise). */
+export declare function renderComposeFile(plan: InitPlan): string;
+export declare function planWorldInit(name: string, repoPath: string, options?: InitOptions): InitPlan;
+/** The `app.env` rendering of the SAME map the config's `env` block holds — a dotenv for anything
+ * attached to the World (a shell, app process, or CI step), annotated with the
+ * disposition of every name so the file explains itself. Both artifacts are rendered from one map
+ * in one call, so they cannot drift. */
+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 function writeWorldInit(plan: InitPlan, options?: {
+    force?: boolean;
+}): void;
+/**
+ * Plan, emit, and PROVE. The coverage proof runs against the just-written config (by path, so it
+ * reads exactly the bytes on disk rather than the in-memory plan) — `ok` is the proof's verdict and
+ * the caller's exit code. Deliberately does NOT boot the world.
+ */
+export declare function initWorld(name: string, repoPath: string, options?: InitOptions): InitResult;
+export declare function formatInitReport(result: InitResult): string;