@volter/world-runtime 3.0.166 → 3.0.167

package/dist/src/init.d.ts

@@ -1,3 +1,4 @@
+import { type ManagedApiSourceReader } from './managed-api-source.js';
 import { type NativeServerInputs } from './native-server-inputs.js';
 import { type GoMysqlBinding } from './go-mysql-binding.js';
 import { type OriginalInputReference } from './original-inputs.js';
@@ -147,6 +148,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 */
@@ -228,6 +231,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. */
 export type InitStackNeed = {

package/dist/src/init.js

@@ -1,5 +1,8 @@
+import { withCurrentCredentialDoor } from "./credential-door.js";
+import { composeManagedApiNeeds9 } from "./managed-api-needs.js";
+import { readManagedApiSourceSession } from "./managed-api-source.js";
 import { copyNativeServerInputs, readNativeServerInputs, nativeServerRuntimeReference } from "./native-server-inputs.js";
-import { goMysqlBinding, renderGoMysqlBinding } from "./go-mysql-binding.js";
+import { goMysqlBinding, goMysqlBindingFields, 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.
@@ -48,7 +51,7 @@ import { CATALOG_INDEX_PACKAGE, defaults as catalogDefaults } from "./catalog-in
 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";
+import { APP_URL_ENV, DEFAULT_WORLD_SELECTION, ISSUE_ENV_PREFIX, MINT_ENV, assertWorldConfig, worldConfigDocument, worldSelectionIncludes } from "./schema.js";
 import { loadWorldConfig } from "./configs.js";
 import { parseInfraDefinition } from "./pglite-backing.js";
 import { ownedPath } from "./owned-path.js";
@@ -93,7 +96,7 @@ const APP_ORIGIN_ENV = /^(?:NEXT_PUBLIC_)?(?:APP_)?(?:BASE_)?URL$|^NEXT_PUBLIC_A
 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) {
+function readStackNeeds(path, repo, apiReader) {
     let document;
     try {
         document = JSON.parse(readFileSync(path, 'utf8'));
@@ -101,7 +104,13 @@ function readStackNeeds(path) {
     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, what) => {
@@ -111,6 +120,7 @@ function readStackNeeds(path) {
     };
     const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? Object.entries(value) : [];
     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
@@ -120,7 +130,7 @@ function readStackNeeds(path) {
         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)
+                    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;
@@ -130,7 +140,7 @@ function readStackNeeds(path) {
                     return reference;
                 })() }),
             ...(need.nativeServerInputs === undefined ? {} : (() => {
-                if (document.version !== 5 && document.version !== 7)
+                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'));
@@ -145,14 +155,14 @@ function readStackNeeds(path) {
                 // 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))
+                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, ...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 } : {}) };
+                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 } : {}) };
             }),
             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))
+                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) => {
                     if (!part || typeof part !== 'object' || Array.isArray(part))
@@ -168,7 +178,7 @@ function readStackNeeds(path) {
             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))
+                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)
@@ -231,8 +241,9 @@ 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) {
-    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) {
     // RULE 2: ask the injector, never guess. `aws` yields s3/secretsmanager here — the very keys
@@ -671,9 +682,22 @@ export function planWorldInit(name, repoPath, options = {}) {
     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 = 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 = 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 = apiSource ? { include: [...baseSelection.include, ...apiVendors.filter(vendor => !baseSelection.include.some(item => item.vendor === vendor && item.usage === 'application')).map(vendor => ({ vendor, usage: 'application' }))], 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) */
@@ -687,8 +711,8 @@ 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 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(options.vendors.map((v) => [v, ['--twins']]))
@@ -696,6 +720,8 @@ export function planWorldInit(name, repoPath, options = {}) {
     const unknown = options.vendors
         ? new Map()
         : 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 = [];
     const services = [];
     const existingIds = new Set(existing?.services.map((service) => service.id) ?? []);
@@ -841,8 +867,53 @@ export function planWorldInit(name, repoPath, options = {}) {
             source: { kind: catalogSource.kindOf(vendor), ...(catalogSource.version(vendor) !== undefined ? { version: catalogSource.version(vendor) } : {}) },
         });
     }
+    // Resolve the actual selected catalog service, never the application service or a writer-invented id.
+    const apiOwnerIds = new Map();
+    // 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) => 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();
+    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 = () => apiVendors.map((vendor) => ({ vendor, api: 's3', serviceId: apiOwnerIds.get(vendor), currentDoor: packFacts()[vendor]?.credentialDoor }));
+    const composedServices = new Map();
+    const currentService = (service) => composedServices.get(service.id) ?? withIssues(service);
+    if (apiSource) {
+        apiSource.assertCurrent();
+        const base = { ...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 = {};
+    const env = apiSource ? Object.create(null) : {};
     const envRows = [];
     const envSources = [];
     const bootRisks = [];
@@ -925,7 +996,7 @@ export function planWorldInit(name, repoPath, options = {}) {
     // 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();
-    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);
@@ -1364,7 +1435,18 @@ export function planWorldInit(name, repoPath, options = {}) {
             },
         });
     }
-    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();
         for (const service of mergedServices) {
@@ -1391,7 +1473,7 @@ export function planWorldInit(name, repoPath, options = {}) {
         ...(Array.isArray(savedInfra) ? savedInfra : []),
         ...infra.filter((entry) => !savedInfraIds.has(entry.stub.id)).map((entry) => entry.stub),
     ];
-    const config = {
+    let config = {
         ...comments,
         id: name,
         manifestVersion: 2,
@@ -1425,7 +1507,12 @@ export function planWorldInit(name, repoPath, options = {}) {
         ...(existing?.fixtures ? { fixtures: existing.fixtures } : {}),
         ...(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 = {
         name,
         repo,
         out,
@@ -1445,7 +1532,8 @@ export function planWorldInit(name, repoPath, options = {}) {
             ? { entryPath: resolve(out, 'seed.ts'), storyPath: resolve(out, 'seeds', 'story.ts') }
             : null,
         config,
-        env: config.env,
+        env: config.env ?? {},
+        ...(apiSource === undefined ? {} : { applicationApiSourceIdentity: apiSource.identity }),
         vendors,
         envRows,
         envSources,
@@ -1466,6 +1554,30 @@ export function planWorldInit(name, repoPath, options = {}) {
             .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;
 }
 // ---------------------------------------------------------------------------------------------
 // Emission
@@ -1523,13 +1635,34 @@ pages-sessions.json
 browsers/
 keys.json
 `;
+function initConfigDocument(config, path) {
+    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();
+function assertApiPlanCurrent(plan) {
+    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, options = {}) {
+    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) {
         throw new Error(`volter init: a world already exists at ${plan.configPath}. `
             + '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));
@@ -1549,7 +1682,7 @@ export function writeWorldInit(plan, options = {}) {
                 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));
@@ -1674,7 +1807,8 @@ export function initWorld(name, repoPath, options = {}) {
     // 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',

package/dist/src/managed-api-needs.d.ts

@@ -0,0 +1,101 @@
+/** Needs9 metadata only. Plain CLI init without a live trusted source reader still refuses version9. No I/O, issuer or runtime attachment here. */
+import { type OriginalInputReference } from '@volter/world-core/managed-original-inputs';
+import { type CredentialDoor } from './credential-door.js';
+import { type GoMysqlBinding } from './go-mysql-binding.js';
+import { type NativeServerInputs } from './native-server-inputs.js';
+import { type WorldManifestV2 } from './schema.js';
+declare const APPLICATION_REASONS: readonly ["the declared application service", "builds this Dockerfile", "the service the stack builds", "runs the project's own image", "the stack's only service runs an image", "the one service that publishes a port with an image of no family"];
+type ApplicationReason = typeof APPLICATION_REASONS[number];
+export type ManagedApiNeed = {
+    service: string;
+    vendor: 'aws';
+    api: 's3';
+    endpoints: string[];
+    credentials: Record<string, string>;
+    cliRedirect: Record<string, '${url}'>;
+    issues: CredentialDoor & {
+        required: string[];
+    };
+};
+export type ManagedApiInfrastructureNeed = {
+    service: string;
+    image?: string;
+    builds?: string;
+    family?: string;
+    supplier: 'a World' | 'named by a catalog family' | 'nobody' | "the project's own build";
+    names: Array<{
+        name: string;
+        scheme?: string;
+        query?: string;
+        withPort?: true;
+        containerPort?: number;
+    } & Partial<GoMysqlBinding>>;
+    ports?: string[];
+    portTargets?: Record<string, number>;
+    components?: Array<{
+        name: string;
+        component: 'database' | 'user' | 'password';
+    }>;
+    originalInputs?: OriginalInputReference;
+    nativeServerInputs?: NativeServerInputs;
+};
+export type ManagedApiNeeds9 = {
+    kind: 'browser-substrate.stack-needs';
+    version: 9;
+    dockerfile: string;
+    target?: string;
+    composeFile: string;
+    application: {
+        service: string;
+        told: ApplicationReason;
+        image?: string;
+        target?: string;
+        notInTheImage: string[];
+        envFiles: string[];
+    };
+    needs: ManagedApiInfrastructureNeed[];
+    settings: Record<string, string>;
+    unset: Record<string, string[]>;
+    bare?: string[];
+    notTold?: string;
+    leftOut?: Array<{
+        what: string;
+        kind: string;
+        why: string;
+        wouldHaveBeen: string;
+        service?: string;
+        pointing?: Array<{
+            service: string;
+            variable: string;
+        }>;
+    }>;
+    said: string[];
+    applicationApis: ManagedApiNeed[];
+};
+/** Strict whole metadata shape, preserving common fields. References are metadata, not authenticated files. */
+export declare function readManagedApiNeeds9(value: unknown): ManagedApiNeeds9;
+export type ManagedApiOwner = {
+    vendor: 'aws';
+    api: 's3';
+    serviceId: string;
+    currentDoor: unknown;
+};
+export type ManagedApiApplication = {
+    service: string;
+    environment: Readonly<Record<string, string>>;
+    inheritedNames: readonly string[];
+};
+/** Data from a trusted caller's actual source reading; this validates shape, not custody. */
+export declare function readManagedApiApplication(value: unknown): ManagedApiApplication;
+/** Caller prerequisites: authenticated immutable source/full correspondence, supplied package/current descriptor,
+ * and deliberate owner selection. This metadata composition neither proves those prerequisites nor writes a World. */
+export declare function composeManagedApiNeeds9(input: {
+    document: unknown;
+    world: unknown;
+    application: ManagedApiApplication;
+    owners: readonly ManagedApiOwner[];
+}): {
+    needs: ManagedApiNeeds9;
+    manifest: WorldManifestV2 & Record<string, unknown>;
+};
+export {};