@volter/world-runtime 3.0.163 → 3.0.165

package/src/init.ts

@@ -1,3 +1,7 @@
+import { copyNativeServerInputs, readNativeServerInputs, nativeServerRuntimeReference, type NativeServerInputs } from './native-server-inputs.ts';
+import { goMysqlBinding, renderGoMysqlBinding, type GoMysqlBinding } from './go-mysql-binding.ts';
+import * as managedOriginalInputs from '@volter/world-core/managed-original-inputs';
+import { copyOriginalInputSnapshot, readOriginalInputSnapshot, type OriginalInputReference } from './original-inputs.ts';
 // `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';
@@ -51,7 +56,7 @@ import {
 import { fakeEnvValue, isAppKeyName, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from './fixture-env.ts';
 import { findInstalledPackage, packCli, packEntry, resolveCatalog, type Catalog } from './catalog.ts';
 import { CATALOG_INDEX_PACKAGE, defaults as catalogDefaults } from './catalog-index.ts';
-import { projectEnvReads, projectManifestDirs, projectMigrationTools, type ProjectMigrationTool } from './project-inspect.ts';
+import { filesLeftAsThePersonsOwn, projectEnvReads, projectManifestDirs, projectMigrationTools, readOnlyWhatTheSourceHolds, sourceText, type ProjectMigrationTool } from './project-inspect.ts';
 import { overlayEndpointEnv, packFacts } from './pack-facts.ts';
 import { VENDOR_SERVER_BACKINGS } from './backings.ts';
 import { APP_URL_ENV, DEFAULT_WORLD_SELECTION, ISSUE_ENV_PREFIX, MINT_ENV, worldConfigDocument, worldSelectionIncludes, type WorldConfig, type WorldSelection, type WorldServiceConfig } from './schema.ts';
@@ -173,9 +178,20 @@ export type InitInfraStub = {
 export type InitComposeService = {
   kind: string;
   image: string;
+  /** An explicit MongoDB connection mode, also carried to the selected backing. */
+  replicaSet?: string;
   /** deterministic host port, derived from the world name (see composePort) */
   hostPort: number;
   containerPort: number;
+  virtualTcpEndpoint?: { version: 1; host: string; port: number; targetPort: number };
+  connectionBindings?: Record<string, GoMysqlBinding & { containerPort: number; query?: string }>;
+  sides?: Record<string, { hostPort: number; containerPort: number }>;
+  configuration?: Record<string, unknown>;
+  originalInputs?: OriginalInputReference;
+  originalInputsFrom?: string;
+  nativeServerInputs?: NativeServerInputs;
+  nativeServerInputsFrom?: string;
+  nativeCredentialAliases?: string[];
   memoryMiB: number;
   /** compose volume key, or null (the on-disk docker volume is `<project>_<key>` — the compose
    * project name carries the world name, so volumes are named per world) */
@@ -208,6 +224,12 @@ export type InitPlan = {
    *  (runtime.database.prepare): reported, never written, and no part of the vendor-coverage verdict */
   undeclaredMigrations: ProjectMigrationTool[];
   infra: InitInfraStub[];
+  /** each service of the project's own stack and what was made of it, where `--needs` gave the stack */
+  stackNeeds?: InitStackNeed[];
+  /** The same declared application names used by selection and its coverage proof. */
+  stackEnvironmentNames?: string[];
+  /** the project files a World made for an image left unread: the source does not hold them, so they are the person's own */
+  leftAsThePersonsOwn?: string[];
   /** the services emitted into the private managed-infrastructure definition */
   compose: InitComposeService[];
   /** private managed-infrastructure definition, or null when no detected infra has a recipe */
@@ -271,8 +293,104 @@ export type InitOptions = {
   sources?: Record<string, string>;
   /** A world with no app: served as `/<org>/<world>/`. */
   bare?: string;
+  /** The project's own stack as its image builder read it (`needs.json`): architecture, "The project's own stack as evidence". */
+  needs?: string;
 };
 
+/** One service of the project's stack, as `init` took it. */
+export type InitStackNeed = {
+  service: string;
+  image?: string;
+  family?: string;
+  /** the managed kind it is, or null where the World has none for it */
+  kind: string | null;
+  /** the application's variables given this service's address */
+  names: string[];
+  /** true where the stack named no variable and the conventional names were supplied */
+  conventional: boolean;
+  note: string;
+};
+
+/** The families the image builder names (its SERVICE_FAMILIES) that are a managed kind here. */
+const FAMILY_KIND: Record<string, string> = { postgres: 'postgres', mysql: 'mysql', mongodb: 'mongodb', redis: 'redis', search: 'search', clickhouse: 'clickhouse', memcached: 'memcached' };
+const CONVENTIONAL_NAMES: Record<string, string[]> = { postgres: ['DATABASE_URL'], mysql: ['DATABASE_URL'], mongodb: ['MONGODB_URI'], redis: ['REDIS_URL'], clickhouse: ['CLICKHOUSE_URL'] };
+
+type StackConnectionComponent = "database" | "user" | "password";
+
+
+type StackNeedsFile = { kind?: unknown; version?: unknown; composeFile?: unknown; application?: { service?: unknown }; settings?: unknown; unset?: unknown; needs?: Array<{ service?: unknown; image?: unknown; family?: unknown; supplier?: unknown; names?: Array<{ name?: unknown; scheme?: unknown; query?: unknown; withPort?: unknown; containerPort?: unknown; dsnFormat?: unknown; endpoint?: unknown; dsnPrefix?: unknown; dsnProtocol?: unknown }>; ports?: unknown; portTargets?: unknown; components?: unknown; originalInputs?: unknown; nativeServerInputs?: unknown }> };
+
+/** The needs file, checked for its kind: a file of another shape is refused by name, never half-read. */
+function readStackNeeds(path: string): { composeFile: string; application?: string; settings: Array<{ name: string; value: string }>; unset: string[]; needs: Array<{ service: string; image?: string; family?: string; names: Array<{ name: string; scheme?: string; query?: string; withPort?: true; containerPort?: number } & Partial<GoMysqlBinding>>; originalInputs?: OriginalInputReference; nativeServerInputs?: NativeServerInputs; nativeCredentialAliases?: string[]; ports: string[]; portTargets: Record<string, number>; components: Array<{ name: string; component: StackConnectionComponent }> }> } {
+  let document: StackNeedsFile;
+  try { document = JSON.parse(readFileSync(path, 'utf8')) as StackNeedsFile; }
+  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: string, what: string): string => {
+    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: unknown): Array<[string, unknown]> => value && typeof value === 'object' && !Array.isArray(value) ? Object.entries(value as Record<string, unknown>) : [];
+  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 as string })),
+    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 as string,
+      ...(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 as { raw?: unknown } | undefined;
+        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')) as { name?: unknown; image?: { raw?: unknown } };
+        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 as const } : {}) };
+      }),
+      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: unknown) => {
+          if (!part || typeof part !== 'object' || Array.isArray(part)) throw new Error(`volter init: --needs ${path} has an invalid store component`);
+          const field = part as { name?: unknown; component?: unknown };
+          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 as StackConnectionComponent };
+        });
+      })(),
+      // 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 as unknown[] : []).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
 // ---------------------------------------------------------------------------------------------
@@ -485,6 +603,14 @@ const COMPOSE_INFRA: Record<string, {
   /** healthcheck exec-form argv (makes `docker compose up -d --wait` meaningful) */
   healthcheck: (user: string) => string[];
 }> = {
+  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,
@@ -506,8 +632,8 @@ const COMPOSE_INFRA: Record<string, {
     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,
@@ -564,11 +690,14 @@ function composeService(name: string, kind: string, signals: string[], taken: Se
   // 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'
+    : 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,
@@ -585,12 +714,20 @@ function composeEnvironment(name: string, kind: string): Array<[string, string]>
   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: InitComposeService, containerPort?: number): number {
+  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: InitPlan): string {
@@ -604,13 +741,42 @@ export function renderComposeFile(plan: InitPlan): string {
   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) lines.push(`      ${key}: ${value}`);
@@ -668,8 +834,10 @@ function repoEnvEntries(repo: string): ParsedEnvEntry[] {
     for (const file of ENV_SOURCE_FILES) {
       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);
         byName.set(entry.name, [...(byName.get(entry.name) ?? []), { ...entry, dir }]);
@@ -707,7 +875,11 @@ function isInside(parent: string, candidate: string): boolean {
 
 export function planWorldInit(name: string, repoPath: string, options: InitOptions = {}): InitPlan {
   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);
   // The world lives in the app repo: `.volter/world.json` beside the code, committed like a
@@ -729,16 +901,18 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
    *  (portable between teammates), absolute otherwise (a pilot emitted away from its root) */
   const carried = (path: string): string => (isInside(root, path) ? relative(root, path) : path);
 
-  const catalogSource: Catalog = resolveCatalog(root, { sources: options.sources, vendors: options.vendors });
+  const catalogSource: Catalog = 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
-  const indexDir = findInstalledPackage(root, CATALOG_INDEX_PACKAGE);
+  const indexDir = options.vendors?.length === 0 ? undefined : findInstalledPackage(root, CATALOG_INDEX_PACKAGE);
   // A pack's starters, copied VISIBLY into the world dir: the author's to edit or delete (copy = ownership; never
   // 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: InitPlan['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<string, string[]>(options.vendors.map((v) => [v, ['--twins']]))
     : new Map([...signals!.detected].filter(([vendor]) => (signals!.uses.get(vendor) ?? []).some((use) => worldSelectionIncludes(selection, vendor, use.usage))));
@@ -889,7 +1063,31 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
   const envReads = projectEnvReads(repo);
   const mintedEnv: string[] = [];
   const infraSignals = new Map<string, string[]>();
-  const infraEntries: Array<{ name: string; source: string; kind: string }> = [];
+  const infraEntries: Array<{ name: string; source: string; kind: string; query?: string; host?: true; withPort?: true; scheme?: string; containerPort?: number } & Partial<GoMysqlBinding>> = [];
+  // 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<string, { kind: string; source: string; host: boolean; withPort: boolean; query?: string; scheme?: string; containerPort?: number; service: string; conventional: boolean } & Partial<GoMysqlBinding>>();
+  const stackNeeds: InitStackNeed[] = [];
+  /** The names actually given each service's address, filled where an entry is written: the report counts these. */
+  const stackWritten = new Map<string, string[]>();
+  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: string): void => {
+    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
@@ -914,6 +1112,15 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     ...(existing?.services ?? []),
     ...services.filter((service) => !existingIds.has(service.id)),
   ].flatMap(endpointNames));
+  const stackComponents = new Map<string, { kind: string; source: string; service: string; component: StackConnectionComponent }>();
+  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.
@@ -922,7 +1129,18 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     for (const name of Object.keys(service.issues?.fill ?? {})) if (!issuedBy.has(name)) issuedBy.set(name, service.id);
   }
   const standInStems = new Set<string>();
-  for (const entry of repoEnvEntries(repo)) {
+  // 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: ParsedEnvEntry[] = 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;
     // World-owned names: the world INJECTS these at boot from the services above. Carrying a repo's
@@ -993,12 +1211,29 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
       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 as const } : {}), ...(wired?.withPort ? { withPort: true as const } : {}) });
       continue;
     }
     // A detected vendor's endpoint at a loopback server is the repository's local stand-in for the vendor (a garage for
@@ -1013,8 +1248,16 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     // 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 !== '') {
@@ -1069,6 +1312,32 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     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 as const } : {}), ...(wired.withPort ? { withPort: true as const } : {}) });
+    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');
@@ -1095,22 +1364,125 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     .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<string, string>();
+  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<string>();
+    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 as GoMysqlBinding & typeof 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: InitInfraStub[] = [...infraSignals.entries()]
     .filter(([kind]) => !composeByKind.has(kind))
     .sort(([a], [b]) => a.localeCompare(b))
@@ -1151,7 +1523,10 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
       external: {
         up: ['volter-world-infra', 'up'],
         status: ['volter-world-infra', 'status'],
-        discover: compose.flatMap((service) => service.signals.map((name) => ({ as: name, jsonPath: `connections.${name}`, ...(['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 },
       },
@@ -1250,6 +1625,7 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
       ? [] : 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.
@@ -1330,7 +1706,17 @@ export function writeWorldInit(plan: InitPlan, options: { force?: boolean } = {}
   }
   // 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);
   writeFileSync(plan.envPath, renderEnvFile(plan));
@@ -1448,6 +1834,7 @@ export function initWorld(name: string, repoPath: string, options: InitOptions =
     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.
@@ -1538,6 +1925,18 @@ export function formatInitReport(result: InitResult): string {
     }
     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: (need: InitStackNeed) => boolean): number => 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}):`);