turbine-orm 0.65.0 → 0.66.0

package/dist/query/where.js

@@ -10,11 +10,46 @@
  * instance (built once in its constructor) exposing exactly the class-resident
  * primitives this module needs. See builder.ts for the thin delegating methods.
  */
-import { UnsupportedFeatureError, ValidationError } from '../errors.js';
+import { getErrorMessageMode, UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { camelToSnake, normalizeKeyColumns } from '../schema.js';
 import { assertBindableEqualsOperand, findArrayUniqueKey, findJsonUniqueKey, isArrayFilter, isColumnRef, isJsonFilter, isUnmatchedPlainObject, isWhereOperator, JSON_FILTER_KEYS, JSON_RANGE_OPERATORS, JSON_STRING_OPERATORS, VECTOR_DISTANCE_COMPARATORS, VECTOR_METRIC_OPERATORS, validateTextSearchConfig, } from './filters.js';
-import { coerceTemporalValue, escapeLike, OPERATOR_KEYS, ownLookup } from './utils.js';
-import { classifyScalarForSql, fingerprintScalarToken, walkWhere, } from './where-compile.js';
+import { coerceTemporalValue, escapeLike, isInternalCombinator, markInternalCombinator, OPERATOR_KEYS, ownLookup, } from './utils.js';
+import { assertWhereDepth, classifyScalarForSql, fingerprintScalarToken, walkWhere, } from './where-compile.js';
+/**
+ * LIKE-escape one bound operand through the ACTIVE dialect, falling back to the
+ * shared {@link escapeLike} (`\`, `%`, `_`) when the dialect declares no
+ * override. See {@link Dialect.escapeLikePattern} for why an engine would need
+ * one (T-SQL also treats `[` as a character-class opener, so the standard set
+ * leaves `{ contains: '[draft]' }` matching any title containing d, r, a, f or
+ * t).
+ *
+ * Every LIKE operand in this module goes through here, the scalar
+ * `contains`/`startsWith`/`endsWith` family and the JSON substring operators,
+ * on BOTH the SQL-build and the cache-hit param-collect side. That is the point
+ * of routing it through one function: the two sides must escape identically or
+ * a warmed template binds a differently-escaped value than the one its SQL was
+ * compiled for.
+ */
+function likeOperand(qi, value) {
+    return qi.dialect.escapeLikePattern?.(value) ?? escapeLike(value);
+}
+/**
+ * Render a caller-supplied VALUE for an error message, or a neutral placeholder
+ * when the process is in the default `'safe'` error-message mode.
+ *
+ * SECURITY.md states that where-clause values are rendered as key names only.
+ * These JSON-operator diagnostics used to interpolate the operand verbatim, and
+ * the `path`-missing branch fires on a perfectly VALID value whose only problem
+ * is a missing `path`, so the leak was not limited to malformed input: a
+ * `stringContains` search term reached the error text (and from there a log
+ * aggregator or an API error body) on a query the caller merely wrote wrong.
+ *
+ * Same gate the `NotFoundError` where-rendering already uses, so one setting
+ * governs both.
+ */
+function valueForMessage(value) {
+    return getErrorMessageMode() === 'verbose' ? JSON.stringify(value) : '<value>';
+}
 /**
  * Produce a value-invariant fingerprint of a where clause.
  * Same keys + same operator shapes + same combinator structure => same string.
@@ -22,22 +57,23 @@ import { classifyScalarForSql, fingerprintScalarToken, walkWhere, } from './wher
  *
  * @internal Exposed as package-private for testing via class access.
  */
-export function fingerprintWhere(qi, where) {
+export function fingerprintWhere(qi, where, depth = 0) {
+    assertWhereDepth(depth);
     const parts = [];
     for (const event of walkWhere(qi.whereHost, where)) {
         switch (event.kind) {
             case 'or':
-                parts.push(`OR[${event.conditions.map((cond) => fingerprintWhere(qi, cond)).join(',')}]`);
+                parts.push(`OR[${event.conditions.map((cond) => fingerprintWhere(qi, cond, depth + 1)).join(',')}]`);
                 break;
             case 'and':
-                parts.push(`AND[${event.conditions.map((cond) => fingerprintWhere(qi, cond)).join(',')}]`);
+                parts.push(`AND[${event.conditions.map((cond) => fingerprintWhere(qi, cond, depth + 1)).join(',')}]`);
                 break;
             case 'not':
-                parts.push(`NOT(${fingerprintWhere(qi, event.condition)})`);
+                parts.push(`NOT(${fingerprintWhere(qi, event.condition, depth + 1)})`);
                 break;
             case 'relation':
                 // { posts: { some: { published: true } } } → `posts:{some(...)}`
-                parts.push(`${event.key}:{${fingerprintRelationParts(qi, event.relDef, event.filterObj).join(',')}}`);
+                parts.push(`${event.key}:{${fingerprintRelationParts(qi, event.relDef, event.filterObj, depth + 1).join(',')}}`);
                 break;
             case 'scalar':
                 // Column-blind scalar token (see fingerprintScalarToken): the value's
@@ -55,28 +91,28 @@ export function fingerprintWhere(qi, where) {
  * {@link fingerprintRelFilter} so the FULL inner shape is captured (two
  * different sub-wheres must never collide on one cached SQL text).
  */
-export function fingerprintRelationParts(qi, relDef, filterObj) {
+export function fingerprintRelationParts(qi, relDef, filterObj, depth = 0) {
     const relParts = [];
     if (filterObj.some !== undefined)
         relParts.push(filterObj.some === null
             ? 'some(null)'
-            : `some(${fingerprintRelFilter(qi, relDef.to, filterObj.some)})`);
+            : `some(${fingerprintRelFilter(qi, relDef.to, filterObj.some, depth + 1)})`);
     if (filterObj.every !== undefined)
         relParts.push(filterObj.every === null
             ? 'every(null)'
-            : `every(${fingerprintRelFilter(qi, relDef.to, filterObj.every)})`);
+            : `every(${fingerprintRelFilter(qi, relDef.to, filterObj.every, depth + 1)})`);
     if (filterObj.none !== undefined)
         relParts.push(filterObj.none === null
             ? 'none(null)'
-            : `none(${fingerprintRelFilter(qi, relDef.to, filterObj.none)})`);
+            : `none(${fingerprintRelFilter(qi, relDef.to, filterObj.none, depth + 1)})`);
     if (filterObj.is !== undefined)
         relParts.push(filterObj.is === null
             ? 'is(null)'
-            : `is(${fingerprintRelFilter(qi, relDef.to, filterObj.is)})`);
+            : `is(${fingerprintRelFilter(qi, relDef.to, filterObj.is, depth + 1)})`);
     if (filterObj.isNot !== undefined)
         relParts.push(filterObj.isNot === null
             ? 'isNot(null)'
-            : `isNot(${fingerprintRelFilter(qi, relDef.to, filterObj.isNot)})`);
+            : `isNot(${fingerprintRelFilter(qi, relDef.to, filterObj.isNot, depth + 1)})`);
     return relParts;
 }
 /**
@@ -85,10 +121,10 @@ export function fingerprintRelationParts(qi, relDef, filterObj) {
  * unknown, an empty-relations host makes every key scalar (matching the old
  * `meta?.relations` short-circuit).
  */
-export function fingerprintRelFilter(qi, targetTable, subWhere) {
+export function fingerprintRelFilter(qi, targetTable, subWhere, depth = 0) {
     const meta = qi.schema.tables[targetTable];
     const host = meta ? scopedWhereHost(qi, meta) : emptyRelationsHost(qi, targetTable);
-    return fingerprintScopedWhere(qi, host, subWhere);
+    return fingerprintScopedWhere(qi, host, subWhere, depth);
 }
 /**
  * Walk a where clause and push ONLY values into `params`, in the EXACT same
@@ -97,7 +133,8 @@ export function fingerprintRelFilter(qi, targetTable, subWhere) {
  *
  * @internal Exposed as package-private for testing.
  */
-export function collectWhereParams(qi, where, params) {
+export function collectWhereParams(qi, where, params, depth = 0) {
+    assertWhereDepth(depth);
     // ONE canonical walk (shared with fingerprintWhere + buildWhereClause), so
     // the key order + combinator structure cannot drift out of lockstep.
     for (const event of walkWhere(qi.whereHost, where)) {
@@ -105,13 +142,13 @@ export function collectWhereParams(qi, where, params) {
             case 'or':
             case 'and':
                 for (const cond of event.conditions)
-                    collectWhereParams(qi, cond, params);
+                    collectWhereParams(qi, cond, params, depth + 1);
                 break;
             case 'not':
-                collectWhereParams(qi, event.condition, params);
+                collectWhereParams(qi, event.condition, params, depth + 1);
                 break;
             case 'relation':
-                collectRelationFilterParams(qi, event.relDef, event.filterObj, params);
+                collectRelationFilterParams(qi, event.relDef, event.filterObj, params, depth + 1);
                 break;
             case 'scalar':
                 collectScalarParams(qi, event.key, event.value, params);
@@ -180,40 +217,40 @@ export function collectScalarParams(qi, key, value, params) {
  * Shared by every collect site that mirrors buildRelationFilter
  * (collectWhereParams, collectRelFilterParams, collectAliasWhereParams).
  */
-export function collectRelationFilterParams(qi, relDef, filterObj, params) {
+export function collectRelationFilterParams(qi, relDef, filterObj, params, depth = 0) {
     const target = relDef.to;
     if (filterObj.some !== undefined && filterObj.some !== null) {
-        collectRelFilterParams(qi, target, filterObj.some, params);
+        collectRelFilterParams(qi, target, filterObj.some, params, depth + 1);
         collectTargetGlobalFilterExists(qi, target, params);
     }
     if (filterObj.none !== undefined && filterObj.none !== null) {
-        collectRelFilterParams(qi, target, filterObj.none, params);
+        collectRelFilterParams(qi, target, filterObj.none, params, depth + 1);
         collectTargetGlobalFilterExists(qi, target, params);
     }
     if (filterObj.every !== undefined && filterObj.every !== null) {
         // gf is only emitted (build) when the `every` sub-where compiles to a
         // filter, otherwise `every` is trivially true and no subquery is built.
-        if (buildSubWhereForRelation(qi, target, filterObj.every, []) !== null) {
-            collectRelFilterParams(qi, target, filterObj.every, params);
+        if (buildSubWhereForRelation(qi, target, filterObj.every, [], depth + 1) !== null) {
+            collectRelFilterParams(qi, target, filterObj.every, params, depth + 1);
             collectTargetGlobalFilterExists(qi, target, params);
         }
     }
     if (filterObj.is !== undefined) {
         if (filterObj.is !== null)
-            collectRelFilterParams(qi, target, filterObj.is, params);
+            collectRelFilterParams(qi, target, filterObj.is, params, depth + 1);
         collectTargetGlobalFilterExists(qi, target, params);
     }
     if (filterObj.isNot !== undefined) {
         if (filterObj.isNot !== null)
-            collectRelFilterParams(qi, target, filterObj.isNot, params);
+            collectRelFilterParams(qi, target, filterObj.isNot, params, depth + 1);
         collectTargetGlobalFilterExists(qi, target, params);
     }
 }
-export function collectRelFilterParams(qi, targetTable, subWhere, params) {
+export function collectRelFilterParams(qi, targetTable, subWhere, params, depth = 0) {
     const meta = qi.schema.tables[targetTable];
     if (!meta)
         return;
-    collectScopedWhereParams(qi, relationWhereScope(qi, targetTable, meta), subWhere, params);
+    collectScopedWhereParams(qi, relationWhereScope(qi, targetTable, meta), subWhere, params, depth);
 }
 /**
  * Collect params from operator clauses. Mirrors buildOperatorClauses:
@@ -250,11 +287,11 @@ export function collectOperatorParams(qi, column, op, params, refCtx) {
     if (op.notIn !== undefined)
         params.push(qi.inParam(cv(op.notIn)));
     if (op.contains !== undefined)
-        params.push(`%${escapeLike(op.contains)}%`);
+        params.push(`%${likeOperand(qi, op.contains)}%`);
     if (op.startsWith !== undefined)
-        params.push(`${escapeLike(op.startsWith)}%`);
+        params.push(`${likeOperand(qi, op.startsWith)}%`);
     if (op.endsWith !== undefined)
-        params.push(`%${escapeLike(op.endsWith)}`);
+        params.push(`%${likeOperand(qi, op.endsWith)}`);
 }
 /**
  * Collect params from JSON filter. Mirrors buildJsonFilterClauses exactly:
@@ -277,9 +314,14 @@ export function collectJsonFilterParams(qi, filter, params, column) {
         params.push(String(filter.equals));
     }
     else if (filter.equals !== undefined) {
+        // Mirrors the build path's refusal, and thrown before any param is pushed,
+        // like the text-search gate a few cases above. Not defensive: it is what
+        // stops a warmed template serving a shape the cold build refuses.
+        requireJsonContains(qi, 'equals');
         params.push(JSON.stringify(filter.equals));
     }
     if (filter.contains !== undefined) {
+        requireJsonContains(qi, 'contains');
         params.push(JSON.stringify(filter.contains));
     }
     if (filter.hasKey !== undefined) {
@@ -291,7 +333,7 @@ export function collectJsonFilterParams(qi, filter, params, column) {
     }
     for (const { pattern, value } of jsonStringEntries(filter, column)) {
         pushPathOnce();
-        params.push(pattern(escapeLike(value)));
+        params.push(pattern(likeOperand(qi, value)));
     }
 }
 /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
@@ -308,16 +350,15 @@ export function collectArrayFilterParams(qi, filter, params) {
 /**
  * Collect params for a vector distance WHERE filter. Mirrors
  * {@link buildVectorFilterClauses}: the `$n::vector` query vector first, then
- * the comparison threshold(s).
+ * the comparison threshold(s), both enumerated AND validated by the shared
+ * {@link vectorThresholdEntries} (see there for the production-only bug that
+ * inlining the loop on both sides produced).
  */
 export function collectVectorFilterParams(qi, field, rawColumn, filter, params) {
     const dist = filter.distance;
     pushVectorParam(qi, field, rawColumn, dist.to, params);
-    for (const cmp of Object.keys(VECTOR_DISTANCE_COMPARATORS)) {
-        const threshold = dist[cmp];
-        if (threshold !== undefined)
-            params.push(threshold);
-    }
+    for (const { threshold } of vectorThresholdEntries(filter, field))
+        params.push(threshold);
 }
 /** Build WHERE clause from a where object (supports operators, NULL, OR) */
 export function buildWhere(qi, where) {
@@ -364,7 +405,10 @@ export function mergeGlobalFilter(qi, userWhere) {
         return userWhere;
     if (userWhere === undefined)
         return gf;
-    return { AND: [userWhere, gf] };
+    // Branded: this `AND` is Turbine's, always exactly two branches, so it must
+    // not put the statement on the variable-arity (unnamed) path. See
+    // {@link markInternalCombinator}.
+    return markInternalCombinator({ AND: [userWhere, gf] });
 }
 /**
  * SQL clause for `targetTable`'s global filter rendered against `alias`
@@ -483,15 +527,26 @@ allowFullTableScan) {
  * Returns null if no conditions exist.
  * Supports: equality, operators, NULL, OR, AND, NOT, relation filters (some/every/none).
  */
-export function buildWhereClause(qi, where, params) {
+export function buildWhereClause(qi, where, params, depth = 0) {
+    assertWhereDepth(depth);
     const andClauses = [];
+    // A combinator ARRAY is the one shape whose branch COUNT is written into the
+    // SQL text, so the statement stops being a fixed shape (see
+    // markVariableArity). Marked here, on the BUILD walk, because the mark
+    // is read immediately after `build()` inside `acquireSql`, so it decides the
+    // prepared-statement name of the very entry being created. The internal
+    // wrapper the global-filter merge synthesizes is exempt, see
+    // INTERNAL_COMBINATOR.
+    const internal = isInternalCombinator(where);
     // ONE canonical walk (shared with fingerprintWhere + collectWhereParams).
     for (const event of walkWhere(qi.whereHost, where)) {
         switch (event.kind) {
             case 'or': {
+                if (!internal)
+                    qi.markVariableArity();
                 const orClauses = [];
                 for (const orCond of event.conditions) {
-                    const sub = buildWhereClause(qi, orCond, params);
+                    const sub = buildWhereClause(qi, orCond, params, depth + 1);
                     if (sub)
                         orClauses.push(sub);
                 }
@@ -500,21 +555,23 @@ export function buildWhereClause(qi, where, params) {
                 break;
             }
             case 'and':
+                if (!internal)
+                    qi.markVariableArity();
                 for (const andCond of event.conditions) {
-                    const sub = buildWhereClause(qi, andCond, params);
+                    const sub = buildWhereClause(qi, andCond, params, depth + 1);
                     if (sub)
                         andClauses.push(sub);
                 }
                 break;
             case 'not': {
-                const sub = buildWhereClause(qi, event.condition, params);
+                const sub = buildWhereClause(qi, event.condition, params, depth + 1);
                 if (sub)
                     andClauses.push(`NOT (${sub})`);
                 break;
             }
             case 'relation': {
                 // { posts: { some: { published: true } } } → EXISTS / NOT EXISTS
-                const relClause = buildRelationFilter(qi, event.key, event.relDef, event.filterObj, params);
+                const relClause = buildRelationFilter(qi, event.key, event.relDef, event.filterObj, params, undefined, depth);
                 if (relClause)
                     andClauses.push(relClause);
                 break;
@@ -639,14 +696,20 @@ export function aliasWhereScope(qi, targetTable, meta, alias) {
  * former hand-mirrored walkers, since it renders the same clauses in the same
  * ({@link walkWhere}-canonical) key order.
  */
-export function buildScopedWhere(qi, scope, where, params) {
+export function buildScopedWhere(qi, scope, where, params, depth = 0) {
+    assertWhereDepth(depth);
     const clauses = [];
+    const internal = isInternalCombinator(where);
     for (const event of walkWhere(scope.host, where)) {
         switch (event.kind) {
             case 'or':
             case 'and': {
+                // Same variable-arity rule as the top level: a nested relation filter
+                // or a relation `with` where can carry a caller-sized OR just as easily.
+                if (!internal)
+                    qi.markVariableArity();
                 const parts = event.conditions
-                    .map((cond) => buildScopedWhere(qi, scope, cond, params))
+                    .map((cond) => buildScopedWhere(qi, scope, cond, params, depth + 1))
                     .filter((s) => s !== null)
                     .map((s) => `(${s})`);
                 if (parts.length > 0)
@@ -654,13 +717,13 @@ export function buildScopedWhere(qi, scope, where, params) {
                 break;
             }
             case 'not': {
-                const sub = buildScopedWhere(qi, scope, event.condition, params);
+                const sub = buildScopedWhere(qi, scope, event.condition, params, depth + 1);
                 if (sub)
                     clauses.push(`NOT (${sub})`);
                 break;
             }
             case 'relation': {
-                const c = buildRelationFilter(qi, event.key, event.relDef, event.filterObj, params, scope.relationParent);
+                const c = buildRelationFilter(qi, event.key, event.relDef, event.filterObj, params, scope.relationParent, depth);
                 if (c)
                     clauses.push(c);
                 break;
@@ -733,21 +796,22 @@ export function buildScopedScalarClause(qi, scope, field, value, params, clauses
  * without rebuilding SQL. Serves both {@link collectRelFilterParams} and
  * {@link collectAliasWhereParams}.
  */
-export function collectScopedWhereParams(qi, scope, where, params) {
+export function collectScopedWhereParams(qi, scope, where, params, depth = 0) {
+    assertWhereDepth(depth);
     for (const event of walkWhere(scope.host, where)) {
         switch (event.kind) {
             case 'or':
             case 'and':
                 for (const cond of event.conditions)
-                    collectScopedWhereParams(qi, scope, cond, params);
+                    collectScopedWhereParams(qi, scope, cond, params, depth + 1);
                 break;
             case 'not':
-                collectScopedWhereParams(qi, scope, event.condition, params);
+                collectScopedWhereParams(qi, scope, event.condition, params, depth + 1);
                 break;
             case 'relation':
                 // Same some→none→every→is→isNot (each: sub-where params then target
                 // global-filter params) as buildRelationFilter emits.
-                collectRelationFilterParams(qi, event.relDef, event.filterObj, params);
+                collectRelationFilterParams(qi, event.relDef, event.filterObj, params, depth);
                 break;
             case 'scalar':
                 collectScopedScalarParams(qi, scope, event.key, event.value, params);
@@ -791,21 +855,22 @@ export function collectScopedScalarParams(qi, scope, field, value, params) {
  * may differ from the pre-unification walkers as long as collisions stay
  * impossible.
  */
-export function fingerprintScopedWhere(qi, host, where) {
+export function fingerprintScopedWhere(qi, host, where, depth = 0) {
+    assertWhereDepth(depth);
     const parts = [];
     for (const event of walkWhere(host, where)) {
         switch (event.kind) {
             case 'or':
-                parts.push(`OR[${event.conditions.map((c) => fingerprintScopedWhere(qi, host, c)).join(',')}]`);
+                parts.push(`OR[${event.conditions.map((c) => fingerprintScopedWhere(qi, host, c, depth + 1)).join(',')}]`);
                 break;
             case 'and':
-                parts.push(`AND[${event.conditions.map((c) => fingerprintScopedWhere(qi, host, c)).join(',')}]`);
+                parts.push(`AND[${event.conditions.map((c) => fingerprintScopedWhere(qi, host, c, depth + 1)).join(',')}]`);
                 break;
             case 'not':
-                parts.push(`NOT(${fingerprintScopedWhere(qi, host, event.condition)})`);
+                parts.push(`NOT(${fingerprintScopedWhere(qi, host, event.condition, depth + 1)})`);
                 break;
             case 'relation':
-                parts.push(`${event.key}:{${fingerprintRelationParts(qi, event.relDef, event.filterObj).join(',')}}`);
+                parts.push(`${event.key}:{${fingerprintRelationParts(qi, event.relDef, event.filterObj, depth).join(',')}}`);
                 break;
             case 'scalar':
                 parts.push(`${event.key}:${fingerprintScalarToken(event.value)}`);
@@ -818,7 +883,14 @@ export function fingerprintScopedWhere(qi, host, where) {
  * Build relation filter SQL: WHERE EXISTS / NOT EXISTS subquery
  * Supports: some (EXISTS), every (NOT EXISTS ... NOT), none (NOT EXISTS)
  */
-export function buildRelationFilter(qi, _relName, relDef, filterObj, params, parentTable) {
+export function buildRelationFilter(qi, _relName, relDef, filterObj, params, parentTable, 
+/**
+ * Nesting depth of the WHERE walk that reached this relation filter. Each
+ * relation descent is a level too: `{ posts: { some: { comments: { some:
+ * … } } } }` recurses through here just as `NOT` does, and is exactly as
+ * unbounded without a cap (see {@link assertWhereDepth}).
+ */
+depth = 0) {
     const targetTable = relDef.to;
     const targetMeta = qi.schema.tables[targetTable];
     if (!targetMeta)
@@ -890,21 +962,21 @@ export function buildRelationFilter(qi, _relName, relDef, filterObj, params, par
     // which also skips null. Unreachable via normalization today, guarded anyway.
     if (filterObj.some !== undefined && filterObj.some !== null) {
         const subWhere = filterObj.some;
-        const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params);
+        const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params, depth + 1);
         const filterAnd = filterClause ? ` AND ${filterClause}` : '';
         clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${filterAnd}${gfAnd()})`);
     }
     // "none": NOT EXISTS (SELECT 1 FROM target WHERE correlation AND filter AND gf)
     if (filterObj.none !== undefined && filterObj.none !== null) {
         const subWhere = filterObj.none;
-        const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params);
+        const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params, depth + 1);
         const filterAnd = filterClause ? ` AND ${filterClause}` : '';
         clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${filterAnd}${gfAnd()})`);
     }
     // "every": NOT EXISTS (SELECT 1 FROM target WHERE correlation AND gf AND NOT (filter))
     if (filterObj.every !== undefined && filterObj.every !== null) {
         const subWhere = filterObj.every;
-        const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params);
+        const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params, depth + 1);
         if (filterClause) {
             // gf params pushed AFTER filter params (collect mirrors this order), but
             // placed textually inside the domain so it restricts which rows count.
@@ -923,7 +995,7 @@ export function buildRelationFilter(qi, _relName, relDef, filterObj, params, par
         }
         else {
             const subWhere = filterObj.is;
-            const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params);
+            const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params, depth + 1);
             const filterAnd = filterClause ? ` AND ${filterClause}` : '';
             clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${filterAnd}${gfAnd()})`);
         }
@@ -936,7 +1008,7 @@ export function buildRelationFilter(qi, _relName, relDef, filterObj, params, par
         }
         else {
             const subWhere = filterObj.isNot;
-            const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params);
+            const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params, depth + 1);
             const filterAnd = filterClause ? ` AND ${filterClause}` : '';
             clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${filterAnd}${gfAnd()})`);
         }
@@ -947,11 +1019,11 @@ export function buildRelationFilter(qi, _relName, relDef, filterObj, params, par
  * Build WHERE clause conditions for a relation filter subquery.
  * Uses the target table's column mapping to resolve field names.
  */
-export function buildSubWhereForRelation(qi, targetTable, subWhere, params) {
+export function buildSubWhereForRelation(qi, targetTable, subWhere, params, depth = 0) {
     const meta = qi.schema.tables[targetTable];
     if (!meta)
         return null;
-    return buildScopedWhere(qi, relationWhereScope(qi, targetTable, meta), subWhere, params);
+    return buildScopedWhere(qi, relationWhereScope(qi, targetTable, meta), subWhere, params, depth);
 }
 /**
  * Resolve a column's Postgres type from an arbitrary table's metadata
@@ -1195,15 +1267,15 @@ export function buildOperatorClauses(qi, column, op, params, refCtx) {
     }
     const insensitive = op.mode === 'insensitive';
     if (op.contains !== undefined) {
-        params.push(`%${escapeLike(op.contains)}%`);
+        params.push(`%${likeOperand(qi, op.contains)}%`);
         clauses.push(buildLikeClause(qi, column, qi.p(params.length), insensitive));
     }
     if (op.startsWith !== undefined) {
-        params.push(`${escapeLike(op.startsWith)}%`);
+        params.push(`${likeOperand(qi, op.startsWith)}%`);
         clauses.push(buildLikeClause(qi, column, qi.p(params.length), insensitive));
     }
     if (op.endsWith !== undefined) {
-        params.push(`%${escapeLike(op.endsWith)}`);
+        params.push(`%${likeOperand(qi, op.endsWith)}`);
         clauses.push(buildLikeClause(qi, column, qi.p(params.length), insensitive));
     }
     return clauses;
@@ -1222,6 +1294,34 @@ export function requireFullTextSearch(qi) {
     throw new UnsupportedFeatureError('the full-text search filter (`search`)', qi.dialect.name, 'Full-text `search` compiles to PostgreSQL to_tsvector/to_tsquery. ' +
         'Use `contains` (LIKE) on this engine, or run the query on PostgreSQL.');
 }
+/**
+ * Gate the pathless JSON containment filters (`contains`, and the `equals`
+ * spelling that compiles to the same expression) on
+ * {@link Dialect.supportsJsonContains}.
+ *
+ * The engine this exists for is SQLite, whose emulation compares a decoded
+ * `json_each.value` against a param bound as JSON TEXT and therefore matched
+ * NOTHING, for every operand type: object, array, string and number alike all
+ * returned zero rows where PostgreSQL and MySQL returned the document (measured
+ * in-process, table in dialect.ts). Fewer rows with no error is precisely what
+ * the capability contract exists to convert into a refusal, and since the
+ * feature never worked there, refusing it removes nothing.
+ *
+ * Called from BOTH the build and the param-collect side, and here that is
+ * load-bearing rather than symmetric-for-its-own-sake: a {@link JsonFilter}
+ * fingerprints by which KEYS are present, not by what they hold, so every
+ * `contains` on a column shares one cache entry and a build-only gate would be
+ * skipped for the entire warm life of that entry.
+ */
+export function requireJsonContains(qi, clause) {
+    if (qi.dialect.supportsJsonContains)
+        return;
+    throw new UnsupportedFeatureError(`JSON containment (\`${clause}\` without \`path\`)`, qi.dialect.name, `This engine has no equivalent of PostgreSQL's \`@>\`, and the emulation Turbine used for ` +
+        `\`${clause}\` matched no rows for any operand rather than failing, so it is refused instead. ` +
+        'Filter on the specific value instead: `{ path: [...], equals: ... }` compiles to a real JSON ' +
+        'extraction (`json_extract`) rather than an emulation. For structural containment, run the ' +
+        'query on PostgreSQL or MySQL.');
+}
 /**
  * Gate the array filter operators (`has` / `hasEvery` / `hasSome` / `isEmpty`)
  * on {@link Dialect.supportsArrayColumns}. They compile to PostgreSQL array
@@ -1422,10 +1522,13 @@ export function jsonStringEntries(filter, column) {
             continue;
         if (filter.path === undefined) {
             throw new ValidationError(`[turbine] JSON operator '${op}' on ${column} requires a \`path\` ` +
-                `(e.g. { path: ['meta', 'title'], ${op}: ${JSON.stringify(value)} }).`);
+                `(e.g. { path: ['meta', 'title'], ${op}: ${valueForMessage(value)} }).`);
         }
         if (typeof value !== 'string') {
-            throw new ValidationError(`[turbine] JSON operator '${op}' on ${column} requires a string, got ${JSON.stringify(value)}.`);
+            // `typeof` rather than the value: it says everything the reader needs
+            // (they passed a number where a string belongs) and carries no data.
+            throw new ValidationError(`[turbine] JSON operator '${op}' on ${column} requires a string, got ${typeof value} ` +
+                `(${valueForMessage(value)}).`);
         }
         entries.push({ op, pattern, value });
     }
@@ -1439,11 +1542,11 @@ export function jsonRangeEntries(_qi, filter, column) {
             continue;
         if (filter.path === undefined) {
             throw new ValidationError(`[turbine] JSON range operator '${op}' on ${column} requires a \`path\` ` +
-                `(e.g. { path: ['meta', 'score'], ${op}: ${JSON.stringify(value)} }).`);
+                `(e.g. { path: ['meta', 'score'], ${op}: ${valueForMessage(value)} }).`);
         }
         if (typeof value !== 'number' && typeof value !== 'string') {
             throw new ValidationError(`[turbine] JSON range operator '${op}' on ${column} requires a number or string, ` +
-                `got ${JSON.stringify(value)}.`);
+                `got ${typeof value} (${valueForMessage(value)}).`);
         }
         if (typeof value === 'number' && !Number.isFinite(value)) {
             throw new ValidationError(`[turbine] JSON range operator '${op}' on ${column} requires a finite number.`);
@@ -1480,12 +1583,18 @@ export function buildJsonFilterClauses(qi, column, filter, params) {
         clauses.push(`${extract} = ${qi.p(params.length)}`);
     }
     else if (filter.equals !== undefined) {
-        // Containment equality: column @> $N::jsonb
+        // Containment equality: column @> $N::jsonb. A pathless `equals` compiles
+        // to the SAME containment expression `contains` does, so it inherits the
+        // same engine limitation and is refused under its own clause name (the two
+        // spellings are far enough apart that naming the wrong one would send the
+        // reader to the wrong line).
+        requireJsonContains(qi, 'equals');
         params.push(JSON.stringify(filter.equals));
         clauses.push(qi.dialect.buildJsonContains(column, qi.p(params.length)));
     }
     if (filter.contains !== undefined) {
         // Containment: column @> $N::jsonb
+        requireJsonContains(qi, 'contains');
         params.push(JSON.stringify(filter.contains));
         clauses.push(qi.dialect.buildJsonContains(column, qi.p(params.length)));
     }
@@ -1507,7 +1616,7 @@ export function buildJsonFilterClauses(qi, column, filter, params) {
     // `_` matches literally instead of turning into a wildcard.
     for (const { pattern, value } of jsonStringEntries(filter, column)) {
         const extract = pathExtract();
-        params.push(pattern(escapeLike(value)));
+        params.push(pattern(likeOperand(qi, value)));
         clauses.push(buildLikeClause(qi, extract, qi.p(params.length), filter.mode === 'insensitive'));
     }
     return clauses;
@@ -1592,21 +1701,48 @@ export function buildVectorFilterClauses(qi, field, rawColumn, filter, params) {
     const placeholder = pushVectorParam(qi, field, rawColumn, dist.to, params);
     const distanceExpr = `${qi.q(rawColumn)} ${operator} ${placeholder}`;
     const clauses = [];
+    for (const { sqlOp, threshold } of vectorThresholdEntries(filter, field)) {
+        params.push(threshold);
+        clauses.push(`${distanceExpr} ${sqlOp} ${qi.p(params.length)}`);
+    }
+    return clauses;
+}
+/**
+ * Validate and enumerate the distance comparisons on a vector filter, in the
+ * fixed {@link VECTOR_DISTANCE_COMPARATORS} order. Shared by the SQL-build path
+ * ({@link buildVectorFilterClauses}) and the cache-hit param-collect path
+ * ({@link collectVectorFilterParams}), exactly like {@link jsonRangeEntries}.
+ *
+ * IT IS THE VALIDATION THAT MAKES THIS SHARED, not the enumeration. Both sides
+ * used to inline the same `for` loop, and only the build side checked the
+ * threshold. That build side does not run on a cache HIT, and outside dev the
+ * lockstep cross-check (which re-runs it, and is what masked this) is off, so a
+ * warmed template bound `lt: NaN`, `lt: '5'` or `lt: { a: 1 }` straight into
+ * the statement. NaN is the one that matters: Postgres sorts it above every
+ * real distance, so `distance < NaN` matches EVERY row, i.e. the predicate
+ * inverts, silently, in production only. Same bug class as the 0.19.2 /
+ * 0.32.1 cache-hit drifts, and the same fix: one function, both paths.
+ *
+ * The "at least one comparison" refusal lives here too, so the collect path
+ * cannot quietly accept a filter the build path rejects.
+ */
+export function vectorThresholdEntries(filter, field) {
+    const dist = filter.distance;
+    const entries = [];
     for (const [cmp, sqlOp] of Object.entries(VECTOR_DISTANCE_COMPARATORS)) {
         const threshold = dist[cmp];
         if (threshold === undefined)
             continue;
         if (typeof threshold !== 'number' || !Number.isFinite(threshold)) {
             throw new ValidationError(`[turbine] Vector distance threshold "${cmp}" on "${field}" must be a finite number; ` +
-                `got ${JSON.stringify(threshold)}.`);
+                `got ${typeof threshold} (${valueForMessage(threshold)}).`);
         }
-        params.push(threshold);
-        clauses.push(`${distanceExpr} ${sqlOp} ${qi.p(params.length)}`);
+        entries.push({ sqlOp, threshold });
     }
-    if (clauses.length === 0) {
+    if (entries.length === 0) {
         throw new ValidationError(`[turbine] Vector distance filter on "${field}" requires at least one comparison (lt / lte / gt / gte).`);
     }
-    return clauses;
+    return entries;
 }
 /**
  * Build SQL clause for full-text search using to_tsvector @@ to_tsquery.