@volter/world-runtime 3.0.163 → 3.0.165

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

@@ -0,0 +1,512 @@
+// The actual WALI MariaDB server owns SQL and files. This lifecycle owns only
+// its issued policy, child/group, receipts, readiness and stopped data.
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { chmodSync, chownSync, closeSync, constants, existsSync, fchmodSync, fchownSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { commandLifetime, COMMAND_GRACE_MS } from "./command-lifetime.js";
+import { survivingOwnedGroups, worldEvent } from "./process-groups.js";
+import { publishProcessReceipt, spawnReceiptPath, verifySpawnIdentity, signalOwnedProcess } from "./process-receipt.js";
+import { childIdentity, signalChild } from './process-signal.mjs';
+import { mariaDBBootstrap, mariaDBClientOptions, mariaDBReadinessCommand } from "./mariadb-bootstrap.js";
+import { nativeMariaDBShellEnvironment, nativeMariaDBSupplier } from "./mariadb-supplier.js";
+const starts = new Map();
+const ownerFile = (root) => join(root, 'native-mariadb.owner.json');
+const startingFile = (root) => join(root, 'native-mariadb.starting.json');
+const dataDirectory = (root) => resolve(root, 'native-mariadb-data');
+const wait = (ms) => new Promise(done => setTimeout(done, ms));
+const alive = (pid) => pid > 0 && survivingOwnedGroups([pid]).length !== 0;
+// Keep the existing managed-store readiness/retirement budget and native PID
+// inspection cadence (native-postgres-backing.ts READY_TIMEOUT_MS/READY_CHECK_MS,
+// measured in cookbook/calcom/output/native-lifetime.txt). No MariaDB duration
+// or readiness result is inferred from that PostgreSQL measurement.
+const STORE_BUDGET_MS = 60_000;
+const CHECK_MS = 20;
+function receiptFiles(files) {
+    return files.flatMap(file => {
+        let fd;
+        try {
+            fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        try {
+            const stat = fstatSync(fd);
+            if (!stat.isFile() || stat.nlink !== 1 || stat.uid !== process.getuid?.())
+                throw new Error('native MariaDB lifecycle receipt is not its owned regular file');
+            const data = readFileSync(fd), current = lstatSync(file);
+            if (!current.isFile() || current.dev !== stat.dev || current.ino !== stat.ino || current.ctimeMs !== stat.ctimeMs)
+                throw new Error('native MariaDB lifecycle receipt changed while reading');
+            return [{ file, dev: stat.dev, ino: stat.ino, ctimeMs: stat.ctimeMs,
+                    sha256: createHash('sha256').update(data).digest('hex'), text: data.toString('utf8') }];
+        }
+        finally {
+            closeSync(fd);
+        }
+    });
+}
+function removeReceipts(expected) {
+    const failures = [];
+    for (const held of expected) {
+        try {
+            const current = receiptFiles([held.file])[0];
+            if (!current || current.dev !== held.dev || current.ino !== held.ino || current.ctimeMs !== held.ctimeMs || current.sha256 !== held.sha256)
+                throw new Error('native MariaDB lifecycle receipt changed during retirement: ' + held.file);
+            rmSync(held.file);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    if (failures.length)
+        throw new AggregateError(failures, 'native MariaDB retired with uncertain or unremovable receipts');
+}
+function runAs() {
+    const uid = process.getuid?.(), gid = process.getgid?.();
+    if (uid === undefined || gid === undefined)
+        throw new Error('native MariaDB needs a numeric OS identity');
+    if (uid !== 0)
+        return { uid, gid };
+    const accounts = readFileSync('/etc/passwd', 'utf8').split('\n').map(line => line.split(':'));
+    for (const name of ['mysql', 'nobody']) {
+        const row = accounts.find(fields => fields[0] === name && /^\d+$/u.test(fields[2] ?? '') && /^\d+$/u.test(fields[3] ?? '')
+            && Number(fields[2]) > 0 && Number(fields[2]) < 0xffffffff && Number(fields[3]) > 0 && Number(fields[3]) < 0xffffffff);
+        if (row)
+            return { uid: Number(row[2]), gid: Number(row[3]) };
+    }
+    throw new Error('native MariaDB started by root needs an installed non-root mysql or nobody account');
+}
+function privateFile(file, body, identity) {
+    publishProcessReceipt(file, body);
+    chownSync(file, identity.uid, identity.gid);
+    chmodSync(file, 0o600);
+}
+function privateLog(file, identity) {
+    const fd = openSync(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.nlink !== 1 || ![process.getuid?.(), identity.uid].includes(stat.uid))
+            throw new Error('native MariaDB private log has uncertain ownership or file kind');
+        fchmodSync(fd, 0o600);
+        fchownSync(fd, identity.uid, identity.gid);
+        return fd;
+    }
+    catch (error) {
+        closeSync(fd);
+        throw error;
+    }
+}
+function privateText(file, identity) {
+    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.nlink !== 1 || stat.uid !== identity.uid || (stat.mode & 0o777) !== 0o600)
+            throw new Error('native MariaDB private policy/options file has uncertain ownership or permissions');
+        return readFileSync(fd, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function ownData(directory, identity) {
+    const stat = lstatSync(directory);
+    if (stat.isSymbolicLink())
+        throw new Error('native MariaDB stopped data contains an unsupported storage link');
+    if (!stat.isDirectory() && !stat.isFile())
+        throw new Error('native MariaDB data contains an unsupported special file');
+    if (stat.uid !== identity.uid || stat.gid !== identity.gid)
+        chownSync(directory, identity.uid, identity.gid);
+    if (stat.isDirectory())
+        for (const name of readdirSync(directory))
+            ownData(join(directory, name), identity);
+}
+function searchRoot(root, env, identity) {
+    const directories = [root];
+    if (env.VOLTER_WORLD_DATA && resolve(env.VOLTER_WORLD_DATA) === resolve(root) && env.VOLTER_WORLD_INSTANCE
+        && 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 MariaDB bookkeeping root is not a regular directory');
+        if ((stat.uid === identity.uid && (stat.mode & 0o100)) || (stat.gid === identity.gid && (stat.mode & 0o010)) || (stat.mode & 0o001))
+            continue;
+        chownSync(directory, stat.uid, identity.gid);
+        chmodSync(directory, (stat.mode & 0o7777) | 0o010);
+    }
+}
+function state(root) {
+    const files = [];
+    const read = (file, parse) => {
+        try {
+            const retained = receiptFiles([file])[0];
+            if (!retained)
+                return { present: false };
+            files.push(retained);
+            return { present: true, value: parse(retained.text) };
+        }
+        catch (cause) {
+            return { present: true, error: new Error('native MariaDB ownership reading is uncertain', { cause }) };
+        }
+    };
+    const rows = [ownerFile(root), startingFile(root)].map(file => read(file, text => {
+        const row = JSON.parse(text);
+        if (!Number.isSafeInteger(row.pid) || row.pid < 0 || row.data !== dataDirectory(root)
+            || !Number.isInteger(row.port) || row.port < 1 || row.port > 65535
+            || !/^[a-f0-9]{64}$/u.test(row.receiptSha256) || !/^\d+\.\d+\.\d+$/u.test(row.release))
+            throw new Error('native MariaDB ownership receipt is invalid');
+        if (row.pidFile !== undefined && (!row.pidFile || typeof row.pidFile !== 'object'
+            || !Number.isSafeInteger(row.pidFile.dev) || row.pidFile.dev < 0
+            || !Number.isSafeInteger(row.pidFile.ino) || row.pidFile.ino < 0
+            || !Number.isFinite(row.pidFile.ctimeMs) || row.pidFile.ctimeMs < 0
+            || Object.keys(row.pidFile).some(key => !['dev', 'ino', 'ctimeMs'].includes(key))))
+            throw new Error('native MariaDB server PID-file receipt is invalid');
+        return row;
+    }));
+    const birth = read(spawnReceiptPath(ownerFile(root)), text => {
+        const row = JSON.parse(text);
+        if (!Number.isSafeInteger(row.pid) || row.pid <= 0 || typeof row.start !== 'string' || !row.start.trim())
+            throw new Error('native MariaDB birth token is invalid');
+        return row;
+    });
+    const values = rows.flatMap(row => row.value ? [row.value] : []);
+    const errors = [...rows, birth].flatMap(row => row.error ? [row.error] : []);
+    if (values.length > 1 && values.some(row => JSON.stringify(row) !== JSON.stringify(values[0])))
+        errors.push(new Error('native MariaDB ownership receipts conflict'));
+    if (birth.value && values.some(row => row.pid > 0 && row.pid !== birth.value.pid))
+        errors.push(new Error('native MariaDB process birth and ownership receipts conflict'));
+    return { present: rows.some(row => row.present) || birth.present, owner: values[0], identity: birth.value, values, errors, files };
+}
+function pidFile(owner) {
+    const file = join(owner.data, 'server.pid');
+    let fd;
+    try {
+        fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    let text, stat;
+    try {
+        stat = fstatSync(fd);
+        if (!stat.isFile())
+            throw new Error('native MariaDB PID file is not a regular file');
+        text = readFileSync(fd, 'utf8').trim();
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (!text)
+        return false; // the server creates, then writes, its PID file
+    if (!/^\d+$/u.test(text) || Number(text) !== owner.pid)
+        throw new Error('native MariaDB PID file differs from its recorded child');
+    if (owner.pidFile && (stat.dev !== owner.pidFile.dev || stat.ino !== owner.pidFile.ino || stat.ctimeMs !== owner.pidFile.ctimeMs))
+        throw new Error('native MariaDB PID file identity changed');
+    const current = lstatSync(file);
+    if (!current.isFile() || current.dev !== stat.dev || current.ino !== stat.ino || current.ctimeMs !== stat.ctimeMs)
+        throw new Error('native MariaDB PID file changed while reading');
+    return true;
+}
+async function stop(pid, deliver) {
+    if (!alive(pid))
+        return;
+    // Vendor sql/mysqld.cc:3418-3430 handles SIGTERM with break_connect_loop;
+    // give the server its shutdown before touching its group.
+    const asked = Date.now();
+    worldEvent({ event: 'world.service.stop', service: 'mysql', by: 'native MariaDB down', pid, signal: 'SIGTERM', to: 'pid' });
+    await deliver('SIGTERM', false);
+    while (alive(pid) && Date.now() < asked + STORE_BUDGET_MS)
+        await wait(CHECK_MS);
+    if (alive(pid)) {
+        worldEvent({ event: 'world.service.killed', service: 'mysql', by: 'native MariaDB down', pid, signal: 'SIGKILL', to: 'group', afterMs: Date.now() - asked });
+        await deliver('SIGKILL', true);
+        const deadline = Date.now() + COMMAND_GRACE_MS;
+        while (alive(pid) && Date.now() < deadline)
+            await wait(CHECK_MS);
+    }
+    if (alive(pid))
+        throw new Error('native MariaDB retirement is unconfirmed; receipts retained');
+}
+/** Tool output is private: bootstrap errors can contain an issued password.
+ * Only SELECT's one answer is returned; errors name the retained private log. */
+async function tool(command, args, root, env, identity, deadline, signal) {
+    signal?.throwIfAborted();
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new Error('native MariaDB lifecycle deadline elapsed');
+    const log = join(root, 'native-mariadb-tools.log'), fd = privateLog(log, identity);
+    let child;
+    try {
+        child = spawn(command, args, { env, ...identity, detached: true, windowsHide: true, stdio: ['ignore', 'pipe', fd] });
+    }
+    finally {
+        closeSync(fd);
+    }
+    const lifetime = commandLifetime(child, signal);
+    let stdout = '', spawnError, expired = false;
+    child.stdout?.on('data', chunk => { stdout += chunk.toString(); });
+    child.on('error', error => { spawnError = error; });
+    const receipt = join(root, `native-mariadb-tool-${child.pid ?? 'unspawned'}.json`);
+    const timer = setTimeout(() => { expired = true; lifetime.cancel('SIGTERM'); }, remaining);
+    let failed, published = [];
+    try {
+        try {
+            if (child.pid) {
+                publishProcessReceipt(receipt, JSON.stringify({ pid: child.pid, command: basename(command) }) + '\n');
+                published = receiptFiles([receipt]);
+            }
+            const birth = await lifetime.identity;
+            if (birth?.start) {
+                publishProcessReceipt(spawnReceiptPath(receipt), JSON.stringify(birth) + '\n');
+                published = receiptFiles([receipt, spawnReceiptPath(receipt)]);
+            }
+            else if (child.pid && alive(child.pid))
+                throw new Error('native MariaDB helper birth capture failed');
+        }
+        catch (error) {
+            lifetime.cancel('SIGTERM');
+            try {
+                await lifetime.finish();
+            }
+            catch (cleanup) {
+                throw new AggregateError([error, cleanup], 'native MariaDB helper publication/retirement failed');
+            }
+            throw error;
+        }
+        const result = await lifetime.finish();
+        signal?.throwIfAborted();
+        if (expired || lifetime.forwarded)
+            throw new Error('native MariaDB helper cancelled; private log ' + log);
+        if (spawnError)
+            throw spawnError;
+        return { code: result.code, stdout };
+    }
+    catch (error) {
+        failed = error;
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        if (!child.pid || !alive(child.pid)) {
+            try {
+                removeReceipts(published);
+            }
+            catch (cleanup) {
+                if (failed !== undefined)
+                    throw new AggregateError([failed, cleanup], 'native MariaDB helper and receipt cleanup failed');
+                throw cleanup;
+            }
+        }
+    }
+}
+function policy(service) {
+    // Secrets remain only in this 0600 data-owned file. No password digest,
+    // length or material is written into process receipts or status output.
+    return JSON.stringify({ version: 1, implementation: 'mariadb', image: service.image,
+        release: service.reference.release, sourceSha256: service.reference.sourceSha256,
+        receiptSha256: service.reference.receiptSha256, recipe: service.reference.recipe,
+        credentials: service.credentials }) + '\n';
+}
+function safeBootstrapPaths(paths) {
+    // Upstream mysql_install_db.sh:193-207,302,353-357 expands unquoted path
+    // lists. Refuse paths its source cannot carry, rather than rewriting it.
+    if (paths.some(path => /[\s\\`$*?\[\]"']/u.test(path)))
+        throw new Error('native MariaDB install-db path-quoting gap');
+}
+async function readiness(service, root, config, env, identity, deadline, signal, startingPrograms) {
+    const held = state(root);
+    if (held.errors.length || !held.owner || !held.owner.pidFile || !held.identity || existsSync(startingFile(root))
+        || held.identity.pid !== held.owner.pid || !alive(held.owner.pid)
+        || held.owner.receiptSha256 !== service.reference.receiptSha256 || held.owner.release !== service.reference.release
+        || held.owner.port !== service.hostPort)
+        return false;
+    await verifySpawnIdentity(held.identity);
+    if (!pidFile(held.owner) || privateText(join(held.owner.data, '.world-policy.json'), identity) !== policy(service))
+        return false;
+    // Up authenticated its installed prefix before launching the server. Reuse
+    // that same selection within its readiness loop; each exec still enters the
+    // kernel admission gate. An independent status call authenticates it afresh.
+    const programs = startingPrograms ?? nativeMariaDBSupplier(dirname(config), service.image, service.reference);
+    const options = join(root, 'native-mariadb-client.cnf');
+    if (privateText(options, identity) !== mariaDBClientOptions(service.credentials, '127.0.0.1', service.hostPort))
+        return false;
+    const command = mariaDBReadinessCommand(programs, options);
+    const answer = await tool(command.command, command.args, root, env, identity, deadline, signal);
+    const fields = answer.stdout.trim().split('\t');
+    await verifySpawnIdentity(held.identity);
+    return answer.code === 0 && fields.length === 4
+        && fields[0].startsWith(service.reference.release + '-MariaDB')
+        && fields[1] === String(service.hostPort) && resolve(fields[2]) === held.owner.data
+        && fields[3] === Buffer.from(service.credentials.user + '@%', 'utf8').toString('hex').toUpperCase()
+        && alive(held.owner.pid) && pidFile(held.owner);
+}
+export async function nativeMariaDBUp(service, root, config, launch) {
+    if (process[Symbol.for('tabnode.run.vfs')] === undefined)
+        throw new Error('native MariaDB WALI supply requires the attached kernel and its program admission; no host server substitution');
+    const env = { ...(launch.env ?? process.env), LC_ALL: 'C' }, identity = runAs();
+    const programs = nativeMariaDBSupplier(dirname(config), service.image, service.reference);
+    const deadline = Date.now() + STORE_BUDGET_MS, data = dataDirectory(root);
+    const previous = state(root);
+    if (previous.present || starts.has(root))
+        await nativeMariaDBDown(root);
+    await retireTools(root);
+    searchRoot(root, env, identity);
+    const stamp = join(data, '.world-policy.json'), extra = join(root, 'native-mariadb-bootstrap.sql');
+    safeBootstrapPaths([programs.basedir, data, extra]);
+    if (!existsSync(data))
+        mkdirSync(data, { mode: 0o700 });
+    if (!lstatSync(data).isDirectory())
+        throw new Error('native MariaDB data root must be a regular directory');
+    if (existsSync(join(data, 'server.pid')) || existsSync(join(data, 'server.sock')))
+        throw new Error('native MariaDB retains a PID/socket without confirmed clean teardown; data retained');
+    if (existsSync(stamp)) {
+        if (!lstatSync(stamp).isFile() || readFileSync(stamp, 'utf8') !== policy(service))
+            throw new Error('native MariaDB provider or issued policy changed; explicit configuration/upgrade required');
+    }
+    else {
+        if (readdirSync(data).length)
+            throw new Error('native MariaDB has unstamped or partial data; initialization refused');
+    }
+    ownData(data, identity);
+    if (!existsSync(stamp)) {
+        const bootstrapEnv = nativeMariaDBShellEnvironment(env);
+        const bootstrap = mariaDBBootstrap(programs, service.credentials, data, extra);
+        privateFile(join(data, '.world-initializing.json'), policy(service), identity);
+        privateFile(extra, bootstrap.privateSql, identity);
+        const initialized = await tool(bootstrap.command, bootstrap.args, root, bootstrapEnv, identity, deadline, launch.signal);
+        if (initialized.code !== 0 || !existsSync(join(data, 'mysql')))
+            throw new Error('native MariaDB genuine install-db failed; private log/data retained');
+        privateFile(stamp, policy(service), identity);
+        rmSync(join(data, '.world-initializing.json'));
+        rmSync(extra);
+    }
+    privateFile(join(root, 'native-mariadb-client.cnf'), mariaDBClientOptions(service.credentials, '127.0.0.1', service.hostPort), identity);
+    const owner = { pid: 0, data, port: service.hostPort,
+        receiptSha256: service.reference.receiptSha256, release: service.reference.release };
+    publishProcessReceipt(startingFile(root), JSON.stringify(owner) + '\n');
+    let started;
+    try {
+        launch.signal?.throwIfAborted();
+        const fd = privateLog(join(root, 'native-mariadb.log'), identity);
+        let child;
+        try {
+            child = spawn(programs.server, ['--no-defaults', '--basedir=' + programs.basedir, '--datadir=' + data,
+                '--bind-address=127.0.0.1', '--port=' + service.hostPort, '--pid-file=' + join(data, 'server.pid'),
+                '--socket=' + join(data, 'server.sock')], { env, ...identity, detached: true, windowsHide: true, stdio: ['ignore', fd, fd] });
+        }
+        finally {
+            closeSync(fd);
+        }
+        owner.pid = child.pid ?? 0;
+        started = { child, owner, closed: false };
+        const observed = started;
+        child.on('error', error => { observed.error = error; });
+        child.once('close', () => { observed.closed = true; });
+        starts.set(root, started);
+        // A failed birth capture still retains the actual attempted PID. It is
+        // never sufficient for a later numeric signal without its birth token.
+        publishProcessReceipt(startingFile(root), JSON.stringify(owner) + '\n');
+        const birth = await childIdentity(child);
+        if (!child.pid || !birth?.start)
+            throw new Error('native MariaDB server birth capture failed');
+        started.identity = birth;
+        publishProcessReceipt(spawnReceiptPath(ownerFile(root)), JSON.stringify(birth) + '\n');
+        publishProcessReceipt(startingFile(root), JSON.stringify(owner) + '\n');
+        publishProcessReceipt(ownerFile(root), JSON.stringify(owner) + '\n');
+        // Status refuses a starting record. Remove it only after the server's own
+        // PID file agrees, then run the same authenticated proof status uses.
+        while (!pidFile(owner)) {
+            launch.signal?.throwIfAborted();
+            if (observed.error || observed.closed || child.exitCode !== null || Date.now() >= deadline)
+                throw new Error('native MariaDB ended before its PID file; private log retained');
+            await wait(CHECK_MS);
+        }
+        const stat = lstatSync(join(data, 'server.pid'));
+        owner.pidFile = { dev: stat.dev, ino: stat.ino, ctimeMs: stat.ctimeMs };
+        publishProcessReceipt(ownerFile(root), JSON.stringify(owner) + '\n');
+        rmSync(startingFile(root));
+        while (!await readiness(service, root, config, env, identity, deadline, launch.signal, programs)) {
+            launch.signal?.throwIfAborted();
+            if (observed.error || observed.closed || child.exitCode !== null || Date.now() >= deadline)
+                throw new Error('native MariaDB failed authenticated readiness; private log retained');
+            await wait(CHECK_MS);
+        }
+        child.unref();
+        launch.note?.('native MariaDB ready: owned PID/start, server PID file and authenticated version/port/datadir');
+    }
+    catch (error) {
+        try {
+            await nativeMariaDBDown(root);
+        }
+        catch (cleanup) {
+            throw new AggregateError([error, cleanup], 'native MariaDB startup and retirement failed; receipts retained');
+        }
+        throw error;
+    }
+}
+export async function nativeMariaDBStatus(service, root, config, launch) {
+    try {
+        return await readiness(service, root, config, launch.env ?? process.env, runAs(), Date.now() + STORE_BUDGET_MS, launch.signal);
+    }
+    catch {
+        return false;
+    } // corrupt/unreadable receipts and replaced supply are not-ready
+}
+async function retireTools(root) {
+    if (!existsSync(root))
+        return;
+    const files = new Set(readdirSync(root).filter(name => /^native-mariadb-tool-.*\.json(?:\.spawn\.json)?$/u.test(name))
+        .map(name => name.replace(/\.spawn\.json$/u, '')));
+    for (const name of files) {
+        const file = join(root, name);
+        const recorded = receiptFiles([file, spawnReceiptPath(file)]);
+        const body = recorded.find(row => row.file === spawnReceiptPath(file));
+        if (!body)
+            throw new Error('native MariaDB helper ownership uncertain; receipts retained');
+        const birth = JSON.parse(body.text);
+        await verifySpawnIdentity(birth);
+        if (alive(birth.pid)) {
+            await signalOwnedProcess(birth, 'SIGTERM', true, 'native MariaDB helper down');
+            const deadline = Date.now() + COMMAND_GRACE_MS;
+            while (alive(birth.pid) && Date.now() < deadline)
+                await wait(CHECK_MS);
+            if (alive(birth.pid))
+                await signalOwnedProcess(birth, 'SIGKILL', true, 'native MariaDB helper down');
+            const confirm = Date.now() + COMMAND_GRACE_MS;
+            while (alive(birth.pid) && Date.now() < confirm)
+                await wait(CHECK_MS);
+            if (alive(birth.pid))
+                throw new Error('native MariaDB helper retirement unconfirmed; receipts retained');
+        }
+        removeReceipts(recorded);
+    }
+}
+/** The held identity is enough to retire even if the supplier/config is gone. */
+export async function nativeMariaDBDown(root) {
+    const held = starts.get(root), previous = state(root);
+    if (held) {
+        held.child.ref();
+        await stop(held.owner.pid, async (signal, group) => signalChild(held.child, signal, group, 'native MariaDB down')
+            || (held.identity ? signalOwnedProcess(held.identity, signal, group, 'native MariaDB down') : false));
+    }
+    else if (previous.identity) {
+        await verifySpawnIdentity(previous.identity);
+        await stop(previous.identity.pid, (signal, group) => signalOwnedProcess(previous.identity, signal, group, 'native MariaDB down'));
+    }
+    else if (previous.present)
+        throw new Error('native MariaDB ownership uncertain; down retains receipts');
+    if (previous.values.some(row => row.pid > 0 && alive(row.pid)))
+        throw new Error('native MariaDB conflicting live ownership retained');
+    await retireTools(root);
+    if (previous.errors.length)
+        throw new AggregateError(previous.errors, 'native MariaDB retired with uncertain ownership; receipts retained');
+    if (existsSync(join(dataDirectory(root), 'server.pid')) || existsSync(join(dataDirectory(root), 'server.sock')))
+        throw new Error('native MariaDB retired with PID/socket left; stopped data/receipts retained');
+    removeReceipts(previous.files);
+    starts.delete(root);
+}

package/dist/src/native-postgres-backing.d.ts

@@ -9,15 +9,9 @@ export declare function nativePreparedCluster(worldConfig: string): {
     directory: string;
     stamp: string;
 };
-/**
- * `volter-world-infra prepare` for a World whose PostgreSQL is native (architecture, managed infrastructure; ADR
- * 0018's phase): this lifecycle's own steps once, into `<World dir>/.volter-prepared/native-postgres-data`. initdb with
- * up's arguments, the postmaster on the World's declared loopback port, the declared database, and a clean SIGINT stop (its
- * shutdown checkpoint; no postmaster.pid left), then the stamp. Where the World declares runtime.database.prepare, the
- * step runs against that postmaster before its stop, and a step that fails leaves no cluster. The image build runs it with the programs the tab
- * runs, under the tab's kernel, so the cluster is the one a first boot there would write.
- */
 export declare function nativePrepare(service: InfraService, definition: string, worldConfig: string, launch?: HostLaunch): Promise<string>;
 export declare function nativePostgresUp(services: InfraService[], root: string, definition: string, launch: HostLaunch): Promise<void>;
-export declare function nativePostgresStatus(root: string): Promise<boolean>;
-export declare function nativePostgresDown(root: string): Promise<void>;
+/** 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 declare function nativePostgresStatus(root: string, signal?: AbortSignal): Promise<boolean>;
+export declare function nativePostgresDown(root: string, by?: string): Promise<void>;