@volter/world-runtime 3.0.165 → 3.0.167

package/src/init.ts

@@ -1,5 +1,8 @@
+import { withCurrentCredentialDoor } from './credential-door.ts';
+import { composeManagedApiNeeds9, type ManagedApiOwner } from './managed-api-needs.ts';
+import { readManagedApiSourceSession, type ManagedApiSourceReader, type ManagedApiSourceSession } from './managed-api-source.ts';
 import { copyNativeServerInputs, readNativeServerInputs, nativeServerRuntimeReference, type NativeServerInputs } from './native-server-inputs.ts';
-import { goMysqlBinding, renderGoMysqlBinding, type GoMysqlBinding } from './go-mysql-binding.ts';
+import { goMysqlBinding, goMysqlBindingFields, 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.
@@ -59,7 +62,7 @@ import { CATALOG_INDEX_PACKAGE, defaults as catalogDefaults } from './catalog-in
 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';
+import { APP_URL_ENV, DEFAULT_WORLD_SELECTION, ISSUE_ENV_PREFIX, MINT_ENV, assertWorldConfig, worldConfigDocument, worldSelectionIncludes, type WorldConfig, type WorldSelection, type WorldServiceConfig } from './schema.ts';
 import { loadWorldConfig } from './configs.ts';
 import { parseInfraDefinition } from './pglite-backing.ts';
 import { ownedPath } from './owned-path.ts';
@@ -228,6 +231,8 @@ export type InitPlan = {
   stackNeeds?: InitStackNeed[];
   /** The same declared application names used by selection and its coverage proof. */
   stackEnvironmentNames?: string[];
+  /** Equality/cache identity from the live trusted reader; this digest grants no source custody. */
+  readonly applicationApiSourceIdentity?: 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 */
@@ -295,6 +300,8 @@ export type InitOptions = {
   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;
+  /** Reviewed host attachment to immutable source/correspondence. No CLI flag or JSON bit selects it. */
+  managedApiSourceReader?: ManagedApiSourceReader;
 };
 
 /** One service of the project's stack, as `init` took it. */
@@ -321,11 +328,15 @@ 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 }> }> } {
+function readStackNeeds(path: string, repo: string, apiReader?: ManagedApiSourceReader): { apiSource?: ManagedApiSourceSession; 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)) {
+  // A plain CLI has no trusted function and retains its explicit version9 refusal.
+  const apiSource = document.version === 9 ? readManagedApiSourceSession(repo, path, apiReader) : undefined;
+  if (apiReader !== undefined && apiSource === undefined) throw new Error('volter init: an API source reader cannot be ignored by a non-version9 input');
+  if (apiSource) document = apiSource.document;
+  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 && document.version !== 9) || !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 => {
@@ -334,6 +345,7 @@ function readStackNeeds(path: string): { composeFile: string; application?: stri
   };
   const record = (value: unknown): Array<[string, unknown]> => value && typeof value === 'object' && !Array.isArray(value) ? Object.entries(value as Record<string, unknown>) : [];
   return {
+    ...(apiSource === undefined ? {} : { apiSource }),
     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
@@ -343,7 +355,7 @@ function readStackNeeds(path: string): { composeFile: string; application?: stri
     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');
+        if (document.version !== 4 && document.version !== 5 && document.version !== 6 && document.version !== 7 && document.version !== 9) 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;
@@ -351,7 +363,7 @@ function readStackNeeds(path: string): { composeFile: string; application?: stri
         return reference;
       })() }),
       ...(need.nativeServerInputs === undefined ? {} : (() => {
-        if (document.version !== 5 && document.version !== 7) throw new Error('volter init: native managed input requires needs5 or7');
+        if (document.version !== 5 && document.version !== 7 && document.version !== 9) 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)
@@ -364,12 +376,12 @@ function readStackNeeds(path: string): { composeFile: string; application?: stri
         // 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 } : {}) };
+        if (entry.containerPort !== undefined && ((document.version !== 3 && document.version !== 4 && document.version !== 5 && document.version !== 6 && document.version !== 7 && document.version !== 9) || !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, ...(apiSource ? goMysqlBindingFields(entry, entry.name, COMPOSE_INFRA.mysql!.containerPort) : 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`);
+        if ((document.version !== 2 && document.version !== 3 && document.version !== 4 && document.version !== 5 && document.version !== 6 && document.version !== 7 && document.version !== 9) || !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 };
@@ -381,7 +393,7 @@ function readStackNeeds(path: string): { composeFile: string; application?: stri
       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`);
+        if ((document.version !== 3 && document.version !== 4 && document.version !== 5 && document.version !== 6 && document.version !== 7 && document.version !== 9) || !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)];
@@ -448,8 +460,8 @@ overlayEndpointEnv(APP_READ_ENDPOINT_ENV);
 /** A twin service with its pack's credential door (`issues`) as the pack declares it now: a service kept from a saved
  *  config gets the current door, so its names are issued by the door the pack has, never by a copy it has since fixed. */
 function withIssues(service: WorldServiceConfig): WorldServiceConfig {
-  const door = service.type === 'twin' ? packFacts()[service.id]?.credentialDoor : undefined;
-  return door === undefined ? service : { ...service, issues: door };
+  if ((service.type ?? 'twin') !== 'twin') return service;
+  return withCurrentCredentialDoor(service, packFacts()[service.id]?.credentialDoor);
 }
 
 function wiringFor(vendor: string): {
@@ -893,9 +905,20 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
   if (existing?.manifestVersion === 1) {
     throw new Error(`volter init: ${configPath} uses legacy format 1; run \`volter-world migrate-config ${configPath}\` before regenerating it`);
   }
-  const selection: WorldSelection = options.vendors
+  if (options.managedApiSourceReader !== undefined && options.needs === undefined) throw new Error('volter init: an API source reader requires its explicit needs input');
+  const stack = options.needs ? readStackNeeds(resolve(options.needs), repo, options.managedApiSourceReader) : undefined;
+  const apiSource = stack?.apiSource;
+  const apiVendors = [...new Set(apiSource?.document.applicationApis.map(row => row.vendor) ?? [])];
+  const baseSelection: WorldSelection = options.vendors
     ? { include: options.vendors.map((vendor) => ({ vendor })), exclude: [] }
     : existing?.selection ?? DEFAULT_WORLD_SELECTION;
+  for (const vendor of apiVendors) {
+    if (options.vendors !== undefined && !options.vendors.includes(vendor)) throw new Error(`volter init: API vendor ${vendor} conflicts with the explicit twin selection`);
+    if (baseSelection.exclude.some(item => (item.vendor === undefined || item.vendor === vendor) && (item.usage === undefined || item.usage === 'application')))
+      throw new Error(`volter init: API vendor ${vendor} conflicts with the saved selection exclusion`);
+  }
+  // A source API choice participates in deliberate selection without dropping existing included vendors.
+  const selection: WorldSelection = apiSource ? { include: [...baseSelection.include, ...apiVendors.filter(vendor => !baseSelection.include.some(item => item.vendor === vendor && item.usage === 'application')).map(vendor => ({ vendor, usage: 'application' as const }))], exclude: [...baseSelection.exclude] } : baseSelection;
   const inRepo = isInside(repo, out);
   /** 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) */
@@ -910,8 +933,8 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
   // 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 stack = options.needs ? readStackNeeds(resolve(options.needs)) : undefined;
-  const stackEnvironmentNames = stack ? [...new Set([...stack.settings.map(entry => entry.name), ...stack.unset])].sort() : [];
+  const apiNames = apiSource?.document.applicationApis.flatMap(row => [...row.endpoints, ...Object.keys(row.credentials)]) ?? [];
+  const stackEnvironmentNames = stack ? [...new Set([...stack.settings.map(entry => entry.name), ...stack.unset, ...apiNames])].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']]))
@@ -920,6 +943,8 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     ? new Map<string, string[]>()
     : new Map([...signals!.unknown].filter(([vendor]) => (signals!.unknownUses.get(vendor) ?? []).some((use) => worldSelectionIncludes(selection, vendor, use.usage))));
 
+  for (const vendor of apiVendors) detected.set(vendor, [...(detected.get(vendor) ?? []), `--needs ${stack!.composeFile} service ${apiSource!.document.application.service} explicit ${vendor}/s3 API`]);
+
   const vendors: InitVendorPlan[] = [];
   const services: WorldServiceConfig[] = [];
   const existingIds = new Set(existing?.services.map((service) => service.id) ?? []);
@@ -1055,8 +1080,48 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     });
   }
 
+  // Resolve the actual selected catalog service, never the application service or a writer-invented id.
+  const apiOwnerIds = new Map<string, string>();
+  // Bind every source/execution field, including the extra Node loaders and environment used by startService.
+  // Environment key order is documentary; preload and argv order change execution. Readiness can run a child too.
+  const ownerExecution = (service: WorldServiceConfig): string => JSON.stringify([
+    service.type ?? 'twin', service.package ?? null, service.version ?? null,
+    service.command ?? null, service.args ?? [], service.cwd ?? null, service.rootArg ?? null, service.portArg ?? null,
+    service.colocate?.module ?? null, service.colocate?.export ?? null, service.colocate?.scenarioPath ?? null,
+    service.preload ?? [], Object.entries(service.env ?? {}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0),
+    service.controlPlane ?? false, service.branchState ?? null, service.external ?? null,
+    service.ready === undefined || service.ready === 'tcp' ? null : [
+      service.ready.command ?? null, service.ready.args ?? [], service.ready.httpUrl ?? null,
+      service.ready.timeoutMs ?? null, service.ready.intervalMs ?? null,
+    ],
+  ]);
+  const apiOwnerExecutions = new Map<string, string>();
+  for (const vendor of apiVendors) {
+    const selected = vendors.find(row => row.vendor === vendor);
+    if (!selected?.service || selected.service.type !== 'twin' || !catalog.has(vendor) || packFacts()[vendor]?.credentialDoor === undefined)
+      throw new Error(`volter init: explicit ${vendor}/s3 API has no actual selected twin/current credential door`);
+    const resolved = services.find(service => service.id === selected.service!.id);
+    if (!resolved || ownerExecution(selected.service) !== ownerExecution(resolved)) throw new Error(`volter init: API owner ${selected.service.id} does not use its resolved catalog execution; revalidate the saved source`);
+    apiOwnerIds.set(vendor, selected.service.id);
+    apiOwnerExecutions.set(selected.service.id, ownerExecution(selected.service));
+  }
+  const apiOwners = (): ManagedApiOwner[] => apiVendors.map((vendor): ManagedApiOwner => ({ vendor, api: 's3', serviceId: apiOwnerIds.get(vendor)!, currentDoor: packFacts()[vendor]?.credentialDoor }));
+  const composedServices = new Map<string, WorldServiceConfig>();
+  const currentService = (service: WorldServiceConfig): WorldServiceConfig => composedServices.get(service.id) ?? withIssues(service);
+  if (apiSource) {
+    apiSource.assertCurrent();
+    const base: WorldConfig = { ...existing, id: name, manifestVersion: 2, selection,
+      env: { ...(existing?.env ?? {}) }, services: [...(existing?.services ?? []).map(withIssues), ...services.filter(service => !existingIds.has(service.id))] };
+    const proposed = composeManagedApiNeeds9({ document: apiSource.document, world: worldConfigDocument(base),
+      application: apiSource.application, owners: apiOwners() });
+    for (const service of assertWorldConfig(proposed.manifest, 'needs9 issuer planning').services) if (apiOwnerExecutions.has(service.id)) composedServices.set(service.id, service);
+    // Keep normal later bindings on the same owner object, and leave unrelated service objects untouched.
+    for (let i = 0; i < services.length; i++) services[i] = composedServices.get(services[i]!.id) ?? services[i]!;
+    for (const vendor of vendors) if (vendor.service) vendor.service = currentService(vendor.service);
+  }
+
   // --- env ------------------------------------------------------------------------------------
-  const env: Record<string, string> = {};
+  const env: Record<string, string> = apiSource ? Object.create(null) : {};
   const envRows: InitEnvRow[] = [];
   const envSources: string[] = [];
   const bootRisks: InitBootRisk[] = [];
@@ -1125,7 +1190,7 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
   // 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.
   const issuedBy = new Map<string, string>();
-  for (const service of [...(existing?.services ?? []).map(withIssues), ...services.filter((service) => !existingIds.has(service.id))]) {
+  for (const service of [...(existing?.services ?? []), ...services.filter((service) => !existingIds.has(service.id))].map(currentService)) {
     for (const name of Object.keys(service.issues?.fill ?? {})) if (!issuedBy.has(name)) issuedBy.set(name, service.id);
   }
   const standInStems = new Set<string>();
@@ -1533,7 +1598,14 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     });
   }
 
-  const mergedServices = existing === undefined ? services : [...existing.services.map(withIssues), ...services.filter((service) => !existingIds.has(service.id))];
+  // An inherited/bare explicit alias may not have entered generic env rows; it still has its exact owner.
+  if (apiSource) for (const row of apiSource.document.applicationApis) for (const alias of Object.keys(row.credentials)) {
+    const owner = apiOwnerIds.get(row.vendor)!;
+    if (Object.hasOwn(env, alias) && env[alias] !== `${ISSUE_ENV_PREFIX}${owner}`) throw new Error(`volter init: explicit API alias ${alias} conflicts with its generated pending owner`);
+    env[alias] = `${ISSUE_ENV_PREFIX}${owner}`;
+    if (!envRows.some(entry => entry.name === alias)) envRows.push({ name: alias, disposition: 'issued', source: `${stack!.composeFile} service ${row.service} explicit API`, reason: `${owner} source-required scalar alias; up asks its current credential door` });
+  }
+  const mergedServices = (existing === undefined ? services : [...existing.services, ...services.filter((service) => !existingIds.has(service.id))]).map(currentService);
   if (existing !== undefined) {
     const owners = new Map<string, string>();
     for (const service of mergedServices) {
@@ -1560,7 +1632,7 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     ...(Array.isArray(savedInfra) ? savedInfra : []),
     ...infra.filter((entry) => !savedInfraIds.has(entry.stub.id)).map((entry) => entry.stub),
   ];
-  const config: WorldConfig & { '//infra'?: unknown[]; catalog?: { sha: string } } = {
+  let config: WorldConfig = {
     ...comments,
     id: name,
     manifestVersion: 2,
@@ -1595,7 +1667,13 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     ...(mergedInfra.length ? { '//infra': mergedInfra } : {}),
   };
 
-  return {
+  if (apiSource) {
+    apiSource.assertCurrent();
+    config = assertWorldConfig(composeManagedApiNeeds9({ document: apiSource.document, world: worldConfigDocument(config),
+      application: apiSource.application, owners: apiOwners() }).manifest, 'needs9 final init planning');
+  }
+
+  const plan: InitPlan = {
     name,
     repo,
     out,
@@ -1615,7 +1693,8 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
       ? { entryPath: resolve(out, 'seed.ts'), storyPath: resolve(out, 'seeds', 'story.ts') }
       : null,
     config,
-    env: config.env as Record<string, string>,
+    env: config.env ?? {},
+    ...(apiSource === undefined ? {} : { applicationApiSourceIdentity: apiSource.identity }),
     vendors,
     envRows,
     envSources,
@@ -1636,6 +1715,27 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
       .sort((a, b) => a.name.localeCompare(b.name)),
     mintedEnv: [...mintedEnv].sort(),
   };
+  // Every emission starts from this planner's original object, never from a copied identity marker.
+  initPlanChecks.set(plan, () => {});
+  if (apiSource) {
+    Object.defineProperty(plan, 'applicationApiSourceIdentity', { value: apiSource.identity, enumerable: true, writable: false, configurable: false });
+    initPlanChecks.set(plan, () => {
+      apiSource.assertCurrent();
+      if (plan.applicationApiSourceIdentity !== apiSource.identity) throw new Error('needs9 plan lost its source comparison identity');
+      for (const [id, execution] of apiOwnerExecutions) {
+        const owner = plan.config.services.find(service => service.id === id);
+        if (!owner || ownerExecution(owner) !== execution) throw new Error(`needs9 selected owner ${id} changed its catalog execution after planning`);
+      }
+      const expectedEnv = plan.config.env ?? {};
+      if (Object.keys(plan.env).length !== Object.keys(expectedEnv).length || Object.keys(expectedEnv).some(key => !Object.hasOwn(plan.env, key) || plan.env[key] !== expectedEnv[key]))
+        throw new Error('needs9 init environment preview differs from its planned World environment');
+      const actual = worldConfigDocument(plan.config);
+      const checked = composeManagedApiNeeds9({ document: apiSource.document, world: actual,
+        application: apiSource.application, owners: apiOwners() }).manifest;
+      if (JSON.stringify(checked) !== JSON.stringify(actual)) throw new Error('needs9 planned bindings differ from the current source/descriptor composition');
+    });
+  }
+  return plan;
 }
 
 // ---------------------------------------------------------------------------------------------
@@ -1695,7 +1795,25 @@ browsers/
 keys.json
 `;
 
+function initConfigDocument(config: WorldConfig, path: string): ReturnType<typeof worldConfigDocument> {
+  try {
+    // Validate the saved shape before composition can replace an issuer or discard an unknown field.
+    worldConfigDocument(config);
+    return worldConfigDocument({ ...config, services: config.services.map(withIssues) });
+  } catch (error) {
+    throw new Error(`volter init: invalid credential/config carrier at ${path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}
+
+const initPlanChecks = new WeakMap<InitPlan, () => void>();
+function assertApiPlanCurrent(plan: InitPlan): void {
+  const check = initPlanChecks.get(plan);
+  if (!check) throw new Error('volter init: output requires the original live init plan; copied or serialized plans must be planned again');
+  check();
+}
+
 export function writeWorldInit(plan: InitPlan, options: { force?: boolean } = {}): void {
+  assertApiPlanCurrent(plan);
   // A world already here is refused unless forced; a `.volter/` holding only running state
   // (worlds/, an env) is not a world and does not block init.
   if (existsSync(plan.configPath) && options.force !== true) {
@@ -1704,6 +1822,9 @@ export function writeWorldInit(plan: InitPlan, options: { force?: boolean } = {}
       + 'Pass --force to regenerate it, or --out <dir> to emit elsewhere.',
     );
   }
+  // The complete carrier and current descriptor are checked before directories, snapshots or output writes.
+  const document = initConfigDocument(plan.config, plan.configPath);
+  const configBytes = `${JSON.stringify(document, null, 2)}\n`;
   // 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)
@@ -1717,7 +1838,7 @@ export function writeWorldInit(plan: InitPlan, options: { force?: boolean } = {}
     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`);
+  writeFileSync(plan.configPath, configBytes);
   if (plan.inRepo) writeFileSync(join(plan.out, '.gitignore'), STATE_GITIGNORE);
   writeFileSync(plan.envPath, renderEnvFile(plan));
   if (plan.composePath !== null) writeFileSync(plan.composePath, renderComposeFile(plan));
@@ -1842,7 +1963,8 @@ export function initWorld(name: string, repoPath: string, options: InitOptions =
   // The proof is kept in the config it was made against, beside the selection: the report printed below, as data.
   // Written after the proof because the proof reads the config's bytes; it reads nothing of `discovery.coverage`.
   plan.config.coverage = coverageRecord(coverage);
-  writeFileSync(plan.configPath, `${JSON.stringify(worldConfigDocument(plan.config), null, 2)}\n`);
+  assertApiPlanCurrent(plan);
+  writeFileSync(plan.configPath, `${JSON.stringify(initConfigDocument(plan.config, plan.configPath), null, 2)}\n`);
   const next = plan.inRepo && resolve(options.root ?? plan.repo) === plan.repo
     ? [
         'volter world up   # starts the twins and loads the default data; the live env lands in .volter/world.env',