@north-light/api 0.3.580 → 0.3.588

package/dist/daemon/postgres/binary.js

@@ -0,0 +1,193 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, lstatSync, symlinkSync, unlinkSync, writeFileSync, openSync, readSync, closeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { inflateRawSync } from 'node:zlib';
+import { withExclusiveDirectoryLockAsync } from '../../core/exclusive-lock.js';
+import { POSTGRES_JAR_SHA256, POSTGRES_VERSION, jarUrl } from './pins.js';
+const READY_STAMP = '.crtr-postgres-ready';
+/** The jar artifact suffix for this host. Linux picks the musl build on Alpine-style hosts. */
+export function hostJarSuffix() {
+    const arch = process.arch === 'arm64' ? 'arm64v8' : process.arch === 'x64' ? 'amd64' : null;
+    if (arch === null)
+        throw new Error(`no pinned Postgres build for CPU architecture ${process.arch}`);
+    if (process.platform === 'darwin')
+        return `darwin-${arch}`;
+    if (process.platform === 'linux') {
+        const musl = readdirSync('/lib').some((name) => name.startsWith('ld-musl-'));
+        return `linux-${arch}${musl ? '-alpine' : ''}`;
+    }
+    throw new Error(`no pinned Postgres build for platform ${process.platform}`);
+}
+/** `$XDG_CACHE_HOME/crouter/postgres/<version>/`, the same shared cache as the termrender pin. */
+export function postgresCacheDir(version = POSTGRES_VERSION) {
+    return join(resolve(process.env.XDG_CACHE_HOME || join(homedir(), '.cache')), 'crouter', 'postgres', version);
+}
+function describe(root) {
+    return { root, initdb: join(root, 'bin', 'initdb'), postgres: join(root, 'bin', 'postgres'), pgCtl: join(root, 'bin', 'pg_ctl') };
+}
+/** A stored or deflated single-entry-per-name zip reader: the jar holds one `.txz`. */
+function extractZipEntry(zip, wanted) {
+    let eocd = -1;
+    for (let i = zip.length - 22; i >= Math.max(0, zip.length - 65_557); i--) {
+        if (zip.readUInt32LE(i) === 0x06054b50) {
+            eocd = i;
+            break;
+        }
+    }
+    if (eocd < 0)
+        throw new Error('Postgres jar is not a zip file');
+    let offset = zip.readUInt32LE(eocd + 16);
+    const count = zip.readUInt16LE(eocd + 10);
+    for (let n = 0; n < count; n++) {
+        if (zip.readUInt32LE(offset) !== 0x02014b50)
+            throw new Error('corrupt zip central directory');
+        const method = zip.readUInt16LE(offset + 10);
+        const compressed = zip.readUInt32LE(offset + 20);
+        const nameLen = zip.readUInt16LE(offset + 28);
+        const extraLen = zip.readUInt16LE(offset + 30);
+        const commentLen = zip.readUInt16LE(offset + 32);
+        const local = zip.readUInt32LE(offset + 42);
+        const name = zip.toString('utf8', offset + 46, offset + 46 + nameLen);
+        offset += 46 + nameLen + extraLen + commentLen;
+        if (!wanted(name))
+            continue;
+        const dataStart = local + 30 + zip.readUInt16LE(local + 26) + zip.readUInt16LE(local + 28);
+        const raw = zip.subarray(dataStart, dataStart + compressed);
+        if (method === 0)
+            return { name, data: raw };
+        if (method === 8)
+            return { name, data: inflateRawSync(raw) };
+        throw new Error(`unsupported zip compression method ${method}`);
+    }
+    throw new Error('Postgres jar holds no .txz archive');
+}
+async function download(url, expectedSha256, dest) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(300_000) });
+    if (!response.ok || response.body === null)
+        throw new Error(`downloading ${url} failed: HTTP ${response.status}`);
+    const hash = createHash('sha256');
+    const body = Readable.fromWeb(response.body);
+    body.on('data', (chunk) => hash.update(chunk));
+    await pipeline(body, createWriteStream(dest));
+    const actual = hash.digest('hex');
+    if (actual !== expectedSha256) {
+        rmSync(dest, { force: true });
+        throw new Error(`${url} has sha256 ${actual}, expected the pinned ${expectedSha256}; refusing to unpack it`);
+    }
+}
+function isFatMachO(path) {
+    const fd = openSync(path, 'r');
+    try {
+        const magic = Buffer.alloc(4);
+        return readSync(fd, magic, 0, 4, 0) === 4 && magic.readUInt32BE(0) === 0xcafebabe;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function walkFiles(dir, out = []) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            walkFiles(path, out);
+        else if (entry.isFile())
+            out.push(path);
+    }
+    return out;
+}
+/** macOS jars hold a universal binary and store each ICU library under three names as full copies. Keep the host
+ *  architecture and turn byte-identical files in `lib/` into symlinks to one copy. */
+function slimDarwinTree(root) {
+    const arch = process.arch === 'arm64' ? 'arm64' : 'x86_64';
+    const files = [...walkFiles(join(root, 'bin')), ...walkFiles(join(root, 'lib'))];
+    for (const file of files) {
+        if (!isFatMachO(file))
+            continue;
+        const thin = `${file}.thin`;
+        const run = spawnSync('lipo', ['-thin', arch, '-output', thin, file], { encoding: 'utf8' });
+        if (run.status !== 0)
+            throw new Error(`lipo -thin ${arch} ${file} failed: ${run.stderr}`);
+        renameSync(thin, file);
+    }
+    const byHash = new Map();
+    for (const file of walkFiles(join(root, 'lib'))) {
+        const digest = createHash('sha256').update(readFileSync(file)).digest('hex');
+        byHash.set(digest, [...(byHash.get(digest) ?? []), file]);
+    }
+    for (const group of byHash.values()) {
+        if (group.length < 2)
+            continue;
+        const keep = group.reduce((a, b) => (basename(b).length > basename(a).length ? b : a));
+        for (const file of group) {
+            if (file === keep || dirname(file) !== dirname(keep))
+                continue;
+            unlinkSync(file);
+            symlinkSync(basename(keep), file);
+        }
+    }
+    // lipo drops nothing from a slice's own signature, but verify and re-sign ad hoc if the tree no longer verifies.
+    const verify = spawnSync('codesign', ['--verify', join(root, 'bin', 'postgres')], { encoding: 'utf8' });
+    if (verify.status !== 0) {
+        for (const file of [...walkFiles(join(root, 'bin')), ...walkFiles(join(root, 'lib')).filter((f) => !lstatSync(f).isSymbolicLink())]) {
+            spawnSync('codesign', ['--force', '--sign', '-', file], { encoding: 'utf8' });
+        }
+    }
+}
+/**
+ * Resolve the Postgres binaries: `CRTR_POSTGRES_HOME` names a pre-unpacked tree (the CI image bakes one); otherwise
+ * the pinned jar is downloaded from Maven Central, sha256-verified, unpacked and slimmed into the version-keyed shared
+ * cache, once, under a lock. A later call finds the ready stamp and does no work.
+ */
+export async function ensurePostgresBinaries(log = () => { }) {
+    const preset = process.env['CRTR_POSTGRES_HOME'];
+    if (preset) {
+        const binaries = describe(resolve(preset));
+        if (!existsSync(binaries.postgres))
+            throw new Error(`CRTR_POSTGRES_HOME=${preset} has no bin/postgres`);
+        return binaries;
+    }
+    const cache = postgresCacheDir();
+    const ready = join(cache, READY_STAMP);
+    if (existsSync(ready))
+        return describe(cache);
+    const suffix = hostJarSuffix();
+    const sha = POSTGRES_JAR_SHA256[suffix];
+    if (sha === undefined)
+        throw new Error(`no sha256 pinned for Postgres build ${suffix}`);
+    mkdirSync(dirname(cache), { recursive: true });
+    const lockPath = `${cache}.lock`;
+    await withExclusiveDirectoryLockAsync(lockPath, async () => {
+        if (existsSync(ready))
+            return;
+        const work = `${cache}.tmp-${process.pid}`;
+        rmSync(work, { recursive: true, force: true });
+        mkdirSync(work, { recursive: true });
+        try {
+            const started = Date.now();
+            const jar = join(work, 'postgres.jar');
+            await download(jarUrl(suffix), sha, jar);
+            log(`postgres ${POSTGRES_VERSION} (${suffix}) downloaded and verified in ${Date.now() - started} ms`);
+            const txz = extractZipEntry(readFileSync(jar), (name) => name.endsWith('.txz'));
+            const archive = join(work, 'postgres.txz');
+            writeFileSync(archive, txz.data);
+            const tree = join(work, 'tree');
+            mkdirSync(tree);
+            const untar = spawnSync('tar', ['-xJf', archive, '-C', tree], { encoding: 'utf8' });
+            if (untar.status !== 0)
+                throw new Error(`unpacking the Postgres archive failed: ${untar.stderr || untar.error?.message}`);
+            if (process.platform === 'darwin')
+                slimDarwinTree(tree);
+            writeFileSync(join(tree, READY_STAMP), `${POSTGRES_VERSION} ${suffix}\n`);
+            rmSync(cache, { recursive: true, force: true });
+            renameSync(tree, cache);
+        }
+        finally {
+            rmSync(work, { recursive: true, force: true });
+        }
+    }, { timeoutMs: 600_000, staleMs: 600_000 });
+    return describe(cache);
+}

package/dist/daemon/postgres/cluster.d.ts

@@ -0,0 +1,37 @@
+import type { PostgresBinaries } from './binary.js';
+/** A Unix socket path longer than this fails in `bind()` on macOS (`sun_path` is 104 bytes with the NUL). */
+export declare const MAX_SOCKET_PATH_BYTES = 103;
+export declare const POSTGRES_PORT = 5432;
+export declare const DATABASE_NAME = "postgres";
+/** The supervisor refuses to boot the daemon if Postgres does not answer within this long. */
+export declare const READY_TIMEOUT_MS = 15000;
+export interface ClusterSettings {
+    dataDir: string;
+    socketDir: string;
+    maxConnections: number;
+    /** Also listen on this TCP address (scratch clusters only; the local supervisor listens on the socket alone). */
+    tcp?: {
+        host: string;
+        port: number;
+    };
+    /** Run initdb and postgres as this OS user (a root-run test lane starts its cluster as a non-root user). */
+    asUser?: {
+        uid: number;
+        gid: number;
+    };
+}
+/** The socket file is `.s.PGSQL.<port>`; pass `port` when the postmaster also listens on a TCP port other than the default. */
+export declare function socketUrl(user: string, socketDir: string, port?: number): string;
+export declare function tcpUrl(user: string, host: string, port: number): string;
+/** Postgres refuses to run as root; say so before it does, in terms of what to change. */
+export declare function assertNotRoot(what: string): void;
+export declare function clusterInitialized(dataDir: string): boolean;
+export declare function postmasterPid(dataDir: string): number | null;
+/** `initdb` a new cluster. `trust` is for throwaway clusters; the local cluster uses peer authentication on its socket. */
+export declare function initCluster(bins: PostgresBinaries, settings: ClusterSettings, user: string, auth: 'peer' | 'trust'): void;
+/** Open a connection, run `SELECT 1`, close. Resolves to the failure message when the server does not answer. */
+export declare function probe(url: string, timeoutMs?: number): Promise<string | null>;
+/** Start `postgres` detached in its own process group and wait until `url` answers `SELECT 1`. */
+export declare function startPostmaster(bins: PostgresBinaries, settings: ClusterSettings, url: string, logFile: string, timeoutMs?: number): Promise<void>;
+/** `pg_ctl stop -m fast`, waiting for the postmaster to exit. A cluster that is not running is a no-op. */
+export declare function stopPostmaster(bins: PostgresBinaries, settings: Pick<ClusterSettings, 'dataDir' | 'asUser'>): void;

package/dist/daemon/postgres/cluster.js

@@ -0,0 +1,111 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { closeSync, existsSync, openSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** A Unix socket path longer than this fails in `bind()` on macOS (`sun_path` is 104 bytes with the NUL). */
+export const MAX_SOCKET_PATH_BYTES = 103;
+export const POSTGRES_PORT = 5432;
+export const DATABASE_NAME = 'postgres';
+/** The supervisor refuses to boot the daemon if Postgres does not answer within this long. */
+export const READY_TIMEOUT_MS = 15_000;
+/** The socket file is `.s.PGSQL.<port>`; pass `port` when the postmaster also listens on a TCP port other than the default. */
+export function socketUrl(user, socketDir, port) {
+    return `postgresql://${encodeURIComponent(user)}@/${DATABASE_NAME}?host=${encodeURIComponent(socketDir)}${port === undefined ? '' : `&port=${port}`}`;
+}
+export function tcpUrl(user, host, port) {
+    return `postgresql://${encodeURIComponent(user)}@${host}:${port}/${DATABASE_NAME}`;
+}
+/** Postgres refuses to run as root; say so before it does, in terms of what to change. */
+export function assertNotRoot(what) {
+    if (typeof process.getuid === 'function' && process.getuid() === 0) {
+        throw new Error(`${what}: Postgres refuses to run as root, and this process is root. Run crtrd as a non-root user (the hosted guest launches it as the crtrd user through setpriv), or set CRTR_DATABASE_URL to an existing Postgres.`);
+    }
+}
+export function clusterInitialized(dataDir) {
+    return existsSync(join(dataDir, 'PG_VERSION'));
+}
+export function postmasterPid(dataDir) {
+    try {
+        const pid = Number(readFileSync(join(dataDir, 'postmaster.pid'), 'utf8').split('\n', 1)[0]);
+        return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+function identity(settings) {
+    return settings.asUser ? { uid: settings.asUser.uid, gid: settings.asUser.gid } : {};
+}
+/** `initdb` a new cluster. `trust` is for throwaway clusters; the local cluster uses peer authentication on its socket. */
+export function initCluster(bins, settings, user, auth) {
+    const args = ['-D', settings.dataDir, '-U', user, '--encoding=UTF8', '--locale=C', '--no-instructions',
+        ...(auth === 'peer' ? ['--auth-local=peer', '--auth-host=reject'] : ['--auth=trust'])];
+    const run = spawnSync(bins.initdb, args, { encoding: 'utf8', ...identity(settings), env: { ...process.env, LC_ALL: 'C' } });
+    if (run.status !== 0)
+        throw new Error(`initdb failed (${run.status ?? run.error?.message}): ${(run.stderr || run.stdout).trim()}`);
+}
+function logTail(logFile) {
+    try {
+        return readFileSync(logFile, 'utf8').trim().split('\n').slice(-12).join('\n');
+    }
+    catch {
+        return '(no log)';
+    }
+}
+/** Open a connection, run `SELECT 1`, close. Resolves to the failure message when the server does not answer. */
+export async function probe(url, timeoutMs = 1000) {
+    const { default: pg } = await import('pg');
+    const client = new pg.Client({ connectionString: url, connectionTimeoutMillis: timeoutMs });
+    client.on('error', () => { });
+    try {
+        await client.connect();
+        await client.query('SELECT 1');
+        return null;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    finally {
+        await client.end().catch(() => { });
+    }
+}
+/** Start `postgres` detached in its own process group and wait until `url` answers `SELECT 1`. */
+export async function startPostmaster(bins, settings, url, logFile, timeoutMs = READY_TIMEOUT_MS) {
+    const args = ['-D', settings.dataDir,
+        '-c', `listen_addresses=${settings.tcp ? settings.tcp.host : ''}`,
+        ...(settings.tcp ? ['-c', `port=${settings.tcp.port}`] : []),
+        '-c', `unix_socket_directories=${settings.socketDir}`,
+        '-c', `max_connections=${settings.maxConnections}`,
+        '-c', 'fsync=on'];
+    const log = openSync(logFile, 'a', 0o600);
+    let exited = null;
+    try {
+        const child = spawn(bins.postgres, args, { detached: true, stdio: ['ignore', log, log], env: { ...process.env, LC_ALL: 'C' }, ...identity(settings) });
+        child.on('exit', (code, signal) => { exited = `exited with ${code ?? signal}`; });
+        child.on('error', (error) => { exited = error.message; });
+        child.unref();
+        const deadline = Date.now() + timeoutMs;
+        let last = 'not tried';
+        while (Date.now() < deadline) {
+            if (exited !== null)
+                throw new Error(`postgres ${exited} before answering:\n${logTail(logFile)}`);
+            last = await probe(url, 500);
+            if (last === null) {
+                child.removeAllListeners();
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        throw new Error(`postgres did not answer SELECT 1 within ${timeoutMs / 1000} s (${last}):\n${logTail(logFile)}`);
+    }
+    finally {
+        closeSync(log);
+    }
+}
+/** `pg_ctl stop -m fast`, waiting for the postmaster to exit. A cluster that is not running is a no-op. */
+export function stopPostmaster(bins, settings) {
+    if (postmasterPid(settings.dataDir) === null)
+        return;
+    const run = spawnSync(bins.pgCtl, ['stop', '-D', settings.dataDir, '-m', 'fast', '-w', '-t', '60'], { encoding: 'utf8', ...identity(settings) });
+    if (run.status !== 0 && postmasterPid(settings.dataDir) !== null)
+        throw new Error(`pg_ctl stop failed (${run.status ?? run.error?.message}): ${(run.stderr || run.stdout).trim()}`);
+}

package/dist/daemon/postgres/pins.d.ts

@@ -0,0 +1,7 @@
+/** The pinned zonky embedded-postgres-binaries release (Maven Central, io.zonky.test.postgres). A bump is a
+ *  deliberate edit here plus `node scripts/postgres-pin.mjs` for the hashes; the cache path is version-keyed, so the
+ *  old tree is orphaned and one fresh download happens. A new major version also needs a pg_upgrade step. */
+export declare const POSTGRES_VERSION = "18.6.0";
+/** Artifact id suffix of `embedded-postgres-binaries-<suffix>` → sha256 of its jar. */
+export declare const POSTGRES_JAR_SHA256: Record<string, string>;
+export declare function jarUrl(suffix: string, version?: string): string;

package/dist/daemon/postgres/pins.js

@@ -0,0 +1,16 @@
+/** The pinned zonky embedded-postgres-binaries release (Maven Central, io.zonky.test.postgres). A bump is a
+ *  deliberate edit here plus `node scripts/postgres-pin.mjs` for the hashes; the cache path is version-keyed, so the
+ *  old tree is orphaned and one fresh download happens. A new major version also needs a pg_upgrade step. */
+export const POSTGRES_VERSION = '18.6.0';
+/** Artifact id suffix of `embedded-postgres-binaries-<suffix>` → sha256 of its jar. */
+export const POSTGRES_JAR_SHA256 = {
+    'darwin-arm64v8': '8f6ed6f38195b50a40712ada8b2a12060b6193c1a6977a6eb5cff053bb5a1b89',
+    'darwin-amd64': '690941008aac9ee360820fde9bb7870a4f3dcac5e9e2f9e45e42333a436ad0f9',
+    'linux-amd64': '008ee189eaa7ca2b58bd01dd950291e638b998392cf982297acd4779ec898ac1',
+    'linux-arm64v8': '5f54e016723afa6213925a8acb939bac52944b1d348f65c7a20f0cd2928c31be',
+    'linux-amd64-alpine': '1568b3805c3a3b99b5f4f0d7f6cf16e2a39075462ed47a614bfbabd92508350d',
+    'linux-arm64v8-alpine': 'dccf3c9c8438973e6e8cd9cd511af4a2c6a88d1c90a4cc0465a8f8797808e717',
+};
+export function jarUrl(suffix, version = POSTGRES_VERSION) {
+    return `https://repo1.maven.org/maven2/io/zonky/test/postgres/embedded-postgres-binaries-${suffix}/${version}/embedded-postgres-binaries-${suffix}-${version}.jar`;
+}

package/dist/daemon/postgres/supervisor.d.ts

@@ -0,0 +1,95 @@
+/** Where the daemon's database is and whether this process started it. */
+export interface PostgresEndpoint {
+    /** Connection string for `pg`. */
+    url: string;
+    /** True when this call started the postmaster; false when it adopted a running one (or the URL is external). */
+    started: boolean;
+}
+type Log = (message: string) => void;
+/** The URL of an external Postgres, when `CRTR_DATABASE_URL` names one. */
+export declare function externalDatabaseUrl(): string | null;
+export interface PostgresPaths {
+    /** `<runtime root>/pg` */
+    dir: string;
+    dataDir: string;
+    /** Exclusive directory lock serializing start/adopt across processes. */
+    lockPath: string;
+    /** Holds the socket directory path; written at start for tools that read it without computing it. */
+    socketDirFile: string;
+    logFile: string;
+    /** Directory holding `.s.PGSQL.5432`: `<runtime root>/pg`, or a short `/tmp` directory when that path is too long. */
+    socketDir: string;
+}
+/** Pure path computation for a runtime root; touches no disk. */
+export declare function postgresPaths(root?: string): PostgresPaths;
+/**
+ * The URL the daemon connects to, computed without starting anything: `CRTR_DATABASE_URL` when set, otherwise the
+ * supervised cluster's socket for this runtime root. Valid once `ensurePostgres()` has returned.
+ */
+export declare function resolveDatabaseUrl(root?: string): string;
+/**
+ * Make sure the database for this runtime root answers, and return how to reach it. With `CRTR_DATABASE_URL` set this
+ * does nothing. Otherwise: adopt a running postmaster on the runtime root's socket, or (under `runtime/pg/start.lock`)
+ * download the pinned binaries if needed, `initdb` on first need, start `postgres`, and wait up to 15 s for `SELECT 1`.
+ * Postgres is never stopped here; a handover leaves it running for the successor to adopt.
+ */
+export declare function ensurePostgres(options?: {
+    root?: string;
+    log?: Log;
+    startLockHeld?: boolean;
+}): Promise<PostgresEndpoint>;
+/**
+ * Run `operation` under `runtime/pg/start.lock`, the lock that orders starting or adopting the postmaster against
+ * stopping it. The daemon holds it across `ensurePostgres({ startLockHeld: true })` and its ownership claim, and
+ * `stopPostgres` holds it across its "no daemon has claimed the database" check and `pg_ctl stop`, so a successor
+ * can never adopt a postmaster that is about to be stopped. With `CRTR_DATABASE_URL` set it runs `operation` unlocked.
+ */
+export declare function withPostgresStartLock<T>(operation: () => Promise<T>, root?: string): Promise<T>;
+/**
+ * The daemon's health tick. Returns when the database answers. If it does not, restart it once (WAL recovery handles
+ * the data); a second failure within a minute throws so the daemon's readiness fails.
+ */
+export declare function ensurePostgresHealthy(options?: {
+    root?: string;
+    log?: Log;
+}): Promise<PostgresEndpoint>;
+/**
+ * `crtr sys daemon stop`: `pg_ctl stop -m fast` for this runtime root's cluster, unless `claimed()` reports that
+ * another daemon already owns the database. Both run under the start lock, so no daemon can adopt the postmaster
+ * between the check and the stop. Call after this daemon's ownership claim is released. Never call on a handover.
+ * Returns whether it stopped the cluster; a no-op for an external URL or a stopped cluster.
+ */
+export declare function stopPostgres(options: {
+    root?: string;
+    claimed: () => Promise<boolean>;
+}): Promise<boolean>;
+export interface ScratchCluster {
+    /** Socket URL (superuser `crtr`, database `postgres`, trust authentication). */
+    url: string;
+    /** TCP URL, when `tcp` was requested. */
+    tcpUrl: string | null;
+    dir: string;
+    stop(options?: {
+        remove?: boolean;
+    }): Promise<void>;
+}
+/**
+ * Start a throwaway cluster for a test lane under `dir`, which must be short enough for the socket path (use
+ * `/tmp/<something>`). Data lives in `<dir>/data`, the socket in `<dir>`. Trust authentication, `max_connections`
+ * 100 by default. Independent of CRTR_DATABASE_URL and of any runtime root. Run as root, pass `asUser` (the directory
+ * is chowned to it); otherwise root is refused.
+ */
+export declare function startScratchCluster(options: {
+    dir: string;
+    tcp?: {
+        host: string;
+        port: number;
+    };
+    maxConnections?: number;
+    asUser?: {
+        uid: number;
+        gid: number;
+    };
+    log?: Log;
+}): Promise<ScratchCluster>;
+export {};

package/dist/daemon/postgres/supervisor.js

@@ -0,0 +1,177 @@
+import { createHash } from 'node:crypto';
+import { chownSync, chmodSync, existsSync, lstatSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { join } from 'node:path';
+import { withExclusiveDirectoryLockAsync } from '../../core/exclusive-lock.js';
+import { runtimeRoot } from '../../core/layout.js';
+import { ensurePostgresBinaries } from './binary.js';
+import { MAX_SOCKET_PATH_BYTES, POSTGRES_PORT, assertNotRoot, clusterInitialized, initCluster, probe, socketUrl, startPostmaster, stopPostmaster, tcpUrl, } from './cluster.js';
+const noLog = () => { };
+/** The URL of an external Postgres, when `CRTR_DATABASE_URL` names one. */
+export function externalDatabaseUrl() {
+    return process.env['CRTR_DATABASE_URL'] || null;
+}
+/** Pure path computation for a runtime root; touches no disk. */
+export function postgresPaths(root = runtimeRoot()) {
+    const dir = join(root, 'pg');
+    const socketName = `.s.PGSQL.${POSTGRES_PORT}`;
+    const inRoot = Buffer.byteLength(join(dir, socketName)) <= MAX_SOCKET_PATH_BYTES;
+    const socketDir = inRoot ? dir : `/tmp/crtr-pg-${createHash('sha256').update(root).digest('hex').slice(0, 8)}`;
+    if (!inRoot && Buffer.byteLength(join(socketDir, socketName)) > MAX_SOCKET_PATH_BYTES)
+        throw new Error(`socket path ${join(socketDir, socketName)} is too long`);
+    return { dir, dataDir: join(dir, 'data'), lockPath: join(dir, 'start.lock'), socketDirFile: join(dir, 'socket-dir'), logFile: join(dir, 'postgres.log'), socketDir };
+}
+function osUser() { return userInfo().username; }
+/**
+ * The URL the daemon connects to, computed without starting anything: `CRTR_DATABASE_URL` when set, otherwise the
+ * supervised cluster's socket for this runtime root. Valid once `ensurePostgres()` has returned.
+ */
+export function resolveDatabaseUrl(root = runtimeRoot()) {
+    return externalDatabaseUrl() ?? socketUrl(osUser(), postgresPaths(root).socketDir);
+}
+/** A private (0700, ours) directory; refuses a pre-existing directory that is someone else's or open to others. */
+function ensurePrivateDir(path) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error(`${path} is not a directory`);
+    if (typeof process.getuid === 'function' && stat.uid !== process.getuid())
+        throw new Error(`${path} is owned by uid ${stat.uid}, not this process; refusing to put the Postgres socket there`);
+    if ((stat.mode & 0o077) !== 0)
+        chmodSync(path, 0o700);
+}
+/**
+ * Make sure the database for this runtime root answers, and return how to reach it. With `CRTR_DATABASE_URL` set this
+ * does nothing. Otherwise: adopt a running postmaster on the runtime root's socket, or (under `runtime/pg/start.lock`)
+ * download the pinned binaries if needed, `initdb` on first need, start `postgres`, and wait up to 15 s for `SELECT 1`.
+ * Postgres is never stopped here; a handover leaves it running for the successor to adopt.
+ */
+export async function ensurePostgres(options = {}) {
+    const log = options.log ?? noLog;
+    const external = externalDatabaseUrl();
+    if (external !== null)
+        return { url: external, started: false };
+    assertNotRoot('crtrd cannot start its database');
+    const paths = postgresPaths(options.root);
+    const url = resolveDatabaseUrl(options.root);
+    if (await probe(url) === null)
+        return { url, started: false };
+    const bins = await ensurePostgresBinaries(log);
+    ensurePrivateDir(paths.dir);
+    if (paths.socketDir !== paths.dir)
+        ensurePrivateDir(paths.socketDir);
+    const locked = options.startLockHeld === true
+        ? (operation) => operation()
+        : (operation) => withPostgresStartLock(operation, options.root);
+    return locked(async () => {
+        if (await probe(url) === null)
+            return { url, started: false };
+        const settings = { dataDir: paths.dataDir, socketDir: paths.socketDir, maxConnections: 20 };
+        if (!clusterInitialized(paths.dataDir)) {
+            const started = Date.now();
+            initCluster(bins, settings, osUser(), 'peer');
+            log(`postgres cluster initialized in ${Date.now() - started} ms`);
+        }
+        writeFileSync(paths.socketDirFile, `${paths.socketDir}\n`);
+        const started = Date.now();
+        await startPostmaster(bins, settings, url, paths.logFile);
+        log(`postgres started in ${Date.now() - started} ms`);
+        return { url, started: true };
+    });
+}
+/**
+ * Run `operation` under `runtime/pg/start.lock`, the lock that orders starting or adopting the postmaster against
+ * stopping it. The daemon holds it across `ensurePostgres({ startLockHeld: true })` and its ownership claim, and
+ * `stopPostgres` holds it across its "no daemon has claimed the database" check and `pg_ctl stop`, so a successor
+ * can never adopt a postmaster that is about to be stopped. With `CRTR_DATABASE_URL` set it runs `operation` unlocked.
+ */
+export async function withPostgresStartLock(operation, root) {
+    if (externalDatabaseUrl() !== null)
+        return operation();
+    const paths = postgresPaths(root);
+    ensurePrivateDir(paths.dir);
+    return withExclusiveDirectoryLockAsync(paths.lockPath, operation, {
+        timeoutMs: 45_000, staleMs: 45_000,
+        timeoutError: () => new Error(`timed out waiting for another process to start or stop Postgres (lock ${paths.lockPath})`),
+    });
+}
+let lastRestartAt = 0;
+/**
+ * The daemon's health tick. Returns when the database answers. If it does not, restart it once (WAL recovery handles
+ * the data); a second failure within a minute throws so the daemon's readiness fails.
+ */
+export async function ensurePostgresHealthy(options = {}) {
+    const url = resolveDatabaseUrl(options.root);
+    if (externalDatabaseUrl() !== null || await probe(url, 2000) === null)
+        return { url, started: false };
+    const now = Date.now();
+    if (now - lastRestartAt < 60_000)
+        throw new Error(`Postgres stopped answering twice within a minute; see ${postgresPaths(options.root).logFile}`);
+    (options.log ?? noLog)('postgres did not answer the 2 s health probe; restarting it unless it answers now');
+    // ensurePostgres adopts a postmaster that answers its own probe (slow, not dead) and logs "postgres started" only
+    // when it really starts one; only a real restart counts toward the twice-within-a-minute failure.
+    const endpoint = await ensurePostgres(options);
+    if (endpoint.started)
+        lastRestartAt = now;
+    return endpoint;
+}
+/**
+ * `crtr sys daemon stop`: `pg_ctl stop -m fast` for this runtime root's cluster, unless `claimed()` reports that
+ * another daemon already owns the database. Both run under the start lock, so no daemon can adopt the postmaster
+ * between the check and the stop. Call after this daemon's ownership claim is released. Never call on a handover.
+ * Returns whether it stopped the cluster; a no-op for an external URL or a stopped cluster.
+ */
+export async function stopPostgres(options) {
+    if (externalDatabaseUrl() !== null)
+        return false;
+    const paths = postgresPaths(options.root);
+    if (!existsSync(join(paths.dataDir, 'postmaster.pid')))
+        return false;
+    return withPostgresStartLock(async () => {
+        if (await options.claimed())
+            return false;
+        stopPostmaster(await ensurePostgresBinaries(), { dataDir: paths.dataDir });
+        return true;
+    }, options.root);
+}
+/**
+ * Start a throwaway cluster for a test lane under `dir`, which must be short enough for the socket path (use
+ * `/tmp/<something>`). Data lives in `<dir>/data`, the socket in `<dir>`. Trust authentication, `max_connections`
+ * 100 by default. Independent of CRTR_DATABASE_URL and of any runtime root. Run as root, pass `asUser` (the directory
+ * is chowned to it); otherwise root is refused.
+ */
+export async function startScratchCluster(options) {
+    const log = options.log ?? noLog;
+    if (options.asUser === undefined)
+        assertNotRoot('a scratch Postgres cluster');
+    const bins = await ensurePostgresBinaries(log);
+    ensurePrivateDir(options.dir);
+    if (options.asUser)
+        chownSync(options.dir, options.asUser.uid, options.asUser.gid);
+    if (Buffer.byteLength(join(options.dir, `.s.PGSQL.${options.tcp?.port ?? POSTGRES_PORT}`)) > MAX_SOCKET_PATH_BYTES)
+        throw new Error(`scratch directory ${options.dir} is too long for a Postgres socket path`);
+    const settings = { dataDir: join(options.dir, 'data'), socketDir: options.dir, maxConnections: options.maxConnections ?? 100, ...(options.tcp ? { tcp: options.tcp } : {}), ...(options.asUser ? { asUser: options.asUser } : {}) };
+    const url = socketUrl('crtr', options.dir, options.tcp?.port);
+    try {
+        initCluster(bins, settings, 'crtr', 'trust');
+        await startPostmaster(bins, settings, url, join(options.dir, 'postgres.log'));
+    }
+    catch (error) {
+        // A postmaster that started but never answered must not outlive the failed call, or its directory cannot be removed.
+        try {
+            stopPostmaster(bins, settings);
+        }
+        catch { /* the startup error is the one to report */ }
+        throw error;
+    }
+    return {
+        url,
+        tcpUrl: options.tcp ? tcpUrl('crtr', options.tcp.host, options.tcp.port) : null,
+        dir: options.dir,
+        stop: async (stopOptions = {}) => {
+            stopPostmaster(bins, settings);
+            if (stopOptions.remove !== false)
+                rmSync(options.dir, { recursive: true, force: true });
+        },
+    };
+}

package/dist/daemon/readiness.d.ts

@@ -0,0 +1,11 @@
+import type { ReadyDTO } from '../api/dto/health.js';
+/** True on a joined Mac whose issuer snapshot has never committed (a committed empty snapshot counts as committed). A cloud role
+ *  never waits on a snapshot: its grant authority is the shared grant rows the directory writes directly, always installed. */
+export declare function grantSnapshotMissing(): Promise<boolean>;
+export interface ReadinessInputs {
+    /** App listener only: the JWKS mirror has loaded. */
+    jwksReady?: boolean;
+    /** App listener only: its injected grant-snapshot test, used in place of the mirror read. */
+    grantsReady?: () => boolean;
+}
+export declare function runtimeReadiness(inputs?: ReadinessInputs): Promise<ReadyDTO>;