@rebasepro/server-postgres 0.22.0 → 0.24.0

package/dist/services/realtimeService.d.ts

@@ -5,7 +5,7 @@ import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { RealtimeProvider, CollectionSubscriptionConfig, SingleSubscriptionConfig } from "../interfaces.js";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
 import { ChannelBus } from "./channel-bus/index.js";
-import type { ChannelRetentionRule } from "@rebasepro/types";
+import type { ChannelRetentionRule, RealtimeListenerHealth } from "@rebasepro/types";
 /**
  * Auth context stored per-subscription so real-time refetches respect RLS.
  * Mirrors the session variables set by PostgresBackendDriver.withAuth().
@@ -133,7 +133,11 @@ export type DataDriverSubscriptionRequest = {
  * last delivery *started* the last one *delivered*.
  */
 type Subscription = {
+    /** The id the client named it by — what every frame for it carries. */
+    subscriptionId: string;
     clientId: string;
+    /** The {@link SubscriptionGroup} whose refetch answers it. */
+    groupKey: string;
     type: "collection" | "single";
     path: string;
     id?: string | number;
@@ -150,6 +154,24 @@ type Subscription = {
     /** The highest started-sequence that has already reached the subscriber. */
     delivered: number;
 };
+/**
+ * The default ceiling on subscriptions one socket may hold.
+ *
+ * Each collection subscription is a refetch on every write to its collection;
+ * without a ceiling one socket could open tens of thousands and turn every
+ * write anyone made into as many transactions. The SDK shares identical
+ * subscriptions on a socket, so a real page holds one per distinct list or
+ * record on screen — the admin panel's tables, forms and reference previews
+ * stay well under this. See `REALTIME_MAX_SUBSCRIPTIONS_PER_SOCKET`.
+ */
+export declare const DEFAULT_MAX_SUBSCRIPTIONS_PER_SOCKET = 1000;
+/**
+ * Read a subscription ceiling, refusing anything that is not a positive whole
+ * number. A typo here does not fall back to a default: the ceiling is a limit
+ * someone chose, and silently running with another one is how it stops
+ * meaning anything.
+ */
+export declare function parseMaxSubscriptionsPerSocket(value: unknown, source: string): number;
 /**
  * PostgreSQL-specific realtime service.
  * Handles WebSocket connections and subscriptions for real-time row updates.
@@ -188,6 +210,8 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * wait on each other.
      */
     private channelSendQueues;
+    /** The receiving half of the same ordering: retained bus frames per channel, one at a time. */
+    private channelReceiveQueues;
     /**
      * Cross-instance transport for channel frames and presence.
      *
@@ -233,21 +257,46 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     /** How often stale roster rows from other instances are reaped. */
     private static readonly PRESENCE_SWEEP_INTERVAL_MS;
     private dataService;
+    /**
+     * Every subscription, by {@link subscriptionKey} — the client's own id
+     * qualified by the client that chose it.
+     *
+     * Keyed by the bare id, this was one namespace for every socket: two raw
+     * clients that both counted from `"sub-1"` replaced each other's
+     * subscription without a word, and either one's `unsubscribe` ended the
+     * other's.
+     */
     private _subscriptions;
+    /** In-process listeners' callbacks, by subscription key. */
     private subscriptionCallbacks;
+    /** Each client's subscriptions, by key — for its ceiling and its disconnect. */
+    private subscriptionsByClient;
+    /** Subscriptions one refetch answers — see {@link SubscriptionGroup}. */
+    private groups;
+    /**
+     * The collection groups on each path, and the single-row groups at each
+     * `path` + id: what a change looks up, instead of walking every
+     * subscription on the server once per changed row.
+     */
+    private collectionGroupsByPath;
+    private singleGroupsByAddress;
+    /**
+     * Every path a subscription holds, with the collection it lands on and how
+     * many hold it — the candidates `aliasPaths` considers, resolved once.
+     */
+    private subscribedPaths;
+    /**
+     * How many subscriptions one socket may hold; set from config at boot. See
+     * {@link DEFAULT_MAX_SUBSCRIPTIONS_PER_SOCKET}.
+     */
+    maxSubscriptionsPerSocket: number;
     private driver?;
     /** Unique identifier for this process instance, used to skip own notifications. */
     private readonly instanceId;
-    /** Dedicated pg.Client for LISTEN (outside the Drizzle pool). */
-    private listenClient?;
-    /** Connection string used for reconnecting the LISTEN client. */
-    private listenConnectionString?;
+    /** The LISTEN connection on {@link PG_NOTIFY_CHANNEL}, outside the Drizzle pool. */
+    private crossInstanceListener?;
     /** Whether cross-instance broadcasting is active. */
     private broadcasting;
-    /** Reconnection timer handle. */
-    private reconnectTimer?;
-    /** Debounce timers for collection refetches to prevent refetch storms. */
-    private refetchTimers;
     /** Debounce window (ms) for coalescing rapid row updates into a single correctness refetch. */
     private static readonly REFETCH_DEBOUNCE_MS;
     /** Dedicated LISTEN client for DB-level change events (undefined unless CDC is enabled). */
@@ -267,7 +316,19 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * and always flow through. Keyed → expiry timestamp (ms).
      */
     private recentAppEmits;
-    /** How long an app-emit key suppresses its own CDC echo. Covers NOTIFY round-trip latency. */
+    /**
+     * How long an app-emit key suppresses its own CDC echo: the refetch
+     * debounce, and no longer.
+     *
+     * The mark cannot tell an echo from another writer's change to the same
+     * row, and a save that touches no row of the table (a to-many relation
+     * only, an empty payload) is announced with no echo ever coming to consume
+     * it. Held for seconds, it swallowed the next change psql, a cron or
+     * another instance made to that row. Inside the debounce nothing is lost:
+     * the refetch the app emit scheduled has not started yet — its timer fires
+     * no earlier than this — and it reads after any commit whose NOTIFY has
+     * already arrived. An echo later than that costs one more refetch.
+     */
     private static readonly CDC_DEDUP_WINDOW_MS;
     constructor(db: NodePgDatabase<any>, registry: PostgresCollectionRegistry);
     /**
@@ -289,7 +350,50 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     private debugLog;
     setDataDriver(driver: DataDriver): void;
-    get subscriptions(): Map<string, Subscription>;
+    /**
+     * The live subscriptions by the id their client gave them — for tests and
+     * diagnostics. Two clients may use one id; this view shows the last.
+     */
+    get subscriptions(): ReadonlyMap<string, Subscription>;
+    /** The internal key of `subscriptionId` as `clientId` named it. */
+    private subscriptionKey;
+    /**
+     * The group a subscription's refetch belongs to. Socket subscriptions that
+     * would run the same read as the same principal share one; an in-process
+     * listener is always alone — see {@link SubscriptionGroup}.
+     */
+    private groupKeyFor;
+    /**
+     * Register (or replace) a subscription under `key`, in its group and in
+     * every index that finds it.
+     */
+    private registerSubscription;
+    /** Remove the subscription under `key` from everything that holds it. */
+    private dropSubscription;
+    /** Take `subscription` out of its group and path count; a group left empty goes, timer and all. */
+    private leaveGroup;
+    /**
+     * Ask for a refetch of `group` once changes have been quiet for the
+     * debounce window — for every member, or only for `member`.
+     *
+     * The window is measured from the last change, as a debounce is, but the
+     * timer is not re-armed per change: a 10k-row statement is 10k changes,
+     * and re-arming a timer per change per group was work in proportion to
+     * both. A change only moves the timestamp; the timer, when it fires early,
+     * waits out the rest.
+     */
+    private scheduleGroupRefetch;
+    private armGroupTimer;
+    /**
+     * One read for the group, delivered to each member it is for.
+     *
+     * Each member still claims its own delivery slot before the read and
+     * checks it after (see {@link beginDelivery}), so a member that left, was
+     * replaced or was overtaken while the read ran is skipped exactly as it
+     * was when it had a read of its own. A socket frame is serialised once and
+     * only its subscription id differs per member.
+     */
+    private refetchGroup;
     /**
      * Claim a delivery slot for a subscription, before doing the work.
      *
@@ -343,13 +447,27 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     subscribeToOne(subscriptionId: string, config: SingleSubscriptionConfig, callback?: (row: Record<string, unknown> | null) => void, onError?: (error: unknown) => void): void;
     /**
-     * Unsubscribe from a subscription (RealtimeProvider interface)
+     * Unsubscribe an in-process subscription (RealtimeProvider interface).
+     *
+     * By id alone, because the in-process callers hold nothing else — so a
+     * socket's subscription under the same id is not this one, and is left
+     * alone. A socket ends its own through the `unsubscribe` frame.
      */
     unsubscribe(subscriptionId: string): void;
     addClient(clientId: string, ws: WebSocket): void;
     handleClientMessage(clientId: string, message: WebSocketMessage, authContext?: SubscriptionAuthContext): Promise<void>;
     removeClient(clientId: string): Promise<void>;
     private handleMessage;
+    /**
+     * Refuse a new subscription past the socket's ceiling, and say so.
+     *
+     * Every collection subscription is a refetch on every write to its
+     * collection, so a socket allowed to open them without limit could turn
+     * each write anyone makes into tens of thousands of transactions. Replacing
+     * a subscription the socket already holds — the same id again — is not a
+     * new one and always passes. Returns whether the subscription may go ahead.
+     */
+    private admitSubscription;
     private handleCollectionSubscription;
     private handleEntitySubscription;
     /**
@@ -366,6 +484,29 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * synchronously, so nothing else can have answered the request yet.
      */
     private reportSocketFetchFailure;
+    /**
+     * Re-judge everything a socket holds open as the identity it has now.
+     *
+     * A socket re-authenticates on every session refresh, and when a role is
+     * taken away, a tenant claim removed or a different account signs in, the
+     * next token says so. Requests read as the new identity at once; the
+     * subscriptions kept refetching as the one they were opened with, so a
+     * demoted user went on receiving editor-only or another tenant's rows for
+     * as long as the view stayed mounted.
+     *
+     * Each of this client's subscriptions is replaced by one carrying the new
+     * identity — a replacement, so a refetch already running as the old one
+     * cannot deliver — and refetched, so the view narrows now rather than at
+     * the next write. A subscription whose filter, sort or projection names a
+     * field the new roles may not read is ended with the refusal a new
+     * subscription would get. Channel memberships are put to the authorizer
+     * again, when one is installed, and left when it refuses.
+     */
+    rescopeClient(clientId: string, authContext: SubscriptionAuthContext): Promise<void>;
+    /**
+     * End a socket's own subscription. Only its own: the id is the client's,
+     * so another socket's subscription under the same id is a different one.
+     */
     private handleUnsubscribe;
     /**
      * Enhanced notification method that handles nested relation updates.
@@ -415,15 +556,6 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * whether this subscriber may see the row at all.
      */
     private notifyPathUpdate;
-    /**
-     * Debounce a collection refetch for a WebSocket subscription.
-     * Coalesces rapid row mutations into a single database query.
-     */
-    private debouncedCollectionRefetch;
-    /**
-     * Debounce a collection refetch for a DataDriver callback subscription.
-     */
-    private debouncedDriverRefetch;
     /**
      * Tell an in-process listener its refetch failed, through the slot the
      * rows would have used.
@@ -453,19 +585,17 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * the total describes the same set they came from.
      */
     private collectionMetaWithAuth;
-    /**
-     * Debounce an row refetch for a WebSocket subscription.
-     */
-    private debouncedSingleRefetch;
-    /**
-     * Debounce an row refetch for a Driver callback subscription.
-     */
-    private debouncedSingleDriverRefetch;
     /**
      * Fetch a single row with optional RLS auth context.
      */
     private fetchEntityWithAuth;
     private sendCollectionUpdate;
+    /**
+     * Everything in a `collection_update` frame after its subscription id,
+     * serialised once for every member of a group: the same rows, keys and
+     * meta as {@link sendCollectionUpdate} sends, in the same order.
+     */
+    private collectionFrameTail;
     private sendSingleUpdate;
     /**
      * Send a lightweight row-level patch to a collection subscriber.
@@ -493,10 +623,36 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     private sendError;
     private sendMessage;
+    /**
+     * Send an already-serialised frame to a client, if it is still connected.
+     *
+     * Every frame to a socket goes through here, so this is where a client
+     * that does not read what it is sent is let go of — see
+     * {@link terminateIfBacklogged}. Terminated, it closes like any other
+     * socket, and {@link removeClient} drops what it held.
+     */
+    private sendRaw;
     /**
      * Extract parent paths from a nested path like "posts/70/tags"
      * Returns ["posts", "posts/70"] for the example above
      */
+    /**
+     * The other paths a subscriber can address the row written at `path` by.
+     *
+     * `authors/1/posts` and `posts` are two addresses for the same rows, and
+     * subscriptions were matched by the written path's exact string. So a post
+     * saved through `authors/1/posts` never reached a subscriber of `posts` or
+     * of `posts/43`, and one saved through `posts` never reached a subscriber
+     * of `authors/1/posts`, whose list it may just have joined or left.
+     *
+     * The aliases are the target collection's root path, and every nested path
+     * a live subscription holds that lands on the same collection. Each still
+     * refetches under its own scope and its own parent, so naming a path here
+     * decides only who is asked to look again — never what they are shown.
+     */
+    private aliasPaths;
+    /** The slug of the collection a path lands on, or `undefined` for one that names none. */
+    private collectionSlugAt;
     private getParentPaths;
     /**
      * Install a channel authorizer — see {@link ChannelAuthorizer}.
@@ -620,6 +776,7 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * its own `sid`.
      */
     private handleBusFrame;
+    private deliverBusFrame;
     /**
      * Install retention rules and create the tables they need.
      *
@@ -705,12 +862,20 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      *  1. All debounced refetch timers are cancelled (prevents queries after pool closes).
      *  2. All subscription state and callbacks are cleared.
      *  3. The dedicated LISTEN client (outside the pool) is disconnected.
-     *  4. All WebSocket clients are removed (but not forcefully closed — the
-     *     HTTP server close will handle that).
+     *  4. All WebSocket clients are closed with 1001 ("going away"); one that
+     *     does not answer the close frame is dropped after a short grace.
      */
     destroy(): Promise<void>;
-    /** Whether database-level change capture is currently the active source. */
+    /**
+     * Whether database-level change capture is the source and is listening.
+     *
+     * Configured is not enough: a CDC connection that went half-open used to
+     * leave this `true` while nothing arrived. False while the connection is
+     * down and being replaced.
+     */
     isCdcActive(): boolean;
+    /** The LISTEN connections this service depends on — see `RealtimeProvider.health`. */
+    health(): RealtimeListenerHealth[];
     /**
      * Enable database-level change capture as the realtime source.
      *
@@ -729,6 +894,18 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      *                         (bypass PgBouncer — LISTEN needs a session connection).
      */
     enableCdc(connectionString: string): Promise<void>;
+    /**
+     * Refetch every live subscription, as a change to its path would.
+     *
+     * Called when a LISTEN connection (CDC, or the cross-instance broadcast)
+     * is listening again after a drop. Postgres does not queue NOTIFY for a
+     * session that is not listening, so every change committed while it was
+     * down — by another instance, psql, a cron — reached nobody here, and a
+     * subscriber held its pre-gap rows until some later change to the same
+     * collection happened to arrive. Each refetch runs under the
+     * subscription's own scope, so this decides only who looks again.
+     */
+    private resyncSubscriptions;
     /** Stop the CDC listener and clear its state. */
     stopCdc(): Promise<void>;
     /**
@@ -742,8 +919,8 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     /**
      * Route a captured database change into the realtime pipeline.
      *
-     * Delivery is RLS-safe by construction: the raw tuple from the WAL/trigger is
-     * NOT forwarded to subscribers. Instead the change is marked invalidated, so
+     * Delivery is RLS-safe by construction: the event carries the changed row's
+     * key and nothing else, and even that is NOT forwarded to subscribers. Instead the change is marked invalidated, so
      * every matching subscription re-reads the row under its own auth context via
      * {@link fetchCollectionWithAuth} / {@link fetchEntityWithAuth}. A subscriber
      * therefore only ever receives rows its RLS policies permit — filtering is per
@@ -769,6 +946,16 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     private handleJunctionCdcEvent;
     /** Compute the canonical (possibly composite) id string from a captured row. */
     private extractIdFromCdcRow;
+    /**
+     * A captured row with its key under the key's *field* names.
+     *
+     * The trigger captures the tuple by column — `user_id` — and an address is
+     * built from the key's property names — `userId`. Read by property name
+     * alone, a key declared apart from its column was never on the captured
+     * row, the address fell back to `*`, and no single-row subscriber heard
+     * about any write made outside this server.
+     */
+    private cdcRowByKeyFields;
     private dedupKey;
     /** Record that this instance just delivered `key` via the app path. */
     private markAppEmit;
@@ -776,8 +963,15 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     private consumeAppEmit;
     /**
      * Enable cross-instance realtime broadcasting via Postgres LISTEN/NOTIFY.
-     * Creates a dedicated pg.Client (outside the Drizzle pool) that stays
-     * connected and listens for change notifications from other instances.
+     * Listens on a dedicated connection (outside the Drizzle pool) for the
+     * changes other instances publish, through a {@link PgNotifyListener}: it
+     * proves itself with a heartbeat, is replaced when it drops or stops
+     * answering, and every subscription is refetched once it is back, since
+     * whatever was published meanwhile reached nobody here.
+     *
+     * A database that cannot be reached at boot does not fail this call: the
+     * listener reports itself down (see {@link health}) and keeps dialling.
+     * There is no other cross-instance path to fall back to.
      *
      * This is an **optional** feature — if never called, the backend operates
      * in single-instance mode (the default, perfectly fine for most setups).
@@ -794,14 +988,8 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * Uses the main Drizzle connection (pooled) — NOT the LISTEN client.
      */
     private broadcastChange;
-    /**
-     * Create and connect the dedicated LISTEN client with auto-reconnect.
-     */
-    private connectListenClient;
-    /**
-     * Schedule a reconnection attempt with a fixed 3s delay.
-     */
-    private scheduleReconnect;
+    /** One change another instance published on {@link PG_NOTIFY_CHANNEL}. */
+    private handleCrossInstanceNotification;
 }
 /**
  * Alias for RealtimeService for consistent naming with other database implementations.

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

@@ -59,6 +59,11 @@ export declare function toRestValues(row: Record<string, unknown>, collection: C
  * an `update` that echoes the row back overwrite the real value with the null it
  * was handed.
  *
+ * A withheld to-one relation takes its foreign key with it. `bandId: 7` names
+ * the salary band exactly as `band: { id: 7 }` does, and the row carries the
+ * column beside the relation — so withholding only the relation withheld
+ * nothing.
+ *
  * `_matches` is filtered rather than deleted: it is the list of fields a text
  * search hit, and a field the caller cannot read must not appear in it even
  * though the array itself is theirs to see.

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

@@ -0,0 +1,45 @@
+/**
+ * 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. 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;
+/**
+ * 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.
+ */
+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.
  *
@@ -23,8 +24,6 @@ import type { CollectionConfig } from "@rebasepro/types";
  * (`assertCollectionConfigs`), where the answer is a config change, rather than
  * at the first delete, where it would be a 500 for whoever pressed the button.
  */
-/** The default field, when `softDelete: true` names none. */
-export declare const DEFAULT_SOFT_DELETE_FIELD = "deletedAt";
 /** How a caller asks about deleted rows. See `FetchCollectionProps.withDeleted`. */
 export type WithDeleted = boolean | "only" | undefined;
 export interface SoftDeleteField {
@@ -71,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,71 @@
+import type { Pool, PoolClient } from "pg";
+import type { SqlScriptResult } from "@rebasepro/types";
+/**
+ * `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>;
+}
+/**
+ * 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>[]): SqlScriptResult;

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

@@ -0,0 +1,16 @@
+/**
+ * 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>;

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

@@ -1,4 +1,5 @@
 import { type AmbientTransaction } from "@rebasepro/server";
+import type { RebaseCallContext } from "@rebasepro/types";
 import type { DrizzleClient } from "../interfaces.js";
 type RunSql = (sqlText: string, params?: unknown[]) => Promise<Record<string, unknown>[]>;
 /**
@@ -24,6 +25,10 @@ export declare class WriteTransactionScope implements AmbientTransaction {
     private open;
     private readonly inflight;
     private readonly commitHooks;
+    /** The first tracked statement that failed, whether or not its caller caught it. */
+    private failure?;
+    private readonly settledHooks;
+    private settledContext?;
     /** The transaction handle, for statements in this package that are already written against drizzle. */
     tx?: DrizzleClient;
     /** Attach the transaction, once it has begun. */
@@ -49,6 +54,43 @@ export declare class WriteTransactionScope implements AmbientTransaction {
      * connection, as if outside any write.
      */
     settle(): Promise<void>;
+    /**
+     * Refuse to commit a transaction a failed statement has aborted.
+     *
+     * Once any statement fails, Postgres aborts the whole transaction, and
+     * catching the error in JavaScript does not undo that. The COMMIT that
+     * follows is answered with the tag `ROLLBACK` and no error, so the driver
+     * resolves it: the write reported success — 200, webhooks, realtime,
+     * the idempotency record — while nothing was stored. A callback that
+     * wrapped a lookup or a job enqueue in `try/catch` was enough.
+     *
+     * 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. 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>;
+    /**
+     * 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
+     * own. The write's transaction is gone by the time the hook runs, so a
+     * context bound to it would be bound to a connection back in the pool.
+     */
+    setSettledContext(context: RebaseCallContext): void;
+    /**
+     * Run `fn` once this write's transaction is over, whichever way it went,
+     * outside it — for what a failure hook hands off (a job, a queue message,
+     * a webhook), which must not ride the transaction the failure rolls back.
+     * `false` when this scope has no context to hand it; the caller runs it
+     * itself then.
+     */
+    afterSettled(fn: (context: RebaseCallContext) => Promise<void>): boolean;
+    /** The transaction committed or rolled back: run what was waiting for either. */
+    settled(): Promise<void>;
     /**
      * The transaction is over, whichever way it went. Nothing may reach it now:
      * its client is back in the pool, and a callback's detached promise still