@volter/world-runtime 3.0.144 → 3.0.146

package/dist/src/schema.d.ts

@@ -26,6 +26,38 @@ export type WorldSelection = {
     include: WorldSelectionSelector[];
     exclude: WorldSelectionSelector[];
 };
+/** One row of the coverage proof as it is kept: `evidence` is the proof table's detected-via column, `connection`
+ *  its transport column and `twinInWorld` its twin-in-world column (a display label, not a service id). */
+export type WorldCoverageEntry = {
+    vendor: string;
+    evidence: string[];
+    connection?: string;
+    twinInWorld?: string;
+};
+/** The last coverage proof `init` or `covers` printed, kept beside the selection it applied (covers.ts
+ *  `coverageRecord`): each list is the proof's rows of one status. A record; nothing reads it to route, select or boot. */
+export type WorldCoverage = {
+    /** The package that made the proof. */
+    producer: {
+        package: string;
+        version: string;
+    };
+    /** The proof's verdict, which was the command's exit code. */
+    ok: boolean;
+    covered: WorldCoverageEntry[];
+    notCovered: WorldCoverageEntry[];
+    uninterceptable: WorldCoverageEntry[];
+    unknownSdk: {
+        signal: string;
+        evidence: string[];
+        connection?: string;
+        twinInWorld?: string;
+    }[];
+    acknowledged: (WorldCoverageEntry & {
+        reason: string;
+    })[];
+    excludedBySelection: WorldCoverageEntry[];
+};
 /** The format-2 document is normalized to WorldConfig before runtime code sees it. */
 export type WorldManifestV2 = {
     schemaVersion: 2;
@@ -35,6 +67,7 @@ export type WorldManifestV2 = {
     };
     discovery?: {
         selection?: WorldSelection;
+        coverage?: WorldCoverage;
     };
     services: unknown[];
     runtime?: {
@@ -44,6 +77,10 @@ export type WorldManifestV2 = {
             strip?: string[];
         };
         network?: WorldNetwork;
+        database?: {
+            prepare?: WorldDatabasePrepare;
+        };
+        development?: WorldDevelopment;
     };
     serving?: {
         mode?: 'app' | 'bare';
@@ -290,8 +327,36 @@ export type WorldChangesetRules = {
     approvals?: number;
     summary?: 'required' | 'generated';
 };
+/**
+ * The app's own migration of its database, run by `volter-world-infra prepare` against the prepared cluster
+ * (architecture, managed infrastructure): its command as the app's image runs it (an argv), the image path it runs in,
+ * and the paths under it whose bytes decide what it writes (the prepared cluster's stamp names their digests).
+ */
+export type WorldDatabasePrepare = {
+    command: string[];
+    cwd: string;
+    inputs: string[];
+};
+/**
+ * SETTINGS FOR THE PERSON DEVELOPING THE APP AGAINST THIS WORLD (runtime.development). A World that sets any of
+ * them is a development World: `up` and an image's build say so each time, and an image built from it is not a
+ * prepared one. None of them is a way to make an application boot or to get past a failed preparation; an
+ * application's World does not set them.
+ *
+ * migrateDatabaseAtRuntime: the app may run its own migration when it starts, for a schema its developer is
+ * changing right now. Omitted, no: a migration is the World's `runtime.database.prepare`, run when the image is
+ * built.
+ */
+export type WorldDevelopment = {
+    migrateDatabaseAtRuntime?: boolean;
+};
 export type WorldConfig = {
     id: string;
+    /** The app's own migration step for the World's prepared database cluster (runtime.database.prepare). */
+    databasePrepare?: WorldDatabasePrepare;
+    /** The World's development settings (runtime.development; WorldDevelopment says whose they are). Its
+     *  migrateDatabaseAtRuntime is said to the app's commands as VOLTER_WORLD_DEVELOPMENT_MIGRATE_AT_RUNTIME. */
+    development?: WorldDevelopment;
     /** How changesets are made and readied here; omitted: one approval, a summary required. */
     changesets?: WorldChangesetRules;
     /** HTTPS origin/exact-path/subtree grants with declared phase and explicit build passthrough; [] closes real egress. */
@@ -299,6 +364,8 @@ export type WorldConfig = {
     /** Internal normalized source format and saved discovery selection. */
     manifestVersion?: 1 | 2;
     selection?: WorldSelection;
+    /** The last coverage proof made for this config (`discovery.coverage`); carried so a rewrite keeps it. */
+    coverage?: WorldCoverage;
     description?: string;
     /** A world with no app in front of it (`init --bare <org>/<world>`): a shared world for a team, or a
      *  world standing in for a vendor. `name` is how it is served: `/<org>/<world>/…`. */
@@ -497,6 +564,7 @@ export declare function isEnvironmentName(value: unknown): value is string;
 export declare const DEFAULT_WORLD_SELECTION: WorldSelection;
 export declare const LEGACY_WORLD_SELECTION: WorldSelection;
 export declare function assertWorldSelection(value: unknown, path: string): asserts value is WorldSelection;
+export declare function assertWorldCoverage(value: unknown, path: string): asserts value is WorldCoverage;
 export declare function assertWorldConfig(value: unknown, path: string): WorldConfig;
 export declare function worldSelectionIncludes(selection: WorldSelection, vendor: string, usage: WorldUsage): boolean;
 /** Serialize normalized intent as the committed format-2 manifest. */

package/dist/src/schema.js

@@ -489,8 +489,32 @@ function normalizeV2(value, path) {
     const serving = (value.serving ?? {});
     const scenario = (value.scenario ?? {});
     const provenance = (value.provenance ?? {});
-    assertKeys(discovery, ['selection'], 'discovery', path);
-    assertKeys(runtime, ['isolation', 'environment', 'network'], 'runtime', path);
+    assertKeys(discovery, ['selection', 'coverage'], 'discovery', path);
+    assertKeys(runtime, ['isolation', 'environment', 'network', 'database', 'development'], 'runtime', path);
+    const database = runtime.database ?? {};
+    if (!record(database))
+        throw new Error(`runtime.database must be an object in ${path}`);
+    assertKeys(database, ['prepare'], 'runtime.database', path);
+    const development = runtime.development ?? {};
+    if (!record(development))
+        throw new Error(`runtime.development must be an object in ${path}`);
+    assertKeys(development, ['migrateDatabaseAtRuntime'], 'runtime.development', path);
+    if (development.migrateDatabaseAtRuntime !== undefined && typeof development.migrateDatabaseAtRuntime !== 'boolean')
+        throw new Error(`runtime.development.migrateDatabaseAtRuntime must be a boolean in ${path}`);
+    const databasePrepare = database.prepare;
+    if (databasePrepare !== undefined) {
+        if (!record(databasePrepare))
+            throw new Error(`runtime.database.prepare must be an object in ${path}`);
+        assertKeys(databasePrepare, ['command', 'cwd', 'inputs'], 'runtime.database.prepare', path);
+        const strings = (value) => Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === 'string' && item !== '');
+        if (!strings(databasePrepare.command))
+            throw new Error(`runtime.database.prepare.command must be a non-empty argv in ${path}`);
+        if (typeof databasePrepare.cwd !== 'string' || !databasePrepare.cwd.startsWith('/'))
+            throw new Error(`runtime.database.prepare.cwd must be an absolute image path in ${path}`);
+        if (!strings(databasePrepare.inputs) || databasePrepare.inputs.some((input) => input.startsWith('/') || input.split('/').includes('..'))) {
+            throw new Error(`runtime.database.prepare.inputs must name paths under its cwd in ${path}`);
+        }
+    }
     assertKeys(serving, ['mode', 'name', 'share'], 'serving', path);
     assertKeys(scenario, ['actors', 'fixtures'], 'scenario', path);
     assertKeys(provenance, ['catalog'], 'provenance', path);
@@ -513,6 +537,8 @@ function normalizeV2(value, path) {
         throw new Error(`App serving must omit serving.name in ${path}`);
     const selection = discovery.selection ?? DEFAULT_WORLD_SELECTION;
     assertWorldSelection(selection, path);
+    if (discovery.coverage !== undefined)
+        assertWorldCoverage(discovery.coverage, path);
     if (!Array.isArray(value.services))
         throw new Error(`World manifest must define services[] in ${path}`);
     const normalized = {
@@ -521,9 +547,12 @@ function normalizeV2(value, path) {
         ...(metadata.description === undefined ? {} : { description: metadata.description }),
         manifestVersion: 2,
         selection,
+        ...(discovery.coverage === undefined ? {} : { coverage: discovery.coverage }),
         services: value.services.map((service) => serviceV2ToLegacy(service, path)),
         ...(runtime.isolation === undefined ? {} : { isolation: runtime.isolation }),
         ...(runtime.network === undefined ? {} : { network: normalizeWorldNetwork(runtime.network) }),
+        ...(databasePrepare === undefined ? {} : { databasePrepare: databasePrepare }),
+        ...(development.migrateDatabaseAtRuntime === true ? { development: { migrateDatabaseAtRuntime: true } } : {}),
         ...(environment.values === undefined ? {} : { env: environment.values }),
         ...(environment.strip === undefined ? {} : { stripEnv: environment.strip }),
         ...(mode === 'bare' ? { bare: { name: serving.name } } : {}),
@@ -536,6 +565,41 @@ function normalizeV2(value, path) {
     };
     return { ...assertLegacyWorldConfig(normalized, path), manifestVersion: 2, selection };
 }
+const WORLD_COVERAGE_LISTS = ['covered', 'notCovered', 'uninterceptable', 'unknownSdk', 'acknowledged', 'excludedBySelection'];
+export function assertWorldCoverage(value, path) {
+    if (!record(value))
+        throw new Error(`discovery.coverage must be an object in ${path}`);
+    assertKeys(value, ['producer', 'ok', ...WORLD_COVERAGE_LISTS], 'discovery.coverage', path);
+    const producer = value.producer;
+    if (!record(producer))
+        throw new Error(`discovery.coverage.producer must be an object in ${path}`);
+    assertKeys(producer, ['package', 'version'], 'discovery.coverage.producer', path);
+    for (const key of ['package', 'version'])
+        if (typeof producer[key] !== 'string' || producer[key] === '')
+            throw new Error(`discovery.coverage.producer.${key} must be a non-empty string in ${path}`);
+    if (typeof value.ok !== 'boolean')
+        throw new Error(`discovery.coverage.ok must be a boolean in ${path}`);
+    for (const list of WORLD_COVERAGE_LISTS) {
+        if (!Array.isArray(value[list]))
+            throw new Error(`discovery.coverage.${list} must be an array in ${path}`);
+        const name = list === 'unknownSdk' ? 'signal' : 'vendor';
+        const strings = [name, 'connection', 'twinInWorld', ...(list === 'acknowledged' ? ['reason'] : [])];
+        const required = [name, ...(list === 'acknowledged' ? ['reason'] : [])];
+        for (const entry of value[list]) {
+            if (!record(entry))
+                throw new Error(`discovery.coverage.${list} entries must be objects in ${path}`);
+            assertKeys(entry, [...strings, 'evidence'], `discovery.coverage.${list} entry`, path);
+            for (const key of strings) {
+                if (entry[key] === undefined && !required.includes(key))
+                    continue;
+                if (typeof entry[key] !== 'string' || entry[key] === '')
+                    throw new Error(`discovery.coverage.${list} ${key} must be a non-empty string in ${path}`);
+            }
+            if (!Array.isArray(entry.evidence) || entry.evidence.some((item) => typeof item !== 'string'))
+                throw new Error(`discovery.coverage.${list} evidence must be an array of strings in ${path}`);
+        }
+    }
+}
 export function assertWorldConfig(value, path) {
     if (record(value) && value.schemaVersion !== undefined) {
         if (value.schemaVersion !== WORLD_SCHEMA_VERSION)
@@ -604,9 +668,11 @@ export function worldConfigDocument(config, selection = config.selection ?? DEFA
     return {
         schemaVersion: WORLD_SCHEMA_VERSION,
         metadata: { id: config.id, ...(config.description === undefined ? {} : { description: config.description }) },
-        discovery: { selection },
-        ...(config.isolation === undefined && config.env === undefined && config.stripEnv === undefined && config.network === undefined ? {} : { runtime: {
+        discovery: { selection, ...(config.coverage === undefined ? {} : { coverage: config.coverage }) },
+        ...(config.isolation === undefined && config.env === undefined && config.stripEnv === undefined && config.network === undefined && config.databasePrepare === undefined && !config.development?.migrateDatabaseAtRuntime ? {} : { runtime: {
                 ...(config.isolation === undefined ? {} : { isolation: config.isolation }),
+                ...(config.databasePrepare === undefined ? {} : { database: { prepare: config.databasePrepare } }),
+                ...(config.development?.migrateDatabaseAtRuntime ? { development: { migrateDatabaseAtRuntime: true } } : {}),
                 ...(config.network === undefined ? {} : { network: normalizeWorldNetwork(config.network) }),
                 ...(config.env === undefined && config.stripEnv === undefined ? {} : { environment: {
                         ...(config.env === undefined ? {} : { values: config.env }),

package/dist/src/up-cli.js

@@ -29,7 +29,13 @@ export async function upCommand(subject, rest, root) {
     const appUrl = optionValue(rest, '--app-url') || undefined;
     if (appUrl !== undefined && !(URL.canParse(appUrl) && /^https?:$/.test(new URL(appUrl).protocol)))
         throw new Error(`volter-world up: --app-url "${appUrl}" must be an http(s) URL`);
-    const instance = await superviseWorldUp(subject, { name, root, mode, envFile, forceEnvOutput: rest.includes('--force'), owner: ownerOption(rest), ...(isolation ? { isolation } : {}), ...(keepState ? { keepState: true } : {}) });
+    const options = { name, root, mode, envFile, forceEnvOutput: rest.includes('--force'), owner: ownerOption(rest), ...(isolation ? { isolation } : {}), ...(keepState ? { keepState: true } : {}) };
+    // --in-process: the boot runs in this process, for a caller with no terminal to lose (a browser tab's page, whose
+    // loss ends every process it runs). The owner process exists so a closed terminal does not leave a boot half-done;
+    // where there is none, it costs a whole Node start before the boot and its own end after it (Rallly run 35: 611 ms
+    // from the owner's "returning" to its reply reaching this process). The caller's SIGINT or SIGTERM still cancels the
+    // boot, which rolls back.
+    const instance = rest.includes('--in-process') ? await upInProcess(subject, options) : await superviseWorldUp(subject, options);
     if (appUrl !== undefined) {
         const { setAppUrl } = await import("./app-url.js");
         setAppUrl(instance.name, appUrl, { root });
@@ -40,6 +46,20 @@ export async function upCommand(subject, rest, root) {
     else
         printReady(instance);
 }
+async function upInProcess(configId, options) {
+    const { upWorld } = await import("./runtime.js");
+    const abort = new AbortController();
+    const cancel = (signal) => abort.abort(signal);
+    process.on('SIGINT', cancel);
+    process.on('SIGTERM', cancel);
+    try {
+        return await upWorld(configId, options, abort.signal);
+    }
+    finally {
+        process.off('SIGINT', cancel);
+        process.off('SIGTERM', cancel);
+    }
+}
 export function printReady(instance) {
     process.stdout.write(`World ${instance.name} is ready (${instance.config})
 Instance: ${instance.instance}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.144",
+  "version": "3.0.146",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -70,14 +70,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.144",
-    "@volter/world-console": "3.0.139"
+    "@volter/world-core": "3.0.146",
+    "@volter/world-console": "3.0.141"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.144",
+    "@volter/world-core": "3.0.146",
     "mongodb": "~6.20.0",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",

package/src/cli-commands.ts

@@ -7,7 +7,7 @@ import { createRequire } from 'node:module';
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve, resolve as resolvePath } 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, upWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from './index.ts';
+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, upWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from './index.ts';
 import { formatApplication, formatChangeset, formatRebaseReport, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/world-core/runtime';
 import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from './serve.ts';
 import type { WorldManifest } from './attach.ts';
@@ -61,7 +61,7 @@ function printHelp(): void {
                                                   # 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)
@@ -468,6 +468,14 @@ export async function main(): Promise<void> {
     if (!repo) 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/src/covers.ts

@@ -26,14 +26,15 @@ import { errorMessage } from './error-message.ts';
 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.ts';
+import { getActiveWorldStore, installedPackageDir, packVendor, vendorOfPackModule } from '@volter/world-core/runtime';
+import { loadWorldConfig, writeWorldConfig } from './configs.ts';
+import { runtimeManifest } from './package-manifest.ts';
 import { VENDOR_SERVER_BACKINGS } from './backings.ts';
 import { injectableVendorKeys, loadInject, twinUrlVendorFor } from './inject-map.ts';
 import { connectionProtocol, projectConnections, projectDependencies, projectManifestDirs, projectEnvNames, projectFetchUrls, projectNpmRegistries, PYPI_TWINS, SDK_TWINS } from './project-inspect.ts';
 import { overlayCoversMaps, packFacts } from './pack-facts.ts';
 import { statusWorld } from './runtime.ts';
-import { ISSUE_ENV_PREFIX, worldSelectionIncludes, type WorldSelection, type WorldServiceConfig, type WorldServiceInstance, type WorldUsage } from './schema.ts';
+import { ISSUE_ENV_PREFIX, worldSelectionIncludes, type WorldCoverage, type WorldCoverageEntry, type WorldSelection, type WorldServiceConfig, type WorldServiceInstance, type WorldUsage } from './schema.ts';
 
 export type CoverageStatus = 'covered' | 'missing' | 'uninterceptable' | 'unknown-sdk' | 'acknowledged' | 'excluded';
 
@@ -54,6 +55,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[];
@@ -348,6 +352,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, { protocol: string | null; label: string }>;
@@ -593,7 +599,7 @@ export function worldTwinInventory(world: string, root: string): WorldTwinInvent
       // a bare env `*_TWIN_URL` var is only a REACHABLE twin when the injector reads it
       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);
   }
@@ -608,7 +614,7 @@ export function worldTwinInventory(world: string, root: string): WorldTwinInvent
     for (const [name, value] of Object.entries(config.env ?? {})) {
       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);
     throw new Error(
@@ -1023,6 +1029,7 @@ export function coverWorld(world: string, repoPath: string, options: CoverageOpt
     world,
     worldSource: inventory.source,
     worldPath: inventory.path,
+    configPath: inventory.configPath,
     repo,
     twinsInWorld: [...inventory.ids.values()].map((id) => id.label).sort(),
     rows,
@@ -1037,6 +1044,47 @@ export function coverWorld(world: string, repoPath: string, options: CoverageOpt
   };
 }
 
+/**
+ * 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: CoverageReport): WorldCoverage {
+  const entry = (row: CoverageRow): Omit<WorldCoverageEntry, 'vendor'> => ({
+    evidence: row.detectedVia,
+    ...(row.connection === undefined ? {} : { connection: row.connection }),
+    ...(row.twinInWorld === null ? {} : { twinInWorld: row.twinInWorld }),
+  });
+  const of = (status: CoverageStatus): WorldCoverageEntry[] =>
+    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: CoverageReport, root = process.cwd()): boolean {
+  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: CoverageReport): string {
   const lines: string[] = [];
   lines.push(`World ${report.world} (${report.worldSource}: ${report.worldPath})`);

package/src/index.ts

@@ -13,6 +13,8 @@ export type {
   WorldRunRecord,
   WorldResourceRequirements,
   WorldManifestV2,
+  WorldCoverage,
+  WorldCoverageEntry,
   WorldSelection,
   WorldSelectionSelector,
   WorldUsage,
@@ -87,11 +89,13 @@ export { fakeEnvValue, fakeGoogleOAuthClientJson, fakeGoogleServiceAccountJson,
 export type { FakeServiceAccountOptions } from './fixture-env.ts';
 export {
   coverWorld,
+  coverageRecord,
   detectRepoVendors,
   envNameVendor,
   formatCoverageReport,
   injectorVendorKeysFor,
   isCredentialShapedEnvName,
+  recordCoverage,
   worldTwinInventory,
 } from './covers.ts';
 export type { CoverageReport, CoverageRow, CoverageStatus, CoverageOptions, RepoVendorSignals } from './covers.ts';

package/src/infra.ts

@@ -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.ts';
+import { containerlessDataDirectory, infraConnections, liveDatabaseBehind, liveDatabaseMigration, developmentMigratesAtRuntime, DEVELOPMENT_MIGRATION_NOTICE, parseInfraDefinition } from './pglite-backing.ts';
 import { errorMessage } from './error-message.ts';
 
 /** Whether a program is on PATH, read from the file system without starting a process: where a missing program
@@ -77,6 +77,11 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
   // 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: 'docker' | 'pglite' | 'native'): string => env.VOLTER_WORLD_INFRA_BACKING === backing ? ' (forced by VOLTER_WORLD_INFRA_BACKING)' : '';
+  const backingFact = (backing: 'docker' | 'pglite' | 'native'): { backing: { is: string; by: 'forced' | 'chosen' } } =>
+    ({ 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;
@@ -90,11 +95,23 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
       return 0;
     }
     const { pglitePrepare } = await import('./pglite-backing.ts');
+    const { nativePrepare, nativePostgresTools } = await import('./native-postgres-backing.ts');
+    // 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: string) => 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;
     }
   }
@@ -110,7 +127,19 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
     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: string | undefined;
+  const databaseFacts = (): { database?: { migrated?: string[]; behind?: string[] }; development?: { migrateDatabaseAtRuntime: true } } => {
+    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 as const } } : {}) };
+  };
   const base = ['compose', '-f', definition];
   const run = async (args: string[]): Promise<Ran> => {
     const ran = await runCommand('docker', [...base, ...args], { env: { ...env, VOLTER_WORLD_DATA: worldData }, timeout: 120_000, ...(signal ? { signal } : {}) });
@@ -216,7 +245,7 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
       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 '
@@ -233,11 +262,12 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
     }
     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!);
@@ -298,7 +328,7 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
   }
   if (composed?.length === 0) {
     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`);
+    else if (phase === 'status') io.out(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env), ...databaseFacts() })}\n`);
     else io.out('managed infrastructure stopped\n');
     return 0;
   }
@@ -317,7 +347,7 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
     }
     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); }
         catch (error) {
@@ -329,7 +359,8 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
       } else if (phase === 'status') {
         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);
         await nativePostgresDown(worldData);
@@ -345,6 +376,7 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
 
   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);
     io.out('managed infrastructure ready\n');
@@ -359,7 +391,7 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
       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']);
     if (result.status !== 0) return fail(result);