@volter/world-runtime 2.0.54 → 3.0.0

package/dist/src/init.js

@@ -34,20 +34,59 @@
 //     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, detectRepoVendors, envNameVendor, formatCoverageReport, injectorEnvNameForKey, injectorVendorKeysFor, isCredentialShapedEnvName, registryAcknowledgedReason, } from "./covers.js";
 import { fakeEnvValue, isAppKeyName, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from "./fixture-env.js";
-import { resolveCatalog, twinPackageName } from "./catalog.js";
+import { findInstalledPackage, packCli, packEntry, resolveCatalog, twinPackageName } from "./catalog.js";
+import { CATALOG_INDEX_PACKAGE, defaults as catalogDefaults } from "./catalog-index.js";
 import { projectEnvReads, projectManifestDirs } from "./project-inspect.js";
 import { overlayEndpointEnv, packFacts } from "./pack-facts.js";
-import { DEFAULT_WORLD_SELECTION, MINT_ENV, worldConfigDocument, worldSelectionIncludes } from "./schema.js";
+import { VENDOR_SERVER_BACKINGS } from "./backings.js";
+import { APP_URL_ENV, DEFAULT_WORLD_SELECTION, ISSUE_ENV_PREFIX, MINT_ENV, worldConfigDocument, worldSelectionIncludes } from "./schema.js";
 import { loadWorldConfig } from "./configs.js";
+/** 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() {
+    const out = new Set();
+    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;
+}
+/** The env stem of a detected vendor whose endpoint this is, when it points at a loopback server; otherwise null. */
+function standInStem(name, value, detected) {
+    // 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;
+    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$/;
 // ---------------------------------------------------------------------------------------------
 // The pack catalog
 // ---------------------------------------------------------------------------------------------
 /** The twins available at `root`, sorted — a deterministic input (catalog.ts: this checkout's
- * `packages/twin/<vendor>/` dirs, or the `@volter/twin-<vendor>` packages installed above root). */
+ * vendor directories in the pack repository, or the `@volter/twin-<vendor>` packages installed above root). */
 export function packCatalog(root) {
     return resolveCatalog(root).vendors();
 }
@@ -55,38 +94,13 @@ export function packCatalog(root) {
 // Wiring knowledge
 // ---------------------------------------------------------------------------------------------
 /**
- * The REAL endpoint env names for packs the injector cannot intercept — the other half of
- * `scripts/vendor-hosts.test.ts`'s descriptor hostsNone ruling. That allowlist states WHY each pack
- * has no VENDOR_HOSTS entry; this table states WHAT to wire instead, using the env var the vendor's
- * own SDK documents. Every entry is grounded in the SDK, not invented:
- *
- *   inngest                   `INNGEST_BASE_URL` (+ `INNGEST_EVENT_API_BASE_URL` for the event API)
- *                             — inngest@4's own apiBaseUrl/eventBaseUrl getters.
- *   ai-gateway                `AI_GATEWAY_BASE_URL` — `@ai-sdk/gateway`'s baseURL env.
- *   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 = {
-    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
@@ -107,31 +121,24 @@ export const APP_READ_ENDPOINT_ENV = {
         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.js";
+// 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) {
+    const door = service.type === 'twin' ? packFacts()[service.id]?.credentialDoor : undefined;
+    return door === undefined ? service : { ...service, issues: door };
+}
 function wiringFor(vendor) {
-    // 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);
@@ -433,25 +440,44 @@ export function parseEnvFile(text, 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. */
+/** 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) {
-    const seen = new Set();
-    const entries = [];
+    const byName = new Map();
     for (const dir of projectManifestDirs(repo)) {
+        const inDir = new Set();
         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))
+                if (inDir.has(entry.name))
                     continue;
-                seen.add(entry.name);
-                entries.push(entry);
+                inDir.add(entry.name);
+                byName.set(entry.name, [...(byName.get(entry.name) ?? []), { ...entry, dir }]);
             }
         }
     }
+    const holdsApp = (dir) => existsSync(resolve(dir, 'prisma', 'schema.prisma')) || existsSync(resolve(dir, 'vercel.json'));
+    const entries = [];
+    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;
 }
 // ---------------------------------------------------------------------------------------------
@@ -493,6 +519,15 @@ export function planWorldInit(name, repoPath, options = {}) {
     const carried = (path) => (isInside(root, path) ? relative(root, path) : path);
     const catalogSource = 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 = [];
@@ -520,6 +555,16 @@ export function planWorldInit(name, repoPath, options = {}) {
     }
     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,
@@ -527,7 +572,9 @@ export function planWorldInit(name, repoPath, options = {}) {
                 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;
         }
@@ -552,8 +599,15 @@ export function planWorldInit(name, repoPath, options = {}) {
             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`
@@ -566,7 +620,7 @@ export function planWorldInit(name, repoPath, options = {}) {
         const serveExport = packFacts()[vendor]?.serveExport;
         // In an app repo the twin is a PACKAGE, resolved from the world root at boot (hoisting-proof);
         // inside this checkout it is the checkout-relative path, as the cookbook and the gates expect.
-        const boot = catalogSource.kind === 'installed'
+        const boot = catalogSource.kindOf(vendor) === 'installed'
             ? {
                 package: twinPackageName(vendor),
                 ...(handlersArg !== null ? { args: ['--scenario', handlersArg] } : {}),
@@ -574,8 +628,8 @@ export function planWorldInit(name, repoPath, options = {}) {
             }
             : {
                 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 = {
             '//': note,
@@ -589,6 +643,8 @@ export function planWorldInit(name, repoPath, options = {}) {
             ...(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
@@ -613,6 +669,7 @@ export function planWorldInit(name, repoPath, options = {}) {
             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) } : {}) },
         });
     }
     // --- env ------------------------------------------------------------------------------------
@@ -652,16 +709,54 @@ export function planWorldInit(name, repoPath, options = {}) {
         ...(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();
+    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();
     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
@@ -685,6 +780,12 @@ export function planWorldInit(name, repoPath, options = {}) {
             });
             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);
@@ -699,6 +800,14 @@ export function planWorldInit(name, repoPath, options = {}) {
             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.
@@ -729,34 +838,32 @@ export function planWorldInit(name, repoPath, options = {}) {
             envRows.push({ name, disposition: 'unknown', source, reason: 'empty in the example and not credential-shaped — you decide', unset: true });
         }
     }
-    // --- native frontends ------------------------------------------------------------------------
-    // A detected native connection (Prisma over mysql://) that a SELECTED twin serves as a native
-    // frontend of its own state (the descriptor's `nativeTransport`) is that twin, not managed
-    // infrastructure: a separate database would split the state the app reads through the vendor's
-    // HTTP client from the state it writes natively — the two-client bug this exists to prevent.
-    for (const [kind, signals] of [...infraSignals.entries()]) {
-        const owner = vendors.find((entry) => entry.service !== null && packFacts()[entry.vendor]?.nativeTransport?.protocol === kind);
-        if (owner === undefined || owner.service === null)
+    // 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;
-        const native = packFacts()[owner.vendor].nativeTransport;
-        const id = `${owner.vendor}-${kind}`;
-        const frontend = {
-            '//': `${owner.vendor}'s native ${kind} frontend: the same state as the "${owner.vendor}" twin over the ${kind} wire protocol (declare the HTTP twin first; it reads ${native.upstreamEnv} from it).`,
-            id,
-            type: 'twin',
-            ...(catalogSource.kind === 'installed'
-                ? { package: twinPackageName(owner.vendor), args: [native.flag] }
-                : { command: 'bun', args: [`packages/twin/${owner.vendor}/src/cli.ts`, 'serve', native.flag] }),
-            ...(catalogSource.version(owner.vendor) !== undefined ? { version: catalogSource.version(owner.vendor) } : {}),
-            port: 'auto',
-            injectEnvTemplates: Object.fromEntries([...signals].sort().map((name) => [name, `${kind}://twin:twin@${'${host}'}:${'${port}'}/twin`])),
-        };
-        services.splice(services.indexOf(owner.service) + 1, 0, frontend);
-        for (const entry of infraEntries.filter((candidate) => candidate.kind === kind)) {
-            envRows.push({ name: entry.name, disposition: 'unknown', source: entry.source, reason: `${kind} connection string — injected at boot by the "${id}" twin service (${owner.vendor}'s native frontend over the same state)` });
-        }
-        infraSignals.delete(kind);
-        infraEntries.splice(0, infraEntries.length, ...infraEntries.filter((candidate) => candidate.kind !== kind));
+        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` });
+    }
+    // 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 ----------------------------------------------------------------------------------
     // Kinds with a managed recipe get a private definition next to the config, a declared external
@@ -823,13 +930,13 @@ export function planWorldInit(name, repoPath, options = {}) {
             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();
         for (const service of mergedServices) {
@@ -1001,7 +1108,7 @@ export function writeWorldInit(plan, options = {}) {
     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));
+            writeFileSync(copy.to, copy.content ?? readFileSync(copy.from));
     }
     if (plan.seedEntry !== null) {
         mkdirSync(dirname(plan.seedEntry.storyPath), { recursive: true });
@@ -1023,6 +1130,30 @@ export function writeWorldInit(plan, options = {}) {
                 + `\nawait story();\n`);
     }
 }
+/** 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) {
+    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
@@ -1087,8 +1218,9 @@ export function formatInitReport(result) {
     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) => [
+        lines.push(...table(['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('; '),
@@ -1102,7 +1234,7 @@ export function formatInitReport(result) {
     lines.push('');
     const counts = (disposition) => plan.envRows.filter((row) => row.disposition === disposition);
     lines.push(`Env (${plan.envRows.length} name(s) from ${plan.envSources.join(', ') || 'no example env file'}):`);
-    for (const disposition of ['faked', 'kept', 'compose', 'placeholder', 'unknown']) {
+    for (const disposition of ['faked', 'kept', 'app-origin', 'stand-in', 'compose', 'placeholder', 'unknown']) {
         const rows = counts(disposition);
         if (rows.length === 0)
             continue;

package/dist/src/lifecycle-record.js

@@ -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.js";
 const directory = () => join(volterHome(), 'world-lifecycles');
 const identity = (root, world) => createHash('sha256').update(`${resolve(root)}\0${world}`).digest('hex');

package/dist/src/local-branches.js

@@ -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.js";
 import { loadWorldConfig } from "./configs.js";
 import { TOKEN_HEADER } from "./served-world.js";

package/dist/src/origin.d.ts

@@ -1,4 +1,4 @@
-import { type HistoryReference } from '@volter/world-core';
+import { type HistoryReference } from '@volter/world-core/runtime';
 import type { WorldInstance } from './schema.js';
 export type FetchOptions = {
     root?: string;

package/dist/src/origin.js

@@ -1,11 +1,11 @@
-import { captureHistory, historyDigest, publishOriginHistory, readHistoryView, historyLength, worldPaths } from '@volter/world-core';
+import { captureHistory, historyDigest, publishOriginHistory, readHistoryView, historyLength, worldPaths } from '@volter/world-core/runtime';
 // `volter world clone` and `fetch` — a world's ORIGIN is another world, served (docs/concepts/the-model.md
 // #a-branch-is-a-position-not-a-copy: a clone is a branch whose parent is at a URL): its whole log per twin is this world's PARENT. `clone` records the origin
 // and brings every twin's log in from position zero; `fetch` appends what the origin has past the
 // recorded position. Nothing here touches a vendor: an origin is always a world, the token is the
 // served world's, and what arrives are entries — the parent log grows, the branch log is untouched.
 import { join, resolve } from 'node:path';
-import { getActiveWorldStore, readBranchMeta, withAncestryLock, writeBranchMeta } from '@volter/world-core';
+import { getActiveWorldStore, readBranchMeta, withHistoryLock, writeBranchMeta } from '@volter/world-core/runtime';
 import { saveWorldInstance, statusWorld } from "./runtime.js";
 import { fetchReady, isPathRemote, localWorld, TOKEN_HEADER } from "./served-world.js";
 import { loadWorldConfig, writeWorldConfig } from "./configs.js";
@@ -47,14 +47,15 @@ export async function fetchFromOrigin(name, options) {
     const appended = {};
     const behind = {};
     const snapshots = {};
-    withAncestryLock(() => {
-        for (const service of services) {
-            const controlRoot = join(instance.dirs.data, service);
-            const meta = readBranchMeta(stateServiceOf(controlRoot, service), controlRoot);
+    for (const service of services) {
+        const controlRoot = join(instance.dirs.data, service);
+        const state = stateServiceOf(controlRoot, service);
+        withHistoryLock(worldPaths(state, controlRoot).dir, () => {
+            const meta = readBranchMeta(state, controlRoot);
             if (meta?.parent && !meta.origin)
                 throw new Error('Cannot attach a first origin to an existing local fork; clone the origin before branching');
-        }
-    });
+        });
+    }
     for (const service of services) {
         const controlRoot = join(instance.dirs.data, service);
         const state = stateServiceOf(controlRoot, service);
@@ -62,7 +63,8 @@ export async function fetchFromOrigin(name, options) {
             // A PARENT ON THIS MACHINE is read live through the pointer, like a local branch (contract
             // "Just like Neon", 1): nothing is copied; a clone points at the parent's head, a fetch only
             // says how far the parent has moved past this branch's position
-            withAncestryLock(() => {
+            // under the branch's history lock, as rebase is: a fetch cannot restore a pointer a concurrent rebase advanced
+            withHistoryLock(worldPaths(state, controlRoot).dir, () => {
                 const target = localWorld(origin.url);
                 const at = join(target.instance.dirs.data, service);
                 const parentState = stateServiceOf(at, service);
@@ -113,7 +115,7 @@ export async function fetchFromOrigin(name, options) {
         }
         if (historyDigest({ layout: first.layout, entries }) !== first.digest)
             throw new Error('Origin history digest mismatch');
-        withAncestryLock(() => {
+        withHistoryLock(worldPaths(state, controlRoot).dir, () => {
             const meta = readBranchMeta(state, controlRoot);
             if (meta?.parent && !meta.origin)
                 throw new Error('Cannot attach a first origin to an existing local fork; clone the origin before branching');