@rebasepro/server-postgres 0.23.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). */
@@ -301,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.
      *
@@ -355,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;
     /**
@@ -397,6 +503,10 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * 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.
@@ -446,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.
@@ -484,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.
@@ -524,6 +623,15 @@ 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
@@ -668,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.
      *
@@ -757,8 +866,16 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      *     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.
      *
@@ -802,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
@@ -846,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).
@@ -864,18 +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.
-     *
-     * @param reconnect Set when the client is coming back from a drop: every
-     *        notification published in the gap is gone, so the subscriptions
-     *        are refetched once it is listening again.
-     */
-    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/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.
  *
@@ -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,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

@@ -66,9 +66,12 @@ 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>;
     /**

package/dist/utils/drizzle-conditions.d.ts

@@ -48,6 +48,18 @@ export type UnknownFilterFieldsMode = "error" | "warn";
  * documented input.
  */
 export declare const escapeLikePattern: (value: string) => string;
+/**
+ * A table's column by the name a `joinPath` step gives it — the SQL column — or
+ * by its Drizzle property key.
+ *
+ * A column has two names. A generated schema keys a collection table's columns
+ * by property (`orderId: uuid("order_id")`) while a step names the column
+ * (`from: "order_id"`), so a lookup by key alone found nothing on a real app,
+ * and the hand-written fixtures — keyed by column name — never showed it.
+ * Junction tables are generated keyed by column name, which is why a
+ * many-to-many was unaffected.
+ */
+export declare function joinColumn(table: PgTable<any>, name: string): AnyPgColumn | undefined;
 /** Set the process-wide behaviour for unresolvable filter fields. */
 export declare function configureUnknownFilterFields(mode: UnknownFilterFieldsMode): void;
 /** The process-wide behaviour for unresolvable filter fields. */
@@ -171,11 +183,24 @@ export declare class DrizzleConditionBuilder {
      * foreign key are expressible from the parent's *id* alone, and
      * requiring the table for them would make a child listing fail on a
      * parent whose table isn't registered.
+     *
+     * `key` is the parent row's key, every column with its value: those
+     * three shapes find the parent row itself, and a lookup on the first
+     * column of a composite key finds every row that shares it.
      */
     parent: () => {
         table: PgTable<any>;
-        idColumn: AnyPgColumn;
-    }, parentId: string | number, targetTable: PgTable<any>, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry): SQL;
+        key: {
+            column: AnyPgColumn;
+            value: string | number;
+        }[];
+    }, 
+    /**
+     * The value a plain foreign key or a junction column holds for this
+     * parent. One column, so it reaches a single-column key only —
+     * `findRelationDefects` refuses those links into a composite one.
+     */
+    parentId: string | number, targetTable: PgTable<any>, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry): SQL;
     /**
      * `EXISTS` for an explicit `joinPath`.
      *
@@ -663,6 +688,21 @@ export declare class DrizzleConditionBuilder {
     /**
      * Helper method to extract table names from columns
      */
+    /**
+     * The two tables one step of a join path joins, by the rule `JoinStep`
+     * documents: `on.from` is a column of the previous table — the source
+     * collection's for the first step — and `on.to` is a column of
+     * `step.table`. A `table.column` spelling names its table outright.
+     *
+     * The tables used to come from that spelling alone, so a step written the
+     * documented way, `{ from: "id", to: "product_id" }`, named no table at
+     * all: every count and include over such a `via` threw "Join tables not
+     * found for step: from  to ", and since a record read at a nested address
+     * is gated on that count, opening an order from a product's Orders tab
+     * failed. The tab's own listing worked — it walks the path forward from
+     * the parent, by position — so only the record behind it broke.
+     */
+    private static joinStepTableNames;
     static getTableNamesFromColumns(columns: string | string[]): string[];
     /**
      * Helper method to extract column names from columns

package/dist/utils/sql-redaction.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SQL a person ran, as the audit log may keep it: every string literal masked.
+ *
+ * The SQL console's audit line wrote the statement verbatim, so `ALTER ROLE app
+ * PASSWORD 'hunter2'`, `CREATE USER MAPPING … OPTIONS (password 'hunter2')` and
+ * `dblink_connect('host=db password=hunter2')` put the password in the
+ * production logs, where the logger's redaction — by key name — never looks.
+ *
+ * A literal is a value the statement carries inline, which is exactly what the
+ * line already declines to write when it is bound as a parameter: the
+ * statement's shape is the audit signal, the values are whatever the operator
+ * was touching. So every literal goes, not only the ones beside a word that
+ * looks like `password` — a secret has no reliable neighbour. Identifiers,
+ * keywords, numbers and comments stay.
+ *
+ * Read with Postgres's own lexical rules, not a regular expression over the
+ * text: a quote inside a comment, a doubled quote, an `E'…\'…'` escape or a
+ * `$tag$` body must not shift where a literal is thought to end, or the mask
+ * covers the statement and leaves the secret.
+ */
+export declare function redactSqlLiterals(sql: string): string;