@volter/world-runtime 3.0.163 → 3.0.165

package/dist/src/native-postgres-backing.js

@@ -2,7 +2,7 @@
 // belong to the infrastructure service; a recipe never operates postgres itself.
 import { spawn } 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.js";
 import { delimiter, dirname, join, resolve } from 'node:path';
@@ -10,8 +10,94 @@ import { commandLifetime, COMMAND_GRACE_MS, CommandRetirementError } from "./com
 import { survivingOwnedGroups } from "./process-groups.js";
 import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnReceiptPath, verifySpawnIdentity, signalOwnedProcess } from "./process-receipt.js";
 import { signalChild, childIdentity } from './process-signal.mjs';
+import { worldEvent } from './process-groups.mjs';
 import { errorMessage } from "./error-message.js";
-import { PREPARED_DIRECTORY, databasePrepareOf, expectedMigration, forgetStaleMigration, keepFailureEvidence, runDatabasePrepare, takePreparedCluster } from "./pglite-backing.js";
+import { PREPARED_DIRECTORY, PREPARE_STATE_DIRECTORY, packageScriptPath, databasePrepareOf, environmentFile, expectedMigration, forgetStaleMigration, keepFailureEvidence, migrationInputDigests, preparedStore, preparedStoreStamp, preparedWorldServices, runDatabasePrepare, takePreparedCluster } from "./pglite-backing.js";
+/** OS identity, distinct from PostgreSQL's configured SQL role. No in-process privilege mutation. */
+function postgresRunAs() {
+    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) {
+    const copy = (from, to) => {
+        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, runAs) {
+    // 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) => {
+        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, env, runAs) {
+    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);
+    }
+}
 const starts = new Map();
 const wait = (ms) => new Promise(done => setTimeout(done, ms));
 const recordPath = (root) => join(root, 'native-postgres.owner.json');
@@ -43,11 +129,73 @@ function ownership(root) {
     }
     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 };
 }
+/**
+ * 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) {
-    const lines = readFileSync(join(held.data, 'postmaster.pid'), 'utf8').split('\n');
+    let text;
+    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.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, deliver, by, data) {
+    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) => pid > 0 && survivingOwnedGroups([pid]).length > 0;
 function removeReceipts(root) {
@@ -73,6 +221,12 @@ function removeReceipts(root) {
     if (errors.length)
         throw new AggregateError(errors, 'native postgres retired but receipt cleanup failed');
 }
+async function retirePostmaster(identity, by, data) {
+    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) {
     const { pid } = identity;
     for (const signal of ['SIGINT', 'SIGKILL']) {
@@ -87,21 +241,18 @@ async function retireIdentity(identity) {
         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) {
+async function retireStarted(started, by = 'down (this process started it)') {
     const { child, owned } = started;
     child.ref();
-    for (const signal of ['SIGINT', 'SIGKILL']) {
+    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`);
 }
@@ -144,12 +295,12 @@ function logTail(log) {
     }
 }
 /** Every helper joins exit and its private group, including spawn errors and abort. */
-async function tool(command, args, env, deadline, root, signal) {
+async function tool(command, args, env, deadline, root, runAs, signal) {
     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 = '';
@@ -265,6 +416,17 @@ export function nativePostgresTools(env) {
     }
     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() {
+    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) {
     return [`--username=${user}`, '--auth=trust', '--no-locale', '--encoding=UTF8'];
@@ -329,6 +491,171 @@ function nativeStampMatches(text, expected) {
  * 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) {
+    const out = [];
+    const walk = (directory) => {
+        let names;
+        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) => /^[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, definition, worldConfig, tools, env, launch) {
+    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 = () => { try {
+        return readdirSync(dirname(directory)).filter(stagedStore);
+    }
+    catch {
+        return [];
+    } };
+    const unstage = () => { 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.js");
+        let ran;
+        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 !== undefined) : [];
+        const world = preparedWorldServices(worldConfig);
+        mkdirSync(dirname(directory), { recursive: true });
+        renameSync(data, directory);
+        moved = true;
+        const migration = { command: [...step.command], inputs: migrationInputDigests(cwd, step.inputs), world };
+        const staged = [];
+        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, definition, worldConfig, launch = {}) {
     if (service.kind !== 'postgres')
         throw new Error('only a declared PostgreSQL is prepared');
@@ -338,6 +665,9 @@ export async function nativePrepare(service, definition, worldConfig, launch = {
     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 });
@@ -380,14 +710,7 @@ export async function nativePrepare(service, definition, worldConfig, launch = {
     }
     // 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);
@@ -400,10 +723,21 @@ export async function nativePrepare(service, definition, worldConfig, launch = {
     writeFileSync(stamp, `${JSON.stringify(nativeStamp(tools, user, database, true, migration))}\n`);
     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, root, definition, launch) {
     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) => { const now = performance.now(); launch.note?.(`native PostgreSQL: ${what}, ${Math.round(now - stepBegan)} ms`); stepBegan = now; };
     const env = { ...(launch.env ?? process.env), LC_ALL: launch.env?.LC_ALL || 'C' };
     const binaries = nativePostgresTools(env);
     if (!binaries)
@@ -428,12 +762,19 @@ export async function nativePostgresUp(services, root, definition, launch) {
     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).
@@ -442,14 +783,34 @@ export async function nativePostgresUp(services, root, definition, launch) {
             launch.note?.(wanted.note);
         else {
             const expected = nativeStamp(binaries, user, database, false, wanted.migration);
-            const placed = takePreparedCluster(prepared, text => nativeStampMatches(text, expected), data, 'other PostgreSQL programs, initdb arguments, identity or migration', wanted.migration);
+            const placed = takePreparedCluster(prepared, text => nativeStampMatches(text, expected), data, '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');
@@ -463,7 +824,7 @@ export async function nativePostgresUp(services, root, definition, launch) {
         const fd = openSync(log, 'a');
         let child;
         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;
@@ -487,7 +848,13 @@ export async function nativePostgresUp(services, root, definition, launch) {
         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;
@@ -495,19 +862,33 @@ export async function nativePostgresUp(services, root, definition, launch) {
                 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 = [];
+                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)
@@ -520,7 +901,7 @@ export async function nativePostgresUp(services, root, definition, launch) {
         const failures = [error];
         try {
             if (started)
-                await retireStarted(started);
+                await retireStarted(started, 'up (startup failed)');
             removeReceipts(root);
             starts.delete(root);
         }
@@ -532,7 +913,9 @@ export async function nativePostgresUp(services, root, definition, launch) {
         throw error;
     }
 }
-export async function nativePostgresStatus(root) {
+/** 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, signal) {
     const state = ownership(root);
     if (state.errors.length)
         throw new AggregateError(state.errors, 'native postgres ownership uncertain; retry down');
@@ -540,8 +923,9 @@ export async function nativePostgresStatus(root) {
         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) {
     if (!existsSync(root))
@@ -570,18 +954,19 @@ async function retireTools(root) {
         rmSync(spawnReceiptPath(receipt), { force: true });
     }
 }
-export async function nativePostgresDown(root) {
+export async function nativePostgresDown(root, by = 'down') {
     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) {