@classytic/repo-core 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,80 @@ All notable changes to `@classytic/repo-core` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.0] - 2026-07-16
+
+### Added — canonical `matchesRecordFilter` (the `DataAdapter.matchesFilter` home)
+
+- **`matchesRecordFilter(item, record)`** + **`policyRecordToFilter(record)`**
+  (`@classytic/repo-core/filter`) — THE single, shared implementation of the
+  `DataAdapter.matchesFilter` seam. Evaluates arc's Mongo-record `_policyFilters`
+  (`{ ownerId }`, `{ organizationId }`, `{ $or: [{ ownerId }, { _id: { $in } }] }`)
+  against an already-fetched document IN PROCESS, by converting to the portable
+  `Filter` IR and delegating to `matchFilter` — the SAME IR kits compile to
+  SQL/Mongo, so in-memory and DB enforcement agree by construction. Every kit's
+  adapter now delegates here; **no per-kit matcher, one contract, one IR.**
+  Operator scope: `$or`/`$and`/`$nor`/`$not`, `$eq`/`$ne`/`$gt`/`$gte`/`$lt`/`$lte`,
+  `$in`/`$nin`, `$exists`, implicit-eq; fails LOUD on anything else. (Distinct from
+  `recordToFilter`, the bare-operator query normalizer that does not accept
+  `$`-prefixed or logical operators.)
+- **`matchFilter` is now fully array + id + date aware** (additive superset;
+  primitive/Date-vs-Date behavior unchanged — strict cases still short-circuit):
+  - **id coercion** — an id-like object with a meaningful `toString` (Mongo
+    `ObjectId`, `Buffer`, `Decimal128`) matches its string form, so one shared
+    matcher serves Mongo (`ObjectId` `_id`) and SQL (primitive ids) alike.
+  - **array semantics** — dot-paths fan out over subdocument arrays
+    (`items.sku` on `[{sku},{sku}]`), and a scalar condition on a leaf array
+    field matches when ANY element satisfies it (`{ tags: 'x' }`,
+    `{ scores: { $gt: 5 } }`, regex on array elements). All array unwrapping is
+    concentrated in one helper; the comparators stay pure scalar.
+  - **Date⇄ISO-string range** — `compare` coerces the string side to a date
+    instant when the other side is a genuine `Date` (mirrors `equals`), and
+    never claims ordering across a number/string type boundary (fails closed
+    instead of matching spuriously).
+  - **prototype-pollution-safe reads** — path resolution uses `Object.hasOwn`,
+    so a crafted `{ '__proto__.x': … }` / `{ constructor.name: … }` filter can
+    never traverse the prototype chain.
+- **Ability parity across kits**: mongokit's earlier standalone matcher
+  (subdocument-array fan-out, array-contains, `$regex`, ObjectId coercion) is now
+  fully covered by the shared engine — nothing was lost in consolidation.
+- **MongoDB-parity hardening** (validated against the MongoDB manual + sift.js +
+  mingo — the two industry-standard in-memory matchers). The authorization-critical
+  rule "an absent field participates in comparisons as null/undefined" is now
+  fully honored:
+  - `{ field: null }`, `$ne`, `$nin`, and a `null` MEMBER of `$in`/`$nin` all
+    match a MISSING field (a policy filter `{ status: { $ne: 'archived' } }`
+    correctly returns docs that lack the field, exactly as MongoDB does — the top
+    silent-authorization-divergence trap). `$ne: null` remains the exception
+    (requires present + non-null).
+  - `$in` accepts RegExp-literal members (`{ name: { $in: [/^a/] } }`).
+  - Comparison ops are type-bracketed (no cross-type ordering; `$gt: null` matches
+    nothing); NaN equals NaN for `$eq` (via `Object.is`, not `===`).
+  - Numeric dot-path segments resolve as positional array indices (`items.0.sku`).
+  - Documented DELIBERATE divergences: `$exists` = present-and-non-null (matches
+    the IR `exists` op + SQL `IS NOT NULL` + sift; Mongo/mingo count present-null
+    as existing); `Date`⇄ISO-string range leniency; array-literal operands are
+    element-matched not exact-matched.
+- New: 41-case matcher suite incl. the 11 researched MongoDB gotchas + adversarial
+  (prototype pollution, NaN/Infinity, boolean/zero/empty-string, empty
+  `$in`/`$or`/`$and`/`$nor`, fail-loud on unsupported operators) + a 100k-doc
+  performance smoke (linear, cached regex).
+- **Security hardening** (from a review against sift.js/mingo CVEs + the OWASP
+  NoSQL-injection / ReDoS / prototype-pollution literature):
+  - **Prototype-key denylist** on path segments — `__proto__` / `constructor` /
+    `prototype` resolve to nothing (fail-closed), string-normalized (the
+    object-path CVE-2021-23434 lesson: an array-typed segment bypassed a `===`
+    check). Closes the "match an inherited member → wrong auth answer" case and
+    the `JSON.parse('{"__proto__":…}')` own-property vector, on top of the
+    already-`Object.hasOwn` reads.
+  - **`$regex` input-length cap** (64 KiB) — ReDoS is `pattern × input`; a field
+    value longer than the cap is treated as no-match (fail-closed) so one slow
+    match can't stall the event loop and amplify across a realtime fan-out
+    (matcher runs once per subscriber per record). Pattern-side ReDoS is a
+    non-issue for framework-supplied (trusted) patterns.
+  - Reaffirmed **fail-closed** posture: comparisons never coerce across a
+    number/string type boundary (return no-match rather than JS-coerced nonsense
+    — the classic over-visibility leak), and unsupported operators throw.
+
 ## [0.13.0] - 2026-07-15
 
 ### Added — `StandardRepo.applyTransition?()` contract (state-machine CAS with history)

package/dist/filter/index.d.mts

@@ -3,6 +3,7 @@ import { FALSE, TRUE, and, anyOf as in_, between, contains, endsWith, eq, exists
 import { recordToFilter } from "./from-record.mjs";
 import { isFilter } from "./guard.mjs";
 import { asPredicate, matchFilter } from "./match.mjs";
+import { matchesRecordFilter, policyRecordToFilter } from "./match-record.mjs";
 import { SCOPE_ANY, buildTenantScope, mergeScope } from "./scope.mjs";
 import { collectFields, mapFilter, walkFilter } from "./walk.mjs";
-export { FALSE, type Filter, type FilterAnd, type FilterEq, type FilterExists, type FilterFalse, type FilterGt, type FilterGte, type FilterIn, type FilterLike, type FilterLt, type FilterLte, type FilterNe, type FilterNin, type FilterNot, type FilterOp, type FilterOr, type FilterRaw, type FilterRegex, type FilterTrue, SCOPE_ANY, TRUE, and, in_ as anyOf, asPredicate, between, buildTenantScope, collectFields, contains, endsWith, eq, exists, gt, gte, iEq, in_, not as invert, isFilter, isNotNull, isNull, like, lt, lte, mapFilter, matchFilter, mergeScope, ne, nin, nin as noneOf, not, or, raw, recordToFilter, regex, startsWith, walkFilter };
+export { FALSE, type Filter, type FilterAnd, type FilterEq, type FilterExists, type FilterFalse, type FilterGt, type FilterGte, type FilterIn, type FilterLike, type FilterLt, type FilterLte, type FilterNe, type FilterNin, type FilterNot, type FilterOp, type FilterOr, type FilterRaw, type FilterRegex, type FilterTrue, SCOPE_ANY, TRUE, and, in_ as anyOf, asPredicate, between, buildTenantScope, collectFields, contains, endsWith, eq, exists, gt, gte, iEq, in_, not as invert, isFilter, isNotNull, isNull, like, lt, lte, mapFilter, matchFilter, matchesRecordFilter, mergeScope, ne, nin, nin as noneOf, not, or, policyRecordToFilter, raw, recordToFilter, regex, startsWith, walkFilter };

package/dist/filter/index.mjs

@@ -3,5 +3,6 @@ import { collectFields, mapFilter, walkFilter } from "./walk.mjs";
 import { FALSE, TRUE, and, anyOf as in_, between, contains, endsWith, eq, exists, gt, gte, iEq, invert as not, isNotNull, isNull, like, lt, lte, ne, nin, or, raw, regex, startsWith } from "./builders.mjs";
 import { recordToFilter } from "./from-record.mjs";
 import { asPredicate, matchFilter } from "./match.mjs";
+import { matchesRecordFilter, policyRecordToFilter } from "./match-record.mjs";
 import { SCOPE_ANY, buildTenantScope, mergeScope } from "./scope.mjs";
-export { FALSE, SCOPE_ANY, TRUE, and, in_ as anyOf, asPredicate, between, buildTenantScope, collectFields, contains, endsWith, eq, exists, gt, gte, iEq, in_, not as invert, isFilter, isNotNull, isNull, like, lt, lte, mapFilter, matchFilter, mergeScope, ne, nin, nin as noneOf, not, or, raw, recordToFilter, regex, startsWith, walkFilter };
+export { FALSE, SCOPE_ANY, TRUE, and, in_ as anyOf, asPredicate, between, buildTenantScope, collectFields, contains, endsWith, eq, exists, gt, gte, iEq, in_, not as invert, isFilter, isNotNull, isNull, like, lt, lte, mapFilter, matchFilter, matchesRecordFilter, mergeScope, ne, nin, nin as noneOf, not, or, policyRecordToFilter, raw, recordToFilter, regex, startsWith, walkFilter };

package/dist/filter/match-record.d.mts

@@ -0,0 +1,19 @@
+import { Filter } from "./types.mjs";
+//#region src/filter/match-record.d.ts
+/**
+ * Convert an arc Mongo-record `_policyFilters` object into Filter IR.
+ * `{}` → `TRUE`. Throws on unsupported top-level operators.
+ */
+declare function policyRecordToFilter(record: Record<string, unknown>): Filter;
+/**
+ * Evaluate an arc Mongo-record `_policyFilters` object against a document —
+ * converts to Filter IR, then delegates to the shared {@link matchFilter}
+ * engine. THE canonical `DataAdapter.matchesFilter` implementation; every
+ * kit's adapter delegates here.
+ *
+ * @param item    The already-fetched document / row.
+ * @param filters Arc's `_policyFilters` in Mongo record syntax.
+ */
+declare function matchesRecordFilter(item: unknown, filters: Record<string, unknown>): boolean;
+//#endregion
+export { matchesRecordFilter, policyRecordToFilter };

package/dist/filter/match-record.mjs

@@ -0,0 +1,187 @@
+import { FALSE, TRUE, and, anyOf as in_, eq, gt, gte, invert as not, isNotNull, isNull, lt, lte, ne, or, regex } from "./builders.mjs";
+import { matchFilter } from "./match.mjs";
+//#region src/filter/match-record.ts
+/**
+* Mongo-record `_policyFilters` → Filter IR conversion + in-memory match.
+*
+* The CANONICAL, single home for evaluating arc's row-level policy filters
+* against an already-fetched document IN PROCESS (no DB round-trip). Every
+* kit's `DataAdapter.matchesFilter` delegates here — one contract, one IR,
+* no per-kit matcher.
+*
+* Arc's permission helpers emit policy filters in Mongo record syntax,
+* kit-agnostic (`requireOwnership` → `{ ownerId }`, multiTenant →
+* `{ organizationId }`, `requireGrant` list resolutions →
+* `{ $or: [{ ownerId }, { _id: { $in } }] }`). This module converts that
+* record into the portable {@link Filter} IR and evaluates it with the
+* shared {@link matchFilter} engine — the SAME IR kits compile to SQL /
+* Mongo, so in-memory and DB-level enforcement agree by construction.
+*
+* `matchFilter` is id-coercion aware (Mongo `ObjectId` `_id` matches its
+* string form — no kit-specific coercion) and array-aware (dot-paths fan
+* out over subdocument arrays; scalar conditions on array fields match any
+* element). See `match.ts`.
+*
+* SCOPE — the operators arc's policy filters emit. Fails LOUD on anything
+* else so a silent mismatch never masquerades as a denial:
+*
+*   logical:    $or, $and, $nor, $not
+*   comparison: implicit-eq, $eq, $ne, $gt, $gte, $lt, $lte
+*   membership: $in, $nin
+*   existence:  $exists (see divergence note below)
+*   pattern:    $regex (+ $options; RegExp literal accepted)
+*
+* MongoDB parity (validated against the MongoDB manual + sift/mingo):
+*   - Missing field ≡ null for `{field: null}`, `$ne`/`$nin`, and a `null`
+*     member of `$in`/`$nin` — the authorization-critical rule (a policy
+*     filter `{ status: { $ne: 'archived' } }` MUST return docs lacking the
+*     field, exactly as MongoDB does).
+*   - `$in` accepts RegExp-literal members (Mongo allows `/re/` in `$in`).
+*   - Comparison ops are TYPE-BRACKETED: no cross-type ordering
+*     (`{ n: { $gt: 5 } }` never matches a string `n`); `$gt: null` matches
+*     nothing. NaN equals NaN for `$eq`.
+*   - Dot-paths fan out over arrays AND resolve numeric segments as
+*     positional indices (`items.0.sku`).
+*
+* DELIBERATE divergences (documented, not bugs):
+*   - `$exists` = present-AND-non-null (a null value reads as absent),
+*     matching the shared IR `exists` op + SQL `IS NOT NULL` + sift.js.
+*     MongoDB/mingo treat present-null as existing; that would require a
+*     separate key-presence IR op threaded through every kit's SQL/Mongo
+*     compiler. Arc's built-in policy helpers never emit `$exists`; a
+*     custom filter that needs Mongo key-presence should use
+*     `{ field: { $ne: null } }` (present + non-null) or `{ field: null }`
+*     (null OR missing) instead.
+*   - `$gt`/`$lt` allow ONE cross-type leniency: a `Date` field compares
+*     against an ISO-string operand (JSON policy filters carry dates as
+*     strings). Consistent with `$eq`'s Date⇄string coercion.
+*   - An array-literal operand (`{ tags: ['a','b'] }`) is element-matched,
+*     not exact-array-matched — policy filters never assert whole-array
+*     equality.
+*
+* Distinct from {@link recordToFilter}, which is the ergonomic
+* record→IR normalizer for BARE-operator query shorthand (`{ price:
+* { gte } }`) and deliberately does NOT accept `$`-prefixed operators or
+* logical `$or`/`$and`. This function is the arc-policy-filter dialect
+* (`$`-prefixed, with logical operators).
+*/
+/** Field operators understood inside a `{ field: { ... } }` condition. */
+const FIELD_OPS = [
+	"$eq",
+	"$ne",
+	"$gt",
+	"$gte",
+	"$lt",
+	"$lte",
+	"$in",
+	"$nin",
+	"$exists",
+	"$regex"
+];
+function isOperatorObject(value) {
+	if (value === null || typeof value !== "object") return false;
+	if (Array.isArray(value) || value instanceof Date) return false;
+	const keys = Object.keys(value);
+	return keys.length > 0 && keys.every((k) => k.startsWith("$"));
+}
+/**
+* `$in` with MongoDB parity: a `null` member also matches a MISSING field
+* (inherits `{field: null}` semantics), and RegExp-literal members match by
+* pattern (Mongo allows `/re/` inside `$in`). Split members into
+* null / regex / scalar and OR the branches.
+*/
+function buildIn(field, members) {
+	const branches = [];
+	const scalars = [];
+	let hasNull = false;
+	for (const m of members) if (m === null || m === void 0) hasNull = true;
+	else if (m instanceof RegExp) branches.push(regex(field, m.source, m.flags));
+	else scalars.push(m);
+	if (hasNull) branches.push(isNull(field));
+	if (scalars.length > 0) branches.push(in_(field, scalars));
+	if (branches.length === 0) return FALSE;
+	return branches.length === 1 ? branches[0] : or(...branches);
+}
+/** `$nin` is the negation of `$in` — none of the members may match. */
+function buildNin(field, members) {
+	const inFilter = buildIn(field, members);
+	return inFilter.op === "false" ? TRUE : not(inFilter);
+}
+/** Convert a single `{ field: condition }` entry into a Filter IR node. */
+function fieldFilter(field, condition) {
+	if (!isOperatorObject(condition)) return condition === null ? isNull(field) : eq(field, condition);
+	const parts = [];
+	const options = typeof condition["$options"] === "string" ? condition["$options"] : void 0;
+	for (const [op, operand] of Object.entries(condition)) switch (op) {
+		case "$options": break;
+		case "$eq":
+			parts.push(operand === null ? isNull(field) : eq(field, operand));
+			break;
+		case "$ne":
+			parts.push(operand === null ? isNotNull(field) : ne(field, operand));
+			break;
+		case "$gt":
+			parts.push(gt(field, operand));
+			break;
+		case "$gte":
+			parts.push(gte(field, operand));
+			break;
+		case "$lt":
+			parts.push(lt(field, operand));
+			break;
+		case "$lte":
+			parts.push(lte(field, operand));
+			break;
+		case "$in":
+			parts.push(buildIn(field, operand ?? []));
+			break;
+		case "$nin":
+			parts.push(buildNin(field, operand ?? []));
+			break;
+		case "$exists":
+			parts.push(operand ? isNotNull(field) : isNull(field));
+			break;
+		case "$regex": {
+			const pattern = operand instanceof RegExp ? operand.source : String(operand);
+			const flags = operand instanceof RegExp ? operand.flags : options;
+			parts.push(flags ? regex(field, pattern, flags) : regex(field, pattern));
+			break;
+		}
+		default: throw new Error(`[repo-core] matchesRecordFilter: unsupported field operator '${op}'. Supported: ${FIELD_OPS.join(", ")}.`);
+	}
+	return parts.length === 1 ? parts[0] : and(...parts);
+}
+/**
+* Convert an arc Mongo-record `_policyFilters` object into Filter IR.
+* `{}` → `TRUE`. Throws on unsupported top-level operators.
+*/
+function policyRecordToFilter(record) {
+	const parts = [];
+	for (const [key, value] of Object.entries(record)) if (key === "$or") parts.push(or(...asFilterArray(value)));
+	else if (key === "$and") parts.push(and(...asFilterArray(value)));
+	else if (key === "$nor") parts.push(not(or(...asFilterArray(value))));
+	else if (key === "$not") parts.push(not(policyRecordToFilter(value)));
+	else if (key.startsWith("$")) throw new Error(`[repo-core] matchesRecordFilter: unsupported top-level operator '${key}'. Supported: $and, $or, $nor, $not.`);
+	else parts.push(fieldFilter(key, value));
+	if (parts.length === 0) return TRUE;
+	return parts.length === 1 ? parts[0] : and(...parts);
+}
+function asFilterArray(value) {
+	if (!Array.isArray(value)) throw new Error("[repo-core] matchesRecordFilter: $or/$and/$nor operand must be an array");
+	return value.map((entry) => policyRecordToFilter(entry));
+}
+/**
+* Evaluate an arc Mongo-record `_policyFilters` object against a document —
+* converts to Filter IR, then delegates to the shared {@link matchFilter}
+* engine. THE canonical `DataAdapter.matchesFilter` implementation; every
+* kit's adapter delegates here.
+*
+* @param item    The already-fetched document / row.
+* @param filters Arc's `_policyFilters` in Mongo record syntax.
+*/
+function matchesRecordFilter(item, filters) {
+	if (item === null || typeof item !== "object") return false;
+	return matchFilter(item, policyRecordToFilter(filters));
+}
+//#endregion
+export { matchesRecordFilter, policyRecordToFilter };

package/dist/filter/match.mjs

@@ -7,35 +7,26 @@ function matchFilter(doc, filter) {
 		case "and": return filter.children.every((child) => matchFilter(doc, child));
 		case "or": return filter.children.some((child) => matchFilter(doc, child));
 		case "not": return !matchFilter(doc, filter.child);
-		case "eq": return equals(getField(doc, filter.field), filter.value);
-		case "ne": return !equals(getField(doc, filter.field), filter.value);
-		case "gt": return compare(getField(doc, filter.field), filter.value) > 0;
-		case "gte": return compare(getField(doc, filter.field), filter.value) >= 0;
-		case "lt": return compare(getField(doc, filter.field), filter.value) < 0;
-		case "lte": return compare(getField(doc, filter.field), filter.value) <= 0;
-		case "in": {
-			const v = getField(doc, filter.field);
-			return filter.values.some((candidate) => equals(v, candidate));
-		}
-		case "nin": {
-			const v = getField(doc, filter.field);
-			return !filter.values.some((candidate) => equals(v, candidate));
-		}
+		case "eq": return someValue(resolve(doc, filter.field), (v) => equals(v, filter.value));
+		case "ne": return !someValue(resolve(doc, filter.field), (v) => equals(v, filter.value));
+		case "gt": return someValue(resolve(doc, filter.field), (v) => compare(v, filter.value) > 0);
+		case "gte": return someValue(resolve(doc, filter.field), (v) => compare(v, filter.value) >= 0);
+		case "lt": return someValue(resolve(doc, filter.field), (v) => compare(v, filter.value) < 0);
+		case "lte": return someValue(resolve(doc, filter.field), (v) => compare(v, filter.value) <= 0);
+		case "in": return someValue(resolve(doc, filter.field), (v) => filter.values.some((candidate) => equals(v, candidate)));
+		case "nin": return !someValue(resolve(doc, filter.field), (v) => filter.values.some((candidate) => equals(v, candidate)));
 		case "exists": {
-			const v = getField(doc, filter.field);
-			const present = v !== void 0 && v !== null;
+			const present = fieldPresent(doc, filter.field);
 			return filter.exists ? present : !present;
 		}
 		case "like": {
-			const v = getField(doc, filter.field);
-			if (typeof v !== "string") return false;
 			const flags = filter.caseSensitivity === "sensitive" ? "" : "i";
-			return getOrCompileLike(filter.pattern, flags).test(v);
+			const re = getOrCompileLike(filter.pattern, flags);
+			return someValue(resolve(doc, filter.field), (v) => regexTest(re, v));
 		}
 		case "regex": {
-			const v = getField(doc, filter.field);
-			if (typeof v !== "string") return false;
-			return getOrCompileRegex(filter.pattern, filter.flags).test(v);
+			const re = getOrCompileRegex(filter.pattern, filter.flags);
+			return someValue(resolve(doc, filter.field), (v) => regexTest(re, v));
 		}
 		case "raw": return false;
 	}
@@ -47,27 +38,92 @@ function matchFilter(doc, filter) {
 function asPredicate(filter) {
 	return (doc) => matchFilter(doc, filter);
 }
-function getField(doc, path) {
-	if (!doc || typeof doc !== "object") return void 0;
-	const segments = path.split(".");
-	let cursor = doc;
-	for (const segment of segments) {
-		if (cursor === null || cursor === void 0) return void 0;
-		if (typeof cursor !== "object") return void 0;
-		cursor = cursor[segment];
+/**
+* Resolve a dot-path to the SET of values it reaches, fanning out over
+* arrays on intermediate segments (Mongo/JSON-path array semantics):
+* `items.sku` on `{ items: [{ sku: 1 }, { sku: 2 }] }` → `[1, 2]`. A path
+* with no array yields a single-element list, so scalar leaf ops behave
+* exactly as before. A leaf array field (`tags`) is returned as one value
+* (the array) so `equals`'s array-contains handles it.
+*/
+/**
+* Path segments that must never be resolved — reading them can surface an
+* inherited member (or, for a JSON-parsed doc where `JSON.parse('{"__proto__":
+* …}')` created a real OWN `__proto__`, a crafted value) and produce a WRONG
+* authorization answer. Denied string-normalized (the object-path CVE-2021-23434
+* lesson: an array-typed segment bypassed a `===` check). Fail closed: any
+* path touching one of these resolves to no values → no match.
+*/
+const DANGEROUS_SEGMENTS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+function resolve(doc, path) {
+	let frontier = [doc];
+	for (const segment of path.split(".")) {
+		if (DANGEROUS_SEGMENTS.has(String(segment))) return [];
+		const next = [];
+		for (const node of frontier) {
+			if (node === null || node === void 0 || typeof node !== "object") continue;
+			if (Array.isArray(node)) {
+				const idx = Number(segment);
+				if (Number.isInteger(idx) && idx >= 0 && idx < node.length) next.push(node[idx]);
+				for (const el of node) if (el && typeof el === "object" && Object.hasOwn(el, segment)) next.push(el[segment]);
+			} else if (Object.hasOwn(node, segment)) next.push(node[segment]);
+		}
+		if (next.length === 0) return [];
+		frontier = next;
 	}
-	return cursor;
+	return frontier;
+}
+/** Is any value reachable at `path` present (defined + non-null)? */
+function fieldPresent(doc, path) {
+	return resolve(doc, path).some((v) => v !== void 0 && v !== null);
+}
+/**
+* Apply a scalar predicate to a resolved value SET, unwrapping leaf array
+* values so a scalar condition on an array field (`tags`, `scores`)
+* matches when ANY element satisfies it — Mongo + SQL array semantics,
+* concentrated in ONE place so `equals`/`compare`/regex stay pure scalar.
+*/
+function someValue(values, pred) {
+	for (const v of values) if (Array.isArray(v)) {
+		if (v.some(pred)) return true;
+	} else if (pred(v)) return true;
+	return false;
 }
 function equals(a, b) {
+	if (a === b) return true;
+	if (typeof a === "number" && typeof b === "number") return Number.isNaN(a) && Number.isNaN(b);
 	if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
 	if (a instanceof Date && typeof b === "string") return a.toISOString() === b;
 	if (b instanceof Date && typeof a === "string") return b.toISOString() === a;
-	return a === b;
+	const as = idString(a);
+	const bs = idString(b);
+	if (as !== void 0 && bs !== void 0) return as === bs;
+	return false;
+}
+/** String form of an id-like value for coercing comparison; else undefined. */
+function idString(value) {
+	if (typeof value === "string") return value;
+	if (value === null || value === void 0 || typeof value !== "object") return void 0;
+	if (Array.isArray(value)) return void 0;
+	const s = String(value);
+	return s === "[object Object]" ? void 0 : s;
 }
 function compare(a, b) {
+	if (a instanceof Date && typeof b === "string") {
+		const t = Date.parse(b);
+		if (!Number.isNaN(t)) b = new Date(t);
+	} else if (b instanceof Date && typeof a === "string") {
+		const t = Date.parse(a);
+		if (!Number.isNaN(t)) a = new Date(t);
+	}
 	const aNum = toComparable(a);
 	const bNum = toComparable(b);
 	if (aNum === void 0 || bNum === void 0) return NaN;
+	if (typeof aNum !== typeof bNum) return NaN;
 	if (aNum < bNum) return -1;
 	if (aNum > bNum) return 1;
 	return 0;
@@ -114,6 +170,21 @@ function getOrCompileRegex(pattern, flags) {
 	regexCache.set(key, re);
 	return re;
 }
+/**
+* Max string length fed to a regex `.test()`. ReDoS is `pattern × input`;
+* even a benign developer-written pattern can go quadratic on a pathological
+* INPUT string — and in a realtime fan-out the matcher runs once per
+* subscriber per record, so one slow match blocks the event loop and
+* amplifies across the whole subscriber set. A field value longer than this
+* is treated as NO MATCH (fail closed) rather than risking a stall; policy
+* filters never regex-test megabyte fields. (Trusted-source patterns make
+* pattern-side ReDoS a non-issue; this caps the input side.)
+*/
+const MAX_REGEX_INPUT = 64 * 1024;
+/** Guarded regex test: string-only, input-length-capped (see MAX_REGEX_INPUT). */
+function regexTest(re, v) {
+	return typeof v === "string" && v.length <= MAX_REGEX_INPUT && re.test(v);
+}
 /** SQL `LIKE` pattern → JS regex body. Escapes regex metachars; `%` → `.*`, `_` → `.`. */
 function likeToRegex(pattern) {
 	let out = "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
   "type": "module",
   "sideEffects": false,