@volter/world-runtime 3.0.143 → 3.0.145

package/dist/src/pglite-backing.js

@@ -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 } from "./schema.js";
 import { connect } from 'node:net';
 import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
 import { spawn } from 'node:child_process';
 import { commandLifetime, COMMAND_GRACE_MS, COMMAND_CONFIRM_MS } from "./command-lifetime.js";
 import { survivingOwnedGroups } from "./process-groups.js";
 import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnReceiptPath, verifySpawnIdentity, signalOwnedProcess } from "./process-receipt.js";
 import { errorMessage } from "./error-message.js";
+import { runtimeManifest } from "./package-manifest.js";
 import { fileURLToPath } from 'node:url';
 import { parse } from 'yaml';
 import { mongodbArgv, mongodbReady, mongodbServes } from "./mongodb-backing.js";
@@ -212,34 +215,142 @@ export function preparedCluster(worldConfig) {
     const directory = join(dirname(worldConfig), PREPARED_DIRECTORY, containerlessDataDirectory('postgres'));
     return { directory, stamp: `${directory}.json` };
 }
-/**
- * What a prepared cluster must have been made with: this runtime (whose pglite-host.mjs is the open path that made
- * it), its exact PGlite pin (initdb's encoding and locale are PGlite's defaults: the host passes no initdb
- * parameters), and the declared user and database. The password is not in the cluster: the role is created without
- * one (LOGIN SUPERUSER) and the host's gateway checks the declared password on each connection, so a World with
- * 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() {
-    for (let dir = here();; dir = dirname(dir)) {
-        const candidate = join(dir, 'package.json');
-        if (existsSync(candidate)) {
-            const manifest = JSON.parse(readFileSync(candidate, 'utf8'));
-            if (manifest.name === '@volter/world-runtime')
-                return manifest;
-        }
-        if (dirname(dir) === dir)
-            throw new Error(`no @volter/world-runtime package.json above ${here()}`);
-    }
-}
-function preparedStamp(service) {
+function preparedStamp(service, migration) {
     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, inputs) {
+    const digests = {};
+    for (const input of inputs) {
+        const hash = createHash('sha256');
+        const walk = (absolute, relative) => {
+            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) {
+    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) {
+    const values = {};
+    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, evidence, env) {
+    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, worldConfig, launch) {
+    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) => { output += chunk.toString('utf8'); });
+    migration.stderr.on('data', (chunk) => { 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, directory, step, worldConfig, launch) {
+    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) => { hostOutput += chunk.toString('utf8'); });
+    host.stderr.on('data', (chunk) => { 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. */
 export async function pglitePrepare(service, worldConfig, launch = {}) {
@@ -262,20 +373,123 @@ export async function pglitePrepare(service, worldConfig, launch = {}) {
     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;
+    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, serviceData, worldConfig) {
+function placePreparedCluster(service, serviceData, worldConfig, env) {
+    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, env, directory) {
+    const step = databasePrepareOf(worldConfig);
+    if (!step)
+        return {};
+    let inputs;
+    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;
+        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;
+    }
+    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) => `${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) {
+    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, env, serviceData) {
+    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, env, serviceData) {
+    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) {
+    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, expected, serviceData, mismatch, migration) {
+    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 };
@@ -291,6 +505,8 @@ function placePreparedCluster(service, serviceData, worldConfig) {
             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}` };
 }
 export async function pgliteUp(services, dataDir, launch = {}) {
@@ -321,7 +537,7 @@ export async function pgliteUp(services, dataDir, launch = {}) {
     const started = [];
     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) {

package/dist/src/process-groups.mjs

@@ -14,10 +14,31 @@ export function survivingOwnedGroups(pids) {
     }
   });
   if (!candidates.length || process.platform === 'win32') return candidates;
-  const result = spawnSync('ps', ['-axo', 'pid=,pgid=,stat='], { windowsHide: true,
-    encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', maxBuffer: 4 * 1024 * 1024,
-  });
-  if (result.status !== 0 || result.error) return candidates;
+  const options = { windowsHide: true, encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', maxBuffer: 4 * 1024 * 1024 };
+  const result = spawnSync('ps', ['-axo', 'pid=,pgid=,stat='], options);
+  // When the whole-table listing does not answer (a non-zero status or an error; which of the two it was in the
+  // run this was written for, Cal build 43, was not read, and no measurement says why), every candidate would read
+  // as live, a group of zombies among them. Where the system can list one group by its leader (Darwin's `ps -g`: "processes with the
+  // specified process group leaders"), each candidate is asked for by itself, which does not walk the table; a
+  // group that cannot be listed either stays live.
+  if (result.status !== 0 || result.error) {
+    if (process.platform !== 'darwin') return candidates;
+    return candidates.filter(pid => {
+      const own = spawnSync('ps', ['-o', 'pid=,pgid=,stat=', '-g', String(pid)], options);
+      // Status 1 with no row is `ps` saying the group has no process; any other failure says nothing.
+      if (own.error || own.signal || (own.status !== 0 && !(own.status === 1 && !own.stdout.trim()))) return true;
+      const members = own.stdout.trim() ? own.stdout.trim().split('\n').map(line => line.trim().split(/\s+/)) : [];
+      // Visibility restrictions can omit a live group. Only ESRCH proves absence.
+      if (!members.length) {
+        for (const target of [-pid, pid]) {
+          try { process.kill(target, 0); return true; }
+          catch (error) { if (error.code !== 'ESRCH') return true; }
+        }
+        return false;
+      }
+      return members.some(([, , state]) => !state || !state.startsWith('Z'));
+    });
+  }
   const rows = result.stdout.trim().split('\n').map(line => line.trim().split(/\s+/));
   return candidates.filter(pid => {
     const members = rows.filter(([id, group]) => Number(group) === pid || Number(id) === pid);

package/dist/src/process-signal.mjs

@@ -1,6 +1,7 @@
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { survivingOwnedGroups } from './process-groups.mjs';
 
 // Retain the existing 1000 ms inspection ceiling, not a new timeout chosen from one sample.
 // Measured 2026-10-03 on shared Darwin 25.4.0 ARM64, Bun 1.3.11 (process.version
@@ -33,7 +34,24 @@ function birthProbe(pid) {
     },
   };
 }
-/** No subprocess on Linux; elsewhere the lookup never blocks the lifecycle event loop. */
+/** What a probe that could not answer says, once for each distinct outcome in this process: its command, error code,
+ *  exit, signal, timeout and branch. It is said, never thrown (see processBirth). */
+const saidProbeFailures = new Set();
+function sayProbeFailure(probe, error, code, signal, timedOut, reason) {
+  const line = `Process birth probe ${probe.command} failed (${reason}): errorCode=${error?.code ?? 'none'}, exit=${code ?? 'null'}, signal=${signal ?? 'null'}, timedOut=${timedOut}`;
+  if (saidProbeFailures.has(line)) return;
+  saidProbeFailures.add(line);
+  try { process.stderr.write(`[birth] ${line}; the birth is unknown (first asked of pid ${probe.args.at(-1)})\n`); } catch { /* an instrument */ }
+}
+/** A pid's birth, or undefined: no process has that pid, or the probe could not answer. A probe that cannot run is
+ *  a birth unknown, never a thrown lifecycle error: spawn throws synchronously where the process may not exec `ps` at
+ *  all (setuid root on macOS, which a sandbox-exec profile refuses with EPERM: an image build's prepare exited 1 for
+ *  it), and reports other failures as 'error', a timeout, another exit or output that is not a birth. Every command
+ *  the runtime runs captures its child's identity through this, and `down` asks it of every recorded pid, so a
+ *  rejection here would fail a command that succeeded and refuse a whole `down`. Ownership is decided elsewhere and
+ *  never from an unknown: verifySpawnIdentity refuses to retire a live pid whose birth it cannot read, and each
+ *  spawner that needs a birth refuses a child it captured none for. What the probe met is said once on stderr.
+ *  No subprocess on Linux; elsewhere the lookup never blocks the lifecycle event loop. */
 export async function processBirth(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return undefined; // a pid enters a probe's command only as an integer
   if (process.platform === 'linux') {
@@ -45,29 +63,43 @@ export async function processBirth(pid) {
   }
   const probe = birthProbe(pid);
   return new Promise(resolve => {
-    // A probe that cannot run is a birth unknown, never a lifecycle failure: spawn throws synchronously where the
-    // process may not exec `ps` at all (setuid root on macOS, which a sandbox-exec profile refuses: EPERM), and reports
-    // other failures as 'error' (below). Either way the identity is the pid without a start time.
     let child;
     try {
       child = spawn(probe.command, probe.args, {
         windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'],
         env: { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' },
       });
-    } catch {
+    } catch (error) {
+      sayProbeFailure(probe, error, null, null, false, 'spawn threw');
       resolve(undefined);
       return;
     }
     let output = '', settled = false;
-    const finish = value => { if (!settled) { settled = true; clearTimeout(timer); child.stdout.destroy(); resolve(value); } };
+    const finish = (value, error, code, signal, timedOut, reason) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.stdout.destroy();
+      if (value === undefined) sayProbeFailure(probe, error, code, signal, timedOut, reason);
+      resolve(value);
+    };
     // This is our still-held inspector, not a PID from a receipt.
     const timer = setTimeout(() => {
       try { signalChild(child, 'SIGKILL'); } catch { /* failed inspection remains unavailable */ }
-      finish(undefined); // an exited wrapper's descendant may keep stdout open indefinitely
+      finish(undefined, undefined, child.exitCode, child.signalCode, true, 'timeout'); // a descendant may keep stdout open
     }, BIRTH_LOOKUP_MS);
     child.stdout.on('data', chunk => { output += chunk; });
-    child.once('error', () => finish(undefined));
-    child.once('close', code => finish(code === 0 ? probe.read(output.trim()) : undefined));
+    child.once('error', error => finish(undefined, error, child.exitCode, child.signalCode, false, 'spawn error'));
+    child.once('close', (code, signal) => {
+      // No process by that pid is an answer, not a failed inspection, and is not said. `ps -p <pid>` (and the Windows
+      // probe) says it by ending on its own with status 1 and no row: read on Darwin 25.4, `ps -o pid=,lstart= -p <an
+      // exited pid>` prints nothing and exits 1; its manual gives `-p` no other way to say it. Everything else is
+      // the probe failing: it could not be spawned, was killed, ran out of time, exited otherwise, or printed
+      // something that is not a birth. That is said once and is also undefined.
+      if (code === 1 && signal === null && output.trim() === '') { if (!settled) { settled = true; clearTimeout(timer); child.stdout.destroy(); resolve(undefined); } return; }
+      finish(code === 0 ? probe.read(output.trim()) : undefined, undefined, code, signal, false,
+        code === 0 ? 'unrecognized birth output' : 'nonzero exit');
+    });
   });
 }
 /** Capture at spawn for durable ownership, never when retrying a retained PID. */
@@ -96,11 +128,28 @@ export async function verifySpawnIdentity(identity) {
     throw new Error(`Process ${identity.pid} identity cannot be established; ownership retained`);
   }
 }
+/** A signal the system refused has nothing left to reach when the process and its group are gone or are zombies
+ *  only: a zombie holds nothing and takes no signal, and a group of them is retired (Cal build 43: "kill EPERM"
+ *  after the postmaster had shut down). That is read from the process table (`survivingOwnedGroups`), never from
+ *  the error's code; where the table cannot be read the group counts as live and the refusal is thrown. */
+function nothingLeftToSignal(pid) {
+  try { return survivingOwnedGroups([pid]).length === 0; } catch { return false; }
+}
+/** An instrument: a signal that failed with anything but ESRCH says what it targeted and who is in that group, then
+ *  is thrown as before (Cal build 43: "kill EPERM" after the postmaster's clean shutdown). It changes no outcome. */
+function saySignalFailure(error, target, signal, child) {
+  try {
+    const rows = process.platform === 'win32' ? '' : spawnSync('ps', ['-o', 'pid=,pgid=,stat=,lstart=,command=', '-g', String(Math.abs(target))],
+      { encoding: 'utf8', timeout: BIRTH_LOOKUP_MS, killSignal: 'SIGKILL' }).stdout ?? '';
+    process.stderr.write(`[signal] ${error.code} kill(${target}, ${signal}) exitCode=${child?.exitCode} signalCode=${child?.signalCode} group: ${rows.trim() || 'no rows'}\n`);
+  } catch { /* the failure itself is still thrown by the caller */ }
+}
 /** Stored or retained numbers use birth verification before every delivery. */
 export async function signalOwnedProcess(identity, signal, group = false) {
   await verifySpawnIdentity(identity);
-  try { return process.kill(group && process.platform !== 'win32' ? -identity.pid : identity.pid, signal); }
-  catch (error) { if (error.code === 'ESRCH') return false; throw error; }
+  const target = group && process.platform !== 'win32' ? -identity.pid : identity.pid;
+  try { return process.kill(target, signal); }
+  catch (error) { if (error.code === 'ESRCH' || nothingLeftToSignal(identity.pid)) return false; saySignalFailure(error, target, signal); throw error; }
 }
 /** A live ChildProcess is ownership until exit. A group additionally needs its leader alive.
  * False means no held delivery was possible; a caller with surviving descendants needs a birth. */
@@ -108,9 +157,9 @@ export function signalChild(child, signal, group = false) {
   if (!child.pid || child.exitCode !== null || child.signalCode !== null) return false;
   if (!group || process.platform === 'win32') return child.kill(signal);
   try { process.kill(child.pid, 0); }
-  catch (error) { if (error.code === 'ESRCH') return false; throw error; }
+  catch (error) { if (error.code === 'ESRCH' || nothingLeftToSignal(child.pid)) return false; saySignalFailure(error, child.pid, 0, child); throw error; }
   try { return process.kill(-child.pid, signal); }
-  catch (error) { if (error.code === 'ESRCH') return false; throw error; }
+  catch (error) { if (error.code === 'ESRCH' || nothingLeftToSignal(child.pid)) return false; saySignalFailure(error, -child.pid, signal, child); throw error; }
 }
 
 /** Held first; an orphaned group then becomes retained numeric ownership. */

package/dist/src/project-inspect.d.ts

@@ -99,6 +99,15 @@ export declare function projectConnections(input?: string, attributedEnv?: Set<s
  * env heuristic. Only direct `fetch("https://...")`, `window.fetch`, and `globalThis.fetch` calls
  * count. Dynamic destinations remain intentionally unclaimed; guessing from arbitrary URL strings
  * would turn docs, links, and webhook examples into false external-service dependencies. */
+/** A migration tool an application carries, by its evidence in the repository (architecture, World wiring). */
+export interface ProjectMigrationTool {
+    tool: string;
+    /** the tool's schema, and its migrations directory, relative to the repository */
+    schema: string;
+    migrations: string;
+}
+/** Each migration tool the repository depends on that has migrations beside its schema (or beside its schema's folder). */
+export declare function projectMigrationTools(input?: string): ProjectMigrationTool[];
 export declare function projectFetchUrls(input?: string): ProjectFetchUrl[];
 /** Env names read directly by production JS/TS source, with repo-relative `path:line` evidence.
  * This is intentionally evidence, not validator inference: seeing an empty example value read by

package/dist/src/project-inspect.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { parse as parseToml } from 'smol-toml';
-import { basename, relative, resolve } from 'node:path';
+import { basename, dirname, relative, resolve } from 'node:path';
 import { normalizePypiName, overlayPypiTwins, overlaySdkTwins } from "./pack-facts.js";
 /** npm package → vendor/twin mapping — the shared vendor↔SDK knowledge used by both
  * `inspect-project` (adoption discovery) and `covers` (room-setup coverage proof).
@@ -663,13 +663,36 @@ export function projectConnections(input = process.cwd(), attributedEnv = new Se
     }
     return [...merged.values()];
 }
-/** Literal HTTP(S) destinations passed directly to the platform fetch API in production source.
- *
- * This is the third vendor signal beside dependencies and env names: hand-written REST clients
- * often declare no SDK, and an unconventional credential name can hide the same vendor from the
- * env heuristic. Only direct `fetch("https://...")`, `window.fetch`, and `globalThis.fetch` calls
- * count. Dynamic destinations remain intentionally unclaimed; guessing from arbitrary URL strings
- * would turn docs, links, and webhook examples into false external-service dependencies. */
+/**
+ * The migration tools `init` can notice from a repository: the tool as a dependency, and its own migrations beside
+ * its schema. One row per tool; the next tool is a row. What a World's `runtime.database.prepare` needs (the command
+ * as the image runs it, the image path it runs in, the inputs' paths there) is the IMAGE's, which a repository does
+ * not state: a Dockerfile's prune and copies decide it. So this names the tool and where its migrations are, never
+ * the step.
+ */
+const MIGRATION_TOOLS = [
+    { tool: 'prisma', dependency: 'prisma', schemaExtension: '.prisma', migrations: 'migrations' },
+];
+/** Each migration tool the repository depends on that has migrations beside its schema (or beside its schema's folder). */
+export function projectMigrationTools(input = process.cwd()) {
+    const root = resolve(input);
+    const dependencies = new Set(projectDependencies(root));
+    const found = new Map();
+    for (const row of MIGRATION_TOOLS) {
+        if (!dependencies.has(row.dependency))
+            continue;
+        for (const schema of projectSourceFiles(root, new Set([row.schemaExtension]))) {
+            const beside = [dirname(schema), dirname(dirname(schema))].map((dir) => resolve(dir, row.migrations))
+                .find((dir) => existsSync(dir) && statSync(dir).isDirectory());
+            if (!beside)
+                continue;
+            const migrations = relative(root, beside);
+            if (!found.has(`${row.tool}\0${migrations}`))
+                found.set(`${row.tool}\0${migrations}`, { tool: row.tool, schema: relative(root, schema), migrations });
+        }
+    }
+    return [...found.values()].sort((a, b) => a.migrations.localeCompare(b.migrations));
+}
 export function projectFetchUrls(input = process.cwd()) {
     const root = resolve(input);
     const found = [];

package/dist/src/runtime.js

@@ -1334,6 +1334,24 @@ async function startExternalService(service, paths, worldEnv, stripEnv, boot) {
         }
         injected[mapping.as] = value;
     }
+    // The World's own infrastructure also says what the app's commands are told of its database (architecture,
+    // managed infrastructure): that the live data carries the image's migration, and that this is a development
+    // World whose app migrates when it runs.
+    if (ownInfrastructureUp(external.up) && statusOutput) {
+        let facts;
+        try {
+            facts = JSON.parse(statusOutput);
+        }
+        catch { /* a status that is not JSON says neither */ }
+        const migrated = facts?.database?.migrated;
+        if (Array.isArray(migrated) && migrated.every((word) => typeof word === 'string'))
+            injected.VOLTER_WORLD_DATABASE_MIGRATED = JSON.stringify(migrated);
+        const behind = facts?.database?.behind;
+        if (Array.isArray(behind) && behind.every((word) => typeof word === 'string'))
+            injected.VOLTER_WORLD_DATABASE_BEHIND = JSON.stringify(behind);
+        if (facts?.development?.migrateDatabaseAtRuntime === true)
+            injected.VOLTER_WORLD_DEVELOPMENT_MIGRATE_AT_RUNTIME = '1';
+    }
     return {
         id: service.id,
         type: 'external',
@@ -3972,8 +3990,11 @@ export async function attachWorld(name, command, root = process.cwd(), options =
             throw new Error(`World "${name}" is changing lifecycle; retry after it finishes`);
         }
         const current = statusWorld(name, resolvedRoot);
-        if (!current.running || current.createdAt !== attached.instance.createdAt)
-            throw new Error(`World "${name}" is stopped or changed while attaching`);
+        // Which of the two it was, with what was read: "stopped" and "another instance" are different repairs.
+        if (!current.running)
+            throw new Error(`World "${name}" is not running while attaching: none of its recorded processes is live and its own (recorded pids ${readPids(current.pidsFile).join(', ') || 'none'}; live and its own: none)`);
+        if (current.createdAt !== attached.instance.createdAt)
+            throw new Error(`World "${name}" changed while attaching: its instance was created ${attached.instance.createdAt} when the command's environment was read and ${current.createdAt} now`);
         // Attaching to a World whose services died is allowed (a command may not need them), but never silent.
         for (const [id, state] of Object.entries(current.serviceStates)) {
             if (state === 'running' || state === 'external')