@volter/world-runtime 2.0.55 → 3.0.0

package/src/init.ts

@@ -34,7 +34,7 @@
 //     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 { PROTOCOL_MAJOR, stateDirName } from '@volter/world-core/runtime';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import {
   coverWorld,
@@ -48,12 +48,23 @@ import {
   type CoverageReport,
 } from './covers.ts';
 import { fakeEnvValue, isAppKeyName, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from './fixture-env.ts';
-import { resolveCatalog, twinPackageName, type Catalog } from './catalog.ts';
+import { findInstalledPackage, packCli, packEntry, resolveCatalog, twinPackageName, type Catalog } from './catalog.ts';
+import { CATALOG_INDEX_PACKAGE, defaults as catalogDefaults } from './catalog-index.ts';
 import { projectEnvReads, projectManifestDirs } from './project-inspect.ts';
 import { overlayEndpointEnv, packFacts } from './pack-facts.ts';
-import { DEFAULT_WORLD_SELECTION, MINT_ENV, worldConfigDocument, worldSelectionIncludes, type WorldConfig, type WorldSelection, type WorldServiceConfig } from './schema.ts';
+import { VENDOR_SERVER_BACKINGS } from './backings.ts';
+import { APP_URL_ENV, DEFAULT_WORLD_SELECTION, ISSUE_ENV_PREFIX, MINT_ENV, worldConfigDocument, worldSelectionIncludes, type WorldConfig, type WorldSelection, type WorldServiceConfig } from './schema.ts';
 import { loadWorldConfig } from './configs.ts';
 
+/** The names a pack's credential door fills with a file it writes (`file:<field>`, the descriptor's): a path, never a value. */
+function fileCredentialNames(): Set<string> {
+  const out = new Set<string>();
+  try {
+    for (const facts of Object.values(packFacts())) for (const [name, spec] of Object.entries(facts?.credentialDoor?.fill ?? {})) if (String(spec).startsWith('file:')) out.add(name);
+  } catch { /* no artifact: no file doors known */ }
+  return out;
+}
+
 /** 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 */
@@ -62,7 +73,9 @@ export type InitWiring =
   | '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 */
+  /** the vendor's own open-source server runs as the World's service (VENDOR_SERVER_BACKINGS) */
+  | 'backing'
+  /** detected vendor with no vendor pack in the catalog — nothing to emit */
   | 'no-pack';
 
 export type InitVendorPlan = {
@@ -76,18 +89,47 @@ export type InitVendorPlan = {
   service: WorldServiceConfig | null;
   /** why this wiring — printed in the report and embedded in the service's `//` note */
   note: string;
+  /** the source init chose the pack from (architecture, "The catalog: where twins come from"): where it comes from, its
+   *  protocol and its version */
+  source?: { kind: 'checkout' | 'installed'; version?: string };
 };
 
+/** The env stem of a detected vendor whose endpoint this is, when it points at a loopback server; otherwise null. */
+function standInStem(name: string, value: string, detected: ReadonlyMap<string, unknown>): string | null {
+  // an endpoint override only (`S3_ENDPOINT`, `AWS_ENDPOINT_URL`): a vendor's `*_URL` may be its only address (Supabase's
+  // project URL) or the app's own (`STRIPE_WEBHOOK_URL`), never a stand-in to drop
+  if (!/(^|_)(ENDPOINT|ENDPOINT_URL)$/.test(name) || !/^https?:\/\//.test(value)) return null;
+  let host: string;
+  try { host = new URL(value).hostname.replace(/^\[|\]$/g, ''); } catch { return null; }
+  if (!['localhost', '127.0.0.1', '::1', '0.0.0.0', 'host.docker.internal'].includes(host)) return null;
+  for (const vendor of detected.keys()) {
+    for (const stem of packFacts()[vendor]?.adoption?.envStems ?? []) {
+      if (name.startsWith(`${stem}_`)) return stem;
+    }
+  }
+  return null;
+}
+
+/** Names that carry the application's own origin: its base URL (Next's public one included) and its auth library's. */
+const APP_ORIGIN_ENV = /^(?:NEXT_PUBLIC_)?(?:APP_)?(?:BASE_)?URL$|^NEXT_PUBLIC_APP_(?:BASE_)?URL$|^(?:NEXTAUTH|BETTER_AUTH|AUTH)_URL$/;
+
 /** 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'
+  /** a credential the vendor's twin issues at boot → `$issue:<vendor>` (the twin refuses a key it did not make) */
+  | 'issued'
   /** 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'
+  /** the application's own origin → `$app-url`, the address its booter records, resolved when it attaches */
+  | 'app-origin'
+  /** a detected vendor's endpoint pointed at a local stand-in server (a garage or MinIO for S3) → left unset, so the SDK
+   *  addresses the vendor's own host, which the World routes to its twin */
+  | 'stand-in'
   /** neither credential-shaped nor valued: the operator has to decide */
   | 'unknown';
 
@@ -172,7 +214,8 @@ export type InitPlan = {
   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 }>;
+  /** `from` is copied byte for byte; `content` (a runner init writes for a protocol-3 pack's seed data) is written as given. */
+  defaultsCopies: Array<{ vendor: string; kind: 'handlers' | 'seed' | 'seed-data'; from?: string; content?: string; to: string }>;
   /** emitted when any pack ships a default seed: the one explicit entry point + story skeleton */
   seedEntry: { entryPath: string; storyPath: string } | null;
   /** Explicit wiring for new default seeds when the existing entry point is operator-owned. */
@@ -206,7 +249,7 @@ export type InitResult = {
 
 export type InitOptions = {
   /** the WORLD root: where the emitted config boots from, and where the catalog is resolved —
-   *  this checkout's `packages/twin` when init runs here, else the `@volter/twin-<vendor>`
+   *  the sibling pack repository when init runs here, else the `@volter/twin-<vendor>`
    *  packages installed above it (docs/concepts/worlds.md#the-config-and-the-running-world). Defaults to the
    *  application repo. */
   root?: string;
@@ -226,7 +269,7 @@ export type InitOptions = {
 // ---------------------------------------------------------------------------------------------
 
 /** 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). */
+ * vendor directories in the pack repository, or the `@volter/twin-<vendor>` packages installed above root). */
 export function packCatalog(root: string): string[] {
   return resolveCatalog(root).vendors();
 }
@@ -236,38 +279,13 @@ export function packCatalog(root: string): string[] {
 // ---------------------------------------------------------------------------------------------
 
 /**
- * The REAL endpoint env names for packs the injector cannot intercept — the other half of
- * `scripts/vendor-hosts.test.ts`'s descriptor hostsNone ruling. That allowlist states WHY each pack
- * has no VENDOR_HOSTS entry; this table states WHAT to wire instead, using the env var the vendor's
- * own SDK documents. Every entry is grounded in the SDK, not invented:
- *
- *   inngest                   `INNGEST_BASE_URL` (+ `INNGEST_EVENT_API_BASE_URL` for the event API)
- *                             — inngest@4's own apiBaseUrl/eventBaseUrl getters.
- *   ai-gateway                `AI_GATEWAY_BASE_URL` — `@ai-sdk/gateway`'s baseURL env.
- *   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.
+ * The endpoint env for a pack the injector cannot intercept and whose descriptor cannot state it as `endpointEnv`
+ * (which receives the twin's URL): a raw protocol, whose client is pointed by host and port. Every name is one a real
+ * client documents. A pack with no such env is 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 while
+ * the app, which reads no such var, still talks to the real vendor.
  */
 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.',
-  },
-  // (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.',
-  },
-  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
@@ -288,30 +306,25 @@ export const APP_READ_ENDPOINT_ENV: Record<string, { injectEnv?: string; injectE
     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.',
-  },
-  // RAW PROTOCOL, the gRPC kind. The Temporal SDKs dial the frontend address they are given
-  // (`Connection.connect({ address })`, `NativeConnection.connect({ address })`), conventionally read
-  // from TEMPORAL_ADDRESS — Postiz's temporal.module.ts, the SDK samples and the Temporal CLI all read
-  // that name — and speak gRPC over HTTP/2, which the http/fetch injector never sees. The value is an
-  // address (host:port), not a URL, which is why this lives here as a template and not as the
-  // descriptor's `endpointEnv` (whose `name` receives the twin's URL).
-  temporal: {
-    injectEnvTemplates: {
-      TEMPORAL_ADDRESS: '${host}:${port}',
-    },
-    note: 'no injector entry and none possible: the Temporal SDKs speak gRPC to the address they are configured with. '
-      + 'TEMPORAL_ADDRESS=<host>:<port> points them at the twin (namespace `default` exists); an app that sets '
-      + 'TEMPORAL_API_KEY turns TLS on in the SDK, which this loopback frontend does not speak — leave it unset.',
+      + 'sends there. Read the mail back at the mailbox the World records beside it: `volter-world url <world> smtp.inspect` '
+      + '(/_twin/messages?to=<address>, newest first; /_twin/messages/<id> for one).',
   },
 };
-// descriptor-first migration (adding-a-twin.md §3): packs now declare their endpoint-env wiring (with its grounding
+export { VENDOR_SERVER_BACKINGS } from './backings.ts';
+
+// descriptor-first migration (architecture.md, "The descriptor"): 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. */
+/** A twin service with its pack's credential door (`issues`) as the pack declares it now: a service kept from a saved
+ *  config gets the current door, so its names are issued by the door the pack has, never by a copy it has since fixed. */
+function withIssues(service: WorldServiceConfig): WorldServiceConfig {
+  const door = service.type === 'twin' ? packFacts()[service.id]?.credentialDoor : undefined;
+  return door === undefined ? service : { ...service, issues: door };
+}
+
 function wiringFor(vendor: string): {
   wiring: Exclude<InitWiring, 'no-pack'>;
   injectEnv?: string;
@@ -320,7 +333,7 @@ function wiringFor(vendor: string): {
   serviceEnv?: Record<string, string>;
   note: string;
 } {
-  // RULE 2: ask the injector, never guess. `aws` yields s3/dynamodb/timestream here — the very keys
+  // RULE 2: ask the injector, never guess. `aws` yields s3/secretsmanager here — the very keys
   // the inert `AWS_TWIN_URL` does not.
   const keys = injectorVendorKeysFor(vendor);
   const twinUrlNames = keys.map(injectorEnvNameForKey);
@@ -607,7 +620,7 @@ export function renderComposeFile(plan: InitPlan): string {
   return `${lines.join('\n')}\n`;
 }
 
-export type ParsedEnvEntry = { name: string; value: string; source: string };
+export type ParsedEnvEntry = { name: string; value: string; source: string; /** several dirs define it differently: each `source=value` */ conflict?: 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
@@ -634,23 +647,36 @@ export function parseEnvFile(text: string, source: string): ParsedEnvEntry[] {
   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. */
+/** Every example-env entry in the repo, in a deterministic order: root before workspace members (sorted), and within a
+ * dir the ENV_SOURCE_FILES priority. A name defined in several dirs with one value is that value; with different values
+ * it is the definition of the dir that holds the application (its Prisma schema or its vercel.json) when exactly one such
+ * dir defines it, and otherwise a conflict the operator decides, each definition listed (a landing page's base URL must
+ * never silently become the app's). */
 function repoEnvEntries(repo: string): ParsedEnvEntry[] {
-  const seen = new Set<string>();
-  const entries: ParsedEnvEntry[] = [];
+  const byName = new Map<string, Array<ParsedEnvEntry & { dir: string }>>();
   for (const dir of projectManifestDirs(repo)) {
+    const inDir = new Set<string>();
     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);
+        if (inDir.has(entry.name)) continue;
+        inDir.add(entry.name);
+        byName.set(entry.name, [...(byName.get(entry.name) ?? []), { ...entry, dir }]);
       }
     }
   }
+  const holdsApp = (dir: string): boolean => existsSync(resolve(dir, 'prisma', 'schema.prisma')) || existsSync(resolve(dir, 'vercel.json'));
+  const entries: ParsedEnvEntry[] = [];
+  for (const defs of byName.values()) {
+    const first = defs[0]!;
+    const values = new Set(defs.map((d) => d.value).filter((v) => v !== ''));
+    if (values.size <= 1) { entries.push({ name: first.name, value: defs.find((d) => d.value !== '')?.value ?? '', source: defs.find((d) => d.value !== '')?.source ?? first.source }); continue; }
+    const app = defs.filter((d) => d.value !== '' && holdsApp(d.dir));
+    if (app.length === 1) { entries.push({ name: first.name, value: app[0]!.value, source: app[0]!.source }); continue; }
+    entries.push({ name: first.name, value: first.value, source: first.source, conflict: defs.filter((d) => d.value !== '').map((d) => `${d.source}=${d.value}`) });
+  }
   return entries;
 }
 
@@ -696,9 +722,13 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
 
   const catalogSource: Catalog = resolveCatalog(root);
   const catalog = new Set(catalogSource.vendors());
+  // the catalog index's defaults (the installed `@volter/twin-catalog`), which name the twin to install for a vendor
+  // this catalog lacks
+  const indexDir = findInstalledPackage(root, CATALOG_INDEX_PACKAGE);
+  const indexDefaults = (() => { try { return indexDir === undefined ? {} : catalogDefaults(indexDir); } catch { return {}; } })();
   // 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 defaultsCopies: InitPlan['defaultsCopies'] = [];
   const signals = options.vendors ? null : detectRepoVendors(repo);
   const detected = options.vendors
     ? new Map<string, string[]>(options.vendors.map((v) => [v, ['--twins']]))
@@ -723,6 +753,14 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
   }
   for (const vendor of [...detected.keys()].sort()) {
     const detectedVia = [...(detected.get(vendor) ?? [])].sort();
+    const backing = catalog.has(vendor) ? undefined : VENDOR_SERVER_BACKINGS[vendor];
+    if (backing !== undefined) {
+      const service = existing?.services.find((entry) => entry.id === vendor) ?? backing.service;
+      if (!existingIds.has(vendor)) for (const name of endpointNames(service)) claimedEnv.set(name, vendor);
+      services.push(service);
+      vendors.push({ vendor, pack: null, detectedVia, wiring: 'backing', service, note: backing.service['//'] ?? '' });
+      continue;
+    }
     if (!catalog.has(vendor)) {
       vendors.push({
         vendor,
@@ -730,7 +768,9 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
         detectedVia,
         wiring: 'no-pack',
         service: null,
-        note: `no packages/twin/${vendor} pack in this catalog — the proof reports it MISSING until one exists.`,
+        note: indexDefaults[vendor] !== undefined
+          ? `no ${vendor} twin installed — the catalog index's default is ${indexDefaults[vendor]!.name}@${indexDefaults[vendor]!.version} (from ${indexDefaults[vendor]!.source}): install it (\`bun add -d ${indexDefaults[vendor]!.name}@${indexDefaults[vendor]!.version}\`) and run init again. Until then the proof reports it MISSING.`
+          : `no ${vendor} pack in this catalog — the proof reports it MISSING until one exists.`,
       });
       continue;
     }
@@ -753,7 +793,14 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     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');
+    // a protocol-3 pack's default data (src/semantics/seed.ts: calls to the vendor's own operations, as data) is copied
+    // beside a runner that makes each call against the twin, both the author's from then on
+    const semanticsSeedPath = join(packDir, 'src', 'semantics', 'seed.ts');
     if (existsSync(defaultsSeedPath)) defaultsCopies.push({ vendor, kind: 'seed', from: defaultsSeedPath, to: resolve(out, 'seeds', 'defaults', `${vendor}.ts`) });
+    else if (existsSync(semanticsSeedPath)) {
+      defaultsCopies.push({ vendor, kind: 'seed-data', from: semanticsSeedPath, to: resolve(out, 'seeds', 'defaults', `${vendor}.data.ts`) });
+      defaultsCopies.push({ vendor, kind: 'seed', content: seedCallsRunner(vendor), 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`
@@ -766,7 +813,7 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     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: Pick<WorldServiceConfig, 'package' | 'command' | 'args' | 'colocate'> = catalogSource.kind === 'installed'
+    const boot: Pick<WorldServiceConfig, 'package' | 'command' | 'args' | 'colocate'> = catalogSource.kindOf(vendor) === 'installed'
       ? {
           package: twinPackageName(vendor),
           ...(handlersArg !== null ? { args: ['--scenario', handlersArg] } : {}),
@@ -774,8 +821,8 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
         }
       : {
           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 } : {}) } } : {}),
+          args: [relative(root, packCli(packDir)!), 'serve', ...(handlersArg !== null ? ['--scenario', handlersArg] : [])],
+          ...(serveExport !== undefined ? { colocate: { module: `./${relative(root, packEntry(packDir))}`, export: serveExport, ...(handlersArg !== null ? { scenarioPath: handlersArg } : {}) } } : {}),
         };
     const service: WorldServiceConfig = {
       '//': note,
@@ -789,6 +836,8 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
       ...(conflict === undefined && wiring.injectEnvTemplates ? { injectEnvTemplates: wiring.injectEnvTemplates } : {}),
       ...(conflict === undefined && wiring.cliRedirect ? { cliRedirect: wiring.cliRedirect } : {}),
       ...(wiring.serviceEnv ? { env: wiring.serviceEnv } : {}),
+      // a twin that holds its keys issues the applications' credential at boot (its descriptor's credentialDoor)
+      ...(packFacts()[vendor]?.credentialDoor !== undefined ? { issues: packFacts()[vendor]!.credentialDoor! } : {}),
     };
     if (existing !== undefined && !existingIds.has(vendor)) {
       // Check the complete proposed bindings, including any that the fresh-init conflict path
@@ -811,6 +860,7 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
       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,
+      source: { kind: catalogSource.kindOf(vendor), ...(catalogSource.version(vendor) !== undefined ? { version: catalogSource.version(vendor) } : {}) },
     });
   }
 
@@ -847,15 +897,51 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     ...(existing?.services ?? []),
     ...services.filter((service) => !existingIds.has(service.id)),
   ].flatMap(endpointNames));
+  // Every name a twin of this World issues (its pack's credentialDoor fill), by the twin: the pack names them, so a name
+  // is issued whatever its stem (PlanetScale's DATABASE_URL, Vercel's TEAM_ID_VERCEL, Upstash's KV_REST_API_TOKEN) once
+  // that vendor's twin is in the World, and never when it is not.
+  const issuedBy = new Map<string, string>();
+  for (const service of [...(existing?.services ?? []).map(withIssues), ...services.filter((service) => !existingIds.has(service.id))]) {
+    for (const name of Object.keys(service.issues?.fill ?? {})) if (!issuedBy.has(name)) issuedBy.set(name, service.id);
+  }
+  const standInStems = new Set<string>();
   for (const entry of repoEnvEntries(repo)) {
     if (!envSources.includes(entry.source)) envSources.push(entry.source);
-    const { name, value, source } = entry;
+    const { name, value, source, conflict } = 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;
     }
+    // The application's own origin (its base URL, its auth library's URL): only the booter knows where the app is
+    // reached (a local port, a browser tab's preview origin), so the World names it `$app-url` rather than copying the
+    // example's production address or faking one the app would then call itself at.
+    if (APP_ORIGIN_ENV.test(name)) {
+      env[name] = APP_URL_ENV;
+      envRows.push({ name, disposition: 'app-origin', source, reason: 'the application\'s own origin — `$app-url`: the address its booter records (`volter-world app-url <world> --set <url>`), resolved when the app attaches' });
+      continue;
+    }
+    // a name a twin of this World issues (its descriptor's credentialDoor): `$issue:<service>`, asked of the running twin
+    // at boot, so the application holds a key the twin made rather than a fixture it refuses
+    const issuer = issuedBy.get(name);
+    if (issuer !== undefined) {
+      env[name] = `${ISSUE_ENV_PREFIX}${issuer}`;
+      envRows.push({ name, disposition: 'issued', source, reason: `${issuer} credential — \`$issue:${issuer}\`: up asks the running twin to issue it` });
+      continue;
+    }
+    // a name some pack's credential door fills with a file (`file:<field>`) holds a path: with its issuer unselected, the
+    // example's path is never copied
+    if (fileCredentialNames().has(name)) {
+      env[name] = `/__volter_fake_credentials__/${name.toLowerCase().replace(/_/g, '-')}.json`;
+      envRows.push({ name, disposition: 'unknown', source, reason: 'credential file path — select its detected issuer to receive a World key file; the example path is never copied' });
+      continue;
+    }
+    // Several directories give it different values and none is the application's: the operator decides.
+    if (conflict !== undefined && !isCredentialShapedEnvName(name)) {
+      envRows.push({ name, disposition: 'unknown', source, reason: `defined differently in several places (${conflict.join('; ')}) and none of them is the application's directory — you decide`, unset: true });
+      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
@@ -878,6 +964,12 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
       });
       continue;
     }
+    const served = vendors.filter((v) => v.wiring === 'backing').map((v) => VENDOR_SERVER_BACKINGS[v.vendor]?.env[name]).find((value) => value !== undefined);
+    if (served !== undefined) {
+      env[name] = served;
+      envRows.push({ name, disposition: 'faked', source, reason: 'the key the World\'s own vendor server is started with' });
+      continue;
+    }
     const vendor = envNameVendor(name);
     if (vendor !== null) {
       env[name] = fakeEnvValue(name);
@@ -892,6 +984,14 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
       infraEntries.push({ name, source, kind: infraKind });
       continue;
     }
+    // A detected vendor's endpoint at a loopback server is the repository's local stand-in for the vendor (a garage for
+    // S3): the World routes the vendor's own host to its twin, so the name is left unset and the SDK addresses that host.
+    const standIn = standInStem(name, value, detected);
+    if (standIn !== null) {
+      standInStems.add(standIn);
+      envRows.push({ name, disposition: 'stand-in', source, reason: `a local stand-in for ${standIn}'s own host — left unset; the World routes that host to its twin`, unset: true });
+      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.
@@ -921,34 +1021,29 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
       envRows.push({ name, disposition: 'unknown', source, reason: 'empty in the example and not credential-shaped — you decide', unset: true });
     }
   }
+  // A twinned vendor's credential the app's code reads that no example env declares (a script, an app whose keys come
+  // from a secrets manager): the SDK refuses to start without it, so it is faked as a declared one would be. Only a
+  // credential: a base-URL override the code reads (`OPENAI_BASE_URL`) is optional there, and a fake one would send
+  // the SDK nowhere instead of through the injector; and never a framework's public name (`NEXT_PUBLIC_…`), whose
+  // value the app's own env files hold for the browser, which a set variable would override
+  for (const [name, readAt] of [...envReads.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    if (name in env || envRows.some((row) => row.name === name) || /_TWIN_URL$/.test(name) || /^VOLTER_/.test(name) || worldInjected.has(name)) continue;
+    if (/(?:^|_)(?:URL|URI|ENDPOINT|HOST|BASE|ORIGIN|DOMAIN|REGION|PORT)$/.test(name) || /^(?:NEXT_PUBLIC_|VITE_|REACT_APP_|EXPO_PUBLIC_|NUXT_PUBLIC_|PUBLIC_)/.test(name)) continue;
+    const vendor = envNameVendor(name);
+    if (vendor === null || !vendors.some((entry) => entry.vendor === vendor && entry.service !== null)) continue;
+    env[name] = fakeEnvValue(name);
+    envRows.push({ name, disposition: 'faked', source: readAt[0] ?? 'source', reason: `${vendor} credential read by the app's code; no example env declares it` });
+  }
 
-  // --- 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: WorldServiceConfig = {
-      '//': `${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));
+  // the stand-in's own region (garage's `garage`), where it is not a region of the vendor's shape (`eu-west-1`): the SDK
+  // would sign for a region the vendor does not have
+  for (const row of envRows) {
+    const stem = [...standInStems].find((candidate) => row.name === `${candidate}_REGION`);
+    if (stem === undefined || row.disposition !== 'kept' || /^[a-z]{2}(-[a-z]+)+-\d+$/.test(env[row.name] ?? '')) continue;
+    delete env[row.name];
+    row.disposition = 'stand-in';
+    row.reason = `the local stand-in's region, not one ${stem}'s vendor has — left unset`;
+    row.unset = true;
   }
 
   // --- infra ----------------------------------------------------------------------------------
@@ -1017,14 +1112,14 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
       external: {
         up: ['volter-world-infra', 'up'],
         status: ['volter-world-infra', 'status'],
-        discover: compose.flatMap((service) => service.signals.map((name) => ({ as: name, jsonPath: `connections.${name}` }))),
+        discover: compose.flatMap((service) => service.signals.map((name) => ({ as: name, jsonPath: `connections.${name}`, ...(['postgres', 'mysql', 'mongodb', 'redis'].includes(service.kind) ? { protocol: service.kind } : {}) }))),
         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))];
+  const mergedServices = existing === undefined ? services : [...existing.services.map(withIssues), ...services.filter((service) => !existingIds.has(service.id))];
   if (existing !== undefined) {
     const owners = new Map<string, string>();
     for (const service of mergedServices) {
@@ -1198,7 +1293,7 @@ export function writeWorldInit(plan: InitPlan, options: { force?: boolean } = {}
   // 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 (!(options.force === true && existsSync(copy.to))) writeFileSync(copy.to, copy.content ?? readFileSync(copy.from!));
   }
   if (plan.seedEntry !== null) {
     mkdirSync(dirname(plan.seedEntry.storyPath), { recursive: true });
@@ -1222,6 +1317,31 @@ export function writeWorldInit(plan: InitPlan, options: { force?: boolean } = {}
   }
 }
 
+/** The runner of a protocol-3 pack's default data (its `src/semantics/seed.ts`, copied beside it as `<vendor>.data.ts`):
+ *  each call, in order, against the twin at its `<VENDOR>_TWIN_URL`, a refusal stopping the seed with the twin's answer. */
+export function seedCallsRunner(vendor: string): string {
+  const stem = vendor.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+  return `// ${vendor}'s default data, as its twin's pack declares it (./${vendor}.data.ts: calls to the vendor's own
+// operations), made against the twin in order. Ownership transferred on copy: both files are yours — edit or delete.
+import { seed as calls } from './${vendor}.data.ts';
+
+export async function seed(): Promise<void> {
+  // a twin with a root is the vendor's real account: its default data is not written (VOLTER_SEED_SKIP)
+  if ((process.env.VOLTER_SEED_SKIP ?? '').split(',').includes('${vendor}')) return;
+  const base = process.env.${stem}_TWIN_URL;
+  if (!base) throw new Error('${stem}_TWIN_URL is not set — bring the world up and run the seed with its env (volter-world attach/run)');
+  for (const call of calls) {
+    const res = await fetch(\`\${base.replace(/\\/$/, '')}\${call.path}\`, {
+      method: call.method,
+      headers: { ...(call.body !== undefined ? { 'content-type': 'application/json' } : {}), ...(call.headers ?? {}) },
+      ...(call.body !== undefined ? { body: JSON.stringify(call.body) } : {}),
+    });
+    if (!res.ok) throw new Error(\`${vendor} seed: \${call.method} \${call.path}: \${res.status} \${await res.text()}\`);
+  }
+}
+`;
+}
+
 /**
  * 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
@@ -1287,9 +1407,10 @@ export function formatInitReport(result: InitResult): string {
   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'],
+      ['vendor', 'source', 'wiring', 'inject-env', 'detected-via'],
       plan.vendors.map((vendor) => [
         vendor.vendor,
+        vendor.source ? `${vendor.source.kind}${vendor.source.version ? ` ${vendor.source.version}` : ''}` : '-',
         vendor.wiring,
         [vendor.service?.injectEnv, ...Object.keys(vendor.service?.injectEnvTemplates ?? {})].filter(Boolean).join(', ') || '-',
         vendor.detectedVia.join('; '),
@@ -1303,7 +1424,7 @@ export function formatInitReport(result: InitResult): string {
   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[]) {
+  for (const disposition of ['faked', 'kept', 'app-origin', 'stand-in', '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(', ')}`);

package/src/lifecycle-record.ts

@@ -1,10 +1,10 @@
 // Durable ownership of one World. This inventory does not allocate or reserve capacity.
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
-import { volterHome } from '@volter/world-core';
+import { volterHome } from '@volter/world-core/runtime';
 import { hostname } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
-import { stateDirName, withFileLock } from '@volter/world-core';
+import { stateDirName, withFileLock } from '@volter/world-core/runtime';
 import { checkedOwner } from './consumers.ts';
 
 export type WorldLifecycleRecord = {

package/src/local-branches.ts

@@ -5,7 +5,7 @@
 // and `volter world view` both make them with this; a hosted World's supervisor makes its own.
 import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { stateDirName, withStateRemoval } from '@volter/world-core';
+import { stateDirName, withStateRemoval } from '@volter/world-core/runtime';
 import { clockFile } from './runtime.ts';
 import { loadWorldConfig } from './configs.ts';
 import { TOKEN_HEADER, type BranchDoors, type BranchRow, type MountedWorld } from './served-world.ts';