@rebasepro/server-postgres 0.14.0 → 0.14.1

package/src/services/channel-presence.ts

@@ -29,6 +29,7 @@
 import { sql } from "drizzle-orm";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { revokeInternalTableSql } from "@rebasepro/common";
+import { drizzleDdlBootstrapper } from "../schema/drizzle-ddl";
 
 /** A tracked client, as any instance sees it. */
 export interface PresenceRow {
@@ -45,17 +46,34 @@ export class ChannelPresenceStore {
         private readonly instanceId: string
     ) {}
 
-    /** Create the roster table. Idempotent. */
+    /**
+     * Create the roster table. Idempotent, and safe to run on every instance at
+     * once.
+     *
+     * Written as separate contained steps rather than one straight sequence for
+     * a reason that only bites with more than one replica, which is exactly the
+     * deployment shape this table exists to serve: `CREATE … IF NOT EXISTS`
+     * reads the catalog and then writes to it non-atomically, so peers booting
+     * together collide, and the loser used to abandon everything after it —
+     * including the trailing `REVOKE`. That revoke is the only thing keeping the
+     * roster off the end-user role, so losing a boot race silently left the
+     * whole channel roster readable by every signed-in user.
+     *
+     * `tablesReady` is now set from a probe of what exists, not from having been
+     * the instance that created it.
+     */
     async ensureTables(): Promise<void> {
         if (this.tablesReady) return;
 
-        await this.db.execute(sql`CREATE SCHEMA IF NOT EXISTS rebase`);
+        const ddl = drizzleDdlBootstrapper(this.db, "channel-presence");
+
+        await ddl.ensureObject("rebase schema", "CREATE SCHEMA IF NOT EXISTS rebase");
 
         // Keyed by (channel, client_id): a client id is globally unique, so the
         // instance is a column rather than part of the identity — a client that
         // reconnects onto another replica replaces its own row instead of
         // appearing twice in the roster.
-        await this.db.execute(sql`
+        await ddl.ensureObject("channel_presence table", `
             CREATE TABLE IF NOT EXISTS rebase.channel_presence (
                 channel TEXT NOT NULL,
                 client_id TEXT NOT NULL,
@@ -67,7 +85,7 @@ export class ChannelPresenceStore {
         `);
 
         // The sweep's access path; the roster read rides the primary key.
-        await this.db.execute(sql`
+        await ddl.ensureObject("channel_presence last_seen index", `
             CREATE INDEX IF NOT EXISTS idx_channel_presence_last_seen
             ON rebase.channel_presence (last_seen)
         `);
@@ -82,9 +100,15 @@ export class ChannelPresenceStore {
         // see `docs/channel-authorization.md` for what it does *not*
         // yet decide. Revoke the schema-wide grant the driver handed out
         // before this table existed.
-        await this.db.execute(sql.raw(revokeInternalTableSql("rebase", "channel_presence")));
-
-        this.tablesReady = true;
+        //
+        // Driven off the probe, not off who won the create: the privilege has to
+        // come off whether this instance created the table or found it.
+        if (await ddl.isReadable("rebase.channel_presence")) {
+            await ddl.step("channel_presence revoke", () =>
+                this.db.execute(sql.raw(revokeInternalTableSql("rebase", "channel_presence")))
+            );
+            this.tablesReady = true;
+        }
     }
 
     /** Record (or refresh) a client's presence. */

package/src/services/dataService.ts

@@ -1,5 +1,5 @@
 // import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { FilterValues, LogicalCondition } from "@rebasepro/types";
+import { FilterValues, LogicalCondition, OrderByTuple } from "@rebasepro/types";
 import type { VectorSearchParams } from "@rebasepro/types";
 import { FetchService } from "./FetchService";
 import { PersistService } from "./PersistService";
@@ -62,7 +62,7 @@ export class DataService implements DataRepository {
             filter?: FilterValues<Extract<keyof M, string>>;
             /** An `or(...)`/`and(...)` group, applied alongside `filter`. */
             logical?: LogicalCondition;
-            orderBy?: string;
+            orderBy?: string | OrderByTuple[];
             order?: "desc" | "asc";
             limit?: number;
             offset?: number;
@@ -85,7 +85,7 @@ export class DataService implements DataRepository {
             filter?: FilterValues<Extract<keyof M, string>>;
             /** An `or(...)`/`and(...)` group, applied alongside `filter`. */
             logical?: LogicalCondition;
-            orderBy?: string;
+            orderBy?: string | OrderByTuple[];
             order?: "desc" | "asc";
             limit?: number;
             databaseId?: string;
@@ -106,6 +106,8 @@ export class DataService implements DataRepository {
             logical?: LogicalCondition;
             searchString?: string;
             databaseId?: string;
+            /** Only the `threshold` narrows the count — see `FetchService.count`. */
+            vectorSearch?: VectorSearchParams;
         } = {}
     ): Promise<number> {
         return this.fetchService.count<M>(collectionPath, options);
@@ -133,7 +135,7 @@ export class DataService implements DataRepository {
         relationKey: string,
         options: {
             filter?: FilterValues<Extract<keyof M, string>>;
-            orderBy?: string;
+            orderBy?: string | OrderByTuple[];
             order?: "desc" | "asc";
             limit?: number;
             startAfter?: Record<string, unknown>;

package/src/services/pg-notify-listener.ts

@@ -84,8 +84,16 @@ export class PgNotifyListener {
 
     private async connect({ initial = false }: { initial?: boolean } = {}): Promise<void> {
         const { connectionString, channel, onPayload, logLabel } = this.options;
+        // Held here rather than only inside the `try` so the failure path can
+        // still reach it: everything below `connect()` can throw, and until
+        // `this.client` is assigned nothing else in this class knows the
+        // connection exists. Left unreleased it stays open on the server while
+        // `scheduleReconnect` opens another — one leaked backend per attempt,
+        // every few seconds, for as long as the failure lasts.
+        let pending: PgClient | undefined;
         try {
             const client = new PgClient({ connectionString });
+            pending = client;
 
             client.on("error", (err) => {
                 logger.error(`❌ ${logLabel} LISTEN client error`, { detail: err.message });
@@ -111,8 +119,14 @@ export class PgNotifyListener {
             await client.connect();
             await client.query(`LISTEN ${channel}`);
             this.client = client;
+            // Adopted: `stop()` and `scheduleReconnect` will close it now.
+            pending = undefined;
             logger.debug(`📡 ${logLabel} Listening on channel "${channel}".`);
         } catch (err) {
+            // Never adopted, so nothing else will ever close it.
+            if (pending) {
+                try { await pending.end(); } catch { /* already dead */ }
+            }
             // Surface the initial failure so callers can choose to fall back;
             // for reconnects, keep retrying quietly in the background.
             if (initial) throw err;

package/src/services/realtimeService.ts

@@ -4,12 +4,12 @@ import { Client as PgClient } from "pg";
 import { randomUUID } from "crypto";
 import { DataService } from "./dataService";
 
-import { ANONYMOUS_USER_ID, FetchCollectionProps, ListenCollectionProps, ListenOneProps, DataDriver, CollectionUpdateMessage, SingleUpdateMessage, CollectionPatchMessage, WebSocketMessage, FilterValues, LogicalCondition, CollectionConfig, RebaseCallContext, resolveClientListLimit, ListLimitError } from "@rebasepro/types";
+import { ANONYMOUS_USER_ID, FetchCollectionProps, ListenCollectionProps, ListenOneProps, DataDriver, CollectionUpdateMessage, SingleUpdateMessage, CollectionPatchMessage, WebSocketMessage, FilterValues, LogicalCondition, OrderByTuple, CollectionConfig, RebaseCallContext, resolveClientListLimit, ListLimitError } from "@rebasepro/types";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { sql as drizzleSql } from "drizzle-orm";
 import { RealtimeProvider, CollectionSubscriptionConfig, SingleSubscriptionConfig } from "../interfaces";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
-import { buildPropertyCallbacks, getTableName } from "@rebasepro/common";
+import { buildPropertyCallbacks, getTableName, OrderBySpecError, parseOrderBySpecStrict } from "@rebasepro/common";
 import { applyAuthContext } from "../security/rls-enforcement";
 import { buildJunctionLinkMap, type JunctionLink } from "./cdc/junction-tables";
 import { logger } from "@rebasepro/server";
@@ -85,7 +85,7 @@ type RealTimeListenCollectionProps = ListenCollectionProps & {
 type StoredCollectionRequest = {
     filter?: Record<string, unknown>;
     logical?: LogicalCondition;
-    orderBy?: string;
+    orderBy?: string | OrderByTuple[];
     order?: "desc" | "asc";
     limit?: number;
     offset?: number;
@@ -98,6 +98,42 @@ type StoredCollectionRequest = {
 
 type RealTimeListenEntityProps = ListenOneProps & { subscriptionId: string };
 
+/**
+ * A registered subscription, plus the two counters that order its deliveries.
+ *
+ * Every update a subscription delivers is a full re-fetch, and more than one
+ * thing starts one for the same subscription without coordinating: the initial
+ * fetch at subscribe time, and a debounced refetch per notification (app
+ * mutation, cross-instance NOTIFY, or CDC). A fetch that started earlier can
+ * finish later, and the delivery replaces everything the subscriber has — so
+ * the subscriber goes back to the state before the change and stays there,
+ * silently, until the next write to that collection.
+ *
+ * The debounce is not a fix for this. It collapses a burst into one refetch and
+ * does nothing about two refetches that overlap: notification A fires its timer
+ * and starts fetch A, notification B arrives while A is still in flight, and B's
+ * timer fires and starts fetch B regardless. See class 44 in
+ * `docs/bug-classes.md`.
+ *
+ * `started` is taken before the work, `delivered` after it — which makes the
+ * last delivery *started* the last one *delivered*.
+ */
+type Subscription = {
+    clientId: string;
+    type: "collection" | "single";
+    path: string;
+    id?: string | number;
+    // Store full collection request parameters for proper refetching
+    collectionRequest?: StoredCollectionRequest;
+    // Auth context for RLS — when set, refetches run in a transaction
+    // with set_config('app.uid', ...) / set_config('app.user_roles', ...)
+    authContext?: SubscriptionAuthContext;
+    /** How many deliveries have been started for this subscription. */
+    started: number;
+    /** The highest started-sequence that has already reached the subscriber. */
+    delivered: number;
+};
+
 /**
  * PostgreSQL-specific realtime service.
  * Handles WebSocket connections and subscriptions for real-time row updates.
@@ -195,17 +231,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
     private static readonly PRESENCE_SWEEP_INTERVAL_MS = 10000; // 10s
     private dataService: DataService;
     // Enhanced subscriptions storage with full request parameters
-    private _subscriptions = new Map<string, {
-        clientId: string;
-        type: "collection" | "single";
-        path: string;
-        id?: string | number;
-        // Store full collection request parameters for proper refetching
-        collectionRequest?: StoredCollectionRequest;
-        // Auth context for RLS — when set, refetches run in a transaction
-        // with set_config('app.uid', ...) / set_config('app.user_roles', ...)
-        authContext?: SubscriptionAuthContext;
-    }>();
+    private _subscriptions = new Map<string, Subscription>();
 
     // Add callback storage for DataDriver subscriptions
     private subscriptionCallbacks = new Map<string, (data: Record<string, unknown>[] | Record<string, unknown> | null) => void>();
@@ -279,6 +305,34 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
         return this._subscriptions;
     }
 
+    /**
+     * Claim a delivery slot for a subscription, before doing the work.
+     *
+     * Returns the check to run immediately before delivering. It refuses in
+     * three cases, all of which used to deliver:
+     *
+     * - **Out of order.** A newer refetch has already delivered, so this one is
+     *   stale — the subscriber would go back to the state before the change.
+     * - **Unsubscribed.** The subscription was cancelled while the fetch was in
+     *   flight. The `has(subscriptionId)` check the debounced refetches ran
+     *   *before* the await cannot answer this; only a check after it can.
+     * - **Replaced.** The same id can name a *different* subscription by the
+     *   time a fetch lands — a re-subscribe overwrites the map entry, and the
+     *   old filter's rows would be delivered to the new subscriber.
+     *
+     * The last two are identity, not presence: the map has to still hold *this
+     * exact object*, not merely something under this id.
+     */
+    private beginDelivery(subscriptionId: string, subscription: Subscription): () => boolean {
+        const seq = ++subscription.started;
+        return () => {
+            if (this._subscriptions.get(subscriptionId) !== subscription) return false;
+            if (seq <= subscription.delivered) return false;
+            subscription.delivered = seq;
+            return true;
+        };
+    }
+
     // Add public method to register DataDriver subscriptions
     registerDataDriverSubscription(subscriptionId: string, subscription: {
         clientId: string;
@@ -289,7 +343,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
         authContext?: SubscriptionAuthContext;
     }) {
         this.debugLog("📋 [RealtimeService] Registering DataDriver subscription:", subscriptionId, subscription.authContext ? "(with auth)" : "(no auth)");
-        this._subscriptions.set(subscriptionId, subscription);
+        this._subscriptions.set(subscriptionId, { ...subscription, started: 0, delivered: 0 });
     }
 
     // Add callback management methods
@@ -328,7 +382,9 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                 databaseId: config.databaseId,
                 searchString: config.searchString,
                 searchExplain: config.searchExplain
-            }
+            },
+            started: 0,
+            delivered: 0
         });
 
         if (callback) {
@@ -348,7 +404,9 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             clientId: config.clientId,
             type: "single",
             path: config.path,
-            id: config.id
+            id: config.id,
+            started: 0,
+            delivered: 0
         });
 
         if (callback) {
@@ -507,15 +565,31 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                 return;
             }
 
+            // The sort arrives as whatever JSON the client put in the frame, so
+            // its *shape* is checked here the way the REST ingress checks the
+            // query parameter. Unchecked, a malformed entry reads as a field
+            // name that resolves to no column, and under lenient unknown-field
+            // handling the subscription then streams rows in no order at all
+            // while reporting nothing wrong.
+            let orderBy: OrderByTuple[] | undefined;
+            try {
+                orderBy = parseOrderBySpecStrict(request.orderBy, request.order);
+            } catch (e) {
+                if (!(e instanceof OrderBySpecError)) throw e;
+                logger.warn(`[RealtimeService] Refused subscription to '${request.path}': ${e.message}`);
+                this.sendError(clientId, e.message, subscriptionId, e.code);
+                return;
+            }
+
             // Store subscription with full request parameters and auth context for RLS
-            this._subscriptions.set(subscriptionId, {
+            const subscription: Subscription = {
                 clientId,
                 type: "collection",
                 path: request.path,
                 collectionRequest: {
                     filter: request.filter,
                     logical: request.logical,
-                    orderBy: request.orderBy,
+                    orderBy,
                     order: request.order,
                     limit: boundedLimit,
                     offset: request.offset,
@@ -524,19 +598,30 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                     searchString: request.searchString,
                     searchExplain: request.searchExplain
                 },
-                authContext
-            });
+                authContext,
+                started: 0,
+                delivered: 0
+            };
+            this._subscriptions.set(subscriptionId, subscription);
+
+            // The subscription is registered before this fetch runs, so a write
+            // arriving in that window starts a refetch of its own — with nothing
+            // ordering the two. Claim a slot first: this fetch is the oldest, so
+            // if the refetch answers first, this one no longer delivers.
+            const canDeliver = this.beginDelivery(subscriptionId, subscription);
 
             // Send initial data. Built from the request the subscription just
             // stored, so the first answer and every refetch after it cannot
             // describe different queries.
             const rows = await this.fetchCollectionWithAuth(
                 request.path,
-                this._subscriptions.get(subscriptionId)!.collectionRequest!,
+                subscription.collectionRequest!,
                 authContext
             );
 
-            this.sendCollectionUpdate(clientId, subscriptionId, rows, request.path);
+            if (canDeliver()) {
+                this.sendCollectionUpdate(clientId, subscriptionId, rows, request.path);
+            }
 
         } catch (error) {
             const sanitized = sanitizeErrorForClient(error, request.path);
@@ -559,13 +644,21 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             }
 
             // Store subscription in memory with auth context for RLS
-            this._subscriptions.set(subscriptionId, {
+            const subscription: Subscription = {
                 clientId,
                 type: "single",
                 path: request.path,
                 id: request.id,
-                authContext
-            });
+                authContext,
+                started: 0,
+                delivered: 0
+            };
+            this._subscriptions.set(subscriptionId, subscription);
+
+            // Same race as the collection case: a write landing between the
+            // registration above and this fetch starts a refetch that can answer
+            // first, and this one must not overwrite it afterwards.
+            const canDeliver = this.beginDelivery(subscriptionId, subscription);
 
             // Send initial data
             const row = await this.fetchEntityWithAuth(
@@ -574,7 +667,9 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                 authContext
             );
 
-            this.sendSingleUpdate(clientId, subscriptionId, row || null);
+            if (canDeliver()) {
+                this.sendSingleUpdate(clientId, subscriptionId, row || null);
+            }
 
         } catch (error) {
             const sanitized = sanitizeErrorForClient(error, request.path);
@@ -757,7 +852,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
     private debouncedCollectionRefetch(
         subscriptionId: string,
         notifyPath: string,
-        subscription: { clientId: string; collectionRequest?: StoredCollectionRequest; authContext?: SubscriptionAuthContext }
+        subscription: Subscription
     ) {
         const timerKey = `ws_${subscriptionId}`;
         const existing = this.refetchTimers.get(timerKey);
@@ -765,11 +860,19 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
 
         this.refetchTimers.set(timerKey, setTimeout(async () => {
             this.refetchTimers.delete(timerKey);
-            // Verify subscription still exists (client may have disconnected)
-            if (!this._subscriptions.has(subscriptionId)) return;
+            // Cheap bail before spending a query: the client may have
+            // disconnected, or re-subscribed under the same id. It is only an
+            // optimisation — `canDeliver()` after the await is what makes the
+            // delivery safe, because the same things can happen *during* it.
+            if (this._subscriptions.get(subscriptionId) !== subscription) return;
+            // Claimed here rather than when the timer was scheduled: the
+            // debounce coalesces, and no work exists to order until it fires.
+            const canDeliver = this.beginDelivery(subscriptionId, subscription);
             try {
                 const rows = await this.fetchCollectionWithAuth(notifyPath, subscription.collectionRequest!, subscription.authContext);
-                this.sendCollectionUpdate(subscription.clientId, subscriptionId, rows, notifyPath);
+                if (canDeliver()) {
+                    this.sendCollectionUpdate(subscription.clientId, subscriptionId, rows, notifyPath);
+                }
             } catch (error) {
                 const sanitized = sanitizeErrorForClient(error, notifyPath);
                 this.sendError(subscription.clientId, sanitized.message, subscriptionId, sanitized.code);
@@ -783,7 +886,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
     private debouncedDriverRefetch(
         subscriptionId: string,
         notifyPath: string,
-        subscription: { collectionRequest?: StoredCollectionRequest; authContext?: SubscriptionAuthContext },
+        subscription: Subscription,
         callback: (data: Record<string, unknown>[] | Record<string, unknown> | null) => void
     ) {
         const timerKey = `drv_${subscriptionId}`;
@@ -792,10 +895,11 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
 
         this.refetchTimers.set(timerKey, setTimeout(async () => {
             this.refetchTimers.delete(timerKey);
-            if (!this._subscriptions.has(subscriptionId)) return;
+            if (this._subscriptions.get(subscriptionId) !== subscription) return;
+            const canDeliver = this.beginDelivery(subscriptionId, subscription);
             try {
                 const rows = await this.fetchCollectionWithAuth(notifyPath, subscription.collectionRequest!, subscription.authContext);
-                callback(rows);
+                if (canDeliver()) callback(rows);
             } catch (error) {
                 logger.error(`❌ [RealtimeService] Error in debounced driver refetch for ${subscriptionId}`, { error: error });
             }
@@ -960,7 +1064,7 @@ roles: activeAuth.roles },
         subscriptionId: string,
         notifyPath: string,
         id: string,
-        subscription: { clientId: string; authContext?: SubscriptionAuthContext }
+        subscription: Subscription
     ) {
         const timerKey = `wse_${subscriptionId}`;
         const existing = this.refetchTimers.get(timerKey);
@@ -968,10 +1072,13 @@ roles: activeAuth.roles },
 
         this.refetchTimers.set(timerKey, setTimeout(async () => {
             this.refetchTimers.delete(timerKey);
-            if (!this._subscriptions.has(subscriptionId)) return;
+            if (this._subscriptions.get(subscriptionId) !== subscription) return;
+            const canDeliver = this.beginDelivery(subscriptionId, subscription);
             try {
                 const row = await this.fetchEntityWithAuth(notifyPath, id, subscription.authContext);
-                this.sendSingleUpdate(subscription.clientId, subscriptionId, row || null);
+                if (canDeliver()) {
+                    this.sendSingleUpdate(subscription.clientId, subscriptionId, row || null);
+                }
             } catch (error) {
                 const sanitized = sanitizeErrorForClient(error, notifyPath);
                 this.sendError(subscription.clientId, sanitized.message, subscriptionId, sanitized.code);
@@ -986,7 +1093,7 @@ roles: activeAuth.roles },
         subscriptionId: string,
         notifyPath: string,
         id: string,
-        subscription: { clientId: string; authContext?: SubscriptionAuthContext },
+        subscription: Subscription,
         callback: (data: Record<string, unknown>[] | Record<string, unknown> | null) => void
     ) {
         const timerKey = `drve_${subscriptionId}`;
@@ -995,10 +1102,11 @@ roles: activeAuth.roles },
 
         this.refetchTimers.set(timerKey, setTimeout(async () => {
             this.refetchTimers.delete(timerKey);
-            if (!this._subscriptions.has(subscriptionId)) return;
+            if (this._subscriptions.get(subscriptionId) !== subscription) return;
+            const canDeliver = this.beginDelivery(subscriptionId, subscription);
             try {
                 const row = await this.fetchEntityWithAuth(notifyPath, id, subscription.authContext);
-                callback(row || null);
+                if (canDeliver()) callback(row || null);
             } catch (error) {
                 logger.error(`❌ [RealtimeService] Error in debounced row driver refetch for ${subscriptionId}`, { error: error });
             }
@@ -1362,7 +1470,7 @@ roles: activeAuth.roles },
         logger.warn(
             "⚠️ [ChannelBus] Channels are in use with the in-memory bus, but notifications from another " +
             "instance have been seen — this deployment runs more than one process. Broadcast and presence " +
-            "reach only the clients connected to this one. Set `realtime.bus` (or REBASE_REALTIME_BUS=postgres) " +
+            "reach only the clients connected to this one. Set `realtime.bus` (or REALTIME_CHANNEL_BUS=postgres) " +
             "to make channels cross-instance."
         );
     }
@@ -2296,8 +2404,15 @@ lastSeen: Date.now() });
     private async connectListenClient(): Promise<void> {
         if (!this.listenConnectionString) return;
 
+        let pending: PgClient | undefined;
         try {
+            // See `PgNotifyListener.connect` — same shape, same reason. Until
+            // `this.listenClient` is assigned, nothing else in this class knows
+            // the connection exists, so a throw between `connect()` and that
+            // assignment leaks a live backend and `scheduleReconnect` opens
+            // another one three seconds later.
             const client = new PgClient({ connectionString: this.listenConnectionString });
+            pending = client;
 
             client.on("error", (err) => {
                 logger.error("❌ [RealtimeService] LISTEN client error", { detail: err.message });
@@ -2365,9 +2480,14 @@ lastSeen: Date.now() });
             await client.connect();
             await client.query(`LISTEN ${PG_NOTIFY_CHANNEL}`);
             this.listenClient = client;
+            // Adopted: `destroy()` and `scheduleReconnect` close it now.
+            pending = undefined;
 
             this.debugLog(`📡 [RealtimeService] LISTEN client connected on channel "${PG_NOTIFY_CHANNEL}"`);
         } catch (err) {
+            if (pending) {
+                try { await pending.end(); } catch { /* already dead */ }
+            }
             logger.error("❌ [RealtimeService] Failed to connect LISTEN client", { error: err });
             this.scheduleReconnect();
         }