@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/adapters/postgresPooler.d.ts

@@ -0,0 +1,28 @@
+import type { PgQuery } from './postgresPool.js';
+export interface TransactionScopedClient extends PgQuery {
+    /** Invalidate future SQL without waiting for the current driver operation.
+     * The lease owner destroys that operation's physical client separately. */
+    close(reason: Error): void;
+    /** Close a transaction the lease's work left open, rather than hand the
+     * pooler a server connection mid-transaction. */
+    settle(): Promise<void>;
+}
+/**
+ * The statement past its leading space and comments. PostgreSQL nests block
+ * comments, so this does too: a misread edge here is a transaction left open
+ * on a pooled server connection, not a cosmetic slip.
+ */
+export declare function statementHead(text: string): string;
+export declare function transactionScoped(client: PgQuery, options: Readonly<{
+    role: 'read' | 'write';
+    capMs: number;
+    untrusted: boolean;
+    /** A writer's lock wait (writeLanes.ts). */
+    lockTimeoutMs?: number;
+    /** The path a store's unqualified names resolve on (the authentication
+     * store's, for Better Auth), set per transaction for the same reason. */
+    searchPath?: string;
+    /** The client sends each query as it is asked (node-postgres's `pipeline`):
+     * a statement's own transaction is then sent with it, not around it. */
+    pipelines?: boolean;
+}>): TransactionScopedClient;

package/dist/adapters/postgresPooler.js

@@ -0,0 +1,267 @@
+/**
+ * A leased PostgreSQL client made safe behind a transaction-mode pooler:
+ * PgBouncer with `pool_mode = transaction`, or RDS Proxy, which multiplexes
+ * the same way until a session setting pins a connection.
+ *
+ * Such a pooler lends a server connection for one transaction and gives it to
+ * another client for the next. A setting made on the session therefore does
+ * not follow this client to its next transaction, and does follow the server
+ * connection to the pooler's next client. The direct path's per-connection
+ * defaults — `default_transaction_read_only` on every reader, a
+ * `statement_timeout` everywhere — are made per transaction here, with
+ * `SET LOCAL`, which dies with its transaction:
+ *
+ * - A transaction a caller begins gets the cap, and on a reader
+ *   `SET TRANSACTION READ ONLY`, in the same round trip as its BEGIN.
+ * - A statement sent outside a transaction is wrapped in one of its own:
+ *   BEGIN with the settings, the statement, COMMIT. A bare statement is
+ *   exactly what a pooler may run on any server connection. On a client that
+ *   pipelines, the three leave together: one round trip, not three, and the
+ *   same statements in the same order on the same connection. The statement
+ *   cannot run outside them: the BEGIN and the settings are one simple query,
+ *   so a setting that fails leaves the transaction aborted, the statement
+ *   refused in it, and the COMMIT a ROLLBACK.
+ * - An untrusted lease — user-authored SQL — fences each statement with a
+ *   savepoint, and before its transaction ends runs the part of DISCARD ALL
+ *   a transaction block allows. An advisory lock or a prepared statement
+ *   survives ROLLBACK and a setting survives COMMIT; none of them may reach
+ *   the pooler's next client.
+ *
+ * Transaction edges are read off each statement's first keyword. That is
+ * sound here: every BEGIN, COMMIT and ROLLBACK this codebase sends is a
+ * literal of its own, and user-authored SQL is one statement at a time
+ * (the extended protocol, behind refuseStacked) on a lease that is discarded
+ * afterwards.
+ */
+import { trimStatement } from './adapter.js';
+/* The in-transaction half of DISCARD ALL, which itself refuses a transaction
+   block. Every part of it also runs inside a read-only transaction. */
+const RESET = 'SET SESSION AUTHORIZATION DEFAULT; RESET ALL; DEALLOCATE ALL; CLOSE ALL; UNLISTEN *; ' +
+    'SELECT pg_catalog.pg_advisory_unlock_all(); DISCARD PLANS; DISCARD SEQUENCES; DISCARD TEMP';
+const MARK = 'mistri_statement';
+const BEGINS = /^(?:BEGIN|START\s+TRANSACTION)\b/i;
+/** COMMIT, END, ABORT or ROLLBACK: not ROLLBACK TO a savepoint, and not the PREPARED forms. */
+const ENDS = /^(?:COMMIT|END|ABORT|ROLLBACK)\b(?!\s+(?:(?:WORK|TRANSACTION)\s+)?(?:TO|PREPARED)\b)/i;
+/** Neither wrapped nor fenced: statements that only mean something at a transaction's edge. */
+const EDGES = /^(?:SAVEPOINT|RELEASE|ROLLBACK\s+(?:(?:WORK|TRANSACTION)\s+)?TO|PREPARE\s+TRANSACTION|COMMIT\s+PREPARED|ROLLBACK\s+PREPARED)\b/i;
+/**
+ * The statement past its leading space and comments. PostgreSQL nests block
+ * comments, so this does too: a misread edge here is a transaction left open
+ * on a pooled server connection, not a cosmetic slip.
+ */
+export function statementHead(text) {
+    let i = 0;
+    while (i < text.length) {
+        if (/\s/.test(text[i])) {
+            i += 1;
+            continue;
+        }
+        if (text.startsWith('--', i)) {
+            const end = text.indexOf('\n', i);
+            if (end < 0)
+                return '';
+            i = end + 1;
+            continue;
+        }
+        if (text.startsWith('/*', i)) {
+            let depth = 0;
+            do {
+                if (text.startsWith('/*', i)) {
+                    depth += 1;
+                    i += 2;
+                }
+                else if (text.startsWith('*/', i)) {
+                    depth -= 1;
+                    i += 2;
+                }
+                else
+                    i += 1;
+            } while (depth > 0 && i < text.length);
+            continue;
+        }
+        break;
+    }
+    return text.slice(i);
+}
+export function transactionScoped(client, options) {
+    let closed;
+    const raw = (request, params) => {
+        if (closed)
+            return Promise.reject(closed);
+        return client.query(request, params);
+    };
+    const reader = options.role === 'read';
+    /* On a reader the transaction is read-only whatever its BEGIN said: the
+       session default that promised it on a direct connection is not here. */
+    const lockWait = !reader && options.lockTimeoutMs !== undefined ? `; SET LOCAL lock_timeout = ${Math.max(1, Math.floor(options.lockTimeoutMs))}` : '';
+    const path = options.searchPath === undefined ? '' : `; SET LOCAL search_path TO ${options.searchPath}`;
+    const settings = `${reader ? 'SET TRANSACTION READ ONLY; ' : ''}SET LOCAL statement_timeout = ${Math.max(1, Math.floor(options.capMs))}${lockWait}${path}`;
+    const settingCount = 1 + (reader ? 1 : 0) + (lockWait ? 1 : 0) + (path ? 1 : 0);
+    let open = false;
+    // A simple-protocol string with several statements answers with one result each.
+    const first = (result) => (Array.isArray(result) ? result[0] : result);
+    const simple = (request, params) => typeof request === 'string' && (params === undefined || (Array.isArray(params) && params.length === 0));
+    const begin = async (text, request, params) => {
+        /* Open from the moment the BEGIN is sent, not answered: a statement a
+           pipelining caller sends right behind it (pipelined,
+           postgresTransactionHandle.ts) belongs to this transaction, and must not
+           be wrapped in one of its own. */
+        open = true;
+        try {
+            let result;
+            if (simple(request, params)) {
+                /* A BEGIN may carry a prologue (a read snapshot's LOCK and first
+                   query, PostgresAdapter.readSnapshot). The settings go straight
+                   after the BEGIN, so the cap is in force before the prologue runs,
+                   and the settings' own results are taken out of the answer. The
+                   BEGIN is one of this codebase's literals, so its first `;` is
+                   where it ends. */
+                const statement = trimStatement(text), cut = statement.indexOf(';');
+                if (cut < 0)
+                    result = first(await raw(`${statement}; ${settings}`));
+                else {
+                    const answers = (await raw(`${statement.slice(0, cut)}; ${settings}; ${statement.slice(cut + 1).trimStart()}`));
+                    result = [answers[0], ...answers.slice(1 + settingCount)];
+                }
+            }
+            else {
+                /* Asked together, so the settings are in force before anything a
+                   pipelining caller sent behind the BEGIN. */
+                const answer = raw(request, params), set = raw(settings);
+                void set.catch(() => { });
+                result = await answer;
+                await set;
+            }
+            return result;
+        }
+        catch (error) {
+            open = false;
+            // BEGIN may have taken effect before a setting failed; if not, ROLLBACK costs a warning.
+            await raw('ROLLBACK').catch(() => { });
+            throw error;
+        }
+    };
+    const end = async (request, params) => {
+        open = false;
+        if (options.untrusted) {
+            try {
+                await raw(RESET);
+            }
+            catch (error) {
+                // A transaction that cannot shed what its statement left behind does not commit with it.
+                await raw('ROLLBACK').catch(() => { });
+                throw error;
+            }
+        }
+        return raw(request, params);
+    };
+    const within = async (request, params) => {
+        if (!options.untrusted)
+            return raw(request, params);
+        await raw(`SAVEPOINT ${MARK}`);
+        try {
+            return await raw(request, params);
+        }
+        catch (error) {
+            /* Back to before the statement, so the transaction can still shed what
+               the statement took before it failed: an advisory lock outlives both
+               the failure and a rollback. */
+            await raw(`ROLLBACK TO SAVEPOINT ${MARK}`).catch(() => { });
+            throw error;
+        }
+    };
+    /* BEGIN with the settings, the statement and COMMIT asked at once. Each is
+       answered on its own (a pipelining client syncs every query), so a failed
+       statement leaves the transaction aborted and the COMMIT behind it ends it
+       as a ROLLBACK: nothing is left open, and nothing commits. Trusted
+       statements only: an untrusted one is fenced by a savepoint it awaits. */
+    const together = async (request, params) => {
+        const opened = raw(`BEGIN${reader ? ' READ ONLY' : ''}; ${settings}`), answer = raw(request, params), ended = raw('COMMIT');
+        for (const pending of [opened, answer, ended])
+            void pending.catch(() => { });
+        try {
+            await opened;
+        }
+        catch (error) {
+            await answer.catch(() => { });
+            await ended.catch(() => raw('ROLLBACK').catch(() => { }));
+            throw error;
+        }
+        let result;
+        try {
+            result = await answer;
+        }
+        catch (error) {
+            await ended.catch(() => raw('ROLLBACK').catch(() => { }));
+            throw error;
+        }
+        try {
+            await ended;
+        }
+        catch (error) {
+            await raw('ROLLBACK').catch(() => { });
+            throw error;
+        }
+        return result;
+    };
+    const alone = async (request, params) => {
+        if (options.pipelines && !options.untrusted)
+            return together(request, params);
+        try {
+            await raw(`BEGIN${reader ? ' READ ONLY' : ''}; ${settings}${options.untrusted ? `; SAVEPOINT ${MARK}` : ''}`);
+        }
+        catch (error) {
+            await raw('ROLLBACK').catch(() => { });
+            throw error;
+        }
+        let result;
+        try {
+            result = await raw(request, params);
+        }
+        catch (error) {
+            await raw(options.untrusted ? `ROLLBACK TO SAVEPOINT ${MARK}; ${RESET}; ROLLBACK` : 'ROLLBACK').catch(() => raw('ROLLBACK').catch(() => { }));
+            throw error;
+        }
+        try {
+            await raw(options.untrusted ? `${RESET}; COMMIT` : 'COMMIT');
+        }
+        catch (error) {
+            await raw('ROLLBACK').catch(() => { });
+            throw error;
+        }
+        return result;
+    };
+    const query = (request, params) => {
+        if (closed)
+            return Promise.reject(closed);
+        const text = typeof request === 'string'
+            ? request
+            : request && typeof request === 'object' && typeof request.text === 'string'
+                ? request.text
+                : undefined;
+        // Nothing to read an edge from: the driver says what is wrong with it.
+        if (text === undefined)
+            return raw(request, params);
+        const statement = statementHead(text);
+        if (BEGINS.test(statement))
+            return open ? raw(request, params) : begin(text, request, params);
+        if (ENDS.test(statement))
+            return open ? end(request, params) : raw(request, params);
+        if (EDGES.test(statement))
+            return raw(request, params);
+        return open ? within(request, params) : alone(request, params);
+    };
+    const settle = async () => {
+        if (!open)
+            return;
+        open = false;
+        await raw(options.untrusted ? `${RESET}; ROLLBACK` : 'ROLLBACK').catch(() => raw('ROLLBACK'));
+    };
+    return {
+        query: query,
+        settle,
+        close: (reason) => {
+            closed ??= reason;
+        },
+    };
+}

package/dist/adapters/postgresReadCatalog.d.ts

@@ -0,0 +1,31 @@
+/** Private native read-snapshot shape owner. Locks and native catalog identity
+ * are evidence of source shape, never caller authorization or an ACL fence.
+ * Only PostgresAdapter supplies the snapshot runner in production. */
+import { type SqlFragment, type QueryResult } from './adapter.js';
+import type { PostgresReadSnapshot } from './postgres.js';
+import type { DatabaseSchema } from '../shared/schema.js';
+export interface PostgresReadDependency {
+    readonly schema: string;
+    readonly name: string;
+}
+export interface PinnedPostgresRead {
+    readonly schema: DatabaseSchema;
+    assertCurrent(): void;
+    execute(statement: SqlFragment, hint?: {
+        binary?: true;
+    }): Promise<QueryResult>;
+}
+export interface PinnedPostgresReadOwner {
+    readonly schema: DatabaseSchema;
+    withSnapshot<T>(callback: (read: PinnedPostgresRead) => Promise<T>): Promise<T>;
+    /** Whether a snapshot has seen these tables differ from the baseline: then
+     * no later one will match, and an owner holding several may retire them all. */
+    drifted(): boolean;
+    retire(): Promise<void>;
+}
+type Runner = <T>(run: (snapshot: PostgresReadSnapshot) => Promise<T>) => Promise<T>;
+/** Adapter-only construction seam. Baseline is captured from that adapter's
+ * native transaction, not accepted as a caller-authored schema/hash. Callback
+ * code is trusted and must not await retirement of its own active operation. */
+export declare function createPinnedPostgresReadOwner(run: Runner, raw: readonly PostgresReadDependency[], assertCurrent: () => void): Promise<PinnedPostgresReadOwner>;
+export {};

package/dist/adapters/postgresReadCatalog.js

@@ -0,0 +1,226 @@
+/** Private native read-snapshot shape owner. Locks and native catalog identity
+ * are evidence of source shape, never caller authorization or an ACL fence.
+ * Only PostgresAdapter supplies the snapshot runner in production. */
+import { POSTGRES_STYLE, Refusal, TransactionOperations } from './adapter.js';
+import { snapshot } from './commands/canonicalJson.js';
+import { assertScopeCatalog, captureScopeCatalog } from '../shared/scopeCatalog.js';
+import { isProxy } from 'node:util/types';
+const refuse = () => {
+    throw new Refusal('The pinned PostgreSQL read snapshot is unavailable.');
+};
+const order = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const id = (value) => JSON.stringify([value.schema, value.name]);
+function dependencies(raw) {
+    const value = snapshot(raw, 65536).value;
+    if (!Array.isArray(value) || !value.length || value.length > 128)
+        return refuse();
+    const captured = value
+        .map((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item) || Object.keys(item).sort().join(',') !== 'name,schema')
+            return refuse();
+        const valid = (text) => typeof text === 'string' && text.length > 0 && Buffer.byteLength(text) <= 63 && !/[\p{Cc}\p{Cs}]/u.test(text);
+        if (!valid(item.schema) || !valid(item.name) || item.schema === 'information_schema' || item.schema.startsWith('pg_'))
+            return refuse();
+        return Object.freeze({ schema: item.schema, name: item.name });
+    })
+        .sort((a, b) => order(a.schema, b.schema) || order(a.name, b.name));
+    if (new Set(captured.map(id)).size !== captured.length)
+        return refuse();
+    return Object.freeze(captured);
+}
+const FACTS = `SELECT n.nspname AS schema, c.relname AS name, c.oid::text AS oid,
+  c.relkind::text AS kind, c.relpersistence::text AS persistence,
+  c.relispartition AS partition, c.relrowsecurity AS rls, c.relforcerowsecurity AS force,
+  EXISTS (SELECT 1 FROM pg_catalog.pg_inherits i WHERE i.inhrelid=c.oid OR i.inhparent=c.oid) AS inheritance,
+  EXISTS (SELECT 1 FROM pg_catalog.pg_rewrite r WHERE r.ev_class=c.oid) AS rules,
+  EXISTS (SELECT 1 FROM pg_catalog.pg_policy p WHERE p.polrelid=c.oid) AS policies,
+  COALESCE((SELECT json_agg(json_build_object('name', a.attname, 'number', a.attnum,
+    'typeOid', a.atttypid::text, 'type', t.typname, 'typeSchema', tn.nspname, 'typeKind', t.typtype,
+    'modifier', a.atttypmod, 'notnull', a.attnotnull, 'dropped', a.attisdropped,
+    'generated', a.attgenerated, 'identity', a.attidentity, 'collation', a.attcollation::text) ORDER BY a.attnum)
+    FROM pg_catalog.pg_attribute a LEFT JOIN pg_catalog.pg_type t ON t.oid=a.atttypid
+    LEFT JOIN pg_catalog.pg_namespace tn ON tn.oid=t.typnamespace
+    WHERE a.attrelid=c.oid AND a.attnum>0), '[]'::json) AS columns,
+  COALESCE((SELECT json_agg(json_build_object('oid', p.oid::text, 'index', p.conindid::text,
+    'keys', p.conkey, 'valid', i.indisvalid, 'ready', i.indisready, 'deferrable', p.condeferrable))
+    FROM pg_catalog.pg_constraint p JOIN pg_catalog.pg_index i ON i.indexrelid=p.conindid
+    WHERE p.conrelid=c.oid AND p.contype='p'), '[]'::json) AS primary
+ FROM unnest($1::text[], $2::text[]) AS w(schema, name)
+ JOIN pg_catalog.pg_namespace n ON n.nspname=w.schema
+ JOIN pg_catalog.pg_class c ON c.relnamespace=n.oid AND c.relname=w.name
+ ORDER BY n.nspname COLLATE "C", c.relname COLLATE "C"`;
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : refuse();
+const oid = (value) => typeof value === 'string' && /^[1-9][0-9]{0,9}(?![\s\S])/.test(value) && BigInt(value) <= 4294967295n;
+const TYPES = new Set(['int2', 'int4', 'int8', 'float4', 'float8', 'text', 'varchar', 'bpchar', 'bool', 'date']);
+async function capture(lease, wanted, current) {
+    if (typeof lease.assertCurrent !== 'function')
+        return refuse();
+    const ownerCurrent = current;
+    current = () => {
+        ownerCurrent();
+        lease.assertCurrent();
+    };
+    current();
+    await lease.client.query(`LOCK TABLE ${wanted.map((at) => `ONLY ${POSTGRES_STYLE.quote(at.schema)}.${POSTGRES_STYLE.quote(at.name)}`).join(', ')} IN ACCESS SHARE MODE`);
+    current();
+    const rows = snapshot((await lease.client.query(FACTS, [wanted.map((at) => at.schema), wanted.map((at) => at.name)])).rows, 1048576).value;
+    current();
+    if (!Array.isArray(rows) || rows.length !== wanted.length)
+        return refuse();
+    const seen = new Set();
+    for (const value of rows) {
+        const row = record(value), key = JSON.stringify([row.schema, row.name]);
+        if (!wanted.some((at) => id(at) === key) ||
+            seen.has(key) ||
+            !oid(row.oid) ||
+            row.kind !== 'r' ||
+            row.persistence !== 'p' ||
+            ['partition', 'rls', 'force', 'inheritance', 'rules', 'policies'].some((field) => row[field] !== false) ||
+            !Array.isArray(row.columns) ||
+            !row.columns.length ||
+            !Array.isArray(row.primary) ||
+            row.primary.length !== 1)
+            return refuse();
+        seen.add(key);
+        const numbers = new Set(), names = new Set();
+        for (const value of row.columns) {
+            const column = record(value);
+            if (typeof column.name !== 'string' ||
+                !column.name ||
+                names.has(column.name) ||
+                !Number.isSafeInteger(column.number) ||
+                Number(column.number) < 1 ||
+                numbers.has(Number(column.number)) ||
+                !oid(column.typeOid) ||
+                column.typeSchema !== 'pg_catalog' ||
+                column.typeKind !== 'b' ||
+                typeof column.type !== 'string' ||
+                !TYPES.has(column.type) ||
+                column.dropped !== false ||
+                // A generated column ('s' stored, 'v' virtual) is read like any other: the database computes it from the row.
+                !['', 's', 'v'].includes(String(column.generated)) ||
+                !['', 'a', 'd'].includes(String(column.identity)) ||
+                !Number.isSafeInteger(column.modifier) ||
+                typeof column.notnull !== 'boolean' ||
+                typeof column.collation !== 'string' ||
+                !/^(?:0|[1-9][0-9]{0,9})(?![\s\S])/.test(column.collation))
+                return refuse();
+            names.add(column.name);
+            numbers.add(Number(column.number));
+        }
+        const columns = row.columns;
+        const primary = record(row.primary[0]);
+        if (!oid(primary.oid) ||
+            !oid(primary.index) ||
+            primary.valid !== true ||
+            primary.ready !== true ||
+            primary.deferrable !== false ||
+            !Array.isArray(primary.keys) ||
+            !primary.keys.length ||
+            new Set(primary.keys).size !== primary.keys.length ||
+            primary.keys.some((key) => typeof key !== 'number' ||
+                !numbers.has(key) ||
+                !columns.some((value) => record(value).number === key && record(value).notnull === true)))
+            return refuse();
+    }
+    const described = await lease.describe();
+    current();
+    const selected = described.tables.filter((table) => wanted.some((at) => at.schema === table.schema && at.name === table.name));
+    if (described.dialect !== 'postgres' || selected.length !== wanted.length)
+        return refuse();
+    const selectedIds = new Set(selected.map((table) => table.id));
+    if (described.foreignKeys.some((fk) => selectedIds.has(fk.from.table) && !selectedIds.has(fk.to.table)))
+        return refuse();
+    const schema = captureScopeCatalog({
+        ...described,
+        label: 'Pinned PostgreSQL read',
+        readAt: '',
+        tables: selected,
+        foreignKeys: described.foreignKeys.filter((fk) => selectedIds.has(fk.from.table) && selectedIds.has(fk.to.table)),
+    });
+    return { facts: snapshot(rows, 1048576).json, schema };
+}
+/** Adapter-only construction seam. Baseline is captured from that adapter's
+ * native transaction, not accepted as a caller-authored schema/hash. Callback
+ * code is trusted and must not await retirement of its own active operation. */
+export async function createPinnedPostgresReadOwner(run, raw, assertCurrent) {
+    if (typeof run !== 'function' || isProxy(run) || typeof assertCurrent !== 'function' || isProxy(assertCurrent))
+        return refuse();
+    const wanted = dependencies(raw), pending = new Set();
+    let retired = false, drift = false;
+    const current = () => {
+        if (retired)
+            return refuse();
+        assertCurrent();
+        if (retired)
+            return refuse();
+    };
+    current();
+    const baseline = await run((lease) => capture(lease, wanted, current));
+    current();
+    return Object.freeze({
+        schema: baseline.schema,
+        withSnapshot: (callback) => {
+            const work = Promise.resolve().then(async () => {
+                current();
+                if (typeof callback !== 'function' || isProxy(callback))
+                    return refuse();
+                const result = await run(async (lease) => {
+                    current();
+                    const observed = await capture(lease, wanted, current);
+                    current();
+                    try {
+                        if (observed.facts !== baseline.facts)
+                            return refuse();
+                        assertScopeCatalog(baseline.schema, observed.schema);
+                    }
+                    catch (error) {
+                        drift = true;
+                        throw error;
+                    }
+                    let active = true;
+                    const operations = new TransactionOperations();
+                    const held = () => {
+                        current();
+                        if (!active || !lease.assertCurrent)
+                            return refuse();
+                        lease.assertCurrent();
+                    };
+                    try {
+                        const output = await callback(Object.freeze({
+                            schema: baseline.schema,
+                            assertCurrent: held,
+                            execute: (statement, hint) => {
+                                const captured = snapshot(statement, 1048576).value;
+                                return operations.run(async () => {
+                                    held();
+                                    const result = await lease.execute(captured, hint?.binary ? { binary: true } : undefined);
+                                    held();
+                                    return result;
+                                });
+                            },
+                        }));
+                        held();
+                        await operations.finish();
+                        held();
+                        return output;
+                    }
+                    finally {
+                        active = false;
+                        await operations.finish();
+                    }
+                });
+                current();
+                return result;
+            });
+            pending.add(work);
+            void work.then(() => pending.delete(work), () => pending.delete(work));
+            return work;
+        },
+        drifted: () => drift,
+        retire: async () => {
+            retired = true;
+            await Promise.allSettled([...pending]);
+        },
+    });
+}

package/dist/adapters/postgresReadSnapshot.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The read snapshot a trusted owner is lent (postgres.ts `readSnapshot`): one `REPEATABLE READ, READ ONLY` transaction
+ * on a leased reader, with its prologue sent in the BEGIN's own message, an `ahead` form whose first statements leave
+ * behind the BEGIN, a `whole` form that is a single round trip, and the `finish` that commits it and reads a fence in a
+ * fresh snapshot. Apart from the adapter because it needs nothing of it but the reader pool and its introspection.
+ */
+import { type QueryResult, type SqlFragment } from './adapter.js';
+import { type PgConnectionManager, type PgQuery, type PgResult } from './postgresPool.js';
+import type { DatabaseSchema } from '../shared/schema.js';
+/** What a trusted read-snapshot owner is lent: the leased reader inside its
+ * transaction, the adapter's own introspection on it, and scoped-read
+ * execution on it with the adapter's value mapping. Never retained. */
+export interface PostgresReadSnapshot {
+    readonly client: PgQuery;
+    /** The results of the owner's prologue, in order, when it passed one. */
+    readonly prologue?: readonly PgResult<Record<string, unknown>>[];
+    /**
+     * For an owner that asked `ahead`: the same results, still on their way.
+     * The owner is handed the snapshot as soon as its BEGIN is sent, so what it
+     * asks next leaves right behind it on a reader that pipelines; it must
+     * await this, and stand on what it says, before it relies on anything it
+     * read. A BEGIN that failed rejects it, and fails every statement behind.
+     */
+    readonly opened?: Promise<readonly PgResult<Record<string, unknown>>[]>;
+    /** Present only for observed checkouts; native local lifetime, not a grant. */
+    assertCurrent?(): void;
+    /**
+     * Commit this snapshot and read `next` — parameter-free statements — in a
+     * fresh snapshot of its own, committed too, all in the one message: the
+     * COMMIT and a question that must see what committed after this snapshot
+     * began (a release fence) in one round trip where they were three. Its
+     * answers are `next`'s, in order. Nothing is asked on the snapshot once it
+     * is called. Absent from a whole snapshot and an observed checkout.
+     */
+    finish?(next: string): Promise<readonly PgResult<Record<string, unknown>>[]>;
+    describe(): Promise<DatabaseSchema>;
+    /** A file's read keeps its bytes (`hint.binary`); every other read gets the `<n bytes>` label. */
+    execute(statement: SqlFragment, hint?: {
+        binary?: true;
+    }): Promise<QueryResult>;
+}
+/**
+ * Run `run` in a snapshot on `connections`' reader. `describe` is the adapter's own introspection on the leased
+ * client; `onCheckout` says it is a pinned owner's, whose introspection is the class's and not an instance's.
+ */
+export declare function readSnapshotOn<T>(connections: PgConnectionManager, describe: (db: PgQuery, checkout: boolean) => Promise<DatabaseSchema>, run: (snapshot: PostgresReadSnapshot) => Promise<T>, observeCheckout: boolean, prologue: string | undefined, ahead: boolean, whole: boolean): Promise<T>;