turbine-orm 0.81.0 → 0.90.0

package/dist/cjs/query/where.js

@@ -12,6 +12,8 @@
  * primitives this module needs. See builder.ts for the thin delegating methods.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEXT_COMPARED_TYPES = exports.assertJsonFilterKeys = void 0;
+exports.adviceLogger = adviceLogger;
 exports.fingerprintWhere = fingerprintWhere;
 exports.fingerprintRelationParts = fingerprintRelationParts;
 exports.fingerprintRelFilter = fingerprintRelFilter;
@@ -27,6 +29,7 @@ exports.buildWhere = buildWhere;
 exports.resolveGlobalFilterFrom = resolveGlobalFilterFrom;
 exports.resolveGlobalFilter = resolveGlobalFilter;
 exports.mergeGlobalFilter = mergeGlobalFilter;
+exports.withTargetGlobalFilter = withTargetGlobalFilter;
 exports.targetGlobalFilterAlias = targetGlobalFilterAlias;
 exports.collectTargetGlobalFilterAlias = collectTargetGlobalFilterAlias;
 exports.targetGlobalFilterExists = targetGlobalFilterExists;
@@ -34,6 +37,7 @@ exports.collectTargetGlobalFilterExists = collectTargetGlobalFilterExists;
 exports.globalFilterCacheSegment = globalFilterCacheSegment;
 exports.userPredicateIsEmpty = userPredicateIsEmpty;
 exports.assertMutationHasPredicate = assertMutationHasPredicate;
+exports.emptyMutationWhereMessage = emptyMutationWhereMessage;
 exports.buildWhereClause = buildWhereClause;
 exports.buildScalarClause = buildScalarClause;
 exports.emptyRelationsHost = emptyRelationsHost;
@@ -51,6 +55,8 @@ exports.buildRelationFilter = buildRelationFilter;
 exports.buildSubWhereForRelation = buildSubWhereForRelation;
 exports.pgTypeForColumn = pgTypeForColumn;
 exports.coerceWhereOperand = coerceWhereOperand;
+exports.textComparedOperand = textComparedOperand;
+exports.utcDateTimeRewrite = utcDateTimeRewrite;
 exports.enumTypeForColumn = enumTypeForColumn;
 exports.enumCastSuffix = enumCastSuffix;
 exports.assertBindableEqualityValue = assertBindableEqualityValue;
@@ -69,9 +75,9 @@ exports.normalizeRelationFilter = normalizeRelationFilter;
 exports.isJsonColumnType = isJsonColumnType;
 exports.getColumnPgType = getColumnPgType;
 exports.getArrayElementType = getArrayElementType;
-exports.assertJsonFilterKeys = assertJsonFilterKeys;
 exports.jsonStringEntries = jsonStringEntries;
 exports.jsonRangeEntries = jsonRangeEntries;
+exports.jsonPathEqualsOperand = jsonPathEqualsOperand;
 exports.buildJsonFilterClauses = buildJsonFilterClauses;
 exports.jsonPathParam = jsonPathParam;
 exports.castJsonNumeric = castJsonNumeric;
@@ -80,11 +86,30 @@ exports.buildVectorFilterClauses = buildVectorFilterClauses;
 exports.vectorThresholdEntries = vectorThresholdEntries;
 exports.buildTextSearchClause = buildTextSearchClause;
 exports.getColumnArrayType = getColumnArrayType;
+const diagnostics_js_1 = require("../diagnostics.js");
 const errors_js_1 = require("../errors.js");
+const global_filters_config_js_1 = require("../global-filters-config.js");
+const logger_js_1 = require("../logger.js");
 const schema_js_1 = require("../schema.js");
 const filters_js_1 = require("./filters.js");
 const utils_js_1 = require("./utils.js");
 const where_compile_js_1 = require("./where-compile.js");
+// The JSON filter key check lives with the other operand checks in filters.ts;
+// re-exported so the engines keep one import site for it.
+var filters_js_2 = require("./filters.js");
+Object.defineProperty(exports, "assertJsonFilterKeys", { enumerable: true, get: function () { return filters_js_2.assertJsonFilterKeys; } });
+/**
+ * Where per-query advice goes for this context: the client's logger when its
+ * `diagnostics.advice` is on, else `undefined`. A site calls this first and
+ * builds its message only on a logger.
+ *
+ * A context without the client's diagnostics (one built by hand) resolves
+ * them here; every context a QueryInterface builds carries them, so on a query
+ * path this never reads the environment.
+ */
+function adviceLogger(qi) {
+    return (qi.diagnostics ?? (0, diagnostics_js_1.resolveDiagnostics)()).advice ? (qi.logger ?? logger_js_1.consoleLogger) : undefined;
+}
 /**
  * LIKE-escape one bound operand through the ACTIVE dialect, falling back to the
  * shared {@link escapeLike} (`\`, `%`, `_`) when the dialect declares no
@@ -120,6 +145,21 @@ function likeOperand(qi, value) {
 function valueForMessage(value) {
     return (0, errors_js_1.getErrorMessageMode)() === 'verbose' ? JSON.stringify(value) : '<value>';
 }
+/** The operand-validation context for an operator object on `refCtx`'s column. */
+function operandContext(qi, column, refCtx) {
+    if (!refCtx)
+        return { column, table: qi.table, kind: 'scalar' };
+    return { column: refCtx.rawColumn, table: refCtx.table, kind: (0, filters_js_1.operandColumnKind)(refCtx.pgType) };
+}
+/**
+ * The inner operator object of `not: { ... }`, with this object's `mode`
+ * inherited when the inner one sets none. The fingerprint reads the same
+ * effective mode (`fingerprintOperatorShape`).
+ */
+function notOperand(op) {
+    const inner = op.not;
+    return inner.mode === undefined && op.mode !== undefined ? { ...inner, mode: op.mode } : inner;
+}
 /**
  * Produce a value-invariant fingerprint of a where clause.
  * Same keys + same operator shapes + same combinator structure => same string.
@@ -156,25 +196,20 @@ function fingerprintWhere(qi, where, depth = 0) {
 }
 /**
  * Fingerprint the present branches of a normalized relation filter, in the
- * fixed order some→every→none→is→isNot. A `null` branch tokenizes as
- * `<branch>(null)`; a present branch recurses through
+ * fixed order some→every→none→is→isNot. A present branch recurses through
  * {@link fingerprintRelFilter} so the FULL inner shape is captured (two
- * different sub-wheres must never collide on one cached SQL text).
+ * different sub-wheres must never collide on one cached SQL text). `is: null`
+ * and `isNot: null` tokenize as `<branch>(null)`; the where walk refuses any
+ * other non-object value before this runs.
  */
 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, depth + 1)})`);
+        relParts.push(`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, depth + 1)})`);
+        relParts.push(`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, depth + 1)})`);
+        relParts.push(`none(${fingerprintRelFilter(qi, relDef.to, filterObj.none, depth + 1)})`);
     if (filterObj.is !== undefined)
         relParts.push(filterObj.is === null
             ? 'is(null)'
@@ -199,32 +234,43 @@ function fingerprintRelFilter(qi, targetTable, subWhere, depth = 0) {
 /**
  * Walk a where clause and push ONLY values into `params`, in the EXACT same
  * order that `buildWhereClause` pushes them. Used on cache hit to fill params
- * without rebuilding SQL.
+ * without rebuilding SQL. Returns whether the clause compiles to a condition,
+ * i.e. whether `buildWhereClause` returns non-null for it.
  *
  * @internal Exposed as package-private for testing.
  */
 function collectWhereParams(qi, where, params, depth = 0) {
     (0, where_compile_js_1.assertWhereDepth)(depth);
+    let emitted = false;
     // ONE canonical walk (shared with fingerprintWhere + buildWhereClause), so
     // the key order + combinator structure cannot drift out of lockstep.
     for (const event of (0, where_compile_js_1.walkWhere)(qi.whereHost, where)) {
         switch (event.kind) {
             case 'or':
+                collectOrParams(event.conditions, params, (cond) => collectWhereParams(qi, cond, params, depth + 1));
+                emitted = true;
+                break;
             case 'and':
-                for (const cond of event.conditions)
-                    collectWhereParams(qi, cond, params, depth + 1);
+                for (const cond of event.conditions) {
+                    if (collectWhereParams(qi, cond, params, depth + 1))
+                        emitted = true;
+                }
                 break;
             case 'not':
-                collectWhereParams(qi, event.condition, params, depth + 1);
+                if (collectWhereParams(qi, event.condition, params, depth + 1))
+                    emitted = true;
                 break;
             case 'relation':
-                collectRelationFilterParams(qi, event.relDef, event.filterObj, params, depth + 1);
+                if (collectRelationFilterParams(qi, event.relDef, event.filterObj, params, depth + 1))
+                    emitted = true;
                 break;
             case 'scalar':
                 collectScalarParams(qi, event.key, event.value, params);
+                emitted = true;
                 break;
         }
     }
+    return emitted;
 }
 /**
  * Push a scalar WHERE value's params, mirroring {@link buildScalarClause}'s
@@ -252,7 +298,7 @@ function collectScalarParams(qi, key, value, params) {
             collectJsonFilterParams(qi, value, params, qi.q(rawColumn));
             return;
         case 'array':
-            collectArrayFilterParams(qi, value, params);
+            collectArrayFilterParams(qi, value, params, qi.q(rawColumn));
             return;
         case 'textsearch':
             // Same gate the build path applies, so the collect path never diverges
@@ -266,15 +312,22 @@ function collectScalarParams(qi, key, value, params) {
                 table: qi.table,
                 prefix: '',
                 rawColumn,
+                pgType: getColumnPgType(qi, rawColumn),
             });
             return;
-        default:
+        default: {
             // 'equality' | 'jsonThrow' | 'arrayThrow': same strict validation as
             // the build path, so a cache hit can never silently bind a
             // misspelled-operator object.
-            assertBindableEqualityValue(qi, rawColumn, value, getColumnPgType(qi, rawColumn), qi.table);
+            const pgType = getColumnPgType(qi, rawColumn);
+            assertBindableEqualityValue(qi, rawColumn, value, pgType, qi.table);
+            if (isBareJsonDocument(qi, pgType, value)) {
+                jsonDocumentEquals(qi, '', rawColumn, value, collectOnly(params));
+                return;
+            }
             params.push(coerceWhereOperand(qi, qi.tableMeta, rawColumn, value));
             return;
+        }
     }
 }
 /**
@@ -286,52 +339,69 @@ function collectScalarParams(qi, key, value, params) {
  * the gf calls are no-ops, so this stays byte-identical to the pre-0.28 path.
  * Shared by every collect site that mirrors buildRelationFilter
  * (collectWhereParams, collectRelFilterParams, collectAliasWhereParams).
+ * Returns whether {@link buildRelationFilter} emits a clause for it.
  */
 function collectRelationFilterParams(qi, relDef, filterObj, params, depth = 0) {
     const target = relDef.to;
-    if (filterObj.some !== undefined && filterObj.some !== null) {
+    if (!qi.schema.tables[target])
+        return false;
+    let emitted = false;
+    if (filterObj.some !== undefined) {
         collectRelFilterParams(qi, target, filterObj.some, params, depth + 1);
         collectTargetGlobalFilterExists(qi, target, params);
+        emitted = true;
     }
-    if (filterObj.none !== undefined && filterObj.none !== null) {
+    if (filterObj.none !== undefined) {
         collectRelFilterParams(qi, target, filterObj.none, params, depth + 1);
         collectTargetGlobalFilterExists(qi, target, params);
+        emitted = true;
     }
-    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, qi.q(target), filterObj.every, [], depth + 1) !==
-            null) {
-            collectRelFilterParams(qi, target, filterObj.every, params, depth + 1);
-            collectTargetGlobalFilterExists(qi, target, params);
-        }
+    // gf is only emitted (build) when the `every` sub-where compiles to a
+    // filter, otherwise `every` is trivially true and no subquery is built. A
+    // sub-where that compiles to nothing pushes nothing.
+    if (filterObj.every !== undefined &&
+        collectRelFilterParams(qi, target, filterObj.every, params, depth + 1)) {
+        collectTargetGlobalFilterExists(qi, target, params);
+        emitted = true;
     }
     if (filterObj.is !== undefined) {
         if (filterObj.is !== null)
             collectRelFilterParams(qi, target, filterObj.is, params, depth + 1);
         collectTargetGlobalFilterExists(qi, target, params);
+        emitted = true;
     }
     if (filterObj.isNot !== undefined) {
         if (filterObj.isNot !== null)
             collectRelFilterParams(qi, target, filterObj.isNot, params, depth + 1);
         collectTargetGlobalFilterExists(qi, target, params);
+        emitted = true;
     }
+    return emitted;
 }
+/** Collect a relation sub-where's params; returns whether it compiles to a condition. */
 function collectRelFilterParams(qi, targetTable, subWhere, params, depth = 0) {
     const meta = qi.schema.tables[targetTable];
     if (!meta)
-        return;
+        return false;
     // The FROM-item reference only shapes SQL text, never params, so the bare
     // name serves the collect mirror whether or not the build path aliased it.
-    collectScopedWhereParams(qi, relationWhereScope(qi, targetTable, meta, qi.q(targetTable)), subWhere, params, depth);
+    return collectScopedWhereParams(qi, relationWhereScope(qi, targetTable, meta, qi.q(targetTable)), subWhere, params, depth);
 }
 /**
  * Collect params from operator clauses. Mirrors buildOperatorClauses:
  * {@link ColumnRef} values compile into the SQL text, so they push NOTHING -
  * but they re-run the same validation (unknown ref / insensitive mode) so a
- * warmed cache can never skip a check the build path enforces.
+ * warmed cache can never skip a check the build path enforces. The operand
+ * validation ({@link assertOperatorOperands}) runs here too, for the same
+ * reason.
  */
 function collectOperatorParams(qi, column, op, params, refCtx) {
+    const operand = operandContext(qi, column, refCtx);
+    (0, filters_js_1.assertOperatorOperands)(op, operand);
+    collectOperatorParamsChecked(qi, column, op, params, refCtx, operand);
+}
+/** {@link collectOperatorParams} after validation; recursive for a `not` operator object. */
+function collectOperatorParamsChecked(qi, column, op, params, refCtx, operand) {
     const skipRef = (v) => {
         if (!(0, filters_js_1.isColumnRef)(v))
             return false;
@@ -343,7 +413,6 @@ function collectOperatorParams(qi, column, op, params, refCtx) {
     const cv = (v) => (refCtx ? coerceWhereOperand(qi, refCtx.meta, refCtx.rawColumn, v) : v);
     const insensitive = op.mode === 'insensitive';
     if (op.equals !== undefined && op.equals !== null && !skipRef(op.equals)) {
-        (0, filters_js_1.assertBindableEqualsOperand)(op.equals, `"${column}"`);
         if (insensitive)
             assertInsensitiveOperand(op.equals, 'equals', column);
         params.push(cv(op.equals));
@@ -357,9 +426,18 @@ function collectOperatorParams(qi, column, op, params, refCtx) {
     if (op.lte !== undefined && !skipRef(op.lte))
         params.push(cv(op.lte));
     if (op.not !== undefined && op.not !== null && !skipRef(op.not)) {
-        if (insensitive)
-            assertInsensitiveOperand(op.not, 'not', column);
-        params.push(cv(op.not));
+        const negatedDocument = jsonNegatedDocument(qi, op.not, operand);
+        if (negatedDocument !== NO_JSON_NEGATION) {
+            jsonDocumentEquals(qi, '', column, negatedDocument, collectOnly(params));
+        }
+        else if (isNegatedOperatorObject(op.not, operand)) {
+            collectOperatorParamsChecked(qi, column, notOperand(op), params, refCtx, operand);
+        }
+        else {
+            if (insensitive)
+                assertInsensitiveOperand(op.not, 'not', column);
+            params.push(cv(op.not));
+        }
     }
     if (op.in !== undefined) {
         if (insensitive) {
@@ -382,6 +460,14 @@ function collectOperatorParams(qi, column, op, params, refCtx) {
     if (op.endsWith !== undefined)
         params.push(`%${likeOperand(qi, op.endsWith)}`);
 }
+/**
+ * Is this `not` operand an operator object to negate as a whole, rather than a
+ * value? On a JSON column an object is a JSON VALUE (`not: { a: 1 }` compares
+ * documents), so only non-JSON columns read it as an operator object.
+ */
+function isNegatedOperatorObject(value, operand) {
+    return operand.kind !== 'json' && (0, filters_js_1.isWhereOperator)(value);
+}
 /**
  * Collect params from JSON filter. Mirrors buildJsonFilterClauses exactly:
  * the `path` is bound at most once (its placeholder is shared by every
@@ -389,7 +475,7 @@ function collectOperatorParams(qi, column, op, params, refCtx) {
  * comparison values in {@link JSON_RANGE_OPERATORS} order.
  */
 function collectJsonFilterParams(qi, filter, params, column) {
-    assertJsonFilterKeys(filter, column);
+    (0, filters_js_1.assertJsonFilterKeys)(filter, column);
     let pathPushed = false;
     const pushPathOnce = () => {
         if (!pathPushed) {
@@ -400,14 +486,18 @@ function collectJsonFilterParams(qi, filter, params, column) {
     };
     if (filter.path !== undefined && filter.equals !== undefined) {
         pushPathOnce();
-        params.push(String(filter.equals));
+        const hook = jsonPathEqualsHook(qi);
+        if (hook) {
+            hook.call(qi.dialect, jsonPathEqualsInput(qi, filter, column, '', '', collectOnly(params)));
+        }
+        else {
+            params.push(jsonPathEqualsOperand(qi, filter.equals, column));
+        }
     }
     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));
+        // Mirrors the build path, refusals included: a warmed template must never
+        // serve a shape the cold build refuses.
+        jsonDocumentEquals(qi, '', column, filter.equals, collectOnly(params));
     }
     if (filter.contains !== undefined) {
         requireJsonContains(qi, 'contains');
@@ -426,8 +516,9 @@ function collectJsonFilterParams(qi, filter, params, column) {
     }
 }
 /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
-function collectArrayFilterParams(qi, filter, params) {
+function collectArrayFilterParams(qi, filter, params, column) {
     requireArrayColumns(qi);
+    (0, filters_js_1.assertArrayFilter)(filter, column);
     if (filter.has !== undefined)
         params.push(filter.has);
     if (filter.hasEvery !== undefined)
@@ -461,34 +552,57 @@ function buildWhere(qi, where) {
  * THE global-filter resolution rule, with no dependency on a `BuilderCtx`.
  *
  * Split out from {@link resolveGlobalFilter} so `PowqlInterface` can consume
- * the SAME rule rather than a transcription of it. It is a parallel
- * implementation of the public surface, and this repository's history is
- * unambiguous that a rule written twice is how two engines come to disagree
- * (the 0.64 projection resolver, the 0.73 findUnique guard). Every clause here
- * is load-bearing on both engines: a function filter is evaluated PER BUILD so
- * per-request tenancy works, an all-undefined filter is treated as absent so it
- * cannot emit a dangling clause, and `skip` is honoured in both its whole-query
- * and per-table forms.
- */
-function resolveGlobalFilterFrom(filters, table, skip) {
-    if (!filters)
-        return null;
+ * the SAME rule rather than a transcription of it: a rule written twice is how
+ * two engines come to disagree. A function filter is evaluated PER BUILD so
+ * per-request tenancy works, and `skip` is honoured in both its whole-query and
+ * per-table forms.
+ *
+ * FAIL CLOSED. A filter that resolves to `undefined`, or to an object holding
+ * an `undefined` anywhere inside it, throws {@link ValidationError} (E003). A
+ * missing tenant context is exactly what produces `{ tenantId: undefined }`,
+ * and treating that as "no filter" read and wrote every tenant's rows. The
+ * explicit values `null` and `{}` still mean "no filter for this call": neither
+ * is what a missing value produces.
+ *
+ * A `skipGlobalFilters` list names tables by table name or client accessor,
+ * the two spellings `globalFilters` keys take. With `tables` (the schema's
+ * table map), an entry that names no table is refused (E003): it would skip
+ * nothing, so the caller who meant to lift a filter would silently keep it.
+ */
+function resolveGlobalFilterFrom(filters, table, skip, tables) {
     if (skip === true)
         return null;
-    if (Array.isArray(skip) && skip.includes(table))
+    if (Array.isArray(skip)) {
+        if (tables !== undefined)
+            (0, global_filters_config_js_1.assertSkipListNames)(skip, tables);
+        if ((0, global_filters_config_js_1.skipListNamesTable)(skip, table, tables))
+            return null;
+    }
+    if (!filters)
         return null;
-    const raw = filters[table];
-    if (raw === undefined)
+    if (!Object.hasOwn(filters, table))
         return null;
+    const raw = filters[table];
     const resolved = typeof raw === 'function' ? raw() : raw;
-    if (resolved === null || resolved === undefined)
-        return null;
-    const obj = resolved;
-    // An all-undefined filter (e.g. `{ tenantId: undefined }`) contributes
-    // nothing, treat it as absent so it never emits a dangling clause.
-    if (Object.keys(obj).every((k) => obj[k] === undefined))
+    if (resolved === null)
         return null;
-    return obj;
+    if (resolved === undefined)
+        throw unresolvedGlobalFilter(table, 'resolved to undefined');
+    if (typeof resolved !== 'object' || Array.isArray(resolved)) {
+        throw new errors_js_1.ValidationError(`Global filter for "${table}" must be a where object (or a function returning one), received ` +
+            `${Array.isArray(resolved) ? 'an array' : typeof resolved}.`);
+    }
+    // The boolean scan allocates nothing; the path string is built only on the throw path.
+    const hole = (0, filters_js_1.holdsUndefinedValue)(resolved, 0) ? (0, filters_js_1.findUndefinedPath)(resolved, '', 0) : null;
+    if (hole !== null)
+        throw unresolvedGlobalFilter(table, `has an undefined value at "${hole}"`);
+    return Object.keys(resolved).length === 0 ? null : resolved;
+}
+function unresolvedGlobalFilter(table, what) {
+    return new errors_js_1.ValidationError(`Global filter for "${table}" ${what}. A global filter is never dropped because its input is missing: ` +
+        "an undefined tenant id would otherwise read and write every tenant's rows. Supply the value it reads " +
+        '(for example the current tenant) before this query runs, or pass `skipGlobalFilters: UNSAFE` ' +
+        "(import { UNSAFE } from 'turbine-orm') on a query that must see every row.");
 }
 /**
  * Resolve the configured global filter for `table`, evaluating a function
@@ -496,7 +610,7 @@ function resolveGlobalFilterFrom(filters, table, skip) {
  * no filter applies, the query opted out, or the filter is empty.
  */
 function resolveGlobalFilter(qi, table, skip = qi.currentSkip) {
-    return resolveGlobalFilterFrom(qi.globalFilters, table, skip);
+    return resolveGlobalFilterFrom(qi.globalFilters, table, skip, qi.schema.tables);
 }
 /**
  * AND-merge this table's resolved global filter into a user `where`. Either
@@ -514,6 +628,45 @@ function mergeGlobalFilter(qi, userWhere) {
     // {@link markInternalCombinator}.
     return (0, utils_js_1.markInternalCombinator)({ AND: [userWhere, gf] });
 }
+/**
+ * The tables whose global filter is being compiled right now, per builder
+ * context. A table's filter applies to every relation target a query reaches,
+ * the targets inside another table's filter included, so two filters that
+ * reach each other through relations (or one that reaches its own table) would
+ * apply each other without end. While a table's filter is being compiled, a
+ * relation that reaches that table again reads its rows unfiltered, which ends
+ * the chain. A static filter that forms such a cycle is refused when the client
+ * is built (`normalizeGlobalFilters`); this covers function filters, whose
+ * relations are known only per query. Compilation is synchronous, so the stack
+ * is pushed and popped around each application, on the build and the collect
+ * pass alike.
+ */
+const filtersBeingApplied = new WeakMap();
+/**
+ * Apply `table`'s global filter as a relation target: `apply(gf)` with the
+ * table on the stack, or `none` when no filter applies or the table's filter
+ * is already being compiled further out (see {@link filtersBeingApplied}).
+ * Every target application goes through here, build and collect alike.
+ */
+function withTargetGlobalFilter(qi, table, none, apply) {
+    let stack = filtersBeingApplied.get(qi);
+    if (stack?.includes(table))
+        return none;
+    const gf = resolveGlobalFilter(qi, table);
+    if (!gf)
+        return none;
+    if (!stack) {
+        stack = [];
+        filtersBeingApplied.set(qi, stack);
+    }
+    stack.push(table);
+    try {
+        return apply(gf);
+    }
+    finally {
+        stack.pop();
+    }
+}
 /**
  * SQL clause for `targetTable`'s global filter rendered against `alias`
  * (relation subqueries, `_count`, relation `orderBy`). Pushes its params to
@@ -521,23 +674,17 @@ function mergeGlobalFilter(qi, userWhere) {
  * {@link collectTargetGlobalFilterAlias}.
  */
 function targetGlobalFilterAlias(qi, targetTable, alias, params) {
-    const gf = resolveGlobalFilter(qi, targetTable);
-    if (!gf)
-        return '';
     const meta = qi.schema.tables[targetTable];
     if (!meta)
         return '';
-    return buildAliasWhere(qi, targetTable, meta, alias, gf, params) ?? '';
+    return withTargetGlobalFilter(qi, targetTable, '', (gf) => buildAliasWhere(qi, targetTable, meta, alias, gf, params) ?? '');
 }
 /** Param-collect mirror of {@link targetGlobalFilterAlias}. */
 function collectTargetGlobalFilterAlias(qi, targetTable, params) {
-    const gf = resolveGlobalFilter(qi, targetTable);
-    if (!gf)
-        return;
     const meta = qi.schema.tables[targetTable];
     if (!meta)
         return;
-    collectAliasWhereParams(qi, targetTable, meta, gf, params);
+    withTargetGlobalFilter(qi, targetTable, false, (gf) => collectAliasWhereParams(qi, targetTable, meta, gf, params));
 }
 /**
  * SQL clause for `targetTable`'s global filter rendered against `targetRef`,
@@ -546,17 +693,11 @@ function collectTargetGlobalFilterAlias(qi, targetTable, params) {
  * params; `''` when none. Mirror: {@link collectTargetGlobalFilterExists}.
  */
 function targetGlobalFilterExists(qi, targetTable, targetRef, params) {
-    const gf = resolveGlobalFilter(qi, targetTable);
-    if (!gf)
-        return '';
-    return buildSubWhereForRelation(qi, targetTable, targetRef, gf, params) ?? '';
+    return withTargetGlobalFilter(qi, targetTable, '', (gf) => buildSubWhereForRelation(qi, targetTable, targetRef, gf, params) ?? '');
 }
 /** Param-collect mirror of {@link targetGlobalFilterExists}. */
 function collectTargetGlobalFilterExists(qi, targetTable, params) {
-    const gf = resolveGlobalFilter(qi, targetTable);
-    if (!gf)
-        return;
-    collectRelFilterParams(qi, targetTable, gf, params);
+    withTargetGlobalFilter(qi, targetTable, false, (gf) => collectRelFilterParams(qi, targetTable, gf, params));
 }
 /**
  * Value-invariant SQL-cache-key segment for the active global-filter
@@ -601,16 +742,41 @@ function globalFilterCacheSegment(qi) {
     return parts.length ? `|gf=${parts.join(';')}` : '';
 }
 /**
- * True when the USER-supplied `where` compiles to no predicate (`{}`,
- * `{ id: undefined }`, `{ OR: [{ a: undefined }] }`, …). This is the exact
- * signal the empty-`where` guard needs, the compiled emptiness, NOT the
- * fingerprint (which is non-empty for an all-undefined `OR`/`AND`). It ignores
- * any configured global filter, so a global filter never lets an unguarded
- * mass mutation through.
+ * True when the USER-supplied `where` narrows no row: it compiles to no
+ * predicate (`{}`, `{ id: undefined }`, `{ OR: [{ a: undefined }] }`, …), or
+ * to one that is TRUE for every row (`{ NOT: { OR: [] } }`,
+ * `{ id: { notIn: [] } }`, and on a NOT NULL column `{ email: { contains: '' } }`
+ * or `{ id: { not: null } }`, see {@link foldWhere}). Either way a mutation
+ * guarded by it would write every row. It reads the compiled emptiness, NOT
+ * the fingerprint (which is non-empty for an all-undefined `OR`/`AND`), and it
+ * ignores any configured global filter, so a global filter never lets an
+ * unguarded mass mutation through.
  */
 function userPredicateIsEmpty(qi, userWhere) {
     const throwaway = [];
-    return buildWhereClause(qi, userWhere, throwaway) === null;
+    if (buildWhereClause(qi, userWhere, throwaway) === null)
+        return true;
+    return (0, where_compile_js_1.foldWhere)(qi.whereHost, userWhere, (table) => tableWhereHost(qi, table), 0, guardFoldOptions(qi)) === 'true';
+}
+/**
+ * The guard's fold reads NOT NULL columns, and trusts a declared foreign key
+ * except on SQLite, which enforces one only when the connection turned
+ * `foreign_keys` on, so a row there can point at a row that does not exist.
+ */
+function guardFoldOptions(qi) {
+    return {
+        notNull: {
+            foreignKeys: qi.dialect.capabilities.enforcesForeignKeys,
+            hasGlobalFilter: (table) => qi.globalFilters !== undefined && Object.hasOwn(qi.globalFilters, table),
+        },
+    };
+}
+/** The where host of `table` in this client's schema, or `undefined` when the schema has no such table. */
+function tableWhereHost(qi, table) {
+    const meta = (0, utils_js_1.ownLookup)(qi.schema.tables, table);
+    if (!meta)
+        return undefined;
+    return meta.name === qi.tableMeta.name ? qi.whereHost : scopedWhereHost(qi, meta);
 }
 function assertMutationHasPredicate(qi, operation, whereSql, 
 // Already RESOLVED by the caller (writes.ts) through `resolveUnsafeFlag`, so
@@ -622,9 +788,18 @@ allowFullTableScan) {
         return;
     if (allowFullTableScan === true)
         return;
-    throw new errors_js_1.ValidationError(`${operation} on "${qi.table}" refused: the \`where\` clause is empty. ` +
+    throw new errors_js_1.ValidationError(emptyMutationWhereMessage(operation, qi.table));
+}
+/**
+ * The mass-mutation refusal, one text for every engine. "Empty" covers a where
+ * that is always true (see {@link userPredicateIsEmpty}), which writes every
+ * row just the same.
+ */
+function emptyMutationWhereMessage(operation, table) {
+    return (`${operation} on "${table}" refused: the \`where\` clause is empty or always true ` +
+        '(for example `NOT: { OR: [] }` or `{ id: { notIn: [] } }`), so it would apply to every row. ' +
         "Pass `allowFullTableScan: UNSAFE` to opt in (import { UNSAFE } from 'turbine-orm'), " +
-        'or check that your filter values are defined.');
+        'or check that your filter values are defined and your lists are not empty.');
 }
 /**
  * Build the inner WHERE expression (without the WHERE keyword).
@@ -648,18 +823,12 @@ function buildWhereClause(qi, where, params, depth = 0) {
             case 'or': {
                 if (!internal)
                     qi.markVariableArity();
-                const orClauses = [];
-                for (const orCond of event.conditions) {
-                    const sub = buildWhereClause(qi, orCond, params, depth + 1);
-                    if (sub)
-                        orClauses.push(sub);
-                }
-                if (orClauses.length > 0)
-                    andClauses.push(`(${orClauses.join(' OR ')})`);
+                andClauses.push(buildOrClause(event.conditions, params, (cond) => buildWhereClause(qi, cond, params, depth + 1)));
                 break;
             }
             case 'and':
-                if (!internal)
+                // `AND: { ... }` is one branch whatever the caller sends (fixedArity).
+                if (!internal && !event.fixedArity)
                     qi.markVariableArity();
                 for (const andCond of event.conditions) {
                     const sub = buildWhereClause(qi, andCond, params, depth + 1);
@@ -689,6 +858,46 @@ function buildWhereClause(qi, where, params, depth = 0) {
         return null;
     return andClauses.join(' AND ');
 }
+/**
+ * The SQL an `OR` compiles to when one of its branches compiles to nothing.
+ * Written out rather than left empty, because `NOT` of an empty clause applies
+ * no condition while `NOT` of this matches no row.
+ */
+const ALWAYS_TRUE_SQL = '(1 = 1)';
+/**
+ * Compile an `OR` from its branches. A branch with no condition (`{}`,
+ * `{ AND: [] }`) is TRUE for every row, so the whole `OR` is TRUE: the clause
+ * is {@link ALWAYS_TRUE_SQL} and the params the other branches pushed are
+ * taken back. Every branch is still built, so each is validated exactly as the
+ * param collect validates it. {@link collectOrParams} is the mirror.
+ */
+function buildOrClause(branches, params, build) {
+    const mark = params.length;
+    const parts = [];
+    let alwaysTrue = false;
+    for (const branch of branches) {
+        const sub = build(branch);
+        if (sub === null)
+            alwaysTrue = true;
+        else
+            parts.push(sub);
+    }
+    if (!alwaysTrue)
+        return `(${parts.join(' OR ')})`;
+    params.length = mark;
+    return ALWAYS_TRUE_SQL;
+}
+/** Param-collect mirror of {@link buildOrClause}; `collect` reports whether the branch compiled to a condition. */
+function collectOrParams(branches, params, collect) {
+    const mark = params.length;
+    let alwaysTrue = false;
+    for (const branch of branches) {
+        if (!collect(branch))
+            alwaysTrue = true;
+    }
+    if (alwaysTrue)
+        params.length = mark;
+}
 /**
  * Emit the SQL clause(s) for one scalar WHERE key onto `andClauses`, pushing
  * any params. The shape decision comes from the shared
@@ -731,18 +940,52 @@ function buildScalarClause(qi, key, value, params, andClauses) {
                 table: qi.table,
                 prefix: '',
                 rawColumn,
+                pgType: getColumnPgType(qi, rawColumn),
             }));
             return;
-        default:
+        default: {
             // 'equality': a plain object literal that matched no known filter shape
             // is almost always a misspelled operator (`startWith` for `startsWith`);
             // the guard also runs on the cache-hit param-collect path.
-            assertBindableEqualityValue(qi, rawColumn, value, getColumnPgType(qi, rawColumn), qi.table);
+            const pgType = getColumnPgType(qi, rawColumn);
+            assertBindableEqualityValue(qi, rawColumn, value, pgType, qi.table);
+            if (isBareJsonDocument(qi, pgType, value)) {
+                andClauses.push(jsonDocumentEquals(qi, column, rawColumn, value, bindInto(qi, params)));
+                return;
+            }
             params.push(coerceWhereOperand(qi, qi.tableMeta, rawColumn, value));
             andClauses.push(`${column} = ${qi.p(params.length)}`);
             return;
+        }
     }
 }
+/**
+ * A bare object on a JSON column is a whole-document equality, the same thing
+ * `equals` is. PostgreSQL's `jsonb = $1` already reads it so. MySQL compared
+ * the column with the bound TEXT, which matched no row (and its `NOT` every
+ * row), so there it compiles to the typed comparison `equals` uses. SQLite and
+ * SQL Server compared the stored text, so key order and whitespace decided the
+ * match; they refuse it (E017) as they refuse `equals`, and a bare array with
+ * it. Decided from the dialect, the column and the value's shape, all of which
+ * the cache key already carries (a bare object fingerprints as `obj(...)`; a
+ * bare array only ever refuses, so it changes no SQL).
+ */
+function isBareJsonDocument(qi, pgType, value) {
+    if (qi.dialect.capabilities.jsonDocumentEquality === 'jsonb' || (0, filters_js_1.operandColumnKind)(pgType) !== 'json')
+        return false;
+    return (0, filters_js_1.isPlainRecord)(value) || (Array.isArray(value) && !comparesJsonDocuments(qi));
+}
+/** Whether the engine compares two whole JSON documents exactly (key order and whitespace aside). */
+function comparesJsonDocuments(qi) {
+    return qi.dialect.capabilities.jsonDocumentEquality !== 'text';
+}
+/** A bind callback for the build passes: pushes the value and returns its placeholder. */
+function bindInto(qi, params) {
+    return (value) => {
+        params.push(value);
+        return qi.p(params.length);
+    };
+}
 /**
  * A {@link WhereHost} with no relations, used to fingerprint a sub-where
  * whose target table is unknown (`schema.tables[t]` miss). `walkWhere` reads
@@ -802,8 +1045,8 @@ function relationWhereScope(qi, targetTable, meta, targetRef) {
  */
 function aliasWhereScope(qi, targetTable, meta, alias) {
     if (alias.includes('"')) {
-        throw new errors_js_1.ValidationError(`Internal: aliasWhereScope was given the rendered reference ${alias} for table "${targetTable}", ` +
-            'but it takes a bare alias and quotes it itself. Use renderedRefWhereScope for an already-quoted reference.');
+        throw new errors_js_1.InvariantError('where-scope-reference', `aliasWhereScope was given the rendered reference ${alias} for table "${targetTable}", but it takes a ` +
+            'bare alias and quotes it itself. Use renderedRefWhereScope for an already-quoted reference.');
     }
     return {
         meta,
@@ -859,17 +1102,24 @@ function buildScopedWhere(qi, scope, where, params, depth = 0) {
     for (const event of (0, where_compile_js_1.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();
+                clauses.push(buildOrClause(event.conditions, params, (cond) => {
+                    const sub = buildScopedWhere(qi, scope, cond, params, depth + 1);
+                    return sub === null ? null : `(${sub})`;
+                }));
+                break;
+            case 'and': {
+                if (!internal && !event.fixedArity)
+                    qi.markVariableArity();
                 const parts = event.conditions
                     .map((cond) => buildScopedWhere(qi, scope, cond, params, depth + 1))
                     .filter((s) => s !== null)
                     .map((s) => `(${s})`);
                 if (parts.length > 0)
-                    clauses.push(`(${parts.join(event.kind === 'or' ? ' OR ' : ' AND ')})`);
+                    clauses.push(`(${parts.join(' AND ')})`);
                 break;
             }
             case 'not': {
@@ -939,10 +1189,16 @@ function buildScopedScalarClause(qi, scope, field, value, params, clauses) {
             table: scope.table,
             prefix: scope.qualifier,
             rawColumn: col,
+            pgType: pgTypeForColumn(qi, meta, col),
         }));
         return;
     }
-    assertBindableEqualityValue(qi, col, value, pgTypeForColumn(qi, meta, col), scope.table);
+    const pgType = pgTypeForColumn(qi, meta, col);
+    assertBindableEqualityValue(qi, col, value, pgType, scope.table);
+    if (isBareJsonDocument(qi, pgType, value)) {
+        clauses.push(jsonDocumentEquals(qi, qCol, col, value, bindInto(qi, params)));
+        return;
+    }
     params.push(coerceWhereOperand(qi, meta, col, value));
     clauses.push(`${qCol} = ${qi.p(params.length)}`);
 }
@@ -950,30 +1206,41 @@ function buildScopedScalarClause(qi, scope, field, value, params, clauses) {
  * Cache-hit param-collect mirror of {@link buildScopedWhere}: pushes the exact
  * same params in the exact same order (driven by the same {@link walkWhere}),
  * without rebuilding SQL. Serves both {@link collectRelFilterParams} and
- * {@link collectAliasWhereParams}.
+ * {@link collectAliasWhereParams}. Returns whether the clause compiles to a
+ * condition (`buildScopedWhere` non-null).
  */
 function collectScopedWhereParams(qi, scope, where, params, depth = 0) {
     (0, where_compile_js_1.assertWhereDepth)(depth);
+    let emitted = false;
     for (const event of (0, where_compile_js_1.walkWhere)(scope.host, where)) {
         switch (event.kind) {
             case 'or':
+                collectOrParams(event.conditions, params, (cond) => collectScopedWhereParams(qi, scope, cond, params, depth + 1));
+                emitted = true;
+                break;
             case 'and':
-                for (const cond of event.conditions)
-                    collectScopedWhereParams(qi, scope, cond, params, depth + 1);
+                for (const cond of event.conditions) {
+                    if (collectScopedWhereParams(qi, scope, cond, params, depth + 1))
+                        emitted = true;
+                }
                 break;
             case 'not':
-                collectScopedWhereParams(qi, scope, event.condition, params, depth + 1);
+                if (collectScopedWhereParams(qi, scope, event.condition, params, depth + 1))
+                    emitted = true;
                 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, depth);
+                if (collectRelationFilterParams(qi, event.relDef, event.filterObj, params, depth))
+                    emitted = true;
                 break;
             case 'scalar':
                 collectScopedScalarParams(qi, scope, event.key, event.value, params);
+                emitted = true;
                 break;
         }
     }
+    return emitted;
 }
 /** Param-collect mirror of {@link buildScopedScalarClause}. */
 function collectScopedScalarParams(qi, scope, field, value, params) {
@@ -995,15 +1262,26 @@ function collectScopedScalarParams(qi, scope, field, value, params) {
     if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isArrayFilter)(value)) {
         const colType = pgTypeForColumn(qi, meta, col);
         if (colType.startsWith('_')) {
-            collectArrayFilterParams(qi, value, params);
+            collectArrayFilterParams(qi, value, params, `${qi.q(scope.table)}.${qi.q(col)}`);
             return;
         }
     }
     if ((0, filters_js_1.isWhereOperator)(value)) {
-        collectOperatorParams(qi, col, value, params, { meta, table: scope.table, prefix: '', rawColumn: col });
+        collectOperatorParams(qi, col, value, params, {
+            meta,
+            table: scope.table,
+            prefix: '',
+            rawColumn: col,
+            pgType: pgTypeForColumn(qi, meta, col),
+        });
+        return;
+    }
+    const pgType = pgTypeForColumn(qi, meta, col);
+    assertBindableEqualityValue(qi, col, value, pgType, scope.table);
+    if (isBareJsonDocument(qi, pgType, value)) {
+        jsonDocumentEquals(qi, '', col, value, collectOnly(params));
         return;
     }
-    assertBindableEqualityValue(qi, col, value, pgTypeForColumn(qi, meta, col), scope.table);
     params.push(coerceWhereOperand(qi, meta, col, value));
 }
 /**
@@ -1158,24 +1436,23 @@ depth = 0) {
         return gf ? ` AND ${gf}` : '';
     };
     // "some": EXISTS (SELECT 1 FROM target WHERE correlation AND filter AND gf)
-    // A `null` branch is skipped (never reaches buildSubWhereForRelation, which
-    // would throw on Object.keys(null)), matching collectRelationFilterParams,
-    // which also skips null. Unreachable via normalization today, guarded anyway.
-    if (filterObj.some !== undefined && filterObj.some !== null) {
+    // `some` / `none` / `every` hold a where object here: the where walk refuses
+    // any other value (relationFilterValueProblem), so none compiles to nothing.
+    if (filterObj.some !== undefined) {
         const subWhere = filterObj.some;
         const filterClause = buildSubWhereForRelation(qi, targetTable, qt, subWhere, params, depth + 1);
         const filterAnd = filterClause ? ` AND ${filterClause}` : '';
         clauses.push(`EXISTS (SELECT 1 FROM ${fromTarget} WHERE ${correlation}${filterAnd}${gfAnd()})`);
     }
     // "none": NOT EXISTS (SELECT 1 FROM target WHERE correlation AND filter AND gf)
-    if (filterObj.none !== undefined && filterObj.none !== null) {
+    if (filterObj.none !== undefined) {
         const subWhere = filterObj.none;
         const filterClause = buildSubWhereForRelation(qi, targetTable, qt, subWhere, params, depth + 1);
         const filterAnd = filterClause ? ` AND ${filterClause}` : '';
         clauses.push(`NOT EXISTS (SELECT 1 FROM ${fromTarget} 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) {
+    if (filterObj.every !== undefined) {
         const subWhere = filterObj.every;
         const filterClause = buildSubWhereForRelation(qi, targetTable, qt, subWhere, params, depth + 1);
         if (filterClause) {
@@ -1246,16 +1523,96 @@ function pgTypeForColumn(_qi, meta, column) {
  * SQL-template cache is unaffected, and it is applied on the cache-hit
  * param-collect path as well as the build path.
  *
+ * On MySQL a number, bigint or boolean compared with a text column binds as
+ * text ({@link textComparedOperand}), and so does each such element of a list.
+ *
  * `timestamptz` and every non-temporal column are returned by identity.
  */
 function coerceWhereOperand(qi, meta, column, value) {
-    if (!(value instanceof Date) && !Array.isArray(value))
+    if (value instanceof Date || Array.isArray(value)) {
+        const dbType = pgTypeForColumn(qi, meta, column);
+        const coerced = (0, utils_js_1.coerceTemporalValue)(dbType, value, utcDateTimeRewrite(qi, dbType));
+        return Array.isArray(coerced) ? textComparedList(qi, dbType, coerced) : coerced;
+    }
+    if (!qi.dialect.capabilities.numericTextComparison || typeof value === 'string' || typeof value === 'object') {
+        return value;
+    }
+    return textComparedOperand(qi, pgTypeForColumn(qi, meta, column), value);
+}
+/**
+ * Column types MySQL compares with a NUMBER numerically, converting each
+ * stored text to a number: `'0zz' = 0` and `'abc' = 0` are both true, and a
+ * boolean is the number 1 or 0 there. A request body that carries `0` or
+ * `false` where a token string belongs would match the first row whose token
+ * does not start with a digit. Exported so the write path's re-read keys use
+ * this one list rather than a copy.
+ */
+exports.TEXT_COMPARED_TYPES = new Set([
+    'char',
+    'varchar',
+    'character',
+    'character varying',
+    'bpchar',
+    'nchar',
+    'nvarchar',
+    'text',
+    'tinytext',
+    'mediumtext',
+    'longtext',
+    'binary',
+    'varbinary',
+    'tinyblob',
+    'blob',
+    'mediumblob',
+    'longblob',
+    'uuid',
+    'citext',
+]);
+/**
+ * A value bound against a column of `columnType`, as MySQL must receive it to
+ * compare it as the value it is: a number or bigint becomes its decimal text
+ * and a boolean `'1'` / `'0'` (what MySQL stores when a boolean is written to
+ * a text column), so the comparison is text with text. Every other engine,
+ * value and column type is returned unchanged. THE rule for every value Turbine
+ * binds against a column on MySQL: the where compiler applies it to each
+ * operand, and the writes apply it to the keys they re-read a row by.
+ */
+function textComparedOperand(qi, columnType, value) {
+    if (!qi.dialect.capabilities.numericTextComparison)
+        return value;
+    if (typeof value !== 'number' && typeof value !== 'bigint' && typeof value !== 'boolean')
         return value;
-    return (0, utils_js_1.coerceTemporalValue)(pgTypeForColumn(qi, meta, column), value, 
-    // Same PostgreSQL + `utcTimestamps` gate as the write path (see
-    // `utcDateTimeWrites` in writes.ts): only the read/write-symmetric engine
-    // gets the zone-less rewrite. Time-of-day always rewrites.
-    qi.dialect.name === 'postgresql' && qi.utcTimestamps !== false);
+    if (columnType === undefined || !exports.TEXT_COMPARED_TYPES.has(columnType.toLowerCase()))
+        return value;
+    return typeof value === 'boolean' ? (value ? '1' : '0') : String(value);
+}
+/** {@link textComparedOperand} for each element of an `in` / `notIn` list; the list itself when none changes. */
+function textComparedList(qi, columnType, list) {
+    if (!qi.dialect.capabilities.numericTextComparison)
+        return list;
+    let out;
+    for (let i = 0; i < list.length; i++) {
+        const next = textComparedOperand(qi, columnType, list[i]);
+        if (next === list[i])
+            continue;
+        out ??= list.slice();
+        out[i] = next;
+    }
+    return out ?? list;
+}
+/**
+ * Whether a `Date` bound against `dbType` gets the zone-less UTC rewrite (the
+ * write path's gate). A `date` column takes the UTC date part on every SQL
+ * engine: the write path stores `YYYY-MM-DD` there, and a full timestamp
+ * compared with that text matches nothing. A zone-less `timestamp` is
+ * rewritten on PostgreSQL only, because MySQL reads a zone-less literal in the
+ * session time zone. `utcTimestamps: false` turns both off. Time-of-day
+ * columns always rewrite.
+ */
+function utcDateTimeRewrite(qi, dbType) {
+    if (qi.utcTimestamps === false)
+        return false;
+    return qi.dialect.capabilities.utcTimestampRewrite || (0, schema_js_1.localDateTimeKind)(dbType) === 'date';
 }
 /**
  * The Postgres enum type name for a column, when the schema knows one.
@@ -1267,13 +1624,13 @@ function coerceWhereOperand(qi, meta, column, value) {
  * value as text and Postgres refuses the implicit text→enum coercion
  * ("column X is of type Y but expression is of type text").
  *
- * Postgres-only by construction: gated on the active dialect being
- * `postgresql` AND on `schema.enums` having entries (only PG introspection
- * produces them, `defineSchema` and the other engines leave it empty), so
- * SQLite/MySQL/MSSQL/PowDB output is byte-identical.
+ * Postgres-only by construction: gated on the engine having named enum types
+ * (`namedEnumTypes`) AND on `schema.enums` having entries (only PG
+ * introspection produces them, `defineSchema` and the other engines leave it
+ * empty), so SQLite/MySQL/MSSQL/PowDB output is byte-identical.
  */
 function enumTypeForColumn(qi, column) {
-    if (qi.dialect.name !== 'postgresql')
+    if (!qi.dialect.capabilities.namedEnumTypes)
         return null;
     const enums = qi.schema.enums;
     if (!enums)
@@ -1302,25 +1659,14 @@ function enumCastSuffix(qi, column) {
 }
 /**
  * Equality-fallthrough guard shared by every SQL-build path AND every
- * cache-hit param-collect path. A plain object literal that matched no known
- * filter shape on a non-JSON column is almost always a misspelled operator
- * (`startWith` for `startsWith`); binding it as `col = $1` silently returns
- * wrong rows. Class instances (Buffer for bytea, Decimal wrappers, ...) are
- * legitimate bind values and pass through, as do objects on json/jsonb
- * columns (object equality).
- */
-function assertBindableEqualityValue(qi, rawColumn, value, columnPgType, table) {
-    if (!(0, filters_js_1.isUnmatchedPlainObject)(value))
-        return;
-    if (isJsonColumnType(qi, columnPgType))
-        return;
-    const badKeys = Object.keys(value);
-    throw new errors_js_1.ValidationError(badKeys.length === 0
-        ? `Empty filter object on "${rawColumn}" for table "${table}". ` +
-            `Provide a value or an operator like { gt: 1 }.`
-        : `Unknown operator${badKeys.length > 1 ? 's' : ''} ` +
-            `${badKeys.map((k) => `"${k}"`).join(', ')} on "${rawColumn}" for table "${table}". ` +
-            `Supported operators: ${[...utils_js_1.OPERATOR_KEYS].join(', ')}.`);
+ * cache-hit param-collect path: a bare value must fit its column
+ * ({@link assertEqualityOperand}). A plain object literal that matched no
+ * known filter shape on a non-JSON column is almost always a misspelled
+ * operator (`startWith` for `startsWith`), and binding it as `col = $1` would
+ * silently return wrong rows. Objects on json/jsonb columns are JSON values.
+ */
+function assertBindableEqualityValue(_qi, rawColumn, value, columnPgType, table) {
+    (0, filters_js_1.assertEqualityOperand)(value, { column: rawColumn, table, kind: (0, filters_js_1.operandColumnKind)(columnPgType) });
 }
 /**
  * Build the user-supplied `where` filter of a relation `with` clause against
@@ -1339,7 +1685,7 @@ function buildAliasWhere(qi, targetTable, targetMeta, alias, where, params) {
 function collectAliasWhereParams(qi, targetTable, targetMeta, where, params) {
     // The alias identifier is irrelevant to param collection (it only shapes SQL
     // text), so reuse the relation scope's host binding for `targetMeta`.
-    collectScopedWhereParams(qi, aliasWhereScope(qi, targetTable, targetMeta, ''), where, params);
+    return collectScopedWhereParams(qi, aliasWhereScope(qi, targetTable, targetMeta, ''), where, params);
 }
 /**
  * Value-invariant, shape-aware fingerprint for a relation `with` clause's
@@ -1388,11 +1734,20 @@ function columnRefSql(qi, ref, ctx, mode) {
  * Each operator key becomes its own clause, all ANDed together.
  *
  * `equals`/`not`/`gt`/`gte`/`lt`/`lte` also accept a {@link ColumnRef}
- * (`{ col: 'otherField' }`) which compiles to a column-to-column comparison
+ * (`col('otherField')`) which compiles to a column-to-column comparison
  * against `refCtx`: no param bound, so `collectOperatorParams` mirrors by
  * pushing nothing and the referenced name lives in the fingerprint.
+ *
+ * `not` also accepts an operator object, compiled as `NOT (<inner clauses>)`
+ * (see {@link WhereOperator.not}).
  */
 function buildOperatorClauses(qi, column, op, params, refCtx) {
+    const operand = operandContext(qi, column, refCtx);
+    (0, filters_js_1.assertOperatorOperands)(op, operand);
+    return buildOperatorClausesChecked(qi, column, op, params, refCtx, operand);
+}
+/** {@link buildOperatorClauses} after validation; recursive for a `not` operator object. */
+function buildOperatorClausesChecked(qi, column, op, params, refCtx, operand) {
     const clauses = [];
     // Temporal bind rewrite, identical to `collectOperatorParams`. Value-only, so
     // the emitted SQL (and therefore the template cache) is untouched.
@@ -1406,7 +1761,6 @@ function buildOperatorClauses(qi, column, op, params, refCtx) {
             clauses.push(`${column} = ${columnRefSql(qi, op.equals, refCtx, op.mode)}`);
         }
         else {
-            (0, filters_js_1.assertBindableEqualsOperand)(op.equals, column);
             if (insensitive)
                 assertInsensitiveOperand(op.equals, 'equals', column);
             params.push(cv(op.equals));
@@ -1450,12 +1804,25 @@ function buildOperatorClauses(qi, column, op, params, refCtx) {
         }
     }
     if (op.not !== undefined) {
+        const negatedDocument = op.not === null || (0, filters_js_1.isColumnRef)(op.not) ? NO_JSON_NEGATION : jsonNegatedDocument(qi, op.not, operand);
         if (op.not === null) {
             clauses.push(`${column} IS NOT NULL`);
         }
         else if ((0, filters_js_1.isColumnRef)(op.not)) {
             clauses.push(`${column} != ${columnRefSql(qi, op.not, refCtx, op.mode)}`);
         }
+        else if (negatedDocument !== NO_JSON_NEGATION) {
+            const equality = jsonDocumentEquals(qi, column, column, negatedDocument, (v) => {
+                params.push(v);
+                return qi.p(params.length);
+            });
+            clauses.push(`NOT (${equality})`);
+        }
+        else if (isNegatedOperatorObject(op.not, operand)) {
+            const inner = buildOperatorClausesChecked(qi, column, notOperand(op), params, refCtx, operand);
+            if (inner.length > 0)
+                clauses.push(`NOT (${inner.join(' AND ')})`);
+        }
         else {
             if (insensitive)
                 assertInsensitiveOperand(op.not, 'not', column);
@@ -1512,9 +1879,8 @@ function requireFullTextSearch(qi) {
         '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}.
+ * Gate the pathless JSON filters, `contains` (containment) and `equals`
+ * (whole-document equality), 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
@@ -1533,11 +1899,12 @@ function requireFullTextSearch(qi) {
 function requireJsonContains(qi, clause) {
     if (qi.dialect.supportsJsonContains)
         return;
-    throw new errors_js_1.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. ` +
+    const what = clause === 'equals' ? 'way to compare two whole JSON documents' : "JSON containment (PostgreSQL's `@>`)";
+    throw new errors_js_1.UnsupportedFeatureError(clause === 'equals'
+        ? 'JSON document equality (`equals` without `path`)'
+        : 'JSON containment (`contains` without `path`)', qi.dialect.name, `This engine has no ${what}, so the filter is refused rather than emulated. ` +
         '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.');
+        'extraction (`json_extract`). To compare or match whole documents, run the query on PostgreSQL or MySQL.');
 }
 /**
  * Gate the array filter operators (`has` / `hasEvery` / `hasSome` / `isEmpty`)
@@ -1611,15 +1978,7 @@ function pushVectorParam(qi, field, _rawColumn, to, params) {
  * ambiguous and was never valid in Prisma either).
  */
 function normalizeRelationFilter(_qi, relDef, filterObj) {
-    if ((relDef.type === 'belongsTo' || relDef.type === 'hasOne') &&
-        !('some' in filterObj) &&
-        !('every' in filterObj) &&
-        !('none' in filterObj) &&
-        !('is' in filterObj) &&
-        !('isNot' in filterObj)) {
-        return { is: filterObj };
-    }
-    return filterObj;
+    return (0, where_compile_js_1.normalizeToOneRelationFilter)(relDef, filterObj);
 }
 /**
  * Case-insensitive json/jsonb column-type check. Postgres reports lowercase
@@ -1667,7 +2026,11 @@ function getArrayElementType(_qi, pgType) {
  */
 /**
  * One LIKE comparison, honoring `mode: 'insensitive'` through the dialect and
- * always carrying the `ESCAPE '\'` clause that pairs with {@link escapeLike}.
+ * always carrying the `ESCAPE` clause that pairs with {@link likeOperand}: the
+ * dialect's `likeEscapeCharacter`, else `\` (the character {@link escapeLike}
+ * escapes with). MySQL names `!`, because `'\'` is a syntax error there unless
+ * the session runs with `NO_BACKSLASH_ESCAPES`, which a caller-supplied pool
+ * need not.
  *
  * Shared by the scalar `contains` / `startsWith` / `endsWith` operators and by
  * the JSON substring operators, so the two can never drift into escaping their
@@ -1675,7 +2038,7 @@ function getArrayElementType(_qi, pgType) {
  */
 function buildLikeClause(qi, column, paramRef, insensitive) {
     const base = insensitive ? qi.dialect.buildInsensitiveLike(column, paramRef) : `${column} LIKE ${paramRef}`;
-    return `${base} ESCAPE '\\'`;
+    return `${base} ESCAPE '${qi.dialect.likeEscapeCharacter ?? '\\'}'`;
 }
 /**
  * One equality-family comparison (`=` / `!=`) honoring `mode: 'insensitive'`.
@@ -1725,11 +2088,12 @@ function insensitiveInClause(qi, column, paramRef, negated, operator) {
  * on that engine.
  *
  * Folding the elements in SQL instead is not reachable from here for the other
- * dialects: each unpacks a bound IN list in a subquery of its OWN shape
- * (`json_each` / `JSON_TABLE` / `OPENJSON`) whose projection is written by the
- * dialect, not by this module, and the length-independence the SQL-template
- * cache depends on rules out the other portable form, one placeholder per
- * element. Restoring the operator on those engines means a dialect hook that
+ * dialects: each unpacks a bound IN list in its OWN way (`json_each` on SQLite,
+ * `OPENJSON` on SQL Server, one placeholder per element expanded by the MySQL
+ * pool shim after the statement leaves the builder), that shape is the
+ * dialect's and not this module's, and the length-independence the
+ * SQL-template cache depends on rules out emitting one placeholder per element
+ * here. Restoring the operator on those engines means a dialect hook that
  * projects the folded element, one correct implementation per engine. Until
  * then a typed refusal is the honest outcome. `equals`, `not` and the LIKE
  * operators are unaffected: they fold a single operand the engine can reach.
@@ -1738,7 +2102,7 @@ function insensitiveInClause(qi, column, paramRef, negated, operator) {
  * every other gate in this module.
  */
 function requireInsensitiveList(qi, column, operator) {
-    if (qi.dialect.name === 'postgresql')
+    if (qi.dialect.capabilities.insensitiveInList)
         return;
     throw new errors_js_1.UnsupportedFeatureError(`mode: 'insensitive' on \`${operator}\` (${column})`, qi.dialect.name, "Case-folding a bound list needs the engine to lower every element in SQL, which this dialect's " +
         'IN-list form cannot express. Lowering them in JavaScript instead would fold the list and the ' +
@@ -1762,54 +2126,6 @@ function assertInsensitiveOperand(value, operator, column) {
         `(received ${Array.isArray(value) ? 'a list with a non-string element' : typeof value}). ` +
         `Case folding applies to text; drop the mode or compare a string.`);
 }
-/**
- * Refuse a {@link JsonFilter} carrying a key that is not a JSON operator, and
- * refuse a filter that selects a `path` but never compares it.
- *
- * Both shapes used to compile to NOTHING. `buildJsonFilterClauses` only ever
- * emitted a clause for a key it recognized, so `{ path: ['title'],
- * string_contains: 'x' }`, the Prisma spelling, and an easy typo besides -
- * produced an empty clause list, the predicate vanished, and the query
- * returned EVERY row. Inside an `AND` it silently dropped that conjunct, so a
- * tenant scope written this way widened to the whole table. The equivalent
- * typo on a scalar column has always thrown; this closes the inconsistency.
- *
- * Called from both the SQL-build path and the cache-hit param-collect path, so
- * a warmed SQL cache cannot skip the check.
- */
-function assertJsonFilterKeys(filter, column) {
-    const obj = filter;
-    const present = Object.keys(obj).filter((k) => obj[k] !== undefined);
-    for (const key of present) {
-        if (filters_js_1.JSON_FILTER_KEYS.has(key))
-            continue;
-        const suggestion = JSON_PRISMA_SPELLINGS[key];
-        throw new errors_js_1.ValidationError(`Unknown JSON filter operator "${key}" on ${column}.` +
-            (suggestion ? ` Did you mean \`${suggestion}\`?` : '') +
-            ` Supported operators: ${[...filters_js_1.JSON_FILTER_KEYS].sort().join(', ')}.`);
-    }
-    // `mode` and `path` are modifiers, not comparisons: a filter made only of
-    // those compares nothing, which is exactly the silent no-op shape above.
-    if (present.length > 0 && present.every((k) => k === 'path' || k === 'mode')) {
-        throw new errors_js_1.ValidationError(`JSON filter on ${column} selects a \`path\` but has no comparison. ` +
-            `Add one of: ${[...filters_js_1.JSON_FILTER_KEYS]
-                .filter((k) => k !== 'path' && k !== 'mode')
-                .sort()
-                .join(', ')}.`);
-    }
-}
-/**
- * The Prisma spelling of each JSON operator, so a migrator who writes the
- * name they already know gets told the turbine one instead of a bare list.
- */
-const JSON_PRISMA_SPELLINGS = {
-    string_contains: 'stringContains',
-    string_starts_with: 'stringStartsWith',
-    string_ends_with: 'stringEndsWith',
-    array_contains: 'contains',
-    startsWith: 'stringStartsWith',
-    endsWith: 'stringEndsWith',
-};
 /**
  * Validate and enumerate the substring comparisons on a JSON filter, in the
  * fixed {@link JSON_STRING_OPERATORS} order. Shared by the build and collect
@@ -1856,6 +2172,136 @@ function jsonRangeEntries(_qi, filter, column) {
     }
     return entries;
 }
+/**
+ * The `{ path, equals }` operand after the checks every engine shares: a
+ * function, symbol or column reference is refused, a non-finite number is
+ * refused (JSON.stringify would turn it into `null`, which matches JSON null),
+ * and a Date becomes the ISO string JSON stores it as.
+ */
+function jsonPathEqualsValue(value, column) {
+    if (typeof value === 'function' || typeof value === 'symbol' || (0, filters_js_1.isColumnRef)(value)) {
+        throw new errors_js_1.ValidationError(`JSON path 'equals' on ${column} takes a JSON value (string, number, boolean, null, array or object), ` +
+            `received ${(0, filters_js_1.isColumnRef)(value) ? 'a column reference' : `a ${typeof value}`}.`);
+    }
+    const scalar = value instanceof Date ? value.toISOString() : value;
+    if (typeof scalar === 'number' && !Number.isFinite(scalar)) {
+        throw new errors_js_1.ValidationError(`JSON path 'equals' on ${column} takes a finite number: JSON has no form for ${scalar}.`);
+    }
+    return scalar;
+}
+/** The engine's typed `{ path, equals }` hook; the jsonb form lives here, so an engine using it never takes one. */
+function jsonPathEqualsHook(qi) {
+    return qi.dialect.capabilities.jsonDocumentEquality === 'jsonb' ? undefined : qi.dialect.buildJsonPathEquals;
+}
+/** The hook input, identical on the build and collect passes but for `column`, `pathRef` and `bind`. */
+function jsonPathEqualsInput(qi, filter, label, column, pathRef, bind) {
+    return {
+        column,
+        pathRef,
+        path: filter.path,
+        value: jsonPathEqualsValue(filter.equals, label),
+        label,
+        bind,
+        encodePath: (path) => jsonPathParam(qi, path),
+    };
+}
+/**
+ * A whole-document JSON `equals` (no `path`): the column equals the operand as
+ * a JSON value, on the build and collect passes alike (`bind` pushes; on the
+ * collect pass the returned SQL is discarded). PostgreSQL compares jsonb, which
+ * ignores object key order and whitespace; the cast makes a `json` column
+ * comparable too (it has no `=` operator). MySQL compares through its typed
+ * hook; an engine without one refuses (E017) through
+ * {@link requireJsonContains}.
+ */
+function jsonDocumentEquals(qi, column, label, value, bind) {
+    const v = jsonPathEqualsValue(value, label);
+    if (qi.dialect.capabilities.jsonDocumentEquality === 'jsonb') {
+        return `${column}::jsonb = ${bind(typeof v === 'bigint' ? v.toString() : JSON.stringify(v))}::jsonb`;
+    }
+    const hook = qi.dialect.buildJsonPathEquals;
+    if (hook) {
+        return hook.call(qi.dialect, {
+            column,
+            pathRef: undefined,
+            path: [],
+            value: v,
+            label,
+            bind,
+            encodePath: (path) => jsonPathParam(qi, path),
+        });
+    }
+    requireJsonContains(qi, 'equals');
+    throw new errors_js_1.UnsupportedFeatureError(`JSON \`equals\` on the whole document (${label})`, qi.dialect.name, 'This engine has no exact comparison of JSON documents. Compare a value with `{ path: [...], equals }`.');
+}
+/** A bind callback for the collect passes: pushes the value, emits no SQL. */
+function collectOnly(params) {
+    return (value) => {
+        params.push(value);
+        return '';
+    };
+}
+/**
+ * The operand of a `not` on a JSON column that negates a whole-document
+ * equality, or `NO_JSON_NEGATION` when the `not` keeps its bound-value form.
+ * `not: { equals: X }` is the negation of `equals: X` everywhere it compiles
+ * (an engine without an exact comparison refuses it rather than comparing a
+ * document `{"equals": X}`). A plain `not: X` means the same thing on the
+ * engines that compare whole documents exactly (PostgreSQL, MySQL). On SQLite
+ * and SQL Server a document (object or array) is refused the same way, since
+ * comparing it as text lets key order decide; a scalar keeps comparing as the
+ * bound value, as before.
+ */
+function jsonNegatedDocument(qi, not, operand) {
+    if (operand.kind !== 'json' || not === null || not === undefined || (0, filters_js_1.isColumnRef)(not))
+        return NO_JSON_NEGATION;
+    if ((0, filters_js_1.isWhereOperator)(not)) {
+        const keys = Object.keys(not).filter((k) => not[k] !== undefined);
+        if (keys.length === 1 && keys[0] === 'equals')
+            return not.equals;
+    }
+    if (comparesJsonDocuments(qi))
+        return not;
+    return (0, filters_js_1.isPlainRecord)(not) || Array.isArray(not) ? not : NO_JSON_NEGATION;
+}
+const NO_JSON_NEGATION = Symbol('no JSON negation');
+/**
+ * The bound operand of `{ path, equals }`, shared by the build and collect
+ * paths so both bind (and refuse) identically.
+ *
+ * PostgreSQL compares JSON to JSON, so the operand is its JSON text: `5`,
+ * `"5"`, `null`, `[1,2]` and `{"a":1}` each match only that JSON value at the
+ * path (numbers compare numerically, so `5` also matches `5.0`). A Date is the
+ * ISO string JSON would store, and a bigint is a JSON number.
+ *
+ * MySQL and SQL Server compare typed through `Dialect.buildJsonPathEquals`
+ * and never reach this function. SQLite compares the value its path
+ * extraction returns, so only a value with a text form can match: a string,
+ * number, boolean, bigint or Date.
+ * There a number and a numeric string match the same rows, except on SQLite,
+ * whose extraction returns typed values: a number binds as a number there, and
+ * a boolean is refused because SQLite reads `true` and `1` alike. `null`,
+ * objects and arrays matched no row on those engines and are refused (E017).
+ */
+function jsonPathEqualsOperand(qi, value, column) {
+    const scalar = jsonPathEqualsValue(value, column);
+    if (qi.dialect.capabilities.jsonDocumentEquality === 'jsonb') {
+        return typeof scalar === 'bigint' ? scalar.toString() : JSON.stringify(scalar);
+    }
+    if (scalar === null || typeof scalar === 'object') {
+        throw new errors_js_1.UnsupportedFeatureError(`JSON path \`equals\` with ${scalar === null ? 'null' : Array.isArray(scalar) ? 'an array' : 'an object'} (${column})`, qi.dialect.name, 'This engine compares the text extracted at the path, which has no form for null, arrays or objects, so ' +
+            'the comparison would match no row. Compare a scalar at a deeper path, or run the query on PostgreSQL.');
+    }
+    if (qi.dialect.capabilities.jsonExtractTyped) {
+        if (typeof scalar === 'number')
+            return scalar;
+        if (typeof scalar === 'boolean') {
+            throw new errors_js_1.UnsupportedFeatureError(`JSON path \`equals\` with a boolean (${column})`, qi.dialect.name, 'SQLite extracts JSON true and false as the integers 1 and 0, so a boolean comparison would also match ' +
+                'those numbers. Compare with 1 / 0 if the documents hold only booleans there.');
+        }
+    }
+    return String(scalar);
+}
 /**
  * Build SQL clauses for JSONB filter operators on a column.
  * Supports: path, equals, contains, hasKey, gt, gte, lt, lte.
@@ -1865,33 +2311,49 @@ function jsonRangeEntries(_qi, filter, column) {
  * stays byte-identical to {@link collectJsonFilterParams}.
  */
 function buildJsonFilterClauses(qi, column, filter, params) {
-    assertJsonFilterKeys(filter, column);
+    (0, filters_js_1.assertJsonFilterKeys)(filter, column);
     const clauses = [];
     // Lazily bind the path once; reuse the same $N in every extraction clause.
     let pathParamIdx = null;
-    const pathExtract = () => {
+    const pathRef = () => {
         if (pathParamIdx === null) {
             // Only reached when a path-requiring clause validated filter.path.
             params.push(jsonPathParam(qi, filter.path, filter.path));
             pathParamIdx = params.length;
         }
-        return qi.dialect.buildJsonPathExtract(column, qi.p(pathParamIdx));
+        return qi.p(pathParamIdx);
     };
+    const pathExtract = () => qi.dialect.buildJsonPathExtract(column, pathRef());
     if (filter.path !== undefined && filter.equals !== undefined) {
-        // Path access + equals: column #>> $N::text[] = $M
-        const extract = pathExtract();
-        params.push(String(filter.equals));
-        clauses.push(`${extract} = ${qi.p(params.length)}`);
+        // Path access + equals. PostgreSQL compares the JSON VALUE at the path,
+        // typed: `(column #> $N::text[])::jsonb = $M::jsonb`, so 5 and "5" differ,
+        // and null, arrays and objects compare as JSON. MySQL and SQL Server bring
+        // their own typed form (Dialect.buildJsonPathEquals); SQLite compares the
+        // extracted value (see jsonPathEqualsOperand).
+        const ref = pathRef();
+        const hook = jsonPathEqualsHook(qi);
+        if (hook) {
+            // The engine's typed comparison (MySQL, SQL Server).
+            clauses.push(hook.call(qi.dialect, jsonPathEqualsInput(qi, filter, column, column, ref, (v) => {
+                params.push(v);
+                return qi.p(params.length);
+            })));
+        }
+        else {
+            const value = jsonPathEqualsOperand(qi, filter.equals, column);
+            params.push(value);
+            clauses.push(qi.dialect.capabilities.jsonDocumentEquality === 'jsonb'
+                ? `(${column} #> ${ref}::text[])::jsonb = ${qi.p(params.length)}::jsonb`
+                : `${qi.dialect.buildJsonPathExtract(column, ref)} = ${qi.p(params.length)}`);
+        }
     }
     else if (filter.equals !== undefined) {
-        // 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)));
+        // Whole-document equality, NOT containment (`@>` matched every document
+        // holding the operand's keys).
+        clauses.push(jsonDocumentEquals(qi, column, column, filter.equals, (v) => {
+            params.push(v);
+            return qi.p(params.length);
+        }));
     }
     if (filter.contains !== undefined) {
         // Containment: column @> $N::jsonb
@@ -1932,12 +2394,19 @@ function buildJsonFilterClauses(qi, column, filter, params) {
  * params) and fail at runtime with the engine's bad-JSON-path error. The
  * encoded path stays a bound parameter, never spliced into SQL text, so
  * the build/collect param mirrors stay in lockstep and injection-safe.
+ *
+ * A key segment is written as a JSON string literal (`JSON.stringify`), the
+ * form the engines' JSONPath grammars read a quoted key in: a backslash, a
+ * quote and a control character are each escaped. Escaping only the quote
+ * read a key holding a backslash as an escape sequence, so the key `a\b` was
+ * looked up as a different key and matched nothing, a key ending in a
+ * backslash was a bad path, and MySQL refused a key holding a newline.
  */
 function jsonPathParam(qi, path, nativeForm) {
     if (qi.dialect.jsonPathSupport === 'native')
         return nativeForm ?? path.map(String);
     return `$${path
-        .map((seg) => typeof seg === 'number' || /^\d+$/.test(String(seg)) ? `[${seg}]` : `."${String(seg).replace(/"/g, '\\"')}"`)
+        .map((seg) => typeof seg === 'number' || /^\d+$/.test(String(seg)) ? `[${seg}]` : `.${JSON.stringify(String(seg))}`)
         .join('')}`;
 }
 /**
@@ -1948,7 +2417,7 @@ function jsonPathParam(qi, path, nativeForm) {
  * SQL Server have no `::` operator) as a float cast.
  */
 function castJsonNumeric(qi, extract) {
-    if (qi.dialect.name === 'postgresql')
+    if (qi.dialect.capabilities.jsonExactNumericCast)
         return `(${extract})::numeric`;
     return qi.dialect.castAggregate ? qi.dialect.castAggregate(`(${extract})`, 'float') : `(${extract})::numeric`;
 }
@@ -1958,6 +2427,7 @@ function castJsonNumeric(qi, extract) {
  */
 function buildArrayFilterClauses(qi, column, filter, params, pgType) {
     requireArrayColumns(qi);
+    (0, filters_js_1.assertArrayFilter)(filter, column);
     const clauses = [];
     const elementType = getArrayElementType(qi, pgType);
     if (filter.has !== undefined) {