@volter/world-runtime 3.0.144 → 3.0.146

package/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/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/src/project-inspect.ts

@@ -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.ts';
 
 export type ProjectInspection = {
@@ -628,6 +628,43 @@ export function projectConnections(input = process.cwd(), attributedEnv = new Se
  * 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;
+}
+
+/**
+ * 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: Array<{ tool: string; dependency: string; schemaExtension: string; migrations: string }> = [
+  { 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()): ProjectMigrationTool[] {
+  const root = resolve(input);
+  const dependencies = new Set(projectDependencies(root));
+  const found = new Map<string, ProjectMigrationTool>();
+  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()): ProjectFetchUrl[] {
   const root = resolve(input);
   const found: ProjectFetchUrl[] = [];

package/src/runtime.ts

@@ -1316,6 +1316,18 @@ async function startExternalService(
     }
     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: { database?: { migrated?: unknown; behind?: unknown }; development?: { migrateDatabaseAtRuntime?: unknown } } | undefined;
+    try { facts = JSON.parse(statusOutput) as typeof facts; } 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,
@@ -3746,7 +3758,9 @@ export async function attachWorld(name: string, command: string[], root = proces
       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') continue;

package/src/schema.ts

@@ -23,14 +23,31 @@ export const WORLD_USAGES = ['application', 'dependencies', 'build', 'deployment
 export type WorldUsage = typeof WORLD_USAGES[number];
 export type WorldSelectionSelector = { usage?: WorldUsage; vendor?: string };
 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;
   metadata: { id: string; description?: string };
-  discovery?: { selection?: WorldSelection };
+  discovery?: { selection?: WorldSelection; coverage?: WorldCoverage };
   services: unknown[];
-  runtime?: { isolation?: WorldIsolation; environment?: { values?: Record<string, string>; strip?: string[] }; network?: WorldNetwork };
+  runtime?: { isolation?: WorldIsolation; environment?: { values?: Record<string, string>; strip?: string[] }; network?: WorldNetwork; database?: { prepare?: WorldDatabasePrepare }; development?: WorldDevelopment };
   serving?: { mode?: 'app' | 'bare'; name?: string; share?: WorldShareConfig };
   remotes?: Record<string, string>;
   changesets?: WorldChangesetRules;
@@ -256,8 +273,32 @@ export type WorldServiceConfig = {
  *  generated from its changes. A team's rules, committed with the World, as a repository's are. */
 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. */
@@ -265,6 +306,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>/…`. */
@@ -845,7 +888,25 @@ function normalizeV2(value: Record<string, unknown>, path: string): WorldConfig
   const serving = (value.serving ?? {}) as Record<string, unknown>;
   const scenario = (value.scenario ?? {}) as Record<string, unknown>;
   const provenance = (value.provenance ?? {}) as Record<string, unknown>;
-  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: unknown): value is string[] => 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);
   const environment = runtime.environment ?? {};
   if (!record(environment)) throw new Error(`runtime.environment must be an object in ${path}`);
@@ -859,6 +920,7 @@ function normalizeV2(value: Record<string, unknown>, path: string): WorldConfig
   if (mode === 'app' && serving.name !== undefined) 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: WorldConfig = {
     ...Object.fromEntries(Object.entries(value).filter(([key]) => key.startsWith('//'))),
@@ -866,9 +928,12 @@ function normalizeV2(value: Record<string, unknown>, path: string): WorldConfig
     ...(metadata.description === undefined ? {} : { description: metadata.description as string }),
     manifestVersion: 2,
     selection,
+    ...(discovery.coverage === undefined ? {} : { coverage: discovery.coverage as WorldCoverage }),
     services: value.services.map((service) => serviceV2ToLegacy(service, path)),
     ...(runtime.isolation === undefined ? {} : { isolation: runtime.isolation as WorldIsolation }),
     ...(runtime.network === undefined ? {} : { network: normalizeWorldNetwork(runtime.network) }),
+    ...(databasePrepare === undefined ? {} : { databasePrepare: databasePrepare as WorldDatabasePrepare }),
+    ...(development.migrateDatabaseAtRuntime === true ? { development: { migrateDatabaseAtRuntime: true } } : {}),
     ...(environment.values === undefined ? {} : { env: environment.values as Record<string, string> }),
     ...(environment.strip === undefined ? {} : { stripEnv: environment.strip as string[] }),
     ...(mode === 'bare' ? { bare: { name: serving.name as string } } : {}),
@@ -882,6 +947,33 @@ function normalizeV2(value: Record<string, unknown>, path: string): WorldConfig
   return { ...assertLegacyWorldConfig(normalized, path), manifestVersion: 2, selection };
 }
 
+const WORLD_COVERAGE_LISTS = ['covered', 'notCovered', 'uninterceptable', 'unknownSdk', 'acknowledged', 'excludedBySelection'] as const;
+
+export function assertWorldCoverage(value: unknown, path: string): asserts value is WorldCoverage {
+  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'] as const) 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: unknown, path: string): WorldConfig {
   if (record(value) && value.schemaVersion !== undefined) {
     if (value.schemaVersion !== WORLD_SCHEMA_VERSION) throw new Error(`Unsupported World schemaVersion ${String(value.schemaVersion)} in ${path}`);
@@ -952,9 +1044,11 @@ export function worldConfigDocument(config: WorldConfig, selection: WorldSelecti
   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/src/up-cli.ts

@@ -27,7 +27,13 @@ export async function upCommand(subject: string | undefined, rest: string[], roo
   // saves a whole command between up and the app's start.
   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.ts');
     setAppUrl(instance.name, appUrl, { root });
@@ -37,6 +43,15 @@ export async function upCommand(subject: string | undefined, rest: string[], roo
   else printReady(instance);
 }
 
+async function upInProcess(configId: string, options: Parameters<typeof upWorld>[1]): Promise<Awaited<ReturnType<typeof upWorld>>> {
+  const { upWorld } = await import('./runtime.ts');
+  const abort = new AbortController();
+  const cancel = (signal: NodeJS.Signals) => 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: Awaited<ReturnType<typeof upWorld>>): void {
   process.stdout.write(`World ${instance.name} is ready (${instance.config})
 Instance: ${instance.instance}