@north-light/api 0.3.580 → 0.3.587

package/dist/core/canvas/daemon-actions.js

@@ -0,0 +1,98 @@
+// One-shot daemon obligations that have no publishing object and no event:
+// cron `spawn`/`human` sinks and human-request completion actions. They were
+// `external_action` rows in `deliveries`; they live here so `deliveries`
+// carries only deliveries to objects. The daemon action lane
+// (`daemon/reconcilers/action-lane.ts`) claims and settles these rows with the
+// same state/attempt/owner fence `settleDelivery` applies to deliveries.
+import { randomBytes } from 'node:crypto';
+import { withCanvasWrite, openDb } from './db.js';
+import { normalizedSettlement } from './deliveries.js';
+import { withRetryBudget } from './delivery-contract.js';
+import { emitEvent } from '../events/emit.js';
+function actionFrom(row) {
+    return {
+        actionId: row.action_id,
+        adapter: JSON.parse(row.adapter_json),
+        body: row.body_json === null ? null : JSON.parse(row.body_json),
+        idempotencyKey: row.idempotency_key,
+        state: row.state,
+        attempts: row.attempts,
+        nextAttemptAt: row.next_attempt_at,
+        claimedAt: row.claimed_at,
+        claimOwner: row.claim_owner,
+        acknowledgedAt: row.acknowledged_at,
+        failedAt: row.failed_at,
+        lastFailure: row.last_failure_json === null ? null : JSON.parse(row.last_failure_json),
+        canceledAt: row.canceled_at,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function newId() {
+    return randomBytes(16).toString('hex');
+}
+/** Insert one frozen daemon action, due now. A duplicate idempotency key returns the original action id. */
+export async function enqueueDaemonAction(input) {
+    return await withCanvasWrite(async (db) => {
+        const existing = await db.prepare('SELECT action_id FROM daemon_actions WHERE idempotency_key = ?').get(input.idempotencyKey);
+        if (existing !== undefined)
+            return existing.action_id;
+        const now = Date.now();
+        const actionId = newId();
+        const bodyJson = input.bodyJson === undefined ? null : JSON.stringify(input.bodyJson);
+        await db.prepare(`INSERT INTO daemon_actions (action_id, adapter_json, body_json, idempotency_key, state, attempts, next_attempt_at, created_at, updated_at)
+       VALUES (?, ?, ?, ?, 'pending', 0, ?, ?, ?)`).run(actionId, JSON.stringify(input.adapter), bodyJson, input.idempotencyKey, now, now, now);
+        return actionId;
+    });
+}
+export async function readDaemonAction(idempotencyKey) {
+    const row = await (await openDb()).prepare('SELECT * FROM daemon_actions WHERE idempotency_key = ?').get(idempotencyKey);
+    return row === undefined ? null : actionFrom(row);
+}
+export async function readDaemonActionById(actionId) {
+    const row = await (await openDb()).prepare('SELECT * FROM daemon_actions WHERE action_id = ?').get(actionId);
+    return row === undefined ? null : actionFrom(row);
+}
+export async function dueDaemonActions(now) {
+    return (await (await openDb()).prepare(`SELECT * FROM daemon_actions
+      WHERE state = 'pending' AND canceled_at IS NULL AND next_attempt_at <= ?
+      ORDER BY next_attempt_at, created_at, action_id`).all(now)).map(actionFrom);
+}
+export async function claimDaemonAction(actionId, now, claimOwner) {
+    return await withCanvasWrite(async (db) => {
+        const result = await db.prepare(`UPDATE daemon_actions SET state = 'handed_off', attempts = attempts + 1, claimed_at = ?, claim_owner = ?, updated_at = ?
+        WHERE action_id = ? AND state = 'pending' AND canceled_at IS NULL AND next_attempt_at <= ?`).run(now, claimOwner, now, actionId, now);
+        if (Number(result.changes) === 0)
+            return null;
+        return actionFrom(await db.prepare('SELECT * FROM daemon_actions WHERE action_id = ?').get(actionId));
+    });
+}
+/** The state/attempt/owner fence, identical in shape to `settleDelivery`. */
+export async function settleDaemonAction(actionId, attempts, claimOwner, settlement, now = Date.now()) {
+    // The same finite attempt budget as `settleDelivery`: the last failure is terminal, not another retry.
+    const budget = withRetryBudget(normalizedSettlement(settlement), attempts);
+    const next = budget.settlement;
+    const failure = next.state === 'pending' || next.state === 'permanent_failed' ? JSON.stringify(next.failure) : null;
+    const state = next.state === 'released' ? 'pending' : next.state;
+    const nextAttemptAt = next.state === 'pending' ? next.nextAttemptAt : state === 'pending' ? now : null;
+    const changed = Number((await (await openDb()).prepare(`UPDATE daemon_actions
+        SET state = ?, next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL,
+            acknowledged_at = ?, failed_at = ?, last_failure_json = ?, updated_at = ?
+      WHERE action_id = ? AND state = 'handed_off' AND attempts = ? AND claim_owner = ?`).run(state, nextAttemptAt, state === 'acknowledged' ? now : null, state === 'permanent_failed' ? now : null, failure, now, actionId, attempts, claimOwner)).changes) === 1;
+    if (changed && budget.exhausted && next.state === 'permanent_failed') {
+        emitEvent({ level: 'error', event: 'daemon_action.exhausted', outcome: 'failed', attempt: attempts,
+            fields: { action_id: actionId, failure: next.failure, retry: `crtr sys retry-delivery ${actionId}` } });
+    }
+    return changed;
+}
+/** Deliberate operator retry of a daemon action that failed for good: pending, due now, fresh attempt budget. */
+export async function retryFailedDaemonAction(actionId, now = Date.now()) {
+    return Number((await (await openDb()).prepare(`UPDATE daemon_actions
+        SET state = 'pending', attempts = 0, next_attempt_at = ?, failed_at = NULL, updated_at = ?
+      WHERE action_id = ? AND state = 'permanent_failed' AND canceled_at IS NULL AND last_failure_json IS NOT NULL`).run(now, now, actionId)).changes) === 1;
+}
+/** Daemon startup: an action a previous daemon handed off is due again now. */
+export async function resetHandedOffDaemonActions(now) {
+    return Number((await (await openDb()).prepare(`UPDATE daemon_actions SET state = 'pending', next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL, updated_at = ?
+      WHERE state = 'handed_off'`).run(now, now)).changes);
+}

package/dist/core/canvas/db.d.ts

@@ -0,0 +1,60 @@
+import type { SQLInputValue } from 'node:sqlite';
+/** Thrown for a unique-constraint violation (SQLSTATE 23505). `constraint` is the violated constraint or unique index. */
+export declare class CanvasConstraintError extends Error {
+    readonly constraint: string | undefined;
+    readonly code = "23505";
+    constructor(message: string, constraint: string | undefined, options?: {
+        cause?: unknown;
+    });
+}
+export type CanvasValue = SQLInputValue;
+export type CanvasParams = CanvasValue[];
+export interface CanvasRunResult {
+    changes: number;
+}
+export interface CanvasStatement {
+    get<T = Record<string, unknown>>(...params: CanvasParams): Promise<T | undefined>;
+    all<T = Record<string, unknown>>(...params: CanvasParams): Promise<T[]>;
+    run(...params: CanvasParams): Promise<CanvasRunResult>;
+}
+export interface CanvasDb {
+    /** A named prepared statement, translated once per connection; for fixed SQL only. */
+    prepare(sql: string): CanvasStatement;
+    /** An unnamed statement per call; for generated SQL (IN lists, schema-dependent text). */
+    prepareUncached(sql: string): CanvasStatement;
+    /** Run one or more statements with no parameters (no `?` translation). */
+    exec(sql: string): Promise<void>;
+    /** True when the calling async context is inside a `withCanvasWrite` body (its own open transaction). */
+    readonly inTransaction: boolean;
+}
+export declare function canvasPoolSize(env?: Record<string, string | undefined>): number;
+/** The URL of the database for the current `CRTR_HOME`. In a test it creates the home's database on first use. */
+export declare function canvasDatabaseUrl(): Promise<string>;
+/** Open (or reuse) the canvas db handle for the current `CRTR_HOME`. Keyed by database URL, so tests with distinct
+ *  homes get independent handles. The first open applies the schema. */
+export declare function openDb(): Promise<CanvasDb>;
+/** Close and forget the connection for the current home. Mainly for tests. */
+export declare function closeDb(): Promise<void>;
+/** Close every connection this process holds (daemon shutdown). */
+export declare function closeAllDbs(): Promise<void>;
+/** Run `hook` once the calling context's outermost transaction has committed (and returned its connection to the pool); drop it if
+ *  the transaction or the savepoint holding it rolls back. Outside a transaction it runs in the next microtask. Use it for anything
+ *  that tells another context about a write, so that context never reads uncommitted rows or hears of a rolled-back one. */
+export declare function afterCommit(hook: () => void): void;
+export interface CanvasWriteOptions {
+    /** When nested, run the body in a SAVEPOINT so a throw undoes only its own writes and the outer transaction continues. */
+    savepoint?: boolean;
+    /** Always undo the body's writes, even when it returns (a dry run). Nested, it runs in a SAVEPOINT rolled back at the end. */
+    rollback?: boolean;
+}
+/** Run `body` in one transaction on its own pooled connection, the only transaction entry point for the canvas database.
+ *  A call from inside the body's own async context joins it and only the outermost call commits. A call from any other
+ *  context opens a separate transaction that runs concurrently (READ COMMITTED): a read-modify-write that must not lose an
+ *  update takes its row with `SELECT … FOR UPDATE` or writes conditionally. A throwing body rolls back (with `savepoint`, a
+ *  nested body rolls back only its own writes). With `rollback` the body's writes are always undone.
+ *
+ *  The body holds its connection until it returns: keep network, subprocess and filesystem waits out of it.
+ *
+ *  Postgres aborts the whole transaction when a statement fails, so a body that catches a failed statement and
+ *  carries on must run that statement inside a nested `withCanvasWrite(…, { savepoint: true })`. */
+export declare function withCanvasWrite<T>(body: (db: CanvasDb) => Promise<T> | T, options?: CanvasWriteOptions): Promise<T>;

package/dist/core/canvas/db.js

@@ -0,0 +1,426 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomBytes } from 'node:crypto';
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import pg from 'pg';
+import { resolveDatabaseUrl } from '../../daemon/postgres/supervisor.js';
+import { publishFileExclusive } from '../fs-utils.js';
+import { initializeEmptyLayout, runtimeRoot } from '../layout.js';
+import { translatePlaceholders, translateOnce } from '../statements.js';
+import { ensureHome } from './paths.js';
+import { emitEvent } from '../events/emit.js';
+import { ensureSchema } from './schema-chain.js';
+import { canvasDatabaseSchema, canvasSchemaDatabaseUrl, canvasSearchPathOptions } from './schema-version.js';
+// ---------------------------------------------------------------------------
+// The canvas database: one `pg.Pool` per database URL. There is no global write lock.
+//
+// A standalone statement takes a pooled connection for itself. `withCanvasWrite` takes one pooled connection for the
+// whole transaction, so two transactions in different async contexts run concurrently on different connections and
+// Postgres arbitrates them (row locks, conditional updates, `FOR UPDATE`, unique indexes) — also across processes.
+//
+// `CanvasDb` is the Promise-returning handle every canvas-db caller uses. The transaction a context opened is recorded
+// in AsyncLocalStorage: a nested `withCanvasWrite` or a statement from inside that context joins it (same connection,
+// so a read sees the transaction's own writes), while any other context gets its own connection and sees only
+// committed rows. Before any query is served the schema chain has run once on one direct connection.
+// Design: [[design-fleet]] D10; the single-connection predecessor is [[design-postgres-swap]].
+/** Which database `openDb()` reaches:
+ *  - production: `CRTR_DATABASE_URL`, else the supervised cluster's socket for this runtime root;
+ *  - tests: `CRTR_TEST_PG_URL` names a server holding the database `crtr_test_template`; each `CRTR_HOME` gets its own
+ *    database cloned from it, recorded in `<runtime root>/test-db`. With the variable unset in a `node --test` process
+ *    `openDb()` throws rather than reach a real database. */
+const TEST_TEMPLATE_DATABASE = 'crtr_test_template';
+/** Thrown for a unique-constraint violation (SQLSTATE 23505). `constraint` is the violated constraint or unique index. */
+export class CanvasConstraintError extends Error {
+    constraint;
+    code = '23505';
+    constructor(message, constraint, options) {
+        super(message, options);
+        this.name = 'CanvasConstraintError';
+        this.constraint = constraint;
+    }
+}
+// Open-ledger instrumentation
+//
+// When `CRTR_DB_OPEN_LEDGER=<path>` is set, every *fresh* connection (not a cache hit) appends one line recording the
+// opening process's identity and the database URL. This is corroborating runtime evidence for the
+// crtrd-sole-state-owner guarantee: the C-4 §11 scenario runner sets the env for daemon + CLI and asserts the ledger
+// contains ONLY the crtrd process — zero opens attributed to a `crtr`/`bin/crtr` CLI process.
+//
+// Line format (space-separated, one per open):  <iso-timestamp> <pid> <argv1> <database url, password removed>
+//
+// A dumb append — no locking, no dedup. Zero behavior change when the env is unset; a failing append is swallowed so
+// instrumentation never breaks an open.
+function recordOpenLedger(url) {
+    const ledger = process.env['CRTR_DB_OPEN_LEDGER'];
+    if (!ledger)
+        return;
+    try {
+        const line = `${new Date().toISOString()} ${process.pid} ${process.argv[1] ?? '<unknown>'} ${url.replace(/\/\/([^:@/]*):[^@/]*@/, '//$1@')}\n`;
+        appendFileSync(ledger, line);
+    }
+    catch {
+        /* instrumentation only — never let a ledger write break a db open */
+    }
+}
+/** Connections one process's pool may hold per database URL. Each process also holds one listen connection
+ *  (`crtr-signal-<pid>`), and the schema chain opens one more, briefly, at the first open.
+ *
+ *  - Supervised cluster (a Mac): `max_connections=20`, 3 reserved for superusers, so 17 are usable. During a daemon
+ *    handover the old and the new daemon are both up for a while, and `psql`, the importer and a CLI `sys db` command also
+ *    connect: 6 per process (plus the listener) keeps two overlapping daemons at 14 of 17 even if both pools are full,
+ *    and idle connections close after 10 s. Six is far above the one writer + four readers it replaces for concurrency.
+ *  - An external Postgres (`CRTR_DATABASE_URL`, the cloud's single-AZ RDS `db.t4g.medium`, no proxy): its default
+ *    `max_connections` is about 400 (4 GiB of memory / 9.5 MB), the directory shares the database, and the control plane runs several
+ *    processes (api and reconcile roles, rolling deploys overlapping two generations). 12 per process (plus the listener)
+ *    keeps ten processes at 130 connections, about a third of the server.
+ *  `CRTR_DATABASE_POOL_MAX` overrides either default; the floor is 2 because a body that runs a statement outside its own
+ *  async context needs a second connection while it holds the first. */
+const SUPERVISED_POOL_SIZE = 6;
+const EXTERNAL_POOL_SIZE = 12;
+const MIN_POOL_SIZE = 2;
+export function canvasPoolSize(env = process.env) {
+    const configured = env['CRTR_DATABASE_POOL_MAX']?.trim();
+    if (configured) {
+        const parsed = Number(configured);
+        if (!Number.isInteger(parsed) || parsed < MIN_POOL_SIZE)
+            throw new Error(`CRTR_DATABASE_POOL_MAX must be an integer of at least ${MIN_POOL_SIZE}; got ${JSON.stringify(configured)}`);
+        return parsed;
+    }
+    return env['CRTR_DATABASE_URL'] ? EXTERNAL_POOL_SIZE : SUPERVISED_POOL_SIZE;
+}
+/** How long a statement or transaction waits for a free pooled connection (or for a new one to open) before it fails.
+ *  Long, because a transaction body that awaits something slow holds its connection; the error names the pool so a
+ *  starved pool reads as that, not as a hung query. */
+const POOL_WAIT_MS = 30_000;
+/** A write transaction spends more than this outside db statements only when its body does non-db work. */
+const SLOW_TRANSACTION_MS = 1000;
+const transactionContext = new AsyncLocalStorage();
+// json/jsonb come back as their JSON text so readers that `JSON.parse` keep working; int8 and numeric (a SUM or AVG of
+// int8) come back as numbers — every bigint here is a counter or epoch-ms, far below 2^53.
+const JSON_OIDS = new Set([114, 3802]);
+const typeParsers = {
+    getTypeParser: ((oid, format) => {
+        if (JSON_OIDS.has(oid))
+            return (value) => value;
+        if (oid === 20 || oid === 1700) {
+            return (value) => {
+                const parsed = Number(value);
+                if (oid === 20 && !Number.isSafeInteger(parsed))
+                    throw new Error(`canvas db: bigint ${value} does not fit a JS number`);
+                return parsed;
+            };
+        }
+        return pg.types.getTypeParser(oid, format);
+    }),
+};
+/** Everything about one database URL: its pool and statement wrapper. */
+class Handle {
+    url;
+    db;
+    pool = null;
+    schema = null;
+    constructor(url) {
+        this.url = url;
+        const handle = this;
+        this.db = {
+            prepare: sql => this.statement(sql, true),
+            prepareUncached: sql => this.statement(sql, false),
+            exec: sql => this.run({ text: sql }).then(() => undefined),
+            get inTransaction() { return ownsTransaction(handle); },
+        };
+    }
+    /** Resolves once the schema chain has run for this URL (once per handle; a failure is retried by the next open). */
+    ready() {
+        this.schema ??= applySchema(this.url).catch(error => { this.schema = null; throw error; });
+        return this.schema;
+    }
+    connections() {
+        if (this.pool !== null)
+            return this.pool;
+        const pool = new pg.Pool({
+            connectionString: this.url, types: typeParsers, application_name: `crtr-${process.pid}`, connectionTimeoutMillis: POOL_WAIT_MS,
+            options: canvasSearchPathOptions(), max: canvasPoolSize(), idleTimeoutMillis: 10_000, allowExitOnIdle: true,
+        });
+        pool.on('connect', () => recordOpenLedger(this.url));
+        // An idle connection that drops is discarded by the pool; the next statement opens another.
+        pool.on('error', error => console.warn(`[canvas db] pooled connection error: ${error.message}`));
+        return this.pool = pool;
+    }
+    /** The connection of the pool for one transaction. The caller releases it. */
+    async checkout() {
+        try {
+            return await this.connections().connect();
+        }
+        catch (error) {
+            throw this.mapError(error);
+        }
+    }
+    /** Run one statement: on this context's own transaction connection when it has one, else on a pooled connection of its own. */
+    async run(config) {
+        const transaction = transactionContext.getStore();
+        try {
+            if (transaction !== undefined && transaction.open && transaction.handle === this) {
+                const began = performance.now();
+                try {
+                    return await transaction.client.query(config);
+                }
+                finally {
+                    transaction.statementMs += performance.now() - began;
+                }
+            }
+            return await this.connections().query(config);
+        }
+        catch (error) {
+            throw this.mapError(error);
+        }
+    }
+    mapError(error) {
+        const e = error;
+        if (e.code === '23505')
+            return new CanvasConstraintError(e.message ?? 'unique constraint violation', e.constraint, { cause: error });
+        if (/timeout exceeded when trying to connect/i.test(e.message ?? '')) {
+            return new Error(`canvas db: no pooled connection became free within ${POOL_WAIT_MS} ms (pool of ${canvasPoolSize()}); a transaction body is holding connections across a slow await`, { cause: error });
+        }
+        return error;
+    }
+    statement(sql, named) {
+        const config = named
+            ? (() => { const t = translatePlaceholders(sql); return { text: t.text, name: t.name }; })()
+            : (() => ({ text: translateOnce(sql).text }))();
+        const query = (params) => this.run({ ...config, values: params.map(bindable) });
+        return {
+            get: async (...params) => (await query(params)).rows[0],
+            all: async (...params) => (await query(params)).rows,
+            run: async (...params) => ({ changes: (await query(params)).rowCount ?? 0 }),
+        };
+    }
+    /** End the pool. Resolves once every checked-out connection (an open transaction) has been returned. */
+    async close() {
+        const pool = this.pool;
+        this.pool = null;
+        await pool?.end().catch(() => { });
+    }
+}
+/** pg sends Buffers as bytea; other typed-array views are copied into one. */
+function bindable(value) {
+    if (ArrayBuffer.isView(value) && !Buffer.isBuffer(value))
+        return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    return value;
+}
+function ownsTransaction(handle) {
+    const owned = transactionContext.getStore();
+    return owned !== undefined && owned.open && owned.handle === handle;
+}
+// ---------------------------------------------------------------------------
+// Schema
+/** Bring the database to this build's schema, in the Postgres schema `CRTR_DATABASE_SCHEMA` names, on one direct
+ *  connection that is not part of the pool: the chain's advisory lock needs one session, and `CRTR_SCHEMA_DATABASE_URL` (set
+ *  where the pool's URL goes through a pooler) names the direct endpoint. Unset, the pool's own URL is used. The pool's
+ *  connections carry the same schema as their search_path (`canvasSearchPathOptions`), so they read what the chain built. */
+async function applySchema(poolUrl) {
+    const emit = (level, event, fields) => { emitEvent({ level, event, fields }); };
+    const schema = canvasDatabaseSchema();
+    const schemaUrl = canvasSchemaDatabaseUrl();
+    const url = schemaUrl ?? poolUrl;
+    recordOpenLedger(url);
+    const direct = new pg.Client({
+        connectionString: url, application_name: `crtr-schema-${process.pid}`, connectionTimeoutMillis: 10_000,
+        ...(schemaUrl === undefined ? { options: canvasSearchPathOptions() } : {}),
+    });
+    // A server termination also emits 'error' on the client; the pending query's rejection already carries it, so this
+    // listener only keeps the event from crashing the process.
+    direct.on('error', () => { });
+    await direct.connect();
+    try {
+        await ensureSchema(direct, { schema, emit });
+    }
+    finally {
+        await direct.end().catch(() => { });
+    }
+}
+// ---------------------------------------------------------------------------
+// Which database, and the handle cache
+function runningUnderNodeTest() {
+    return process.env['NODE_TEST_CONTEXT'] !== undefined || process.execArgv.includes('--test');
+}
+/** `url` with its database name replaced. Not `new URL`: the supervisor's socket URL has an empty host, which WHATWG URL rejects. */
+function withDatabase(url, database) {
+    const match = /^(postgres(?:ql)?:\/\/[^/?#]*)(\/[^?#]*)?(.*)$/s.exec(url);
+    if (match === null)
+        throw new Error(`not a postgres URL: ${url.replace(/\/\/[^@/]*@/, '//')}`);
+    return `${match[1]}/${database}${match[3]}`;
+}
+/** The test database for the current `CRTR_HOME`: the name recorded in `<runtime root>/test-db`, else a fresh clone of
+ *  `crtr_test_template`, so a home switch or a recreated home gets its own database and a subprocess that inherits
+ *  `CRTR_HOME` reaches the same one. */
+async function testDatabaseUrl(server) {
+    const record = join(runtimeRoot(), 'test-db');
+    const recorded = () => {
+        try {
+            return readFileSync(record, 'utf8').trim() || undefined;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+    };
+    const existing = recorded();
+    if (existing !== undefined)
+        return withDatabase(server, existing);
+    mkdirSync(runtimeRoot(), { recursive: true });
+    const name = `t_${randomBytes(8).toString('hex')}`;
+    const admin = new pg.Client({ connectionString: withDatabase(server, 'postgres') });
+    admin.on('error', () => { }); // as in applySchema: the query's rejection carries the error
+    await admin.connect();
+    try {
+        await admin.query(`CREATE DATABASE ${name} TEMPLATE ${TEST_TEMPLATE_DATABASE} STRATEGY file_copy`);
+        if (!publishFileExclusive(record, `${name}\n`, 0o600)) {
+            // Another process of this home won the race; use its database and discard ours.
+            await admin.query(`DROP DATABASE ${name}`);
+            return withDatabase(server, recorded());
+        }
+    }
+    finally {
+        await admin.end();
+    }
+    return withDatabase(server, name);
+}
+/** The URL of the database for the current `CRTR_HOME`. In a test it creates the home's database on first use. */
+export async function canvasDatabaseUrl() {
+    const testServer = process.env['CRTR_TEST_PG_URL'];
+    if (testServer)
+        return testDatabaseUrl(testServer);
+    if (runningUnderNodeTest()) {
+        throw new Error('CRTR_TEST_PG_URL is not set: a test must reach its own Postgres (run the suite through the lane runner); refusing to open a real canvas database');
+    }
+    return resolveDatabaseUrl(runtimeRoot());
+}
+const handles = new Map();
+/** The URL each `CRTR_HOME` last opened, so `closeDb` finds the handle even after the home directory is gone. */
+const urlByRoot = new Map();
+async function openHandle() {
+    initializeEmptyLayout();
+    ensureHome();
+    const url = await canvasDatabaseUrl();
+    urlByRoot.set(runtimeRoot(), url);
+    let handle = handles.get(url);
+    if (handle === undefined)
+        handles.set(url, handle = new Handle(url));
+    await handle.ready();
+    return handle;
+}
+/** Open (or reuse) the canvas db handle for the current `CRTR_HOME`. Keyed by database URL, so tests with distinct
+ *  homes get independent handles. The first open applies the schema. */
+export async function openDb() {
+    return (await openHandle()).db;
+}
+/** Close and forget the connection for the current home. Mainly for tests. */
+export async function closeDb() {
+    const url = urlByRoot.get(runtimeRoot());
+    if (url === undefined)
+        return;
+    urlByRoot.delete(runtimeRoot());
+    const handle = handles.get(url);
+    if (handle === undefined)
+        return;
+    handles.delete(url);
+    await handle.close();
+}
+/** Close every connection this process holds (daemon shutdown). */
+export async function closeAllDbs() {
+    const open = [...handles.values()];
+    handles.clear();
+    urlByRoot.clear();
+    await Promise.all(open.map(handle => handle.close()));
+}
+/** Run `hook` once the calling context's outermost transaction has committed (and returned its connection to the pool); drop it if
+ *  the transaction or the savepoint holding it rolls back. Outside a transaction it runs in the next microtask. Use it for anything
+ *  that tells another context about a write, so that context never reads uncommitted rows or hears of a rolled-back one. */
+export function afterCommit(hook) {
+    const transaction = transactionContext.getStore();
+    if (transaction === undefined || !transaction.open) {
+        queueMicrotask(hook);
+        return;
+    }
+    transaction.afterCommit.push(hook);
+}
+let savepoints = 0;
+/** Run `body` in one transaction on its own pooled connection, the only transaction entry point for the canvas database.
+ *  A call from inside the body's own async context joins it and only the outermost call commits. A call from any other
+ *  context opens a separate transaction that runs concurrently (READ COMMITTED): a read-modify-write that must not lose an
+ *  update takes its row with `SELECT … FOR UPDATE` or writes conditionally. A throwing body rolls back (with `savepoint`, a
+ *  nested body rolls back only its own writes). With `rollback` the body's writes are always undone.
+ *
+ *  The body holds its connection until it returns: keep network, subprocess and filesystem waits out of it.
+ *
+ *  Postgres aborts the whole transaction when a statement fails, so a body that catches a failed statement and
+ *  carries on must run that statement inside a nested `withCanvasWrite(…, { savepoint: true })`. */
+export async function withCanvasWrite(body, options = {}) {
+    const handle = await openHandle();
+    const canvas = handle.db;
+    if (ownsTransaction(handle)) {
+        if (!options.savepoint && !options.rollback)
+            return body(canvas);
+        const open = transactionContext.getStore();
+        const name = `canvas_write_${++savepoints}`;
+        await handle.run({ text: `SAVEPOINT ${name}` });
+        const hooks = open.afterCommit;
+        const hooksBefore = hooks.length;
+        let result;
+        try {
+            result = await body(canvas);
+        }
+        catch (err) {
+            await handle.run({ text: `ROLLBACK TO ${name}; RELEASE ${name}` });
+            hooks.splice(hooksBefore);
+            throw err;
+        }
+        await handle.run({ text: options.rollback ? `ROLLBACK TO ${name}; RELEASE ${name}` : `RELEASE ${name}` });
+        if (options.rollback)
+            hooks.splice(hooksBefore);
+        return result;
+    }
+    const entry = new Error('canvas write transaction entered here');
+    const client = await handle.checkout();
+    // The pool removes its own 'error' listener while a connection is checked out. A server error or a dropped socket that
+    // arrives between statements (a body awaiting non-database work) has no active query to fail, so without a listener of
+    // ours it is an unhandled 'error' event and kills the process. Record it: the client is no longer queryable, so the
+    // body's next statement or the COMMIT rejects, and the connection is released as broken.
+    let broken;
+    const onConnectionError = (error) => { broken ??= error; };
+    client.on('error', onConnectionError);
+    const started = performance.now();
+    let committed = false;
+    const transaction = { handle, client, open: true, afterCommit: [], statementMs: 0 };
+    try {
+        await client.query('BEGIN');
+        try {
+            const result = await transactionContext.run(transaction, () => body(canvas));
+            await client.query(options.rollback ? 'ROLLBACK' : 'COMMIT');
+            committed = !options.rollback;
+            return result;
+        }
+        catch (err) {
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch (rollbackError) {
+                broken ??= rollbackError; /* the connection is gone: the pool must not reuse it */
+            }
+            throw handle.mapError(err);
+        }
+    }
+    finally {
+        transaction.open = false;
+        const held = performance.now() - started;
+        if (held - transaction.statementMs > SLOW_TRANSACTION_MS) {
+            console.warn(`[canvas db] write transaction held its connection ${Math.round(held)}ms (${Math.round(transaction.statementMs)}ms in its statements); its body did non-db work while holding a pooled connection and its row locks\n${entry.stack}`);
+        }
+        client.removeListener('error', onConnectionError);
+        client.release(broken);
+        if (committed)
+            for (const hook of transaction.afterCommit)
+                queueMicrotask(hook);
+    }
+}