@rebasepro/server-postgres 0.13.1-canary.gf57a27e → 0.14.0

package/src/utils/drizzle-conditions.ts

@@ -1,14 +1,15 @@
 import { and, eq, or, sql, SQL, ilike, inArray, getTableColumns } from "drizzle-orm";
-import { AnyPgColumn, PgTable, PgVarchar, PgText, PgChar } from "drizzle-orm/pg-core";
+import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
 import {
+    ALL_WHERE_FILTER_OPS,
     CollectionConfig, FilterValues, WhereFilterOp, JoinStep, LogicalCondition, FilterCondition,
     ResolvedRelation, ResolvedBelongsTo, ResolvedHasOne, ResolvedHasMany,
     ResolvedForeignKeyOnTarget, ResolvedManyToMany, hasForeignKeyOnTarget, isManyToMany
 } from "@rebasepro/types";
 import {
-    getColumnName, getTableName, normalizeToEntityRelation, resolveCollectionRelations
+    fieldKeyForColumn, getColumnName, getTableName, normalizeToEntityRelation, resolveCollectionRelations, toFilterTuples
 } from "@rebasepro/common";
-import { generateForeignKeyName } from "@rebasepro/utils";
+import { generateForeignKeyName, toWireKey } from "@rebasepro/utils";
 /**
  * Postgres's own default for `pg_trgm.word_similarity_threshold`. Named here
  * because the fuzzy predicate has to know when the index-backed operator agrees
@@ -35,6 +36,101 @@ import { getColumnMeta } from "../services/collection-helpers";
  */
 export type UnknownFilterFieldsMode = "error" | "warn";
 
+/**
+ * A user's search term, made safe to drop inside a `%…%` LIKE pattern.
+ *
+ * The term is already a bind parameter, so this is not about injection. It is
+ * about the two things a LIKE metacharacter does when it arrives from a search
+ * box:
+ *
+ *  1. **It changes the query.** `%` and `_` are wildcards, so searching for
+ *     `50%` returned every row and `a_c` matched `abc`. Nothing the caller
+ *     could type would find a literal `%`.
+ *  2. **It is a cost the caller chooses.** Postgres matches LIKE by
+ *     backtracking: each `%` re-tries every remaining offset, so
+ *     `?searchString=a%a%a%a%a%a%a%b` is polynomial with an attacker-chosen
+ *     exponent — evaluated per row, OR-ed across every string property of the
+ *     collection, on a sequential scan (a leading `%` cannot use an index), and
+ *     the page limit does not bound it because the scan happens first.
+ *
+ * This is the server-side half of the pattern `like-pattern-redos.test.ts`
+ * hardened the offline evaluator against; that test's own note ("the same
+ * translation in the Mongo driver hands the expression to the database, where
+ * it occupies a server thread instead") describes this call site.
+ *
+ * Backslash is the default `ESCAPE` character for LIKE, and the pattern is
+ * bound rather than interpolated, so a single backslash here reaches the
+ * matcher as one. Escaping the escape character first is what keeps a term
+ * ending in `\` from swallowing the closing `%`.
+ *
+ * Note this is a *substring search*, not the `like` filter operator: a caller
+ * who wants wildcards has `?title=like.foo%` for that, where the pattern is the
+ * documented input.
+ */
+export const escapeLikePattern = (value: string): string =>
+    value.replace(/[\\%_]/g, ch => `\\${ch}`);
+
+/**
+ * The Drizzle column a relation's column name addresses on a table.
+ *
+ * A relation names its link in *column* terms — `localKey: "author_id"`,
+ * `foreignKeyOnTarget: "author_id"` — because that is what the database and
+ * every FK constraint call it. A Drizzle table is keyed by the *wire* name,
+ * `authorId`. Indexing the table with the column, which is what every one of
+ * these call sites used to do, therefore finds nothing the moment the two
+ * differ: for a `columnName`-carrying property that was already true, and it is
+ * now true of every derived foreign key.
+ *
+ * `undefined` rather than a throw: each caller already has a message naming the
+ * relation it was resolving, which is worth more than a generic one here.
+ */
+const relationColumn = (
+    table: PgTable<any>,
+    collection: CollectionConfig | undefined,
+    column: string
+): AnyPgColumn | undefined => {
+    const key = fieldKeyForColumn(collection, column);
+    return (key in table ? table[key as keyof typeof table] as AnyPgColumn : undefined) || undefined;
+};
+
+/** The target collection of a relation, or `undefined` if its thunk cannot resolve. */
+const targetOf = (relation: ResolvedRelation): CollectionConfig | undefined => {
+    try {
+        return relation.target();
+    } catch {
+        return undefined;
+    }
+};
+
+/** Column types `ILIKE '%…%'` is defined on. */
+const ILIKE_SQL_TYPES = /^(text|varchar|character varying|char|character|bpchar|citext)\b/;
+
+/**
+ * Can this column be matched with `ILIKE`?
+ *
+ * Asked of the column's *declared SQL type*, never with `instanceof`. The
+ * previous version tested `column instanceof PgVarchar || … PgText || … PgChar`,
+ * and `instanceof` compares class identity: it is only true when the column was
+ * constructed by the very same copy of `drizzle-orm` that this module imported.
+ *
+ * An application's generated schema builds its tables with the app's own
+ * `drizzle-orm`, and this driver declares its own dependency on one. When the
+ * two ranges do not overlap — an app scaffolded against `^0.44` with a driver
+ * asking for `^0.45` — a strict installer gives the driver a second copy, every
+ * check returns false, no condition is produced, and the caller compiles that
+ * into an impossible `WHERE`. The result is a 200 with an empty page for every
+ * search on every collection without a `search` block: the failure looks
+ * exactly like "nothing matched". Observed in production, not theorised.
+ *
+ * `getSQLType()` is a value the column reports about itself, so it crosses
+ * module instances the way a class identity cannot. It also happens to fix
+ * `citext`, which the `instanceof` list never covered.
+ */
+const supportsILike = (column: AnyPgColumn): boolean => {
+    const sqlType = typeof column?.getSQLType === "function" ? column.getSQLType().toLowerCase() : "";
+    return ILIKE_SQL_TYPES.test(sqlType);
+};
+
 /**
  * Process-wide default, set once when the driver is constructed.
  *
@@ -240,7 +336,7 @@ export class DrizzleConditionBuilder {
 
             case "hasOne":
             case "hasMany": {
-                const fkColumn = targetTable[relation.foreignKeyOnTarget as keyof typeof targetTable] as AnyPgColumn;
+                const fkColumn = relationColumn(targetTable, targetOf(relation), relation.foreignKeyOnTarget);
                 if (!fkColumn) {
                     throw new Error(
                         `Foreign key column '${relation.foreignKeyOnTarget}' not found in the target table of ` +
@@ -393,7 +489,7 @@ export class DrizzleConditionBuilder {
 
             // Owning relation, resolved: the relation names its own local key.
             if (relation?.kind === "belongsTo") {
-                const foreignKey = columnAt(relation.localKey);
+                const foreignKey = relationColumn(table, collection, relation.localKey);
                 if (foreignKey) return { kind: "column", column: foreignKey };
             }
 
@@ -408,7 +504,7 @@ export class DrizzleConditionBuilder {
                 // correlating on the id anyway silently matches nothing —
                 // "filter by this relation" would quietly return zero rows.
                 const correlationColumn = hasForeignKeyOnTarget(relation) && relation.sourceKey
-                    ? columnAt(relation.sourceKey)
+                    ? relationColumn(table, collection, relation.sourceKey)
                     : sourceIdColumn;
                 if (!correlationColumn) {
                     throw new Error(
@@ -421,10 +517,17 @@ export class DrizzleConditionBuilder {
             }
         }
 
-        // No collection in hand — the two shapes an owning relation's key takes
-        // by default (e.g. `project` → `project_id`, `userProfile` →
-        // `user_profile_id`).
-        for (const guess of [`${field}_id`, generateForeignKeyName(field)]) {
+        // No collection in hand — the shapes an owning relation's key takes by
+        // default (e.g. `project` → `projectId`, `userProfile` →
+        // `userProfileId`). The snake forms stay in the list because a project
+        // may have authored the property under its column name, which is still
+        // its wire name.
+        for (const guess of [
+            `${field}Id`,
+            toWireKey(generateForeignKeyName(field)),
+            `${field}_id`,
+            generateForeignKeyName(field)
+        ]) {
             const foreignKey = columnAt(guess);
             if (foreignKey) return { kind: "column", column: foreignKey };
         }
@@ -472,11 +575,9 @@ export class DrizzleConditionBuilder {
             const target = this.resolveFilterTarget(table, field, collectionPath, mode, options);
             if (!target) continue;
 
-            const paramsList = Array.isArray(filterParam) && filterParam.length > 0 && Array.isArray(filterParam[0])
-                ? (filterParam as [WhereFilterOp, any][])
-                : [filterParam as [WhereFilterOp, any]];
-
-            for (const [op, value] of paramsList) {
+            // One tuple or an array of them — the grammar, read the same way by
+            // every compiler. See `toFilterTuples`.
+            for (const [op, value] of toFilterTuples(filterParam)) {
                 const condition = this.compileFilterTarget(target, op, value, field, collectionPath);
                 if (condition) {
                     conditions.push(condition);
@@ -610,7 +711,7 @@ export class DrizzleConditionBuilder {
                     `(collection '${targetCollection.slug}')`
                 );
             }
-            const fkColumn = targetTable[relation.foreignKeyOnTarget as keyof typeof targetTable] as AnyPgColumn;
+            const fkColumn = relationColumn(targetTable, targetCollection, relation.foreignKeyOnTarget);
             if (!fkColumn) {
                 throw new Error(
                     `Foreign key column '${relation.foreignKeyOnTarget}' not found in the target table of ` +
@@ -851,8 +952,24 @@ export class DrizzleConditionBuilder {
             case "is-not-null":
                 return sql`${column} IS NOT NULL`;
             default:
-                logger.warn(`Unsupported filter operation: ${op}`);
-                return null;
+                // The relation path five hundred lines up already refuses this,
+                // and says why: "returning `null` for an operator this cannot
+                // express would drop the condition", and a dropped condition
+                // widens the result. The column path is its twin and kept the
+                // warning — so `{ status: ["contains", "x"] }` filtered on
+                // nothing and answered 200 with every row, which reads as data
+                // that matched.
+                //
+                // The wire layer rejects operator-shaped unknowns before they
+                // arrive (`UnknownFilterOperatorError`, 400). What reaches here
+                // came from in-process `rebase.data`, a stored filter preset or
+                // a config — none of them typechecked at the call site, all of
+                // them able to name an operator that no longer exists.
+                throw ApiError.badRequest(
+                    `Unknown filter operator '${op}'. Valid operators: ${ALL_WHERE_FILTER_OPS.join(", ")}.`,
+                    "UNKNOWN_FILTER_OPERATOR",
+                    { operator: op, validOperators: ALL_WHERE_FILTER_OPS }
+                );
         }
     }
 
@@ -1253,7 +1370,7 @@ whereConditions };
             return match(targetIdCol);
         }
 
-        const foreignKeyCol = targetTable[relation.foreignKeyOnTarget as keyof typeof targetTable] as AnyPgColumn;
+        const foreignKeyCol = relationColumn(targetTable, targetOf(relation), relation.foreignKeyOnTarget);
         if (!foreignKeyCol) {
             throw new Error(
                 `Foreign key column '${relation.foreignKeyOnTarget}' not found in the target table of relation ` +
@@ -1290,7 +1407,8 @@ whereConditions };
      *   `tsvector` column. Stems, drops stopwords, AND-es the terms, reaches
      *   inside JSONB and arrays, and uses the GIN index.
      * - **Not declared** — the original `ILIKE '%term%'` OR-ed across top-level
-     *   string properties, unchanged.
+     *   string properties, with the term escaped (see {@link escapeLikePattern})
+     *   so it is matched as the literal text the user typed.
      *
      * The second is the default and stays the default. A collection that has
      * not opted in compiles to exactly the SQL it compiled to before this
@@ -1313,26 +1431,34 @@ whereConditions };
             : undefined;
         if (ftsCondition) return [ftsCondition];
 
+        let declaredStringProperties = 0;
+
         for (const [key, prop] of Object.entries(properties)) {
             const p = prop as Record<string, unknown>;
             // Only include string properties that don't have enum defined
             // PostgreSQL enum and uuid columns don't support ILIKE, so we skip them
             if (p.type === "string" && !p.enum && p.isId !== "uuid") {
+                declaredStringProperties++;
                 const fieldColumn = table[key as keyof typeof table] as AnyPgColumn;
-                if (fieldColumn) {
-                    // Verify that the underlying database column supports string pattern-matching
-                    const supportsILike =
-                        fieldColumn instanceof PgVarchar ||
-                        fieldColumn instanceof PgText ||
-                        fieldColumn instanceof PgChar ||
-                        (fieldColumn && typeof fieldColumn === "object" && !("columnType" in fieldColumn));
-                    if (supportsILike) {
-                        searchConditions.push(ilike(fieldColumn, `%${searchString}%`));
-                    }
+                if (fieldColumn && supportsILike(fieldColumn)) {
+                    searchConditions.push(ilike(fieldColumn, `%${escapeLikePattern(searchString)}%`));
                 }
             }
         }
 
+        // Every string property was rejected, so the caller is about to turn an
+        // empty condition list into "match nothing" — a 200 with an empty page,
+        // which reads as "no such row" rather than as the breakage it is. Say so
+        // once per query: this is how the `instanceof` version of
+        // {@link supportsILike} failed silently in the field for months.
+        if (declaredStringProperties > 0 && searchConditions.length === 0) {
+            logger.warn(
+                `[search] "${collection?.slug ?? "collection"}" declares ${declaredStringProperties} string ` +
+                "property(ies) but none compiled to a searchable column, so this search can only return nothing. " +
+                "Check that the generated schema's column types are text/varchar/char."
+            );
+        }
+
         return searchConditions;
     }
 
@@ -1759,6 +1885,16 @@ whereConditions };
      * - `orderBy`: SQL expression to ORDER BY distance (ascending = closest first)
      * - `filter`: optional WHERE clause for distance threshold
      * - `distanceSelect`: SQL expression for selecting the distance as `_distance`
+     *
+     * `property` is `?vector_search=` off the querystring, so it is an untrusted
+     * *name*, and it used to be looked up straight in the drizzle table object.
+     * Two ways that went wrong, both answering 500 to a malformed request:
+     * `?vector_search=title` built `"title" <=> '[1,2]'::vector`, which the
+     * database rejects with "operator does not exist"; and a table object also
+     * carries non-column keys (`_`, methods), which passed the `if (!column)`
+     * guard and compiled to nonsense. The name is resolved against the table's
+     * actual columns and required to be a `vector` — anything else is the
+     * caller's mistake and gets a 400 that says so.
      */
     static buildVectorSearchConditions(
         table: PgTable<any>,
@@ -1769,10 +1905,7 @@ whereConditions };
             threshold?: number;
         }
     ): { orderBy: SQL; filter?: SQL; distanceSelect: SQL } {
-        const column = table[vectorSearch.property as keyof typeof table] as AnyPgColumn;
-        if (!column) {
-            throw new Error(`Vector column '${vectorSearch.property}' not found in table`);
-        }
+        const column = DrizzleConditionBuilder.resolveVectorColumn(table, vectorSearch.property);
 
         // The vector is interpolated as a raw SQL literal below (pgvector has no
         // bind form for the `::vector` cast), so every element must be a finite
@@ -1813,8 +1946,52 @@ whereConditions };
             distanceSelect: sql`(${column} ${sql.raw(operator)} ${sql.raw(vectorLiteral)})`
         };
     }
+
+    /**
+     * The `vector` column a request named, or a 400 explaining what it named.
+     *
+     * `getTableColumns` rather than a key lookup: it returns only the columns,
+     * so `_`, `getSQL` and every other property of a drizzle table stop looking
+     * like candidates. The type check is on the *physical* column
+     * (`vector(1536)`) rather than on the declared property, so it holds for an
+     * introspected collection too, where the property carries no Rebase type.
+     */
+    private static resolveVectorColumn(table: PgTable<any>, property: string): AnyPgColumn {
+        const columns = getTableColumns(table) as Record<string, AnyPgColumn> | undefined;
+        const column = columns?.[property];
+        if (!column) {
+            const known = Object.entries(columns ?? {})
+                .filter(([, c]) => isVectorColumn(c))
+                .map(([name]) => name);
+            throw ApiError.badRequest(
+                `Unknown vector property "${property}". ` +
+                (known.length > 0
+                    ? `This collection's vector properties are: ${known.join(", ")}.`
+                    : "This collection declares no `vector` property to search."),
+                "UNKNOWN_VECTOR_PROPERTY"
+            );
+        }
+        if (!isVectorColumn(column)) {
+            throw ApiError.badRequest(
+                `Property "${property}" is not a vector column (it is \`${columnSqlType(column) || "unknown"}\`), ` +
+                "so it has no distance operator. Name the property declared as `{ type: \"vector\" }`.",
+                "UNKNOWN_VECTOR_PROPERTY"
+            );
+        }
+        return column;
+    }
 }
 
+/** The column's SQL type, for a value that may not be a drizzle column at all. */
+const columnSqlType = (column: unknown): string => {
+    const getSQLType = (column as { getSQLType?: () => string })?.getSQLType;
+    return typeof getSQLType === "function" ? getSQLType.call(column).toLowerCase() : "";
+};
+
+/** True for `vector(1536)` and its pgvector siblings, whatever the width. */
+const isVectorColumn = (column: unknown): boolean =>
+    /^(vector|halfvec|sparsevec)\b/.test(columnSqlType(column));
+
 /**
  * Alias for DrizzleConditionBuilder for consistent naming with other database implementations.
  * This allows code to use PostgresConditionBuilder alongside future MongoConditionBuilder, etc.

package/src/utils/pg-error-utils.ts

@@ -314,9 +314,14 @@ export function sanitizeErrorForClient(error: unknown, context: string): { messa
             column: pgError.column,
             table: pgError.table,
             constraint: pgError.constraint,
-            dataType: pgError.dataType,
-            // Also log the outer Drizzle wrapper message for full context
-            drizzleMessage: error instanceof Error ? error.message : String(error)
+            dataType: pgError.dataType
+            // The outer Drizzle wrapper message used to be logged here "for
+            // full context": it is `Failed query: <sql>\nparams: <values>`, so
+            // it published the statement and every bound value (an email, a
+            // password hash) on every realtime data failure. The SQLSTATE,
+            // detail, table, column and constraint above are the diagnostic
+            // value; the wrapper added only the leak. `logger` strips the
+            // wrapper as well, but the field itself carried nothing else.
         });
         return pgErrorToFriendlyMessage(pgError, context);
     }

package/src/websocket.ts

@@ -1,7 +1,7 @@
 import { RealtimeService } from "./services/realtimeService";
 import { PostgresBackendDriver } from "./PostgresBackendDriver";
 import type { DataDriver, DeleteProps, FetchCollectionProps, FetchOneProps, SaveProps, TableMetadata, BranchInfo, AuthAdapter } from "@rebasepro/types";
-import { ANONYMOUS_USER_ID, isSQLAdmin, isSchemaAdmin } from "@rebasepro/types";
+import { ANONYMOUS_USER_ID, isSQLAdmin, isSchemaAdmin, resolveClientListLimit, ListLimitError } from "@rebasepro/types";
 import type { User } from "@rebasepro/types";
 
 import { WebSocketServer, WebSocket } from "ws";
@@ -39,6 +39,9 @@ interface ClientSession {
     /** Sliding window message counter for rate limiting */
     messageCount: number;
     messageWindowStart: number;
+    /** The same window, counted separately for channel frames. */
+    channelMessageCount: number;
+    channelWindowStart: number;
 }
 
 
@@ -47,6 +50,33 @@ const WS_RATE_LIMIT = 2000;
 /** Rate limit window in milliseconds (60 seconds) */
 const WS_RATE_WINDOW_MS = 60_000;
 
+/**
+ * Channel frames get their own budget, because they are a different workload.
+ *
+ * 2000/minute is 33/second, which is generous for queries and subscriptions and
+ * an order of magnitude below what the documented channel idiom asks for: the
+ * capacity note in `docs/backend/realtime.md` uses 60 fps cursor movement as
+ * its worked example, and the presence idiom re-`track()`s on every move, so
+ * one client sustaining that sends ~120 frames/second — 7200 a minute. Sharing
+ * one counter meant the cursor stream ate the query budget and then froze for
+ * the rest of the window.
+ *
+ * The number is sized to that documented workload and nothing more; it is not
+ * a considered product limit (see `docs/channel-authorization.md`).
+ */
+const WS_CHANNEL_RATE_LIMIT = 7200;
+
+/** Frames counted against the channel budget rather than the general one. */
+const CHANNEL_MESSAGE_TYPES = new Set([
+    "join_channel",
+    "leave_channel",
+    "broadcast",
+    "presence_track",
+    "presence_untrack",
+    "presence_state",
+    "channel_history"
+]);
+
 /** Admin-only WebSocket message types */
 const ADMIN_ONLY_TYPES = new Set([
     "EXECUTE_SQL",
@@ -139,7 +169,9 @@ export function createPostgresWebSocket(
         clientSessions.set(clientId, { ws,
 authenticated: !requireAuth,
 messageCount: 0,
-messageWindowStart: Date.now() });
+messageWindowStart: Date.now(),
+channelMessageCount: 0,
+channelWindowStart: Date.now() });
         realtimeService.addClient(clientId, ws);
 
         ws.on("close", () => {
@@ -247,19 +279,34 @@ roles: verifiedUser.roles }
                     }
                 }
 
-                // Rate limiting: reject if client exceeds message limit
+                // Rate limiting: reject if client exceeds message limit.
+                // Channel frames are counted against their own budget — see
+                // WS_CHANNEL_RATE_LIMIT for why one shared counter starved them.
                 {
                     const session = clientSessions.get(clientId);
                     if (session) {
                         const now = Date.now();
-                        if (now - session.messageWindowStart > WS_RATE_WINDOW_MS) {
-                            session.messageCount = 0;
-                            session.messageWindowStart = now;
-                        }
-                        session.messageCount++;
-                        if (session.messageCount > WS_RATE_LIMIT) {
-                            sendError("ERROR", "RATE_LIMITED", "Too many requests. Please slow down.");
-                            return;
+                        const isChannelFrame = CHANNEL_MESSAGE_TYPES.has(type);
+                        if (isChannelFrame) {
+                            if (now - session.channelWindowStart > WS_RATE_WINDOW_MS) {
+                                session.channelMessageCount = 0;
+                                session.channelWindowStart = now;
+                            }
+                            session.channelMessageCount++;
+                            if (session.channelMessageCount > WS_CHANNEL_RATE_LIMIT) {
+                                sendError("ERROR", "RATE_LIMITED", "Too many channel messages. Please slow down.");
+                                return;
+                            }
+                        } else {
+                            if (now - session.messageWindowStart > WS_RATE_WINDOW_MS) {
+                                session.messageCount = 0;
+                                session.messageWindowStart = now;
+                            }
+                            session.messageCount++;
+                            if (session.messageCount > WS_RATE_LIMIT) {
+                                sendError("ERROR", "RATE_LIMITED", "Too many requests. Please slow down.");
+                                return;
+                            }
                         }
                     }
                 }
@@ -312,7 +359,19 @@ roles: verifiedUser.roles }
                         wsDebug("📋 [WebSocket Server] Processing FETCH_COLLECTION request");
                         const request: FetchCollectionProps = payload;
                         const delegate = await getScopedDelegate();
-                        const rows = await delegate.fetchCollection(request);
+                        // Bound the client-supplied limit with the SAME guarantee
+                        // the REST ingress and `subscribe_collection` apply
+                        // (`resolveClientListLimit`). Without it an absent limit
+                        // reached the driver as `undefined`, which emits no LIMIT
+                        // clause — one socket frame streamed the whole table, on
+                        // the one transport that skipped the ceiling every other
+                        // read path enforces.
+                        const rows = await delegate.fetchCollection({
+                            ...request,
+                            limit: resolveClientListLimit(request.limit, {
+                                vectorSearch: !!request.vectorSearch
+                            })
+                        });
                         wsDebug("📋 [WebSocket Server] FETCH_COLLECTION result - rows count:", rows.length);
                         const response = {
                             type: "FETCH_COLLECTION_SUCCESS",
@@ -400,6 +459,12 @@ colors: true }));
 
 
                     case "COUNT": {
+                        // Deliberately NOT routed through `resolveClientListLimit`:
+                        // this answers with a scalar, and the driver drops `limit`
+                        // on the way to `SELECT count(*)`. Clamping here could only
+                        // ever make `total` describe fewer rows than the collection
+                        // holds — the page size is the caller's business, the total
+                        // is not.
                         const request: FetchCollectionProps = payload;
                         const delegate = await getScopedDelegate();
                         const count = await delegate.count!(request);
@@ -426,14 +491,29 @@ colors: true }));
                                 wsDebug(`⚡ [WebSocket Server] SQL executed. Returned ${Array.isArray(result) ? result.length : "non-array"} rows.`);
                             }
                             const auditSession = clientSessions.get(clientId);
-                            console.log("[SQL Audit] WebSocket SQL execution", JSON.stringify({
-                                sql: typeof sql === "string" ? sql.substring(0, 500) : sql,
-                                options,
+                            // Through `logger`, not `console.log`: this line is
+                            // emitted in production, and a bare console call
+                            // has no severity, no timestamp, no JSON envelope
+                            // and no LOG_LEVEL gate, so it lands in Cloud
+                            // Logging as unstructured text the queries written
+                            // for every other line cannot match.
+                            //
+                            // The bound values are counted, never written — the
+                            // statement is the audit signal, the parameters are
+                            // whatever row the operator was touching. (stdout is
+                            // not an audit sink either; a real trail belongs in
+                            // a table with an actor and a retention policy.)
+                            logger.info("[SQL Audit] WebSocket SQL execution", {
+                                sql: typeof sql === "string" ? sql.substring(0, 500) : String(sql),
+                                database: options?.database,
+                                role: options?.role,
+                                paramCount: Array.isArray(options?.params) ? options.params.length : 0,
                                 resultRows: Array.isArray(result) ? result.length : "unknown",
                                 uid: auditSession?.user?.uid ?? "unknown",
                                 roles: auditSession?.user?.roles ?? [],
                                 isAdmin: auditSession?.user?.isAdmin ?? false,
-                            }));
+                                requestId
+                            });
                             const response = {
                                 type: "EXECUTE_SQL_SUCCESS",
                                 payload: { result },
@@ -644,6 +724,23 @@ roles: ["anon"] };
                         logger.error("❌ [WebSocket Server] Unknown message type", { detail: type });
                 }
             } catch (error: unknown) {
+                // A refused `limit` is the caller's mistake, not a server fault.
+                // Left to the generic branch below it answers INTERNAL_ERROR
+                // with the message suppressed in production — so the one thing
+                // that would tell the caller what to send instead is exactly
+                // what gets dropped. Answered here the way
+                // `subscribe_collection` already answers it: INVALID_LIMIT,
+                // message intact. The text names the ceiling and nothing else.
+                if (error instanceof ListLimitError) {
+                    logger.warn(`[WebSocket Server] Refused a list read: ${error.message}`);
+                    ws.send(JSON.stringify({
+                        type: "ERROR",
+                        requestId,
+                        payload: { error: { message: error.message,
+code: "INVALID_LIMIT" } }
+                    }));
+                    return;
+                }
                 logger.error("💥 [WebSocket Server] Error handling message", { error: error });
                 if (error instanceof Error) {
                     logger.error("Stack trace", { detail: error.stack });