@volter/world-runtime 3.0.144 → 3.0.146

package/src/init.ts

@@ -40,6 +40,7 @@ import {
   coverWorld,
   detectRepoVendors,
   envNameVendor,
+  coverageRecord,
   formatCoverageReport,
   injectorEnvNameForKey,
   injectorVendorKeysFor,
@@ -50,7 +51,7 @@ import {
 import { fakeEnvValue, isAppKeyName, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from './fixture-env.ts';
 import { findInstalledPackage, packCli, packEntry, resolveCatalog, type Catalog } from './catalog.ts';
 import { CATALOG_INDEX_PACKAGE, defaults as catalogDefaults } from './catalog-index.ts';
-import { projectEnvReads, projectManifestDirs } from './project-inspect.ts';
+import { projectEnvReads, projectManifestDirs, projectMigrationTools, type ProjectMigrationTool } from './project-inspect.ts';
 import { overlayEndpointEnv, packFacts } from './pack-facts.ts';
 import { VENDOR_SERVER_BACKINGS } from './backings.ts';
 import { APP_URL_ENV, DEFAULT_WORLD_SELECTION, ISSUE_ENV_PREFIX, MINT_ENV, worldConfigDocument, worldSelectionIncludes, type WorldConfig, type WorldSelection, type WorldServiceConfig } from './schema.ts';
@@ -201,6 +202,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[];
@@ -1233,6 +1237,9 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     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,
@@ -1437,6 +1444,10 @@ export function initWorld(name: string, repoPath: string, options: InitOptions =
   // 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: CoverageReport = { ...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',
@@ -1519,6 +1530,16 @@ export function formatInitReport(result: InitResult): string {
     }
     lines.push('  Resolve these before expecting the app to listen. Vendor coverage can be green while the app rejects its own env.');
   }
+  if (plan.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/src/native-postgres-backing.ts

@@ -1,15 +1,17 @@
 // World-managed multi-session PostgreSQL. The declaration, data, process and teardown
 // belong to the infrastructure service; a recipe never operates postgres itself.
 import { spawn, type ChildProcess } from 'node:child_process';
-import { accessSync, closeSync, constants, existsSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { accessSync, closeSync, constants, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { connect } from 'node:net';
+import { runtimeManifest } from './package-manifest.ts';
 import { delimiter, dirname, join, resolve } from 'node:path';
 import { commandLifetime, COMMAND_GRACE_MS, CommandRetirementError } from './command-lifetime.ts';
 import { survivingOwnedGroups } from './process-groups.ts';
 import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnReceiptPath, verifySpawnIdentity, signalOwnedProcess, type SpawnIdentity } from './process-receipt.ts';
 import { signalChild, childIdentity } from './process-signal.mjs';
 import { errorMessage } from './error-message.ts';
-import type { HostLaunch, InfraService } from './pglite-backing.ts';
+import { PREPARED_DIRECTORY, databasePrepareOf, expectedMigration, forgetStaleMigration, keepFailureEvidence, runDatabasePrepare, takePreparedCluster, type HostLaunch, type InfraService, type PreparedMigration } from './pglite-backing.ts';
 
 interface Ownership { pid: number; data: string; port: number; binary: string }
 interface Started { child: ChildProcess; owned: Ownership; closed: boolean; identity?: SpawnIdentity; birth?: Promise<SpawnIdentity | undefined>; error?: Error }
@@ -108,6 +110,15 @@ async function listening(port: number, deadline: number, signal?: AbortSignal):
     if (signal?.aborted) abort();
   });
 }
+/** The last lines of a child's stream for an error, labelled, or nothing when it said nothing. */
+function streamTail(label: string, text: string, lines = 40): string {
+  const tail = text.trim().split('\n').slice(-lines).join('\n');
+  return tail ? `\n${label}:\n${tail}` : '';
+}
+/** The postmaster's log as an error carries it: its last lines. A failed preparation also keeps the whole file (nativePrepare). */
+function logTail(log: string): string {
+  try { return streamTail(`log ${log}`, readFileSync(log, 'utf8')); } catch { return ''; }
+}
 /** Every helper joins exit and its private group, including spawn errors and abort. */
 async function tool(command: string, args: string[], env: NodeJS.ProcessEnv, deadline: number, root: string, signal?: AbortSignal): Promise<string> {
   signal?.throwIfAborted();
@@ -138,7 +149,9 @@ async function tool(command: string, args: string[], env: NodeJS.ProcessEnv, dea
     signal?.throwIfAborted();
     if (timedOut) throw new Error(`native postgres readiness deadline elapsed during ${command}`);
     if (spawnError) throw spawnError;
-    if (result.code !== 0 || lifetime.forwarded) throw new Error(`${command} exited ${result.code}/${result.signal}: ${errorOutput.trim()}`);
+    // Both streams, labelled: a tool's last words on stdout say how far it got (initdb's bootstrap steps) and are
+    // otherwise lost with the process.
+    if (result.code !== 0 || lifetime.forwarded) throw new Error(`${command} exited ${result.code}/${result.signal}${streamTail('stderr', errorOutput)}${streamTail('stdout', output)}`);
     return output;
   } catch (error) {
     failure = error;
@@ -200,6 +213,144 @@ export function nativePostgresTools(env: NodeJS.ProcessEnv): string | undefined
   return undefined;
 }
 
+/** initdb's arguments after `-D`, the same at up and at prepare, and so in the stamp. */
+function initdbArguments(user: string): string[] {
+  return [`--username=${user}`, '--auth=trust', '--no-locale', '--encoding=UTF8'];
+}
+
+/** Where a World's prepared native cluster lives, beside its world.json, and its stamp (ADR 0018's layout). */
+export function nativePreparedCluster(worldConfig: string): { directory: string; stamp: string } {
+  const directory = join(dirname(worldConfig), PREPARED_DIRECTORY, 'native-postgres-data');
+  return { directory, stamp: `${directory}.json` };
+}
+
+/**
+ * What a prepared native cluster was made with: this runtime (its lifecycle made it), the postgres and initdb that
+ * made it, initdb's arguments, the declared user and database, and, for a migrated cluster, the World's step and its
+ * inputs' digests (pglite-backing.ts, runDatabasePrepare). initdb's own choices (its dynamic shared memory
+ * probe, its configuration trials) are in the cluster's postgresql.conf, which its programs make again. Neither the
+ * port nor a password is in a trust-authenticated cluster.
+ *
+ * Each program is recorded by its size and, at prepare, its sha256: the record of what made the cluster. At up only
+ * the sizes are compared, from the files' metadata. Hashing the programs again there read the whole of postgres and
+ * of initdb through the tab's file system on every boot (initdb otherwise untouched when the cluster is taken,
+ * postgres then read a second time to run), inside the boot's budget. What the sizes do not prove, PostgreSQL proves
+ * itself: the server reads pg_control at start and refuses a cluster whose control version, catalog version, block
+ * size, alignment or float8 passing differ from its build (a 64-bit or another-version cluster), so a foreign cluster
+ * is never served, only refused.
+ */
+interface NativeStamp {
+  runtime: string; backing: 'native';
+  programs: Record<string, { bytes: number; sha256?: string }>;
+  initdb: string[]; user: string; database: string;
+  migration?: PreparedMigration;
+}
+
+function nativeStamp(tools: string, user: string, database: string, digests: boolean, migration?: PreparedMigration): NativeStamp {
+  const manifest = runtimeManifest();
+  const programs: NativeStamp['programs'] = {};
+  for (const name of ['postgres', 'initdb']) {
+    const file = programFile(join(tools, name));
+    programs[name] = { bytes: statSync(file).size,
+      ...(digests ? { sha256: createHash('sha256').update(readFileSync(file)).digest('hex') } : {}) };
+  }
+  return { runtime: manifest.version ?? 'unversioned', backing: 'native', programs, initdb: initdbArguments(user), user, database,
+    ...(migration ? { migration } : {}) };
+}
+
+/**
+ * The file a command runs: itself, or, for a host shim that runs another build of the program (an image's wasm32
+ * PostgreSQL at its image build: browser-substrate wali-host-program.ts), the program it declares on a
+ * `# program: <file>` line in its first 1 KiB. The stamp is about the program that makes the cluster, not its launcher.
+ */
+function programFile(command: string): string {
+  const file = realpathSync(command);
+  // Its first 1 KiB only: read whole, postgres and initdb crossed the tab's file system at every up for this line.
+  const bytes = Buffer.alloc(1024);
+  const fd = openSync(file, 'r');
+  let length: number;
+  try { length = readSync(fd, bytes, 0, bytes.length, 0); } finally { closeSync(fd); }
+  const head = bytes.subarray(0, length).toString('latin1');
+  return head.startsWith('#!') ? /^# program: (.+)$/m.exec(head)?.[1]?.trim() || file : file;
+}
+
+/** Whether a stamp names this runtime, these programs' sizes, these initdb arguments, this identity and this migration
+ *  (up's check): a migrated cluster is taken only for the step and input digests it was migrated from, an unmigrated one
+ *  only by a World that declares no step. */
+function nativeStampMatches(text: string, expected: NativeStamp): boolean {
+  let stamp: NativeStamp;
+  try { stamp = JSON.parse(text) as NativeStamp; } catch { return false; }
+  return stamp.runtime === expected.runtime && stamp.backing === 'native' && stamp.user === expected.user
+    && stamp.database === expected.database && JSON.stringify(stamp.initdb) === JSON.stringify(expected.initdb)
+    && Object.keys(expected.programs).every(name => stamp.programs?.[name]?.bytes === expected.programs[name]!.bytes)
+    && JSON.stringify(stamp.migration) === JSON.stringify(expected.migration);
+}
+
+/**
+ * `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 async function nativePrepare(service: InfraService, definition: string, worldConfig: string, launch: HostLaunch = {}): Promise<string> {
+  if (service.kind !== 'postgres') throw new Error('only a declared PostgreSQL is prepared');
+  const env: NodeJS.ProcessEnv = { ...(launch.env ?? process.env) };
+  // The preparation makes the cluster; it never takes one.
+  delete env.VOLTER_WORLD_CONFIG;
+  const tools = nativePostgresTools(env);
+  if (!tools) throw new Error('native prepare requires the PostgreSQL programs: a postgres server on PATH, or VOLTER_WORLD_POSTGRES_BIN');
+  const { directory, stamp } = nativePreparedCluster(worldConfig);
+  const root = dirname(directory);
+  mkdirSync(root, { recursive: true });
+  if (ownership(root).present) await nativePostgresDown(root);
+  rmSync(directory, { recursive: true, force: true });
+  rmSync(stamp, { force: true });
+  const { user, database } = settings(definition);
+  // On the World's declared port, the one up serves: the image build's sandbox admits exactly that loopback endpoint
+  // (browser-substrate world-cluster.ts), and a port already held is refused by up's own check.
+  // A preparation that fails keeps the postmaster's WHOLE log outside this directory, which its caller may remove,
+  // and says where (pglite-backing.ts keepFailureEvidence). The log is removed only once the cluster is prepared.
+  const log = join(root, 'native-postgres.log');
+  const failed = (error: unknown): unknown => {
+    const kept = existsSync(log) ? keepFailureEvidence('native-postgres-log', { file: log }, env) : '';
+    if (error instanceof Error) { error.message += kept; return error; }
+    return new Error(`${String(error)}${kept}`);
+  };
+  try { await nativePostgresUp([service], root, definition, { ...launch, env }); }
+  catch (error) { throw failed(error); }
+  // The app's own migration, where the World declares one, against the postmaster this lifecycle has up: the same step
+  // the PGlite backing runs against its host. Its failure waits for the stop below, then removes the cluster.
+  const step = databasePrepareOf(worldConfig);
+  let migration: PreparedMigration | undefined;
+  let stepFailure: { error: unknown } | undefined;
+  if (step) {
+    try { migration = await runDatabasePrepare(step, worldConfig, { ...launch, env }); }
+    catch (error) { stepFailure = { error }; }
+  }
+  // The clean stop: SIGINT is the postmaster's fast shutdown, which writes its checkpoint and removes postmaster.pid.
+  // Its wait is the lifecycle's own readiness budget, not a new limit; down then clears the receipts.
+  const identity = readSpawnReceipt(recordPath(root)).value;
+  if (identity) {
+    await signalOwnedProcess(identity, 'SIGINT', true);
+    const deadline = Date.now() + READY_TIMEOUT_MS;
+    while (liveGroup(identity.pid) && Date.now() < deadline) await wait(100);
+  }
+  await nativePostgresDown(root);
+  if (stepFailure) {
+    rmSync(directory, { recursive: true, force: true });
+    throw failed(stepFailure.error);
+  }
+  if (!existsSync(join(directory, 'PG_VERSION')) || existsSync(join(directory, 'postmaster.pid'))) {
+    rmSync(directory, { recursive: true, force: true });
+    throw failed(new Error('native prepare ended without a cleanly stopped cluster'));
+  }
+  rmSync(log, { force: true });
+  writeFileSync(stamp, `${JSON.stringify(nativeStamp(tools, user, database, true, migration))}\n`);
+  return directory;
+}
+
 export async function nativePostgresUp(services: InfraService[], root: string, definition: string, launch: HostLaunch): Promise<void> {
   if (services.length !== 1 || services[0]!.kind !== 'postgres') throw new Error('native postgres requires one declared postgres service');
   const deadline = Date.now() + READY_TIMEOUT_MS;
@@ -223,10 +374,26 @@ export async function nativePostgresUp(services: InfraService[], root: string, d
   const service = services[0]!;
   if (await listening(service.hostPort, deadline, launch.signal)) throw new Error(`native postgres port ${service.hostPort} is already occupied`);
   const data = resolve(root, 'native-postgres-data');
-  mkdirSync(data, { recursive: true, mode: 0o700 });
   const { user, database } = settings(definition);
+  // An empty data directory takes the World's prepared cluster when its stamp matches (ADR 0018's placement; the
+  // cluster was made by these same programs at image build). initdb then finds PG_VERSION, and the database exists.
+  forgetStaleMigration(data);
+  const prepared = env.VOLTER_WORLD_CONFIG ? nativePreparedCluster(env.VOLTER_WORLD_CONFIG) : undefined;
+  // The check reads two files' metadata and the stamp; it runs only when a prepared cluster is there to take.
+  if (prepared && existsSync(join(prepared.directory, 'PG_VERSION')) && !existsSync(join(data, 'PG_VERSION'))) {
+    // A migrated cluster is the app's only for the step inputs it was migrated from (pglite-backing.ts, expectedMigration).
+    const wanted = expectedMigration(env.VOLTER_WORLD_CONFIG!, env, prepared.directory);
+    if ('note' in wanted) launch.note?.(wanted.note);
+    else {
+      const expected = nativeStamp(binaries, user, database, false, wanted.migration);
+      const placed = takePreparedCluster(prepared, text => nativeStampMatches(text, expected), data,
+        'other PostgreSQL programs, initdb arguments, identity or migration', wanted.migration);
+      if (placed.note) launch.note?.(placed.note);
+    }
+  }
+  mkdirSync(data, { recursive: true, mode: 0o700 });
   if (!existsSync(join(data, 'PG_VERSION'))) {
-    await tool(join(binaries, 'initdb'), ['-D', data, `--username=${user}`, '--auth=trust', '--no-locale', '--encoding=UTF8'], env, deadline, root, launch.signal);
+    await tool(join(binaries, 'initdb'), ['-D', data, ...initdbArguments(user)], env, deadline, root, launch.signal);
   }
   launch.signal?.throwIfAborted();
   const binary = join(binaries, 'postgres');
@@ -260,8 +427,8 @@ export async function nativePostgresUp(services: InfraService[], root: string, d
     for (;;) {
       launch.signal?.throwIfAborted();
       if (started.error) throw started.error;
-      if (child.exitCode !== null || child.signalCode !== null || started.closed) throw new Error(`native postgres exited before readiness; see ${log}`);
-      if (Date.now() >= deadline) throw new Error(`native postgres did not become ready; see ${log}`);
+      if (child.exitCode !== null || child.signalCode !== null || started.closed) throw new Error(`native postgres exited before readiness; see ${log}${logTail(log)}`);
+      if (Date.now() >= deadline) throw new Error(`native postgres did not become ready; see ${log}${logTail(log)}`);
       if (existsSync(join(data, 'postmaster.pid'))) {
         verifyOwner(current);
         const lines = readFileSync(join(data, 'postmaster.pid'), 'utf8').split('\n');
@@ -275,7 +442,7 @@ export async function nativePostgresUp(services: InfraService[], root: string, d
       if (!output.trim()) await tool(join(binaries, 'createdb'), ['-h', '127.0.0.1', '-p', String(service.hostPort), '-U', user, '--', database], env, deadline, root, launch.signal);
     }
     launch.signal?.throwIfAborted();
-    if (child.exitCode !== null || child.signalCode !== null) throw new Error(`native postgres exited during readiness; see ${log}`);
+    if (child.exitCode !== null || child.signalCode !== null) throw new Error(`native postgres exited during readiness; see ${log}${logTail(log)}`);
     rmSync(startingPath(root));
     child.unref();
   } catch (error) {

package/src/package-manifest.ts

@@ -0,0 +1,31 @@
+// THIS PACKAGE'S OWN MANIFEST, found by its name walking up from this module. One finder for every module of the
+// runtime that needs it (a prepared cluster's stamp records the runtime's version and its PGlite's).
+//
+// A fixed hop is wrong in one of the two places the runtime runs from: src/ in the repository is one directory below
+// the package root, dist/src/ in the published package is two, so `..` from a published module is dist/, which
+// holds no package.json. That mistake was made twice and fixed once: the PGlite backing walked up, the native
+// backing still hopped, and a native preparation failed after its migration had run (Cal run 28: "ENOENT ...
+// node_modules/@volter/world-runtime/dist/package.json").
+//
+// Nothing runs at import: a module that builds a URL from import.meta.url when it loads fails to load in workerd,
+// which bundles the runtime into the hosted World.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const NAME = '@volter/world-runtime';
+
+export interface RuntimeManifest { name?: string; version?: string; dependencies?: Record<string, string> }
+
+/** The runtime's package.json, from wherever this module runs. */
+export function runtimeManifest(): RuntimeManifest {
+  const from = fileURLToPath(new URL('.', import.meta.url));
+  for (let dir = from; ; dir = dirname(dir)) {
+    const candidate = join(dir, 'package.json');
+    if (existsSync(candidate)) {
+      const manifest = JSON.parse(readFileSync(candidate, 'utf8')) as RuntimeManifest;
+      if (manifest.name === NAME) return manifest;
+    }
+    if (dirname(dir) === dir) throw new Error(`no ${NAME} package.json above ${from}`);
+  }
+}

package/src/pglite-backing.ts

@@ -12,15 +12,18 @@
 // services only. A definition declaring mysql without a container runtime is
 // refused with the kinds named, never half-booted. Redis never reaches it: every
 // redis service is the redis twin's (redis-backing.ts).
-import { appendFileSync, closeSync, cpSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
-import { randomUUID } from 'node:crypto';
+import { appendFileSync, closeSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, renameSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { assertWorldConfig, type WorldDatabasePrepare } from './schema.ts';
 import { connect } from 'node:net';
 import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
 import { spawn, type ChildProcess } from 'node:child_process';
 import { commandLifetime, COMMAND_GRACE_MS, COMMAND_CONFIRM_MS } from './command-lifetime.ts';
 import { survivingOwnedGroups } from './process-groups.ts';
 import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnReceiptPath, verifySpawnIdentity, signalOwnedProcess, type SpawnIdentity } from './process-receipt.ts';
 import { errorMessage } from './error-message.ts';
+import { runtimeManifest } from './package-manifest.ts';
 import { fileURLToPath } from 'node:url';
 import { parse } from 'yaml';
 import { mongodbArgv, mongodbReady, mongodbServes } from './mongodb-backing.ts';
@@ -220,24 +223,135 @@ export function preparedCluster(worldConfig: string): { directory: string; stamp
  * another password takes the same cluster and authenticates against its own. Extensions are loaded into the module
  * at each open, never created in the cluster by the open path.
  */
-/** This package's own manifest, found by its name walking up from this module: the package root from src/ in the
- *  repository and from dist/src/ in the published package alike, where a fixed `..` reached dist/package.json. */
-function runtimeManifest(): { version?: string; dependencies?: Record<string, string> } {
-  for (let dir = here(); ; dir = dirname(dir)) {
-    const candidate = join(dir, 'package.json');
-    if (existsSync(candidate)) {
-      const manifest = JSON.parse(readFileSync(candidate, 'utf8')) as { name?: string; version?: string; dependencies?: Record<string, string> };
-      if (manifest.name === '@volter/world-runtime') return manifest;
-    }
-    if (dirname(dir) === dir) throw new Error(`no @volter/world-runtime package.json above ${here()}`);
-  }
-}
+/** A prepared cluster's migration, as its stamp records it: the step's command and the digest of each of its inputs. */
+export interface PreparedMigration { command: string[]; inputs: Record<string, string> }
 
-function preparedStamp(service: InfraService): string {
+function preparedStamp(service: InfraService, migration?: PreparedMigration): string {
   const manifest = runtimeManifest();
   const pglite = manifest.dependencies?.['@electric-sql/pglite'];
   if (!pglite || !/^\d+\.\d+\.\d+$/.test(pglite)) throw new Error('world-runtime pins no exact @electric-sql/pglite version');
-  return `${JSON.stringify({ runtime: manifest.version ?? 'unversioned', pglite, user: service.postgres!.user, database: service.postgres!.database })}\n`;
+  return `${JSON.stringify({ runtime: manifest.version ?? 'unversioned', pglite, user: service.postgres!.user, database: service.postgres!.database,
+    ...(migration ? { migration } : {}) })}\n`;
+}
+
+/**
+ * The SHA-256 of each of a migration step's inputs, under its cwd in the app's tree: a file's bytes; a directory's
+ * sorted relative paths, each with its type, its mode and its bytes (a link, its target). What the image build records
+ * for an image, and what `up` hashes only for a World run outside one.
+ */
+export function migrationInputDigests(cwd: string, inputs: readonly string[]): Record<string, string> {
+  const digests: Record<string, string> = {};
+  for (const input of inputs) {
+    const hash = createHash('sha256');
+    const walk = (absolute: string, relative: string): void => {
+      const stat = lstatSync(absolute);
+      if (stat.isSymbolicLink()) { hash.update(`l ${relative} ${readlinkSync(absolute)}\n`); return; }
+      if (stat.isDirectory()) {
+        hash.update(`d ${relative} ${(stat.mode & 0o7777).toString(8)}\n`);
+        for (const name of readdirSync(absolute).sort()) walk(join(absolute, name), relative === '' ? name : `${relative}/${name}`);
+        return;
+      }
+      hash.update(`f ${relative} ${(stat.mode & 0o7777).toString(8)} ${stat.size}\n`);
+      hash.update(readFileSync(absolute));
+    };
+    walk(join(cwd, input), '');
+    digests[input] = `sha256:${hash.digest('hex')}`;
+  }
+  return digests;
+}
+
+/** The World's declared migration step for its prepared database, if any (runtime.database.prepare). */
+export function databasePrepareOf(worldConfig: string): WorldDatabasePrepare | undefined {
+  return assertWorldConfig(JSON.parse(readFileSync(worldConfig, 'utf8')), worldConfig).databasePrepare;
+}
+
+/** `NAME=value` lines (an image's environment, VOLTER_WORLD_APP_ENV), as an environment. */
+function environmentFile(path: string): Record<string, string> {
+  const values: Record<string, string> = {};
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    const at = line.indexOf('=');
+    if (at > 0) values[line.slice(0, at)] = line.slice(at + 1);
+  }
+  return values;
+}
+
+/**
+ * The World's declared step (runtime.database.prepare) run once against a prepared cluster its backing is serving on
+ * the World's port: the declared command in the app's tree, with the image's environment and the World's values over
+ * it. The build host's own PATH finds the command's tools (the image's PATH names its own paths). Its failure throws,
+ * with its output; its answer is what the cluster's stamp records.
+ */
+/**
+ * A FAILED PREPARATION KEEPS ITS WHOLE EVIDENCE. An error carries a tail, and the preparation's own directory is
+ * its caller's to remove (an image build prepares in a staging directory it retires when the preparation fails), so
+ * the tail was all that survived: a postmaster's first lines, its shared-memory setup among them, were gone with the
+ * directory (Cal runs 23 and 24). The whole text or file is written under the preparation's temporary directory
+ * (TMPDIR, which a failed build retains; the system's otherwise), outside the World's directory, and the sentence
+ * naming it is added to the error. Never on success, and a copy that fails says so instead of hiding the failure.
+ */
+export function keepFailureEvidence(name: string, evidence: string | { file: string }, env: NodeJS.ProcessEnv): string {
+  try {
+    const directory = env.TMPDIR ?? tmpdir();
+    mkdirSync(directory, { recursive: true });
+    const path = join(directory, `volter-world-prepare-${name}-${Date.now()}-${process.pid}.log`);
+    if (typeof evidence === 'string') writeFileSync(path, evidence); else copyFileSync(evidence.file, path);
+    return `\nThe whole ${name} is kept at ${path}`;
+  } catch (error) {
+    return `\n(the whole ${name} could not be kept: ${errorMessage(error)})`;
+  }
+}
+
+export async function runDatabasePrepare(step: WorldDatabasePrepare, worldConfig: string, launch: HostLaunch): Promise<PreparedMigration> {
+  const env = launch.env ?? process.env;
+  const appRoot = env.VOLTER_WORLD_APP_ROOT;
+  if (!appRoot) throw new Error('the World declares runtime.database.prepare: VOLTER_WORLD_APP_ROOT must name the app image\'s root');
+  const cwd = join(appRoot, step.cwd);
+  const imageEnv = env.VOLTER_WORLD_APP_ENV ? environmentFile(env.VOLTER_WORLD_APP_ENV) : {};
+  const { PATH: _imagePath, ...imageValues } = imageEnv;
+  const worldValues = assertWorldConfig(JSON.parse(readFileSync(worldConfig, 'utf8')), worldConfig).env ?? {};
+  const [program, ...words] = step.command;
+  const migration = spawn(program!, words, { windowsHide: true, cwd, env: { ...env, ...imageValues, ...worldValues }, stdio: ['ignore', 'pipe', 'pipe'] });
+  let output = '';
+  migration.stdout!.on('data', (chunk: Buffer) => { output += chunk.toString('utf8'); });
+  migration.stderr!.on('data', (chunk: Buffer) => { output += chunk.toString('utf8'); });
+  const { code } = await commandLifetime(migration, launch.signal).finish();
+  if (code !== 0) throw new Error(`the World's database prepare step (${step.command.join(' ')}) exited ${code ?? 'null'}\n${output.trim().split('\n').slice(-40).join('\n')}${keepFailureEvidence('database-prepare-step-output', output, env)}`);
+  launch.note?.(`database prepare step: ${step.command.join(' ')}\n${output.trim()}`);
+  return { command: [...step.command], inputs: migrationInputDigests(cwd, step.inputs) };
+}
+
+/**
+ * The app's own migration against a prepared PGlite cluster: the cluster served by the same host at the World's port
+ * for the step (runDatabasePrepare), then the host closed cleanly.
+ */
+async function migratePreparedCluster(service: InfraService, directory: string, step: WorldDatabasePrepare, worldConfig: string, launch: HostLaunch): Promise<PreparedMigration> {
+  const env = launch.env ?? process.env;
+  const pidFile = join(dirname(directory), 'pglite-prepare.pid');
+  const boot = randomUUID();
+  rmSync(listeningReceiptPath(pidFile), { force: true });
+  const [command, ...args] = [...hostArgv(service, directory), '--prepared', '--listening-file', listeningReceiptPath(pidFile), '--boot', boot];
+  let hostOutput = '';
+  const host = spawn(command!, args, { windowsHide: true,
+    env: { ...env, VOLTER_WORLD_PGLITE_USER: service.postgres!.user, VOLTER_WORLD_PGLITE_DATABASE: service.postgres!.database, VOLTER_WORLD_PGLITE_PASSWORD: service.postgres!.password! },
+    stdio: ['ignore', 'pipe', 'pipe'] });
+  host.stdout!.on('data', (chunk: Buffer) => { hostOutput += chunk.toString('utf8'); });
+  host.stderr!.on('data', (chunk: Buffer) => { hostOutput += chunk.toString('utf8'); });
+  const hostLifetime = commandLifetime(host, launch.signal);
+  try {
+    const deadline = Date.now() + READY_TIMEOUT_MS;
+    while (!(host.pid && alive(host.pid) && await hostServes(service, pidFile, host.pid, boot))) {
+      if (!host.pid || !alive(host.pid)) throw new Error(`the prepared cluster's host exited before serving\n${hostOutput.trim().split('\n').slice(-20).join('\n')}`);
+      if (Date.now() > deadline) throw new Error(`the prepared cluster's host did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s`);
+      launch.signal?.throwIfAborted();
+      await sleep(25);
+    }
+    return await runDatabasePrepare(step, worldConfig, launch);
+  } finally {
+    // A clean close: PGlite writes its cluster back before the host exits.
+    if (host.pid && alive(host.pid)) host.kill('SIGTERM');
+    await hostLifetime.finish();
+    rmSync(listeningReceiptPath(pidFile), { force: true });
+  }
 }
 
 /** Run the host's open path once into the World's prepared directory; replaces an earlier preparation. */
@@ -260,18 +374,108 @@ export async function pglitePrepare(service: InfraService, worldConfig: string,
   const { code } = await lifetime.finish();
   if (code !== 0 || !existsSync(join(directory, 'PG_VERSION'))) {
     rmSync(directory, { recursive: true, force: true });
-    throw new Error(`pglite prepare exited ${code ?? 'null'} without a cluster\n${output.trim().split('\n').slice(-40).join('\n')}`);
+    throw new Error(`pglite prepare exited ${code ?? 'null'} without a cluster\n${output.trim().split('\n').slice(-40).join('\n')}${keepFailureEvidence('pglite-prepare-output', output, launch.env ?? process.env)}`);
   }
-  writeFileSync(stamp, preparedStamp(service));
+  // The app's own migration, where the World declares one: a cluster it did not complete is never stamped.
+  const step = databasePrepareOf(worldConfig);
+  let migration: PreparedMigration | undefined;
+  if (step) {
+    try { migration = await migratePreparedCluster(service, directory, step, worldConfig, launch); }
+    catch (error) { rmSync(directory, { recursive: true, force: true }); throw error; }
+  }
+  writeFileSync(stamp, preparedStamp(service, migration));
   return directory;
 }
 
 /** Give an empty service data directory the World's prepared cluster when its stamp matches; says what it did. */
-function placePreparedCluster(service: InfraService, serviceData: string, worldConfig: string | undefined): { placed: boolean; note?: string } {
+function placePreparedCluster(service: InfraService, serviceData: string, worldConfig: string | undefined, env: NodeJS.ProcessEnv): { placed: boolean; note?: string } {
+  if (service.kind === 'postgres') forgetStaleMigration(serviceData);
   if (service.kind !== 'postgres' || !worldConfig || existsSync(join(serviceData, 'PG_VERSION'))) return { placed: false };
-  const { directory, stamp } = preparedCluster(worldConfig);
+  const prepared = preparedCluster(worldConfig);
+  if (!existsSync(join(prepared.directory, 'PG_VERSION')) || !existsSync(prepared.stamp)) return { placed: false };
+  const wanted = expectedMigration(worldConfig, env, prepared.directory);
+  if ('note' in wanted) return { placed: false, note: wanted.note };
+  return takePreparedCluster(prepared, preparedStamp(service, wanted.migration), serviceData, 'another PGlite pin, identity or migration', wanted.migration);
+}
+
+/**
+ * The migration a prepared cluster must have been made with for `up` to take it, on either backing: none when the
+ * World declares no step; else the step's command and its inputs' digests, as the app's image recorded them
+ * (VOLTER_WORLD_APP_DIGESTS, no read of the tree) or, for a World run outside an image, as its tree has them. With
+ * neither given a migrated cluster is not taken, and the note says so.
+ */
+export function expectedMigration(worldConfig: string, env: NodeJS.ProcessEnv, directory: string): { migration?: PreparedMigration } | { note: string } {
+  const step = databasePrepareOf(worldConfig);
+  if (!step) return {};
+  let inputs: Record<string, string> | undefined;
+  if (env.VOLTER_WORLD_APP_DIGESTS) {
+    // The image wrote this; a value that is not a JSON object of digests is said, and the cluster is not taken.
+    let recorded: unknown;
+    try { recorded = JSON.parse(env.VOLTER_WORLD_APP_DIGESTS); } catch { recorded = undefined; }
+    if (!recorded || typeof recorded !== 'object' || Array.isArray(recorded) || Object.values(recorded).some((value) => typeof value !== 'string')) {
+      return { note: `prepared cluster ${directory} not taken: it is migrated, and VOLTER_WORLD_APP_DIGESTS is not a JSON object of its inputs' digests` };
+    }
+    inputs = recorded as Record<string, string>;
+  } else if (env.VOLTER_WORLD_APP_ROOT) inputs = migrationInputDigests(join(env.VOLTER_WORLD_APP_ROOT, step.cwd), step.inputs);
+  if (!inputs) return { note: `prepared cluster ${directory} not taken: it is migrated, and neither the app's recorded digests nor its tree were given to compare (VOLTER_WORLD_APP_DIGESTS, VOLTER_WORLD_APP_ROOT)` };
+  return { migration: { command: [...step.command], inputs: Object.fromEntries(step.inputs.map((input) => [input, inputs![input] ?? ''])) } };
+}
+
+/** Beside a service's data: the migration its live cluster carries, written when a migrated cluster is placed. */
+const migrationRecord = (serviceData: string): string => `${serviceData}.migration.json`;
+
+/** A data directory with no cluster carries no migration: a record left by data since removed is dropped. */
+export function forgetStaleMigration(serviceData: string): void {
+  if (!existsSync(join(serviceData, 'PG_VERSION'))) rmSync(migrationRecord(serviceData), { force: true });
+}
+
+/**
+ * The declared step's command when the LIVE database carries the migration the app's image expects, else undefined
+ * (architecture, managed infrastructure). A fact of the data, not of this boot's placement: kept data is still
+ * migrated on a later boot, and kept data under an image whose step inputs have changed is older than the image.
+ */
+export function liveDatabaseMigration(worldConfig: string, env: NodeJS.ProcessEnv, serviceData: string): string[] | undefined {
+  if (!existsSync(join(serviceData, 'PG_VERSION')) || !existsSync(migrationRecord(serviceData))) return undefined;
+  const wanted = expectedMigration(worldConfig, env, serviceData);
+  if ('note' in wanted || !wanted.migration) return undefined;
+  return readFileSync(migrationRecord(serviceData), 'utf8') === `${JSON.stringify(wanted.migration)}\n` ? [...wanted.migration.command] : undefined;
+}
+
+/**
+ * The declared step's command when the World declares one and the live database does NOT carry the migration the
+ * image expects: data kept from an earlier image, or a cluster that was initialized here because the prepared one
+ * was not taken. Undefined with no step, no cluster yet, or a migrated one.
+ */
+export function liveDatabaseBehind(worldConfig: string, env: NodeJS.ProcessEnv, serviceData: string): string[] | undefined {
+  const step = databasePrepareOf(worldConfig);
+  if (!step || !existsSync(join(serviceData, 'PG_VERSION')) || liveDatabaseMigration(worldConfig, env, serviceData)) return undefined;
+  return [...step.command];
+}
+
+/**
+ * Whether this is a development World whose app may migrate its database when it starts
+ * (runtime.development.migrateDatabaseAtRuntime; schema.ts WorldDevelopment says whose the setting is).
+ */
+export function developmentMigratesAtRuntime(worldConfig: string): boolean {
+  return assertWorldConfig(JSON.parse(readFileSync(worldConfig, 'utf8')), worldConfig).development?.migrateDatabaseAtRuntime === true;
+}
+
+/** What a development World says each time it is brought up or built into an image, so its use is never silent. */
+export const DEVELOPMENT_MIGRATION_NOTICE = 'development World: its database migrates at run time; it is not prepared';
+
+/**
+ * The one placement of a prepared cluster, for every backing that prepares one (PGlite here, native PostgreSQL in
+ * native-postgres-backing.ts): an empty `serviceData` takes `prepared.directory` by rename when the stamp beside it
+ * is exactly `expected`; a mismatch is named, never taken. A migrated cluster's `migration` is recorded beside the data
+ * it becomes (liveDatabaseMigration).
+ */
+export function takePreparedCluster(prepared: { directory: string; stamp: string }, expected: string | ((stamp: string) => boolean), serviceData: string,
+  mismatch: string, migration?: PreparedMigration): { placed: boolean; note?: string } {
+  const { directory, stamp } = prepared;
+  if (existsSync(join(serviceData, 'PG_VERSION'))) return { placed: false };
   if (!existsSync(join(directory, 'PG_VERSION')) || !existsSync(stamp)) return { placed: false };
-  if (readFileSync(stamp, 'utf8') !== preparedStamp(service)) return { placed: false, note: `prepared cluster ${directory} not taken: its stamp names another PGlite pin or identity` };
+  const text = readFileSync(stamp, 'utf8');
+  if (typeof expected === 'string' ? text !== expected : !expected(text)) return { placed: false, note: `prepared cluster ${directory} not taken: its stamp names ${mismatch}` };
   if (existsSync(serviceData)) {
     if (readdirSync(serviceData).length) return { placed: false };
     rmdirSync(serviceData);
@@ -283,6 +487,7 @@ function placePreparedCluster(service: InfraService, serviceData: string, worldC
     if ((error as NodeJS.ErrnoException).code !== 'EXDEV') throw error;
     cpSync(directory, serviceData, { recursive: true });
   }
+  if (migration) writeFileSync(migrationRecord(serviceData), `${JSON.stringify(migration)}\n`);
   return { placed: true, note: `prepared cluster ${directory} placed at ${serviceData}` };
 }
 
@@ -312,7 +517,7 @@ export async function pgliteUp(services: InfraService[], dataDir: string, launch
   const started: string[] = [];
   try {
     for (const { service, name, serviceData, log, pidFile, argv } of plan) {
-      const placed = placePreparedCluster(service, serviceData, env.VOLTER_WORLD_CONFIG);
+      const placed = placePreparedCluster(service, serviceData, env.VOLTER_WORLD_CONFIG, env);
       mkdirSync(serviceData, { recursive: true });
       mkdirSync(dirname(log), { recursive: true });
       if (placed.note) { appendFileSync(log, `${placed.note}\n`); launch.note?.(placed.note); }