@rebasepro/server-postgres 0.23.0 → 0.24.1-canary.g56af4a4

package/dist/services/row-pipeline.d.ts

@@ -29,15 +29,6 @@ export type RelationStyle = "ref" | "inline";
  * to unwrap that same level back out.
  */
 export declare function isJunctionRelation(relation: ResolvedRelation): boolean;
-/**
- * Apply {@link toRestScalar} across a row, leaving undeclared columns alone.
- *
- * Exported because the include loader attaches related rows itself, and a
- * target rendered differently from its parent is the shape bug this whole file
- * exists to prevent — a date was a string at the top level and a
- * `{ __type: "date" }` envelope one level down, in the same response.
- */
-export declare function toRestValues(row: Record<string, unknown>, collection: CollectionConfig): Record<string, unknown>;
 /** Render one target row in the requested style. */
 /**
  * Drop every column this caller may not read.
@@ -69,6 +60,22 @@ export declare function toRestValues(row: Record<string, unknown>, collection: C
  * though the array itself is theirs to see.
  */
 export declare function stripUnreadable(row: Record<string, unknown>, collection: CollectionConfig): Record<string, unknown>;
+/**
+ * May the current caller be handed the rows of this relation of `collection`?
+ *
+ * A relation property's value *is* its related rows, so a property the caller
+ * may not read withholds the relation whole: an `include` neither loads it nor
+ * counts it. {@link stripUnreadable} cannot be the only guard here, because the
+ * REST rows are stripped before the include loader runs (`toRestRow`, then
+ * `loadIncludes`) — the loader wrote the rows back onto the key the strip had
+ * just deleted, and `_count` beside them.
+ *
+ * Judged by every `type: "relation"` property that names this relation: by its
+ * own key (the include key of an inline relation), or by the `relationName` it
+ * addresses in the collection's `relations` array. A relation declared only in
+ * `relations` has no property, so no field rule, and stays readable.
+ */
+export declare function canReadRelation(collection: CollectionConfig, key: string, relation: ResolvedRelation): boolean;
 /**
  * The address a relation ref points at.
  *

package/dist/services/socket-liveness.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Letting go of client sockets the server can no longer reach.
+ *
+ * A phone that loses signal, a laptop that sleeps, a NAT that forgets the
+ * connection: the peer is gone, and nothing tells the server. No close frame
+ * arrives and no FIN, so the socket stays open until the operating system gives
+ * up on the TCP connection — about two hours on Linux. Meanwhile every
+ * subscription it holds is refetched on every write to its collection, and
+ * every frame for it is serialised into a send buffer nobody drains.
+ *
+ * Two checks catch it. The socket must answer a ping: one that has not answered
+ * by the next is terminated. And it must read what it is sent: one whose unsent
+ * backlog passes {@link MAX_SOCKET_BUFFERED_BYTES} is terminated at the next
+ * frame for it, and when all of the process's sockets together hold more than
+ * {@link MAX_PROCESS_BUFFERED_BYTES}, the ones with the largest backlogs go
+ * first. A terminated socket closes like any other, so the realtime service
+ * drops its subscriptions, channels and presence on its `close`.
+ */
+import { WebSocket, type WebSocketServer } from "ws";
+/**
+ * How often every socket is pinged. A socket that has not answered one ping by
+ * the next is terminated, so a peer that vanished is let go of within two
+ * intervals. Every browser and `ws` client answers a ping by itself.
+ */
+export declare const SOCKET_PING_INTERVAL_MS = 30000;
+/**
+ * The unsent bytes a socket may have queued before it is terminated.
+ *
+ * A healthy client drains its queue as fast as the network allows; one whose
+ * backlog keeps growing is not reading, or is so far behind that what it would
+ * read is stale. Set well above a single frame — the largest body the data API
+ * accepts is 10 MiB, and a list frame can approach it — so a burst of large
+ * frames to a client that is keeping up does not trip it. A terminated client
+ * reconnects and resubscribes, which brings it up to date with one frame per
+ * subscription instead of the backlog.
+ */
+export declare const MAX_SOCKET_BUFFERED_BYTES: number;
+/**
+ * The unsent bytes all of this process's sockets may hold between them before
+ * the ones with the largest backlogs are terminated.
+ *
+ * The per-socket ceiling alone bounds nothing for the process: a hundred slow
+ * phones during a bulk-update storm could each sit just under it, 1.6 GB of
+ * frames between them, before any one was let go. A healthy socket's backlog
+ * is close to nothing — the kernel takes a frame as it is written — so a
+ * process holding this much unread is already in a storm. 256 MiB is sixteen
+ * sockets at their own ceiling, and an eighth of a 2 GiB container; under a
+ * smaller memory limit it is a quarter of that limit (see
+ * {@link processSendBudget}).
+ */
+export declare const MAX_PROCESS_BUFFERED_BYTES: number;
+/**
+ * The process-wide budget: {@link MAX_PROCESS_BUFFERED_BYTES}, or a quarter of
+ * the memory limit the process runs under when that is smaller — never less
+ * than one socket's own ceiling. `constrained` is the limit in bytes, 0 for
+ * none, as `process.constrainedMemory()` reports it.
+ */
+export declare function processSendBudget(constrained?: number): number;
+/**
+ * Count the sockets of `wss` in the process-wide send budget. Returns the
+ * function that stops counting them, for when the server closes.
+ */
+export declare function budgetSendBuffers(wss: WebSocketServer): () => void;
+/**
+ * Terminate sockets, largest backlog first, until what this process's sockets
+ * hold unread between them is back within `budget`. Returns the sockets it
+ * terminated. A terminated socket closes like any other, and its client
+ * reconnects and re-subscribes: one fresh frame per subscription, instead of
+ * the backlog.
+ */
+export declare function enforceProcessSendBudget(budget?: number): WebSocket[];
+/**
+ * Ping every socket of `wss` each `intervalMs`, and terminate the ones that did
+ * not answer the previous ping. Returns the function that stops it.
+ */
+export declare function reapSilentSockets(wss: WebSocketServer, intervalMs?: number): () => void;
+/**
+ * Terminate `ws` if its unsent backlog has passed {@link MAX_SOCKET_BUFFERED_BYTES}.
+ * Returns whether it did; the caller then sends nothing.
+ *
+ * Every frame in and out of a socket comes through here, so this is also where
+ * the process-wide budget is kept, summed at most every
+ * {@link PROCESS_BUDGET_CHECK_MS} — see {@link enforceProcessSendBudget}.
+ */
+export declare function terminateIfBacklogged(ws: WebSocket, clientId: string): boolean;

package/dist/services/soft-delete.d.ts

@@ -1,6 +1,7 @@
 import { SQL } from "drizzle-orm";
 import type { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
 import type { CollectionConfig } from "@rebasepro/types";
+import { ApiError } from "@rebasepro/server";
 /**
  * Soft delete, in one place.
  *
@@ -69,3 +70,14 @@ export declare function withSoftDelete(conditions: SQL[], collection: Collection
  * For the call sites that hold one composed condition rather than a list.
  */
 export declare function andSoftDelete(where: SQL | undefined, collection: CollectionConfig | undefined, table: PgTable, withDeleted?: WithDeleted): SQL | undefined;
+/**
+ * The refusal of an upsert whose key belongs to a row in the trash.
+ *
+ * The key is taken — the stamped row still holds it — so the write cannot be a
+ * create, and an upsert is not the operation that brings a deleted row back:
+ * that is the restore, an update setting the field to `null`, which goes
+ * through the update gate and is what history records as one. Left to the
+ * statement, `INSERT … ON CONFLICT DO UPDATE` wrote the new values into the
+ * hidden row and the caller was told "created", with the row still in the trash.
+ */
+export declare function rowInTrashError(path: string, key: string, softDelete: SoftDeleteField): ApiError;

package/dist/services/sql-script.d.ts

@@ -0,0 +1,275 @@
+import { type Connection, type Pool, type PoolClient, type Submittable } from "pg";
+import type { SqlCursor, SqlScriptResult } from "@rebasepro/types";
+/**
+ * Running a SQL script a person wrote — the Studio console — and saying what
+ * came back, column by column.
+ *
+ * The console used to receive bare rows and guess, from the query's text, which
+ * table a cell belonged to and which column held its key. The guess wrote
+ * `UPDATE authors SET name = … WHERE id = <the post's id>` for a cell of
+ * `SELECT p.id, a.name FROM posts p JOIN authors a …`, and `UPDATE users SET
+ * name = …` for `lower(email) AS name`. The database knows the answer: every
+ * column of a result's row description carries the table and column it was
+ * read from, or zero when it was computed. This reads it off the wire.
+ *
+ * Values come back as the text the database wrote, never parsed. Parsed, a
+ * `text[]` read as a JavaScript array and went back as JSON — a malformed array
+ * literal; a `bytea` as a serialized Buffer; a `timestamp` as a Date shifted by
+ * the server's timezone; a `numeric` as a float. Text is what the database
+ * reads back exactly.
+ */
+/** The parts of a `RowDescription` field this reads. */
+interface WireField {
+    name: string;
+    /** The OID of the table the column was read from; 0 when it was computed. */
+    tableID: number;
+    /** Its attribute number in that table; 0 when it was computed. */
+    columnID: number;
+    dataTypeID: number;
+}
+/** One statement of the script, as it came back. */
+export interface StatementOutcome {
+    fields: WireField[];
+    rows: Record<string, string | null>[];
+    /** How many rows the database sent for it, kept or not. */
+    received: number;
+    /** Rows past the {@link SqlResultLimits} were counted and not kept. */
+    truncated: boolean;
+    /** The command tag, e.g. `SELECT 3`, `INSERT 0 1`, `CREATE TABLE`. */
+    tag?: string;
+}
+/** How much of one statement's result a run keeps. */
+export interface SqlResultLimits {
+    /** Rows kept; the rest are counted and let go. */
+    maxRows: number;
+    /** Characters of values kept, summed over the kept rows. */
+    maxTextLength: number;
+}
+/**
+ * What the Studio console keeps of a result: its first 10,000 rows, or its
+ * first 32 Mi characters of values, whichever ends first.
+ *
+ * Every row used to be kept. `TABLE events` on a million rows held 418 MB of
+ * row objects and built a 475 MB frame, and a server with 1 GiB died of it —
+ * every other user's connection with it. Ten times the console's own
+ * `LIMIT 1000`, so a run that asked for a page always gets it whole; the text
+ * budget is for the rows a count does not bound — a document column, a
+ * `jsonb` blob — and keeps the frame, the string it is built from and the
+ * socket's copy of it around 100 MB at worst.
+ *
+ * Postgres still sends every row (a simple query cannot be stopped short of
+ * cancelling it, which would abort the statements after it); they are counted,
+ * so the result says how many there were.
+ */
+export declare const SQL_CONSOLE_RESULT_LIMITS: SqlResultLimits;
+/**
+ * The script, sent as one simple query and read message by message.
+ *
+ * A `Submittable` rather than `client.query(text)`: node-postgres parses every
+ * value through its type parsers and drops each field's origin, and for a
+ * multi-statement script returns an array the driver's callers took for a
+ * result with no rows. The message handlers below are the ones node-postgres
+ * calls on the active query — the same protocol `pg-cursor` implements.
+ */
+export declare class ScriptRun implements Submittable {
+    private readonly text;
+    private readonly limits;
+    /**
+     * Set by node-postgres when the pool has a `query_timeout`: a wrapper that
+     * clears its read timer. Called on every outcome, so the timer never
+     * outlives the run.
+     */
+    callback?: (error: Error | null) => void;
+    /**
+     * Every statement of the script, as it came back. Only the last holds its
+     * rows: the console shows the last, and a statement's rows are let go when
+     * the next one begins — `SELECT * FROM big; SELECT 1` held every row of
+     * `big` to the end, to show one.
+     */
+    readonly statements: StatementOutcome[];
+    readonly done: Promise<StatementOutcome[]>;
+    /** The statement whose row description arrived and whose command has not completed. */
+    private open?;
+    /** What {@link open} has kept of its rows. */
+    private budget;
+    private settled;
+    private resolveRun;
+    private rejectRun;
+    constructor(text: string, limits?: SqlResultLimits);
+    submit(connection: Connection): void;
+    handleRowDescription(message: {
+        fields: WireField[];
+    }): void;
+    handleDataRow(message: {
+        fields: (string | null)[];
+    }): void;
+    handleCommandComplete(message: {
+        text: string;
+    }): void;
+    handleEmptyQuery(): void;
+    handlePortalSuspended(): void;
+    /**
+     * `COPY … FROM STDIN` waits for data the console has no way to send. Fail
+     * the copy rather than leave the session waiting for it.
+     */
+    handleCopyInResponse(connection: Connection): void;
+    handleCopyData(): void;
+    handleError(error: Error): void;
+    handleReadyForQuery(): void;
+    /** Let go of the rows of the statement before the one beginning: only the last is shown. */
+    private releaseRows;
+    private settle;
+}
+/**
+ * `INSERT 0 1` → `INSERT`, 1. `CREATE TABLE` → `CREATE TABLE`, no count.
+ *
+ * Only the commands whose tag ends in a count have one; the numbers are
+ * stripped from the end of every other tag, of which there are none.
+ */
+export declare function parseCommandTag(tag: string | undefined): {
+    command?: string;
+    rowCount?: number;
+};
+/**
+ * What puts a session back after caller SQL: the session user and role, then
+ * every setting. Two statements, because the extended protocol refuses a
+ * multi-command string. Pinned settings (`search_path` from the connection's
+ * startup options) come back as they were pinned.
+ */
+export declare const RESET_SESSION_STATEMENTS: readonly ["SET SESSION AUTHORIZATION DEFAULT", "RESET ALL"];
+/**
+ * A connection's transaction state, as its last ReadyForQuery reported it:
+ * `I` idle, `T` in a transaction, `E` in a failed one. `null` when the client
+ * does not say (node-postgres has since 8.16; the package requires 8.22).
+ */
+export declare function transactionStatus(connection: object): string | null;
+/**
+ * SQL a person ran began a transaction and did not end it.
+ *
+ * Each run is a session of its own, so a transaction cannot outlive the run
+ * that began it: a `BEGIN` alone, then an `UPDATE` in the next run, then a
+ * `ROLLBACK` in a third, committed the UPDATE and reported three successes.
+ * Refused instead, with the transaction rolled back.
+ */
+export declare class SqlTransactionLeftOpenError extends Error {
+    readonly code = "SQL_TRANSACTION_LEFT_OPEN";
+    constructor();
+}
+export interface OwnSessionOptions {
+    /**
+     * Put the session in the role the SQL runs as. Called once, before it, at
+     * session level — so the role holds for every statement, a `COMMIT` in the
+     * middle included. `SET LOCAL ROLE` inside a wrapping transaction did not:
+     * the caller's `COMMIT` ended that transaction, and every statement after
+     * it ran as the connection owner.
+     */
+    assumeRole?: (connection: PoolClient) => Promise<void>;
+    /**
+     * Cancels the run when aborted: the statement in progress is stopped with
+     * `pg_cancel_backend`, and the run fails with the database's "canceling
+     * statement due to user request". A signal already aborted runs nothing.
+     */
+    signal?: AbortSignal;
+}
+/** A run whose signal was aborted before it began. */
+export declare class SqlRunCancelledError extends Error {
+    readonly code = "SQL_RUN_CANCELLED";
+    constructor();
+}
+/**
+ * Run `work` — SQL a person wrote — on a connection of its own from `pool`,
+ * and put the connection back the way it was handed out.
+ *
+ * A transaction the SQL left open is rolled back, and the run refused with
+ * {@link SqlTransactionLeftOpenError}; a run that failed with one open says
+ * that it was rolled back. The session is then reset — role, session
+ * authorization, settings — and destroyed instead when it cannot be. Last,
+ * `afterReset` reads what it needs on the clean session, as the owner.
+ */
+export declare function onOwnSession<T>(pool: Pool, options: OwnSessionOptions, work: (connection: PoolClient) => Promise<T>, afterReset?: (connection: PoolClient, value: T) => Promise<T>): Promise<T>;
+/**
+ * Run `sql` on a connection of its own from `pool` and return what the last
+ * statement returned, with each column's provenance and what the database
+ * said along the way — `there is no transaction in progress` for a ROLLBACK
+ * with nothing to roll back, which used to read as success.
+ */
+export declare function runSqlScriptOnPool(pool: Pool, sql: string, options?: OwnSessionOptions): Promise<SqlScriptResult>;
+/**
+ * The same shape for rows that came back parsed, from a handle that is not a
+ * pool (PGlite in process): every value as text, and no column with a source —
+ * nothing to say where a value came from, so nothing the console will edit.
+ */
+export declare function sqlScriptResultFromRows(rows: Record<string, unknown>[], limits?: SqlResultLimits): SqlScriptResult;
+/**
+ * How many bytes of rows one answer of the admin `executeSql` door — the
+ * WebSocket `EXECUTE_SQL` without `mode: "script"` — may carry: 128 MiB.
+ *
+ * That door had no limit at all. A million-row `SELECT` held every row parsed
+ * (432 MB of heap on the console's door before it was capped), then built the
+ * frame from them, and a server with 1 GiB died of it — with every other
+ * user's connection. Unlike the console's script door it does not keep a
+ * prefix: a program reading rows through it would take a prefix for the whole
+ * answer, so past the budget the answer is refused, {@link SqlResultTooLargeError}.
+ *
+ * Generous on purpose. The catalogue reads the admin UI makes through this door
+ * are far below it — the SQL console's schema browser reads one
+ * `information_schema.columns` row per column, 7 MB for the 100,000 columns of
+ * 5,000 tables — and anything near it is a result no browser tab should hold.
+ */
+export declare const SQL_RESULT_BYTE_BUDGET: number;
+/**
+ * A result larger than the bytes its caller allowed, refused rather than
+ * returned in part. Its message is for the person who wrote the SQL.
+ */
+export declare class SqlResultTooLargeError extends Error {
+    readonly limitBytes: number;
+    readonly code = "RESULT_TOO_LARGE";
+    constructor(limitBytes: number);
+}
+/**
+ * Refuse rows that came back whole and are past `maxBytes`.
+ *
+ * Where nothing could watch the read, it is measured once done — and the
+ * answer still refused rather than sent.
+ */
+export declare function refuseOversizedRows<T extends Record<string, unknown>>(rows: T[], maxBytes: number): T[];
+/**
+ * Run `work` — one query on `connection` — and stop reading once its rows pass
+ * `maxBytes`.
+ *
+ * node-postgres keeps every row of a query until the query completes, and a
+ * simple query cannot be stopped short of its end, so the only way to stop
+ * holding rows is to stop receiving them: the socket is closed. Postgres sees
+ * its client gone and abandons the statement; the session — and anything it
+ * held — goes with it, and `onOwnSession` destroys the connection rather than
+ * return it to the pool. What the caller gets is {@link SqlResultTooLargeError},
+ * never the rows read so far.
+ *
+ * Counted from the wire, message by message, as they arrive: what is held when
+ * it stops is the budget plus one network read.
+ */
+export declare function readWithinBudget<T extends Record<string, unknown>>(connection: PoolClient, maxBytes: number, work: () => Promise<T[]>): Promise<T[]>;
+/** Rows one read of a {@link SqlCursor} fetches. */
+export declare const SQL_CURSOR_BATCH_ROWS = 1000;
+/**
+ * Open a cursor over ONE query a person wrote — the SQL console's "Download
+ * full result as CSV".
+ *
+ * On a connection of its own, in the role asked for, inside
+ * `BEGIN TRANSACTION READ ONLY`: the database refuses a write, a
+ * data-modifying `WITH` and a function that writes. The query is declared over
+ * the extended protocol, which refuses a second statement — `SELECT 1; DROP
+ * TABLE t` cannot ride along. Rows are then fetched {@link SQL_CURSOR_BATCH_ROWS}
+ * at a time, each `FETCH` under the session's `statement_timeout`; nothing
+ * fetches ahead of the reader, so memory holds one batch. The first batch is
+ * read here, so a query that fails on its first rows fails before anything has
+ * been sent.
+ *
+ * The caller closes the cursor — always. A reader that stops reading without
+ * closing is ended by `idle_in_transaction_session_timeout` after
+ * {@link SQL_CURSOR_IDLE_TIMEOUT_MS}.
+ */
+export declare function openSqlCursorOnPool(pool: Pool, sql: string, options?: OwnSessionOptions & {
+    batchRows?: number;
+}): Promise<SqlCursor>;
+export {};

package/dist/services/vector-iterative-scan.d.ts

@@ -0,0 +1,40 @@
+import type { DrizzleClient } from "../interfaces.js";
+/**
+ * pgvector's iterative index scans, for a vector read that also filters.
+ *
+ * An HNSW index answers a nearest-neighbour query with the `hnsw.ef_search`
+ * (40 by default) candidates it found, and every other condition of the query
+ * — a `where`, a search, a soft-delete stamp, a row-level-security policy — is
+ * applied to those candidates afterwards. Where few of them pass, the page
+ * comes back short, or empty, though plenty of rows match: measured on 20,000
+ * rows with half of them matching a `status` filter far from the query vector,
+ * `LIMIT 10` served 0 rows. Offset pages over the index were empty or short the
+ * same way, while deeper pages, where the planner switched to an exact scan,
+ * served rows, so a walk skipped some and could repeat others.
+ *
+ * From pgvector 0.8.0, `hnsw.iterative_scan` makes the index keep scanning
+ * until the query has its rows (bounded by `hnsw.max_scan_tuples`, 20,000 by
+ * default). `strict_order` and not `relaxed_order`: the planner reads the
+ * index's output as already sorted by distance, so out-of-order rows would be
+ * cut at the wrong place by `LIMIT` and the same row could land on two pages.
+ * Measured on the case above: 0/10 → 10/10, and the first 200 rows by offset
+ * pages of 10 with no duplicates (`relaxed_order`: 18).
+ *
+ * Set with `set_config(…, true)` — local to the transaction the read runs in,
+ * so it never outlives it on a pooled connection. A read not in a transaction
+ * is given one.
+ *
+ * pgvector before 0.8.0 has no such setting, and with its library loaded it
+ * refuses an unknown `hnsw.` parameter, so the setting is applied only where
+ * the extension's version has it; there a filtered vector read keeps the
+ * behaviour above. IVFFlat indexes are not touched: their iterative scan only
+ * comes in relaxed order.
+ */
+/** Whether a pgvector version (`extversion`, e.g. `"0.8.1"`) has iterative index scans. */
+export declare function hasIterativeIndexScans(version: string | undefined | null): boolean;
+/** Whether `db`'s pgvector has iterative index scans. Asked once per `key`. */
+export declare function iterativeScansAvailable(db: DrizzleClient, key: object): Promise<boolean>;
+/** Whether `db` is a transaction, in which a `set_config(…, true)` stays. */
+export declare function inTransaction(db: DrizzleClient): boolean;
+/** Turn on strict-order iterative HNSW scans for the rest of `db`'s transaction. */
+export declare function enableIterativeScan(db: DrizzleClient): Promise<void>;

package/dist/services/write-depth.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Deep enough for any chain that ends (a hook writing another collection whose
+ * hook writes a third is depth 3), shallow enough that a loop stops at once.
+ */
+export declare const MAX_WRITE_DEPTH = 16;
+/** One write in progress, and which of its hooks is running. */
+export interface WriteFrame {
+    readonly path: string;
+    readonly operation: "save" | "delete";
+    readonly depth: number;
+    readonly parent: WriteFrame | undefined;
+    /** The hook running right now — what a nested write was started from. */
+    stage: string | undefined;
+}
+/** Run one write as a frame, refusing it when the chain is already too deep. */
+export declare function inWriteFrame<T>(path: string, operation: "save" | "delete", fn: (frame: WriteFrame) => Promise<T>): Promise<T>;
+/**
+ * How deep in hook-started writes the code running now is: 0 outside any
+ * write, 1 inside a write a caller started, 2 or more inside a write a hook of
+ * another write started (`context.data`).
+ */
+export declare function currentWriteDepth(): number;

package/dist/services/write-transaction-scope.d.ts

@@ -28,6 +28,8 @@ export declare class WriteTransactionScope implements AmbientTransaction {
     /** The first tracked statement that failed, whether or not its caller caught it. */
     private failure?;
     private readonly settledHooks;
+    /** Whether application code (a hook) has run on this transaction. See {@link noteApplicationCode}. */
+    private applicationCodeRan;
     private settledContext?;
     /** The transaction handle, for statements in this package that are already written against drizzle. */
     tx?: DrizzleClient;
@@ -66,11 +68,21 @@ export declare class WriteTransactionScope implements AmbientTransaction {
      *
      * So one statement is asked of the transaction before its commit. On an
      * aborted one it fails with `25P02`, and the write is refused and rolled
-     * back instead. A failed `context.data` write is not caught by this: it
-     * runs in a savepoint, is undone on its own, and leaves the transaction
-     * usable — which is what makes catching one safe.
+     * back instead. The database refusing a `context.data` create, update or
+     * delete is not caught by this: each of those statements runs in a
+     * savepoint, is undone on its own, and leaves the transaction usable —
+     * which is what makes catching one safe. (Deletes ran without one, so a
+     * caught refused delete landed here, under a message saying catching it
+     * was safe.)
      */
     assertCommittable(): Promise<void>;
+    /**
+     * Application code — a collection, global or property hook, a
+     * `beforeQuery` — is about to run on this transaction, so it may catch a
+     * failed statement and leave the transaction aborted: the commit then has
+     * to ask ({@link assertCommittable}).
+     */
+    noteApplicationCode(): void;
     /**
      * What a hook deferred with {@link afterSettled} is handed as `context`:
      * the same caller, on a driver where every call is a transaction of its