@rebasepro/common 0.13.0 → 0.13.1-canary.g06dbe5b

package/src/data/buildRebaseData.ts

@@ -14,11 +14,13 @@ import {
     SDKCollectionClient,
     SDKQueryBuilderInterface,
     WhereFilterOp,
-    WhereValue
+    WhereValueFor,
+    type ComputedSortField,
+    type SearchMatch
 } from "@rebasepro/types";
 import { toSnakeCase } from "@rebasepro/utils";
 import { QueryBuilder } from "./query_builder";
-import { collectAllPages, paginateFind } from "./paginate";
+import { collectAllPages, paginateFind, resolveFindWindow } from "./paginate";
 import { deserializeFilter } from "./filter-dialect";
 import { buildCompositeId, resolvePrimaryKeys, PrimaryKeyInfo } from "../util/identity";
 
@@ -89,12 +91,19 @@ function rowToEntity<M extends Record<string, unknown>>(
     slug: string,
     primaryKeys: PrimaryKeyInfo[] = []
 ): Entity<M> {
+    // Query-computed metadata rides in on the row because that is how the wire
+    // carries it, but it is not a column: it belongs beside `values`, not in
+    // them. Left inside, `_matches` would show up in the record inspector as a
+    // field the collection never declared.
+    const { _matches, ...values } = row as Record<string, unknown> & { _matches?: SearchMatch[] };
+
     return {
         id: primaryKeys.length > 0
             ? buildCompositeId(row, primaryKeys)
             : row.id as string | number,
         path: slug,
-        values: row as EntityValues<M>
+        values: values as EntityValues<M>,
+        ...(_matches ? { searchMatches: _matches } : {})
     };
 }
 
@@ -153,8 +162,7 @@ function createDriverAccessor<M extends Record<string, unknown> = Record<string,
         async find(params?: FindParams<M>): Promise<FindResponse<M>> {
             // Ensure filters are in canonical [op, value] format even if passed as PostgREST strings
             const filter = params?.where ? deserializeFilter(params.where as Record<string, unknown>) : undefined;
-            const limit = params?.limit ?? 20;
-            const offset = params?.offset ?? 0;
+            const { limit, offset, driverOffset } = resolveFindWindow(params);
 
             // One relation shape, whatever the call looks like.
             //
@@ -177,8 +185,12 @@ function createDriverAccessor<M extends Record<string, unknown> = Record<string,
                     slug,
                     {
                         filter,
-                        limit: params?.limit,
-                        offset: params?.offset,
+                        // Without this the group was dropped and the read ran
+                        // unfiltered — every row the caller's policies allow,
+                        // in place of the ones they asked for.
+                        logical: params?.logical,
+                        limit,
+                        offset: driverOffset,
                         orderBy: params?.orderBy?.[0],
                         order: params?.orderBy?.[1],
                         searchString: params?.searchString
@@ -187,9 +199,10 @@ function createDriverAccessor<M extends Record<string, unknown> = Record<string,
                 )
                 : await driver.fetchCollection<M>({
                     path: slug,
-                    limit: params?.limit,
-                    offset: params?.offset,
+                    limit,
+                    offset: driverOffset,
                     filter,
+                    logical: params?.logical,
                     orderBy: params?.orderBy?.[0],
                     order: params?.orderBy?.[1],
                     searchString: params?.searchString
@@ -199,7 +212,16 @@ function createDriverAccessor<M extends Record<string, unknown> = Record<string,
             let total = rows.length + offset;
             let hasMore = rows.length >= limit;
             if (driver.count) {
-                total = await driver.count({ path: slug, filter });
+                // The same narrowing the rows were read with. Counting only by
+                // `filter` reported the whole collection beside a narrowed
+                // page, and `hasMore` is derived from it — so the list offered
+                // a next page that did not exist.
+                total = await driver.count({
+                    path: slug,
+                    filter,
+                    logical: params?.logical,
+                    searchString: params?.searchString
+                });
                 hasMore = offset + rows.length < total;
             }
 
@@ -258,37 +280,70 @@ values: {} as Record<string, unknown> }
             });
         },
 
+        // Present only when the driver is: exposing these unconditionally and
+        // looping single writes underneath would give a caller neither the
+        // atomicity nor the single round trip they reached for a batch to get,
+        // while looking exactly like it had.
+        updateMany: driver.updateMany
+            ? async (updates: { id: string | number; data: Partial<EntityValues<M>> }[]): Promise<Entity<M>[]> => {
+                const rows = await driver.updateMany!<M>({
+                    path: slug,
+                    updates: updates.map(u => ({ id: u.id,
+values: u.data })),
+                });
+                return rows.map(row => rowToEntity<M>(row, slug, getPks()));
+            }
+            : undefined,
+
+        deleteMany: driver.deleteMany
+            ? async (ids: (string | number)[]): Promise<void> => {
+                await driver.deleteMany!<M>({ path: slug,
+ids });
+            }
+            : undefined,
+
         count: driver.count
             ? async (params?: FindParams<M>): Promise<number> => {
                 const filter = params?.where ? deserializeFilter(params.where as Record<string, unknown>) : undefined;
+                // Every narrowing `find()` applies has to apply here too, or
+                // the count describes a different query than the one it is
+                // reported against.
                 return driver.count!({
                     path: slug,
-                    filter
+                    filter,
+                    logical: params?.logical,
+                    searchString: params?.searchString
                 });
             }
             : undefined,
 
         listen: driver.listenCollection
             ? (params: FindParams<M> | undefined, onUpdate: (response: FindResponse<M>) => void, onError?: (error: Error) => void) => {
-                const limit = params?.limit ?? 20;
-                const offset = params?.offset ?? 0;
+                const { limit, offset, driverOffset } = resolveFindWindow(params);
                 // Realtime has no REST-pipeline equivalent, so the rows arrive
                 // admin-shaped. Flatten them to the one shape the rest of this
                 // accessor serves.
                 const normalize = driver.restFetchService ? inlineRelationRefs : (row: Record<string, unknown>) => row;
                 return driver.listenCollection!<M>({
                     path: slug,
-                    limit: params?.limit,
-                    offset: params?.offset,
+                    limit,
+                    offset: driverOffset,
                     filter: params?.where,
+                    logical: params?.logical,
                     orderBy: params?.orderBy?.[0],
                     order: params?.orderBy?.[1],
                     searchString: params?.searchString,
+                    searchExplain: params?.searchExplain,
                     onUpdate: (entities) => {
                         onUpdate({
                             data: entities.map((row: Record<string, unknown>) => rowToEntity<M>(normalize(row), slug, getPks())),
                             meta: {
-                                total: entities.length,
+                                // No count is issued on this path, so the total
+                                // is unknown; the lower bound is the rows in
+                                // hand plus the ones paged past to reach them.
+                                // Reporting `entities.length` claimed a read at
+                                // offset 100 had found a collection of two.
+                                total: offset + entities.length,
                                 limit,
                                 offset,
                                 hasMore: entities.length >= limit
@@ -316,9 +371,9 @@ values: {} as Record<string, unknown> }
             if (typeof columnOrCondition === "object") {
                 return builder.where(columnOrCondition);
             }
-            return builder.where(columnOrCondition as keyof M & string, operator!, value as WhereValue<M[keyof M & string]>);
+            return builder.where(columnOrCondition as keyof M & string, operator!, value as WhereValueFor<WhereFilterOp, M[keyof M & string]>);
         },
-        orderBy(column: keyof M & string, ascending?: "asc" | "desc") {
+        orderBy(column: (keyof M & string) | ComputedSortField, ascending?: "asc" | "desc") {
             return new QueryBuilder<M>(accessor).orderBy(column, ascending);
         },
         limit(count: number) {
@@ -327,8 +382,15 @@ values: {} as Record<string, unknown> }
         offset(count: number) {
             return new QueryBuilder<M>(accessor).offset(count);
         },
-        search(searchString: string) {
-            return new QueryBuilder<M>(accessor).search(searchString);
+        search(searchString: string, options?: { explain?: boolean }) {
+            return new QueryBuilder<M>(accessor).search(searchString, options);
+        },
+        vectorSearch(
+            property: string,
+            vector: number[],
+            options?: { distance?: "cosine" | "l2" | "inner_product"; threshold?: number }
+        ) {
+            return new QueryBuilder<M>(accessor).vectorSearch(property, vector, options);
         },
         include(...relations: string[]) {
             return new QueryBuilder<M>(accessor).include(...relations);
@@ -405,7 +467,7 @@ class SdkQueryBuilder<M extends Record<string, unknown> = Record<string, unknown
 
     constructor(private client: SDKCollectionClient<M>) {}
 
-    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;
     where(logicalCondition: LogicalCondition): this;
     where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown): this {
         if (typeof columnOrCondition === "object" && columnOrCondition !== null && "type" in columnOrCondition) {
@@ -432,14 +494,27 @@ class SdkQueryBuilder<M extends Record<string, unknown> = Record<string, unknown
         return this;
     }
 
-    orderBy(column: keyof M & string, direction: "asc" | "desc" = "asc"): this {
+    orderBy(column: (keyof M & string) | ComputedSortField, direction: "asc" | "desc" = "asc"): this {
         this.params.orderBy = [column, direction];
         return this;
     }
 
     limit(count: number): this { this.params.limit = count; return this; }
     offset(count: number): this { this.params.offset = count; return this; }
-    search(searchString: string): this { this.params.searchString = searchString; return this; }
+    search(searchString: string, options?: { explain?: boolean }): this { this.params.searchString = searchString; if (options?.explain !== undefined) this.params.searchExplain = options.explain; return this; }
+    vectorSearch(
+        property: string,
+        vector: number[],
+        options?: { distance?: "cosine" | "l2" | "inner_product"; threshold?: number }
+    ): this {
+        this.params.vectorSearch = {
+            property,
+            vector,
+            ...(options?.distance !== undefined && { distance: options.distance }),
+            ...(options?.threshold !== undefined && { threshold: options.threshold })
+        };
+        return this;
+    }
     include(...relations: string[]): this { this.params.include = relations; return this; }
 
     async find(): Promise<FindResult<M>> {
@@ -506,9 +581,39 @@ function toSdkCollectionClient<M extends Record<string, unknown>>(
         async update(id: string | number, data: Partial<M>): Promise<M> {
             return entityToRow(await snap.update(id, data as Partial<EntityValues<M>>));
         },
+        async updateMany(updates: { id: string | number; data: Partial<M> }[]): Promise<M[]> {
+            if (!Array.isArray(updates)) {
+                throw new TypeError("updateMany expects an array of { id, data } entries.");
+            }
+            if (updates.length === 0) return [];
+            if (!snap.updateMany) {
+                throw new Error(
+                    "Bulk updates are not supported by this collection's data source. " +
+                    "Fall back to update() per record."
+                );
+            }
+            const rows = await snap.updateMany(
+                updates.map(u => ({ id: u.id,
+data: u.data as Partial<EntityValues<M>> }))
+            );
+            return rows.map(entityToRow);
+        },
         delete(id: string | number): Promise<void> {
             return snap.delete(id);
         },
+        async deleteMany(ids: (string | number)[]): Promise<void> {
+            if (!Array.isArray(ids)) {
+                throw new TypeError("deleteMany expects an array of ids.");
+            }
+            if (ids.length === 0) return;
+            if (!snap.deleteMany) {
+                throw new Error(
+                    "Bulk deletes are not supported by this collection's data source. " +
+                    "Fall back to delete() per record."
+                );
+            }
+            await snap.deleteMany(ids);
+        },
         count: snap.count ? (params?: FindParams<M>) => snap.count!(params) : undefined,
         listen: snap.listen
             ? (params: FindParams<M> | undefined, onUpdate: (r: FindResult<M>) => void, onError?: (e: Error) => void) =>
@@ -523,12 +628,17 @@ function toSdkCollectionClient<M extends Record<string, unknown>>(
             if (typeof columnOrCondition === "object") {
                 return builder.where(columnOrCondition);
             }
-            return builder.where(columnOrCondition as keyof M & string, operator!, value as WhereValue<M[keyof M & string]>);
+            return builder.where(columnOrCondition as keyof M & string, operator!, value as WhereValueFor<WhereFilterOp, M[keyof M & string]>);
         },
         orderBy: (column: keyof M & string, direction?: "asc" | "desc") => new SdkQueryBuilder<M>(client).orderBy(column, direction),
         limit: (count: number) => new SdkQueryBuilder<M>(client).limit(count),
         offset: (count: number) => new SdkQueryBuilder<M>(client).offset(count),
         search: (searchString: string) => new SdkQueryBuilder<M>(client).search(searchString),
+        vectorSearch: (
+            property: string,
+            vector: number[],
+            options?: { distance?: "cosine" | "l2" | "inner_product"; threshold?: number }
+        ) => new SdkQueryBuilder<M>(client).vectorSearch(property, vector, options),
         include: (...relations: string[]) => new SdkQueryBuilder<M>(client).include(...relations)
     };
     return client;
@@ -537,7 +647,7 @@ function toSdkCollectionClient<M extends Record<string, unknown>>(
 /**
  * Wrap a flat {@link SDKCollectionClient} into a Entity-shaped
  * {@link CollectionAccessor}. Every returned row is re-wrapped into the
- * `{ id, path, values }` view-model the admin admin renders.
+ * `{ id, path, values }` view-model the admin panel renders.
  */
 function toEntityAccessor<M extends Record<string, unknown>>(
     sdk: SDKCollectionClient<M>,
@@ -556,6 +666,16 @@ function toEntityAccessor<M extends Record<string, unknown>>(
         async create(data: Partial<EntityValues<M>>, id?: string | number): Promise<Entity<M>> {
             return rowToEntity<M>(await sdk.create(data as Partial<M>, id), slug, getPks());
         },
+        // Declared on `CollectionAccessor` and, until now, never implemented on
+        // this side of the boundary — so the admin's own import wrote one HTTP
+        // request per row and could neither be atomic nor upsert. It forwards to
+        // the same `/bulk` route the SDK client uses.
+        createMany: sdk.createMany
+            ? async (data: Partial<EntityValues<M>>[], options?: { upsert?: boolean }): Promise<Entity<M>[]> => {
+                const rows = await sdk.createMany!(data as Partial<M>[], options);
+                return rows.map((row) => rowToEntity<M>(row, slug, getPks()));
+            }
+            : undefined,
         async update(id: string | number, data: Partial<EntityValues<M>>): Promise<Entity<M>> {
             const row = await sdk.update(id, data as Partial<M>);
             if (!row) throw new Error(`Update returned no data for id ${id}`);
@@ -578,12 +698,17 @@ function toEntityAccessor<M extends Record<string, unknown>>(
             if (typeof columnOrCondition === "object") {
                 return builder.where(columnOrCondition);
             }
-            return builder.where(columnOrCondition as keyof M & string, operator!, value as WhereValue<M[keyof M & string]>);
+            return builder.where(columnOrCondition as keyof M & string, operator!, value as WhereValueFor<WhereFilterOp, M[keyof M & string]>);
         },
         orderBy: (column: keyof M & string, direction?: "asc" | "desc") => new QueryBuilder<M>(accessor).orderBy(column, direction),
         limit: (count: number) => new QueryBuilder<M>(accessor).limit(count),
         offset: (count: number) => new QueryBuilder<M>(accessor).offset(count),
         search: (searchString: string) => new QueryBuilder<M>(accessor).search(searchString),
+        vectorSearch: (
+            property: string,
+            vector: number[],
+            options?: { distance?: "cosine" | "l2" | "inner_product"; threshold?: number }
+        ) => new QueryBuilder<M>(accessor).vectorSearch(property, vector, options),
         include: (...relations: string[]) => new QueryBuilder<M>(accessor).include(...relations)
     };
     return accessor;
@@ -598,7 +723,16 @@ function toEntityAccessor<M extends Record<string, unknown>>(
  * admin `RebaseDataContext` — without it the admin renders rows with only their
  * `id`.
  */
-export function wrapAsEntityData(sdkData: RebaseSdkData, options?: EntityDataOptions): RebaseData {
+/**
+ * Only the by-slug accessor is asked for, so only that is required.
+ *
+ * Taking a whole `RebaseSdkData` meant taking `RebaseSdkData<unknown>`, whose
+ * dynamic branch is an index signature — and no `RebaseSdkData<DB>` satisfies
+ * it, because its own `collection` method is not a `SDKCollectionClient`. So a
+ * caller holding a *typed* client could not pass it to a function that reads
+ * one method off it, and that method is identical on every instantiation.
+ */
+export function wrapAsEntityData(sdkData: Pick<RebaseSdkData, "collection">, options?: EntityDataOptions): RebaseData {
     const cache = new Map<string, CollectionAccessor>();
     const primaryKeysFor = createPrimaryKeyResolver(options);
 

package/src/data/filter-conditions.ts

@@ -0,0 +1,46 @@
+/**
+ * The `FilterValues` grammar, one level below the wire codec.
+ *
+ * A field's filter is either one `[op, value]` tuple or an **array** of them —
+ * `{ age: [[">=", 18], ["<", 65]] }` — which is what the fluent builder produces
+ * from two `.where()` calls on the same column. Reading that shape is grammar,
+ * not a driver detail, so every compiler reads it through here.
+ *
+ * It lived only inside the Postgres compiler, and the Mongo one destructured
+ * `const [op, value] = filterParam` regardless: given the array-of-tuples form
+ * `op` bound to `[">=", 18]`, no operator matched, and the condition was
+ * dropped. Both of them. A read asking for adults under 65 returned every row
+ * of the collection with a 200.
+ *
+ * @module
+ */
+
+import type { WhereFilterOp } from "@rebasepro/types";
+
+/** One `[operator, value]` condition. */
+export type FilterTuple = [WhereFilterOp, unknown];
+
+/**
+ * Read one field's filter as the list of conditions it stands for.
+ *
+ * Accepts both declared shapes and normalises them to a list:
+ *
+ * ```ts
+ * toFilterTuples(["==", "active"])          // [["==", "active"]]
+ * toFilterTuples([[">=", 18], ["<", 65]])   // [[">=", 18], ["<", 65]]
+ * ```
+ *
+ * A falsy, non-array or empty param has no conditions in it — the empty list,
+ * so a caller iterating adds nothing rather than compiling a tuple of
+ * `undefined`s and logging about an operator nobody sent.
+ */
+export function toFilterTuples(filterParam: unknown): FilterTuple[] {
+    if (!filterParam || !Array.isArray(filterParam) || filterParam.length === 0) return [];
+    // The first element discriminates: a condition starts with an operator
+    // string, a list of conditions starts with a condition. `["in", ["a","b"]]`
+    // is one condition whose value happens to be a list.
+    if (Array.isArray(filterParam[0])) {
+        return filterParam as FilterTuple[];
+    }
+    return [filterParam as FilterTuple];
+}

package/src/data/filter-dialect.ts

@@ -9,8 +9,10 @@
  * metadata, so type coercion is the responsibility of the server-side data
  * driver which has access to the collection schema.
  *
- * Commas inside list values are backslash-escaped (`\,`), and literal
- * backslashes are escaped as `\\`.
+ * Structural characters inside a value are backslash-escaped: `,` → `\,`,
+ * `(` → `\(`, `)` → `\)`, and a literal backslash as `\\`. Decoding is
+ * deliberately conservative — only those four sequences are decoded, so a
+ * backslash that arrives unescaped from an older client survives intact.
  *
  * @module
  */
@@ -51,26 +53,49 @@ function stringifyValue(value: unknown): string {
 // ---------------------------------------------------------------------------
 
 /**
- * Escape a single list item for the wire format.
- * `\` → `\\`, `,` → `\,`
+ * Characters that carry structure in the wire format and must therefore be
+ * escaped inside a value: the separator, the group delimiters, and the escape
+ * character itself.
+ *
+ * Parentheses are here because `and(...)`/`or(...)` groups are parsed by
+ * tracking paren depth. A value containing one is not merely ambiguous, it
+ * moves where the parser thinks the group ends.
+ */
+const WIRE_SPECIALS = /[\\,()]/g;
+
+/**
+ * Escape a value for the wire format: `\` → `\\`, `,` → `\,`, `(` → `\(`,
+ * `)` → `\)`.
  */
-function escapeListItem(value: string): string {
-    return value.replace(/\\/g, "\\\\").replace(/,/g, "\\,");
+function escapeWireValue(value: string): string {
+    return value.replace(WIRE_SPECIALS, ch => `\\${ch}`);
 }
 
 /**
- * Unescape a single list item from the wire format.
- * `\\` → `\`, `\,` → `,`
+ * Unescape a wire-format value.
+ *
+ * **Conservative**, and deliberately so: only the four sequences
+ * {@link escapeWireValue} actually produces are decoded. A backslash followed
+ * by anything else is left exactly as it is.
+ *
+ * This used to consume the backslash before *any* character, which is
+ * indistinguishable for anything this codec emitted — it only ever emits those
+ * four — but not for input arriving from elsewhere. A client on an older
+ * release sends a Windows path or a LIKE pattern with a literal `C:\x`
+ * unescaped, and greedy unescaping silently turned it into `C:x`, changing
+ * which rows matched. Decoding only what the encoder can produce makes the two
+ * directions agree across versions.
  */
-function unescapeListItem(value: string): string {
+function unescapeWireValue(value: string): string {
     let result = "";
     for (let i = 0; i < value.length; i++) {
-        if (value[i] === "\\" && i + 1 < value.length) {
-            result += value[i + 1];
-            i++; // skip next char
-        } else {
-            result += value[i];
+        const next = value[i + 1];
+        if (value[i] === "\\" && (next === "\\" || next === "," || next === "(" || next === ")")) {
+            result += next;
+            i++;
+            continue;
         }
+        result += value[i];
     }
     return result;
 }
@@ -88,20 +113,49 @@ function splitListItems(inner: string): string[] {
     let current = "";
     for (let i = 0; i < inner.length; i++) {
         if (inner[i] === "\\" && i + 1 < inner.length) {
-            // Escaped character — consume both chars
+            // Escaped pair — consume both chars so the comma in `\,` is not
+            // read as a separator. Kept verbatim; decoding happens once, below.
             current += inner[i] + inner[i + 1];
             i++;
         } else if (inner[i] === ",") {
-            items.push(unescapeListItem(current));
+            items.push(unescapeWireValue(current));
             current = "";
         } else {
             current += inner[i];
         }
     }
-    items.push(unescapeListItem(current));
+    items.push(unescapeWireValue(current));
     return items;
 }
 
+/**
+ * Split a group body on commas at paren depth 0, honouring escapes.
+ *
+ * The escape-awareness is the point. The splitter used to track only paren
+ * depth, so a comma inside a scalar value ended a condition:
+ * `or(name.eq.Doe, John,age.gte.18)` parsed as *three* conditions, the middle
+ * one a fabricated `" John" == true`. On an `or` that widens the result set,
+ * and nothing anywhere reports an error — the query simply stops meaning what
+ * the caller wrote.
+ */
+function splitGroupItems(inner: string): string[] {
+    const parts: string[] = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < inner.length; i++) {
+        const ch = inner[i];
+        if (ch === "\\" && i + 1 < inner.length) { i++; continue; }
+        if (ch === "(") depth++;
+        else if (ch === ")") depth--;
+        else if (ch === "," && depth === 0) {
+            parts.push(inner.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(inner.slice(start));
+    return parts;
+}
+
 // ---------------------------------------------------------------------------
 // Typed operator map lookups (no `as any`)
 // ---------------------------------------------------------------------------
@@ -146,7 +200,7 @@ function serializeTuple(tuple: [WhereFilterOp, unknown]): string {
     }
 
     if (Array.isArray(value)) {
-        const items = value.map(v => escapeListItem(stringifyValue(v))).join(",");
+        const items = value.map(v => escapeWireValue(stringifyValue(v))).join(",");
         return `${restOp}.(${items})`;
     }
 
@@ -337,10 +391,13 @@ export function serializeLogicalCondition(
     // FilterCondition
     const restOp = CANONICAL_OP_LOOKUP[cond.operator] ?? "eq";
     if (Array.isArray(cond.value)) {
-        const items = cond.value.map(v => escapeListItem(stringifyValue(v))).join(",");
+        const items = cond.value.map(v => escapeWireValue(stringifyValue(v))).join(",");
         return `${cond.column}.${restOp}.(${items})`;
     }
-    return `${cond.column}.${restOp}.${stringifyValue(cond.value)}`;
+    // Escaped, like a list item. A scalar inside a group sits between the same
+    // delimiters a list item does, so leaving it raw let a comma in the value
+    // end the condition early — see `splitGroupItems`.
+    return `${cond.column}.${restOp}.${escapeWireValue(stringifyValue(cond.value))}`;
 }
 
 /**
@@ -354,28 +411,42 @@ export function serializeLogicalCondition(
  * deserializeLogicalCondition("or(status.eq.active,age.gte.18)")
  * // → { type: "or", conditions: [...] }
  */
+/**
+ * How deeply `or(...)`/`and(...)` groups may nest.
+ *
+ * This parser recurses once per level, on a value that arrives in a query
+ * string. Unbounded, twenty thousand levels reached `RangeError: Maximum call
+ * stack size exceeded`, which a caller sees as a 500 about the call stack
+ * rather than a 400 about their filter. Node's 16 KB header cap keeps a GET
+ * below that in practice, but "the HTTP layer happens to stop it" is not a
+ * bound this parser should rely on.
+ *
+ * Thirty-two is far past anything a real filter expresses; the deepest in this
+ * repository's own tests is three.
+ */
+export const MAX_LOGICAL_NESTING_DEPTH = 32;
+
 export function deserializeLogicalCondition(
-    str: string
+    str: string,
+    // Not `depth`: the body already uses that name for paren tracking, inside a
+    // block that shadows a parameter of the same name — so the recursion
+    // counter silently became the paren counter and never grew.
+    nesting = 0
 ): LogicalCondition | FilterCondition {
+    if (nesting > MAX_LOGICAL_NESTING_DEPTH) {
+        throw new Error(
+            `Filter groups nest more than ${MAX_LOGICAL_NESTING_DEPTH} levels deep. ` +
+            "Flatten the condition — `or(a,or(b,c))` is `or(a,b,c)`."
+        );
+    }
     // Check for logical group: "and(...)" or "or(...)"
     const logicalMatch = str.match(/^(and|or)\((.+)\)$/);
     if (logicalMatch) {
         const type = logicalMatch[1] as "and" | "or";
         const innerStr = logicalMatch[2];
 
-        // Split on commas that are not inside parentheses
-        const conditions: (LogicalCondition | FilterCondition)[] = [];
-        let depth = 0;
-        let start = 0;
-        for (let i = 0; i < innerStr.length; i++) {
-            if (innerStr[i] === "(") depth++;
-            else if (innerStr[i] === ")") depth--;
-            else if (innerStr[i] === "," && depth === 0) {
-                conditions.push(deserializeLogicalCondition(innerStr.slice(start, i)));
-                start = i + 1;
-            }
-        }
-        conditions.push(deserializeLogicalCondition(innerStr.slice(start)));
+        const conditions = splitGroupItems(innerStr)
+            .map(part => deserializeLogicalCondition(part, nesting + 1));
 
         return { type, conditions };
     }
@@ -392,18 +463,20 @@ export function deserializeLogicalCondition(
     const secondDot = rest.indexOf(".");
     if (secondDot === -1) {
         // "column.value" — treat as equality (value kept as string)
-        return { column, operator: "==", value: rest };
+        return { column, operator: "==", value: unescapeWireValue(rest) };
     }
 
     const opStr = rest.substring(0, secondDot);
     const valueStr = rest.substring(secondDot + 1);
     const operator = toCanonicalOp(opStr) ?? "==";
 
-    // Parse list values with escape-aware splitting
+    // Parse list values with escape-aware splitting. The wrapping parens are
+    // written by the serializer *after* the items are escaped, so an escaped
+    // paren inside an item can never be mistaken for them.
     if (valueStr.startsWith("(") && valueStr.endsWith(")")) {
         const items = splitListItems(valueStr.slice(1, -1));
         return { column, operator, value: items };
     }
 
-    return { column, operator, value: valueStr };
+    return { column, operator, value: unescapeWireValue(valueStr) };
 }