@volter/world-runtime 3.0.163 → 3.0.164

package/src/native-postgres-backing.ts

@@ -2,7 +2,7 @@
 // belong to the infrastructure service; a recipe never operates postgres itself.
 import { spawn, type ChildProcess } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { accessSync, closeSync, constants, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { accessSync, chmodSync, chownSync, copyFileSync, lchownSync, lstatSync, closeSync, constants, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { connect } from 'node:net';
 import { runtimeManifest } from './package-manifest.ts';
 import { delimiter, dirname, join, resolve } from 'node:path';
@@ -10,8 +10,81 @@ import { commandLifetime, COMMAND_GRACE_MS, CommandRetirementError } from './com
 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 { worldEvent } from './process-groups.mjs';
 import { errorMessage } from './error-message.ts';
-import { PREPARED_DIRECTORY, databasePrepareOf, expectedMigration, forgetStaleMigration, keepFailureEvidence, runDatabasePrepare, takePreparedCluster, type HostLaunch, type InfraService, type PreparedMigration } from './pglite-backing.ts';
+import { PREPARED_DIRECTORY, PREPARE_STATE_DIRECTORY, packageScriptPath, databasePrepareOf, environmentFile, expectedMigration, forgetStaleMigration, keepFailureEvidence, migrationInputDigests, preparedStore, preparedStoreStamp, preparedWorldServices, runDatabasePrepare, takePreparedCluster, type HostLaunch, type InfraService, type PreparedMigration } from './pglite-backing.ts';
+import type { WorldDatabasePrepare } from './schema.ts';
+
+
+/** OS identity, distinct from PostgreSQL's configured SQL role. No in-process privilege mutation. */
+function postgresRunAs(): { uid: number; gid: number } {
+  const uid = process.getuid?.(); const gid = process.getgid?.();
+  if (uid === undefined || gid === undefined) throw new Error('native PostgreSQL requires a numeric OS process identity');
+  if (uid !== 0) return { uid, gid };
+  const accounts = readFileSync('/etc/passwd', 'utf8').split('\n').map(line => line.split(':'));
+  for (const name of ['postgres', 'nobody']) {
+    const account = accounts.find(fields => fields[0] === name && /^\d+$/.test(fields[2] ?? '') && /^\d+$/.test(fields[3] ?? '')
+      && Number(fields[2]) > 0 && Number(fields[2]) < 0xffffffff && Number(fields[3]) > 0 && Number(fields[3]) < 0xffffffff);
+    if (account) return { uid: Number(account[2]), gid: Number(account[3]) };
+  }
+  throw new Error('native PostgreSQL started by root requires an installed non-root postgres or nobody account');
+}
+
+/**
+ * The prepared cluster copied as the server's own (S2 R15): each directory, file and link made, its mode taken from
+ * the source as cpSync takes it, and given to the server's uid and gid as it is made. A cpSync and then
+ * ownPostgresCluster's walk asked the tree for every one of the cluster's files twice more (Cal in a tab: the
+ * placing step 170 ms, each ask a kernel request from up's process).
+ */
+function copyClusterOwned(runAs: { uid: number; gid: number }): (from: string, to: string) => void {
+  const copy = (from: string, to: string): void => {
+    const stat = lstatSync(from);
+    if (stat.isSymbolicLink()) { symlinkSync(readlinkSync(from), to); lchownSync(to, runAs.uid, runAs.gid); return; }
+    if (stat.isDirectory()) {
+      mkdirSync(to);
+      for (const name of readdirSync(from)) copy(join(from, name), join(to, name));
+    } else if (stat.isFile()) copyFileSync(from, to);
+    else throw new Error(`native PostgreSQL's prepared cluster holds a ${stat.isFIFO() ? 'FIFO' : 'special file'}, which is not copied: ${from}`);
+    chmodSync(to, stat.mode & 0o7777);
+    chownSync(to, runAs.uid, runAs.gid);
+  };
+  return copy;
+}
+
+/** Assign only the stopped World's cluster, including a cluster placed from preparation. Never follow links. */
+function ownPostgresCluster(data: string, runAs: { uid: number; gid: number }): { walked: number; changed: number } {
+  // What the walk did, said by the start's step (S2 R71): every entry is looked at, and only another owner's changed.
+  const counts = { walked: 0, changed: 0 };
+  const visit = (path: string): void => {
+    const stat = lstatSync(path);
+    counts.walked += 1;
+    if (stat.uid !== runAs.uid || stat.gid !== runAs.gid) {
+      counts.changed += 1;
+      if (stat.isSymbolicLink()) lchownSync(path, runAs.uid, runAs.gid);
+      else chownSync(path, runAs.uid, runAs.gid);
+    }
+    if (stat.isDirectory()) for (const name of readdirSync(path)) visit(join(path, name));
+  };
+  visit(data);
+  return counts;
+}
+
+/** The service may traverse its own World bookkeeping directories, without reading their private receipts. */
+function postgresDirectorySearch(root: string, env: NodeJS.ProcessEnv, runAs: { uid: number; gid: number }): void {
+  const directories = [root];
+  // The live lifecycle creates instance/data as 0700. Only its recorded instance is granted search;
+  // preparation has a different root and never changes the application's directory above it.
+  if (env.VOLTER_WORLD_INSTANCE && env.VOLTER_WORLD_DATA
+    && resolve(env.VOLTER_WORLD_DATA) === resolve(root)
+    && dirname(resolve(env.VOLTER_WORLD_INSTANCE)) === dirname(resolve(root))) directories.push(dirname(resolve(root)));
+  for (const directory of directories) {
+    const stat = lstatSync(directory);
+    if (!stat.isDirectory()) throw new Error(`native PostgreSQL directory is not a directory: ${directory}`);
+    if ((stat.uid === runAs.uid && (stat.mode & 0o100)) || (stat.gid === runAs.gid && (stat.mode & 0o010)) || (stat.mode & 0o001)) continue;
+    chownSync(directory, stat.uid, runAs.gid);
+    chmodSync(directory, (stat.mode & 0o7777) | 0o010);
+  }
+}
 
 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 }
@@ -46,11 +119,58 @@ function ownership(root: string) {
   }
   return { present: records.some(row => row.present) || spawn.present, held: values.find(row => row.pid === spawn.value?.pid) ?? values[0], identity: spawn.value, values, errors };
 }
-function verifyOwner(held: Ownership): void {
-  const lines = readFileSync(join(held.data, 'postmaster.pid'), 'utf8').split('\n');
+/**
+ * Whether postmaster.pid names the postmaster this lifecycle holds. The postmaster CREATES that file and then writes
+ * it, and removes it as it exits: a reader meets it empty, part written, or gone. Those are not a cluster owned by
+ * another; they are a file not written yet (false: ask again). A mismatch is four COMPLETE lines of which the pid,
+ * the data directory or the port differs, and it is refused with what was read beside what was held.
+ */
+function verifyOwner(held: Ownership): boolean {
+  let text: string;
+  try { text = readFileSync(join(held.data, 'postmaster.pid'), 'utf8'); } catch { return false; }
+  const lines = text.split('\n');
+  // Lines 1-4 are pid, data directory, start time, port; each is complete when a line follows it.
+  if (lines.length < 5 || lines.slice(0, 4).some((line) => line.trim() === '')) return false;
   if (Number(lines[0]) !== held.pid || resolve(lines[1]!) !== held.data || Number(lines[3]) !== held.port) {
-    throw new Error('native postgres ownership does not match the cluster; teardown refused');
+    // A FILE LEFT BY A POSTMASTER THAT IS GONE IS STALE, NOT ANOTHER OWNER. After a kill or a crash the file stays,
+    // four complete lines naming a pid with no process; the postmaster just started reads it, finds that, and
+    // writes its own. Read in between, it names neither this postmaster nor a live one: not written yet. Only a
+    // file naming a LIVE process that is not this one, or this one with another directory or port, is a mismatch.
+    const named = Number(lines[0]);
+    if (named !== held.pid && Number.isInteger(named) && named > 0) {
+      let gone = false;
+      try { process.kill(named, 0); } catch (error) { gone = (error as NodeJS.ErrnoException).code === 'ESRCH'; }
+      if (gone) return false;
+    }
+    throw new Error(`native postgres ownership does not match the cluster; teardown refused (postmaster.pid says pid ${lines[0]}, data ${lines[1]}, port ${lines[3]}; this lifecycle holds pid ${held.pid}, data ${held.data}, port ${held.port})`);
+  }
+  return true;
+}
+/**
+ * THE POSTMASTER'S STOP. PostgreSQL's contract for a stop is one signal to the postmaster (SIGINT, its fast
+ * shutdown; what pg_ctl sends): it ends its backends itself, writes the shutdown checkpoint and removes
+ * postmaster.pid. A signal to its GROUP reaches the checkpointer and the writers too, which are not the ones to
+ * tell. Between the signal and its exit the postmaster is writing the cluster down, and how long that takes is the
+ * size of what is dirty, so it is awaited on the lifecycle's own budget (READY_TIMEOUT_MS), never a command's
+ * grace: a SIGKILL in the middle of the checkpoint leaves a cluster with its pid file, which nothing takes. Only
+ * past that budget is the group killed, and that is said as a kill. The stop, the exit, and the time between are
+ * events in the World's log.
+ */
+async function stopPostmaster(pid: number, deliver: (signal: NodeJS.Signals, group: boolean) => Promise<boolean> | boolean, by: string, data?: string): Promise<void> {
+  if (!liveGroup(pid)) return;
+  const asked = Date.now();
+  worldEvent({ event: 'world.service.stop', service: 'postgres', by, signal: 'SIGINT', to: 'pid', pid });
+  await deliver('SIGINT', false);
+  const deadline = asked + READY_TIMEOUT_MS;
+  while (liveGroup(pid) && Date.now() < deadline) await wait(100);
+  if (!liveGroup(pid)) {
+    worldEvent({ event: 'world.service.exited', service: 'postgres', by, pid, shutdownMs: Date.now() - asked, ...(data ? { pidFileLeft: existsSync(join(data, 'postmaster.pid')) } : {}) });
+    return;
   }
+  worldEvent({ event: 'world.service.killed', service: 'postgres', by, pid, signal: 'SIGKILL', to: 'group', afterMs: Date.now() - asked, doing: 'its shutdown had not ended within the lifecycle budget; the cluster is left with its pid file and is not taken' });
+  await deliver('SIGKILL', true);
+  const confirm = Date.now() + COMMAND_GRACE_MS;
+  while (liveGroup(pid) && Date.now() < confirm) await wait(20);
 }
 const liveGroup = (pid: number) => pid > 0 && survivingOwnedGroups([pid]).length > 0;
 function removeReceipts(root: string): void {
@@ -65,6 +185,11 @@ function removeReceipts(root: string): void {
   }
   if (errors.length) throw new AggregateError(errors, 'native postgres retired but receipt cleanup failed');
 }
+async function retirePostmaster(identity: SpawnIdentity, by: string, data?: string): Promise<void> {
+  await stopPostmaster(identity.pid, (signal, group) => signalOwnedProcess(identity, signal, group, by), by, data);
+  if (liveGroup(identity.pid)) throw new Error(`native postgres group ${identity.pid} retirement unconfirmed; ownership retained`);
+}
+/** A helper this backing started (psql, createdb, initdb): it holds no state, and keeps a command's grace. */
 async function retireIdentity(identity: SpawnIdentity): Promise<void> {
   const { pid } = identity;
   for (const signal of ['SIGINT', 'SIGKILL'] as const) {
@@ -76,19 +201,17 @@ async function retireIdentity(identity: SpawnIdentity): Promise<void> {
   if (liveGroup(pid)) throw new Error(`native postgres group ${pid} retirement unconfirmed; ownership retained`);
 }
 /** A retained child is ownership even before postmaster.pid or the ready receipt exists. */
-async function retireStarted(started: Started): Promise<void> {
+async function retireStarted(started: Started, by = 'down (this process started it)'): Promise<void> {
   const { child, owned } = started;
   child.ref();
-  for (const signal of ['SIGINT', 'SIGKILL'] as const) {
+  if (owned.pid > 0) {
+    await stopPostmaster(owned.pid, async (signal, group) => signalChild(child, signal, group, by)
+      || (liveGroup(owned.pid) ? signalOwnedProcess(started.identity ?? await started.birth, signal, group, by) : false), by, owned.data);
+  }
+  const deadline = Date.now() + COMMAND_GRACE_MS;
+  while (Date.now() < deadline) {
     if (started.closed && !liveGroup(owned.pid)) return;
-    if (owned.pid > 0 && !signalChild(child, signal, true) && liveGroup(owned.pid)) {
-      await signalOwnedProcess(started.identity ?? await started.birth, signal, true);
-    }
-    const deadline = Date.now() + COMMAND_GRACE_MS;
-    while (Date.now() < deadline) {
-      if (started.closed && !liveGroup(owned.pid)) return;
-      await wait(20);
-    }
+    await wait(20);
   }
   throw new Error(`native postgres child ${owned.pid} retirement unconfirmed; ownership retained`);
 }
@@ -120,11 +243,11 @@ 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> {
+async function tool(command: string, args: string[], env: NodeJS.ProcessEnv, deadline: number, root: string, runAs: { uid: number; gid: number }, signal?: AbortSignal): Promise<string> {
   signal?.throwIfAborted();
   const remaining = deadline - Date.now();
   if (remaining <= 0) throw new Error(`native postgres readiness deadline elapsed before ${command}`);
-  const child = spawn(command, args, { env, detached: true, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+  const child = spawn(command, args, { env, ...runAs, detached: true, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
   const lifetime = commandLifetime(child, signal);
   let output = ''; let errorOutput = ''; let spawnError: Error | undefined; let timedOut = false; let failure: unknown;
   child.stdout?.on('data', chunk => { output += chunk; });
@@ -213,6 +336,18 @@ export function nativePostgresTools(env: NodeJS.ProcessEnv): string | undefined
   return undefined;
 }
 
+/**
+ * How a cluster left running is made durable before its recovery: one syncfs of its file system, where PostgreSQL's
+ * default opens and fsyncs every file under the data directory. A World's postmaster is not stopped when its tab
+ * closes, so a returning visit recovers: the Umami f7b17202 pair's second visit spent 652 ms in the startup process
+ * (3,078 opens, 1,496 fsyncs, 244 directory reads), where the first's took 77 ms, and was ready at check 8, not 5
+ * (S2 L1). syncfs is Linux's (PostgreSQL builds it where the C library has it: glibc, and the musl the tab's postgres
+ * is built with); macOS has none, and an option its build lacks is refused at start, so only Linux asks for it.
+ */
+function recoverySync(): string[] {
+  return process.platform === 'linux' ? ['-c', 'recovery_init_sync_method=syncfs'] : [];
+}
+
 /** 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'];
@@ -294,6 +429,131 @@ function nativeStampMatches(text: string, expected: NativeStamp): boolean {
  * 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.
  */
+/** Every log file under a state directory, as one text with each file's path before its lines; empty when none. */
+function worldLogs(state: string): string {
+  const out: string[] = [];
+  const walk = (directory: string): void => {
+    let names: string[];
+    try { names = readdirSync(directory).sort(); } catch { return; }
+    for (const name of names) {
+      const path = join(directory, name);
+      let stats;
+      try { stats = statSync(path); } catch { continue; }
+      if (stats.isDirectory()) { if (name !== 'native-postgres-data' && name !== 'node_modules') walk(path); }
+      else if (stats.isFile() && /\.log$/.test(name) && stats.size <= 8 * 1024 * 1024) {
+        try { out.push(`==> ${path} <==\n${readFileSync(path, 'utf8')}`); } catch { /* a log that cannot be read is left out */ }
+      }
+    }
+  };
+  walk(state);
+  return out.join('\n');
+}
+
+/**
+ * A managed store, other than the cluster, that keeps its bytes under the World's data and is staged with it: the
+ * tree of a service a twin serves, which twin-backing.ts names `<kind>-twin` (redis-twin).
+ */
+const stagedStore = (name: string): boolean => /^[a-z0-9]+-twin$/.test(name);
+
+/** The state directory a preparation with the World up boots its disposable instance in, beside the World's own. */
+
+/**
+ * A cluster migrated by a step that needs the World (`runtime.database.prepare.with: "world"`): a migration that
+ * talks to a service the World supplies (a cache it flushes, a queue it registers with, a vendor it reads) cannot
+ * run against a bare postmaster. The World is brought up whole, as `run` brings it up, in a state directory of its
+ * own beside the World's (`.volter-prepare`), with no prepared cluster to take, so its managed PostgreSQL is made
+ * new by initdb; the step is the World's foreground command, in the app's tree, with the image's environment under
+ * the World's own (the names its twins issued and its infrastructure discovered); the World then goes down, which
+ * stops the postmaster cleanly. The stopped cluster is moved to the World's prepared place and stamped with the
+ * step, its inputs' digests and the twins that were up. Each other managed store that keeps its bytes under the
+ * World's data (the tree of each service a twin serves, `<kind>-twin`: the Redis twin's root) is staged beside the cluster with the same migration in a
+ * stamp of its own, since what the step wrote there is the World's prepared state as much as its tables are.
+ * Everything else that instance wrote (a twin's own state, its logs) is named in the note and removed with the
+ * state directory. A step that fails leaves no cluster, keeps the step's whole output where a failed preparation
+ * keeps its evidence, and says so.
+ */
+async function prepareWithWorld(step: WorldDatabasePrepare, definition: string, worldConfig: string, tools: string, env: NodeJS.ProcessEnv, launch: HostLaunch): Promise<string> {
+  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 root = dirname(worldConfig);
+  const { directory, stamp } = nativePreparedCluster(worldConfig);
+  const state = join(root, PREPARE_STATE_DIRECTORY);
+  rmSync(directory, { recursive: true, force: true });
+  rmSync(stamp, { force: true });
+  rmSync(state, { recursive: true, force: true });
+  // The other stores a step run with the World up may write, staged beside the cluster (architecture, "A step may
+  // need the World"): each by the name of its directory under the World's data.
+  const previouslyStaged = (): string[] => { try { return readdirSync(dirname(directory)).filter(stagedStore); } catch { return []; } };
+  const unstage = (): void => { for (const name of previouslyStaged()) { const store = preparedStore(worldConfig, name); rmSync(store.directory, { recursive: true, force: true }); rmSync(store.stamp, { force: true }); } };
+  unstage();
+  const cwd = join(appRoot, step.cwd);
+  const { user, database } = settings(definition);
+  // The World's run reads this process's environment: the preparation's own (its PostgreSQL programs, the app's
+  // root), the image's values over it as for a step run alone, and the state directory. This process is the
+  // preparation and nothing else, so its environment is the preparation's to set.
+  const { PATH: _imagePath, ...imageValues } = env.VOLTER_WORLD_APP_ENV ? environmentFile(env.VOLTER_WORLD_APP_ENV) : {};
+  const before = { ...process.env };
+  for (const [name, value] of Object.entries({ ...env, ...imageValues, VOLTER_STATE_DIR: PREPARE_STATE_DIRECTORY })) if (value !== undefined) process.env[name] = value;
+  // The step is a package script's command here too, and is found where the application's own start finds it
+  // (pglite-backing.ts runDatabasePrepare): each node_modules/.bin from its working directory upward, before PATH.
+  process.env.PATH = [...packageScriptPath(cwd, appRoot), process.env.PATH ?? ''].filter(Boolean).join(delimiter);
+  delete process.env.VOLTER_WORLD_CONFIG;
+  const names = join(state, 'prepare.env');
+  let moved = false;
+  try {
+    const { runWorldOwned } = await import('./runtime.ts');
+    let ran: Awaited<ReturnType<typeof runWorldOwned>>;
+    try { ran = await runWorldOwned(worldConfig, step.command, { root, cwd, owner: 'database-prepare', envFile: names, forceEnvOutput: true }, launch.signal); }
+    catch (error) { throw new Error(`the World's database prepare step (${step.command.join(' ')}), run with the World up, did not complete: ${errorMessage(error)}`, { cause: error }); }
+    const log = ran.outcome.log, output = log && existsSync(log) ? readFileSync(log, 'utf8') : '';
+    if (ran.exitCode !== 0) {
+      throw new Error(`the World's database prepare step (${step.command.join(' ')}), run with the World up, exited ${ran.exitCode}\n${output.trim().split('\n').slice(-40).join('\n')}${keepFailureEvidence('database-prepare-step-output', output, env)}`);
+    }
+    const data = join(ran.instance.dirs.data, 'native-postgres-data');
+    if (!existsSync(join(data, 'PG_VERSION'))) throw new Error(`the World came up without a native PostgreSQL cluster at ${data}: a step declared with: "world" is prepared on the native backing only`);
+    if (existsSync(join(data, 'postmaster.pid'))) throw new Error('the World went down and left its postmaster\'s pid file: the cluster was not stopped cleanly and is not taken');
+    const given = existsSync(names) ? readFileSync(names, 'utf8').split('\n').map((line) => /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=/.exec(line)?.[1]).filter((name): name is string => name !== undefined) : [];
+    const world = preparedWorldServices(worldConfig);
+    mkdirSync(dirname(directory), { recursive: true });
+    renameSync(data, directory);
+    moved = true;
+    const migration: PreparedMigration = { command: [...step.command], inputs: migrationInputDigests(cwd, step.inputs), world };
+    const staged: string[] = [];
+    for (const name of readdirSync(ran.instance.dirs.data).filter(stagedStore).sort()) {
+      const from = join(ran.instance.dirs.data, name), store = preparedStore(worldConfig, name);
+      if (!statSync(from).isDirectory() || !readdirSync(from).length) continue;
+      // The twin that served this root is gone when its pid file is: the World's down waits for it and removes the
+      // file (twin-backing.ts). One left behind is a twin that may still be writing, as a postmaster's is above.
+      const left = readdirSync(ran.instance.dirs.data).filter((entry) => entry.startsWith(`${name}-`) && entry.endsWith('.pid'));
+      if (left.length) throw new Error(`the World went down and left ${left.join(', ')}: the ${name} was not stopped cleanly and its root is not staged`);
+      renameSync(from, store.directory);
+      writeFileSync(store.stamp, preparedStoreStamp(migration));
+      staged.push(name);
+    }
+    // Everything else the instance left under its data, by name: not staged, and gone with the state directory.
+    const notStaged = readdirSync(ran.instance.dirs.data).filter((name) => !/\.(?:log|pid|json)$/.test(name) && !/^(?:logs?|run)$/.test(name)).sort();
+    // The cluster's stamp is written LAST: a preparation killed before here leaves a cluster nothing takes, never a
+    // stamped cluster whose stores did not arrive.
+    writeFileSync(stamp, `${JSON.stringify(nativeStamp(tools, user, database, true, migration))}\n`);
+    launch.note?.(`prepared stores beside the cluster: ${staged.join(', ') || 'none'}${notStaged.length ? `; left under the instance's data and not staged: ${notStaged.join(', ')}` : ''}`);
+    launch.note?.(`database prepare step, with the World up (${Object.entries(world).map(([id, version]) => `${id}@${version}`).join(', ') || 'no twins'}; ${given.length} names given: ${given.join(', ')}): ${step.command.join(' ')}\n${output.trim()}`);
+    return directory;
+  } catch (error) {
+    if (moved) { rmSync(directory, { recursive: true, force: true }); rmSync(stamp, { force: true }); }
+    unstage();
+    // The instance's own logs go with the state directory below, and they are where a World that did not come up
+    // says why (the co-located host's output, a managed service's log, the lifecycle log). They are kept first,
+    // whole, where a failed preparation keeps its evidence, and the error names the file.
+    const logs = worldLogs(state);
+    if (logs && error instanceof Error) error.message += keepFailureEvidence('database-prepare-world-logs', logs, env);
+    throw error;
+  } finally {
+    rmSync(state, { recursive: true, force: true });
+    for (const name of Object.keys(process.env)) if (!(name in before)) delete process.env[name];
+    Object.assign(process.env, before);
+  }
+}
+
 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) };
@@ -301,6 +561,8 @@ export async function nativePrepare(service: InfraService, definition: string, w
   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 withWorld = databasePrepareOf(worldConfig);
+  if (withWorld?.with === 'world') return prepareWithWorld(withWorld, definition, worldConfig, tools, env, launch);
   const { directory, stamp } = nativePreparedCluster(worldConfig);
   const root = dirname(directory);
   mkdirSync(root, { recursive: true });
@@ -331,13 +593,7 @@ export async function nativePrepare(service: InfraService, definition: string, w
   }
   // 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);
+  await nativePostgresDown(root, 'prepare (the cluster is made; its clean stop)');
   if (stepFailure) {
     rmSync(directory, { recursive: true, force: true });
     throw failed(stepFailure.error);
@@ -351,9 +607,21 @@ export async function nativePrepare(service: InfraService, definition: string, w
   return directory;
 }
 
+/**
+ * How often the start looks for the postmaster's readiness (postmaster.pid's status line, then its port). Each look
+ * is two file reads; at 100 ms a start waited up to 100 ms past a ready server (Cal in a tab: ready at check 8, 1,211
+ * ms). The postmaster says it no other way a parent can wait on: its log is a file this start does not hold open.
+ */
+const READY_CHECK_MS = 20;
+
 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;
+  // EACH STEP OF THIS START SAYS ITS OWN TIME AND WHAT IT WAITED ON, as a note the World's up prints on its own
+  // clock. In a tab the whole start took ten seconds of a World's twelve (Twenty: backing chosen at +1.29 s, ready at
+  // +11.72 s) and one line, the cluster's placing, said where any of it went.
+  let stepBegan = performance.now();
+  const step = (what: string): void => { const now = performance.now(); launch.note?.(`native PostgreSQL: ${what}, ${Math.round(now - stepBegan)} ms`); stepBegan = now; };
   const env: NodeJS.ProcessEnv = { ...(launch.env ?? process.env), LC_ALL: launch.env?.LC_ALL || 'C' };
   const binaries = nativePostgresTools(env);
   if (!binaries) throw new Error('native postgres requires an installed PostgreSQL: a postgres server on PATH, or VOLTER_WORLD_POSTGRES_BIN naming its tool directory');
@@ -373,12 +641,19 @@ export async function nativePostgresUp(services: InfraService[], root: string, d
   await retireTools(root);
   const service = services[0]!;
   if (await listening(service.hostPort, deadline, launch.signal)) throw new Error(`native postgres port ${service.hostPort} is already occupied`);
+  step(`an earlier start's programs retired and port ${service.hostPort} found free (one connection refused)`);
   const data = resolve(root, 'native-postgres-data');
   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;
+  // Placed this start under a stamp that names its database: the cluster holds it (S2 R15).
+  let placedDatabase = false;
+  // Copied as the server's own, every file already its: the walk below would find nothing to change.
+  let ownedAsCopied = false;
+  // Moved in whole this start, as the image laid it (S2 B2): owned by the owner the image names, not to be walked.
+  let movedAsLaid = false;
   // 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).
@@ -387,13 +662,33 @@ export async function nativePostgresUp(services: InfraService[], root: string, d
     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);
+        'other PostgreSQL programs, initdb arguments, identity or migration', wanted.migration, copyClusterOwned(postgresRunAs()));
+      ownedAsCopied = placed.copied === true;
+      movedAsLaid = placed.placed && placed.copied !== true;
       if (placed.note) launch.note?.(placed.note);
+      placedDatabase = placed.placed;
     }
   }
+  // The placement's own parts, each a step (S2 R71: Cal's 195-206 ms was one line): the stamp's check and the move,
+  // then the server's directories and ownership with what the walk looked at and changed.
+  step(placedDatabase ? 'the prepared cluster\'s stamp read and matched, and the cluster moved into place' : 'the prepared cluster looked for (none placed)');
   mkdirSync(data, { recursive: true, mode: 0o700 });
+  const runAs = postgresRunAs();
+  postgresDirectorySearch(root, env, runAs);
+  // A cluster this start moved in whole from the prepared tree is owned as the image laid it. Where the page says the
+  // image laid every entry of that cluster with one owner, and that owner is the server's (VOLTER_WORLD_PREPARED_CLUSTER_
+  // OWNER, given only where its open placed the World's tree with the prepared project), the walk could change nothing
+  // and is not run (S2 B2: 134-206 ms of lstats on Cal and Twenty). Any other cluster, or no such word, is walked.
+  const laid = /^(\d+):(\d+)$/u.exec(env.VOLTER_WORLD_PREPARED_CLUSTER_OWNER ?? '');
+  const ownedAsLaid = movedAsLaid && laid !== null && Number(laid[1]) === runAs.uid && Number(laid[2]) === runAs.gid;
+  const owned = ownedAsCopied || ownedAsLaid ? undefined : ownPostgresCluster(data, runAs);
+  launch.note?.(`native PostgreSQL: child uid ${runAs.uid}, gid ${runAs.gid}; cluster ${data}`);
+  step(ownedAsCopied ? 'the prepared cluster looked for and copied as the server\'s own'
+    : ownedAsLaid ? `the prepared cluster looked for and placed where one matches, laid as the server's own (${runAs.uid}:${runAs.gid}): not walked`
+    : `the prepared cluster looked for and placed where one matches, its files made the server's (${owned!.walked} entries walked, ${owned!.changed} changed)`);
   if (!existsSync(join(data, 'PG_VERSION'))) {
-    await tool(join(binaries, 'initdb'), ['-D', data, ...initdbArguments(user)], env, deadline, root, launch.signal);
+    await tool(join(binaries, 'initdb'), ['-D', data, ...initdbArguments(user)], env, deadline, root, runAs, launch.signal);
+    step('initdb run to its end (no prepared cluster was placed)');
   }
   launch.signal?.throwIfAborted();
   const binary = join(binaries, 'postgres');
@@ -407,7 +702,7 @@ export async function nativePostgresUp(services: InfraService[], root: string, d
     const fd = openSync(log, 'a');
     let child: ChildProcess;
     try {
-      child = spawn(binary, ['-D', data, '-h', '127.0.0.1', '-p', String(service.hostPort), '-k', ''], { env, detached: true, windowsHide: true, stdio: ['ignore', fd, fd] });
+      child = spawn(binary, ['-D', data, '-h', '127.0.0.1', '-p', String(service.hostPort), '-k', '', ...recoverySync()], { env, ...runAs, detached: true, windowsHide: true, stdio: ['ignore', fd, fd] });
       current.pid = child.pid ?? 0;
       started = { child, owned: current, closed: false };
       const observed = started;
@@ -424,22 +719,36 @@ export async function nativePostgresUp(services: InfraService[], root: string, d
     if (started.error) throw started.error;
     if (!child.pid) throw new Error('native postgres spawn failed');
     publishProcessReceipt(recordPath(root), JSON.stringify(current) + '\n');
+    step('the postmaster spawned, its identity captured and its receipts written');
+    // The cluster is chosen and placed (takePreparedCluster's move or copy, its migration record written; or initdb's)
+    // and its server spawned: what a twin's staged store is placed beside is there now (S2 R79), before readiness.
+    launch.onPlaced?.();
+    let checks = 0;
     for (;;) {
+      checks += 1;
       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}${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');
+      if (existsSync(join(data, 'postmaster.pid')) && verifyOwner(current)) {
+        // Read again for its status line; gone or shorter between the two reads is not ready yet.
+        let lines: string[] = [];
+        try { lines = readFileSync(join(data, 'postmaster.pid'), 'utf8').split('\n'); } catch { /* removed since the check above */ }
         if (lines[7]?.trim() === 'ready' && await listening(service.hostPort, deadline, launch.signal)) break;
       }
-      await wait(100);
+      await wait(READY_CHECK_MS);
     }
-    if (database !== 'postgres') {
+    step(`the postmaster ready: postmaster.pid says so and its port answers, at check ${checks} (a check every ${READY_CHECK_MS} ms)`);
+    // A cluster placed this start was matched on a stamp that names this database (nativeStampMatches), and made with
+    // it by these same programs at image build: asking the server again was a psql process of its own (Cal in a tab:
+    // 327 ms of a 2.3 s World up). A cluster from an earlier start, or initdb's, is still asked, and given the database
+    // where it lacks it.
+    if (placedDatabase && database !== 'postgres') step(`database ${database} is the placed cluster's, by its stamp: not asked`);
+    else if (database !== 'postgres') {
       const sql = `SELECT 1 FROM pg_database WHERE datname = '${database.replaceAll("'", "''")}'`;
-      const output = await tool(join(binaries, 'psql'), ['-h', '127.0.0.1', '-p', String(service.hostPort), '-U', user, '-d', 'postgres', '-tAc', sql], env, deadline, root, launch.signal);
-      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);
+      const output = await tool(join(binaries, 'psql'), ['-h', '127.0.0.1', '-p', String(service.hostPort), '-U', user, '-d', 'postgres', '-tAc', sql], env, deadline, root, runAs, launch.signal);
+      step(`psql run to its end, asking whether database ${database} is there`);
+      if (!output.trim()) { await tool(join(binaries, 'createdb'), ['-h', '127.0.0.1', '-p', String(service.hostPort), '-U', user, '--', database], env, deadline, root, runAs, launch.signal); step(`createdb run to its end`); }
     }
     launch.signal?.throwIfAborted();
     if (child.exitCode !== null || child.signalCode !== null) throw new Error(`native postgres exited during readiness; see ${log}${logTail(log)}`);
@@ -449,7 +758,7 @@ export async function nativePostgresUp(services: InfraService[], root: string, d
     // The original publication/readiness failure survives every cleanup failure.
     const failures: unknown[] = [error];
     try {
-      if (started) await retireStarted(started);
+      if (started) await retireStarted(started, 'up (startup failed)');
       removeReceipts(root);
       starts.delete(root);
     } catch (cleanup) { failures.push(cleanup); }
@@ -457,13 +766,15 @@ export async function nativePostgresUp(services: InfraService[], root: string, d
     throw error;
   }
 }
-export async function nativePostgresStatus(root: string): Promise<boolean> {
+/** The native postmaster's status proof: its ownership known, its held group live, its spawn identity and owner
+ *  verified, and its port answering. `signal` ends the port's wait with the boot that asks (an up's hand-over). */
+export async function nativePostgresStatus(root: string, signal?: AbortSignal): Promise<boolean> {
   const state = ownership(root);
   if (state.errors.length) throw new AggregateError(state.errors, 'native postgres ownership uncertain; retry down');
   if (!state.held || !liveGroup(state.held.pid)) return false;
   if (state.identity) await verifySpawnIdentity(state.identity);
-  verifyOwner(state.held);
-  return listening(state.held.port, Date.now() + READY_TIMEOUT_MS);
+  if (!verifyOwner(state.held)) return false;
+  return listening(state.held.port, Date.now() + READY_TIMEOUT_MS, signal);
 }
 
 async function retireTools(root: string): Promise<void> {
@@ -488,16 +799,17 @@ async function retireTools(root: string): Promise<void> {
     rmSync(receipt, { force: true }); rmSync(spawnReceiptPath(receipt), { force: true });
   }
 }
-export async function nativePostgresDown(root: string): Promise<void> {
+export async function nativePostgresDown(root: string, by = 'down'): Promise<void> {
   const started = starts.get(root);
   const state = ownership(root);
+  const data = resolve(root, 'native-postgres-data');
   if (state.errors.length) process.stderr.write(`${errorMessage(new AggregateError(state.errors, 'native postgres ownership uncertain; retrying retirement through established identity'))}\n`);
   if (started) {
-    await retireStarted(started);
+    await retireStarted(started, by);
   } else if (state.identity) {
     if (liveGroup(state.identity.pid)) {
       await verifySpawnIdentity(state.identity);
-      await retireIdentity(state.identity);
+      await retirePostmaster(state.identity, by, data);
     }
   } else if (state.held && state.held.pid > 0) {
     if (liveGroup(state.held.pid)) {