@volter/world-runtime 2.0.0

package/dist/src/init.js

@@ -0,0 +1,1117 @@
+// `volter-world init <name> --repo <path>` — the DETERMINISTIC FRONT DOOR of world adoption.
+//
+// Everything it needs already existed, in three pieces that no one command composed:
+//   • `inspect-project` / `covers` know WHICH vendors a repo talks to (dependencies across every
+//     workspace member, vendor-shaped env names in committed .env files, SMTP/raw-protocol signals,
+//     and literal fetch destinations in production source);
+//   • `@volter/world-core/inject`'s VENDOR_HOSTS knows WHICH of those can be intercepted zero-edit, and
+//     under exactly which `*_TWIN_URL` name (the LibreChat `AWS_TWIN_URL` trap is what happens when
+//     a config guesses instead of asking);
+//   • `fixture-env` knows how to mint a fake credential that a client SDK will actually accept
+//     (structurally valid where the SDK parses it, opaque where it does not).
+// `init` composes them into the two files an operator otherwise hand-writes — a world config and an
+// env file — and then RUNS THE PROOF over its own output, so the command's exit code is the answer
+// to "can I `up` this?" rather than a claim that it wrote something.
+//
+// THE FOUR RULES THIS COMMAND IS BUILT ON
+//
+//  1. THE WORLD LIVES IN THE APP REPO. Output goes to `<repo>/.volter/` by default (docs/concepts/worlds.md
+//     #the-config-and-the-running-world): the config, the default data and the handlers are the story and are
+//     committed; the running state is gitignored; nothing written holds a key (`$mint` is minted at boot).
+//     `--out` still emits a disposable pilot elsewhere.
+//  2. INJECT-ENV IS DERIVED, NEVER GUESSED. Every `*_TWIN_URL` this command emits comes from
+//     `injectorVendorKeysFor()` reading the injector's own table. A vendor the injector cannot
+//     intercept gets its REAL app-read endpoint env (INNGEST_BASE_URL, LIVEKIT_URL, …)
+//     from APP_READ_ENDPOINT_ENV below, or — when the vendor's SDK is wired only by explicit client
+//     config — NO env var at all and a note saying so. Emitting a plausible-looking var that
+//     nothing reads would turn the proof green over a world whose traffic still leaves the machine.
+//  3. A COMMITTED EXAMPLE VALUE IS NEVER A SAFE VALUE. Every credential-shaped name is replaced by a
+//     fake, whether or not its stem maps to a vendor: `.env.example` files really do carry live keys
+//     (the ponder blind-adoption run found some). Only non-credential app config is copied verbatim.
+//  4. THE EXIT CODE IS THE VENDOR-COVERAGE PROOF'S. 0 means every detected vendor is covered. 1
+//     means the honest vendor worklist — missing packs, unknown SDKs, twins nothing can reach —
+//     with a remediation line each. App-boot risks are a separate, prominent signal: an empty
+//     example value read by production source can block before listen even when vendor coverage is
+//     green. `init` never boots the world: it diagnoses, the operator (or the room) boots.
+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 { resolveCatalog, twinPackageName } from "./catalog.js";
+import { projectEnvReads, projectManifestDirs } from "./project-inspect.js";
+import { overlayEndpointEnv, packFacts } from "./pack-facts.js";
+import { DEFAULT_WORLD_SELECTION, MINT_ENV, worldConfigDocument, worldSelectionIncludes } from "./schema.js";
+import { loadWorldConfig } from "./configs.js";
+// ---------------------------------------------------------------------------------------------
+// The pack catalog
+// ---------------------------------------------------------------------------------------------
+/** 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 function packCatalog(root) {
+    return resolveCatalog(root).vendors();
+}
+// ---------------------------------------------------------------------------------------------
+// Wiring knowledge
+// ---------------------------------------------------------------------------------------------
+/**
+ * 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 const APP_READ_ENDPOINT_ENV = {
+    tunnel: {
+        injectEnv: 'TUNNEL_SERVER_URL',
+        note: 'no injector entry: the native volter-tunnel CLI and @volter/tunnel WebSocket client are endpoint-configured through TUNNEL_SERVER_URL / the SDK host option; native cloudflared is outside Node HTTP injection.',
+    },
+    // (inngest moved to its pack descriptor's `endpointEnv` — the descriptor-first exemplar (adding-a-twin.md §3).)
+    'ai-gateway': {
+        injectEnv: 'AI_GATEWAY_BASE_URL',
+        note: 'no injector entry: @ai-sdk/gateway is base-URL-configured through AI_GATEWAY_BASE_URL.',
+    },
+    supabase: {
+        injectEnv: 'SUPABASE_MGMT_TWIN_URL',
+        note: 'CONTROL PLANE ONLY — this twin is the Supabase MANAGEMENT API. The DATA plane (Postgres/PostgREST/Storage) '
+            + 'is the REAL local Supabase stack: see the `//infra` supabase stub, fill in its `supabase start` lifecycle, and '
+            + 'move it into "services". Until then the proof reports supabase UNINTERCEPTABLE, which is the truth.',
+    },
+    livekit: {
+        injectEnvTemplates: { LIVEKIT_URL: 'ws://${host}:${port}' },
+        note: 'no injector entry: LIVEKIT_URL is a ws:// endpoint the SDK takes directly — WebSocket media is outside the HTTP injector\'s reach.',
+    },
+    // RAW PROTOCOL. Not "no injector entry yet" — there is no host to map at all: SMTP is a line
+    // protocol over a raw TCP socket, so the injector's http/fetch patches never see it, and the
+    // relay hostname is whatever the operator configured rather than a fixed vendor host. The env
+    // vars ARE the interception, and every one below is a name a real client documents, not an
+    // invention: SMTP_HOST/SMTP_PORT is nodemailer's own transport config and the classic pair every
+    // framework reads; EMAIL_SERVER_HOST/EMAIL_SERVER_PORT is Cal.com's split form; EMAIL_SERVER is
+    // NextAuth's connection-URL form (its Email provider takes `server` as a `smtp://` URL).
+    // Emitting all three shapes is deliberate — an app reads one of them, and which one is not
+    // knowable from the outside.
+    smtp: {
+        injectEnvTemplates: {
+            SMTP_HOST: '${host}',
+            SMTP_PORT: '${port}',
+            EMAIL_SERVER_HOST: '${host}',
+            EMAIL_SERVER_PORT: '${port}',
+            EMAIL_SERVER: 'smtp://${host}:${port}',
+        },
+        note: 'no injector entry and none possible: SMTP is a RAW TCP protocol, invisible to the http/fetch injector, '
+            + 'with no fixed vendor host. Interception is the app-read env itself — point SMTP_HOST/SMTP_PORT (or Cal.com\'s '
+            + 'EMAIL_SERVER_HOST/PORT, or NextAuth\'s EMAIL_SERVER url) at the twin\'s listener and an unmodified nodemailer '
+            + '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.',
+    },
+};
+// 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
+// entries move. The overlay throws on a vendor declared in both homes.
+overlayEndpointEnv(APP_READ_ENDPOINT_ENV);
+/** The canonical wiring for one vendor's twin service, derived from the injector where possible. */
+function wiringFor(vendor) {
+    // RULE 2: ask the injector, never guess. `aws` yields s3/dynamodb/timestream here — the very keys
+    // the inert `AWS_TWIN_URL` does not.
+    const keys = injectorVendorKeysFor(vendor);
+    const twinUrlNames = keys.map(injectorEnvNameForKey);
+    if (twinUrlNames.length > 0) {
+        const [primary, ...rest] = twinUrlNames;
+        // An injector pack may ALSO declare app-read endpoint templates on its descriptor (the
+        // client's own documented option, e.g. PLANETSCALE_DATABASE_URL): those ride alongside.
+        const declared = packFacts()[vendor]?.endpointEnv?.templates ?? {};
+        const templates = { ...Object.fromEntries(rest.map((name) => [name, '${url}'])), ...declared };
+        return {
+            wiring: 'injector',
+            injectEnv: primary,
+            ...(Object.keys(templates).length ? { injectEnvTemplates: templates } : {}),
+            ...(vendor === 'xai' ? {
+                cliRedirect: {
+                    GROK_CLI_CHAT_PROXY_BASE_URL: '${url}/v1',
+                    XAI_TWIN_AUTH_BASE_URL: '${url}',
+                },
+                serviceEnv: { TWIN_XAI_AUTH_SEAM: 'sealed' },
+            } : {}),
+            note: rest.length
+                ? `the injector redirects this vendor under ${twinUrlNames.join(' / ')} — one consolidated twin answers for all of them.`
+                : vendor === 'xai'
+                    ? 'zero-edit for SDK traffic through the injector; the real Grok CLI documents GROK_CLI_CHAT_PROXY_BASE_URL for its chat transport.'
+                    : 'zero-edit: the injector redirects this vendor\'s hosts to the twin.',
+        };
+    }
+    const appRead = APP_READ_ENDPOINT_ENV[vendor];
+    if (appRead) {
+        return {
+            wiring: 'app-read',
+            ...(appRead.injectEnv ? { injectEnv: appRead.injectEnv } : {}),
+            ...(appRead.injectEnvTemplates ? { injectEnvTemplates: appRead.injectEnvTemplates } : {}),
+            note: appRead.note,
+        };
+    }
+    return {
+        wiring: 'explicit-config',
+        note: 'no injector entry and no conventional endpoint env — point the SDK at this twin through its own client option '
+            + `(baseUrl / serverUrl / host). Get the URL with \`volter-world url <world> ${vendor}\`. The proof reports this vendor `
+            + 'UNINTERCEPTABLE until you do; --acknowledge it once the client is wired.',
+    };
+}
+// ---------------------------------------------------------------------------------------------
+// Env-file emission
+// ---------------------------------------------------------------------------------------------
+/** Example/dev env files, in the order a repo's own conventions put them. The first file that
+ * defines a NAME wins, so an explicit `.env.example` beats a stray `.env.development`. */
+const ENV_SOURCE_FILES = [
+    '.env.example',
+    // wasp splits its example env by tier; `covers` already detects the names inside them, so
+    // omitting them left app.env empty for a repo the scanner could see perfectly well (F5).
+    '.env.server.example',
+    '.env.client.example',
+    '.env.sample',
+    '.env.template',
+    '.env.dev.example',
+    '.env.development.example',
+    '.env.local.example',
+    '.env.dev',
+    '.env.development',
+    '.env',
+];
+/** Infra connection strings — the local dependencies a twin never models. Matched on an infra
+ * KEYWORD plus a connection-string suffix, so `REDIS_URL` and `SHADOW_DATABASE_URL` land here while
+ * `UPSTASH_REDIS_REST_URL` (a hosted vendor, `_REST_URL`) is classified as a credential first. */
+const INFRA_ENV = /(^|_)(DATABASE|POSTGRES|POSTGRESQL|PG|MYSQL|MARIADB|MONGO|MONGODB|REDIS|VALKEY|RABBITMQ|AMQP|KAFKA|NATS|CLICKHOUSE|ELASTICSEARCH|OPENSEARCH|MEMCACHED)[A-Z0-9_]*_(URL|URI|DSN|CONNECTION_STRING)$/;
+/** A connection string's own scheme → the infra kind it names, or null. The VALUE is better
+ * evidence than the name: `DATABASE_URL` is generic (dub's is `mysql://`), so a name-only reading
+ * emits a postgres service for a MySQL app and nothing works. */
+const SCHEME_KIND = {
+    postgres: 'postgres', postgresql: 'postgres', pg: 'postgres',
+    mysql: 'mysql', mariadb: 'mysql',
+    mongodb: 'mongodb', 'mongodb+srv': 'mongodb',
+    redis: 'redis', rediss: 'redis', valkey: 'redis',
+    amqp: 'rabbitmq', amqps: 'rabbitmq',
+    kafka: 'kafka', nats: 'nats', clickhouse: 'clickhouse',
+};
+function schemeKindFor(value) {
+    const scheme = value.trim().match(/^([a-z][a-z0-9+.-]*):\/\//i);
+    return scheme === null ? null : SCHEME_KIND[scheme[1].toLowerCase()] ?? null;
+}
+/** name (+ its value, when the example file carries a real connection string) → the infra kind it
+ * signals, or null. */
+function infraKindFor(name, value = '') {
+    if (!INFRA_ENV.test(name))
+        return null;
+    const fromScheme = schemeKindFor(value);
+    if (fromScheme !== null)
+        return fromScheme;
+    if (/(^|_)(POSTGRES|POSTGRESQL|PG|DATABASE)/.test(name))
+        return 'postgres';
+    if (/(^|_)(MYSQL|MARIADB)/.test(name))
+        return 'mysql';
+    if (/(^|_)(MONGO|MONGODB)/.test(name))
+        return 'mongodb';
+    if (/(^|_)(REDIS|VALKEY)/.test(name))
+        return 'redis';
+    if (/(^|_)(RABBITMQ|AMQP)/.test(name))
+        return 'rabbitmq';
+    if (/(^|_)KAFKA/.test(name))
+        return 'kafka';
+    if (/(^|_)NATS/.test(name))
+        return 'nats';
+    if (/(^|_)CLICKHOUSE/.test(name))
+        return 'clickhouse';
+    if (/(^|_)(ELASTICSEARCH|OPENSEARCH)/.test(name))
+        return 'search';
+    return 'memcached';
+}
+/** A documented, unmistakably-not-real placeholder for an infra URL: the right SHAPE (so an app that
+ * parses the URL at import time still starts) with `REPLACE_ME` where the operator must decide. */
+const INFRA_PLACEHOLDER = {
+    postgres: 'postgres://REPLACE_ME:REPLACE_ME@127.0.0.1:5432/REPLACE_ME',
+    mysql: 'mysql://REPLACE_ME:REPLACE_ME@127.0.0.1:3306/REPLACE_ME',
+    mongodb: 'mongodb://127.0.0.1:27017/REPLACE_ME',
+    redis: 'redis://127.0.0.1:6379',
+    rabbitmq: 'amqp://REPLACE_ME:REPLACE_ME@127.0.0.1:5672',
+    kafka: '127.0.0.1:9092',
+    nats: 'nats://127.0.0.1:4222',
+    clickhouse: 'http://127.0.0.1:8123',
+    search: 'http://127.0.0.1:9200',
+    memcached: '127.0.0.1:11211',
+};
+// ---------------------------------------------------------------------------------------------
+// Infra compose emission
+// ---------------------------------------------------------------------------------------------
+//
+// 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
+// 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.
+/** The compose recipes. Versions are CONSERVATIVE major pins (current LTS-grade, not latest):
+ * a pilot wants "boots everywhere", not "newest features" — bump per pilot if the app demands. */
+const COMPOSE_INFRA = {
+    postgres: {
+        image: 'postgres:16',
+        containerPort: 5432,
+        memoryMiB: 1024,
+        volumePath: '/var/lib/postgresql/data',
+        healthcheck: (user) => ['CMD-SHELL', `pg_isready -U ${user}`],
+    },
+    mysql: {
+        image: 'mysql:8.0',
+        containerPort: 3306,
+        memoryMiB: 1024,
+        volumePath: '/var/lib/mysql',
+        healthcheck: () => ['CMD-SHELL', 'mysqladmin ping -h 127.0.0.1 --silent'],
+    },
+    redis: {
+        image: 'redis:7',
+        containerPort: 6379,
+        memoryMiB: 256,
+        volumePath: '/data',
+        healthcheck: () => ['CMD', 'redis-cli', 'ping'],
+    },
+};
+/** FNV-1a 32-bit — a tiny, dependency-free stable string hash for port derivation. */
+function fnv1a(text) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < text.length; index += 1) {
+        hash ^= text.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash >>> 0;
+}
+/** 'auto' ports, deterministically: hashed from `<world>:<kind>` into 20000–39999 (above the
+ * well-known infra defaults, below the common ephemeral range), probing upward on an in-file
+ * collision. Same world name ⇒ same ports (the byte-identity claim holds); two pilots with
+ * different names get different ports and run side by side. NOT a liveness check — init never
+ * binds sockets; a real clash surfaces during World-managed infrastructure startup. */
+function composePort(name, kind, taken) {
+    let port = 20000 + (fnv1a(`${name}:${kind}`) % 20000);
+    while (taken.has(port))
+        port = port === 39999 ? 20000 : port + 1;
+    taken.add(port);
+    return port;
+}
+/** The world name as a conservative identifier for db/user/password names inside the compose
+ * services (world names allow `.`/`-`, SQL identifiers and URL userinfo are happier without). */
+function composeIdent(name) {
+    return name.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+}
+/** The db user the compose service creates. mysql refuses MYSQL_USER=root, so that one world
+ * name gets a suffix — the URL and the compose env both come from here, so they cannot drift. */
+function composeUser(name, kind) {
+    const ident = composeIdent(name);
+    return kind === 'mysql' && ident === 'root' ? 'root_app' : ident;
+}
+/** Compose project names must be `[a-z0-9][a-z0-9_-]*`; world names also allow `.` and uppercase. */
+function composeProject(name) {
+    return `${name.toLowerCase().replace(/[^a-z0-9_-]/g, '-')}-infra`;
+}
+function composeService(name, kind, signals, taken) {
+    const recipe = COMPOSE_INFRA[kind];
+    const hostPort = composePort(name, kind, taken);
+    const ident = composeIdent(name);
+    const url = kind === 'redis'
+        ? `redis://127.0.0.1:${hostPort}`
+        : `${kind}://${composeUser(name, kind)}:${ident}@127.0.0.1:${hostPort}/${ident}`;
+    return {
+        kind,
+        image: recipe.image,
+        hostPort,
+        containerPort: recipe.containerPort,
+        memoryMiB: recipe.memoryMiB,
+        volume: recipe.volumePath === null ? null : `${kind}-data`,
+        url,
+        signals,
+    };
+}
+/** The declared env of one compose service (empty for redis). */
+function composeEnvironment(name, kind) {
+    const ident = composeIdent(name);
+    if (kind === 'postgres') {
+        return [['POSTGRES_USER', ident], ['POSTGRES_PASSWORD', ident], ['POSTGRES_DB', ident]];
+    }
+    if (kind === 'mysql') {
+        return [['MYSQL_ROOT_PASSWORD', ident], ['MYSQL_DATABASE', ident], ['MYSQL_USER', composeUser(name, kind)], ['MYSQL_PASSWORD', ident]];
+    }
+    return [];
+}
+/** Render the private managed-infrastructure definition — deterministic, with no absolute paths.
+ * Only meaningful when `plan.compose` is non-empty (writeWorldInit skips it otherwise). */
+export function renderComposeFile(plan) {
+    const lines = [
+        `# ${plan.name} — private managed infrastructure for this World.`,
+        '# Do not operate this file directly; volter-world owns its complete lifecycle.',
+        '# Persistent bytes live under VOLTER_WORLD_DATA; runtime resources are reclaimed on down.',
+        `name: ${composeProject(plan.name)}`,
+        'services:',
+    ];
+    for (const service of plan.compose) {
+        const recipe = COMPOSE_INFRA[service.kind];
+        lines.push(`  ${service.kind}:`);
+        lines.push(`    image: ${service.image}`);
+        lines.push(`    mem_limit: ${service.memoryMiB}m`);
+        lines.push(`    memswap_limit: ${service.memoryMiB}m`);
+        lines.push('    cpus: 1');
+        lines.push('    ports:');
+        lines.push(`      - "127.0.0.1:${service.hostPort}:${service.containerPort}"`);
+        const environment = composeEnvironment(plan.name, service.kind);
+        if (environment.length > 0) {
+            lines.push('    environment:');
+            for (const [key, value] of environment)
+                lines.push(`      ${key}: ${value}`);
+        }
+        // a JSON array is a valid YAML flow sequence — exec-form healthchecks, no quoting surprises
+        lines.push('    healthcheck:');
+        lines.push(`      test: ${JSON.stringify(recipe.healthcheck(composeUser(plan.name, service.kind)))}`);
+        lines.push('      interval: 2s');
+        lines.push('      timeout: 5s');
+        lines.push('      retries: 30');
+        if (service.volume !== null) {
+            lines.push('    volumes:');
+            lines.push(`      - "\${VOLTER_WORLD_DATA:?}/${service.volume}:${recipe.volumePath}"`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** Parse one dotenv-ish file into ordered NAME/value pairs. Deliberately conservative: the same
+ * `NAME=` line shape `projectEnvNames` detects, plus quote stripping, so the two views of a repo's
+ * env agree on which names exist. */
+function parseEnvFile(text, source) {
+    const entries = [];
+    for (const line of text.split(/\r?\n/)) {
+        const match = line.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=(.*)$/);
+        if (!match)
+            continue;
+        let value = match[2].trim();
+        if ((value.startsWith('"') && value.endsWith('"') && value.length >= 2)
+            || (value.startsWith("'") && value.endsWith("'") && value.length >= 2)) {
+            value = value.slice(1, -1);
+        }
+        else {
+            // Unquoted: a `#` after whitespace opens a trailing comment (dotenv semantics). Without this
+            // a line like `NEXTAUTH_URL=http://localhost:3000 # dev` yields a value with the comment
+            // still attached, and every consumer that URL-parses it fails at runtime.
+            const comment = value.search(/\s#/);
+            if (comment !== -1)
+                value = value.slice(0, comment).trimEnd();
+        }
+        entries.push({ name: match[1], value, source });
+    }
+    return entries;
+}
+/** Every example-env entry in the repo, first definition winning, in a deterministic order:
+ * root before workspace members (sorted), and within a dir the ENV_SOURCE_FILES priority. */
+function repoEnvEntries(repo) {
+    const seen = new Set();
+    const entries = [];
+    for (const dir of projectManifestDirs(repo)) {
+        for (const file of ENV_SOURCE_FILES) {
+            const path = resolve(dir, file);
+            if (!existsSync(path))
+                continue;
+            const source = relative(repo, path) || file;
+            for (const entry of parseEnvFile(readFileSync(path, 'utf8'), source)) {
+                if (seen.has(entry.name))
+                    continue;
+                seen.add(entry.name);
+                entries.push(entry);
+            }
+        }
+    }
+    return entries;
+}
+// ---------------------------------------------------------------------------------------------
+// Planning
+// ---------------------------------------------------------------------------------------------
+function assertSafeName(name) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) {
+        throw new Error(`volter-world init: invalid world name "${name}" (letters, digits, then . _ -)`);
+    }
+}
+/** Is `candidate` inside `parent` (or the same dir)? The pristine-repo guard. */
+function isInside(parent, candidate) {
+    const rel = relative(resolve(parent), resolve(candidate));
+    return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel));
+}
+export function planWorldInit(name, repoPath, options = {}) {
+    assertSafeName(name);
+    const repo = resolve(repoPath);
+    if (!existsSync(repo))
+        throw new Error(`volter init: the application repo does not exist: ${repo}`);
+    const root = resolve(options.root ?? repo);
+    // The world lives in the app repo: `.volter/world.json` beside the code, committed like a
+    // compose file (docs/concepts/worlds.md#the-config-and-the-running-world). It holds no secret and no
+    // minted material (credential-shaped names carry `twin-fake-…` scalars; a name whose value
+    // must be a real key carries `$mint`, minted at boot into the ignored live env), so the tree is
+    // safe to `git add -A`. `--out` still emits a pilot elsewhere.
+    const out = resolve(options.out ?? resolve(repo, stateDirName()));
+    const configPath = resolve(out, 'world.json');
+    const existing = options.force && existsSync(configPath) ? loadWorldConfig(configPath, root).config : undefined;
+    if (existing?.manifestVersion === 1) {
+        throw new Error(`volter init: ${configPath} uses legacy format 1; run \`volter-world migrate-config ${configPath}\` before regenerating it`);
+    }
+    const selection = options.vendors
+        ? { include: options.vendors.map((vendor) => ({ vendor })), exclude: [] }
+        : existing?.selection ?? DEFAULT_WORLD_SELECTION;
+    const inRepo = isInside(repo, out);
+    /** a path the config carries: relative to the world root when the config lives under it
+     *  (portable between teammates), absolute otherwise (a pilot emitted away from its root) */
+    const carried = (path) => (isInside(root, path) ? relative(root, path) : path);
+    const catalogSource = resolveCatalog(root);
+    const catalog = new Set(catalogSource.vendors());
+    // Pack defaults (defaults/handlers.json, defaults/seed.ts): copied VISIBLY into the world
+    // dir — the author's to edit or delete (copy = ownership; never baked into the pack).
+    const defaultsCopies = [];
+    const signals = options.vendors ? null : detectRepoVendors(repo);
+    const detected = options.vendors
+        ? new Map(options.vendors.map((v) => [v, ['--twins']]))
+        : new Map([...signals.detected].filter(([vendor]) => (signals.uses.get(vendor) ?? []).some((use) => worldSelectionIncludes(selection, vendor, use.usage))));
+    const unknown = options.vendors
+        ? new Map()
+        : new Map([...signals.unknown].filter(([vendor]) => (signals.unknownUses.get(vendor) ?? []).some((use) => worldSelectionIncludes(selection, vendor, use.usage))));
+    const vendors = [];
+    const services = [];
+    const existingIds = new Set(existing?.services.map((service) => service.id) ?? []);
+    /** endpoint env name → the service that already claims it */
+    const claimedEnv = new Map();
+    const endpointNames = (service) => [...new Set([
+            ...(service.injectEnv ? [service.injectEnv] : []),
+            ...Object.keys(service.injectEnvTemplates ?? {}),
+            ...Object.keys(service.cliRedirect ?? {}),
+            ...(service.external?.discover?.map((mapping) => mapping.as) ?? []),
+        ])];
+    for (const service of existing?.services ?? []) {
+        for (const name of endpointNames(service))
+            claimedEnv.set(name, service.id);
+    }
+    for (const vendor of [...detected.keys()].sort()) {
+        const detectedVia = [...(detected.get(vendor) ?? [])].sort();
+        if (!catalog.has(vendor)) {
+            vendors.push({
+                vendor,
+                pack: null,
+                detectedVia,
+                wiring: 'no-pack',
+                service: null,
+                note: `no packages/twin/${vendor} pack in this catalog — the proof reports it MISSING until one exists.`,
+            });
+            continue;
+        }
+        const wiring = wiringFor(vendor);
+        // Two packs can want the SAME endpoint env. One world cannot point
+        // that var at two twins, so the first claimant keeps it and the second
+        // is emitted WITHOUT it — which the proof then reports UNINTERCEPTABLE. Silently letting the
+        // later service overwrite the var would send one vendor's traffic to the other's twin.
+        const claimant = wiring.injectEnv !== undefined ? claimedEnv.get(wiring.injectEnv) : undefined;
+        const conflict = claimant === vendor ? undefined : claimant;
+        const injectEnv = conflict === undefined ? wiring.injectEnv : undefined;
+        if (injectEnv !== undefined && !existingIds.has(vendor))
+            claimedEnv.set(injectEnv, vendor);
+        const note = conflict === undefined
+            ? wiring.note
+            : `${wiring.note} CONFLICT: ${wiring.injectEnv} is already claimed by the "${conflict}" service, so this twin is emitted `
+                + `without it — one world cannot point ${wiring.injectEnv} at two twins. Decide which vendor that var serves, or run them in separate worlds.`;
+        const packDir = catalogSource.packDir(vendor);
+        const defaultsHandlersPath = join(packDir, 'defaults', 'handlers.json');
+        const handlersTo = existsSync(defaultsHandlersPath) ? resolve(out, 'handlers', `${vendor}.json`) : null;
+        if (handlersTo !== null)
+            defaultsCopies.push({ vendor, kind: 'handlers', from: defaultsHandlersPath, to: handlersTo });
+        const handlersArg = handlersTo === null ? null : carried(handlersTo);
+        const defaultsSeedPath = join(packDir, 'defaults', 'seed.ts');
+        if (existsSync(defaultsSeedPath))
+            defaultsCopies.push({ vendor, kind: 'seed', from: defaultsSeedPath, to: resolve(out, 'seeds', 'defaults', `${vendor}.ts`) });
+        // COLOCATION (runtime contract R2a): a pack whose serve factory is known (derived into the
+        // pack-facts artifact) is emitted with `colocate`, so `up` boots it inside the ONE
+        // volter-world-host process instead of spawning a process per twin. The spawn `command`
+        // stays alongside as the process-isolation path. A service carrying a --scenario file
+        // keeps the spawn path for now: the colocate factory contract has no scenarioPath yet,
+        // and silently dropping the world's handlers would be a fake success.
+        // A service carrying a handlers file colocates too (R2a): the colocate contract carries
+        // `scenarioPath` and the host hands it to the factory — the same file the spawn path passes
+        // as --scenario.
+        const serveExport = packFacts()[vendor]?.serveExport;
+        // In an app repo the twin is a PACKAGE, resolved from the world root at boot (hoisting-proof);
+        // inside this checkout it is the checkout-relative path, as the cookbook and the gates expect.
+        const boot = catalogSource.kind === 'installed'
+            ? {
+                package: twinPackageName(vendor),
+                ...(handlersArg !== null ? { args: ['--scenario', handlersArg] } : {}),
+                ...(serveExport !== undefined ? { colocate: { export: serveExport, ...(handlersArg !== null ? { scenarioPath: handlersArg } : {}) } } : {}),
+            }
+            : {
+                command: 'bun',
+                args: [`packages/twin/${vendor}/src/cli.ts`, 'serve', ...(handlersArg !== null ? ['--scenario', handlersArg] : [])],
+                ...(serveExport !== undefined ? { colocate: { module: `./packages/twin/${vendor}/src/index.ts`, export: serveExport, ...(handlersArg !== null ? { scenarioPath: handlersArg } : {}) } } : {}),
+            };
+        const service = {
+            '//': note,
+            id: vendor,
+            type: 'twin',
+            ...boot,
+            // R17 — the pin: the package version this world was born against (its package.json).
+            ...(catalogSource.version(vendor) !== undefined ? { version: catalogSource.version(vendor) } : {}),
+            port: 'auto',
+            ...(injectEnv === undefined ? {} : { injectEnv }),
+            ...(conflict === undefined && wiring.injectEnvTemplates ? { injectEnvTemplates: wiring.injectEnvTemplates } : {}),
+            ...(conflict === undefined && wiring.cliRedirect ? { cliRedirect: wiring.cliRedirect } : {}),
+            ...(wiring.serviceEnv ? { env: wiring.serviceEnv } : {}),
+        };
+        if (existing !== undefined && !existingIds.has(vendor)) {
+            // Check the complete proposed bindings, including any that the fresh-init conflict path
+            // would otherwise omit. Regeneration must refuse before touching the saved World.
+            const proposal = { ...service, injectEnv: wiring.injectEnv, injectEnvTemplates: wiring.injectEnvTemplates, cliRedirect: wiring.cliRedirect };
+            for (const name of endpointNames(proposal)) {
+                const owner = claimedEnv.get(name);
+                if (owner !== undefined && owner !== vendor) {
+                    throw new Error(`volter init: service "${vendor}" conflicts with "${owner}" on endpoint variable ${name}; edit the World config to resolve ownership before regenerating`);
+                }
+            }
+        }
+        if (!existingIds.has(vendor))
+            for (const name of endpointNames(service))
+                claimedEnv.set(name, vendor);
+        services.push(service);
+        const savedService = existing?.services.find((entry) => entry.id === vendor);
+        vendors.push({
+            vendor,
+            pack: vendor,
+            detectedVia,
+            wiring: savedService !== undefined ? 'explicit-config' : conflict === undefined ? wiring.wiring : 'explicit-config',
+            service: savedService ?? service,
+            note: savedService !== undefined ? `Retained saved service "${vendor}" and its configured bindings.` : note,
+        });
+    }
+    // --- env ------------------------------------------------------------------------------------
+    const env = {};
+    const envRows = [];
+    const envSources = [];
+    const bootRisks = [];
+    const envReads = projectEnvReads(repo);
+    const mintedEnv = [];
+    const infraSignals = new Map();
+    const infraEntries = [];
+    // Every name a twin service above injects at boot (its endpoint env and templates).
+    const worldInjected = new Set([
+        ...(existing?.services ?? []),
+        ...services.filter((service) => !existingIds.has(service.id)),
+    ].flatMap(endpointNames));
+    for (const entry of repoEnvEntries(repo)) {
+        if (!envSources.includes(entry.source))
+            envSources.push(entry.source);
+        const { name, value, source } = entry;
+        // World-owned names: the world INJECTS these at boot from the services above. Carrying a repo's
+        // stale copy would shadow the live one.
+        if (/_TWIN_URL$/.test(name) || /^VOLTER_/.test(name) || worldInjected.has(name)) {
+            envRows.push({ name, disposition: 'unknown', source, reason: 'world-owned (injected at boot) — dropped from the emitted env' });
+            continue;
+        }
+        // STRUCTURED credential shapes first: `GOOGLE_VERTEX_JSON` / `GOOGLE_API_CREDENTIALS` carry a
+        // whole JSON document the client SDK PARSES (and signs with) before any request leaves the
+        // process, and neither name ends in a credential SUFFIX — so the suffix heuristics below are
+        // structurally blind to exactly the credentials that must be faked most carefully. `fakeEnvValue`
+        // already knows both shapes; this asks it the same question it answers.
+        if (isGoogleServiceAccountEnvName(name) || isGoogleOAuthClientEnvName(name)) {
+            const minted = isGoogleServiceAccountEnvName(name);
+            // A value that must carry a REAL (throwaway) private key is never written into the config:
+            // `$mint` is minted per boot into the live env only (docs/concepts/worlds.md
+            // #the-config-and-the-running-world), which is what keeps init byte-deterministic and the committed tree key-free.
+            env[name] = minted ? MINT_ENV : fakeEnvValue(name);
+            if (minted)
+                mintedEnv.push(name);
+            envRows.push({
+                name,
+                disposition: 'faked',
+                source,
+                reason: minted
+                    ? 'Google service-account JSON — `$mint`: up mints a structurally valid fake with a throwaway RSA key the SDK can genuinely sign with, into the live env only'
+                    : 'Google OAuth client JSON — structurally valid fake (the {"web":{…}} shape the consumer parses)',
+            });
+            continue;
+        }
+        const vendor = envNameVendor(name);
+        if (vendor !== null) {
+            env[name] = fakeEnvValue(name);
+            envRows.push({ name, disposition: 'faked', source, reason: `${vendor} credential` });
+            continue;
+        }
+        const infraKind = infraKindFor(name, value);
+        if (infraKind !== null) {
+            // DEFERRED: the value depends on whether this kind gets a compose service (a URL pointing
+            // at it) or stays a documented placeholder — decided below, once every signal is in.
+            infraSignals.set(infraKind, [...(infraSignals.get(infraKind) ?? []), name]);
+            infraEntries.push({ name, source, kind: infraKind });
+            continue;
+        }
+        // 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)) {
+            env[name] = fakeEnvValue(name);
+            envRows.push({ name, disposition: 'faked', source, reason: 'credential-shaped name — the example value is never copied' });
+            continue;
+        }
+        if (value !== '') {
+            env[name] = value;
+            envRows.push({ name, disposition: 'kept', source, reason: 'non-secret app config — copied verbatim' });
+            continue;
+        }
+        // declared, not set: an empty value, set, would win over the app's own env files (Next.js and dotenv never let a
+        // file override a set variable), so the key is recorded for the report and the env file, and left unset
+        const readAt = envReads.get(name) ?? [];
+        if (readAt.length > 0) {
+            bootRisks.push({ name, source, readAt });
+            envRows.push({
+                name,
+                disposition: 'unknown',
+                source,
+                reason: `BOOT RISK — empty in the example but read by production source at ${readAt.join(', ')}; the app may reject it before listening`,
+                unset: true,
+            });
+        }
+        else {
+            envRows.push({ name, disposition: 'unknown', source, reason: 'empty in the example and not credential-shaped — you decide', unset: true });
+        }
+    }
+    // --- native frontends ------------------------------------------------------------------------
+    // A detected native connection (Prisma over mysql://) that a SELECTED twin serves as a native
+    // frontend of its own state (the descriptor's `nativeTransport`) is that twin, not managed
+    // infrastructure: a separate database would split the state the app reads through the vendor's
+    // HTTP client from the state it writes natively — the two-client bug this exists to prevent.
+    for (const [kind, signals] of [...infraSignals.entries()]) {
+        const owner = vendors.find((entry) => entry.service !== null && packFacts()[entry.vendor]?.nativeTransport?.protocol === kind);
+        if (owner === undefined || owner.service === null)
+            continue;
+        const native = packFacts()[owner.vendor].nativeTransport;
+        const id = `${owner.vendor}-${kind}`;
+        const frontend = {
+            '//': `${owner.vendor}'s native ${kind} frontend: the same state as the "${owner.vendor}" twin over the ${kind} wire protocol (declare the HTTP twin first; it reads ${native.upstreamEnv} from it).`,
+            id,
+            type: 'twin',
+            ...(catalogSource.kind === 'installed'
+                ? { package: twinPackageName(owner.vendor), args: [native.flag] }
+                : { command: 'bun', args: [`packages/twin/${owner.vendor}/src/cli.ts`, 'serve', native.flag] }),
+            ...(catalogSource.version(owner.vendor) !== undefined ? { version: catalogSource.version(owner.vendor) } : {}),
+            port: 'auto',
+            injectEnvTemplates: Object.fromEntries([...signals].sort().map((name) => [name, `${kind}://twin:twin@${'${host}'}:${'${port}'}/twin`])),
+        };
+        services.splice(services.indexOf(owner.service) + 1, 0, frontend);
+        for (const entry of infraEntries.filter((candidate) => candidate.kind === kind)) {
+            envRows.push({ name: entry.name, disposition: 'unknown', source: entry.source, reason: `${kind} connection string — injected at boot by the "${id}" twin service (${owner.vendor}'s native frontend over the same state)` });
+        }
+        infraSignals.delete(kind);
+        infraEntries.splice(0, infraEntries.length, ...infraEntries.filter((candidate) => candidate.kind !== kind));
+    }
+    // --- infra ----------------------------------------------------------------------------------
+    // Kinds with a managed recipe get a private definition next to the config, a declared external
+    // service whose lifecycle belongs to World, and env URLs pointing at it. Recipe-less kinds keep
+    // the documented placeholder + `//infra` stub.
+    const takenPorts = new Set();
+    const compose = [...infraSignals.entries()]
+        .filter(([kind]) => COMPOSE_INFRA[kind] !== undefined)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([kind, signals]) => composeService(name, kind, [...signals].sort(), takenPorts));
+    const composeByKind = new Map(compose.map((service) => [service.kind, service]));
+    for (const entry of infraEntries) {
+        const composed = composeByKind.get(entry.kind);
+        if (composed !== undefined) {
+            env[entry.name] = composed.url;
+            envRows.push({
+                name: entry.name,
+                disposition: 'compose',
+                source: entry.source,
+                reason: `${entry.kind} connection string — points at the World-managed infrastructure service`,
+            });
+        }
+        else {
+            env[entry.name] = INFRA_PLACEHOLDER[entry.kind] ?? 'REPLACE_ME';
+            envRows.push({ name: entry.name, disposition: 'placeholder', source: entry.source, reason: `${entry.kind} connection string — no twin models it; point it at your own local instance` });
+        }
+    }
+    const infra = [...infraSignals.entries()]
+        .filter(([kind]) => !composeByKind.has(kind))
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([kind, signals]) => ({
+        kind,
+        signals: [...signals].sort(),
+        stub: {
+            description: `${signals.sort().join(', ')} signal${signals.length > 1 ? '' : 's'} ${kind}, which no twin models. `
+                + `Fill in the up/status/down commands for YOUR local ${kind} service, `
+                + 'then MOVE this object into "services" so `volter-world up`/`down` own its lifecycle. '
+                + 'Add `bindings.discover` entries if the tool prints the connection URL; otherwise keep the placeholder in the env file. '
+                + 'See docs/concepts/worlds.md § the external service type.',
+            id: kind,
+            type: 'external',
+            execution: {
+                lifecycle: {
+                    up: ['REPLACE_ME'],
+                    status: ['REPLACE_ME'],
+                    down: ['REPLACE_ME'],
+                },
+            },
+        },
+    }));
+    // `//infra` is a documented, runtime-ignored sidecar rather than a `services` entry ON PURPOSE:
+    // an `external` service with placeholder commands passes no schema check worth having and would
+    // make `up` fail on a config init just told the operator to boot. Stubs sit outside `services`
+    // until they are real.
+    if (compose.length > 0) {
+        if (existingIds.has('infrastructure')) {
+            throw new Error('volter init: new infrastructure requires changes to the saved infrastructure service and world.infrastructure.yml; edit them together before regenerating');
+        }
+        services.push({
+            '//': `World-managed infrastructure (${compose.map((service) => service.kind).join(', ')}); lifecycle and diagnostics stay behind this declared service boundary.`,
+            id: 'infrastructure',
+            type: 'external',
+            controlPlane: true,
+            external: {
+                up: ['volter-world-infra', 'up'],
+                status: ['volter-world-infra', 'status'],
+                discover: compose.flatMap((service) => service.signals.map((name) => ({ as: name, jsonPath: `connections.${name}` }))),
+                down: ['volter-world-infra', 'down'],
+                readyWhen: { command: 'volter-world-infra', args: ['status'], timeoutMs: 120000, intervalMs: 500 },
+            },
+        });
+    }
+    const mergedServices = existing === undefined ? services : [...existing.services, ...services.filter((service) => !existingIds.has(service.id))];
+    if (existing !== undefined) {
+        const owners = new Map();
+        for (const service of mergedServices) {
+            for (const name of endpointNames(service)) {
+                const owner = owners.get(name);
+                if (!existingIds.has(service.id) && owner !== undefined && owner !== service.id) {
+                    throw new Error(`volter init: service "${service.id}" conflicts with "${owner}" on endpoint variable ${name}; edit the World config to resolve ownership before regenerating`);
+                }
+                owners.set(name, service.id);
+            }
+        }
+    }
+    // an empty value an earlier init wrote is dropped: an empty example key is declared and left unset, not set to nothing
+    const mergedEnv = Object.fromEntries(Object.entries({ ...env, ...(existing?.env ?? {}) }).filter(([, value]) => value !== '').sort(([a], [b]) => a.localeCompare(b)));
+    const comments = Object.fromEntries(Object.entries(existing ?? {}).filter(([key]) => key.startsWith('//')));
+    const savedInfra = comments['//infra'];
+    if (savedInfra !== undefined && !Array.isArray(savedInfra) && infra.length > 0) {
+        throw new Error('volter init: cannot merge new infrastructure stubs into a non-array //infra; edit the World config before regenerating');
+    }
+    const savedInfraIds = new Set(Array.isArray(savedInfra)
+        ? savedInfra.flatMap((stub) => stub !== null && typeof stub === 'object' && 'id' in stub ? [stub.id] : [])
+        : []);
+    const mergedInfra = [
+        ...(Array.isArray(savedInfra) ? savedInfra : []),
+        ...infra.filter((entry) => !savedInfraIds.has(entry.stub.id)).map((entry) => entry.stub),
+    ];
+    const config = {
+        ...comments,
+        id: name,
+        manifestVersion: 2,
+        selection,
+        ...(existing?.bare ? { bare: existing.bare } : options.bare ? { bare: { name: options.bare } } : {}),
+        // THE BIRTH STAMP (architecture gap #2, ratified): the catalog version this world was
+        // created under. Replay/upgrade decisions are impossible to make honestly without it,
+        // and retrofitting provenance later is the expensive version. 'unknown' only when the
+        // checkout is not a git tree (an installed package) — still a fact, recorded.
+        // (sha only — init's output is BYTE-DETERMINISTIC by contract, so no wall-clock here;
+        // the serverless provision door, an operator act, stamps createdAt on its side.)
+        // …and the platform protocol major the world is born under (R18): `up` reads it back and
+        // refuses a world this platform can no longer read by construction.
+        catalog: existing?.catalog ?? { sha: catalogSource.sha(), protocol: String(PROTOCOL_MAJOR) },
+        description: existing?.description ?? `World generated by \`volter init\`: selected external vendors the application talks to, `
+            + `fake credentials, and documented stubs for the infra it signals. Regenerate with \`volter init\` — do not hand-edit `
+            + `what init can re-derive; DO fill in the //infra stubs and move them into "services".`,
+        // What a world of twins reserves: ledgers are megabytes, and a branch is another world on the
+        // same box, so the reservation is sized for many worlds side by side, not for one.
+        // One twin process per WORLD, not per vendor (runtime contract R2a): every colocatable
+        // service boots inside the volter-world-host. Local-mode preference only — share/sealed
+        // boots downgrade to per-process isolation (their TWIN-67 contract) in runtime.ts.
+        ...(existing?.isolation ? { isolation: existing.isolation } : mergedServices.some((s) => s.colocate !== undefined) ? { isolation: 'colocated' } : {}),
+        env: mergedEnv,
+        ...(existing?.stripEnv ? { stripEnv: existing.stripEnv } : {}),
+        ...(existing?.network ? { network: existing.network } : {}),
+        services: mergedServices,
+        ...(existing?.share ? { share: existing.share } : {}),
+        ...(existing?.remotes ? { remotes: existing.remotes } : {}),
+        ...(existing?.actors ? { actors: existing.actors } : {}),
+        ...(existing?.fixtures ? { fixtures: existing.fixtures } : {}),
+        ...(mergedInfra.length ? { '//infra': mergedInfra } : {}),
+    };
+    return {
+        name,
+        repo,
+        out,
+        inRepo,
+        catalog: catalogSource.kind,
+        configPath,
+        envPath: resolve(out, 'app.env'),
+        defaultsCopies,
+        seedAdditions: existsSync(resolve(out, 'seed.ts'))
+            ? defaultsCopies.filter((copy) => copy.kind === 'seed' && !existingIds.has(copy.vendor)).map((copy) => ({
+                vendor: copy.vendor,
+                import: `import { seed as ${copy.vendor.replace(/[^a-zA-Z0-9]/g, '_')}Defaults } from './seeds/defaults/${copy.vendor}.ts';`,
+                call: `await ${copy.vendor.replace(/[^a-zA-Z0-9]/g, '_')}Defaults();`,
+            }))
+            : [],
+        seedEntry: defaultsCopies.some((c) => c.kind === 'seed')
+            ? { entryPath: resolve(out, 'seed.ts'), storyPath: resolve(out, 'seeds', 'story.ts') }
+            : null,
+        config,
+        env: config.env,
+        vendors,
+        envRows,
+        envSources,
+        bootRisks: [...bootRisks].sort((a, b) => a.name.localeCompare(b.name)),
+        infra,
+        compose,
+        composePath: compose.length > 0 ? resolve(out, 'world.infrastructure.yml') : null,
+        // Standing registry acknowledgments leave the worklist but never vanish (each keeps its
+        // recorded reason) — the same partition coverWorld's proof applies to the same signals.
+        unknown: [...unknown.keys()].filter((name) => registryAcknowledgedReason(name) === null).sort(),
+        acknowledgedExternal: [...unknown.keys()]
+            .map((name) => ({ name, reason: registryAcknowledgedReason(name) }))
+            .filter((row) => row.reason !== null)
+            .sort((a, b) => a.name.localeCompare(b.name)),
+        mintedEnv: [...mintedEnv].sort(),
+    };
+}
+// ---------------------------------------------------------------------------------------------
+// Emission
+// ---------------------------------------------------------------------------------------------
+/** 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 function renderEnvFile(plan) {
+    const byName = new Map(plan.envRows.map((row) => [row.name, row]));
+    const lines = [
+        `# ${plan.name} — env for the world, generated by \`volter init\`.`,
+        '# Credential-shaped names hold FAKE values (a twin accepts any bearer token; names an SDK parses',
+        '# get a structurally valid fake). Values copied from the repo\'s example env are non-secret app',
+        '# config only. Infra URLs are placeholders — point them at your own local services.',
+        '# This file mirrors runtime.environment.values in world.json, which is what `volter up` injects.',
+        ...(plan.mintedEnv.length
+            ? [
+                '#',
+                `# ${plan.mintedEnv.join(', ')} ${plan.mintedEnv.length === 1 ? 'is' : 'are'} \`$mint\`: up mints a throwaway private key for`,
+                '# each boot into the live env (world.env) only — never into this file or the config.',
+            ]
+            : []),
+        '',
+    ];
+    for (const name of Object.keys(plan.env).sort()) {
+        const row = byName.get(name);
+        if (row)
+            lines.push(`# ${row.disposition}: ${row.reason}`);
+        const value = plan.env[name];
+        // A value with a newline (a service-account JSON) or a leading/trailing space must be quoted to
+        // survive any dotenv reader; JSON.stringify gives exactly the escaping every one of them accepts.
+        lines.push(`${name}=${/[\n"']/.test(value) || value !== value.trim() ? JSON.stringify(value) : value}`);
+    }
+    const declared = plan.envRows.filter((row) => row.unset === true && !(row.name in plan.env)).sort((a, b) => a.name.localeCompare(b.name));
+    if (declared.length) {
+        lines.push('', "# Declared by the repo's example env with no value, and left unset: the app's own env files provide them.");
+        for (const row of declared)
+            lines.push(`# ${row.disposition}: ${row.reason}`, `# ${row.name}=`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** 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 const STATE_GITIGNORE = `# Volter: the world's running state and live env — never committed. world.json, handlers/ and seeds/ are the story.
+worlds/
+current
+*.env
+credentials/
+token
+`;
+export function writeWorldInit(plan, options = {}) {
+    // A world already here is refused unless forced; a `.volter/` holding only running state
+    // (worlds/, an env) is not a world and does not block init.
+    if (existsSync(plan.configPath) && options.force !== true) {
+        throw new Error(`volter init: a world already exists at ${plan.configPath}. `
+            + 'Pass --force to regenerate it, or --out <dir> to emit elsewhere.');
+    }
+    mkdirSync(plan.out, { recursive: true });
+    writeFileSync(plan.configPath, `${JSON.stringify(worldConfigDocument(plan.config), null, 2)}\n`);
+    if (plan.inRepo)
+        writeFileSync(join(plan.out, '.gitignore'), STATE_GITIGNORE);
+    writeFileSync(plan.envPath, renderEnvFile(plan));
+    if (plan.composePath !== null)
+        writeFileSync(plan.composePath, renderComposeFile(plan));
+    // Pack defaults, copied byte-for-byte into the world dir. Ownership transfers on copy: these
+    // are the author's files now (edit or delete; regenerate a fresh world for fresh defaults).
+    for (const copy of plan.defaultsCopies) {
+        mkdirSync(dirname(copy.to), { recursive: true });
+        if (!(options.force === true && existsSync(copy.to)))
+            writeFileSync(copy.to, readFileSync(copy.from));
+    }
+    if (plan.seedEntry !== null) {
+        mkdirSync(dirname(plan.seedEntry.storyPath), { recursive: true });
+        if (!(options.force === true && existsSync(plan.seedEntry.storyPath))) {
+            writeFileSync(plan.seedEntry.storyPath, `// Your world's STORY — the cross-vendor narrative (the only seed you write).\n`
+                + `// Seed state through each vendor's ORDINARY SDK/API pointed at its *_TWIN_URL.\n`
+                + `export async function story(): Promise<void> {\n  // e.g. post the opening support thread, create the incident, ...\n}\n`);
+        }
+        const seedImports = plan.defaultsCopies.filter((c) => c.kind === 'seed');
+        if (!existsSync(plan.seedEntry.entryPath))
+            writeFileSync(plan.seedEntry.entryPath, `// THE seed entry point — composes order VISIBLY (no magic globbing): defaults, then story.\n`
+                + `// This is the world's DEFAULT DATA: \`volter up\` runs it after every boot (--no-seed skips it)\n`
+                + `// and \`volter reset\` returns to it. While it runs every twin records what it creates as\n`
+                + `// data that was already there — the log stays empty and nothing is pending.\n`
+                + `// It runs from your app's directory, so its node_modules resolve any vendor SDK a seed imports.\n`
+                + seedImports.map((c) => `import { seed as ${c.vendor.replace(/[^a-zA-Z0-9]/g, '_')}Defaults } from './seeds/defaults/${c.vendor}.ts';`).join('\n')
+                + `\nimport { story } from './seeds/story.ts';\n\n`
+                + seedImports.map((c) => `await ${c.vendor.replace(/[^a-zA-Z0-9]/g, '_')}Defaults();`).join('\n')
+                + `\nawait story();\n`);
+    }
+}
+/**
+ * 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 function initWorld(name, repoPath, options = {}) {
+    const plan = planWorldInit(name, repoPath, options);
+    writeWorldInit(plan, { force: options.force ?? false });
+    const proof = coverWorld(plan.configPath, plan.repo, {
+        root: resolve(options.root ?? process.cwd()),
+        allowUnknown: options.allowUnknown ?? false,
+        acknowledge: options.acknowledge ?? {},
+    });
+    // The proof was addressed BY PATH (so it reads the bytes just written, not the in-memory plan);
+    // report it under the world's id, which is what every other verb takes.
+    const coverage = { ...proof, world: plan.name };
+    const next = plan.inRepo && resolve(options.root ?? plan.repo) === plan.repo
+        ? [
+            'volter world up   # starts the twins and loads the default data; the live env lands in .volter/world.env',
+            "volter world run -- <your app's dev command>   # the app sees the twins as the vendors",
+            'volter world log   # every write the app made',
+            'volter world down',
+        ]
+        : [
+            `volter-world up ${plan.configPath} --name ${plan.name} --env-file=${resolve(plan.out, 'world.env')}   # up WRITES the live env (twin URLs) there; app.env is init's static preview of the same map`,
+            ...(plan.seedEntry === null ? [] : [`volter-world seed ${plan.name} --cwd ${plan.repo}   # load the default data AFTER every up: it lands as data that was already there, the log empty; reset = down, up, seed`]),
+            `volter-world env ${plan.name} -- <your app's dev command>   # run the app inside the world`,
+            `volter-world down ${plan.name}`,
+        ];
+    return { plan, coverage, ok: coverage.ok, next };
+}
+// ---------------------------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------------------------
+function table(header, rows) {
+    const widths = header.map((title, column) => Math.max(title.length, ...rows.map((row) => row[column].length)));
+    const render = (row) => row.map((cell, column) => cell.padEnd(widths[column])).join(' | ').trimEnd();
+    return [render(header), widths.map((width) => '-'.repeat(width)).join('-|-'), ...rows.map(render)];
+}
+export function formatInitReport(result) {
+    const { plan } = result;
+    const lines = [];
+    lines.push(`World  ${plan.name}`);
+    if (plan.inRepo) {
+        lines.push(`App    ${plan.repo}`);
+        lines.push(`Config ${plan.configPath}   (commit .volter/ — the story; its .gitignore keeps the running state out)`);
+    }
+    else {
+        lines.push(`Repo   ${plan.repo} (unmodified — nothing was written here)`);
+        lines.push(`Config ${plan.configPath}`);
+    }
+    lines.push(`Env    ${plan.envPath}   (a dotenv preview of the config's env; \`up\` writes the live one)`);
+    if (plan.composePath !== null)
+        lines.push(`Infra  World-managed (${plan.compose.length} service${plan.compose.length === 1 ? '' : 's'})`);
+    if (plan.infra.length > 0) {
+        // detected infra with no managed recipe must be SAID here, not only left
+        // as a stub the operator may never open — silence reads as provisioned
+        lines.push(`Infra  NOT World-managed: ${plan.infra.map((stub) => stub.kind).join(', ')} — fill in the //infra stub${plan.infra.length === 1 ? '' : 's'} in the config (env holds a placeholder until then)`);
+    }
+    lines.push('');
+    lines.push(`Vendors (${plan.vendors.length} detected, ${plan.vendors.filter((v) => v.service !== null).length} emitted):`);
+    if (plan.vendors.length === 0)
+        lines.push('  (no external vendor dependencies detected in the repo)');
+    else {
+        lines.push(...table(['vendor', 'wiring', 'inject-env', 'detected-via'], plan.vendors.map((vendor) => [
+            vendor.vendor,
+            vendor.wiring,
+            [vendor.service?.injectEnv, ...Object.keys(vendor.service?.injectEnvTemplates ?? {})].filter(Boolean).join(', ') || '-',
+            vendor.detectedVia.join('; '),
+        ])).map((line) => `  ${line}`));
+        for (const vendor of plan.vendors) {
+            if (vendor.wiring === 'injector')
+                continue; // the zero-edit default needs no explanation
+            lines.push(`  · ${vendor.vendor}: ${vendor.note}`);
+        }
+    }
+    lines.push('');
+    const counts = (disposition) => plan.envRows.filter((row) => row.disposition === disposition);
+    lines.push(`Env (${plan.envRows.length} name(s) from ${plan.envSources.join(', ') || 'no example env file'}):`);
+    for (const disposition of ['faked', 'kept', 'compose', 'placeholder', 'unknown']) {
+        const rows = counts(disposition);
+        if (rows.length === 0)
+            continue;
+        lines.push(`  ${disposition.padEnd(11)} ${String(rows.length).padStart(3)}  ${rows.map((row) => row.name).join(', ')}`);
+    }
+    if (plan.mintedEnv.length > 0) {
+        lines.push(`  (${plan.mintedEnv.join(', ')} hold${plan.mintedEnv.length === 1 ? 's' : ''} a freshly minted throwaway key — the only value(s) that change between runs)`);
+    }
+    if (plan.bootRisks.length > 0) {
+        lines.push('');
+        lines.push(`BOOT RISKS (${plan.bootRisks.length} empty example value(s) read by production source):`);
+        for (const risk of plan.bootRisks) {
+            lines.push(`  ${risk.name} — empty in ${risk.source}; read at ${risk.readAt.join(', ')}`);
+        }
+        lines.push('  Resolve these before expecting the app to listen. Vendor coverage can be green while the app rejects its own env.');
+    }
+    if (plan.compose.length > 0) {
+        lines.push('');
+        lines.push('Infrastructure (owned by the World lifecycle):');
+        for (const service of plan.compose) {
+            lines.push(`  ${service.kind}: ${service.image} on 127.0.0.1:${service.hostPort} — signalled by ${service.signals.join(', ')}; env URLs point at it`);
+        }
+    }
+    if (plan.infra.length > 0) {
+        lines.push('');
+        lines.push(`Infra stubs (documented under the config's "//infra" key — fill in and move into "services"):`);
+        for (const stub of plan.infra)
+            lines.push(`  ${stub.kind}: signalled by ${stub.signals.join(', ')}`);
+    }
+    if (plan.seedAdditions.length > 0) {
+        lines.push('', 'Existing seed.ts preserved. Add these default seeds in your chosen order:');
+        for (const addition of plan.seedAdditions)
+            lines.push(`  ${addition.import}`, `  ${addition.call}`);
+    }
+    lines.push('');
+    lines.push('--- coverage proof (init\'s exit code IS this proof\'s) ---');
+    lines.push(formatCoverageReport(result.coverage).trimEnd());
+    lines.push('');
+    if (result.ok && plan.bootRisks.length > 0) {
+        lines.push('COVERAGE READY; APP BOOT AT RISK — resolve the empty values above, then boot it yourself:');
+    }
+    else if (result.ok) {
+        lines.push('READY. Boot it yourself — init diagnoses, it does not boot:');
+    }
+    else {
+        lines.push('NOT READY — the worklist above is what stands between this pilot and a world that covers the repo.');
+        lines.push('Once it is green (or every remaining finding is --acknowledge\'d with a reason), boot it with:');
+    }
+    for (const command of result.next)
+        lines.push(`  ${command}`);
+    lines.push('');
+    lines.push('The two moves: if the twin stores it, create it through the vendor\'s own API (seed.ts,');
+    lines.push('as the person, clock first for history). Everything else — judgment, lookups, faults —');
+    lines.push('is a handler in handlers/<vendor>.json. Every twin explains itself at GET <url>/twin.');
+    return `${lines.join('\n')}\n`;
+}