@atscript/db 0.1.146 → 0.1.147

package/dist/index.mjs

@@ -1,14 +1,14 @@
 import { a as bucketTimeZoneUnavailable, n as CasMismatchError, r as DbError, t as CasExhaustedError } from "./db-error-D5uilS_A.mjs";
-import { $ as isGeoIndexableType, A as vectorIndexNotFoundMessage, B as guardAggregate, C as createFailureCollector, D as resolveDesignType, E as AtscriptDbReadable, F as bucketSourceVerdict, G as narrowerFilterOps, H as guardPath, I as canFilterLeaf, J as RelationalFieldMapper, K as sortFieldNames, L as checkHavingKeys, M as ENCRYPTED_REASON, N as acceptedOperatorsHint, O as geoIndexNotFoundMessage, P as assertGeoPoint, Q as TableMetadata, R as classifyQueryPath, S as BaseDbAdapter, T as NativeIntegrity, U as guardPaths, V as guardFilter, W as guardQuery, X as FieldMappingStrategy, Y as DocumentFieldMapper, Z as UniquSelect, _ as AtscriptDbTable, at as normalizeComputedSelect, b as ApplicationIntegrity, et as isGeoPointType, g as isViewType, h as isAtscriptDbView, it as jsonValueAncestor, j as ADAPTER_FILTER_REASON, k as searchIndexNotFoundMessage, m as AtscriptDbView, n as isColumnTypeChanged, nt as isBucketableField, ot as resolveCalendarBuckets, q as unsupportedOperatorMessage, rt as isJsonValueField, st as NoopLogger, tt as aliasTargetOf, v as assertNoVersionWrites, w as IntegrityStrategy, x as ALL_BUCKET_UNITS, y as decomposePatch, z as collectQueryPaths } from "./column-diff-e2oHc71_.mjs";
-import { t as ALL_AGGREGATE_FNS } from "./aggregate-fns-CfsveE1w.mjs";
-import { T as tableNameOf } from "./nested-writer-CnOOAehr.mjs";
+import { $ as UniquSelect, A as geoIndexNotFoundMessage, B as classifyQueryPath, C as ALL_VIEW_CAPABILITIES, D as NativeIntegrity, E as IntegrityStrategy, F as acceptedOperatorsHint, G as guardPaths, H as guardAggregate, I as assertGeoPoint, J as sortFieldNames, K as guardQuery, L as bucketSourceVerdict, M as vectorIndexNotFoundMessage, N as ADAPTER_FILTER_REASON, O as AtscriptDbReadable, P as ENCRYPTED_REASON, Q as FieldMappingStrategy, R as canFilterLeaf, S as ALL_BUCKET_UNITS, T as createFailureCollector, U as guardFilter, V as collectQueryPaths, W as guardPath, X as RelationalFieldMapper, Y as unsupportedOperatorMessage, Z as DocumentFieldMapper, _ as isViewType, at as isJsonValueField, b as decomposePatch, ct as resolveCalendarBuckets, et as TableMetadata, f as fkColumns, g as isAtscriptDbView, h as AtscriptDbView, it as isBucketableField, j as searchIndexNotFoundMessage, k as resolveDesignType, lt as NoopLogger, n as isColumnTypeChanged, nt as isGeoPointType, ot as jsonValueAncestor, q as narrowerFilterOps, rt as aliasTargetOf, st as normalizeComputedSelect, tt as isGeoIndexableType, v as AtscriptDbTable, w as BaseDbAdapter, x as ApplicationIntegrity, y as assertNoVersionWrites, z as checkHavingKeys } from "./column-diff-CO06iQvI.mjs";
+import { n as ALL_AGGREGATE_FNS } from "./aggregate-fns-C0BymEqa.mjs";
+import { B as tableNameOf, C as ResolvedRelationFilter, D as forEachResolvedRelation, M as relationStaticFilter, O as hasRelationOp, S as REL_FILTER_MAX_NODES, T as containsRelationFilter, U as isFieldRef, W as translateQueryTree, k as isResolvedRelationFilter, w as andFilters, x as REL_FILTER_MAX_DEPTH } from "./nested-writer-D35UsDBT.mjs";
 import { t as DB_ENTITY_ANNOTATIONS } from "./derived-rules-0sKn4f5C.mjs";
 import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, t as deletePath } from "./object-TkiJQ-Dp.mjs";
 import { t as DEFAULT_DB_SPACE } from "./consts-C_-5_pFq.mjs";
 import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, reconcileCas, separateCas, separateFieldOps } from "./ops.mjs";
 import { a as forceNavNonOptional, c as getKeyProps, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-Clu2q_7z.mjs";
 import { isAnnotatedType } from "@atscript/typescript/utils";
-import { computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
+import { RELATION_OPS, computeInsights, isPrimitive, isRelationOp, walkFilter } from "@uniqu/core";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 //#region src/encryption.ts
 const ENVELOPE_VERSION = "aes1";
@@ -376,34 +376,6 @@ var DbSpace = class {
 	}
 };
 //#endregion
-//#region src/query/query-tree.ts
-/**
-* `true` when a query-tree operand is a field reference (`{ field, type? }`)
-* rather than a literal — e.g. the right side of a field-to-field comparison.
-* @since 0.1.136
-*/
-function isFieldRef(value) {
-	return value !== null && typeof value === "object" && "field" in value;
-}
-/**
-* Translates a JS-emitted query tree into a FilterExpr.
-* Resolves field references (type + field path) to physical column names
-* via the provided resolver function.
-*/
-function translateQueryTree(node, resolveField) {
-	if ("$and" in node) return { $and: node.$and.map((n) => translateQueryTree(n, resolveField)) };
-	if ("$or" in node) return { $or: node.$or.map((n) => translateQueryTree(n, resolveField)) };
-	if ("$not" in node) return { $not: translateQueryTree(node.$not, resolveField) };
-	const comp = node;
-	const leftField = resolveField(comp.left);
-	if (isFieldRef(comp.right)) {
-		const rightField = resolveField(comp.right);
-		return { [leftField]: { [comp.op]: { $field: rightField } } };
-	}
-	if (comp.op === "$exists") return { [leftField]: { $exists: comp.right !== false } };
-	return { [leftField]: { [comp.op]: comp.right } };
-}
-//#endregion
 //#region src/table/db-entity.ts
 /**
 * Whether `value` is a compiled type a `DbSpace` accepts: an annotated type
@@ -422,4 +394,4 @@ function isDbEntityType(value) {
 	return DB_ENTITY_ANNOTATIONS.some((name) => value.metadata.has(name));
 }
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, CasMismatchError, DEFAULT_DB_SPACE, DbEncryption, DbError, DbSpace, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RelationalFieldMapper, TableMetadata, UniquSelect, acceptedOperatorsHint, aliasTargetOf, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, deletePath, findAncestorInSet, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, reconcileCas, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, tableNameOf, translateQueryTree, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, CasMismatchError, DEFAULT_DB_SPACE, DbEncryption, DbError, DbSpace, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, RelationalFieldMapper, ResolvedRelationFilter, TableMetadata, UniquSelect, acceptedOperatorsHint, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, deletePath, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, tableNameOf, translateQueryTree, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };

package/dist/{nested-writer-CnOOAehr.mjs → nested-writer-D35UsDBT.mjs}

@@ -1,6 +1,100 @@
 import { i as DepthLimitExceededError, r as DbError } from "./db-error-D5uilS_A.mjs";
-import { r as getPath } from "./object-TkiJQ-Dp.mjs";
+import { a as isPlainObject, r as getPath } from "./object-TkiJQ-Dp.mjs";
 import { ValidatorError } from "@atscript/typescript/utils";
+import { isRelationOp } from "@uniqu/core";
+//#region src/query/query-tree.ts
+/**
+* `true` when a query-tree operand is a field reference (`{ field, type? }`)
+* rather than a literal — e.g. the right side of a field-to-field comparison.
+* @since 0.1.136
+*/
+function isFieldRef(value) {
+	return value !== null && typeof value === "object" && "field" in value;
+}
+/**
+* Translates a JS-emitted query tree into a FilterExpr.
+* Resolves field references (type + field path) to physical column names
+* via the provided resolver function.
+*/
+function translateQueryTree(node, resolveField) {
+	if ("$and" in node) return { $and: node.$and.map((n) => translateQueryTree(n, resolveField)) };
+	if ("$or" in node) return { $or: node.$or.map((n) => translateQueryTree(n, resolveField)) };
+	if ("$not" in node) return { $not: translateQueryTree(node.$not, resolveField) };
+	const comp = node;
+	const leftField = resolveField(comp.left);
+	if (isFieldRef(comp.right)) {
+		const rightField = resolveField(comp.right);
+		return { [leftField]: { [comp.op]: { $field: rightField } } };
+	}
+	if (comp.op === "$exists") return { [leftField]: { $exists: comp.right !== false } };
+	return { [leftField]: { [comp.op]: comp.right } };
+}
+/**
+* Calls `leaf` with the field path of every field-reference leaf of a
+* computed-column expression (`@db.compute`), in source order — leaves name
+* the view's own fields.
+* @since 0.1.147
+*/
+function walkViewExpr(expr, leaf) {
+	if (typeof expr === "number") return;
+	if ("field" in expr) {
+		leaf(expr.field);
+		return;
+	}
+	for (const arg of expr.args) walkViewExpr(arg, leaf);
+}
+/**
+* Whether a computed-column expression may yield NULL: a `/` (division by
+* zero is NULL), a leaf for which `nullableLeaf` holds, or an operation over
+* a nullable operand — `coalesce` only when every argument is nullable.
+* @since 0.1.147
+*/
+function viewExprNullable(expr, nullableLeaf) {
+	if (typeof expr === "number") return false;
+	if ("field" in expr) return nullableLeaf(expr.field);
+	if (expr.op === "/") return true;
+	if (expr.op === "coalesce") return expr.args.every((a) => viewExprNullable(a, nullableLeaf));
+	return expr.args.some((a) => viewExprNullable(a, nullableLeaf));
+}
+/**
+* The `@db.compute` expression of a view field, if any.
+* @since 0.1.147
+*/
+function computeOf(fieldType) {
+	return fieldType?.metadata.get("db.compute");
+}
+/**
+* The transitive non-computed operands of the `@db.compute` field `field` of
+* `viewType`: its leaves, a computed leaf replaced by its own operands, and
+* (`via`) the computed fields passed through. `undefined` when `field` is not
+* computed. Cycles are not followed (they are rejected where the view's
+* columns are built).
+* @since 0.1.147
+*/
+function computedOperands(viewType, field) {
+	const props = viewType.type.kind === "object" ? viewType.type.props : void 0;
+	const exprOf = (name) => computeOf(props?.get(name));
+	const root = exprOf(field);
+	if (root === void 0) return void 0;
+	const out = /* @__PURE__ */ new Set();
+	const via = [];
+	const seen = new Set([field]);
+	const visit = (expr) => walkViewExpr(expr, (path) => {
+		const nested = exprOf(path);
+		if (nested === void 0) out.add(path);
+		else if (!seen.has(path)) {
+			seen.add(path);
+			via.push(path);
+			visit(nested);
+		}
+	});
+	visit(root);
+	return {
+		operands: [...out],
+		via
+	};
+}
+//#endregion
 //#region src/rel/relation-helpers.ts
 /**
 * Finds the FK entry that connects a `@db.rel.to` relation to its target.
@@ -52,6 +146,452 @@ function tableNameOf(type) {
 function resolveRelationTargetTable(relation) {
 	return tableNameOf(relation.targetType());
 }
+/**
+* A string key of `fields`' values on `obj` — equal for rows that agree on
+* every field (`null` / `undefined` key distinctly from any string). `read`
+* reads one field (default: a top-level property).
+*/
+function compositeKey(fields, obj, read = (o, f) => o[f]) {
+	let key = "";
+	for (let i = 0; i < fields.length; i++) {
+		if (i > 0) key += "\0\0";
+		const v = read(obj, fields[i]);
+		key += v === null || v === void 0 ? "\0" : String(v);
+	}
+	return key;
+}
+/**
+* Keeps, of each group of `rows` sharing `keyOf(row)`, the rows `page`
+* selects — `$skip` / `$limit` applied per group, in the order of `rows`.
+* The order of the kept rows is preserved.
+*/
+function slicePerGroup(rows, keyOf, page) {
+	const skip = page.skip ?? 0;
+	const end = page.limit === void 0 ? Infinity : skip + page.limit;
+	const seen = /* @__PURE__ */ new Map();
+	const kept = [];
+	for (const row of rows) {
+		const key = keyOf(row);
+		const index = seen.get(key) ?? 0;
+		seen.set(key, index + 1);
+		if (index >= skip && index < end) kept.push(row);
+	}
+	return kept;
+}
+//#endregion
+//#region src/query/relation-filter.ts
+/**
+* Relational filter predicates (`{ nav: { $some | $none: <filter on the
+* related table> } }`) — resolution against the related tables.
+*
+* Semantics: `rel(r, nav)` is exactly the set of related rows `$with=nav`
+* loads for row `r` (same foreign-key pairing, the relation's
+* `@db.rel.filter` included). `$some: F` holds when one of them matches `F`,
+* `$none: F` when none does; a NULL foreign-key component means "no related
+* row". The core resolves each predicate into a {@link ResolvedRelationFilter}
+* (physical names on every side, the inner filter translated by the related
+* table's own field mapper) before the adapter sees the filter — adapters
+* only render it.
+*
+* @since 0.1.147
+*/
+/**
+* Maximum nesting of relational predicates in one filter, server-added ones
+* included (a predicate inside a predicate's operand counts one level). The
+* core backstop for every caller; higher than moost-db's per-client limit
+* (`REL_FILTER_CLIENT_MAX_DEPTH`) so server overlays (row scopes,
+* `transformRelationFilter`) have headroom above what a client may send.
+*/
+const REL_FILTER_MAX_DEPTH = 4;
+/** Maximum number of relational predicates in one filter (nested and server-added ones included). See {@link REL_FILTER_MAX_DEPTH}. */
+const REL_FILTER_MAX_NODES = 16;
+/**
+* Cross-realm brand of {@link ResolvedRelationFilter}: `instanceof` fails when
+* two copies of `@atscript/db` are loaded (ESM + CJS, or nested installs) and
+* an adapter from one sees nodes built by the other.
+*/
+const RESOLVED_BRAND = Symbol.for("@atscript/db:ResolvedRelationFilter");
+/**
+* A relational predicate as adapters receive it — the operand of
+* `FilterVisitor.relation(field, op, operand)` once the core translated the
+* filter. Every name is physical:
+*
+* - `to` / `from`: `pairs` correlate a SOURCE column with a TARGET column
+*   (`target.<pair.target> = source.<pair.source>`, one pair per composite
+*   key part);
+* - `via`: `pairs` is empty — `junction.toSource` correlates the junction
+*   with the source row, `junction.toTarget` with the target row.
+*
+* `filter` is the inner filter on the TARGET (already translated by the
+* target's field mapper: renames, flattening, value formatters; nested
+* predicates resolved the same way), conjoined with the target part of the
+* relation's `@db.rel.filter`. `{}` matches every related row.
+*
+* @since 0.1.147
+*/
+var ResolvedRelationFilter = class {
+	/** @internal cross-realm brand (see {@link isResolvedRelationFilter}). */
+	[RESOLVED_BRAND] = true;
+	kind;
+	/** Logical navigation field name on the source table. */
+	nav;
+	source;
+	target;
+	pairs;
+	junction;
+	filter;
+	constructor(init) {
+		this.kind = init.kind;
+		this.nav = init.nav;
+		this.source = init.source;
+		this.target = init.target;
+		this.pairs = init.pairs;
+		this.junction = init.junction;
+		this.filter = init.filter;
+	}
+};
+/** `true` for a {@link ResolvedRelationFilter} (the resolved operand of a predicate). */
+function isResolvedRelationFilter(value) {
+	return typeof value === "object" && value !== null && value[RESOLVED_BRAND] === true;
+}
+/** `true` when `value` (a filter entry's value) is an operator map with a `$some` / `$none` key. */
+function hasRelationOp(value) {
+	if (!isPlainObject(value)) return false;
+	for (const key in value) if (isRelationOp(key)) return true;
+	return false;
+}
+/**
+* Pre-scan results of filters the core BUILT (translated / resolved
+* filters, never mutated after) — adapters scan the same translated filter
+* several times per operation. Caller-owned filters are never cached: they
+* may be mutated between two queries.
+*/
+const relationFilterCache = /* @__PURE__ */ new WeakMap();
+/** @internal Records the pre-scan result of a filter the core built. */
+function noteRelationFilter(filter, has) {
+	if (filter && typeof filter === "object") relationFilterCache.set(filter, has);
+}
+/**
+* `true` when `filter` holds a relational predicate anywhere outside
+* predicate operands (through `$and` / `$or` / `$not`) — the cheap pre-scan
+* the field mappers and renderers use to keep predicate-free filters on
+* their fast paths. Results for filters the core translated are cached.
+*/
+function containsRelationFilter(filter) {
+	if (!filter || typeof filter !== "object") return false;
+	const cached = relationFilterCache.get(filter);
+	if (cached !== void 0) return cached;
+	for (const [key, value] of Object.entries(filter)) if (key === "$and" || key === "$or") {
+		if (Array.isArray(value) && value.some((child) => containsRelationFilter(child))) return true;
+	} else if (key === "$not") {
+		if (containsRelationFilter(value)) return true;
+	} else if (!key.startsWith("$") && hasRelationOp(value)) return true;
+	return false;
+}
+/**
+* Calls `visit` for every resolved predicate of a TRANSLATED filter,
+* depth-first: the top-level ones, then (with `nested`) those inside each
+* operand — target filters and junction filters alike. Adapters use it to
+* prepare per-predicate data (memory snapshots, self-referencing checks).
+*/
+function forEachResolvedRelation(filter, visit, nested = true) {
+	if (!filter || typeof filter !== "object") return;
+	for (const [key, value] of Object.entries(filter)) if (key === "$and" || key === "$or") {
+		if (Array.isArray(value)) for (const child of value) forEachResolvedRelation(child, visit, nested);
+	} else if (key === "$not") forEachResolvedRelation(value, visit, nested);
+	else if (!key.startsWith("$") && isPlainObject(value)) for (const [op, operand] of Object.entries(value)) {
+		if (!isRelationOp(op) || !isResolvedRelationFilter(operand)) continue;
+		visit(operand, op);
+		if (nested) {
+			forEachResolvedRelation(operand.filter, visit, nested);
+			forEachResolvedRelation(operand.junction?.filter, visit, nested);
+		}
+	}
+}
+/** A fresh {@link TRelGuardState} for one query. */
+function relGuardState(write = false) {
+	return {
+		depth: 0,
+		counter: { nodes: 0 },
+		write,
+		path: ""
+	};
+}
+function invalid(path, message) {
+	return new DbError("INVALID_QUERY", [{
+		path,
+		message
+	}]);
+}
+function notSupported(path, message) {
+	return new DbError("REL_FILTER_NOT_SUPPORTED", [{
+		path,
+		message
+	}]);
+}
+/** The present, non-empty `parts` ANDed (`{}` when none, a single one as is). */
+function andFilters(...parts) {
+	const present = parts.filter((p) => p != null && Object.keys(p).length > 0);
+	if (present.length === 0) return {};
+	if (present.length === 1) return present[0];
+	return { $and: present };
+}
+const NO_STATIC_FILTER = {};
+const staticFilterCache = /* @__PURE__ */ new WeakMap();
+/**
+* A relation's `@db.rel.filter` as logical filters per side — what `$with`
+* loading and relational predicates both AND into the related rows (the
+* filter is part of the relation's meaning). Top-level `and` conditions are
+* split by side: an unqualified field and the related type's fields go to
+* `target`, the `@db.rel.via` junction's to `junction`. A single condition
+* that reads both sides (e.g. an `or` across them) or compares two fields is
+* rejected with `INVALID_QUERY` — `name` is the navigation field (error path).
+*
+* @since 0.1.147
+*/
+function relationStaticFilter(relation, name = "") {
+	if (!relation.filter) return NO_STATIC_FILTER;
+	const cached = staticFilterCache.get(relation);
+	if (cached) return cached;
+	const targetType = relation.targetType();
+	const junctionType = relation.viaType?.();
+	const targetName = tableNameOf(targetType);
+	const junctionName = junctionType ? tableNameOf(junctionType) : void 0;
+	const sideOf = (ref) => {
+		const type = ref.type?.();
+		if (!type || type === targetType || tableNameOf(type) === targetName) return "target";
+		if (junctionType && (type === junctionType || tableNameOf(type) === junctionName)) return "junction";
+		throw invalid(name, `@db.rel.filter on "${name}" references a type other than the related type` + (junctionType ? " and the junction" : "") + " — only those can be referenced");
+	};
+	const target = [];
+	const junction = [];
+	const conjuncts = "$and" in relation.filter ? relation.filter.$and : [relation.filter];
+	for (const conjunct of conjuncts) {
+		const sides = /* @__PURE__ */ new Set();
+		collectSides(conjunct, (ref) => sides.add(sideOf(ref)), name);
+		if (sides.size > 1) throw invalid(name, `@db.rel.filter on "${name}" has a condition reading both the junction and the related type — split it into separate "and" conditions`);
+		const filter = translateQueryTree(conjunct, (ref) => ref.field);
+		(sides.has("junction") ? junction : target).push(filter);
+	}
+	const result = {
+		target: target.length > 0 ? andFilters(...target) : void 0,
+		junction: junction.length > 0 ? andFilters(...junction) : void 0
+	};
+	staticFilterCache.set(relation, result);
+	return result;
+}
+function collectSides(node, visit, name) {
+	if ("$and" in node) {
+		for (const child of node.$and) collectSides(child, visit, name);
+		return;
+	}
+	if ("$or" in node) {
+		for (const child of node.$or) collectSides(child, visit, name);
+		return;
+	}
+	if ("$not" in node) {
+		collectSides(node.$not, visit, name);
+		return;
+	}
+	visit(node.left);
+	if (isFieldRef(node.right)) throw invalid(name, `@db.rel.filter on "${name}" compares two fields — only field-to-value conditions are supported`);
+}
+function zip(left, right, a, b) {
+	return left.map((value, i) => ({
+		[a]: value,
+		[b]: right[i]
+	}));
+}
+/**
+* The {@link TRelationFilterHost} of a readable: resolves a navigation
+* field's related table (and junction) through `resolve` (the readable's
+* table resolver), pairing foreign keys exactly like `$with` loading does
+* (`findFKEntryForRelation` / `findRemoteFK`).
+*/
+function createRelationFilterHost(owner, resolve) {
+	const plans = /* @__PURE__ */ new Map();
+	const sameAdapter = (other, path, what) => {
+		if (!owner.getAdapter().sharesStoreWith(other.getAdapter())) throw notSupported(path, `Relational predicate on "${path}": the ${what} table lives in a different database or adapter`);
+	};
+	const planOf = (nav, path) => {
+		const cached = plans.get(nav);
+		if (cached) return cached;
+		const meta = owner.getMetadata();
+		const relation = meta.relations.get(nav);
+		if (!relation) throw invalid(path, `"$some" / "$none" are only valid on a navigation relation — "${nav}" is not one`);
+		const target = resolve(relation.targetType());
+		if (!target) throw notSupported(path, `Relational predicate on "${path}": the related table is not available`);
+		sameAdapter(target, path, "related");
+		let plan;
+		if (relation.direction === "to") {
+			const fk = findFKEntryForRelation(relation, meta.foreignKeys);
+			if (!fk) throw invalid(path, `Relation "${nav}" has no foreign key to filter by`);
+			plan = {
+				kind: "to",
+				relation,
+				target,
+				pairs: zip(fk.fields, fk.targetFields, "source", "target")
+			};
+		} else if (relation.direction === "from") {
+			const fk = findRemoteFK(target.getMetadata(), owner.tableName, relation.alias);
+			if (!fk) throw invalid(path, `Relation "${nav}" has no foreign key to filter by`);
+			plan = {
+				kind: "from",
+				relation,
+				target,
+				pairs: zip(fk.targetFields, fk.fields, "source", "target")
+			};
+		} else {
+			const junctionType = relation.viaType?.();
+			const junction = junctionType ? resolve(junctionType) : void 0;
+			if (!junction) throw notSupported(path, `Relational predicate on "${path}": the junction table is not available`);
+			sameAdapter(junction, path, "junction");
+			const junctionMeta = junction.getMetadata();
+			const fkToThis = findRemoteFK(junctionMeta, owner.tableName);
+			const fkToTarget = findRemoteFK(junctionMeta, tableNameOf(relation.targetType()));
+			if (!fkToThis || !fkToTarget) throw invalid(path, `Relation "${nav}" has no junction foreign keys to filter by`);
+			if (fkToThis === fkToTarget) throw invalid(path, `Relation "${nav}" is a self-referencing many-to-many — relational predicates cannot tell its two junction keys apart`);
+			plan = {
+				kind: "via",
+				relation,
+				target,
+				pairs: [],
+				junction: {
+					owner: junction,
+					toSource: zip(fkToThis.fields, fkToThis.targetFields, "junction", "source"),
+					toTarget: zip(fkToTarget.fields, fkToTarget.targetFields, "junction", "target")
+				}
+			};
+		}
+		plans.set(nav, plan);
+		return plan;
+	};
+	const tableOf = (o) => {
+		const adapter = o.getAdapter();
+		return {
+			table: adapter.resolveTableName(),
+			name: adapter.resolveTableName(false),
+			adapter
+		};
+	};
+	return {
+		guard(nav, op, inner, state) {
+			const path = state.path ? `${state.path}.${nav}` : nav;
+			const depth = state.depth + 1;
+			if (depth > 4) throw invalid("", `Relational predicates nest at most 4 levels deep`);
+			if (++state.counter.nodes > 16) throw invalid("", `At most 16 relational predicates per query`);
+			if (!isPlainObject(inner)) throw invalid(path, `"${op}" on "${path}" expects a filter object`);
+			const plan = planOf(nav, path);
+			relationStaticFilter(plan.relation, path);
+			try {
+				plan.target._guardRelationOperand(inner, {
+					...state,
+					depth,
+					path
+				});
+			} catch (error) {
+				throw prefixError(error, path);
+			}
+		},
+		resolve(nav, _op, inner, depth) {
+			if (depth > 4) throw invalid("", `Relational predicates nest at most 4 levels deep`);
+			const plan = planOf(nav, nav);
+			const ownerMeta = owner.getMetadata();
+			const targetMeta = plan.target.getMetadata();
+			const statics = relationStaticFilter(plan.relation, nav);
+			const filter = plan.target._resolveRelationOperand(andFilters(statics.target, inner), depth);
+			let junction;
+			if (plan.junction) {
+				const junctionMeta = plan.junction.owner.getMetadata();
+				junction = {
+					...tableOf(plan.junction.owner),
+					toSource: plan.junction.toSource.map((p) => ({
+						junction: junctionMeta.physicalPath(p.junction),
+						source: ownerMeta.physicalPath(p.source)
+					})),
+					toTarget: plan.junction.toTarget.map((p) => ({
+						junction: junctionMeta.physicalPath(p.junction),
+						target: targetMeta.physicalPath(p.target)
+					})),
+					...statics.junction ? { filter: plan.junction.owner._resolveRelationOperand(statics.junction, depth) } : {}
+				};
+			}
+			return new ResolvedRelationFilter({
+				kind: plan.kind,
+				nav,
+				source: tableOf(owner),
+				target: tableOf(plan.target),
+				pairs: plan.pairs.map((p) => ({
+					source: ownerMeta.physicalPath(p.source),
+					target: targetMeta.physicalPath(p.target)
+				})),
+				junction,
+				filter
+			});
+		}
+	};
+}
+/** Re-throws a related table's guard error with its paths under the navigation chain. */
+function prefixError(error, path) {
+	if (!(error instanceof DbError)) return error;
+	if (error.errors.every((e) => !e.path)) return error;
+	if (error.errors.every((e) => e.path === path || e.path.startsWith(`${path}.`))) return error;
+	const errors = error.errors.map((e) => ({
+		path: e.path ? `${path}.${e.path}` : path,
+		message: e.message
+	}));
+	return new DbError(error.code, errors, `${errors[0]?.message ?? error.message} (in "${path}")`);
+}
+/**
+* Resolves every relational predicate of a (logical) filter through
+* `meta.relationFilters` — the step every field-mapper entry point runs
+* first. Predicates at the top of `filter` are at level `depth + 1`.
+* Already-resolved operands pass through, so translating twice is safe.
+* One pass: unchanged subtrees (and `filter` itself, when nothing needed
+* resolving) are returned as they are.
+*/
+function resolveRelationFilterTree(filter, meta, depth) {
+	let out;
+	for (const [key, value] of Object.entries(filter)) {
+		let next = value;
+		if (key === "$and" || key === "$or") {
+			if (Array.isArray(value)) {
+				let children;
+				for (let i = 0; i < value.length; i++) {
+					const child = value[i];
+					if (!child || typeof child !== "object") continue;
+					const resolved = resolveRelationFilterTree(child, meta, depth);
+					if (resolved === child) continue;
+					children ??= [...value];
+					children[i] = resolved;
+				}
+				if (children) next = children;
+			}
+		} else if (key === "$not") {
+			if (value && typeof value === "object") next = resolveRelationFilterTree(value, meta, depth);
+		} else if (!key.startsWith("$") && hasRelationOp(value)) next = resolvePredicateMap(key, value, meta, depth);
+		if (next === value) continue;
+		out ??= { ...filter };
+		out[key] = next;
+	}
+	if (!out) return filter;
+	noteRelationFilter(out, true);
+	return out;
+}
+/** One `{ $some | $none: … }` map of `key` resolved (operands already resolved pass through). */
+function resolvePredicateMap(key, value, meta, depth) {
+	const host = meta.relationFilters;
+	if (!host) {
+		if (!meta.navFields.has(key)) throw invalid(key, `"$some" / "$none" are only valid on a navigation relation — "${key}" is not one`);
+		throw notSupported(key, `Relational predicate on "${key}" needs the table to come from a DbSpace (no table resolver)`);
+	}
+	const ops = {};
+	for (const [op, operand] of Object.entries(value)) {
+		if (!isRelationOp(op)) throw invalid(key, `Cannot mix "$some" / "$none" with "${op}" on "${key}"`);
+		ops[op] = isResolvedRelationFilter(operand) ? operand : host.resolve(key, op, operand, depth + 1);
+	}
+	return ops;
+}
 //#endregion
 //#region src/shared/keys.ts
 /** String form of a key value (an ObjectId stringifies to its hex, a bigint to its digits). */
@@ -877,4 +1417,4 @@ async function viaReplace(via, targets, parentPK, maxDepth, depth) {
 	await viaLinkTargets(via, targets, parentPK, maxDepth, depth);
 }
 //#endregion
-export { findRemoteFK as C, findFKForRelation as S, tableNameOf as T, remapDeleteFkViolation as _, batchPatchNestedFrom as a, sameKey as b, batchReplaceNestedFrom as c, checkDepthOverflow as d, planNestedFromVia as f, enrichFkViolation as g, validateBatch as h, batchInsertNestedVia as i, batchReplaceNestedTo as l, preValidateNestedFrom as m, batchInsertNestedFrom as n, batchPatchNestedTo as o, planPatchNestedTo as p, batchInsertNestedTo as r, batchPatchNestedVia as s, applyPatchNestedTo as t, batchReplaceNestedVia as u, pkTupleKey as v, resolveRelationTargetTable as w, findFKEntryForRelation as x, rowMatchesKey as y };
+export { noteRelationFilter as A, tableNameOf as B, ResolvedRelationFilter as C, forEachResolvedRelation as D, createRelationFilterHost as E, findFKEntryForRelation as F, viewExprNullable as G, computedOperands as H, findFKForRelation as I, walkViewExpr as K, findRemoteFK as L, relationStaticFilter as M, resolveRelationFilterTree as N, hasRelationOp as O, compositeKey as P, resolveRelationTargetTable as R, REL_FILTER_MAX_NODES as S, containsRelationFilter as T, isFieldRef as U, computeOf as V, translateQueryTree as W, remapDeleteFkViolation as _, batchPatchNestedFrom as a, sameKey as b, batchReplaceNestedFrom as c, checkDepthOverflow as d, planNestedFromVia as f, enrichFkViolation as g, validateBatch as h, batchInsertNestedVia as i, relGuardState as j, isResolvedRelationFilter as k, batchReplaceNestedTo as l, preValidateNestedFrom as m, batchInsertNestedFrom as n, batchPatchNestedTo as o, planPatchNestedTo as p, batchInsertNestedTo as r, batchPatchNestedVia as s, applyPatchNestedTo as t, batchReplaceNestedVia as u, pkTupleKey as v, andFilters as w, REL_FILTER_MAX_DEPTH as x, rowMatchesKey as y, slicePerGroup as z };