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

package/dist/adapters/poolMetrics.js

@@ -0,0 +1,185 @@
+/**
+ * What a connection pool can say about itself: how long each checkout waited
+ * for a connection, how long it held one, and how full the pool is now.
+ *
+ * Engine-neutral and fixed-size: cumulative counters and bucket counts on the
+ * HTTP request metrics' bounds, so the operator surface carries them without
+ * learning a driver, and their size never grows with traffic. One meter per
+ * role of a pool — the readers, the writers, the background writer — and nothing in it names the
+ * database, because the operator surface must not.
+ */
+/** Inclusive upper bounds, the same as the HTTP request metrics', so one scale reads both. */
+export const POOL_DURATION_BOUNDS_MS = Object.freeze([1, 5, 10, 25, 50, 100, 250, 500, 1_000, 2_500, 5_000, 10_000, 30_000]);
+/** How long a checkout that timed out keeps its pool marked saturated. */
+const SATURATION_MEMORY_MS = 60_000;
+/**
+ * How long a checkout may queue behind a full pool before it is refused, and
+ * how many may queue (per connection the pool holds). Without them a
+ * saturated server held every request for the driver's ten-second timeout and
+ * then failed it as a 500: slow, and no better informed. Past either bound the
+ * request is refused at once, as busy, and its client is told to come back.
+ *
+ * The count is about as many checkouts as a connection works through in that
+ * wait (a few tens of milliseconds each): past it, the wait would run out
+ * anyway. At eight, a burst a server answers well inside the wait was refused
+ * at once — a page's boot has up to eight reads in flight, and a field report saw
+ * two thirds of the tabs opened at one moment by 25 people turned away busy
+ * on a server with its loop idle. The wait is what bounds a slow server.
+ * Who gets the places in the line, account by account, is poolAdmission.ts's.
+ */
+export const POOL_QUEUE_WAIT_MS = 2_000;
+export const POOL_QUEUE_PER_CONNECTION = 64;
+/** What a person is told when the server is busy, and how soon to try again. */
+export const POOL_BUSY_MESSAGE = 'The server is busy; try again in a moment.';
+const POOL_BUSY_RETRY_AFTER_SECONDS = 1;
+/** How long a pool the server refused stays at the connections it holds before it asks for more: its idle timeout. */
+export const POOL_LIMIT_HOLD_MS = 30_000;
+/**
+ * A checkout refused because the pool is full and its queue is too long or
+ * has waited too long, or because the database refused this process another
+ * connection and the pool held none to wait for (`connection_limit`, the
+ * refusal as its cause). Thrown before anything was leased, so no statement
+ * ran: a read can be asked again and a write was never begun.
+ */
+export class PoolBusy extends Error {
+    role;
+    why;
+    constructor(role, why, cause) {
+        super(POOL_BUSY_MESSAGE, cause === undefined ? undefined : { cause });
+        this.role = role;
+        this.why = why;
+        this.name = 'PoolBusy';
+    }
+}
+/**
+ * When to come back after a refused checkout. A full queue clears in a moment; a pool the database refused another
+ * connection holds at what it has and asks for more only after POOL_LIMIT_HOLD_MS, so a retry in one second lands on
+ * the same refusal. A `connection_limit` refusal says the hold's length instead.
+ */
+export function poolBusyRetryAfterSeconds(error) {
+    let at = error;
+    for (let depth = 0; depth < 4 && at && typeof at === 'object'; depth++) {
+        if (at instanceof PoolBusy)
+            return at.why === 'connection_limit' ? POOL_LIMIT_HOLD_MS / 1000 : POOL_BUSY_RETRY_AFTER_SECONDS;
+        at = at.cause;
+    }
+    return POOL_BUSY_RETRY_AFTER_SECONDS;
+}
+/**
+ * Whether `error` is a refused checkout, anywhere in its causes, and not one
+ * that reports an unknown outcome (a transaction whose commit was never
+ * acknowledged is not "busy": it may have landed).
+ */
+export function isPoolBusy(error) {
+    let at = error;
+    for (let depth = 0; depth < 4 && at && typeof at === 'object'; depth++) {
+        if (at.name === 'TransactionOutcomeUnknown' || at.outcome === 'unknown')
+            return false;
+        if (at instanceof PoolBusy)
+            return true;
+        at = at.cause;
+    }
+    return false;
+}
+function record(buckets, ms) {
+    const at = Number.isFinite(ms) && ms > 0 ? ms : 0;
+    const index = POOL_DURATION_BOUNDS_MS.findIndex((bound) => at <= bound);
+    buckets[index < 0 ? POOL_DURATION_BOUNDS_MS.length : index] += 1;
+}
+export class PoolMeter {
+    role;
+    size;
+    now;
+    leased = 0;
+    pending = 0;
+    checkouts = 0;
+    queued = 0;
+    timeouts = 0;
+    failures = 0;
+    lastTimeoutAt = Number.NEGATIVE_INFINITY;
+    waits = Array(POOL_DURATION_BOUNDS_MS.length + 1).fill(0);
+    holds = Array(POOL_DURATION_BOUNDS_MS.length + 1).fill(0);
+    constructor(role, size, now = () => performance.now()) {
+        this.role = role;
+        this.size = size;
+        this.now = now;
+    }
+    /** Every connection is leased or being opened: a checkout begun now waits. */
+    full() {
+        return this.leased + this.pending >= this.size;
+    }
+    /** Checkouts queued now behind a pool whose every connection is in use. */
+    waiting() {
+        return Math.max(0, this.pending - Math.max(0, this.size - this.leased));
+    }
+    /** A checkout turned away before it began: counted as a timeout, so the pool reads saturated and readiness says so. */
+    refuse() {
+        this.checkouts += 1;
+        this.queued += 1;
+        this.timeouts += 1;
+        this.lastTimeoutAt = this.now();
+        record(this.waits, 0);
+    }
+    begin() {
+        const started = this.now();
+        /* Every connection is leased, or being opened for a checkout ahead of
+           this one: this one waits in the driver's queue, not for a dial. */
+        if (this.leased + this.pending >= this.size)
+            this.queued += 1;
+        this.checkouts += 1;
+        this.pending += 1;
+        let settled = false;
+        return {
+            acquired: () => {
+                if (settled)
+                    return () => { };
+                settled = true;
+                this.pending -= 1;
+                this.leased += 1;
+                const at = this.now();
+                record(this.waits, at - started);
+                let returned = false;
+                return () => {
+                    if (returned)
+                        return;
+                    returned = true;
+                    this.leased -= 1;
+                    record(this.holds, this.now() - at);
+                };
+            },
+            failed: (timedOut) => {
+                if (settled)
+                    return;
+                settled = true;
+                this.pending -= 1;
+                const at = this.now();
+                // A checkout that timed out waited longest of all; it is the sample that matters most.
+                record(this.waits, at - started);
+                if (timedOut) {
+                    this.timeouts += 1;
+                    this.lastTimeoutAt = at;
+                }
+                else
+                    this.failures += 1;
+            },
+        };
+    }
+    stats(pooler, open) {
+        const waiting = this.waiting();
+        return Object.freeze({
+            role: this.role,
+            pooler,
+            size: this.size,
+            open,
+            inUse: this.leased,
+            waiting,
+            saturated: waiting > 0 || this.now() - this.lastTimeoutAt < SATURATION_MEMORY_MS,
+            checkouts: this.checkouts,
+            queued: this.queued,
+            timedOut: this.timeouts,
+            failed: this.failures,
+            waitBuckets: Object.freeze([...this.waits]),
+            holdBuckets: Object.freeze([...this.holds]),
+        });
+    }
+}

package/dist/adapters/postgres.d.ts

@@ -0,0 +1,436 @@
+import { type Adapter, type Filter, type QueryRequest, type QueryResult, type ScopedReads, type SqlRequest, type SqlResult, type ViewResult, type BreakdownResult, type ExplainRequest, type ExplainResult, type ProfileResult, TransactionOperations, type WriteTransaction, type DeleteRequest, type DeleteResult, type InsertRequest, type InsertResult, type UpdateRequest, type UpdateResult, type CountItem, type RolePrivileges, type SqlStyle } from './adapter.js';
+import { type PostgresScopeCatalog } from './scoped/postgresScopeCatalog.js';
+import { type PinnedPostgresReadOwner, type PostgresReadDependency } from './postgresReadCatalog.js';
+import type { DatabaseSchema } from '../shared/schema.js';
+import { type ViewDef } from '../shared/view.js';
+import { type BreakdownDef } from '../shared/breakdown.js';
+import { PgConnectionManager, type PgConnectionOptions, type PgQuery, type SharedPoolShape } from './postgresPool.js';
+import { type PipelinedStatement } from './postgresTransactionHandle.js';
+import type { PoolRoleStats } from './poolMetrics.js';
+import { type RowScope } from '../shared/rowScope.js';
+import { type PostgresReadSnapshot } from './postgresReadSnapshot.js';
+/** Constructor-issued source identity, checked without reading receiver data. */
+export declare const isPostgresVerifiedCommandSource: (value: unknown) => value is PostgresAdapter;
+export type { PostgresReadSnapshot } from './postgresReadSnapshot.js';
+/** For the budget tests: how many times this process described a PostgreSQL catalog, and how many were found kept. */
+export declare function postgresDescriptionCounts(): Readonly<{
+    described: number;
+    kept: number;
+}>;
+/**
+ * An adapter on the manager every adapter of `url` with this `shape` shares (sharedPgConnections): its own catalog,
+ * lanes and stores, the pools of its neighbors. Closing it lets its share go; the pools close with the last one.
+ */
+export declare function sharedPostgresAdapter(url: string, label: string, shape?: SharedPoolShape): PostgresAdapter;
+export declare class PostgresAdapter implements Adapter {
+    private label;
+    /** Restrict to these schemas. Empty means every non-system schema. */
+    private schemas;
+    readonly dialect: 'postgres';
+    private connections;
+    private writes;
+    private readonly describes;
+    private readonly database;
+    private readonly catalogCache;
+    /** The epoch each open write transaction read, by the handle it runs on. */
+    private readonly txEpochs;
+    private epochStore;
+    /** `work`, forgetting the kept catalog if it dies on a table or column that is gone: what was kept is wrong. */
+    private watched;
+    constructor(connectionString: string, label?: string, 
+    /** Restrict to these schemas. Empty means every non-system schema. */
+    schemas?: string[], connections?: PgConnectionManager, 
+    /** The reader count the connection's config names; the process defaults fill the rest. */
+    pool?: PgConnectionOptions);
+    private verifiedSource;
+    /** The pools' meters, for the operator surface. */
+    poolStats(): readonly PoolRoleStats[];
+    /** Each replica's state, when the connection names any (replicas.ts). */
+    replicaHealth(): ReturnType<PgConnectionManager['replicaHealth']>;
+    private conn;
+    /**
+     * Run a statement the user wrote.
+     *
+     * The session already carries `default_transaction_read_only = on`, and for
+     * everything else in this adapter that is enough, because every statement is
+     * one this file built. It is **not** enough here: `SET
+     * default_transaction_read_only = off` is itself a statement, and a user who
+     * typed it followed by a `DELETE` would get both.
+     *
+     * `BEGIN READ ONLY` is the version that holds, for one statement. Postgres
+     * refuses `SET TRANSACTION READ WRITE` once the transaction has taken its
+     * first snapshot, and one statement takes it before it runs. It does not hold
+     * against several: `COMMIT; BEGIN READ WRITE; DELETE …` ends the read-only
+     * transaction and opens a writable one. So the text goes on the extended
+     * protocol (`queryMode: 'extended'`), where Postgres itself refuses a second
+     * statement; refuseStacked is the earlier, clearer refusal, not the guard.
+     * (node-postgres sends a query with an empty `values` on the simple protocol,
+     * which runs every statement in the string.) The `ROLLBACK` afterwards also
+     * discards any session state the statement set, so one run cannot change what
+     * the next one means.
+     *
+     * The rollback runs in a `finally`: a statement that errors has still opened
+     * a transaction, and leaving it open would leave the connection in an aborted
+     * state where every later query fails with "current transaction is aborted".
+     *
+     * `write: true` is the other half, and it is a different request rather than
+     * a relaxation of this one: a separate handle, no READ ONLY transaction, and
+     * a decision made further up about whether this connection may write at all.
+     * The two paths share the statement text and nothing else.
+     */
+    runSql(request: SqlRequest): Promise<SqlResult>;
+    /**
+     * EXPLAIN, plain — never the analysing variant that executes to time.
+     *
+     * `runSql`'s bounding wrap is precisely wrong here: a statement made a
+     * derived table is a different statement, with a different plan. The text
+     * goes to the planner as written, inside the same READ ONLY transaction
+     * every user statement gets — so even a smuggled write is only ever
+     * planned, and an execution attempt is the transaction's to refuse, not a
+     * string check's.
+     */
+    explainSql(request: ExplainRequest): Promise<ExplainResult>;
+    /**
+     * The planner's own statistics, read rather than computed.
+     *
+     * `pg_stats` already holds the null share, the distinct estimate, the most
+     * common values with their frequencies, and the histogram — ANALYZE paid
+     * for them, reading them touches no user table. The numbers are
+     * sample-based and stale until the next ANALYZE, which is what
+     * `source: 'statistics'` tells the caller; a column ANALYZE has never
+     * visited simply has no numbers, which beats invented ones.
+     */
+    profile(table: string): Promise<ProfileResult>;
+    introspect(): Promise<DatabaseSchema>;
+    private introspectNow;
+    private scopeStyleRead?;
+    /**
+     * The style a row-scoped read compiles with on this server: its CTEs
+     * inlined from Postgres 12 on (POSTGRES_INLINE_STYLE). Asked once per
+     * adapter; a failed ask is not remembered, and that read compiles as
+     * before — the hint is a plan, never a rule about rows.
+     */
+    scopeStyle(): Promise<SqlStyle>;
+    /** The role's reach, asked of the catalog on the reader (rolePrivileges.ts). */
+    privileges(): Promise<RolePrivileges>;
+    /** The catalog as one handle sees it, read by postgresCatalog.ts: the
+     * reader on connect, or the leased writer inside a scoped transaction,
+     * where the same description is the evidence the deployed permissions are
+     * attested against. */
+    private describe;
+    /** The catalog as `db` sees it at `version`, read there before: a copy of the one kept under it (sharedDescriptions),
+     * or described now and kept. Another adapter's copy carries this one's label. */
+    private describedAt;
+    /** A snapshot's description: the digest first, in the same snapshot, then the description kept under it or a new one. */
+    private describeSnapshot;
+    /** `version`, the exact one `db`'s transaction just read, said for what it attests next (noteCatalogVersion); a time-filed one is not said. */
+    private versionRead;
+    /** How a write (READ COMMITTED) reads `version` again, the digest or the epoch as it read it; a time-filed one is not read. */
+    private rereadOf;
+    /**
+     * The catalog as a scoped transaction's writer sees it, described again
+     * only when it has moved. Every transaction reads the catalog digest
+     * (postgresCatalogDigest.ts) — one statement where a description is six —
+     * and reuses a description read just after the same digest was, by this
+     * adapter or another of the same database (sharedDescriptions). Read
+     * before, never after: DDL committing
+     * between the two then leaves a digest no later read can match, so the
+     * description is taken again rather than trusted on a digest it postdates.
+     * The digest covers every schema but the system's, a superset of what
+     * this adapter describes, and moves with privileges and roles too. What it
+     * does not see, comments and the planner's row estimates, is display and
+     * never authority.
+     */
+    private describeScoped;
+    /**
+     * Begin a write transaction and read the schema epoch in the same message:
+     * `BEGIN`, the LOCK a scope pinned last time under the epoch it expects,
+     * and the epoch statement, in one round trip (the simple protocol carries
+     * several statements when none has parameters). The LOCK comes first, so
+     * DDL on a pinned table after the epoch was read has to wait for this
+     * transaction; whether the lock was the right one is then decided by the
+     * epoch alone. A message that fails — the store gone, a pinned table
+     * dropped, a privilege revoked — is only a miss: rolled back, begun again
+     * plainly, and the transaction describes what it needs as before.
+     */
+    private openWrite;
+    /**
+     * Without the epoch store, a scoped transaction reads the catalog digest
+     * (postgresCatalogDigest.ts) — it always did, to describe the scope — and
+     * the digest is then its epoch: one statement that moves with every catalog
+     * row the scope, a relation's kind and columns, and the journal's layout
+     * depend on, role membership, and (for a command) the journal's meta row.
+     * Read in the message that begins the transaction, after the LOCK the scope
+     * pinned last time, as the epoch is. Slower than the epoch store's one row,
+     * never less exact; a message that fails begins again the long way.
+     */
+    private openWithDigest;
+    /**
+     * A reserved store's layout, attested the first time this adapter reads it
+     * and not again (attestOnce, postgresTransactionHandle.ts): told whether it
+     * stands attested. A read that fails the way a moved catalog fails one
+     * forgets it, and the next read attests in full.
+     */
+    private attestedStore;
+    /** A journal's layout and meta row, attested the first time this adapter opens a transaction with it (a journal
+        that names no meta row, in every transaction). */
+    private attestJournal;
+    query(request: QueryRequest): Promise<QueryResult>;
+    scopeReads(input: RowScope): Promise<ScopedReads>;
+    private queryOn;
+    /**
+     * Run a compiled view.
+     *
+     * Note what is *not* here: any check that the tables named in the view
+     * exist. `compileView` resolves the base table and every hop against the
+     * introspected catalog and refuses anything it cannot find, so the only
+     * identifiers that reach the quoting step are ones the catalog produced.
+     * The user's contribution — the values — never leaves the parameter array.
+     *
+     * The dialect difference this exercises is placeholder numbering:
+     * `POSTGRES_STYLE` counts $1..$n across the whole statement, and the joins
+     * sitting between the SELECT list and the WHERE clause are exactly what
+     * makes an off-by-one here easy and invisible.
+     */
+    runView(view: ViewDef, offset?: number): Promise<ViewResult>;
+    runBreakdown(breakdown: BreakdownDef, offset?: number): Promise<BreakdownResult>;
+    countBreakdown(breakdown: BreakdownDef, limit?: number): Promise<number>;
+    countView(view: ViewDef, limit?: number): Promise<number>;
+    private cachedSchema;
+    private schema;
+    /**
+     * The planner's row estimate, straight from `pg_class`.
+     *
+     * `reltuples` is what the planner itself uses to decide how to run a query,
+     * so it is the number Postgres is already trusting. It is -1 on a table that
+     * has never been analysed, which is a "do not know" rather than a zero —
+     * returning undefined there gets an exact count instead of confidently
+     * reporting an empty table that is not empty.
+     */
+    estimateCount(table: string): Promise<number | undefined>;
+    count(table: string, filter?: Filter, limit?: number): Promise<number>;
+    countEach(items: readonly CountItem[], limit?: number): Promise<number[]>;
+    private countOn;
+    private columnsOf;
+    /**
+     * Update one row, having proved it is one row.
+     *
+     * The pre-flight count runs on the *read* handle, so the check that decides
+     * whether to write cannot itself write. A key that matches anything other
+     * than exactly one row stops here rather than at the UPDATE — the danger in
+     * a cell editor was never injection, it is a WHERE broader than its author
+     * believed.
+     */
+    update(request: UpdateRequest): Promise<UpdateResult>;
+    private updateNow;
+    /**
+     * Add one row.
+     *
+     * `update`'s guards where they apply, with the key rules inverted: a primary
+     * key may be supplied (a country code somebody types) or left for the
+     * database to assign. What is deliberately *not* pre-checked is
+     * completeness — a missing NOT NULL column with no default is the database's
+     * refusal to make, and its message names the column better than a paraphrase
+     * would.
+     *
+     * `RETURNING *` rather than a re-read by key: one statement gives back the
+     * row as stored, defaults filled and the assigned key included, with no
+     * window for another write to land in between.
+     */
+    insert(request: InsertRequest): Promise<InsertResult>;
+    private insertNow;
+    /**
+     * Remove one row, having proved it is one row.
+     *
+     * What is *not* checked here is whether the row should go: what references
+     * it, and what the database will do to those references, is answered above
+     * this layer where the schema is in hand. A `RESTRICT` that fires is the
+     * correct outcome in the engine's own words.
+     */
+    remove(request: DeleteRequest): Promise<DeleteResult>;
+    private recordsHistory;
+    private historyWrites;
+    private removeNow;
+    /**
+     * Several writes as one, or none of them.
+     *
+     * Plain `BEGIN` / `COMMIT` on the write connection. The callback is handed
+     * the same write bodies the public methods call, so every guard — the whole
+     * key, the pre-flight count, the type coercion — applies inside a
+     * transaction exactly as it does outside one.
+     *
+     * Reads, metadata checks, and preflight counts use the same leased client.
+     * This preserves read-after-write visibility; it does not promise serializable
+     * isolation. Call lockRecord explicitly before capturing protected originals:
+     * where an App writes, other transactions of this process run beside this
+     * one (writeLanes.ts), and a row read without its lock may change before
+     * the write that depends on it, as a row read in another pod always could.
+     */
+    transaction<T>(run: (tx: WriteTransaction) => Promise<T>): Promise<T>;
+    private transact;
+    /**
+     * Begin an unscoped write transaction with what it was told it opens with
+     * (writeAhead.ts) behind its BEGIN, as a scoped one does (sendWriteAhead):
+     * the journal's receipt lookup, and for each target its lock and its whole
+     * row, kept to answer the transaction's reads of it by key (keyRows.ts) —
+     * the command's own read of its target, its handler's, the history
+     * capture's before image. The lock goes first, so the row is read under it
+     * and cannot move until this transaction ends; its own writes move the
+     * statement generation and are read again. One that fails aborts the
+     * opening, which begins again without them. Answers the transaction's
+     * reader: by key from the kept rows where they answer, else in its turn.
+     */
+    private openPlain;
+    /** The statements openPlain sends behind the BEGIN; each exactly what the transaction sends in its turn (lockRecordNow, queryOn). */
+    private sendPlainAhead;
+    /**
+     * Same-source records and a durable journal in one transaction, the
+     * journal lent by the App framework (storeHost.ts TransactionJournal): the
+     * command journal, or a public placement's. Lent through the store host,
+     * never on the class, so the database browser has no journal path at all.
+     *
+     * The SQLite version opens `BEGIN IMMEDIATE`, which serialises every writer
+     * in the file; here the transaction is plain `BEGIN` at the server's
+     * default READ COMMITTED, and the journal's per-scope advisory lock does
+     * the one piece of that serialisation a command needs — two deliveries of
+     * the same command cannot both execute. SERIALIZABLE was the alternative
+     * and was refused: it would turn unrelated concurrent commands into 40001
+     * retries the SQLite path never has, and a conditional `expected` update
+     * already refuses a stale row in the write itself.
+     *
+     * The journal is attested inside the transaction and before the callback,
+     * so an unmigrated or altered layout refuses without a write. The outcome
+     * contract is SQLite's: a failure after COMMIT was sent, or a rollback that
+     * was not acknowledged, is `unknown`; everything else is `not_applied`.
+     * `withWriteClient` destroys the client on any failure, so a connection in
+     * an uncertain state is never handed to the next write.
+     */
+    private journalTransaction;
+    private ordinaryJournalTransaction;
+    /**
+     * Private same-source row enforcement, with the SQLite guarantees.
+     *
+     * SQLite gets "the row the scope checked is the row the write changes"
+     * from `BEGIN IMMEDIATE`, which excludes every other writer for the whole
+     * transaction. Here the transaction is plain `BEGIN` at the server's
+     * default READ COMMITTED, and the guarantee is made per row instead: before
+     * a target is scope-checked its row is taken `FOR UPDATE`, and before a
+     * parent is checked its row is taken `FOR SHARE`. A lock waits for any
+     * in-flight writer of that row to finish, and the guard read that follows
+     * takes a fresh snapshot — READ COMMITTED gives one per statement — so it
+     * sees the version that writer committed and nobody can commit another
+     * until this transaction ends. A row a concurrent writer moved out of scope
+     * is therefore refused, whether it moved before the check or while the
+     * check waited. SERIALIZABLE would prove the same thing by aborting one of
+     * the two with 40001, which the SQLite path never does and every handler
+     * would have to learn to retry; the explicit locks make the refusal an
+     * ordinary one.
+     *
+     * The catalog is read on the writer inside the transaction after the
+     * scope's tables are pinned against DDL (`postgresScopeCatalog.ts`), and
+     * handed out as detached evidence for the caller to attest. Outcomes are
+     * the transaction contract's: a failure after COMMIT was sent, or a
+     * rollback that was not acknowledged, is unknown, and the client is
+     * discarded rather than reused. Everything else did not commit.
+     */
+    scopeTransaction<T>(input: RowScope, run: (tx: WriteTransaction, catalog: DatabaseSchema) => Promise<T>): Promise<T>;
+    /**
+     * Private source-owner boundary, deliberately absent from Adapter: the
+     * PostgreSQL counterpart of `SqliteAdapter.scopeVerifiedTransaction`. The
+     * verifier is trusted host code — the tenant write source's attestation and
+     * the store's membership fence (`assertPostgresTenantMembershipFence`) —
+     * never a business callback or a wire value, and must not retain the
+     * client. It runs on the leased writer inside the transaction twice: after
+     * the scope's tables are pinned and the catalog read, before the callback;
+     * and after the callback's operations drain, before COMMIT. It is handed the
+     * catalog evidence and the adapter's own introspection on the writer, for
+     * anything it pins itself. SQLite also re-verifies around every operation,
+     * because its fence is a snapshot check; here the fence is row locks held
+     * to the end of the transaction, so the two checks bound its lifetime.
+     */
+    scopeVerifiedTransaction<T>(input: RowScope, verify: PostgresTransactionVerifier, run: (tx: WriteTransaction, catalog: DatabaseSchema) => Promise<T>): Promise<T>;
+    /**
+     * Private source-owner boundary, deliberately absent from Adapter: one
+     * `REPEATABLE READ, READ ONLY` transaction on a leased reader, for trusted
+     * host code that pins, attests and reads inside a single snapshot (the
+     * PostgreSQL tenant read source). It is what a deferred `BEGIN` on its
+     * read-only handle gives the SQLite tenant reader: every statement sees one
+     * committed state. PostgreSQL takes that snapshot at the first query, not at
+     * BEGIN, so an owner that takes its locks before its first query attests
+     * what committed before them, and DDL after them waits. A ROLLBACK that
+     * fails surfaces as TransactionOutcomeUnknown; any failure discards the
+     * client rather than returning it to the pool.
+     */
+    readSnapshot<T>(run: (snapshot: PostgresReadSnapshot) => Promise<T>, observeCheckout?: boolean, prologue?: string, ahead?: boolean, whole?: boolean): Promise<T>;
+    /** Private source-shape owner, not an authorization proof or generic Adapter
+     * capability. Only this actual adapter's native snapshot runner is used. */
+    capturePinnedReadSnapshot(dependencies: readonly PostgresReadDependency[], assertCurrent: () => void): Promise<PinnedPostgresReadOwner>;
+    private scopedTransact;
+    /**
+     * The statements a scoped transaction opens with, sent behind its BEGIN
+     * (openWrite's `sent`), from what it was told (writeAhead.ts) and the scope
+     * catalog read last time: the verifier's own (its fence), the journal's
+     * receipt lookup, and for each target its row lock, its row read in full
+     * through the scope (kept to answer its reads by key, keyRows.ts), and,
+     * where the write is captured for history, the capture's own lock and read
+     * (historyWrites). Each is exactly the statement the transaction sends in
+     * its turn, built by the same rules; one it never sends is left, counted,
+     * and changes nothing. None where the client does not pipeline.
+     */
+    private sendWriteAhead;
+    /**
+     * Internal runtime-owner composition, deliberately absent from Adapter: the
+     * PostgreSQL counterpart of `SqliteAdapter.runtimeMaintenanceTransaction`,
+     * for trusted runtime code (tenant administration) that composes its own
+     * bounded maintenance facades on the leased writer and the ordinary write
+     * queue. `verify` runs after BEGIN and again after the work's operations
+     * drain, before COMMIT; the synchronous `assertCurrent` handed to the work
+     * refuses once the transaction has ended. Raw handles must never reach
+     * business handlers, policies or request callbacks. Outcomes are the
+     * transaction contract's: unknown after COMMIT was sent or an unacknowledged
+     * ROLLBACK, and the client is discarded rather than reused.
+     */
+    runtimeMaintenanceTransaction<T>(verify: (client: PgQuery) => Promise<void>, run: (client: PgQuery, operations: TransactionOperations, assertCurrent: () => void) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+    private lockRecordNow;
+    /**
+     * Identifiers cannot be bound, so a table name is checked against the
+     * catalog before it is quoted into a statement. The check is a parameterised
+     * query, which means the untrusted string never reaches SQL as syntax.
+     */
+    /**
+     * The same check for a read, answered from the catalog read on connect when
+     * it holds the name. That probe was a round trip before every list and
+     * every count — two per page of rows, one per reference counted — to learn
+     * what the catalog already said. A name the catalog does not hold (made
+     * since) is still asked of the server; writes always are (assertTable),
+     * because a view created since connecting must still refuse one.
+     */
+    private readTable;
+    private epochOf;
+    private assertTable;
+}
+/** Trusted host verification on the writer of a verified scoped transaction:
+ * the scope catalog it was pinned and read with, and the adapter's own
+ * introspection on the same writer. */
+export type PostgresTransactionVerifier = {
+    (client: PgQuery, catalog: PostgresScopeCatalog, describe: () => Promise<DatabaseSchema>, epoch?: string): Promise<void>;
+    /**
+     * The verifier's own LOCK, without parameters, taken in the message that
+     * begins the transaction, after the scope's pin and before the schema epoch
+     * (or catalog digest) is read. The epoch then covers everything it pinned:
+     * DDL committed before it is in the epoch, DDL after it waits for this
+     * transaction. The verifier is handed that epoch as `epoch`, so a full
+     * attestation it made under the same epoch stands without being read again
+     * (tenantWriteSource.ts). A message that fails begins again plainly, and
+     * the verifier is handed no epoch.
+     */
+    readonly pin?: string;
+    /**
+     * The statements the verifier's first pass sends, exactly, sent behind the
+     * BEGIN with what else the transaction opens with (sendWriteAhead): each
+     * answers the identical statement once when the verifier sends it. A
+     * statement it does not send is left unread.
+     */
+    readonly ahead?: () => readonly PipelinedStatement[];
+};