@volter/twin-world 0.1.0 → 0.1.2

package/src/init.ts

@@ -0,0 +1,1142 @@
+// `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/twin/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 REPO STAYS PRISTINE. Output goes OUTSIDE `--repo` (default `<repo>/../<name>-pilot/`), and
+//     an `--out` that resolves inside the repo is refused. Adoption must never be something an app
+//     repo has to accept a commit for; a pilot you can `rm -rf` is the whole point.
+//  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 (QSTASH_URL, 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, readdirSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import {
+  coverWorld,
+  detectRepoVendors,
+  envNameVendor,
+  formatCoverageReport,
+  injectorEnvNameForKey,
+  injectorVendorKeysFor,
+  isCredentialShapedEnvName,
+  registryAcknowledgedReason,
+  type CoverageReport,
+} from './covers.ts';
+import { fakeEnvValue, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from './fixture-env.ts';
+import { projectEnvReads, projectManifestDirs } from './project-inspect.ts';
+import { overlayEndpointEnv, packFacts } from './pack-facts.ts';
+import type { WorldConfig, WorldServiceConfig } from './schema.ts';
+
+/** 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 (QSTASH_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 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;
+  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;
+  /**
+   * 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 twin pack catalog lives and where the emitted config will boot from */
+  root?: string;
+  out?: string;
+  force?: boolean;
+  allowUnknown?: boolean;
+  acknowledge?: Record<string, string>;
+};
+
+// ---------------------------------------------------------------------------------------------
+// The pack catalog
+// ---------------------------------------------------------------------------------------------
+
+/** The twin packs available at `root` — a pack is a `packages/twin/<name>/` dir with a `src/cli.ts`
+ * (the `serve` entrypoint every pack's `world-<name>` bin points at). Read from disk rather than a
+ * hard-coded list so a newly added pack is emittable the day it lands, and sorted so the catalog is
+ * a deterministic input. */
+export function packCatalog(root: string): string[] {
+  const packsDir = resolve(root, 'packages', 'twin');
+  if (!existsSync(packsDir)) {
+    throw new Error(
+      `volter-world init: no twin pack catalog at ${packsDir}. init emits services that run the packs from the world root, `
+      + `so --root must be a twin checkout (it defaults to the current directory).`,
+    );
+  }
+  return readdirSync(packsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(resolve(packsDir, entry.name, 'src', 'cli.ts')))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+// ---------------------------------------------------------------------------------------------
+// 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:
+ *
+ *   qstash / upstashworkflow  `QSTASH_URL` — `@upstash/qstash`'s documented base-URL override, and
+ *                             `@upstash/workflow`'s Client is literally `new QStashClient(config)`,
+ *                             so it reads the very same var (pack READMEs; both verified live).
+ *   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, svix, 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: Record<string, { injectEnv?: string; injectEnvTemplates?: Record<string, string>; note: string }> = {
+  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.',
+  },
+  rh2: {
+    injectEnv: 'RH2_BASE_URL',
+    note: 'no injector entry and none possible: an RH2 control plane has no fixed vendor host — it is wherever the operator deployed it. RH2\'s own first-party clients are base-URL-configured and read RH2_BASE_URL (@runhuman/sdk client.ts, @runhuman/cli), so pointing that one var at the twin is the whole interception for an unmodified SDK or CLI.',
+  },
+  qstash: {
+    injectEnv: 'QSTASH_URL',
+    note: 'no injector entry: @upstash/qstash is base-URL-configured — the SDK reads QSTASH_URL (verified live, pack README).',
+  },
+  upstashworkflow: {
+    injectEnv: 'QSTASH_URL',
+    note: 'no injector entry: @upstash/workflow\'s Client IS a QStash client, so it reads the same QSTASH_URL (pack README).',
+  },
+  // (inngest moved to its pack descriptor's `endpointEnv` — the TWIN-PACK-CONTRACT exemplar.)
+  '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.',
+  },
+};
+// TWIN-PACK-CONTRACT migration: 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: string): {
+  wiring: Exclude<InitWiring, 'no-pack'>;
+  injectEnv?: string;
+  injectEnvTemplates?: Record<string, string>;
+  cliRedirect?: Record<string, string>;
+  serviceEnv?: Record<string, string>;
+  note: string;
+} {
+  // 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 as [string, ...string[]];
+    return {
+      wiring: 'injector',
+      injectEnv: primary,
+      ...(rest.length ? { injectEnvTemplates: Object.fromEntries(rest.map((name) => [name, '${url}'])) } : {}),
+      ...(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: Record<string, string> = {
+  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: string): string | null {
+  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: string, value = ''): string | null {
+  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: Record<string, string> = {
+  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: Record<string, {
+  image: string;
+  containerPort: number;
+  memoryMiB: number;
+  /** the container path a named volume persists, or null for none */
+  volumePath: string | null;
+  /** healthcheck exec-form argv (makes `docker compose up -d --wait` meaningful) */
+  healthcheck: (user: string) => string[];
+}> = {
+  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: string): number {
+  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: string, kind: string, taken: Set<number>): number {
+  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: string): string {
+  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: string, kind: string): string {
+  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: string): string {
+  return `${name.toLowerCase().replace(/[^a-z0-9_-]/g, '-')}-infra`;
+}
+
+function composeService(name: string, kind: string, signals: string[], taken: Set<number>): InitComposeService {
+  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: string, kind: string): Array<[string, string]> {
+  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: InitPlan): string {
+  const lines: string[] = [
+    `# ${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`;
+}
+
+type ParsedEnvEntry = { name: string; value: string; source: string };
+
+/** 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: string, source: string): ParsedEnvEntry[] {
+  const entries: ParsedEnvEntry[] = [];
+  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: string): ParsedEnvEntry[] {
+  const seen = new Set<string>();
+  const entries: ParsedEnvEntry[] = [];
+  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: string): void {
+  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: string, candidate: string): boolean {
+  const rel = relative(resolve(parent), resolve(candidate));
+  return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel));
+}
+
+export function planWorldInit(name: string, repoPath: string, options: InitOptions = {}): InitPlan {
+  assertSafeName(name);
+  const root = resolve(options.root ?? process.cwd());
+  const repo = resolve(repoPath);
+  if (!existsSync(repo)) throw new Error(`volter-world init: --repo path does not exist: ${repo}`);
+  const out = resolve(options.out ?? resolve(repo, '..', `${name}-pilot`));
+  // RULE 1: the repo stays pristine. Emitting into it would make adoption a commit the app repo has
+  // to accept — and would put fake credentials inside a tree someone will `git add -A`.
+  if (isInside(repo, out)) {
+    throw new Error(
+      `volter-world init: --out ${out} is inside --repo ${repo}. init never writes into the application repo `
+      + `(the pilot is disposable and the repo stays pristine) — choose a directory outside it.`,
+    );
+  }
+
+  const catalog = new Set(packCatalog(root));
+  // 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: Array<{ vendor: string; kind: 'handlers' | 'seed'; from: string; to: string }> = [];
+  const { detected, unknown } = detectRepoVendors(repo);
+
+  const vendors: InitVendorPlan[] = [];
+  const services: WorldServiceConfig[] = [];
+  /** endpoint env name → the service that already claims it (QSTASH_URL is wanted by two packs) */
+  const claimedEnv = new Map<string, string>();
+  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 (qstash and upstashworkflow both read QSTASH_URL).
+    // 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 conflict = wiring.injectEnv !== undefined ? claimedEnv.get(wiring.injectEnv) : undefined;
+    const injectEnv = conflict === undefined ? wiring.injectEnv : undefined;
+    if (injectEnv !== undefined) 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 defaultsHandlersPath = join(root, 'packages', 'twin', vendor, '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 defaultsSeedPath = join(root, 'packages', 'twin', vendor, '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.
+    const serveExport = handlersTo === null ? packFacts()[vendor]?.serveExport : undefined;
+    const service: WorldServiceConfig = {
+      '//': note,
+      id: vendor,
+      type: 'twin',
+      command: 'bun',
+      args: [`packages/twin/${vendor}/src/cli.ts`, 'serve', ...(handlersTo !== null ? ['--scenario', handlersTo] : [])],
+      ...(serveExport !== undefined ? { colocate: { module: `./packages/twin/${vendor}/src/index.ts`, export: serveExport } } : {}),
+      port: 'auto',
+      ...(injectEnv === undefined ? {} : { injectEnv }),
+      ...(conflict === undefined && wiring.injectEnvTemplates ? { injectEnvTemplates: wiring.injectEnvTemplates } : {}),
+      ...(conflict === undefined && wiring.cliRedirect ? { cliRedirect: wiring.cliRedirect } : {}),
+      ...(wiring.serviceEnv ? { env: wiring.serviceEnv } : {}),
+    };
+    services.push(service);
+    vendors.push({
+      vendor,
+      pack: vendor,
+      detectedVia,
+      wiring: conflict === undefined ? wiring.wiring : 'explicit-config',
+      service,
+      note,
+    });
+  }
+
+  // --- env ------------------------------------------------------------------------------------
+  const env: Record<string, string> = {};
+  const envRows: InitEnvRow[] = [];
+  const envSources: string[] = [];
+  const bootRisks: InitBootRisk[] = [];
+  const envReads = projectEnvReads(repo);
+  const mintedEnv: string[] = [];
+  const infraSignals = new Map<string, string[]>();
+  const infraEntries: Array<{ name: string; source: string; kind: string }> = [];
+  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)) {
+      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)) {
+      env[name] = fakeEnvValue(name);
+      const minted = isGoogleServiceAccountEnvName(name);
+      if (minted) mintedEnv.push(name);
+      envRows.push({
+        name,
+        disposition: 'faked',
+        source,
+        reason: minted
+          ? 'Google service-account JSON — structurally valid fake with a freshly MINTED throwaway RSA key the SDK can genuinely sign with (the one value that differs between runs)'
+          : '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;
+    }
+    env[name] = '';
+    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`,
+      });
+    } else {
+      envRows.push({ name, disposition: 'unknown', source, reason: 'empty in the example and not credential-shaped — you decide' });
+    }
+  }
+
+  // --- 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<number>();
+  const compose: InitComposeService[] = [...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: InitInfraStub[] = [...infraSignals.entries()]
+    .filter(([kind]) => !composeByKind.has(kind))
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([kind, signals]) => ({
+      kind,
+      signals: [...signals].sort(),
+      stub: {
+        '//': `${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 `external.discover` entries if the tool prints the connection URL; otherwise keep the placeholder in the env file. '
+          + 'See WORLD.md § the external service type.',
+        id: kind,
+        type: 'external',
+        external: {
+          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) {
+    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-managed-infra', 'up'],
+        status: ['volter-world-managed-infra', 'status'],
+        down: ['volter-world-managed-infra', 'down'],
+        readyWhen: { command: 'volter-world-managed-infra', args: ['status'], timeoutMs: 120000, intervalMs: 500 },
+      },
+    });
+  }
+
+  const config: WorldConfig & { '//infra'?: unknown[]; catalog?: { sha: string } } = {
+    id: name,
+    // 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.)
+    catalog: { sha: catalogSha(root) },
+    description: `Pilot world generated by \`volter-world init\`: one twin per external vendor the application repo talks to, `
+      + `fake credentials, and documented stubs for the infra it signals. Regenerate with \`volter-world init\` — do not hand-edit `
+      + `what init can re-derive; DO fill in the //infra stubs and move them into "services".`,
+    resources: { memoryMiB: 2048, writableStorageMiB: 8192 },
+    // 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.
+    ...(services.some((s) => s.colocate !== undefined) ? { isolation: 'colocated' as const } : {}),
+    env: Object.fromEntries(Object.keys(env).sort().map((key) => [key, env[key]!])),
+    services,
+    ...(infra.length ? { '//infra': infra.map((entry) => entry.stub) } : {}),
+  };
+
+  return {
+    name,
+    repo,
+    out,
+    configPath: resolve(out, 'world.config.json'),
+    envPath: resolve(out, 'app.env'),
+    defaultsCopies,
+    seedEntry: defaultsCopies.some((c) => c.kind === 'seed')
+      ? { entryPath: resolve(out, 'seed.ts'), storyPath: resolve(out, 'seeds', 'story.ts') }
+      : null,
+    config,
+    env: config.env as Record<string, string>,
+    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 is { name: string; reason: string } => 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: InitPlan): string {
+  const byName = new Map(plan.envRows.map((row) => [row.name, row]));
+  const lines = [
+    `# ${plan.name} — env for the pilot world, generated by \`volter-world 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 the "env" block of world.config.json, which is what `volter-world up` injects.',
+    ...(plan.mintedEnv.length
+      ? [
+          '#',
+          `# NOT REPRODUCIBLE (by design): ${plan.mintedEnv.join(', ')} hold${plan.mintedEnv.length === 1 ? 's' : ''} a freshly minted`,
+          '# throwaway private key, so re-running init produces a different value for these names and only these.',
+          '# Every other byte of this file is a pure function of the repo + the twin pack catalog.',
+        ]
+      : []),
+    '',
+  ];
+  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}`);
+  }
+  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. */
+/** The twin catalog's git SHA at `root`, or 'unknown' for a non-git install. */
+function catalogSha(root: string): string {
+  const proc = spawnSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
+  const sha = proc.status === 0 ? proc.stdout.trim() : '';
+  return /^[0-9a-f]{40}$/.test(sha) ? sha : 'unknown';
+}
+
+export function writeWorldInit(plan: InitPlan, options: { force?: boolean } = {}): void {
+  const existing = existsSync(plan.out) ? readdirSync(plan.out) : [];
+  if (existing.length > 0 && options.force !== true) {
+    throw new Error(
+      `volter-world init: ${plan.out} already exists and is not empty (${existing.length} entr${existing.length === 1 ? 'y' : 'ies'}). `
+      + 'Pass --force to overwrite it, or --out <dir> to emit elsewhere.',
+    );
+  }
+  mkdirSync(plan.out, { recursive: true });
+  writeFileSync(plan.configPath, `${JSON.stringify(plan.config, null, 2)}\n`);
+  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 });
+    writeFileSync(copy.to, readFileSync(copy.from));
+  }
+  if (plan.seedEntry !== null) {
+    mkdirSync(dirname(plan.seedEntry.storyPath), { recursive: true });
+    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');
+    writeFileSync(plan.seedEntry.entryPath,
+      `// THE seed entry point — composes order VISIBLY (no magic globbing): defaults, then story.\n`
+      + `// Run it AFTER EVERY \`volter-world up\` (the runtime has no startup hooks, by rule, and\n`
+      + `// an instance's state lives only while the world runs — up starts clean; the world dir is\n`
+      + `// the reproducible story). From your APP repo's directory, so its node_modules resolve\n`
+      + `// any vendor SDK a seed imports:  volter-world attach <world> -- bun <this file>\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: string, repoPath: string, options: InitOptions = {}): InitResult {
+  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: CoverageReport = { ...proof, world: plan.name };
+  const next = [
+    `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 attach ${plan.name} -- bun ${plan.seedEntry.entryPath}   # seed AFTER every up, from your app repo's directory (its node_modules resolve the vendor SDKs); a world's state lives only while it runs`]),
+    `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: string[], rows: string[][]): string[] {
+  const widths = header.map((title, column) => Math.max(title.length, ...rows.map((row) => row[column]!.length)));
+  const render = (row: string[]): string => 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: InitResult): string {
+  const { plan } = result;
+  const lines: string[] = [];
+  lines.push(`World  ${plan.name}`);
+  lines.push(`Repo   ${plan.repo} (unmodified — nothing was written here)`);
+  lines.push(`Config ${plan.configPath}`);
+  lines.push(`Env    ${plan.envPath}`);
+  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: EnvDisposition): InitEnvRow[] => 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'] as EnvDisposition[]) {
+    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(', ')}`);
+  }
+  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`;
+}