@volter/world-runtime 3.0.163 → 3.0.164

package/dist/src/init.js

@@ -1,3 +1,7 @@
+import { copyNativeServerInputs, readNativeServerInputs, nativeServerRuntimeReference } from "./native-server-inputs.js";
+import { goMysqlBinding, renderGoMysqlBinding } from "./go-mysql-binding.js";
+import * as managedOriginalInputs from '@volter/world-core/managed-original-inputs';
+import { copyOriginalInputSnapshot, readOriginalInputSnapshot } from "./original-inputs.js";
 // `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:
@@ -33,6 +37,7 @@
 //     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 { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { PROTOCOL_MAJOR, stateDirName } from '@volter/world-core/runtime';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
@@ -40,7 +45,7 @@ import { coverWorld, detectRepoVendors, envNameVendor, coverageRecord, formatCov
 import { fakeEnvValue, isAppKeyName, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from "./fixture-env.js";
 import { findInstalledPackage, packCli, packEntry, resolveCatalog } from "./catalog.js";
 import { CATALOG_INDEX_PACKAGE, defaults as catalogDefaults } from "./catalog-index.js";
-import { projectEnvReads, projectManifestDirs, projectMigrationTools } from "./project-inspect.js";
+import { filesLeftAsThePersonsOwn, projectEnvReads, projectManifestDirs, projectMigrationTools, readOnlyWhatTheSourceHolds, sourceText } from "./project-inspect.js";
 import { overlayEndpointEnv, packFacts } from "./pack-facts.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";
@@ -84,6 +89,96 @@ function standInStem(name, value, detected) {
 }
 /** 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 families the image builder names (its SERVICE_FAMILIES) that are a managed kind here. */
+const FAMILY_KIND = { postgres: 'postgres', mysql: 'mysql', mongodb: 'mongodb', redis: 'redis', search: 'search', clickhouse: 'clickhouse', memcached: 'memcached' };
+const CONVENTIONAL_NAMES = { postgres: ['DATABASE_URL'], mysql: ['DATABASE_URL'], mongodb: ['MONGODB_URI'], redis: ['REDIS_URL'], clickhouse: ['CLICKHOUSE_URL'] };
+/** The needs file, checked for its kind: a file of another shape is refused by name, never half-read. */
+function readStackNeeds(path) {
+    let document;
+    try {
+        document = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`volter init: --needs ${path} could not be read as JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (document.kind !== 'browser-substrate.stack-needs' || (document.version !== 1 && document.version !== 2 && document.version !== 3 && document.version !== 4 && document.version !== 5 && document.version !== 6 && document.version !== 7) || !Array.isArray(document.needs)) {
+        throw new Error(`volter init: --needs ${path} is not a stack-needs file (kind "browser-substrate.stack-needs", version 1, 2, 3, 4, 5, 6 or 7)`);
+    }
+    const identifier = (name, what) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+            throw new Error(`volter init: --needs ${path} names a variable that is not an identifier among ${what}: ${JSON.stringify(name)}`);
+        return name;
+    };
+    const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? Object.entries(value) : [];
+    return {
+        composeFile: typeof document.composeFile === 'string' ? document.composeFile : 'the project\'s Compose file',
+        ...(typeof document.application?.service === 'string' ? { application: document.application.service } : {}),
+        // The application's own variables that name no service: its settings as the stack writes them, and those whose
+        // value the stack makes from a variable nothing sets, which are named and have no value here.
+        settings: record(document.settings).filter(([, value]) => typeof value === 'string').map(([name, value]) => ({ name: identifier(name, 'the application\'s settings'), value: value })),
+        unset: record(document.unset).map(([name]) => identifier(name, 'the application\'s unset variables')),
+        needs: document.needs.filter((need) => typeof need.service === 'string').map((need) => ({
+            service: need.service,
+            ...(need.originalInputs === undefined ? {} : { originalInputs: (() => {
+                    if (document.version !== 4 && document.version !== 5 && document.version !== 6 && document.version !== 7)
+                        throw new Error('volter init: original inputs require needs version4,5,6 or7');
+                    const reference = managedOriginalInputs.referenceOf(need.originalInputs);
+                    const source = readOriginalInputSnapshot(dirname(resolve(path)), reference).snapshot.manifest;
+                    const image = source.start.service.image;
+                    if (source.service !== need.service || source.family !== need.family || typeof need.image !== 'string' || image?.raw !== need.image)
+                        throw new Error('volter init: original inputs belong to another declared service');
+                    return reference;
+                })() }),
+            ...(need.nativeServerInputs === undefined ? {} : (() => {
+                if (document.version !== 5 && document.version !== 7)
+                    throw new Error('volter init: native managed input requires needs5 or7');
+                const checked = readNativeServerInputs(dirname(resolve(path)), need.nativeServerInputs);
+                const source = JSON.parse(checked.files.get('declaration.json').toString('utf8'));
+                if (need.family !== 'mysql' || need.supplier !== 'a World' || source.name !== need.service || source.image?.raw !== need.image)
+                    throw new Error('volter init: native managed source belongs to another declared service');
+                return { nativeServerInputs: checked.reference, nativeCredentialAliases: checked.aliases };
+            })()),
+            ...(typeof need.image === 'string' ? { image: need.image } : {}),
+            ...(typeof need.family === 'string' ? { family: need.family } : {}),
+            names: (Array.isArray(need.names) ? need.names : []).map((entry) => {
+                // A name becomes a key of the World's environment file: an identifier, or it is refused by name. Anything
+                // else (a newline, an `=`) would write lines of its own there.
+                if (typeof entry.name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(entry.name))
+                    throw new Error(`volter init: --needs ${path} names a variable that is not an identifier under service ${String(need.service)}: ${JSON.stringify(entry.name)}`);
+                if (entry.containerPort !== undefined && ((document.version !== 3 && document.version !== 4 && document.version !== 5 && document.version !== 6 && document.version !== 7) || !Number.isInteger(entry.containerPort) || Number(entry.containerPort) < 1 || Number(entry.containerPort) > 65535))
+                    throw new Error(`volter init: --needs ${path} needs version3 and a valid declared vendor port`);
+                return { name: entry.name, ...goMysqlBinding(entry, document.version, entry.name, COMPOSE_INFRA.mysql.containerPort), ...(entry.containerPort !== undefined ? { containerPort: Number(entry.containerPort) } : {}), ...(typeof entry.scheme === 'string' && /^[a-z][a-z0-9+.-]*$/i.test(entry.scheme) ? { scheme: entry.scheme } : {}), ...(typeof entry.query === 'string' ? { query: entry.query } : {}), ...(entry.withPort === true ? { withPort: true } : {}) };
+            }),
+            components: (() => {
+                if (need.components === undefined)
+                    return [];
+                if ((document.version !== 2 && document.version !== 3 && document.version !== 4 && document.version !== 5 && document.version !== 6 && document.version !== 7) || !Array.isArray(need.components))
+                    throw new Error(`volter init: --needs ${path} requires version 2,3,4,5,6 or7 for store components`);
+                return need.components.map((part) => {
+                    if (!part || typeof part !== 'object' || Array.isArray(part))
+                        throw new Error(`volter init: --needs ${path} has an invalid store component`);
+                    const field = part;
+                    if (typeof field.name !== 'string' || !['database', 'user', 'password'].includes(String(field.component)))
+                        throw new Error(`volter init: --needs ${path} has an invalid store component`);
+                    return { name: identifier(field.name, `the components of service ${String(need.service)}`), component: field.component };
+                });
+            })(),
+            // The variables that hold the service's port beside one that holds its host: keys of the environment file too.
+            ports: (Array.isArray(need.ports) ? need.ports : []).map((name) => identifier(String(name), `the port variables of service ${String(need.service)}`)),
+            portTargets: (() => {
+                if (need.portTargets === undefined)
+                    return {};
+                if ((document.version !== 3 && document.version !== 4 && document.version !== 5 && document.version !== 6 && document.version !== 7) || !need.portTargets || typeof need.portTargets !== 'object' || Array.isArray(need.portTargets))
+                    throw new Error(`volter init: --needs ${path} needs version3 for named vendor ports`);
+                return Object.fromEntries(Object.entries(need.portTargets).map(([name, value]) => {
+                    if (!Array.isArray(need.ports) || !need.ports.includes(name) || !Number.isInteger(value) || Number(value) < 1 || Number(value) > 65535)
+                        throw new Error(`volter init: --needs ${path} has an invalid named vendor port`);
+                    return [identifier(name, 'named vendor ports'), Number(value)];
+                }));
+            })(),
+        })),
+    };
+}
 // ---------------------------------------------------------------------------------------------
 // The pack catalog
 // ---------------------------------------------------------------------------------------------
@@ -278,6 +373,14 @@ const INFRA_PLACEHOLDER = {
 /** 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 = {
+    clickhouse: {
+        image: 'clickhouse/clickhouse-server:26.9.13.15',
+        containerPort: 8123,
+        // The existing managed-database Docker default; a backend limit, not measured adequacy.
+        memoryMiB: 1024,
+        volumePath: '/var/lib/clickhouse',
+        healthcheck: () => ['CMD', 'wget', '--quiet', '--output-document=-', 'http://127.0.0.1:8123/ping'],
+    },
     postgres: {
         image: 'postgres:16',
         containerPort: 5432,
@@ -299,8 +402,8 @@ const COMPOSE_INFRA = {
         volumePath: '/data',
         healthcheck: () => ['CMD', 'redis-cli', 'ping'],
     },
-    // The runtime serves this kind with MongoDB's own mongod on PATH, without a container,
-    // at the same loopback port and URL; command: ["mongod", "--replSet", "world"] enables transactions.
+    // The installed declaring twin, or MongoDB's own server, owns this kind's backing.
+    // A replica-set name is metadata passed to that backing, never a choice of executable.
     mongodb: {
         image: 'mongo:7',
         containerPort: 27017,
@@ -352,11 +455,14 @@ function composeService(name, kind, signals, taken) {
     // redis and mongodb run without authentication (no credentials in their images' env), so their URLs carry none
     const url = kind === 'redis'
         ? `redis://127.0.0.1:${hostPort}`
-        : kind === 'mongodb'
-            ? `mongodb://127.0.0.1:${hostPort}/${ident}`
-            : `${kind}://${composeUser(name, kind)}:${ident}@127.0.0.1:${hostPort}/${ident}`;
+        : kind === 'clickhouse'
+            ? `http://${composeUser(name, kind)}:${ident}@127.0.0.1:${hostPort}/${ident}`
+            : kind === 'mongodb'
+                ? `mongodb://127.0.0.1:${hostPort}/${ident}`
+                : `${kind}://${composeUser(name, kind)}:${ident}@127.0.0.1:${hostPort}/${ident}`;
     return {
         kind,
+        ...(kind === 'clickhouse' ? { sides: { native: { hostPort: composePort(name, 'clickhouse-native', taken), containerPort: 9000 } }, configuration: { users: { default: '', [ident]: ident }, databases: [ident] } } : {}),
         image: recipe.image,
         hostPort,
         containerPort: recipe.containerPort,
@@ -372,11 +478,21 @@ function composeEnvironment(name, kind) {
     if (kind === 'postgres') {
         return [['POSTGRES_USER', ident], ['POSTGRES_PASSWORD', ident], ['POSTGRES_DB', ident]];
     }
+    if (kind === 'clickhouse')
+        return [['CLICKHOUSE_DB', ident], ['CLICKHOUSE_USER', ident], ['CLICKHOUSE_PASSWORD', ident], ['CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT', '1']];
     if (kind === 'mysql') {
         return [['MYSQL_ROOT_PASSWORD', ident], ['MYSQL_DATABASE', ident], ['MYSQL_USER', composeUser(name, kind)], ['MYSQL_PASSWORD', ident]];
     }
     return [];
 }
+function managedPort(service, containerPort) {
+    if (containerPort === undefined || containerPort === service.containerPort)
+        return service.hostPort;
+    const side = Object.values(service.sides ?? {}).find(port => port.containerPort === containerPort);
+    if (!side)
+        throw new Error(`volter init: managed ${service.kind} does not serve vendor port ${containerPort}`);
+    return side.hostPort;
+}
 /** 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) {
@@ -390,13 +506,49 @@ export function renderComposeFile(plan) {
     for (const service of plan.compose) {
         const recipe = COMPOSE_INFRA[service.kind];
         lines.push(`  ${service.kind}:`);
-        lines.push(`    image: ${service.image}`);
+        lines.push(`    image: ${JSON.stringify(service.image)}`);
+        if (service.virtualTcpEndpoint)
+            lines.push(`    x-volter-virtual-tcp-endpoint: ${JSON.stringify(service.virtualTcpEndpoint)}`);
+        if (service.replicaSet !== undefined)
+            lines.push(`    x-volter-replica-set: ${JSON.stringify(service.replicaSet)}`);
+        if (service.nativeServerInputs) {
+            lines.push('    x-volter-interfaces: 3');
+            lines.push(`    x-volter-native-server: ${JSON.stringify(nativeServerRuntimeReference(service.nativeServerInputs))}`);
+        }
+        if (service.originalInputs) {
+            if (!service.sides)
+                lines.push('    x-volter-interfaces: 2');
+            lines.push(`    x-volter-original-inputs: ${JSON.stringify({ ...service.originalInputs, root: `original-inputs/${service.originalInputs.sha256}` })}`);
+        }
         lines.push(`    mem_limit: ${service.memoryMiB}m`);
         lines.push(`    memswap_limit: ${service.memoryMiB}m`);
         lines.push('    cpus: 1');
+        if (service.connectionBindings) {
+            lines.push('    x-volter-issued-dsn-bindings:');
+            for (const [name, binding] of Object.entries(service.connectionBindings)) {
+                lines.push(`      ${name}:`);
+                for (const [field, value] of Object.entries(binding))
+                    lines.push(`        ${field}: ${JSON.stringify(value)}`);
+            }
+        }
         lines.push('    ports:');
         lines.push(`      - "127.0.0.1:${service.hostPort}:${service.containerPort}"`);
+        for (const side of Object.values(service.sides ?? {}))
+            lines.push(`      - "127.0.0.1:${side.hostPort}:${side.containerPort}"`);
+        if (service.sides) {
+            lines.push(`    x-volter-interfaces: ${service.originalInputs ? 2 : 1}`);
+            lines.push(`    x-volter-side-ports: ${JSON.stringify(service.sides)}`);
+            lines.push(`    x-volter-configuration: ${JSON.stringify(service.configuration)}`);
+        }
         const environment = composeEnvironment(plan.name, service.kind);
+        if (service.nativeServerInputs)
+            for (const alias of service.nativeCredentialAliases ?? []) {
+                const canonical = alias.replace(/^MARIADB_/, 'MYSQL_');
+                const entry = environment.find(([name]) => name === canonical);
+                if (!entry)
+                    throw new Error('volter init: native provider credential alias has no issued field');
+                environment.push([alias, entry[1]]);
+            }
         if (environment.length > 0) {
             lines.push('    environment:');
             for (const [key, value] of environment)
@@ -455,8 +607,11 @@ function repoEnvEntries(repo) {
             const path = resolve(dir, file);
             if (!existsSync(path))
                 continue;
+            const text = sourceText(path);
+            if (text === undefined)
+                continue;
             const source = relative(repo, path) || file;
-            for (const entry of parseEnvFile(readFileSync(path, 'utf8'), source)) {
+            for (const entry of parseEnvFile(text, source)) {
                 if (inDir.has(entry.name))
                     continue;
                 inDir.add(entry.name);
@@ -497,7 +652,11 @@ function isInside(parent, candidate) {
 }
 export function planWorldInit(name, repoPath, options = {}) {
     assertSafeName(name);
+    // The World's own name, kept under a name no loop below takes: what it issues is made from it.
+    const worldName = name;
     const repo = resolve(repoPath);
+    // A World made from a stack's needs is made for an image: only what the project's source holds is read.
+    readOnlyWhatTheSourceHolds(options.needs ? repo : undefined);
     if (!existsSync(repo))
         throw new Error(`volter init: the application repo does not exist: ${repo}`);
     const root = resolve(options.root ?? repo);
@@ -519,7 +678,7 @@ export function planWorldInit(name, repoPath, options = {}) {
     /** a path the config carries: relative to the world root when the config lives under it
      *  (portable between teammates), absolute otherwise (a pilot emitted away from its root) */
     const carried = (path) => (isInside(root, path) ? relative(root, path) : path);
-    const catalogSource = resolveCatalog(root, { sources: options.sources, vendors: options.vendors });
+    const catalogSource = resolveCatalog(root, { sources: options.sources, vendors: options.vendors, mayBeEmpty: options.needs !== undefined });
     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
@@ -528,7 +687,9 @@ export function planWorldInit(name, repoPath, options = {}) {
     // baked into the pack). Its handlers starter is the answering turns its own life scripts (journeys/scenario.json, the
     // World's handler format, its faults left out); its default data is src/semantics/seed.ts.
     const defaultsCopies = [];
-    const signals = options.vendors ? null : detectRepoVendors(repo, existing?.services);
+    const stack = options.needs ? readStackNeeds(resolve(options.needs)) : undefined;
+    const stackEnvironmentNames = stack ? [...new Set([...stack.settings.map(entry => entry.name), ...stack.unset])].sort() : [];
+    const signals = options.vendors ? null : detectRepoVendors(repo, existing?.services, stackEnvironmentNames);
     const detected = options.vendors
         ? new Map(options.vendors.map((v) => [v, ['--twins']]))
         : new Map([...signals.detected].filter(([vendor]) => (signals.uses.get(vendor) ?? []).some((use) => worldSelectionIncludes(selection, vendor, use.usage))));
@@ -689,6 +850,36 @@ export function planWorldInit(name, repoPath, options = {}) {
     const mintedEnv = [];
     const infraSignals = new Map();
     const infraEntries = [];
+    // The project's own stack, where its image builder read it: each variable it wires to a service of a managed kind
+    // is that kind's signal whatever the variable is called, and is decided here before a name's pattern is asked.
+    const stackNames = new Map();
+    const stackNeeds = [];
+    /** The names actually given each service's address, filled where an entry is written: the report counts these. */
+    const stackWritten = new Map();
+    const kinds = (stack?.needs ?? []).map((need) => {
+        const fromScheme = need.names.map((entry) => entry.scheme === undefined ? null : schemeKindFor(`${entry.scheme}://`)).find((kind) => kind !== null) ?? null;
+        return { need, fromScheme, kind: fromScheme ?? (need.family !== undefined ? FAMILY_KIND[need.family] ?? null : null), source: `${stack.composeFile} service ${need.service}` };
+    });
+    // Explicit names first, over the whole stack: a service the stack wires by name keeps its names whatever is
+    // listed before it. Conventional names are for what is left, and never one another service was given.
+    for (const { need, kind, source } of kinds) {
+        if (kind === null)
+            continue;
+        for (const entry of need.names)
+            if (!stackNames.has(entry.name))
+                stackNames.set(entry.name, { kind, source, ...(entry.dsnFormat ? { dsnFormat: entry.dsnFormat, endpoint: entry.endpoint, dsnPrefix: entry.dsnPrefix, dsnProtocol: entry.dsnProtocol } : {}), host: entry.scheme === undefined, withPort: entry.withPort === true, ...(entry.scheme ? { scheme: entry.scheme } : {}), ...(entry.containerPort !== undefined ? { containerPort: entry.containerPort } : {}), ...(entry.query !== undefined ? { query: entry.query } : {}), service: need.service, conventional: false });
+    }
+    for (const { need, kind, source } of kinds) {
+        if (kind === null || need.names.length > 0)
+            continue;
+        for (const name of CONVENTIONAL_NAMES[kind] ?? [])
+            if (!stackNames.has(name))
+                stackNames.set(name, { kind, source, host: false, withPort: false, service: need.service, conventional: true });
+    }
+    const writeStackName = (name) => {
+        const wired = stackNames.get(name);
+        stackWritten.set(wired.service, [...(stackWritten.get(wired.service) ?? []), name]);
+    };
     // SMTP's host and port under the names this app declares: apps name them their own way (twenty's EMAIL_SMTP_HOST/
     // EMAIL_SMTP_PORT beside nodemailer's SMTP_HOST), and a raw-TCP twin is reached only through the env the app reads,
     // so every declared `…SMTP_HOST` / `…SMTP_PORT` points at the smtp twin (twenty lane: its mail went to the log). A World
@@ -717,6 +908,19 @@ export function planWorldInit(name, repoPath, options = {}) {
         ...(existing?.services ?? []),
         ...services.filter((service) => !existingIds.has(service.id)),
     ].flatMap(endpointNames));
+    const stackComponents = new Map();
+    const addressNames = new Set((stack?.needs ?? []).flatMap(need => [...need.names.map(entry => entry.name), ...need.ports]));
+    for (const { need, kind, source } of kinds)
+        for (const part of need.components) {
+            if (kind === null || addressNames.has(part.name) || worldInjected.has(part.name))
+                throw new Error(`volter init: ${part.name} has no exclusive managed store component binding`);
+            const held = stackComponents.get(part.name);
+            if (held && (held.kind !== kind || held.service !== need.service || held.component !== part.component))
+                throw new Error(`volter init: ${part.name} has conflicting managed store component bindings`);
+            stackComponents.set(part.name, { kind, source, service: need.service, component: part.component });
+            if (!held)
+                stackWritten.set(need.service, [...(stackWritten.get(need.service) ?? []), part.name]);
+        }
     // 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 (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.
@@ -727,7 +931,18 @@ export function planWorldInit(name, repoPath, options = {}) {
                 issuedBy.set(name, service.id);
     }
     const standInStems = new Set();
-    for (const entry of repoEnvEntries(repo)) {
+    // THE STACK'S OWN STATEMENT OF THE APPLICATION'S ENVIRONMENT comes before the env files: the Compose file is what
+    // the project runs, an example env file what it suggests. Each name goes through the rules below as a name from a
+    // file does (a credential-shaped one is replaced by a fake or issued, never copied; an infrastructure one is a
+    // signal), so an application with no env file is still given its settings, and a secret the stack leaves to a
+    // variable nothing sets is one the World supplies.
+    const stackSource = stack ? `${stack.composeFile}${stack.application ? ` service ${stack.application}` : ''} environment` : '';
+    const stackEntries = stack ? [
+        ...stack.settings.map(({ name, value }) => ({ name, value, source: stackSource })),
+        ...stack.unset.filter((name) => !stack.settings.some((entry) => entry.name === name)).map((name) => ({ name, value: '', source: `${stackSource} (left to a variable nothing sets)` })),
+    ] : [];
+    const stated = new Set(stackEntries.map((entry) => entry.name));
+    for (const entry of [...stackEntries, ...repoEnvEntries(repo).filter((entry) => !stated.has(entry.name))]) {
         if (!envSources.includes(entry.source))
             envSources.push(entry.source);
         const { name, value, source, conflict } = entry;
@@ -800,12 +1015,33 @@ export function planWorldInit(name, repoPath, options = {}) {
             envRows.push({ name, disposition: 'faked', source, reason: `${vendor} credential` });
             continue;
         }
-        const infraKind = infraKindFor(name, value);
+        // A conventional name is the stack's guess; where the application's own example gives that name a value whose
+        // scheme says another kind (`DATABASE_URL=mysql://…` beside an unnamed PostgreSQL), the value is the evidence.
+        const offered = stackNames.get(name);
+        const valueKind = schemeKindFor(value);
+        const wired = offered !== undefined && offered.conventional && valueKind !== null && valueKind !== offered.kind ? undefined : offered;
+        if (offered !== undefined && wired === undefined)
+            stackNames.delete(name);
+        const infraKind = wired?.kind ?? infraKindFor(name, value);
         if (infraKind !== null) {
+            if (wired)
+                writeStackName(name);
+            let query = wired?.query;
+            if (query === undefined && infraKind === 'mongodb') {
+                const authority = /^mongodb(?:\+srv)?:\/\/([^/?#]+)/u.exec(value)?.[1]?.split('@').at(-1);
+                if (authority?.includes(','))
+                    throw new Error(`volter init: ${name} names a multi-host MongoDB URI; one managed listener cannot retain that seed list`);
+                try {
+                    const asked = new URL(value).searchParams.getAll('replicaSet');
+                    if (asked.length)
+                        query = new URLSearchParams(asked.map(set => ['replicaSet', set])).toString();
+                }
+                catch { /* a host or empty example declares no URI query */ }
+            }
             // 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 });
+            infraEntries.push({ name, source: wired ? `${wired.source}; ${source}` : source, kind: infraKind, ...(wired?.dsnFormat ? { dsnFormat: wired.dsnFormat, endpoint: wired.endpoint, dsnPrefix: wired.dsnPrefix, dsnProtocol: wired.dsnProtocol } : {}), ...(wired?.scheme ? { scheme: wired.scheme } : {}), ...(wired?.containerPort !== undefined ? { containerPort: wired.containerPort } : {}), ...(query !== undefined ? { query } : {}), ...(wired?.host ? { host: true } : {}), ...(wired?.withPort ? { withPort: true } : {}) });
             continue;
         }
         // A detected vendor's endpoint at a loopback server is the repository's local stand-in for the vendor (a garage for
@@ -820,8 +1056,16 @@ export function planWorldInit(name, repoPath, options = {}) {
         // 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) || isAppKeyName(name)) {
-            env[name] = fakeEnvValue(name);
-            envRows.push({ name, disposition: 'faked', source, reason: 'credential-shaped name — the example value is never copied' });
+            // AN APPLICATION'S OWN SECRET IS ISSUED AT A GENERATOR'S LENGTH. A name no vendor claims and no shape answers
+            // (AUTH_SECRET, JWT_SECRET, SESSION_SECRET) is the application's own, and applications check theirs: kaneo
+            // refuses one under 32 characters, and `twin-fake-auth-secret` is 21. It is issued as 64 hexadecimal
+            // characters, what `openssl rand -hex 32` gives, made from the World's name and the variable's so a World made
+            // twice is the same World and two Worlds do not share a secret anyone could compute from the variable alone.
+            // A vendor's credential keeps `twin-fake-…`, which its twin accepts and which reads as what it is.
+            const generic = fakeEnvValue(name);
+            const appsOwn = generic === `twin-fake-${name.toLowerCase().replace(/_/g, '-')}` && envNameVendor(name) === null;
+            env[name] = appsOwn ? createHash('sha256').update(`${worldName}\0${generic}`).digest('hex') : generic;
+            envRows.push({ name, disposition: 'faked', source, reason: appsOwn ? 'the application\'s own secret — issued as 64 hex characters, never the example value' : 'credential-shaped name — the example value is never copied' });
             continue;
         }
         if (value !== '') {
@@ -879,6 +1123,33 @@ export function planWorldInit(name, repoPath, options = {}) {
         row.reason = `the local stand-in's region, not one ${stem}'s vendor has — left unset`;
         row.unset = true;
     }
+    // What the stack wires that no env file declared (an application with no env file at all), and what an env file
+    // declared under a name no pattern knows, which was then kept or left as an ordinary value: the stack says it
+    // names a service, so it takes the service's address.
+    for (const [name, wired] of stackNames) {
+        if (infraEntries.some((entry) => entry.name === name))
+            continue;
+        const held = envRows.findIndex((row) => row.name === name);
+        if (held >= 0)
+            envRows.splice(held, 1);
+        delete env[name];
+        infraSignals.set(wired.kind, [...(infraSignals.get(wired.kind) ?? []), name]);
+        infraEntries.push({ name, source: wired.source, kind: wired.kind, ...(wired.dsnFormat ? { dsnFormat: wired.dsnFormat, endpoint: wired.endpoint, dsnPrefix: wired.dsnPrefix, dsnProtocol: wired.dsnProtocol } : {}), ...(wired.scheme ? { scheme: wired.scheme } : {}), ...(wired.containerPort !== undefined ? { containerPort: wired.containerPort } : {}), ...(wired.query !== undefined ? { query: wired.query } : {}), ...(wired.host ? { host: true } : {}), ...(wired.withPort ? { withPort: true } : {}) });
+        writeStackName(name);
+    }
+    // What was made of each service, from what was WRITTEN: a service is named, or declared under conventional
+    // names, only by the names that were given its address.
+    for (const { need, kind, fromScheme } of kinds) {
+        const base = { service: need.service, ...(need.image !== undefined ? { image: need.image } : {}), ...(need.family !== undefined ? { family: need.family } : {}) };
+        const written = [...(stackWritten.get(need.service) ?? [])].sort();
+        const conventional = kind !== null && need.names.length === 0;
+        stackNeeds.push({ ...base, kind, names: written, conventional,
+            note: kind === null ? (need.family === undefined ? 'an image of no family the World knows: nothing is declared for it' : `the World manages no ${need.family}: nothing is declared for it${need.names.length ? `, and ${need.names.map((entry) => entry.name).join(', ')} keep what init gives them` : ''}`)
+                : written.length === 0 ? (conventional ? (CONVENTIONAL_NAMES[kind] ? 'not told by the definition which variable names it, and its conventional names were given to another service or carry a value of another kind: nothing is written for it' : `not told by the definition which variable names it, and ${kind} has no conventional name: nothing is written for it`)
+                    : `its names (${need.names.map((entry) => entry.name).join(', ')}) were given to another service of the stack first: nothing is written for it`)
+                    : conventional ? 'not told by the definition which variable names it; the conventional names are supplied'
+                        : `the kind is told by ${fromScheme !== null ? 'a value\'s scheme' : 'the service\'s image'}` });
+    }
     // A selected twin's declared database is part of the World's infrastructure, even when the application
     // only reads that twin's issued connection URL. Do not substitute a guessed DATABASE_URL for its door.
     const infrastructurePath = resolve(out, 'world.infrastructure.yml');
@@ -906,22 +1177,145 @@ export function planWorldInit(name, repoPath, options = {}) {
         .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]));
+    // A declared provider image remains the source stack's choice through endpoint allocation.
+    const requestedImages = new Map();
+    for (const need of stack?.needs ?? [])
+        if (need.image) {
+            const kind = need.family ? FAMILY_KIND[need.family] : undefined;
+            const service = kind ? composeByKind.get(kind) : undefined;
+            if (!service)
+                continue;
+            const prior = requestedImages.get(kind);
+            if (prior && prior !== need.image)
+                throw new Error(`volter init: distinct requested ${kind} images cannot share one managed backing`);
+            requestedImages.set(kind, need.image);
+            service.image = need.image;
+        }
+    for (const need of stack?.needs ?? [])
+        if (need.originalInputs) {
+            const kind = need.family ? FAMILY_KIND[need.family] : undefined;
+            const service = kind ? composeByKind.get(kind) : undefined;
+            if (!service)
+                throw new Error(`volter init: original inputs for ${need.service} have no managed service`);
+            if (service.originalInputs && service.originalInputs.sha256 !== need.originalInputs.sha256)
+                throw new Error(`volter init: distinct original ${kind} service inputs cannot share one managed backing`);
+            service.originalInputs = need.originalInputs;
+            service.originalInputsFrom = dirname(resolve(options.needs));
+        }
+    for (const need of stack?.needs ?? [])
+        if (need.nativeServerInputs) {
+            const service = composeByKind.get('mysql');
+            if (!service || need.family !== 'mysql')
+                throw new Error('volter init: native MariaDB input has no managed MySQL service');
+            if (service.originalInputs)
+                throw new Error('volter init: a native provider cannot discard a separate original-input consumer requirement');
+            if (service.nativeServerInputs && (service.nativeServerInputs.receiptSha256 !== need.nativeServerInputs.receiptSha256
+                || service.nativeServerInputs.declarationSha256 !== need.nativeServerInputs.declarationSha256))
+                throw new Error('volter init: distinct native MariaDB services cannot share one backing');
+            service.nativeServerInputs = need.nativeServerInputs;
+            service.nativeServerInputsFrom = dirname(resolve(options.needs));
+            service.nativeCredentialAliases = need.nativeCredentialAliases ?? [];
+            service.image = need.nativeServerInputs.image;
+            service.volume = 'native-mariadb-data';
+        }
+    // The caller's MongoDB URI declares a server mode as well as connection options. Keep the raw query below,
+    // and carry its set name to the backing instead of silently serving a standalone server at that address.
+    const mongodb = composeByKind.get('mongodb');
+    if (mongodb) {
+        const sets = new Set();
+        for (const entry of infraEntries.filter(entry => entry.kind === 'mongodb' && entry.query !== undefined)) {
+            const asked = new URLSearchParams(entry.query).getAll('replicaSet');
+            if (asked.length > 1 || asked.some(value => !/^[A-Za-z][A-Za-z0-9_-]*$/.test(value))) {
+                throw new Error(`volter init: ${entry.name} must name one valid MongoDB replicaSet`);
+            }
+            for (const set of asked)
+                sets.add(set);
+        }
+        if (sets.size > 1)
+            throw new Error(`volter init: the managed MongoDB service cannot serve conflicting replicaSet names: ${[...sets].join(', ')}`);
+        if (sets.size === 1)
+            mongodb.replicaSet = [...sets][0];
+    }
+    const hostNamed = new Set(infraEntries.filter((entry) => entry.host).map((entry) => entry.name));
+    // THE PORT BESIDE A HOST IS THE WORLD'S TO SAY. A stack that names a service by host and port apart (`REDIS_HOST:
+    // redis`, `REDIS_PORT: 6379`) had its host pointed here and its port left at the stack's number, where nothing of
+    // this World listens: the port is handed out per World, so two Worlds on one machine do not meet on 6379.
+    for (const { need, kind } of kinds) {
+        const composed = kind === null ? undefined : composeByKind.get(kind);
+        if (composed === undefined)
+            continue;
+        for (const name of need.ports) {
+            const held = envRows.findIndex((row) => row.name === name);
+            if (held >= 0)
+                envRows.splice(held, 1);
+            const target = need.portTargets[name];
+            if (composed.sides && target === undefined)
+                throw new Error(`volter init: ${name} requires stack-needs version3 naming the vendor port for this multiwire service`);
+            env[name] = String(managedPort(composed, target));
+            envRows.push({ name, disposition: 'compose', source: `${stack.composeFile} service ${need.service}`, reason: `${kind} port — the World-managed infrastructure service's, in place of the stack's own number` });
+        }
+    }
     for (const entry of infraEntries) {
         const composed = composeByKind.get(entry.kind);
         if (composed !== undefined) {
-            env[entry.name] = composed.url;
+            // A variable the stack set to a bare host (`REDIS_HOST: redis`) is a host, not a connection string.
+            // The World owns the authority and database. The caller's raw options
+            // remain byte-for-byte, including an explicitly empty query.
+            if (composed.sides && entry.host && entry.withPort && entry.containerPort === undefined)
+                throw new Error(`volter init: ${entry.name} requires stack-needs version3 naming the vendor port`);
+            const target = entry.containerPort ?? (entry.kind === 'clickhouse' && entry.scheme === 'clickhouse' ? 9000 : undefined);
+            const physicalPort = managedPort(composed, target);
+            const port = entry.dsnFormat && entry.endpoint === 'default-port' ? composed.containerPort : physicalPort;
+            if (entry.dsnFormat && entry.endpoint === 'default-port') {
+                if (target !== composed.containerPort)
+                    throw new Error(`volter init: ${entry.name} default port differs from its declared listener`);
+                composed.virtualTcpEndpoint ??= { version: 1, host: `w${fnv1a(name).toString(16)}-${composed.kind}.world.volter.internal`, port, targetPort: physicalPort };
+            }
+            // URL.protocol cannot change a special HTTP URL into the non-special native scheme.
+            const connection = new URL(entry.kind === 'clickhouse' && port !== composed.hostPort
+                ? composed.url.replace(/^http:/, 'clickhouse:') : composed.url);
+            if (entry.dsnFormat && entry.endpoint === 'default-port')
+                connection.hostname = composed.virtualTcpEndpoint.host;
+            connection.port = String(port);
+            if (entry.dsnFormat) {
+                (composed.connectionBindings ??= {})[entry.name] = { dsnFormat: entry.dsnFormat, endpoint: entry.endpoint,
+                    dsnPrefix: entry.dsnPrefix, dsnProtocol: entry.dsnProtocol, containerPort: entry.containerPort, ...(entry.query !== undefined ? { query: entry.query } : {}) };
+            }
+            env[entry.name] = entry.dsnFormat ? renderGoMysqlBinding(entry, connection, port)
+                : entry.host ? (entry.withPort ? `127.0.0.1:${port}` : '127.0.0.1')
+                    : `${entry.kind === 'clickhouse' ? connection.toString() : composed.url}${entry.query !== undefined ? `?${entry.query}` : ''}`;
             envRows.push({
                 name: entry.name,
                 disposition: 'compose',
                 source: entry.source,
-                reason: `${entry.kind} connection string — points at the World-managed infrastructure service`,
+                reason: entry.dsnFormat ? 'mysql connection in its declared Go driver grammar — from the World-managed provider' : entry.host
+                    ? (entry.withPort ? `${entry.kind} host and port — the World-managed infrastructure service's` : `${entry.kind} host — the World-managed infrastructure service's (its port is ${composed.hostPort}; a port variable beside it is not set by this)`)
+                    : `${entry.kind} connection string — points at the World-managed infrastructure service`,
             });
         }
         else {
+            if (entry.dsnFormat)
+                throw new Error(`volter init: ${entry.name} needs a supplied MySQL service for its declared Go driver grammar`);
             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` });
         }
     }
+    // A split field comes from the same connection as the host/URL. It is not
+    // an endpoint signal: discovery must never replace a scalar with a URL.
+    for (const [name, binding] of stackComponents) {
+        const composed = composeByKind.get(binding.kind);
+        if (!composed)
+            throw new Error(`volter init: ${name} needs a managed ${binding.kind} connection for its ${binding.component}`);
+        const url = new URL(composed.url);
+        const held = envRows.findIndex(row => row.name === name);
+        if (held >= 0)
+            envRows.splice(held, 1);
+        const value = decodeURIComponent(binding.component === 'database' ? url.pathname.slice(1) : binding.component === 'user' ? url.username : url.password);
+        if (value === '')
+            throw new Error(`volter init: ${name} asks for a ${binding.component} the managed ${binding.kind} connection does not provide`);
+        env[name] = value;
+        envRows.push({ name, disposition: 'compose', source: binding.source, reason: `${binding.kind} ${binding.component} — from the World-managed connection, beside its host and port` });
+    }
     const infra = [...infraSignals.entries()]
         .filter(([kind]) => !composeByKind.has(kind))
         .sort(([a], [b]) => a.localeCompare(b))
@@ -961,7 +1355,10 @@ 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}`, ...(['postgres', 'mysql', 'mongodb', 'redis'].includes(service.kind) ? { protocol: service.kind } : {}) }))),
+                // Only a connection string is discovered: status publishes the values that are a URL at the service's own
+                // port (infraConnections), so a variable that holds a bare host (`REDIS_HOST: redis`, written above as
+                // 127.0.0.1) is never among them, and asking for it made `up` fail on a World whose services were ready.
+                discover: compose.flatMap((service) => service.signals.filter((name) => !hostNamed.has(name)).map((name) => ({ as: name, jsonPath: `connections.${name}`, ...(['postgres', 'mysql', 'mongodb', 'redis', 'clickhouse'].includes(service.kind) ? { protocol: service.kind === 'clickhouse' ? (env[name]?.startsWith('clickhouse:') ? 'clickhouse' : 'http') : service.kind } : {}) }))),
                 down: ['volter-world-infra', 'down'],
                 readyWhen: { command: 'volter-world-infra', args: ['status'], timeoutMs: 120000, intervalMs: 500 },
             },
@@ -1058,6 +1455,7 @@ export function planWorldInit(name, repoPath, options = {}) {
             ? [] : projectMigrationTools(repo),
         infra,
         compose,
+        ...(stack ? { stackNeeds, stackEnvironmentNames, leftAsThePersonsOwn: filesLeftAsThePersonsOwn() } : {}),
         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.
@@ -1135,7 +1533,22 @@ export function writeWorldInit(plan, options = {}) {
     // Recheck the planned name-derived paths before any output is written.
     for (const copy of plan.defaultsCopies)
         ownedPath(plan.out, relative(plan.out, copy.to));
+    for (const service of plan.compose)
+        if (service.nativeServerInputs)
+            ownedPath(plan.out, `native-inputs/${service.nativeServerInputs.receiptSha256}/${service.nativeServerInputs.declarationSha256}`);
     mkdirSync(plan.out, { recursive: true });
+    for (const service of plan.compose)
+        if (service.nativeServerInputs) {
+            if (!service.nativeServerInputsFrom)
+                throw new Error('Native managed input has no retained source parent');
+            copyNativeServerInputs(service.nativeServerInputsFrom, service.nativeServerInputs, plan.out);
+        }
+    for (const service of plan.compose)
+        if (service.originalInputs) {
+            if (!service.originalInputsFrom)
+                throw new Error('Original inputs have no retained source parent');
+            copyOriginalInputSnapshot(service.originalInputsFrom, service.originalInputs, plan.out);
+        }
     writeFileSync(plan.configPath, `${JSON.stringify(worldConfigDocument(plan.config), null, 2)}\n`);
     if (plan.inRepo)
         writeFileSync(join(plan.out, '.gitignore'), STATE_GITIGNORE);
@@ -1253,6 +1666,7 @@ export function initWorld(name, repoPath, options = {}) {
         root: resolve(options.root ?? process.cwd()),
         allowUnknown: options.allowUnknown ?? false,
         acknowledge: options.acknowledge ?? {},
+        ...(plan.stackEnvironmentNames ? { declaredEnvironmentNames: plan.stackEnvironmentNames } : {}),
     });
     // 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.
@@ -1342,6 +1756,19 @@ export function formatInitReport(result) {
         }
         lines.push('  Resolve these before expecting the app to listen. Vendor coverage can be green while the app rejects its own env.');
     }
+    if (plan.stackNeeds !== undefined) {
+        const told = (test) => plan.stackNeeds.filter(test).length;
+        lines.push('');
+        lines.push('READ FOR AN IMAGE: only files the project\'s source holds were read (--needs).');
+        for (const file of plan.leftAsThePersonsOwn ?? [])
+            lines.push(`  ${file} is the person's own and was not read`);
+        lines.push(`THE PROJECT'S OWN STACK (${plan.stackNeeds.length} service${plan.stackNeeds.length === 1 ? '' : 's'} beside the application): `
+            + `${told((need) => need.kind !== null && !need.conventional && need.names.length > 0)} given their address under the stack's own variables, ${told((need) => need.conventional && need.names.length > 0)} under conventional names, `
+            + `${told((need) => need.kind !== null && need.names.length === 0)} of a managed kind with nothing written, ${told((need) => need.kind === null)} the World has no kind for`);
+        for (const need of plan.stackNeeds) {
+            lines.push(`  ${need.service}${need.image ? ` (${need.image})` : ''}: ${need.kind ?? 'no managed kind'}${need.names.length ? ` — ${need.names.join(', ')}` : ''}; ${need.note}`);
+        }
+    }
     if (plan.undeclaredMigrations.length > 0) {
         lines.push('');
         lines.push(`MIGRATION TOOL FOUND, NO STEP DECLARED (${plan.undeclaredMigrations.length}):`);