@volter/world-runtime 3.0.143 → 3.0.145

package/dist/src/cli-commands.js

@@ -7,7 +7,7 @@ import { createRequire } from 'node:module';
 import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, writeWorldClock, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from "./index.js";
+import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, writeWorldClock, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, recordCoverage, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from "./index.js";
 import { formatApplication, formatChangeset, formatRebaseReport, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/world-core/runtime';
 import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from "./serve.js";
 import { clockFile, instanceDir, pruneWorlds, withoutVaultSignIn } from "./runtime.js";
@@ -57,7 +57,7 @@ function printHelp() {
                                                   # emission. Exit 0 = ready to \`up\`; exit 1 = the honest worklist.
                                                   # Deterministic: same repo + same pack catalog => identical bytes.
                                                   # init DIAGNOSES; it never boots — it prints the exact next commands
-  volter-world up <config> --env-out=<path> [--owner <label>] [--name <name>] [--mode local|share|sealed] [--isolation process|colocated|worker] [--keep-state] [--app-url <url>] [--json] [--root <repo>]
+  volter-world up <config> --env-out=<path> [--owner <label>] [--name <name>] [--mode local|share|sealed] [--isolation process|colocated|worker] [--keep-state] [--app-url <url>] [--in-process] [--json] [--root <repo>]
   volter-world outdated <world> [--json]            — each mounted twin: pinned / mounted / catalog-current version and protocol standing (R17)
   volter-world audit <world> [--json]               — each mounted twin's grade, as the catalog records it (R17)
   volter-world down <name> [--grace-ms <ms>] [--purge] [--if-instance <token>] [--root <repo>]   # SIGTERM, then SIGKILL survivors after the grace (default 5000ms)
@@ -516,6 +516,17 @@ export async function main() {
             throw new Error('volter-world covers: --repo <path> is required (the application repo to prove coverage for)');
         const report = coverWorld(subject, repo, { root, allowUnknown: rest.includes('--allow-unknown'), acknowledge: acknowledgeOptions(rest, 'covers') });
         process.stdout.write(rest.includes('--json') ? `${JSON.stringify(report, null, 2)}\n` : formatCoverageReport(report));
+        // `covers` is a reading. It keeps the proof it printed only as the plain verb on a World's own config: with --json
+        // it prints and writes nothing, and it never rewrites the config a running instance booted from. Whether it kept
+        // the proof is said on stderr, beside the report and outside its JSON.
+        if (!rest.includes('--json')) {
+            if (report.worldSource !== 'config')
+                process.stderr.write(`coverage not recorded: ${report.world} was read from its instance (${report.worldPath}); the config it booted from is not rewritten\n`);
+            else if (recordCoverage(report, root))
+                process.stderr.write(`coverage recorded in ${report.configPath}\n`);
+            else
+                process.stderr.write(`coverage not recorded: ${report.configPath} is a format-1 document, which has no discovery section, or is no longer on disk\n`);
+        }
         if (!report.ok)
             process.exit(1);
         return;

package/dist/src/covers.d.ts

@@ -1,4 +1,4 @@
-import { type WorldSelection, type WorldServiceConfig, type WorldServiceInstance, type WorldUsage } from './schema.js';
+import { type WorldCoverage, type WorldSelection, type WorldServiceConfig, type WorldServiceInstance, type WorldUsage } from './schema.js';
 export type CoverageStatus = 'covered' | 'missing' | 'uninterceptable' | 'unknown-sdk' | 'acknowledged' | 'excluded';
 export type CoverageRow = {
     /** vendor key for mapped vendors; the raw dep/env name for unknown-sdk rows */
@@ -16,6 +16,9 @@ export type CoverageReport = {
     /** 'instance' when a booted/recorded instance was read; 'config' for the stable config */
     worldSource: 'instance' | 'config';
     worldPath: string;
+    /** The World's config, where the proof is kept (`recordCoverage`): `worldPath` itself for a config, the config
+     *  an instance booted from otherwise. */
+    configPath: string;
     repo: string;
     twinsInWorld: string[];
     rows: CoverageRow[];
@@ -121,6 +124,8 @@ type WorldTwinInventory = {
     services: Array<WorldServiceConfig | WorldServiceInstance>;
     source: 'instance' | 'config';
     path: string;
+    /** The config the World is declared in: the one read, or the one its instance booted from. */
+    configPath: string;
     /** normalized identifier → id record (e.g. 'stripe' → { label: 'stripe (service)', … }) */
     ids: Map<string, WorldTwinId>;
     connections: Map<string, {
@@ -180,5 +185,20 @@ export type RepoVendorSignals = {
  * and source lists, so callers that preserve it are deterministic. */
 export declare function detectRepoVendors(repoPath: string, services?: Array<WorldServiceConfig | WorldServiceInstance>): RepoVendorSignals;
 export declare function coverWorld(world: string, repoPath: string, options?: CoverageOptions): CoverageReport;
+/**
+ * The report as the data `init` keeps in the config (`discovery.coverage`): the same rows `formatCoverageReport`
+ * prints, grouped by the status each verdict line counts. Every push to `covered`, `missing`, `uninterceptable`,
+ * `unknown`, `acknowledged` and `excluded` in `coverWorld` adds the row of that status, so the lists here name what
+ * those lines name. Paths (`worldPath`, `configPath`, `repo`) stay out: the config is portable and init's bytes are deterministic.
+ */
+export declare function coverageRecord(report: CoverageReport): WorldCoverage;
+/**
+ * Keep a proof just made in the World's config, replacing the record of an earlier one. It answers true when it
+ * wrote the record and false when it wrote nothing: a format-1 document has no `discovery` section and a World whose
+ * config is no longer on disk has nowhere to keep it. The caller decides whether to record at all and says the
+ * answer (`init` writes its own record into the config it makes): `covers` records only as the plain verb on a
+ * World's own config, never with --json and never into the config a running instance booted from (cli-commands.ts).
+ */
+export declare function recordCoverage(report: CoverageReport, root?: string): boolean;
 export declare function formatCoverageReport(report: CoverageReport): string;
 export {};

package/dist/src/covers.js

@@ -25,8 +25,9 @@ import { errorMessage } from "./error-message.js";
 import { existsSync, readFileSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { installedPackageDir, packVendor, vendorOfPackModule } from '@volter/world-core/runtime';
-import { loadWorldConfig } from "./configs.js";
+import { getActiveWorldStore, installedPackageDir, packVendor, vendorOfPackModule } from '@volter/world-core/runtime';
+import { loadWorldConfig, writeWorldConfig } from "./configs.js";
+import { runtimeManifest } from "./package-manifest.js";
 import { VENDOR_SERVER_BACKINGS } from "./backings.js";
 import { injectableVendorKeys, loadInject, twinUrlVendorFor } from "./inject-map.js";
 import { connectionProtocol, projectConnections, projectDependencies, projectManifestDirs, projectEnvNames, projectFetchUrls, projectNpmRegistries, PYPI_TWINS, SDK_TWINS } from "./project-inspect.js";
@@ -472,7 +473,7 @@ export function worldTwinInventory(world, root) {
             if (stem)
                 addId(ids, normalizeId(stem[1]), `env ${key}`, twinUrlVendorFor(key) !== null);
         }
-        return { services: Object.values(status.services), source: 'instance', path: `${status.dirs.instance}/instance.json`, ids, connections: serviceConnections(Object.values(status.services), status.env, root), selection: status.selection, declared: declaredTwin(Object.values(status.services), status.env, root) };
+        return { services: Object.values(status.services), source: 'instance', path: `${status.dirs.instance}/instance.json`, configPath: status.configPath, ids, connections: serviceConnections(Object.values(status.services), status.env, root), selection: status.selection, declared: declaredTwin(Object.values(status.services), status.env, root) };
     }
     catch (error) {
         instanceError = errorMessage(error);
@@ -491,7 +492,7 @@ export function worldTwinInventory(world, root) {
             if (value.startsWith(ISSUE_ENV_PREFIX))
                 connections.set(name, { protocol: 'issued', label: `${value.slice(ISSUE_ENV_PREFIX.length)} (${name}; issued)` });
         }
-        return { services: config.services, source: 'config', path, ids, connections, selection: config.selection, declared: declaredTwin(config.services, undefined, root) };
+        return { services: config.services, source: 'config', path, configPath: path, ids, connections, selection: config.selection, declared: declaredTwin(config.services, undefined, root) };
     }
     catch (error) {
         const configError = errorMessage(error);
@@ -895,6 +896,7 @@ export function coverWorld(world, repoPath, options = {}) {
         world,
         worldSource: inventory.source,
         worldPath: inventory.path,
+        configPath: inventory.configPath,
         repo,
         twinsInWorld: [...inventory.ids.values()].map((id) => id.label).sort(),
         rows,
@@ -908,6 +910,46 @@ export function coverWorld(world, repoPath, options = {}) {
         ok: missing.length === 0 && uninterceptable.length === 0 && (allowUnknown || unknown.length === 0),
     };
 }
+/**
+ * The report as the data `init` keeps in the config (`discovery.coverage`): the same rows `formatCoverageReport`
+ * prints, grouped by the status each verdict line counts. Every push to `covered`, `missing`, `uninterceptable`,
+ * `unknown`, `acknowledged` and `excluded` in `coverWorld` adds the row of that status, so the lists here name what
+ * those lines name. Paths (`worldPath`, `configPath`, `repo`) stay out: the config is portable and init's bytes are deterministic.
+ */
+export function coverageRecord(report) {
+    const entry = (row) => ({
+        evidence: row.detectedVia,
+        ...(row.connection === undefined ? {} : { connection: row.connection }),
+        ...(row.twinInWorld === null ? {} : { twinInWorld: row.twinInWorld }),
+    });
+    const of = (status) => report.rows.filter((row) => row.status === status).map((row) => ({ vendor: row.vendor, ...entry(row) }));
+    return {
+        producer: { package: '@volter/world-runtime', version: runtimeManifest().version ?? 'unversioned' },
+        ok: report.ok,
+        covered: of('covered'),
+        notCovered: of('missing'),
+        uninterceptable: of('uninterceptable'),
+        unknownSdk: report.rows.filter((row) => row.status === 'unknown-sdk').map((row) => ({ signal: row.vendor, ...entry(row) })),
+        acknowledged: of('acknowledged').map((row) => ({ ...row, reason: report.acknowledged.find((held) => held.vendor === row.vendor).reason })),
+        excludedBySelection: of('excluded'),
+    };
+}
+/**
+ * Keep a proof just made in the World's config, replacing the record of an earlier one. It answers true when it
+ * wrote the record and false when it wrote nothing: a format-1 document has no `discovery` section and a World whose
+ * config is no longer on disk has nowhere to keep it. The caller decides whether to record at all and says the
+ * answer (`init` writes its own record into the config it makes): `covers` records only as the plain verb on a
+ * World's own config, never with --json and never into the config a running instance booted from (cli-commands.ts).
+ */
+export function recordCoverage(report, root = process.cwd()) {
+    if (!getActiveWorldStore().exists(report.configPath))
+        return false;
+    const { path, config } = loadWorldConfig(report.configPath, root);
+    if (config.manifestVersion !== 2)
+        return false;
+    writeWorldConfig(path, { ...config, coverage: coverageRecord(report) });
+    return true;
+}
 export function formatCoverageReport(report) {
     const lines = [];
     lines.push(`World ${report.world} (${report.worldSource}: ${report.worldPath})`);

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export type { WorldConfig, WorldInstance, WorldIsolation, WorldMode, WorldServiceConfig, WorldServiceType, WorldExternalServiceConfig, WorldExternalDiscover, WorldExternalDiscoverSource, WorldExternalReadyWhen, WorldRunOutcome, WorldRunRecord, WorldResourceRequirements, WorldManifestV2, WorldSelection, WorldSelectionSelector, WorldUsage, } from './schema.js';
+export type { WorldConfig, WorldInstance, WorldIsolation, WorldMode, WorldServiceConfig, WorldServiceType, WorldExternalServiceConfig, WorldExternalDiscover, WorldExternalDiscoverSource, WorldExternalReadyWhen, WorldRunOutcome, WorldRunRecord, WorldResourceRequirements, WorldManifestV2, WorldCoverage, WorldCoverageEntry, WorldSelection, WorldSelectionSelector, WorldUsage, } from './schema.js';
 export { DEFAULT_WORLD_SELECTION, LEGACY_WORLD_SELECTION, WORLD_SCHEMA_VERSION, WORLD_USAGES, worldConfigDocument, worldSelectionIncludes } from './schema.js';
 export type { WorldChangesetRules } from './schema.js';
 export { loadWorldConfig, migrateWorldConfig, resolveConfigPath, worldChangesetRules, writeWorldConfig } from './configs.js';
@@ -17,7 +17,7 @@ export { inspectProject, formatProjectInspection, projectDependencies, projectEn
 export type { ProjectInspection } from './project-inspect.js';
 export { fakeEnvValue, fakeGoogleOAuthClientJson, fakeGoogleServiceAccountJson, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from './fixture-env.js';
 export type { FakeServiceAccountOptions } from './fixture-env.js';
-export { coverWorld, detectRepoVendors, envNameVendor, formatCoverageReport, injectorVendorKeysFor, isCredentialShapedEnvName, worldTwinInventory, } from './covers.js';
+export { coverWorld, coverageRecord, detectRepoVendors, envNameVendor, formatCoverageReport, injectorVendorKeysFor, isCredentialShapedEnvName, recordCoverage, worldTwinInventory, } from './covers.js';
 export type { CoverageReport, CoverageRow, CoverageStatus, CoverageOptions, RepoVendorSignals } from './covers.js';
 export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from './init.js';
 export { STATE_GITIGNORE } from './init.js';

package/dist/src/index.js

@@ -14,7 +14,7 @@ export { inspectProject, formatProjectInspection, projectDependencies, projectEn
 // Structurally valid fake credentials for world configs (fixture env) — see fixture-env.ts
 // for the pattern (a fake a client SDK parses/signs with must be structurally real).
 export { fakeEnvValue, fakeGoogleOAuthClientJson, fakeGoogleServiceAccountJson, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from "./fixture-env.js";
-export { coverWorld, detectRepoVendors, envNameVendor, formatCoverageReport, injectorVendorKeysFor, isCredentialShapedEnvName, worldTwinInventory, } from "./covers.js";
+export { coverWorld, coverageRecord, detectRepoVendors, envNameVendor, formatCoverageReport, injectorVendorKeysFor, isCredentialShapedEnvName, recordCoverage, worldTwinInventory, } from "./covers.js";
 // `volter-world init` — the deterministic front door: detect the repo's vendors (covers), emit a
 // world config + env file OUTSIDE the repo (fixture-env), and prove the emission with `covers`.
 export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from "./init.js";

package/dist/src/infra.js

@@ -12,7 +12,7 @@ import { delimiter, dirname, join } from 'node:path';
 import { signalChild } from './process-signal.mjs';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { infraConnections, parseInfraDefinition } from "./pglite-backing.js";
+import { containerlessDataDirectory, infraConnections, liveDatabaseBehind, liveDatabaseMigration, developmentMigratesAtRuntime, DEVELOPMENT_MIGRATION_NOTICE, parseInfraDefinition } from "./pglite-backing.js";
 import { errorMessage } from "./error-message.js";
 /** Whether a program is on PATH, read from the file system without starting a process: where a missing program
  *  still costs a process round trip (a browser tab's kernel), the container probe is not spawned at all. */
@@ -98,6 +98,10 @@ export async function runInfrastructure(phase, env, io, signal) {
     // prepare: the image build's step that makes the World's PGlite cluster once, on its host, so the World's first up
     // opens it instead of running initdb (pglite-backing.ts, pglitePrepare; ADR 0018). It needs the World's
     // definition, not an instance.
+    // A backing the World's environment forces is said where the backing is said, and in the status fact: forcing one
+    // is a choice someone made for this World, and it is never silent.
+    const forcedBy = (backing) => env.VOLTER_WORLD_INFRA_BACKING === backing ? ' (forced by VOLTER_WORLD_INFRA_BACKING)' : '';
+    const backingFact = (backing) => ({ backing: { is: backing, by: env.VOLTER_WORLD_INFRA_BACKING === backing ? 'forced' : 'chosen' } });
     if (phase === 'prepare') {
         const config = env.VOLTER_WORLD_CONFIG;
         const declaredDefinition = config ? join(dirname(config), 'world.infrastructure.yml') : undefined;
@@ -111,12 +115,24 @@ export async function runInfrastructure(phase, env, io, signal) {
             return 0;
         }
         const { pglitePrepare } = await import("./pglite-backing.js");
+        const { nativePrepare, nativePostgresTools } = await import("./native-postgres-backing.js");
+        // The backing up would choose for this PostgreSQL: native where the PostgreSQL programs are (containerless rule
+        // 2; in a tab image, the tab's own build), PGlite otherwise or when forced.
+        const native = env.VOLTER_WORLD_INFRA_BACKING !== 'pglite' && nativePostgresTools(env) !== undefined;
+        // The database prepare step's own output (prisma's "N migrations found … No pending migrations") is the
+        // preparation's record, said where its caller reads it.
+        const launch = { env, ...(signal ? { signal } : {}), note: (what) => io.out(`${what.trimEnd()}\n`) };
         try {
-            io.out(`managed infrastructure prepared ${await pglitePrepare(postgres[0], config, { env, ...(signal ? { signal } : {}) })}\n`);
+            const prepared = native
+                ? await nativePrepare(postgres[0], readFileSync(declaredDefinition, 'utf8'), config, launch)
+                : await pglitePrepare(postgres[0], config, launch);
+            io.out(`managed infrastructure prepared ${prepared} (backing: ${native ? 'native PostgreSQL' : 'PGlite'}${forcedBy(native ? 'native' : 'pglite')})\n`);
             return 0;
         }
         catch (error) {
             io.err(`managed infrastructure prepare failed: ${errorMessage(error)}\n`);
+            // Said where the person or agent reading the failure stands: the fix is here, in the preparation.
+            io.err('The fix is in this build-time preparation (the step above, or what it runs against). Migrating at run time is not the remedy for a failed preparation.\n');
             return 1;
         }
     }
@@ -131,6 +147,19 @@ export async function runInfrastructure(phase, env, io, signal) {
         io.err('managed infrastructure: declared definition is missing\n');
         return 2;
     }
+    // A development World says so every time it comes up: its use is never silent.
+    if (phase === 'up' && developmentMigratesAtRuntime(worldConfig))
+        io.out(`${DEVELOPMENT_MIGRATION_NOTICE}\n`);
+    // What the app's commands are told of the World's database (architecture, managed infrastructure): the declared
+    // step's command while the live data carries the migration the image expects, the same command when the World
+    // declares the step and the live data does not carry it, and whether this is a development World whose app migrates when it runs. `postgresData` is the serving backing's data directory, set where a status knows it.
+    let postgresData;
+    const databaseFacts = () => {
+        const migrated = postgresData ? liveDatabaseMigration(worldConfig, env, postgresData) : undefined;
+        const behind = postgresData ? liveDatabaseBehind(worldConfig, env, postgresData) : undefined;
+        return { ...(migrated || behind ? { database: { ...(migrated ? { migrated } : {}), ...(behind ? { behind } : {}) } } : {}),
+            ...(developmentMigratesAtRuntime(worldConfig) ? { development: { migrateDatabaseAtRuntime: true } } : {}) };
+    };
     const base = ['compose', '-f', definition];
     const run = async (args) => {
         const ran = await runCommand('docker', [...base, ...args], { env: { ...env, VOLTER_WORLD_DATA: worldData }, timeout: 120_000, ...(signal ? { signal } : {}) });
@@ -245,7 +274,7 @@ export async function runInfrastructure(phase, env, io, signal) {
             return 1;
         }
         if (phase === 'up') {
-            io.out('managed infrastructure backing: containerless (no container runtime)\n');
+            io.out(`managed infrastructure backing: containerless${forcedBy('pglite') || ' (no container runtime)'}\n`);
             if (services.some((s) => s.kind === 'postgres')) {
                 io.out('managed infrastructure: PostgreSQL is PGlite, one session every connection takes in turn; a read through '
                     + 'the pool inside a transaction waits on itself until that transaction ends. A postgres server on PATH, or '
@@ -263,11 +292,13 @@ export async function runInfrastructure(phase, env, io, signal) {
         }
         if (phase === 'status') {
             const status = await pgliteStatus(services, worldData);
+            if (services.some((s) => s.kind === 'postgres'))
+                postgresData = join(worldData, containerlessDataDirectory('postgres'));
             if (!status.ok) {
                 io.err(`managed infrastructure status failed: ${status.ready}/${services.length} declared services are ready\n`);
                 return 1;
             }
-            io.out(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env) })}\n`);
+            io.out(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env), ...backingFact('pglite'), ...databaseFacts() })}\n`);
             return 0;
         }
         await pgliteDown(services, worldData);
@@ -336,7 +367,7 @@ export async function runInfrastructure(phase, env, io, signal) {
         if (phase === 'up')
             io.out('managed infrastructure ready\n');
         else if (phase === 'status')
-            io.out(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env) })}\n`);
+            io.out(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env), ...databaseFacts() })}\n`);
         else
             io.out('managed infrastructure stopped\n');
         return 0;
@@ -357,7 +388,7 @@ export async function runInfrastructure(phase, env, io, signal) {
         }
         try {
             if (phase === 'up') {
-                io.out('managed infrastructure backing: native PostgreSQL (multi-session)\n');
+                io.out(`managed infrastructure backing: native PostgreSQL (multi-session)${forcedBy('native')}\n`);
                 await nativePostgresUp(postgres, worldData, readFileSync(definition, 'utf8'), launch);
                 try {
                     await pgliteUp(others, worldData, launch);
@@ -377,7 +408,8 @@ export async function runInfrastructure(phase, env, io, signal) {
                 const ready = others.length === 0 || (await pgliteStatus(others, worldData)).ok;
                 if (!ready || !await nativePostgresStatus(worldData))
                     return 1;
-                io.out(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env) })}\n`);
+                postgresData = join(worldData, 'native-postgres-data');
+                io.out(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env), ...backingFact('native'), ...databaseFacts() })}\n`);
             }
             else {
                 await pgliteDown(others, worldData);
@@ -393,6 +425,8 @@ export async function runInfrastructure(phase, env, io, signal) {
     }
     const only = composed ?? [];
     if (phase === 'up') {
+        if (forcedBy('docker'))
+            io.out(`managed infrastructure backing: container runtime${forcedBy('docker')}\n`);
         const result = await run(['up', '-d', '--wait', ...only]);
         if (result.status !== 0)
             return fail(result);
@@ -411,7 +445,7 @@ export async function runInfrastructure(phase, env, io, signal) {
             io.err(`managed infrastructure status failed: ${runningNames.length + twinned.length + native.length}/${expectedNames.length + twinned.length + native.length} declared services are ready\n`);
             return 1;
         }
-        io.out(`${JSON.stringify({ ok: true, services: expectedNames.length + twinned.length + native.length, connections: infraConnections(declared, env) })}\n`);
+        io.out(`${JSON.stringify({ ok: true, services: expectedNames.length + twinned.length + native.length, connections: infraConnections(declared, env), ...backingFact('docker'), ...databaseFacts() })}\n`);
     }
     else {
         const result = await run(['down', '--remove-orphans']);

package/dist/src/init.d.ts

@@ -1,4 +1,5 @@
 import { type CoverageReport } from './covers.js';
+import { type ProjectMigrationTool } from './project-inspect.js';
 import { type WorldConfig, type WorldServiceConfig } from './schema.js';
 /** How a twin service in the emitted world is reached by the app's traffic. */
 export type InitWiring = 
@@ -111,6 +112,9 @@ export type InitPlan = {
     envSources: string[];
     /** empty example values read by production source — prominent warning, not vendor-coverage fact */
     bootRisks: InitBootRisk[];
+    /** migration tools found in the repository while the World manages a database and declares no step
+     *  (runtime.database.prepare): reported, never written, and no part of the vendor-coverage verdict */
+    undeclaredMigrations: ProjectMigrationTool[];
     infra: InitInfraStub[];
     /** the services emitted into the private managed-infrastructure definition */
     compose: InitComposeService[];

package/dist/src/init.js

@@ -36,11 +36,11 @@
 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';
-import { coverWorld, detectRepoVendors, envNameVendor, formatCoverageReport, injectorEnvNameForKey, injectorVendorKeysFor, isCredentialShapedEnvName, registryAcknowledgedReason, } from "./covers.js";
+import { coverWorld, detectRepoVendors, envNameVendor, coverageRecord, formatCoverageReport, injectorEnvNameForKey, injectorVendorKeysFor, isCredentialShapedEnvName, registryAcknowledgedReason, } from "./covers.js";
 import { fakeEnvValue, isAppKeyName, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from "./fixture-env.js";
 import { findInstalledPackage, packCli, packEntry, resolveCatalog } from "./catalog.js";
 import { CATALOG_INDEX_PACKAGE, defaults as catalogDefaults } from "./catalog-index.js";
-import { projectEnvReads, projectManifestDirs } from "./project-inspect.js";
+import { projectEnvReads, projectManifestDirs, projectMigrationTools } 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";
@@ -1047,6 +1047,9 @@ export function planWorldInit(name, repoPath, options = {}) {
         envRows,
         envSources,
         bootRisks: [...bootRisks].sort((a, b) => a.name.localeCompare(b.name)),
+        // A migration belongs in the World's step, run once where the image is built. init can see the tool, not the step.
+        undeclaredMigrations: existing?.databasePrepare !== undefined || !(compose.some((service) => service.kind === 'postgres' || service.kind === 'mysql') || existingIds.has('infrastructure'))
+            ? [] : projectMigrationTools(repo),
         infra,
         compose,
         composePath: compose.length > 0 ? resolve(out, 'world.infrastructure.yml') : null,
@@ -1248,6 +1251,10 @@ export function initWorld(name, repoPath, options = {}) {
     // 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.
     const coverage = { ...proof, world: plan.name };
+    // 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`);
     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',
@@ -1329,6 +1336,17 @@ export function formatInitReport(result) {
         }
         lines.push('  Resolve these before expecting the app to listen. Vendor coverage can be green while the app rejects its own env.');
     }
+    if (plan.undeclaredMigrations.length > 0) {
+        lines.push('');
+        lines.push(`MIGRATION TOOL FOUND, NO STEP DECLARED (${plan.undeclaredMigrations.length}):`);
+        for (const found of plan.undeclaredMigrations)
+            lines.push(`  ${found.tool} — migrations at ${found.migrations} (schema ${found.schema})`);
+        lines.push('  The World manages this app\'s database and declares no runtime.database.prepare, so the app would migrate it at');
+        lines.push('  every start. Declare the step in the World: `command` (the migration as the app\'s image runs it, an argv), `cwd`');
+        lines.push('  (the image path it runs in) and `inputs` (the schema and migrations, as paths under it). These are the IMAGE\'s');
+        lines.push('  paths, which its Dockerfile decides and this repository does not state; an image build that reads the image');
+        lines.push('  prints the step.');
+    }
     if (plan.compose.length > 0) {
         lines.push('');
         lines.push('Infrastructure (owned by the World lifecycle):');

package/dist/src/native-postgres-backing.d.ts

@@ -1,9 +1,23 @@
-import type { HostLaunch, InfraService } from './pglite-backing.js';
+import { type HostLaunch, type InfraService } from './pglite-backing.js';
 /** The PostgreSQL tool directory this machine offers, or undefined: `VOLTER_WORLD_POSTGRES_BIN` as named, else the
  *  directory of a `postgres` server on PATH, resolved through its links, holding the server's own tools beside it
  *  (libpq's client tools on PATH name no server). Read from executable files; nothing is launched or installed
  *  (architecture, managed infrastructure). */
 export declare function nativePostgresTools(env: NodeJS.ProcessEnv): string | undefined;
+/** Where a World's prepared native cluster lives, beside its world.json, and its stamp (ADR 0018's layout). */
+export declare function nativePreparedCluster(worldConfig: string): {
+    directory: string;
+    stamp: string;
+};
+/**
+ * `volter-world-infra prepare` for a World whose PostgreSQL is native (architecture, managed infrastructure; ADR
+ * 0018's phase): this lifecycle's own steps once, into `<World dir>/.volter-prepared/native-postgres-data`. initdb with
+ * up's arguments, the postmaster on the World's declared loopback port, the declared database, and a clean SIGINT stop (its
+ * shutdown checkpoint; no postmaster.pid left), then the stamp. Where the World declares runtime.database.prepare, the
+ * step runs against that postmaster before its stop, and a step that fails leaves no cluster. The image build runs it with the programs the tab
+ * runs, under the tab's kernel, so the cluster is the one a first boot there would write.
+ */
+export declare function nativePrepare(service: InfraService, definition: string, worldConfig: string, launch?: HostLaunch): Promise<string>;
 export declare function nativePostgresUp(services: InfraService[], root: string, definition: string, launch: HostLaunch): Promise<void>;
 export declare function nativePostgresStatus(root: string): Promise<boolean>;
 export declare function nativePostgresDown(root: string): Promise<void>;