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

package/dist/adapters/postgresReadSnapshot.js

@@ -0,0 +1,133 @@
+/**
+ * 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 { Refusal, TransactionOutcomeUnknown } from './adapter.js';
+import { pipelinesAs } from './postgresPool.js';
+import { toJsonSafe, withBytes } from './postgresValues.js';
+const BEGIN_SNAPSHOT = 'BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY';
+/**
+ * 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 async function readSnapshotOn(connections, describe, run, observeCheckout, prologue, ahead, whole) {
+    if (typeof run !== 'function' ||
+        (prologue !== undefined && (typeof prologue !== 'string' || !prologue.trim())) ||
+        (ahead && (observeCheckout || prologue === undefined)) ||
+        (whole && (observeCheckout || ahead || prologue === undefined))) {
+        throw new Refusal('This read snapshot is unavailable.');
+    }
+    /* The answer is final once `run` returns: a read-only transaction's
+         COMMIT changes nothing it showed. So the caller has it then, and the
+         COMMIT finishes on the lease, which goes back to the pool (or is
+         discarded, should the COMMIT fail) only after it. Against a server a
+         round trip away that is one round trip off every snapshot. Not for an
+         observed checkout: its owner hands its response off inside the
+         snapshot (postgresReadCatalog.ts), so a COMMIT it never heard
+         acknowledged is an uncertain outcome it must be told of. */
+    let deliver;
+    const answered = new Promise((resolve) => {
+        deliver = resolve;
+    });
+    const work = async (client, checkout) => {
+        let out;
+        let active = true;
+        const current = () => {
+            if (!active || !checkout)
+                throw new Refusal('The read snapshot is unavailable.');
+            checkout();
+        };
+        /* The owner's prologue rides with BEGIN in one simple-protocol
+             message: statements without parameters (its LOCK, its first query),
+             so the snapshot is still taken where the owner put its first query,
+             and the owner is handed their results. A failure here, as of BEGIN
+             alone, discards the client, and the server rolls back with it. */
+        /* Asked ahead, the owner is handed the snapshot with its BEGIN in
+             flight rather than answered, so its own first statements leave in
+             the same flight on a reader that pipelines: one round trip where
+             BEGIN and each of them were one each. The owner waits on the BEGIN's
+             answer before it trusts anything; a BEGIN that failed fails what was
+             sent behind it, and the owner hears the BEGIN's failure first. */
+        const begun = client.query(prologue === undefined ? BEGIN_SNAPSHOT : `${BEGIN_SNAPSHOT}; ${prologue}${whole ? '; COMMIT' : ''}`).then((opened) => Object.freeze(prologue === undefined
+            ? []
+            : (Array.isArray(opened) ? opened : [opened]).slice(1, whole ? -1 : undefined)));
+        let results;
+        if (ahead)
+            void begun.catch(() => { });
+        else
+            results = await begun;
+        /* Committed already (`whole`, `finish`): there is no snapshot left to ask of, and no COMMIT to send. */
+        let ended = whole;
+        /* The client otherwise, until the snapshot has ended: a statement asked after `finish` would run outside any
+             transaction, on a connection the snapshot no longer holds. It pipelines where the client does (postgresPool.ts). */
+        const asked = Object.freeze({
+            query: ((...args) => ended
+                ? Promise.reject(new Refusal('The read snapshot is unavailable.'))
+                : client.query(...args)),
+        });
+        pipelinesAs(asked, client);
+        const finish = async (next) => {
+            if (ended || typeof next !== 'string' || !next.trim())
+                throw new Refusal('The read snapshot is unavailable.');
+            ended = true;
+            if (ahead)
+                await begun;
+            const closed = (await client.query(`COMMIT; ${BEGIN_SNAPSHOT}; ${next}; COMMIT`));
+            return Object.freeze((Array.isArray(closed) ? closed : [closed]).slice(2, -1));
+        };
+        try {
+            out = await run(Object.freeze({
+                client: asked,
+                ...(results === undefined ? {} : prologue === undefined ? {} : { prologue: results }),
+                ...(ahead ? { opened: begun } : {}),
+                ...(checkout ? { assertCurrent: current } : { ...(whole ? {} : { finish }) }),
+                describe: () => describe(asked, checkout !== undefined),
+                execute: async (statement, hint) => {
+                    if (ended)
+                        throw new Refusal('The read snapshot is unavailable.');
+                    const started = performance.now();
+                    const result = await asked.query(statement.text, statement.params);
+                    return {
+                        columns: result.fields.map((field) => field.name),
+                        rows: result.rows.map(hint?.binary ? withBytes : toJsonSafe),
+                        ms: Math.round(performance.now() - started),
+                        sql: { text: statement.text, params: statement.params },
+                    };
+                },
+            }));
+            // Never an answer from a snapshot whose BEGIN failed, whether or not its owner waited to hear.
+            if (ahead)
+                await begun;
+            if (checkout)
+                current();
+        }
+        catch (error) {
+            active = false;
+            /* A BEGIN that failed is the failure, as it is when awaited first: no
+                 transaction to roll back, and the client is discarded. */
+            if (ahead) {
+                const failed = await begun.then(() => undefined, (reason) => ({ reason }));
+                if (failed)
+                    throw failed.reason;
+            }
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch (rollback) {
+                throw new TransactionOutcomeUnknown(rollback);
+            }
+            throw error;
+        }
+        active = false;
+        if (!observeCheckout)
+            deliver(out);
+        if (!ended)
+            await client.query('COMMIT');
+        return out;
+    };
+    const leased = observeCheckout ? connections.withObservedReadClient(work) : connections.withReadClient(work, false, true);
+    // Whichever settles first: the answer, or a failure before there was one.
+    return Promise.race([answered, leased]);
+}

package/dist/adapters/postgresSchemaEpoch.d.ts

@@ -0,0 +1,24 @@
+export declare const SCHEMA_EPOCH_TABLE = "schema_epoch";
+export declare const EPOCHLESS_TTL_MS = 5000;
+export declare const epochlessEpoch: () => string;
+/** Whether a statement failed for a table (42P01) or column (42703) that is not there: the kept catalog is wrong. */
+export declare function schemaMoved(error: unknown): boolean;
+/**
+ * The statement that reads the epoch: one row, or none when the store is not
+ * whole (trigger disabled or gone). No parameters, so it rides in the
+ * message that begins a transaction. A missing store makes the statement
+ * fail, which the caller treats as a miss.
+ */
+export declare function schemaEpochStatement(): string;
+/** The epoch an epoch statement answered, or undefined when the store is not whole. */
+export declare function schemaEpochOf(result: {
+    rows: readonly Record<string, unknown>[];
+} | undefined): string | undefined;
+/**
+ * Explicit maintenance, under the shared migration lock: creates the store
+ * where none exists, changes nothing where it is whole, refuses a partial
+ * one. Needs a role that may create event triggers.
+ */
+export declare function provisionPostgresSchemaEpoch(url: string): Promise<{
+    provisioned: boolean;
+}>;

package/dist/adapters/postgresSchemaEpoch.js

@@ -0,0 +1,149 @@
+/**
+ * The PostgreSQL catalog's epoch: one row that moves whenever the schema does.
+ *
+ * Every transaction that trusts catalog metadata — the command journal's
+ * layout, the tables a row scope pins, a table's columns and key — used to
+ * read it again (six to eight catalog statements a command), or read the
+ * catalog digest (postgresCatalogDigest.ts), one statement that walks every
+ * catalog row and costs milliseconds of server time. With this store
+ * provisioned, the transaction reads one row instead, and every catalog
+ * answer is kept in memory under the epoch it was read at (epochCache.ts).
+ *
+ * How it moves: an event trigger on `ddl_command_end` appends a row inside
+ * the DDL's own transaction, so the change is visible exactly when the DDL
+ * commits, and the epoch is a digest of the rows there are, each with its row
+ * version (`xmin`). Appending rather than bumping one counter is deliberate:
+ * an UPDATE of one row would make every DDL transaction in the database wait
+ * on every other, and two migrations that each touch the other's table would
+ * then deadlock where today one simply waits. Inserts never wait on each
+ * other, and the trigger keeps the newest 64 rows, deleting older ones with
+ * SKIP LOCKED so that it never waits either. Any committed DDL adds a row the
+ * digest has not seen, and a row put back by hand has a new version, so an
+ * old epoch can never come round again. The function is SECURITY DEFINER,
+ * owned by whoever provisioned it, so DDL by a role that cannot write the
+ * table still moves the epoch — nobody's DDL fails because of this store.
+ * ENABLE ALWAYS keeps it firing under `session_replication_role = replica`.
+ *
+ * What the epoch statement reads besides the rows, so that nothing that could
+ * make a cached answer wrong goes unseen:
+ * - the event trigger (present, `ENABLE ALWAYS`, on `ddl_command_end`) and its
+ *   function's row version: dropped, disabled or replaced, and the statement
+ *   answers nothing, which is a miss;
+ * - role membership and the attributes privileges depend on: roles are
+ *   shared objects, and event triggers do not fire for them.
+ *
+ * Outside the contract, as for the digest: a superuser who turns event
+ * triggers off in a session (`event_triggers = off`) and changes the schema
+ * there. That is the superuser deliberately stepping around the database's
+ * own notification; a restart, or any other DDL, moves the epoch again.
+ *
+ * Provisioning is explicit maintenance, never startup (like the journal and
+ * the inbox), and needs a role that may create event triggers — a superuser
+ * on PostgreSQL 16. Where it is absent, the adapter reads the digest per
+ * transaction as before: slower, never less correct.
+ */
+import { Refusal } from './adapter.js';
+import { withPostgresMaintenanceTransaction } from './postgresMaintenance.js';
+import { RUNTIME_SCHEMA, runtimeTable } from '../shared/runtimeTables.js';
+export const SCHEMA_EPOCH_TABLE = 'schema_epoch';
+/* The function sits in the runtime schema beside the table (RUNTIME_SCHEMA_FUNCTIONS allows it there).
+   An event trigger belongs to the whole database, not to a schema, so its name keeps the reserved prefix. */
+const FUNCTION = 'schema_epoch_bump';
+const TRIGGER = '__mistri_schema_epoch';
+const definitions = [
+    `CREATE TABLE ${runtimeTable('postgres', SCHEMA_EPOCH_TABLE)} (
+  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  at timestamptz NOT NULL DEFAULT now()
+)`,
+    `INSERT INTO ${runtimeTable('postgres', SCHEMA_EPOCH_TABLE)} DEFAULT VALUES`,
+    `CREATE FUNCTION ${runtimeTable('postgres', FUNCTION)}() RETURNS event_trigger LANGUAGE plpgsql
+  SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$
+DECLARE
+  temporary boolean;
+BEGIN
+  -- A session's own temporary objects are nobody else's catalog (the digest
+  -- skips them too); anything else, or a command that names nothing, moves it.
+  SELECT count(*) > 0 AND bool_and(c.schema_name = 'pg_temp') INTO temporary FROM pg_event_trigger_ddl_commands() c;
+  IF temporary THEN RETURN; END IF;
+  INSERT INTO ${runtimeTable('postgres', SCHEMA_EPOCH_TABLE)} DEFAULT VALUES;
+  DELETE FROM ${runtimeTable('postgres', SCHEMA_EPOCH_TABLE)} WHERE id IN (
+    SELECT id FROM ${runtimeTable('postgres', SCHEMA_EPOCH_TABLE)} ORDER BY id DESC OFFSET 64 FOR UPDATE SKIP LOCKED);
+END
+$$`,
+    `REVOKE ALL ON FUNCTION ${runtimeTable('postgres', FUNCTION)}() FROM PUBLIC`,
+    `CREATE EVENT TRIGGER "${TRIGGER}" ON ddl_command_end EXECUTE FUNCTION ${runtimeTable('postgres', FUNCTION)}()`,
+    `ALTER EVENT TRIGGER "${TRIGGER}" ENABLE ALWAYS`,
+];
+/* With no epoch store a write has no version to file its catalog answers under and asked again every time.
+   They are filed under the clock instead: a column changed elsewhere goes unnoticed this long, unless a
+   write fails on a missing table or column (schemaMoved), which forgets them at once. The tenant read sources keep a
+   passed catalog attestation this long too (tenantReadSource.ts, tenantPlatformSource.ts). */
+export const EPOCHLESS_TTL_MS = 5_000;
+export const epochlessEpoch = () => `ttl:${Math.floor(Date.now() / EPOCHLESS_TTL_MS)}`;
+/** Whether a statement failed for a table (42P01) or column (42703) that is not there: the kept catalog is wrong. */
+export function schemaMoved(error) {
+    const code = error?.code;
+    return code === '42P01' || code === '42703';
+}
+/**
+ * The statement that reads the epoch: one row, or none when the store is not
+ * whole (trigger disabled or gone). No parameters, so it rides in the
+ * message that begins a transaction. A missing store makes the statement
+ * fail, which the caller treats as a miss.
+ */
+export function schemaEpochStatement() {
+    return `SELECT md5((SELECT coalesce(string_agg(e.id || ':' || e.xmin, ',' ORDER BY e.id), '') FROM ${runtimeTable('postgres', SCHEMA_EPOCH_TABLE)} e)
+         || '|' || t.xmin::text || '|' || f.xmin::text
+         || '|' || (SELECT coalesce(string_agg(m.roleid || '>' || m.member || ':' || m.xmin, ',' ORDER BY m.roleid, m.member), '')
+                       FROM pg_catalog.pg_auth_members m)
+         || '|' || (SELECT coalesce(string_agg(r.oid || ':' || r.rolname || ':' || r.rolsuper || ':' || r.rolinherit || ':' || r.rolbypassrls, ',' ORDER BY r.oid), '')
+                       FROM pg_catalog.pg_roles r)
+         || '|' || current_user) AS epoch
+  FROM pg_catalog.pg_event_trigger t
+  JOIN pg_catalog.pg_proc f ON f.oid = t.evtfoid AND f.proname = '${FUNCTION}' AND f.pronamespace = (SELECT n.oid FROM pg_catalog.pg_namespace n WHERE n.nspname = '${RUNTIME_SCHEMA}')
+ WHERE t.evtname = '${TRIGGER}' AND t.evtevent = 'ddl_command_end' AND t.evtenabled = 'A'`;
+}
+/** The epoch an epoch statement answered, or undefined when the store is not whole. */
+export function schemaEpochOf(result) {
+    const value = result?.rows.length === 1 ? result.rows[0].epoch : undefined;
+    return typeof value === 'string' && value ? value : undefined;
+}
+/** Whether this database holds the epoch store, whole. */
+async function postgresSchemaEpochReady(client) {
+    try {
+        return schemaEpochOf(await client.query(schemaEpochStatement())) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Explicit maintenance, under the shared migration lock: creates the store
+ * where none exists, changes nothing where it is whole, refuses a partial
+ * one. Needs a role that may create event triggers.
+ */
+export async function provisionPostgresSchemaEpoch(url) {
+    if (typeof url !== 'string' || !/^postgres(ql)?:\/\//i.test(url))
+        throw new Refusal('Schema epoch provisioning requires a postgres:// URL.');
+    return withPostgresMaintenanceTransaction(url, async (client) => {
+        const present = await client.query(`SELECT to_regclass('${runtimeTable('postgres', SCHEMA_EPOCH_TABLE)}') IS NOT NULL AS table,
+      EXISTS (SELECT 1 FROM pg_catalog.pg_event_trigger WHERE evtname = '${TRIGGER}') AS trigger,
+      EXISTS (SELECT 1 FROM pg_catalog.pg_proc WHERE proname = '${FUNCTION}' AND pronamespace = (SELECT n.oid FROM pg_catalog.pg_namespace n WHERE n.nspname = '${RUNTIME_SCHEMA}')) AS function`);
+        const found = present.rows[0];
+        let provisioned = false;
+        if (!found.table && !found.trigger && !found.function) {
+            try {
+                for (const ddl of definitions)
+                    await client.query(ddl);
+            }
+            catch (error) {
+                throw new Refusal(`The schema epoch needs a role that may create event triggers (a superuser on PostgreSQL 16): ${error.message}`);
+            }
+            provisioned = true;
+        }
+        if (!(await postgresSchemaEpochReady(client))) {
+            throw new Refusal(`The schema epoch store is partial or disabled: drop ${runtimeTable('postgres', SCHEMA_EPOCH_TABLE)}, its function and event trigger, then provision again.`);
+        }
+        return { provisioned };
+    });
+}

package/dist/adapters/postgresTransactionHandle.d.ts

@@ -0,0 +1,173 @@
+/**
+ * One transaction's own handle on a leased PostgreSQL client.
+ *
+ * A writer's client is pooled: the same object serves one transaction after
+ * another. Something true of one transaction only — the membership rows its
+ * fence locked, held to its end (tenantWriteSource.ts) — must
+ * therefore be kept on an object that is that transaction's alone: made at
+ * its BEGIN, used for every statement it sends, dropped with it. Never on the
+ * client, and never keyed by a pool connection.
+ *
+ * It also counts the rollbacks that pass through it. A `ROLLBACK TO
+ * SAVEPOINT` undoes everything since the savepoint, the locks taken there
+ * included, so whatever was established before it is no longer vouched for.
+ * Any statement that says ROLLBACK anywhere counts, a string literal
+ * included: a false count only costs a repeated check.
+ */
+import { type PgQuery, type PgResult } from './postgresPool.js';
+/** What became of a transaction's statements sent ahead. */
+export interface AheadReport {
+    /** Sent before their turn. */
+    sent: number;
+    /** Of those, the ones a later identical query took. */
+    taken: number;
+    /** Statements asked in their turn while answers sent ahead were still waiting: each cost a round trip one sent ahead might have saved. */
+    missed: number;
+    /** Answers sent ahead that nothing took before they were dropped, by what each said. */
+    left: string[];
+    /** Times the transaction began again without them, because one failed. */
+    redone: number;
+    /** Reads answered from a row read ahead (holdAhead) instead of being sent. */
+    answered: number;
+    /** What was asked in its turn while answers sent ahead were waiting, by its first words: the missed, and what dropped them. */
+    asked: string[];
+}
+export declare function transactionHandle(client: PgQuery, origin?: object): PgQuery;
+/**
+ * Send statements now that the transaction will ask for later, so they leave
+ * in the flight already going out (behind its BEGIN) instead of each in a
+ * round trip of its own. Each answer is kept for the first later query that
+ * says exactly the same thing, and given to it once; the query then sends
+ * nothing. Only reads and locks are sent ahead, in the order the transaction
+ * would ask them, and every kept answer is dropped the moment the transaction
+ * sends anything else — a write of its own, a rollback to a savepoint — so a
+ * read after this transaction's own change is always asked again.
+ *
+ * The caller awaits the returned answers before it relies on any of them: one
+ * that failed has aborted the transaction, which then begins again without
+ * them (nothing has used them yet). On a client that does not pipeline
+ * nothing is sent: each would cost its own round trip either way.
+ */
+export declare function sendAhead(client: PgQuery, statements: readonly PipelinedStatement[]): Promise<unknown>[];
+/**
+ * Whether an answer sent ahead still waits for exactly `statement`: asking it
+ * then sends nothing. False once a statement of the transaction's own has
+ * dropped it, or where nothing was sent ahead.
+ */
+export declare function waitsAhead(client: PgQuery, statement: Readonly<{
+    text: string;
+    values?: readonly unknown[];
+}>): boolean;
+/**
+ * Send a read now that a caller will answer later reads from itself (a row
+ * read in full, answered by projection: scoped/keyRows.ts), rather than the
+ * handle answering one identical query with it. `take` says it answered one,
+ * so a read never used is reported left like any statement sent ahead.
+ * Undefined where the client does not pipeline.
+ */
+export declare function holdAhead(client: PgQuery, statement: PipelinedStatement): {
+    answer: Promise<PgResult<Record<string, unknown>>>;
+    take(): void;
+} | undefined;
+/**
+ * The transaction's statement generation: a number that moves with every
+ * statement sent through its handle that is not a read or a lock (a write, a
+ * savepoint, a rollback, a notification) and with every one that fails.
+ * Something read while it stood still was read in a transaction that has
+ * changed nothing since. Undefined for anything that is not a handle.
+ */
+export declare const generationOf: (client: PgQuery) => number | undefined;
+/** Whether statements sent ahead on this transaction leave in one flight: its client pipelines. */
+export declare const sendsAhead: (client: PgQuery) => boolean;
+/**
+ * A COMMIT that the server answered as a ROLLBACK, because a write sent in
+ * front of it in the same flight (beforeCommit) failed: nothing committed.
+ * `cause` is that write's own failure.
+ */
+export declare class RolledBackAtCommit extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+/**
+ * Queue writes whose answers nothing reads before COMMIT (a receipt, its
+ * audit, a live change and its notification), to leave with the next
+ * statement the transaction sends — its COMMIT, at best — in the same flight
+ * instead of a round trip each. A write that fails then fails what it was
+ * sent with: the statement behind it throws the write's own failure, and a
+ * COMMIT throws RolledBackAtCommit (nothing committed). False where the
+ * client does not pipeline or is not a transaction's handle: the caller sends
+ * them in their turn.
+ */
+export declare function beforeCommit(client: PgQuery, statements: readonly PipelinedStatement[]): boolean;
+/**
+ * Run `ride` the moment the transaction sends a statement `match` accepts (a
+ * write the caller is about to wait on), so what `ride` sends leaves right
+ * behind it, in its flight, and reads what it wrote. Answers a withdraw: true
+ * when `ride` had not run (it never will now). Undefined where the client
+ * does not pipeline: the caller asks in its turn.
+ */
+export declare function behindWrite(client: PgQuery, match: (text: string) => boolean, ride: () => void): (() => boolean) | undefined;
+/** Drop every answer sent ahead and not yet taken, and count a beginning again without them (one failed). */
+export declare function redoWithoutAhead(client: PgQuery): void;
+/** What became of this transaction's statements sent ahead, those still waiting counted as left; undefined for anything else. */
+export declare function aheadReport(client: PgQuery): AheadReport | undefined;
+/** The same transaction seen through `query`, which must send every
+ * statement on through `client` (a caller's checkpoints around each one):
+ * so the rollbacks are still counted by the handle, and what the transaction
+ * has established is still found. On a bare client, a bare view. */
+export declare function transactionView(client: PgQuery, query: PgQuery['query']): PgQuery;
+/** The transaction a handle or view belongs to, as an object only they
+ * share; undefined for a bare client, so nothing is kept on one. */
+export declare function transactionOf(client: PgQuery): object | undefined;
+/** A statement failed for a table, column or privilege that is not what it was, or a reference that broke: a runtime store may have moved. */
+export declare function suspectsStores(error: unknown): boolean;
+export declare const attestedOn: (origin: object, key: string) => boolean;
+export declare function keepAttestedOn(origin: object, key: string): void;
+export declare const forgetAttestations: (origin: object, client?: PgQuery, error?: unknown) => void;
+/** Whether a message may change the catalog: DDL, or code that may run it. */
+export declare const changesCatalog: (text: string) => boolean;
+/** Say the exact catalog version `client`'s transaction read, before anything it attests: its digest or its epoch.
+ * `reread` reads it again, for a transaction whose statements each see the latest commit (READ COMMITTED); a
+ * snapshot's needs none. Undefined unsays it, for a transaction begun again on the same client that read none. */
+export declare function noteCatalogVersion(client: PgQuery, database: string, version: string | undefined, reread?: () => Promise<string | undefined>): void;
+/** How a transaction on `origin`'s handles reads an exact catalog version of `database` when it has read none. */
+export declare function readsCatalogVersion(origin: object, database: string, read: (client: PgQuery) => Promise<string>): void;
+/**
+ * Attest a runtime store in full (`full`, which refuses) unless the adapter
+ * this transaction runs on attested it under `key` already, or any transaction
+ * on the same database did under the exact catalog version this one read
+ * (sharedAttestations) — read now, if it read none and its adapter says how —
+ * and its meta row still binds it (`rebound`, without which nothing is shared).
+ * Otherwise, off a handle or on one made without an adapter, always in full.
+ */
+export declare function attestOnce(client: PgQuery, key: string, full: () => Promise<void>, rebound?: () => Promise<boolean>): Promise<void>;
+/** How many rollbacks have passed through this transaction's handle; undefined
+ * for anything that is not one. */
+export declare function transactionRollbacks(client: PgQuery): number | undefined;
+/** A statement for pipelined(): bare text goes by the simple protocol, which may carry several. */
+export type PipelinedStatement = string | Readonly<{
+    text: string;
+    values?: readonly unknown[];
+}>;
+/**
+ * Statements asked together and answered in order, on a transaction's handle
+ * or view: one round trip where its client pipelines (a writer's,
+ * postgresPool.ts), one each where it does not, with the same answers.
+ *
+ * Only inside the transaction — the handle's BEGIN sent first, on this handle
+ * or as the first statement here. There a statement that fails aborts the
+ * transaction, and every one sent behind it fails without effect ("current
+ * transaction is aborted"), so nothing runs that depended on one that did not;
+ * outside a transaction block each would commit on its own, which is why a
+ * bare client is refused. Every answer is awaited before this returns or
+ * throws, so the connection is never left mid-pipeline, and the first failure
+ * in order is the one thrown: the ones behind it only say it happened.
+ *
+ * `check` reads each answer as it arrives, in order, before the next one is
+ * read: a check that throws is the failure (the caller rolls the transaction
+ * back), and no later answer reaches a check. Behind a transaction-mode pooler
+ * (PgBouncer) a pipeline stays on its one server connection: the server says
+ * it is idle only after the COMMIT or ROLLBACK that ends the transaction, which
+ * this never sends ahead of a statement that could still fail.
+ */
+export declare function pipelined(client: PgQuery, statements: readonly PipelinedStatement[], check?: (result: PgResult<Record<string, unknown>> | PgResult<Record<string, unknown>>[], index: number) => void): Promise<Array<PgResult<Record<string, unknown>> | PgResult<Record<string, unknown>>[]>>;