@atscript/db 0.1.146 → 0.1.148

package/dist/{column-diff-e2oHc71_.mjs → column-diff-Cp6ZoyRE.mjs}

@@ -1,13 +1,15 @@
-import { n as CasMismatchError, r as DbError } from "./db-error-D5uilS_A.mjs";
-import { i as SUPPORTED_AGGREGATE_FNS, n as BASE_AGGREGATE_FNS } from "./aggregate-fns-CfsveE1w.mjs";
-import { C as findRemoteFK, S as findFKForRelation, T as tableNameOf, _ as remapDeleteFkViolation, a as batchPatchNestedFrom, b as sameKey, c as batchReplaceNestedFrom, d as checkDepthOverflow, f as planNestedFromVia, g as enrichFkViolation, h as validateBatch, i as batchInsertNestedVia, l as batchReplaceNestedTo, m as preValidateNestedFrom, n as batchInsertNestedFrom, p as planPatchNestedTo, r as batchInsertNestedTo, s as batchPatchNestedVia, t as applyPatchNestedTo, u as batchReplaceNestedVia, v as pkTupleKey, x as findFKEntryForRelation, y as rowMatchesKey } from "./nested-writer-CnOOAehr.mjs";
+import { a as aggregateExpressionsNotSupported, l as spaceClosedError, n as CasMismatchError, r as DbError } from "./db-error-Az85UhTX.mjs";
+import { a as SOURCE_VALUE_FNS, c as isFirstLast, o as SUPPORTED_AGGREGATE_FNS, r as BASE_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-CyaZyb9I.mjs";
+import { B as slicePerGroup, D as createRelationFilterHost, E as containsRelationFilter, F as compositeKey, H as computeOf, I as findFKEntryForRelation, J as walkViewExpr, L as findFKForRelation, M as relGuardState, P as resolveRelationFilterTree, R as findRemoteFK, U as computedOperands, V as tableNameOf, _ as remapDeleteFkViolation, a as batchPatchNestedFrom, b as sameKey, c as batchReplaceNestedFrom, d as checkDepthOverflow, f as planNestedFromVia, g as enrichFkViolation, h as validateBatch, i as batchInsertNestedVia, j as noteRelationFilter, k as hasRelationOp, l as batchReplaceNestedTo, m as preValidateNestedFrom, n as batchInsertNestedFrom, p as planPatchNestedTo, q as viewExprNullable, r as batchInsertNestedTo, s as batchPatchNestedVia, t as applyPatchNestedTo, u as batchReplaceNestedVia, v as pkTupleKey, x as uniqueKeyTuple, y as rowMatchesKey } from "./nested-writer-CUBoq1ZO.mjs";
 import { i as isJsonLeafType, n as DERIVED_INCOMPATIBLE } 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 { resolveAlias } from "./agg.mjs";
+import { resolveAlias as resolveAlias$1 } from "./agg.mjs";
+import { t as numericTypeProblem } from "./numeric-operand-B1jKH7x5.mjs";
+import { t as NOT_DIMENSION_REASON } from "./aggregate-rules-jdPrxqWa.mjs";
 import { separateCas, separateFieldOps } from "./ops.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, i as dbPlugin, n as buildPatchPartial, t as buildDbValidator } from "./validator-Clu2q_7z.mjs";
+import { a as forceNavNonOptional, c as getKeyProps, i as dbPlugin, n as buildPatchPartial, t as buildDbValidator } from "./validator-BTiIOTKP.mjs";
 import { flattenAnnotatedType, isAnnotatedType } from "@atscript/typescript/utils";
-import { BUCKET_UNITS, isAggregateExpr, isBucketExpr, isPrimitive, resolveBuckets } from "@uniqu/core";
+import { ARITH_MAX_NODES, BUCKET_UNITS, isAggregateExpr, isAggregateOfExpr, isBucketExpr, isPrimitive, isRelationOp, isSelectArithExpr, resolveAlias, resolveBuckets } from "@uniqu/core";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/logger.ts
 const NoopLogger = {
@@ -51,13 +53,39 @@ const NoopLogger = {
 * @throws DbError `INVALID_QUERY` carrying every issue (`path` `$select` / `$groupBy`).
 */
 function normalizeComputedSelect(controls, fields, aggregate) {
+	return resolveComputedSelect(controls, fields, aggregate).buckets;
+}
+/**
+* Everything {@link normalizeComputedSelect} resolves: the calendar buckets,
+* the arithmetic entries (`exprs`: row-level first, then group-level in
+* dependency order — logical names) and the `$rowOrder` keys of `first()` /
+* `last()` (`rowOrder`, as given — the primary key is appended by the
+* mapper). The same normalizer, also covering uniqu's expression and
+* `$rowOrder` rules.
+*
+* @throws DbError `INVALID_QUERY` carrying every issue (`path` `$select` / `$groupBy` / `$rowOrder`).
+* @since 0.1.148
+*/
+function resolveComputedSelect(controls, fields, aggregate) {
+	const select = controls?.$select;
+	const idIssues = [];
+	if (Array.isArray(select)) {
+		for (const entry of select) if (entry && typeof entry === "object" && entry.$as === "_id") idIssues.push({
+			path: "$select",
+			message: "Alias \"_id\" is reserved — pick another alias for this $select entry"
+		});
+	}
 	const res = resolveBuckets(controls, {
 		aggregate,
 		fns: SUPPORTED_AGGREGATE_FNS,
 		isField: (name) => fields.flatMap.has(name) || fields.navFields.has(name) || fields.physicalNames.has(name)
 	});
-	if (!res.ok) throw new DbError("INVALID_QUERY", res.issues);
-	return res.buckets;
+	if (!res.ok || idIssues.length > 0) throw new DbError("INVALID_QUERY", [...idIssues, ...res.ok ? [] : res.issues]);
+	return {
+		buckets: res.buckets,
+		exprs: res.exprs,
+		rowOrder: res.rowOrder
+	};
 }
 /**
 * @deprecated since 0.1.136 — renamed {@link normalizeComputedSelect} (it
@@ -471,6 +499,14 @@ var TableMetadata = class {
 	jsonValueParents = /* @__PURE__ */ new Set();
 	/** Every field descriptor's `physicalName` — reserved names a bucket alias may not take. */
 	physicalNames = /* @__PURE__ */ new Set();
+	/**
+	* Resolves / guards relational filter predicates (`{ nav: { $some: … } }`)
+	* against the related tables — installed by the owning readable when the
+	* table has navigation fields and a table resolver (a `DbSpace`). The field
+	* mappers and the path guard reach the related tables through it.
+	* @since 0.1.147
+	*/
+	relationFilters;
 	_built = false;
 	_identifications;
 	_alwaysAddressable;
@@ -552,7 +588,7 @@ var TableMetadata = class {
 		if (!this.nestedObjects) this._classifyFields();
 		const overrides = adapter.getMetadataOverrides?.(this);
 		if (overrides) this._applyOverrides(overrides);
-		this._buildFieldDescriptors(adapter);
+		this._buildFieldDescriptors(adapter, type);
 		this._buildGuardIndexes();
 		if (!this.nestedObjects) this._buildLeafIndexes();
 		this._buildIdentifications();
@@ -615,12 +651,15 @@ var TableMetadata = class {
 			const isArr = fieldType.type.kind === "array";
 			const elementType = isArr ? fieldType.type.of : fieldType;
 			const resolveTarget = () => elementType?.ref?.type() ?? elementType;
+			const relFilter = metadata.get("db.rel.filter");
 			this.relations.set(fieldName, {
 				direction,
 				alias,
 				targetType: resolveTarget,
 				isArray: isArr,
-				...direction === "via" ? { viaType: raw } : {}
+				...direction === "via" ? { viaType: raw } : {},
+				...metadata.has("db.rel.filterable") ? { filterable: true } : {},
+				...relFilter ? { filter: relFilter } : {}
 			});
 		}
 		if (metadata.has("db.rel.FK")) {
@@ -878,7 +917,7 @@ var TableMetadata = class {
 	* Called once during build() — everything it needs
 	* (flatMap, indexes, columnMap, etc.) is already populated.
 	*/
-	_buildFieldDescriptors(adapter) {
+	_buildFieldDescriptors(adapter, rootType) {
 		const descriptors = [];
 		const skipFlattening = this.nestedObjects;
 		const indexedFields = new Set([...this.primaryKeys, ...this.uniqueProps]);
@@ -929,10 +968,21 @@ var TableMetadata = class {
 				unitRefField,
 				encrypted: isEncrypted || underEncrypted || void 0,
 				isGeoPoint: isGeoPointType(type) || void 0,
-				derived: this.derivedFields.get(path)
+				derived: this.derivedFields.get(path),
+				computed: computedMeta(rootType, path)
 			});
 		}
-		this._resolveFkTargetFields(descriptors);
+		const flatCache = /* @__PURE__ */ new Map();
+		const flatOf = (type) => {
+			let flat = flatCache.get(type);
+			if (!flat) {
+				flat = flattenAnnotatedType(type);
+				flatCache.set(type, flat);
+			}
+			return flat;
+		};
+		this._resolveFkTargetFields(descriptors, flatOf);
+		this._resolveFkPhysicalFields(flatOf);
 		Object.freeze(descriptors);
 		this.fieldDescriptors = descriptors;
 		this.columnDescriptors = Object.freeze(descriptors.filter((fd) => !fd.ignored && !(skipFlattening && fd.derived)));
@@ -956,9 +1006,37 @@ var TableMetadata = class {
 		}
 	}
 	/**
+	* Fills `physicalFields` / `physicalTargetFields` on every FK: the local
+	* side from this table's path maps, the target side from the referenced
+	* type's own `@db.column` renames (same storage rules as this table — a
+	* dotted target path is a flattened column on relational storage, a
+	* renamed top-level key on document storage).
+	*/
+	_resolveFkPhysicalFields(flatOf) {
+		const targetPhysical = (fk, field) => {
+			const targetType = fk.targetTypeRef?.();
+			if (!targetType) return field;
+			const flat = flatOf(targetType);
+			const columnOf = (path) => flat.get(path)?.metadata?.get("db.column");
+			if (this.nestedObjects) {
+				const dot = field.indexOf(".");
+				const top = dot === -1 ? field : field.slice(0, dot);
+				const renamed = columnOf(top);
+				return renamed === void 0 ? field : renamed + field.slice(top.length);
+			}
+			return relationalColumnName(field, columnOf(field), field.includes("."));
+		};
+		for (const fk of this.foreignKeys.values()) {
+			fk.physicalFields = fk.fields.map((f) => this.physicalPath(f));
+			fk.physicalTargetFields = fk.targetFields.map((f) => targetPhysical(fk, f));
+			const targetSchema = fk.targetTypeRef?.()?.metadata?.get("db.schema");
+			if (targetSchema) fk.targetSchema = targetSchema;
+		}
+	}
+	/**
 	* Resolves `fkTargetField` for FK fields in field descriptors.
 	*/
-	_resolveFkTargetFields(descriptors) {
+	_resolveFkTargetFields(descriptors, flatOf) {
 		if (this.foreignKeys.size === 0) return;
 		const fkFieldToTarget = /* @__PURE__ */ new Map();
 		for (const fk of this.foreignKeys.values()) {
@@ -969,18 +1047,12 @@ var TableMetadata = class {
 			});
 		}
 		if (fkFieldToTarget.size === 0) return;
-		const flatCache = /* @__PURE__ */ new Map();
 		for (const descriptor of descriptors) {
 			const target = fkFieldToTarget.get(descriptor.path);
 			if (!target) continue;
 			const targetType = target.targetTypeRef();
 			if (!targetType) continue;
-			let targetFlatMap = flatCache.get(targetType);
-			if (!targetFlatMap) {
-				targetFlatMap = flattenAnnotatedType(targetType);
-				flatCache.set(targetType, targetFlatMap);
-			}
-			const targetFieldType = targetFlatMap.get(target.targetField);
+			const targetFieldType = flatOf(targetType).get(target.targetField);
 			if (!targetFieldType) continue;
 			const targetMetadata = targetFieldType.metadata;
 			if (targetMetadata?.has("db.encrypted")) throw new Error(`FK field "${descriptor.path}" references encrypted field "${target.targetField}" — joins are impossible over ciphertext`);
@@ -1072,6 +1144,203 @@ var TableMetadata = class {
 		this.preferredId = selected ? [...selected.fields] : [...this.primaryKeys];
 	}
 };
+/** `TDbFieldMeta.computed` of a top-level `@db.compute` view field (since 0.1.147). */
+function computedMeta(rootType, path) {
+	if (path.includes(".")) return void 0;
+	const computed = computedOperands(rootType, path);
+	return computed ? {
+		operands: Object.freeze(computed.operands),
+		via: Object.freeze(computed.via)
+	} : void 0;
+}
+//#endregion
+//#region src/query/aggregate-expr.ts
+/** Most nodes a group-level expression may have once the aliases it names are inlined (SQL repeats them). */
+const EXPANDED_MAX_NODES = 4 * ARITH_MAX_NODES;
+/** Most expanded nodes ALL the expression entries of one query may have together. */
+const QUERY_EXPANDED_MAX_NODES = 1024;
+/**
+* Why a field cannot be an arithmetic operand, or `undefined` when it can: it
+* must be a `number` (not a decimal — those are exact, an expression is IEEE
+* double — and not a timestamp-tagged number) with plain column storage. The
+* runtime twin of `@db.compute`'s operand rule, so declared and query-time
+* arithmetic accept the same fields.
+*
+* @since 0.1.148
+*/
+function numericOperandProblem(fd) {
+	if (fd.encrypted) return "is encrypted";
+	if (isJsonValueField(fd)) return "is not a scalar number";
+	return numericTypeProblem({
+		base: fd.designType,
+		tags: (fd.type?.type)?.tags
+	});
+}
+/**
+* Converts uniqu's JSON arithmetic into the `@db.compute` expression tree
+* the SQL / MongoDB / memory renderers consume: a name becomes a
+* `{ field }` leaf, unary `-` becomes `neg`. `rename` maps each name (the
+* mapper makes row-level names physical; group-level names stay aliases).
+*
+* @since 0.1.148
+*/
+function arithToExprNode(expr, rename = (n) => n) {
+	if (typeof expr === "number") return expr;
+	if (typeof expr === "string") return { field: rename(expr) };
+	const args = expr.$args.map((a) => arithToExprNode(a, rename));
+	if (expr.$op === "-" && args.length === 1) return {
+		op: "neg",
+		args: [args[0]]
+	};
+	if (expr.$op === "coalesce") return {
+		op: "coalesce",
+		args
+	};
+	return {
+		op: expr.$op,
+		args: [args[0], args[1]]
+	};
+}
+/**
+* The names an expression reads, found iteratively and bounded: this runs on
+* a raw, not yet validated expression (a 10k-deep chain must not overflow the
+* stack — `normalizeComputedSelect` rejects it afterwards). Stops after
+* {@link EXPANDED_MAX_NODES} nodes: the shape rules reject anything larger later.
+* (`@uniqu/core`'s `arithNames` is iterative too but unbounded, so it is not used here.)
+*/
+function boundedArithNames(expr) {
+	const out = /* @__PURE__ */ new Set();
+	const stack = [expr];
+	for (let visited = 0; stack.length > 0 && visited < EXPANDED_MAX_NODES; visited++) {
+		const e = stack.pop();
+		if (typeof e === "string") out.add(e);
+		else if (e && typeof e === "object" && Array.isArray(e.$args)) {
+			const args = e.$args;
+			for (let i = args.length - 1; i >= 0; i--) stack.push(args[i]);
+		}
+	}
+	return [...out];
+}
+/**
+* The field paths a `$select` entry reads from the table's rows: a plain
+* field, an aggregate's `$field` (`*` excluded), a row-level expression's
+* names, a calendar bucket's source. A group-level expression contributes
+* none (its names are aliases).
+*/
+function entryFields(item) {
+	if (typeof item === "string") return [item];
+	if (isAggregateExpr(item)) return item.$field === "*" ? [] : [item.$field];
+	if (isAggregateOfExpr(item)) return boundedArithNames(item.$expr);
+	if (isBucketExpr(item)) return [item.$field];
+	return [];
+}
+/** Keys of a `$rowOrder` control (the raw object), or `[]`. */
+function rowOrderKeys(rowOrder) {
+	return rowOrder && typeof rowOrder === "object" ? Object.keys(rowOrder) : [];
+}
+/**
+* Schema-dependent rules of query-time arithmetic and `first` / `last`, after
+* the shape normalizer and the path guard:
+*
+* - every row-level operand and every group-level operand that is a `$groupBy`
+*   field is a numeric field ({@link numericOperandProblem});
+* - every group-level operand that is a `$select` alias is numeric: counts and
+*   expressions always, `sum` / `avg` / `min` / `max` / `first` / `last` when
+*   their `$field` is;
+* - a `first` / `last` field is a scalar (no JSON value or array);
+* - in a strict (dimension / measure) table row-level operands are measures and
+*   `$rowOrder` keys are dimensions or measures (a `first` / `last` field
+*   follows the aggregate rule in `aggregate()`);
+* - an operand or `first` / `last` field tagged with a quantity ref needs that
+*   ref in `$groupBy`;
+* - a group-level expression stays within {@link EXPANDED_MAX_NODES} once the
+*   aliases it names are inlined (SQL repeats them at every use), and all the
+*   expression entries of the query together within {@link QUERY_EXPANDED_MAX_NODES}.
+*
+* Unknown fields are the path guard's, so they are skipped here.
+*
+* @throws DbError `INVALID_QUERY` with every issue.
+* @since 0.1.148
+*/
+function checkAggregateExprs(meta, query, exprs, rowOrder) {
+	const select = query.controls.$select;
+	if (!Array.isArray(select)) return;
+	const issues = [];
+	const fdOf = (name) => meta.descriptorByPath.get(name);
+	const numericField = (name) => {
+		const fd = fdOf(name);
+		return fd === void 0 || numericOperandProblem(fd) === void 0;
+	};
+	const operandIssue = (name) => {
+		if (!numericField(name)) issues.push({
+			path: "$select",
+			message: `Field "${name}" is not numeric — arithmetic needs a number field (not decimal, timestamp or text)`
+		});
+	};
+	const numericAlias = /* @__PURE__ */ new Map();
+	for (const item of select) if (isAggregateExpr(item)) {
+		const counts = item.$fn === "count" || item.$fn === "countDistinct";
+		numericAlias.set(resolveAlias(item), counts || numericField(item.$field));
+	} else if (isAggregateOfExpr(item) || isSelectArithExpr(item)) numericAlias.set(item.$as, true);
+	const strict = meta.dimensions.length > 0 || meta.measures.length > 0;
+	const groupBy = new Set(query.controls.$groupBy);
+	const refGroup = (label, field) => {
+		const ref = meta.quantityRefByField.get(field);
+		if (ref && !groupBy.has(ref)) issues.push({
+			path: "$select",
+			message: `${label} requires "${ref}" in $groupBy — quantity-ref-tagged fields must be grouped by their dimension`
+		});
+	};
+	for (const e of exprs) {
+		if (e.level === "row") {
+			for (const name of e.names) {
+				operandIssue(name);
+				if (strict && fdOf(name) && !meta.measures.includes(name)) issues.push({
+					path: "$select",
+					message: `Expression operand "${name}" is not a measure`
+				});
+				refGroup(`Expression "${e.alias}"`, name);
+			}
+			continue;
+		}
+		for (const name of e.names) if (numericAlias.has(name)) {
+			if (numericAlias.get(name) === false) issues.push({
+				path: "$select",
+				message: `"${name}" is not numeric and cannot be used in an expression`
+			});
+		} else operandIssue(name);
+	}
+	for (const item of select) {
+		if (!isFirstLast(item)) continue;
+		const fd = fdOf(item.$field);
+		if (fd && (isJsonValueField(fd) || fd.designType === "array")) issues.push({
+			path: "$select",
+			message: `${item.$fn}("${item.$field}") needs a scalar field — not a JSON value or array`
+		});
+	}
+	for (const key of rowOrder ?? []) if (strict && fdOf(key.field) && !meta.dimensions.includes(key.field) && !meta.measures.includes(key.field)) issues.push({
+		path: "$rowOrder",
+		message: `$rowOrder field "${key.field}" is not a dimension or measure`
+	});
+	const expanded = /* @__PURE__ */ new Map();
+	const countNodes = (expr) => typeof expr === "number" ? 1 : typeof expr === "string" ? expanded.get(expr) ?? 1 : 1 + expr.$args.reduce((sum, arg) => sum + countNodes(arg), 0);
+	let total = 0;
+	const issuesBeforeSize = issues.length;
+	for (const e of exprs) {
+		const size = countNodes(e.expr);
+		expanded.set(e.alias, size);
+		total += size;
+		if (size > EXPANDED_MAX_NODES) issues.push({
+			path: "$select",
+			message: `Expression "${e.alias}" is too large once its aliases are expanded (more than ${EXPANDED_MAX_NODES} nodes)`
+		});
+	}
+	if (total > 1024 && issues.length === issuesBeforeSize) issues.push({
+		path: "$select",
+		message: `The expressions of this query are too large together (more than ${QUERY_EXPANDED_MAX_NODES} nodes once their aliases are expanded)`
+	});
+	if (issues.length) throw new DbError("INVALID_QUERY", issues);
+}
 //#endregion
 //#region src/query/uniqu-select.ts
 /**
@@ -1084,8 +1353,9 @@ var TableMetadata = class {
 * For exclusion → inclusion inversion, pass `allFields` (physical field names).
 *
 * An array `$select` holds plain field names and computed entries —
-* aggregates (`{ $fn, $field }`, {@link aggregates}) and calendar buckets
-* (`{ $bucket, $field }`, {@link buckets}). Entries arrive normalized
+* aggregates (`{ $fn, $field }`, {@link aggregates}), `first` / `last`
+* ({@link firstLast}), arithmetic ({@link exprAggregates}, {@link exprs}) and
+* calendar buckets (`{ $bucket, $field }`, {@link buckets}). Entries arrive normalized
 * (`normalizeComputedSelect` rejects any other shape before translation).
 */
 var UniquSelect = class UniquSelect {
@@ -1094,7 +1364,6 @@ var UniquSelect = class UniquSelect {
 	_allFields;
 	_array = UniquSelect.UNRESOLVED;
 	_projection = UniquSelect.UNRESOLVED;
-	_aggregates = UniquSelect.UNRESOLVED;
 	/**
 	* The calendar buckets of an aggregate `$select`, normalized (canonical
 	* zone, week start, alias) with the PHYSICAL source `field` and its
@@ -1104,16 +1373,80 @@ var UniquSelect = class UniquSelect {
 	*/
 	buckets;
 	/**
+	* The plain aggregates (`{ $fn, $field }`) of an array-form `$select`;
+	* `undefined` when there are none or the `$select` is object form.
+	* `first` / `last` are listed separately ({@link firstLast}), so an adapter
+	* written before them never meets one here.
+	*/
+	aggregates;
+	/** The `first` / `last` entries of an array-form `$select` (since 0.1.148); `undefined` when none. */
+	firstLast;
+	/**
+	* Row-level expression aggregates (`sum(price*qty)`) — leaves are physical
+	* columns; render `fn(<expr>)` per row. `undefined` when there are none.
+	* Only reaches adapters whose `supportsAggregateExpressions()` is true.
+	* Since 0.1.148.
+	*/
+	exprAggregates;
+	/**
+	* Group-level expressions in dependency order: each leaf names an alias
+	* defined by an aggregate / `first` / `last` / expression entry or a
+	* grouped column; evaluate after grouping. `undefined` when there are none.
+	* Since 0.1.148.
+	*/
+	exprs;
+	/**
+	* The order of the rows inside each group that `first` / `last` read, as
+	* physical columns, with the primary key appended as the final ascending
+	* tie-break. `undefined` without `first` / `last`. Since 0.1.148.
+	*/
+	rowOrder;
+	/**
+	* The descriptors of the PHYSICAL columns a `min` / `max` / `first` / `last`
+	* reads — for an engine that cannot aggregate a type directly (PostgreSQL
+	* has no `MIN(boolean)`). Since 0.1.148.
+	*/
+	sources;
+	/**
+	* The output alias of every computed entry but the calendar buckets, in the
+	* order adapters emit them: {@link aggregates}, {@link exprAggregates},
+	* {@link firstLast}, then {@link exprs} (which read the others). Since 0.1.148.
+	*/
+	computedAliases;
+	/**
 	* @param raw - the `$select` value (field paths already physical).
 	* @param allFields - physical field names, for exclusion-form inversion.
 	* @param buckets - the resolved calendar buckets of the raw `$select`'s
 	*   `{ $bucket }` entries (the field mappers supply them — physical `field`,
 	*   source `fd`).
+	* @param computed - the resolved arithmetic and `$rowOrder` parts (physical).
 	*/
-	constructor(raw, allFields, buckets) {
+	constructor(raw, allFields, buckets, computed) {
 		this._raw = raw;
 		this._allFields = allFields;
 		this.buckets = buckets?.length ? buckets : void 0;
+		this.exprAggregates = computed?.exprAggregates?.length ? computed.exprAggregates : void 0;
+		this.exprs = computed?.exprs?.length ? computed.exprs : void 0;
+		this.rowOrder = computed?.rowOrder?.length ? computed.rowOrder : void 0;
+		this.sources = computed?.sources ?? /* @__PURE__ */ new Map();
+		const aggregates = [];
+		const firstLast = [];
+		if (Array.isArray(raw)) {
+			for (const item of raw) if (isFirstLast(item)) firstLast.push({
+				fn: item.$fn,
+				column: item.$field,
+				alias: resolveAlias(item)
+			});
+			else if (isAggregateExpr(item)) aggregates.push(item);
+		}
+		this.aggregates = aggregates.length > 0 ? aggregates : void 0;
+		this.firstLast = firstLast.length > 0 ? firstLast : void 0;
+		this.computedAliases = [
+			...aggregates.map((expr) => resolveAlias(expr)),
+			...(this.exprAggregates ?? []).map((e) => e.alias),
+			...firstLast.map((fl) => fl.alias),
+			...(this.exprs ?? []).map((e) => e.alias)
+		];
 	}
 	/**
 	* Resolved inclusion array of plain field names (strings only).
@@ -1162,20 +1495,6 @@ var UniquSelect = class UniquSelect {
 		this._projection = result;
 		return this._projection;
 	}
-	/**
-	* Extracts AggregateExpr entries from array-form $select.
-	* Returns undefined if no aggregates present or if $select is object form.
-	*/
-	get aggregates() {
-		if (this._aggregates !== UniquSelect.UNRESOLVED) return this._aggregates;
-		if (!Array.isArray(this._raw)) {
-			this._aggregates = void 0;
-			return;
-		}
-		const aggs = this._raw.filter(isAggregateExpr);
-		this._aggregates = aggs.length > 0 ? aggs : void 0;
-		return this._aggregates;
-	}
 	/** Whether the $select contains any AggregateExpr entries. */
 	get hasAggregates() {
 		return !!this.aggregates?.length;
@@ -1265,6 +1584,15 @@ function toBool(value) {
 	if (value === null || value === void 0) return value;
 	return !!value;
 }
+/**
+* Coerces the computed aliases of aggregate rows (`min` / `max` / `first` /
+* `last` of one boolean or decimal field) the way a column of that type is
+* coerced on read — the row reverse path cannot, as an alias is no column.
+* @since 0.1.148
+*/
+function coerceAliasValues(rows, aliases) {
+	for (const row of rows) for (const [alias, fd] of aliases) if (alias in row) row[alias] = fd.designType === "boolean" ? toBool(row[alias]) : toDecimalString(row[alias]);
+}
 function toDecimalString(value) {
 	if (value === null || value === void 0) return value;
 	if (typeof value === "string") return value;
@@ -1303,9 +1631,13 @@ var FieldMappingStrategy = class {
 	* `buckets` are the query's calendar buckets as the core's normalizer
 	* resolved them (`normalizeComputedSelect` — `AtscriptDbReadable.aggregate`
 	* runs it before the guards); they reach adapters with `field` made
-	* physical and the source descriptor as `fd`.
+	* physical and the source descriptor as `fd`. `exprs` / `rowOrder` are the
+	* arithmetic entries and `$rowOrder` keys of the same normalizer
+	* (`resolveComputedSelect`): they reach adapters as `$select.exprAggregates`
+	* / `.exprs` / `.rowOrder` with physical names (the primary key appended to
+	* the order); `$rowOrder` itself is not forwarded (since 0.1.148).
 	*/
-	translateAggregateQuery(query, meta, buckets) {
+	translateAggregateQuery(query, meta, buckets, exprs = [], rowOrder) {
 		const controls = query.controls;
 		const aliases = this.computedAliasSet(controls.$select);
 		const physicalBuckets = buckets.map((b) => ({
@@ -1314,26 +1646,102 @@ var FieldMappingStrategy = class {
 			fd: meta.descriptorByPath.get(b.field)
 		}));
 		const select = controls.$select && this.physicalSelect(controls.$select, meta);
+		const computed = this.physicalComputed(meta, aliases, exprs, rowOrder, controls.$select);
 		return {
 			filter: this.translateFilter(query.filter ?? {}, meta),
 			controls: {
 				...controls,
 				$with: void 0,
+				$rowOrder: void 0,
 				$groupBy: this.renamesPaths(meta) ? controls.$groupBy.map((key) => aliases.has(key) ? key : this.physicalPath(key, meta)) : controls.$groupBy,
-				$select: select ? new UniquSelect(select, meta.allPhysicalFields, physicalBuckets) : void 0,
+				$select: select ? new UniquSelect(select, meta.allPhysicalFields, physicalBuckets, computed) : void 0,
 				$sort: controls.$sort && this.physicalSort(controls.$sort, meta, aliases),
-				$having: controls.$having ? this.translateFilter(controls.$having, meta) : void 0
+				$having: controls.$having ? this.translateHaving(controls.$having, meta, aliases) : void 0
 			},
 			insights: query.insights
 		};
 	}
-	/** Output aliases of the computed `$select` entries (aggregates and calendar buckets). */
+	/**
+	* `$having` with physical keys — except the computed output `aliases`,
+	* which stay as written (an alias equal to a renamed field's name,
+	* `first(raisedAt):raisedAt`, is the alias, exactly as in `$sort`).
+	*/
+	translateHaving(having, meta, aliases) {
+		if (aliases.size === 0 || !having || typeof having !== "object") return this.translateFilter(having, meta);
+		const out = {};
+		const fields = {};
+		for (const [key, value] of Object.entries(having)) if (key === "$and" || key === "$or") out[key] = value.map((f) => this.translateHaving(f, meta, aliases));
+		else if (key === "$not") out[key] = this.translateHaving(value, meta, aliases);
+		else if (aliases.has(key)) out[key] = value;
+		else fields[key] = value;
+		return Object.keys(fields).length > 0 ? {
+			...out,
+			...this.translateFilter(fields, meta)
+		} : out;
+	}
+	/** Output aliases of the computed `$select` entries (aggregates, expressions and calendar buckets). */
 	computedAliasSet(select) {
 		const aliases = /* @__PURE__ */ new Set();
-		for (const item of select ?? []) if (isAggregateExpr(item) || isBucketExpr(item)) aliases.add(resolveAlias(item));
+		for (const item of select ?? []) if (isAggregateExpr(item) || isBucketExpr(item)) aliases.add(resolveAlias$1(item));
+		else if (isAggregateOfExpr(item) || isSelectArithExpr(item)) aliases.add(item.$as);
 		return aliases;
 	}
 	/**
+	* The arithmetic and `$rowOrder` parts of a grouped query with PHYSICAL
+	* names: a row-level operand is a column; a group-level operand stays an
+	* alias, or becomes the physical name of a `$groupBy` field. The primary
+	* key is appended to the order as the final ascending tie-break.
+	*/
+	physicalComputed(meta, aliases, exprs, rowOrder, select) {
+		const sources = /* @__PURE__ */ new Map();
+		for (const item of select ?? []) {
+			if (!isAggregateExpr(item) || !SOURCE_VALUE_FNS.has(item.$fn)) continue;
+			const fd = meta.descriptorByPath.get(item.$field);
+			if (fd) sources.set(this.physicalPath(item.$field, meta), fd);
+		}
+		const exprAggregates = [];
+		const groupExprs = [];
+		for (const e of exprs) {
+			const names = /* @__PURE__ */ new Set();
+			const node = arithToExprNode(e.expr, (name) => {
+				const resolved = e.level === "group" && aliases.has(name) ? name : this.physicalPath(name, meta);
+				names.add(resolved);
+				return resolved;
+			});
+			if (e.level === "row") exprAggregates.push({
+				fn: e.fn,
+				alias: e.alias,
+				expr: node,
+				names: [...names]
+			});
+			else groupExprs.push({
+				alias: e.alias,
+				expr: node,
+				names: [...names]
+			});
+		}
+		let order;
+		if (rowOrder?.length) {
+			order = rowOrder.map((k) => ({
+				column: this.physicalPath(k.field, meta),
+				desc: k.desc
+			}));
+			for (const pk of meta.primaryKeys) {
+				const column = this.physicalPath(pk, meta);
+				if (!order.some((k) => k.column === column)) order.push({
+					column,
+					desc: false
+				});
+			}
+		}
+		return {
+			exprAggregates,
+			exprs: groupExprs,
+			rowOrder: order,
+			sources
+		};
+	}
+	/**
 	* `$select` with its field paths made physical: array-form names and
 	* computed `$field`s (`'*'` kept), or the keys of the object
 	* (inclusion / exclusion) form. An aggregate's output alias is fixed
@@ -1351,7 +1759,7 @@ var FieldMappingStrategy = class {
 				if (physical === item.$field) return item;
 				return isAggregateExpr(item) ? {
 					...item,
-					$as: resolveAlias(item),
+					$as: resolveAlias$1(item),
 					$field: physical
 				} : {
 					...item,
@@ -1372,19 +1780,43 @@ var FieldMappingStrategy = class {
 		return translated;
 	}
 	/**
-	* Recursively walks a filter expression, applying `@db.column` key renames
-	* (document paths — {@link TableMetadata.documentPath}) and adapter-specific
-	* value formatting via `formatFilterValue`.
+	* Translates a logical filter for the adapter: relational predicates are
+	* resolved first (`resolveRelationFilterTree`), then every key and value
+	* goes through {@link translateResolvedFilter}. `depth` is the predicate
+	* level of `filter` itself (0 for a query's own filter; the related tables
+	* translate predicate operands at deeper levels).
+	*/
+	translateFilter(filter, meta, depth = 0) {
+		const has = containsRelationFilter(filter);
+		const resolved = has ? resolveRelationFilterTree(filter, meta, depth) : filter;
+		return this.noteTranslated(filter, this.translateResolvedFilter(resolved, meta), has);
+	}
+	/**
+	* `out` — the translation of the caller's `filter` — with its pre-scan
+	* result (`has`) cached for the adapter's repeated `containsRelationFilter`
+	* checks; only when the core built it (never the caller's own object).
+	*/
+	noteTranslated(filter, out, has) {
+		if (out !== filter) noteRelationFilter(out, has);
+		return out;
+	}
+	/**
+	* Recursively walks a filter expression (predicates already resolved),
+	* applying `@db.column` key renames (document paths —
+	* {@link TableMetadata.documentPath}) and adapter-specific value formatting
+	* via `formatFilterValue`. A resolved predicate passes through under its
+	* navigation-field key.
 	*
 	* The relational mapper overrides this to use `leafByLogical` for deeper
 	* key resolution (flattened nested paths).
 	*/
-	translateFilter(filter, meta) {
+	translateResolvedFilter(filter, meta) {
 		if (!filter || typeof filter !== "object") return filter;
 		if (!meta.toStorageFormatters && meta.columnMap.size === 0 && meta.derivedFields.size === 0) return filter;
 		const result = {};
-		for (const [key, value] of Object.entries(filter)) if (key === "$and" || key === "$or") result[key] = value.map((f) => this.translateFilter(f, meta));
-		else if (key === "$not") result[key] = this.translateFilter(value, meta);
+		for (const [key, value] of Object.entries(filter)) if (key === "$and" || key === "$or") result[key] = value.map((f) => this.translateResolvedFilter(f, meta));
+		else if (key === "$not") result[key] = this.translateResolvedFilter(value, meta);
+		else if (meta.navFields.has(key)) result[key] = value;
 		else if (key.startsWith("$")) result[key] = value;
 		else {
 			const physical = this.physicalPath(key, meta);
@@ -1686,10 +2118,13 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 		return result;
 	}
 	translateQuery(query, meta) {
+		const logical = query.filter;
+		const has = containsRelationFilter(logical);
+		const filter = has ? resolveRelationFilterTree(logical, meta, 0) : logical;
 		if (!meta.requiresMappings) {
 			const controls = query.controls;
 			return {
-				filter: meta.toStorageFormatters ? this.translateFilter(query.filter, meta) : query.filter,
+				filter: meta.toStorageFormatters ? this.noteTranslated(logical, this.translateResolvedFilter(filter, meta), has) : filter,
 				controls: {
 					...controls,
 					$with: void 0,
@@ -1699,7 +2134,7 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 			};
 		}
 		return {
-			filter: this.translateFilterWithRename(query.filter, meta),
+			filter: this.noteTranslated(logical, this.translateFilterWithRename(filter, meta), has),
 			controls: query.controls ? this.translateControls(query.controls, meta) : {},
 			insights: query.insights
 		};
@@ -1709,10 +2144,10 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 		return meta.leafByLogical.get(logical)?.physicalName ?? logical;
 	}
 	/**
-	* Overrides the base `translateFilter` to use `leafByLogical` for key resolution
+	* Overrides the base `translateResolvedFilter` to use `leafByLogical` for key resolution
 	* (handles flattened nested paths like `contact.email` → `contact__email`).
 	*/
-	translateFilter(filter, meta) {
+	translateResolvedFilter(filter, meta) {
 		if (!filter || typeof filter !== "object") return filter;
 		if (!meta.requiresMappings && !meta.toStorageFormatters) return filter;
 		return this.translateFilterWithRename(filter, meta);
@@ -1720,13 +2155,16 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 	/**
 	* Translates filter with key renaming from logical to physical names.
 	* Used by the relational query path where field paths must be mapped
-	* to `__`-separated column names.
+	* to `__`-separated column names. Relational predicates must already be
+	* resolved (`translateFilter` / `translateQuery` do it); a resolved
+	* predicate passes through under its navigation-field key.
 	*/
 	translateFilterWithRename(filter, meta) {
 		if (!filter || typeof filter !== "object") return filter;
 		const result = {};
 		for (const [key, value] of Object.entries(filter)) if (key === "$and" || key === "$or") result[key] = value.map((f) => this.translateFilterWithRename(f, meta));
 		else if (key === "$not") result[key] = this.translateFilterWithRename(value, meta);
+		else if (meta.navFields.has(key)) result[key] = value;
 		else if (key.startsWith("$")) result[key] = value;
 		else {
 			const physical = meta.leafByLogical.get(key)?.physicalName ?? key;
@@ -1856,6 +2294,236 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 	}
 };
 //#endregion
+//#region src/query/filter-values.ts
+const OPAQUE = {
+	kinds: new Set(["any"]),
+	timestamp: false
+};
+const NUMBER = {
+	kinds: new Set(["number"]),
+	timestamp: false
+};
+const INTEGER = {
+	kinds: new Set(["integer"]),
+	timestamp: false
+};
+const STRING = {
+	kinds: new Set(["string"]),
+	timestamp: false
+};
+function collectKinds(type, kinds, out, depth = 0) {
+	const def = type?.type;
+	const metadata = type?.metadata;
+	if (!def || depth > 8) {
+		kinds.add("any");
+		return;
+	}
+	switch (def.kind) {
+		case "": switch (def.designType) {
+			case "string":
+				kinds.add("string");
+				return;
+			case "number": {
+				const timestamp = def.tags?.has("timestamp") === true;
+				if (timestamp) out.timestamp = true;
+				const integer = timestamp || def.tags?.has("int") === true || metadata?.has?.("expect.int") === true;
+				kinds.add(integer ? "integer" : "number");
+				return;
+			}
+			case "decimal":
+				kinds.add("decimal");
+				return;
+			case "boolean":
+				kinds.add("boolean");
+				return;
+			case "null":
+			case "undefined":
+			case "never": return;
+			default:
+				kinds.add("any");
+				return;
+		}
+		case "union":
+			for (const item of def.items ?? []) collectKinds(item, kinds, out, depth + 1);
+			return;
+		case "array":
+			collectKinds(def.of, kinds, out, depth + 1);
+			return;
+		default: kinds.add("any");
+	}
+}
+const typeCache = /* @__PURE__ */ new WeakMap();
+/**
+* The value kinds a filter on `fd` accepts (cached per descriptor). A leaf
+* inside a JSON value (a `@db.json` object or an array, addressable on
+* nested-object adapters) is opaque: its contents are not schema-enforced.
+*/
+function valueTypeOf(meta, fd) {
+	let vt = typeCache.get(fd);
+	if (vt) return vt;
+	if (jsonValueAncestor(fd.path, meta.jsonValueParents) !== void 0 || fd.encrypted || fd.isGeoPoint || fd.designType === "json" || fd.designType === "object" || !fd.type) vt = OPAQUE;
+	else {
+		const kinds = /* @__PURE__ */ new Set();
+		const out = { timestamp: false };
+		collectKinds(fd.type, kinds, out);
+		const metadata = fd.type.metadata;
+		if ((fd.defaultValue?.kind === "fn" && fd.defaultValue.fn !== "uuid" || metadata?.has?.("db.agg.count") === true || metadata?.has?.("db.agg.countDistinct") === true) && kinds.delete("number")) kinds.add("integer");
+		vt = kinds.size === 0 ? OPAQUE : {
+			kinds,
+			timestamp: out.timestamp
+		};
+	}
+	typeCache.set(fd, vt);
+	return vt;
+}
+/** A decimal literal (`5`, `-1.5`, `.5`, `1e3`), surrounding blanks allowed — no hex, no `Infinity`. */
+const NUMERIC_RE = /^\s*[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?\s*$/i;
+/** An integer literal (`5`, `-12`), surrounding blanks allowed. */
+const INTEGER_RE = /^\s*[+-]?\d+\s*$/;
+function acceptsScalar(kind, value) {
+	switch (kind) {
+		case "any": return true;
+		case "string": return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint";
+		case "number":
+		case "decimal": return typeof value === "number" && Number.isFinite(value) || typeof value === "bigint" || typeof value === "string" && NUMERIC_RE.test(value);
+		case "integer": return typeof value === "number" && Number.isInteger(value) || typeof value === "bigint" || typeof value === "string" && INTEGER_RE.test(value);
+		default: return typeof value === "boolean" || value === 0 || value === 1;
+	}
+}
+/** The first element of `value` (itself when not an array) `vt` rejects, or `undefined`. */
+function rejectedValue(vt, value) {
+	if (vt.kinds.has("any") || value === null || value === void 0) return void 0;
+	if (Array.isArray(value)) {
+		for (const item of value) {
+			const bad = rejectedValue(vt, item);
+			if (bad) return bad;
+		}
+		return;
+	}
+	if (typeof value === "object" && !isPlainObject(value)) return void 0;
+	for (const kind of vt.kinds) if (acceptsScalar(kind, value)) return void 0;
+	return { value };
+}
+const KIND_LABEL = {
+	string: "a string",
+	number: "a number",
+	integer: "an integer",
+	decimal: "a decimal (number or numeric string)",
+	boolean: "a boolean"
+};
+function expectedOf(vt) {
+	const labels = [];
+	for (const kind of vt.kinds) {
+		if (kind === "any") continue;
+		labels.push(kind === "integer" && vt.timestamp ? "an integer (epoch milliseconds)" : KIND_LABEL[kind]);
+	}
+	return labels.join(" or ");
+}
+function describeValue(value) {
+	if (typeof value === "string") return JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}…` : value);
+	if (isPlainObject(value)) return "an object";
+	return String(value);
+}
+function valueError(path, op, message) {
+	return new DbError("INVALID_QUERY", [{
+		path,
+		message: `Invalid filter value for "${path}"${op ? ` (${op})` : ""}: ${message}`
+	}]);
+}
+function holdsStrings(vt) {
+	return vt.kinds.has("string") || vt.kinds.has("any");
+}
+function checkRegex(path, vt, op, pattern) {
+	if (!holdsStrings(vt)) throw valueError(path, op, `a pattern match needs a string field, "${path}" holds ${expectedOf(vt)}`);
+	if (typeof pattern !== "string" && !(pattern instanceof RegExp)) throw valueError(path, op, `expected a regular expression, got ${describeValue(pattern)}`);
+}
+function checkValue(path, vt, op, value) {
+	if (value instanceof RegExp) {
+		checkRegex(path, vt, op ?? "RegExp", value);
+		return;
+	}
+	const bad = rejectedValue(vt, value);
+	if (bad) throw valueError(path, op, `expected ${expectedOf(vt)}, got ${describeValue(bad.value)}`);
+}
+/** Operators whose operand is compared with the field's values. */
+const COMPARE_OPS = new Set([
+	"$eq",
+	"$ne",
+	"$gt",
+	"$gte",
+	"$lt",
+	"$lte",
+	"$in",
+	"$nin"
+]);
+/** Checks one filter entry's value (a bare value or an operator map) against `vt`. */
+function checkEntry(path, vt, value) {
+	if (vt.kinds.has("any")) return;
+	if (!isPlainObject(value)) {
+		checkValue(path, vt, void 0, value);
+		return;
+	}
+	for (const [op, operand] of Object.entries(value)) if (op === "$regex") checkRegex(path, vt, op, operand);
+	else if (COMPARE_OPS.has(op)) checkValue(path, vt, op, operand);
+}
+/**
+* Walks `filter` (through `$and` / `$or` / `$not`; relational predicates are
+* the related table's) and checks every entry whose key `typeOf` knows.
+*/
+function walkFilterValues(filter, typeOf) {
+	if (!isPlainObject(filter)) return;
+	for (const [key, value] of Object.entries(filter)) {
+		if (key === "$and" || key === "$or") {
+			if (Array.isArray(value)) for (const child of value) walkFilterValues(child, typeOf);
+			continue;
+		}
+		if (key === "$not") {
+			walkFilterValues(value, typeOf);
+			continue;
+		}
+		if (key.startsWith("$") || hasRelationOp(value)) continue;
+		const vt = typeOf(key);
+		if (vt) checkEntry(key, vt, value);
+	}
+}
+/**
+* Rejects (`INVALID_QUERY`, `path` = the field) a filter value that cannot
+* denote its field's declared type — see the module notes for the accepted
+* forms. Unknown paths are skipped (the path guard owns them).
+*/
+function guardFilterValues(meta, filter) {
+	if (!filter) return;
+	walkFilterValues(filter, (key) => {
+		const fd = meta.descriptorByPath.get(key);
+		return fd ? valueTypeOf(meta, fd) : void 0;
+	});
+}
+/**
+* `$having` values: an aggregate alias is a number (`count`,
+* `countDistinct`, `sum`, `avg`, an expression) or its source field's type
+* (`min` / `max`, `first` / `last`),
+* a calendar-bucket alias a string label, any other key a `$groupBy`
+* field's own type.
+*/
+function guardHavingValues(meta, controls) {
+	if (!controls?.$having) return;
+	const aliases = /* @__PURE__ */ new Map();
+	if (Array.isArray(controls.$select)) {
+		for (const item of controls.$select) if (isAggregateOfExpr(item) || isSelectArithExpr(item)) aliases.set(item.$as, NUMBER);
+		else if (isAggregateExpr(item)) {
+			const fd = SOURCE_VALUE_FNS.has(item.$fn) ? meta.descriptorByPath.get(item.$field) : void 0;
+			const counts = item.$fn === "count" || item.$fn === "countDistinct";
+			aliases.set(resolveAlias$1(item), fd ? valueTypeOf(meta, fd) : counts ? INTEGER : NUMBER);
+		} else if (isBucketExpr(item)) aliases.set(resolveAlias$1(item), STRING);
+	}
+	walkFilterValues(controls.$having, (key) => {
+		const alias = aliases.get(key);
+		if (alias) return alias;
+		const fd = meta.descriptorByPath.get(key);
+		return fd ? valueTypeOf(meta, fd) : void 0;
+	});
+}
+//#endregion
 //#region src/query/query-guards.ts
 /**
 * Engine-agnostic query-time guards, applied in the core layer BEFORE filter
@@ -1882,6 +2550,9 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 *   {@link canFilterLeaf}) needs → `INVALID_QUERY` (see {@link guardPaths}).
 *   Runs after the checks above so `ENC_*` codes keep firing first for
 *   encrypted subtrees.
+* - every filter / `$having` comparison value must be able to denote its
+*   field's declared type (`?n='x'` on a number) → `INVALID_QUERY`, after
+*   the path guard (see `guardFilterValues`, since 0.1.147).
 */
 /** Validates a `[lng, lat]` tuple (GeoJSON coordinate order). */
 function assertGeoPoint(point, path) {
@@ -1938,6 +2609,10 @@ function guardFilter(meta, adapter, filter, encCode = "ENC_FIELD_FILTER") {
 			continue;
 		}
 		if (key.startsWith("$")) continue;
+		if (hasRelationOp(value)) {
+			guardRelationOperands(key, value);
+			continue;
+		}
 		if (hasEncrypted && isEncryptedRef(meta, key)) throw encryptedRefError(encCode, key, "filter on");
 		if (!isPrimitive(value)) {
 			for (const [op, opValue] of Object.entries(value)) if (op === "$geoWithin") guardGeoWithin(meta, adapter, key, opValue);
@@ -1948,6 +2623,23 @@ function guardFilter(meta, adapter, filter, encCode = "ENC_FIELD_FILTER") {
 		}
 	}
 }
+/**
+* Shape rules of a relational predicate's operator map: only `$some` /
+* `$none` (never mixed with comparison operators), each operand a filter
+* object.
+*/
+function guardRelationOperands(key, ops) {
+	for (const [op, operand] of Object.entries(ops)) {
+		if (!isRelationOp(op)) throw new DbError("INVALID_QUERY", [{
+			path: key,
+			message: `Cannot mix "$some" / "$none" with "${op}" on "${key}"`
+		}]);
+		if (!isPlainObject(operand)) throw new DbError("INVALID_QUERY", [{
+			path: key,
+			message: `"${op}" on "${key}" expects a filter object`
+		}]);
+	}
+}
 /** Rejects `$sort` keys referencing encrypted fields. */
 function guardSort(meta, sort) {
 	if (!sort || typeof sort !== "object" || meta.encryptedFields.size === 0) return;
@@ -2021,8 +2713,18 @@ function filterPredicateOf(value) {
 	const ops = value;
 	if ("$geoWithin" in ops) return "geo";
 	const keys = Object.keys(ops);
+	if (keys.length > 0 && keys.every(isRelationOp)) return "relation";
 	return keys.length === 1 && keys[0] === "$exists" ? "exists" : "compare";
 }
+/** The `{ op, filter }` list of a `relation` entry's operator map. */
+function relationOpsOf(value) {
+	const out = [];
+	for (const [op, filter] of Object.entries(value)) if (isRelationOp(op)) out.push({
+		op,
+		filter
+	});
+	return out;
+}
 /**
 * Whether a stored leaf physically supports a filter predicate of this class
 * — the one rule the core path guard and moost-db's HTTP capability index
@@ -2039,6 +2741,7 @@ function filterPredicateOf(value) {
 function canFilterLeaf(fd, predicate, adapter) {
 	if (fd.encrypted) return false;
 	switch (predicate) {
+		case "relation": return false;
 		case "exists": return true;
 		case "geo": return fd.isGeoPoint === true && adapter.isGeoSearchable();
 		default: return adapter.canFilterField(fd);
@@ -2074,6 +2777,37 @@ function rejectSource(code, reason) {
 	};
 }
 /**
+* Whether the stored leaf `fd` may be a `$groupBy` key (since 0.1.148) — the
+* one rule for the core's strict-table check and moost-db's capability index
+* (`/meta.fields[P].groupable` and the HTTP gate). First failing rule wins:
+*
+* 1. `encrypted` — `@db.encrypted`;
+* 2. `notFilterable` — the adapter cannot filter (so cannot group) the storage;
+* 3. `notDimension` — a strict table ({@link isStrictTable}) and the field is
+*    not a dimension.
+*
+* A calendar-bucket alias is not a field: it groups by its source, whose
+* dimension rule is {@link bucketSourceVerdict}'s (callers skip aliases).
+*/
+function groupSourceVerdict(fd, table, adapter) {
+	if (fd.encrypted) return {
+		ok: false,
+		code: "encrypted",
+		reason: ENCRYPTED_REASON
+	};
+	if (!adapter.canFilterField(fd)) return {
+		ok: false,
+		code: "notFilterable",
+		reason: ADAPTER_FILTER_REASON
+	};
+	if (isStrictTable(table) && !table.dimensions.includes(fd.path)) return {
+		ok: false,
+		code: "notDimension",
+		reason: NOT_DIMENSION_REASON
+	};
+	return { ok: true };
+}
+/**
 * Whether the stored leaf `fd` may be the source of a calendar bucket
 * (since 0.1.133) — every schema and adapter rule, once, for the core path
 * guard ({@link guardPath} op `bucket`) and moost-db's capability index
@@ -2100,7 +2834,7 @@ function bucketSourceVerdict(fd, table, adapter) {
 	if (jsonAncestor !== void 0) return rejectSource("jsonDescendant", `inside JSON-stored column "${jsonAncestor}"`);
 	if (!isBucketableField(fd)) return rejectSource("notTimestamp", "not a timestamp field (declare it number.timestamp)");
 	if (!adapter.canFilterField(fd)) return rejectSource("notFilterable", ADAPTER_FILTER_REASON);
-	if (isStrictTable(table) && !table.dimensions.includes(fd.path)) return rejectSource("notDimension", "not a dimension");
+	if (isStrictTable(table) && !table.dimensions.includes(fd.path)) return rejectSource("notDimension", NOT_DIMENSION_REASON);
 	if (adapter.calendarBucketUnits().size === 0) return rejectSource("noBuckets", "adapter has no calendar buckets");
 	return { ok: true };
 }
@@ -2132,8 +2866,9 @@ function collectFilterKeys(filter, push, skip, refs) {
 *
 * Aggregate mode is `aggregate` when given, else the presence of `$groupBy`.
 * In aggregate mode `$select` computed entries are collected by kind — an
-* aggregate's `$field` into `aggregate`, a calendar bucket's into `bucket` —
-* and their aliases (`$as`, else uniqu's `resolveAlias`) are exempted from
+* aggregate's `$field` (a row-level expression's names, a `first` / `last`
+* field) into `aggregate`, a calendar bucket's into `bucket`, a `$rowOrder`
+* key into `sort` — and their aliases (`$as`, else uniqu's `resolveAlias`) are exempted from
 * `$sort` / `$having`; a bucket alias is also dropped from `groupBy`, which
 * lists grouped fields only.
 *
@@ -2150,10 +2885,17 @@ function collectQueryPaths(query, aggregate) {
 		bucket: [],
 		aggregateMode: false
 	};
-	collectFilterKeys(query.filter, (path, value) => refs.filter.push({
-		path,
-		predicate: filterPredicateOf(value)
-	}), void 0, refs);
+	collectFilterKeys(query.filter, (path, value) => {
+		const predicate = filterPredicateOf(value);
+		refs.filter.push(predicate === "relation" ? {
+			path,
+			predicate,
+			relation: relationOpsOf(value)
+		} : {
+			path,
+			predicate
+		});
+	}, void 0, refs);
 	const controls = query.controls ?? {};
 	const rawGroupBy = controls.$groupBy;
 	const groupBy = Array.isArray(rawGroupBy) ? rawGroupBy.filter((f) => typeof f === "string") : typeof rawGroupBy === "string" ? [rawGroupBy] : [];
@@ -2164,11 +2906,12 @@ function collectQueryPaths(query, aggregate) {
 	if (Array.isArray(select)) {
 		for (const item of select) if (typeof item === "string") refs.select.push(item);
 		else if (!refs.aggregateMode) continue;
-		else if (isAggregateExpr(item)) {
-			aliases.add(resolveAlias(item));
-			if (item.$field !== "*") refs.aggregate.push(item.$field);
-		} else if (isBucketExpr(item)) {
-			const alias = resolveAlias(item);
+		else if (isAggregateExpr(item) || isAggregateOfExpr(item)) {
+			aliases.add(resolveAlias$1(item));
+			refs.aggregate.push(...entryFields(item));
+		} else if (isSelectArithExpr(item)) aliases.add(item.$as);
+		else if (isBucketExpr(item)) {
+			const alias = resolveAlias$1(item);
 			aliases.add(alias);
 			bucketAliases.add(alias);
 			refs.bucket.push(item.$field);
@@ -2176,6 +2919,7 @@ function collectQueryPaths(query, aggregate) {
 	} else if (select && typeof select === "object") refs.select.push(...Object.keys(select));
 	refs.groupBy = bucketAliases.size > 0 ? groupBy.filter((name) => !bucketAliases.has(name)) : groupBy;
 	for (const name of sortFieldNames(controls.$sort)) if (!aliases.has(name)) refs.sort.push(name);
+	if (refs.aggregateMode) refs.sort.push(...rowOrderKeys(controls.$rowOrder));
 	if (refs.aggregateMode) collectFilterKeys(controls.$having, (path) => refs.having.push(path), aliases, refs);
 	return refs;
 }
@@ -2245,8 +2989,11 @@ function pathSourceOf(meta) {
 function guardPath(meta, adapter, path, op, predicate = "compare") {
 	const verb = OP_VERB[op];
 	const { kind, parent } = classifyQueryPath(pathSourceOf(meta), path);
+	if (predicate === "relation" && kind !== "nav" && kind !== "unknown") throw pathError(path, `"$some" / "$none" are only valid on a navigation relation — "${path}" is not one`);
 	switch (kind) {
-		case "nav": throw pathError(path, `Cannot ${verb} "${path}" — navigation path`);
+		case "nav":
+			if (op === "filter" && predicate === "relation" && parent === void 0) return;
+			throw pathError(path, navPathMessage(path, verb, op, parent));
 		case "leaf": {
 			if (op === "select") return;
 			const fd = meta.descriptorByPath.get(path);
@@ -2271,6 +3018,35 @@ function guardPath(meta, adapter, path, op, predicate = "compare") {
 	}
 }
 /**
+* The rejection of a navigation path in a non-predicate position. A filter
+* names the predicate that expresses it: `ticket.status` →
+* `{ ticket: { $some: { status: … } } }`.
+*/
+function navPathMessage(path, verb, op, parent) {
+	const base = `Cannot ${verb} "${path}" — navigation path`;
+	if (op !== "filter") return base;
+	return `${base}; use { ${parent ?? path}: { $some: ${parent === void 0 ? "…" : `{ ${path.slice(parent.length + 1)}: … }`} } }`;
+}
+/**
+* A `relation` filter entry: the adapter must render predicates in this
+* mode, the table must be wired to its related tables (a `DbSpace`), and
+* each operand is guarded by the related table (depth / count caps, the
+* related table's own path rules) — see `TRelationFilterHost.guard`.
+*/
+function guardRelationRef(meta, adapter, ref, state) {
+	const path = state.path ? `${state.path}.${ref.path}` : ref.path;
+	const mode = state.write ? "write" : "read";
+	if (!adapter.supportsRelationFilters(mode)) throw new DbError("REL_FILTER_NOT_SUPPORTED", [{
+		path,
+		message: `Relational predicates ($some / $none) are not supported by this adapter${state.write ? " in mutation filters" : ""}`
+	}]);
+	if (!meta.relationFilters) throw new DbError("REL_FILTER_NOT_SUPPORTED", [{
+		path,
+		message: `Relational predicate on "${path}" needs the table to come from a DbSpace (no table resolver)`
+	}]);
+	for (const { op, filter } of ref.relation ?? []) meta.relationFilters.guard(ref.path, op, filter, state);
+}
+/**
 * Core backstop for every read / aggregate / mutation-filter entry point:
 * each referenced path (see {@link collectQueryPaths}) must exist on THIS
 * adapter with the physical capability the position needs (see
@@ -2285,20 +3061,29 @@ function guardPath(meta, adapter, path, op, predicate = "compare") {
 * `bucket`), `$groupBy` fields are checked, and computed aliases (`$as` or
 * the default) are exempt in `$sort` / `$having`.
 *
+* Then every filter comparison value must be able to denote its field's
+* declared type (`guardFilterValues`, since 0.1.147) — after the paths, so
+* an unknown or unfilterable field keeps its own rejection.
+*
 * Returns the collected refs so callers can run further structural rules
 * (see {@link checkHavingKeys}) without walking the query again.
 */
-function guardPaths(meta, adapter, query, aggregate = false) {
+function guardPaths(meta, adapter, query, aggregate = false, state) {
 	if (!query) return;
 	const refs = collectQueryPaths(query, aggregate);
 	if (refs.unsupportedOperator !== void 0) throw pathError(refs.unsupportedOperator, unsupportedOperatorMessage(refs.unsupportedOperator));
-	for (const ref of refs.filter) guardPath(meta, adapter, ref.path, "filter", ref.predicate);
+	let relState = state;
+	for (const ref of refs.filter) {
+		guardPath(meta, adapter, ref.path, "filter", ref.predicate);
+		if (ref.predicate === "relation") guardRelationRef(meta, adapter, ref, relState ??= relGuardState());
+	}
 	for (const path of refs.sort) guardPath(meta, adapter, path, "sort");
 	for (const path of refs.select) guardPath(meta, adapter, path, "select");
 	for (const path of refs.aggregate) guardPath(meta, adapter, path, "aggregate");
 	for (const path of refs.bucket) guardPath(meta, adapter, path, "bucket");
 	for (const path of refs.groupBy) guardPath(meta, adapter, path, "groupBy");
 	for (const path of refs.having) guardPath(meta, adapter, path, "having");
+	guardFilterValues(meta, query.filter);
 	return refs;
 }
 /**
@@ -2306,12 +3091,12 @@ function guardPaths(meta, adapter, query, aggregate = false) {
 * normalizer (a calendar bucket is invalid outside a grouped query), then
 * the path guard.
 */
-function guardQuery(meta, adapter, query) {
+function guardQuery(meta, adapter, query, state) {
 	if (!query) return;
 	guardFilter(meta, adapter, query.filter);
 	guardSort(meta, query.controls?.$sort);
-	normalizeComputedSelect(query.controls, meta, false);
-	guardPaths(meta, adapter, query);
+	resolveComputedSelect(query.controls, meta, false);
+	guardPaths(meta, adapter, query, false, state);
 }
 /**
 * `$having` is a post-aggregation filter, so a key is either a computed
@@ -2337,29 +3122,45 @@ function checkHavingKeys(refs) {
 * (`AGG_FN_NOT_SUPPORTED`) and calendar-bucket units
 * (`BUCKET_NOT_SUPPORTED`), then the `$having` key rule
 * ({@link checkHavingKeys} — after the path guard so an unknown key still
-* reads `Unknown field`).
+* reads `Unknown field`), then the `$having` values (`guardHavingValues`).
 *
-* `buckets` are the query's resolved calendar buckets when the caller already
-* ran `normalizeComputedSelect` (resolved here otherwise).
+* `resolved` is the query's normalized computed `$select`
+* (`resolveComputedSelect`) when the caller already ran it (resolved here
+* otherwise).
 */
 function guardAggregate(meta, adapter, query, resolved) {
-	const buckets = resolved ?? normalizeComputedSelect(query.controls, meta, true);
+	const computed = resolved ?? resolveComputedSelect(query.controls, meta, true);
+	const { buckets } = computed;
 	guardFilter(meta, adapter, query.filter);
 	const controls = query.controls;
 	if (meta.encryptedFields.size > 0) {
 		for (const field of controls.$groupBy ?? []) if (isEncryptedRef(meta, field)) throw encryptedRefError("ENC_FIELD_AGG", field, "group by");
-		if (controls.$select) for (const item of controls.$select) {
-			const field = typeof item === "string" ? item : item.$field;
-			if (field !== "*" && isEncryptedRef(meta, field)) throw encryptedRefError("ENC_FIELD_AGG", field, "aggregate over");
+		if (controls.$select) {
+			for (const item of controls.$select) for (const field of entryFields(item)) if (isEncryptedRef(meta, field)) throw encryptedRefError("ENC_FIELD_AGG", field, "aggregate over");
 		}
+		for (const key of rowOrderKeys(controls.$rowOrder)) if (isEncryptedRef(meta, key)) throw encryptedRefError("ENC_FIELD_SORT", key, "sort by");
 		if (controls.$having) guardFilter(meta, adapter, controls.$having, "ENC_FIELD_AGG");
 		guardSort(meta, controls.$sort);
 	}
 	const refs = guardPaths(meta, adapter, query, true);
 	guardAggregateFns(adapter, controls.$select);
+	guardAggregateExpressions(adapter, controls.$select);
+	checkAggregateExprs(meta, query, computed.exprs, computed.rowOrder);
 	guardBucketUnits(adapter, buckets);
 	const having = refs ? checkHavingKeys(refs) : void 0;
 	if (having) throw new DbError("INVALID_QUERY", [having]);
+	guardHavingValues(meta, controls);
+}
+/**
+* Rejects an arithmetic `$select` entry (`{ $expr }`, `{ $fn, $expr }`) on an
+* adapter whose `supportsAggregateExpressions()` is false with
+* `AGG_EXPR_NOT_SUPPORTED`, before anything is translated.
+*
+* @since 0.1.148
+*/
+function guardAggregateExpressions(adapter, select) {
+	if (!Array.isArray(select) || adapter.supportsAggregateExpressions()) return;
+	for (const item of select) if (isAggregateOfExpr(item) || isSelectArithExpr(item)) throw aggregateExpressionsNotSupported();
 }
 /**
 * Rejects an aggregate whose (known — the normalizer checked the name)
@@ -2542,9 +3343,18 @@ var AtscriptDbReadable = class {
 	setEncryption(encryption) {
 		this._encryption = encryption;
 	}
+	/** @internal Set by the owning `DbSpace` when it closes. */
+	_spaceClosed = false;
 	/** Ensures metadata is built. Called before any metadata access. */
 	_ensureBuilt() {
-		if (!this._meta.isBuilt) this._meta.build(this.type, this.adapter, this.logger);
+		if (this._spaceClosed) throw spaceClosedError();
+		if (!this._meta.isBuilt) {
+			this._meta.build(this.type, this.adapter, this.logger);
+			if (this._meta.navFields.size > 0 && this._tableResolver) {
+				const resolver = this._tableResolver;
+				this._meta.relationFilters = createRelationFilterHost(this, (type) => resolver(type));
+			}
+		}
 		if (this._meta.encryptedFields.size > 0 && !this._encryption) throw new DbError("ENC_CONFIG_MISSING", [{
 			path: "",
 			message: `Table "${this.tableName}" declares @db.encrypted fields but the DbSpace has no encryption configuration — pass { encryption: { defaultKeyId, keys } } to the DbSpace options`
@@ -2571,6 +3381,56 @@ var AtscriptDbReadable = class {
 	_guardQuery(query) {
 		guardQuery(this._meta, this.adapter, query);
 	}
+	/**
+	* Guards a relational predicate operand against THIS table — the filter
+	* guard and the path guard with the predicate's shared `state` (depth,
+	* count, read/write mode). Called by the source table's relation host.
+	*
+	* @internal Core wiring for relational predicates; not consumer API.
+	*/
+	_guardRelationOperand(filter, state) {
+		this._ensureBuilt();
+		guardFilter(this._meta, this.adapter, filter);
+		guardPaths(this._meta, this.adapter, { filter }, false, state);
+	}
+	/**
+	* Translates a relational predicate operand for THIS table's adapter (its
+	* own field mapper; nested predicates resolved at `depth + 1`).
+	*
+	* @internal Core wiring for relational predicates; not consumer API.
+	*/
+	_resolveRelationOperand(filter, depth) {
+		this._ensureBuilt();
+		return this._fieldMapper.translateFilter(filter, this._meta, depth);
+	}
+	/**
+	* Translates a logical query (filter + controls) for THIS table's adapter
+	* after the read guards — exactly what `findMany` hands the adapter.
+	* For adapters that load `$with` relations natively and must address the
+	* related table's physical names.
+	*
+	* @internal Adapter-facing surface; not part of the consumer API.
+	* @since 0.1.147
+	*/
+	_translateForAdapter(query) {
+		this._ensureBuilt();
+		this._guardQuery(query);
+		return this._fieldMapper.translateQuery(query, this._meta);
+	}
+	/**
+	* Physical rows of THIS table → logical rows (field mapping, value
+	* formatters, decryption) — what every read does before `$with` loading.
+	* `controls` are the logical read controls the rows were read with.
+	*
+	* @internal Adapter-facing surface; not part of the consumer API.
+	* @since 0.1.147
+	*/
+	async _rowsFromAdapter(rows, controls) {
+		this._ensureBuilt();
+		const out = this._fromRead(rows, controls);
+		await this._decryptRows(out);
+		return out;
+	}
 	_encryptedPathsCache;
 	/** Pre-split `encryptedFields` paths — computed once, reused on every read/write. */
 	get _encryptedPaths() {
@@ -2653,6 +3513,22 @@ var AtscriptDbReadable = class {
 		this._ensureBuilt();
 		return this._meta.primaryKeys;
 	}
+	/**
+	* Physical column lists that must be unique: the primary key (when declared)
+	* followed by every unique index and every adapter-contributed unique field. Used by conflict-ignoring inserts.
+	* @since 0.1.148
+	*/
+	get uniqueKeySets() {
+		this._ensureBuilt();
+		const sets = [];
+		if (this._meta.primaryKeys.length > 0) sets.push(this._meta.primaryKeys.map((f) => this._meta.physicalPath(f)));
+		for (const index of this._meta.indexes.values()) if (index.type === "unique") sets.push(index.fields.map((f) => f.name));
+		for (const prop of this._meta.uniqueProps) {
+			const column = this._meta.physicalPath(prop);
+			if (!sets.some((s) => s.length === 1 && s[0] === column)) sets.push([column]);
+		}
+		return sets;
+	}
 	/** Preferred row identifier field names. Defaults to primary keys. */
 	get preferredId() {
 		this._ensureBuilt();
@@ -2825,6 +3701,15 @@ var AtscriptDbReadable = class {
 		this._ensureBuilt();
 		return this._meta.pathToPhysical;
 	}
+	/**
+	* Physical column (or document path) of a logical field path —
+	* `@db.column` renames and flattening applied.
+	* @since 0.1.147
+	*/
+	physicalPath(logical) {
+		this._ensureBuilt();
+		return this._meta.physicalPath(logical);
+	}
 	/** Precomputed physical column name → logical dot-path map (inverse). */
 	get physicalToPath() {
 		this._ensureBuilt();
@@ -2843,8 +3728,10 @@ var AtscriptDbReadable = class {
 	* work (the derived read plan on document adapters) is done once for all
 	* of them. Every read path funnels through here.
 	*/
-	_fromRead(rows, controls) {
-		return this._fieldMapper.reconstructRows(rows, this._meta, controls);
+	_fromRead(rows, controls, aliasFields) {
+		const out = this._fieldMapper.reconstructRows(rows, this._meta, controls);
+		if (aliasFields?.size) coerceAliasValues(out, aliasFields);
+		return out;
 	}
 	/**
 	* Translates a read query for the adapter. A `$select` that leaves out a
@@ -2879,10 +3766,14 @@ var AtscriptDbReadable = class {
 			widened
 		};
 	}
-	/** Reconstructs + decrypts a read's rows, loads its `$with` relations and strips widened keys. */
-	async _finishRead(results, read) {
-		const rows = this._fromRead(results, read.controls);
-		await this._decryptRows(rows);
+	/**
+	* Reconstructs + decrypts a read's rows, keeps the ones `pick` selects (all
+	* by default), loads their `$with` relations and strips widened keys.
+	*/
+	async _finishRead(results, read, pick) {
+		const all = this._fromRead(results, read.controls);
+		await this._decryptRows(all);
+		const rows = pick ? pick(all) : all;
 		if (read.withRelations?.length) {
 			await this.loadRelations(rows, read.withRelations);
 			for (const key of read.widened) for (const row of rows) deletePath(row, key);
@@ -2991,11 +3882,12 @@ var AtscriptDbReadable = class {
 	* table. Defense-in-depth for query-path validation: `flattenAnnotatedType`
 	* still truncates real self-referential cycles, so paths like
 	* `parent.parent.name` on a self-ref schema would miss `flatMap.has` but
-	* remain valid field references on the target.
+	* remain valid field references on the target — a path may cross the same
+	* relation any number of times (callers cap the depth).
 	*
-	* Cycle-safe via a visited set keyed on `<tableName>:<navField>`.
+	* Terminates on cyclic schemas: every hop consumes one path segment.
 	*/
-	isValidFieldPath(path, _visited) {
+	isValidFieldPath(path) {
 		if (this.flatMap.has(path)) return true;
 		const dotIdx = path.indexOf(".");
 		if (dotIdx === -1) return false;
@@ -3003,11 +3895,7 @@ var AtscriptDbReadable = class {
 		const tail = path.slice(dotIdx + 1);
 		const targetTable = this.relatedTable(head);
 		if (!targetTable || typeof targetTable.isValidFieldPath !== "function") return false;
-		const visited = _visited ?? /* @__PURE__ */ new Set();
-		const cycleKey = `${this.tableName}:${head}`;
-		if (visited.has(cycleKey)) return false;
-		visited.add(cycleKey);
-		return targetTable.isValidFieldPath(tail, visited);
+		return targetTable.isValidFieldPath(tail);
 	}
 	/**
 	* Creates a new validator with custom options.
@@ -3041,6 +3929,22 @@ var AtscriptDbReadable = class {
 		return await this._finishRead(await this.adapter.findMany(read.translated), read);
 	}
 	/**
+	* `findMany` for the generic `$with` loader. With `partitionBy` (logical
+	* fields), `$skip` / `$limit` apply per group of rows sharing those fields'
+	* values (`BaseDbAdapter.findManyPerPartition`); `pick` chooses which of the
+	* read rows to keep before their own `$with` relations load.
+	*
+	* @internal Relation-loader surface; not part of the consumer API.
+	* @since 0.1.147
+	*/
+	async _findManyForRelation(query, opts) {
+		this._ensureBuilt();
+		this._guardQuery(query);
+		const read = this._translateRead(query);
+		const results = opts.partitionBy ? await this.adapter.findManyPerPartition(read.translated, opts.partitionBy.map((field) => this._meta.physicalPath(field))) : await this.adapter.findMany(read.translated);
+		return this._finishRead(results, read, opts.pick);
+	}
+	/**
 	* Counts records matching the query.
 	*/
 	async count(query) {
@@ -3087,7 +3991,8 @@ var AtscriptDbReadable = class {
 	async aggregate(query) {
 		this._ensureBuilt();
 		const { $groupBy, $select } = query.controls;
-		const buckets = normalizeComputedSelect(query.controls, this._meta, true);
+		const computed = resolveComputedSelect(query.controls, this._meta, true);
+		const { buckets } = computed;
 		if ($select) {
 			const groupBySet = new Set($groupBy);
 			for (const item of $select) if (typeof item === "string" && !groupBySet.has(item)) throw new DbError("INVALID_QUERY", [{
@@ -3100,13 +4005,19 @@ var AtscriptDbReadable = class {
 			const dimSet = new Set(dimensions);
 			const measSet = new Set(measures);
 			const bucketAliases = new Set(buckets.map((b) => b.alias));
-			for (const field of $groupBy) if (!dimSet.has(field) && !bucketAliases.has(field)) throw new DbError("INVALID_QUERY", [{
-				path: "$groupBy",
-				message: `Field "${field}" is not a dimension`
-			}]);
+			const descriptors = new Map(this._meta.fieldDescriptors.map((fd) => [fd.path, fd]));
+			for (const field of $groupBy) {
+				if (bucketAliases.has(field)) continue;
+				const fd = descriptors.get(field);
+				const verdict = fd && groupSourceVerdict(fd, this._meta, this.adapter);
+				if (verdict ? !verdict.ok && verdict.code === "notDimension" : !dimSet.has(field)) throw new DbError("INVALID_QUERY", [{
+					path: "$groupBy",
+					message: `Field "${field}" is not a dimension`
+				}]);
+			}
 			if ($select) for (const item of $select) {
 				if (!isAggregateExpr(item) || item.$field === "*" || measSet.has(item.$field)) continue;
-				if (item.$fn === "countDistinct") {
+				if (item.$fn === "countDistinct" || isFirstLast(item)) {
 					if (dimSet.has(item.$field)) continue;
 					throw new DbError("INVALID_QUERY", [{
 						path: "$select",
@@ -3136,10 +4047,24 @@ var AtscriptDbReadable = class {
 			this._ensureSearchable();
 			if (!searchTerm.trim()) return query.controls.$count ? [{ count: 0 }] : [];
 		}
-		guardAggregate(this._meta, this.adapter, query, buckets);
-		const dbQuery = this._fieldMapper.translateAggregateQuery(query, this._meta, buckets);
+		guardAggregate(this._meta, this.adapter, query, computed);
+		const dbQuery = this._fieldMapper.translateAggregateQuery(query, this._meta, buckets, computed.exprs, computed.rowOrder);
 		const results = await this.adapter.aggregate(dbQuery);
-		return this._fromRead(results, query.controls);
+		return this._fromRead(results, query.controls, this._aliasFields($select));
+	}
+	/**
+	* The computed aliases of one source field that is a boolean or a decimal —
+	* `min` / `max` / `first` / `last` — with that field's descriptor: the
+	* aggregate row's value is coerced like the column's own on read.
+	*/
+	_aliasFields(select) {
+		const out = /* @__PURE__ */ new Map();
+		for (const item of select ?? []) {
+			if (!isAggregateExpr(item) || !SOURCE_VALUE_FNS.has(item.$fn)) continue;
+			const fd = this._meta.descriptorByPath.get(item.$field);
+			if (fd && (fd.designType === "boolean" || fd.designType === "decimal")) out.set(resolveAlias(item), fd);
+		}
+		return out;
 	}
 	/** Whether the underlying adapter supports text search. */
 	isSearchable() {
@@ -3153,6 +4078,10 @@ var AtscriptDbReadable = class {
 	calendarBucketUnits() {
 		return this.adapter.calendarBucketUnits();
 	}
+	/** Whether the adapter renders aggregate arithmetic (proxies adapter capability). @since 0.1.148 */
+	supportsAggregateExpressions() {
+		return this.adapter.supportsAggregateExpressions();
+	}
 	/** Aggregate functions the adapter renders (proxies adapter capability). @since 0.1.136 */
 	aggregateFns() {
 		return this.adapter.aggregateFns();
@@ -3561,7 +4490,7 @@ var AtscriptDbReadable = class {
 	* Public entry point for relation loading. Used by adapters for nested $with delegation.
 	*/
 	async loadRelations(rows, withRelations) {
-		const { loadRelationsImpl } = await import("./relation-loader-D9XuXaMv.mjs").then((n) => n.n);
+		const { loadRelationsImpl } = await import("./relation-loader-ByY1Byrl.mjs").then((n) => n.n);
 		return loadRelationsImpl(rows, withRelations, this);
 	}
 	/**
@@ -3627,8 +4556,14 @@ function createFailureCollector(what) {
 //#region src/base-adapter.ts
 const EMPTY_DEFAULT_FNS = /* @__PURE__ */ new Set();
 const EMPTY_BUCKET_UNITS = /* @__PURE__ */ new Set();
-/** Every calendar-bucket unit — what an adapter that renders them all returns from `calendarBucketUnits()`. */
+/**
+* Every calendar-bucket unit — what an adapter that renders them all returns
+* from `calendarBucketUnits()`. Includes `'hour'` since 0.1.147.
+*/
 const ALL_BUCKET_UNITS = new Set(BUCKET_UNITS);
+const NO_VIEW_CAPABILITIES = /* @__PURE__ */ new Set();
+/** Every view capability — what the bundled adapters return from `viewCapabilities()`. @since 0.1.147 */
+const ALL_VIEW_CAPABILITIES = new Set(["compute", "firstJoin"]);
 const txStorage = new AsyncLocalStorage();
 /** The innermost open transaction of `owner` in the current async chain. */
 function findTxContext(owner) {
@@ -3688,6 +4623,26 @@ var BaseDbAdapter = class {
 	registerReadable(readable, logger) {
 		this._table = readable;
 		if (logger) this.logger = logger;
+		if (readable.isView) this._guardViewCapabilities(readable);
+	}
+	/**
+	* Makes `ensureTable()` of a managed view fail closed (since 0.1.147): it
+	* throws before the adapter renders a computed column / first-row join its
+	* {@link viewCapabilities} does not list — schema sync refuses such a view
+	* up front, a direct `ensureTable()` call must not render it as a plain
+	* (row-multiplying) join either. Wraps the subclass's own implementation, so
+	* third-party adapters get the guard without code changes.
+	*/
+	_guardViewCapabilities(readable) {
+		if (Object.prototype.hasOwnProperty.call(this, "ensureTable")) return;
+		const view = readable;
+		if (typeof view.viewCapabilityProblems !== "function") return;
+		const ensureTable = this.ensureTable.bind(this);
+		this.ensureTable = (opts) => {
+			const problems = view.viewCapabilityProblems();
+			if (problems.length > 0) return Promise.reject(new Error(problems.join("; ")));
+			return ensureTable(opts);
+		};
 	}
 	/**
 	* Called by {@link DbSpace} right after its factory builds this adapter —
@@ -3872,8 +4827,10 @@ var BaseDbAdapter = class {
 	* be adopted adapter by adapter. An adapter that returns a unit must group
 	* by the bucket alias in `$groupBy` — see `controls.$select.buckets`
 	* (`TResolvedBucket`: physical `field`, source `fd`) — and return the
-	* `YYYY-MM-DD` label of the bucket's first local day (null for a null or
-	* out-of-range source, uniqu's `bucketLabel` semantics). Since 0.1.132.
+	* `YYYY-MM-DD` label of the bucket's first local day, or for `'hour'` the
+	* local wall-clock hour `YYYY-MM-DDTHH:00` (null for a null or out-of-range
+	* source, uniqu's `bucketLabel` semantics). Since 0.1.132; `'hour'` since
+	* 0.1.147 — an adapter returning {@link ALL_BUCKET_UNITS} must render it.
 	*/
 	calendarBucketUnits() {
 		return EMPTY_BUCKET_UNITS;
@@ -3893,6 +4850,22 @@ var BaseDbAdapter = class {
 		return BASE_AGGREGATE_FNS;
 	}
 	/**
+	* Whether this adapter renders arithmetic in an aggregate `$select`
+	* (`{ $expr }`, `{ $fn, $expr }`) — IEEE double, NULL propagating, `/` by
+	* zero NULL, the same semantics as `@db.compute`. Default `false`
+	* (fail-closed): the core rejects such a query with `AGG_EXPR_NOT_SUPPORTED`
+	* before dispatch. An adapter returning `true` also receives
+	* `controls.$select.exprAggregates` / `.exprs` (see `UniquSelect`), and
+	* `first` / `last` (`aggregateFns()`) with `.firstLast` and `.rowOrder`;
+	* the shared `evaluateExpr` evaluates an expression tree in process.
+	* moost-db advertises it as `/meta.aggregateExpressions`.
+	*
+	* @since 0.1.148
+	*/
+	supportsAggregateExpressions() {
+		return false;
+	}
+	/**
 	* Revision of how this adapter renders a managed view (its SQL / pipeline)
 	* from an unchanged view definition. Stored in each managed view's sync
 	* snapshot when defined, so bumping it recreates every managed view of the
@@ -3904,6 +4877,18 @@ var BaseDbAdapter = class {
 	*/
 	viewRenderRevision() {}
 	/**
+	* The managed-view features this adapter renders: `compute` — computed
+	* columns (`@db.compute`); `firstJoin` — first-row joins (the ordered 4th
+	* argument of `@db.view.joins`). Schema sync refuses a view using a feature
+	* not listed. The default is EMPTY (fail-closed): a third-party adapter
+	* opts in once it renders them.
+	*
+	* @since 0.1.147
+	*/
+	viewCapabilities() {
+		return NO_VIEW_CAPABILITIES;
+	}
+	/**
 	* Whether this adapter enforces foreign key constraints natively.
 	* When `true`, the generic layer skips application-level cascade/setNull
 	* on delete — the DB engine handles it (e.g. SQLite `ON DELETE CASCADE`).
@@ -3961,6 +4946,39 @@ var BaseDbAdapter = class {
 		return false;
 	}
 	/**
+	* Whether this adapter renders relational filter predicates
+	* (`{ nav: { $some | $none: … } }`) in `mode` — `read` for find / count /
+	* search / aggregate filters, `write` for mutation filters
+	* (`updateMany`, `deleteMany`, …). Default `false`: the core rejects such
+	* filters with `REL_FILTER_NOT_SUPPORTED` before they reach the adapter.
+	*
+	* An adapter returning `true` receives each predicate already resolved by
+	* the core: the filter visitor's `relation(field, op, operand)` callback
+	* gets a `ResolvedRelationFilter` operand (`kind`, physical
+	* correlation `pairs`, `target` / `junction` tables with their adapters,
+	* and the inner `filter` already translated to the target's physical
+	* names, nested predicates resolved too). Keep `relation` on every
+	* `walkFilter` visitor that may meet such a filter.
+	*
+	* @since 0.1.147
+	*/
+	supportsRelationFilters(_mode) {
+		return false;
+	}
+	/**
+	* Whether `other` serves a table of the SAME store as this adapter, so one
+	* statement / pipeline can correlate both (a relational predicate renders
+	* the related table inside this table's query). Default: same adapter class
+	* and same {@link _transactionOwner} (the driver / pool / client the
+	* adapter was built with). Override when the owner is shared across
+	* separate databases (e.g. one Mongo client over several databases).
+	*
+	* @since 0.1.147
+	*/
+	sharesStoreWith(other) {
+		return other.constructor === this.constructor && other._transactionOwner() === this._transactionOwner();
+	}
+	/**
 	* Loads relations onto result rows using adapter-native operations.
 	* Only called when {@link supportsNativeRelations} returns `true`.
 	*
@@ -4197,6 +5215,31 @@ var BaseDbAdapter = class {
 		};
 	}
 	/**
+	* Reads like {@link findMany}, except that `$skip` / `$limit` apply to each
+	* partition — the rows sharing the values of the `partitionBy` columns
+	* (physical names) — instead of to the whole result. The generic `$with`
+	* loader reads the related rows of many parent rows at once this way, so a
+	* relation's `$skip` / `$limit` page each parent row's related rows.
+	* `$sort` orders the rows within a partition; how partitions interleave is
+	* unspecified.
+	*
+	* Default: one {@link findMany} without `$skip` / `$limit`, paged per
+	* partition in memory. The SQL adapters override it with a `ROW_NUMBER()`
+	* window, so only the kept rows are read.
+	*
+	* @since 0.1.147
+	*/
+	async findManyPerPartition(query, partitionBy) {
+		const { $skip, $limit, ...controls } = query.controls;
+		return slicePerGroup(await this.findMany({
+			...query,
+			controls
+		}), (row) => compositeKey(partitionBy, row, getPath), {
+			skip: $skip ?? void 0,
+			limit: $limit ?? void 0
+		});
+	}
+	/**
 	* Executes an aggregate query (GROUP BY + aggregate functions).
 	* Default throws — override in adapters that support aggregation.
 	*/
@@ -4204,6 +5247,28 @@ var BaseDbAdapter = class {
 		throw new Error("Aggregation not supported by this adapter");
 	}
 	/**
+	* Conflict-ignoring batch insert (`insertMany(rows, { onConflict: 'ignore' })`).
+	* Returns ONE SLOT PER INPUT ROW, in order: `{ insertedId }` for an inserted
+	* row, `null` for a row skipped because it collided with a STORED row on the
+	* primary key or a unique index. (The core already removed duplicates inside
+	* the batch.) Only uniqueness collisions are skipped — NOT NULL, FK, check
+	* and every other error must throw — and a skipped row must never abort the
+	* surrounding transaction. Fail-closed by default: throws
+	* `DbError("ON_CONFLICT_NOT_SUPPORTED")`; also override
+	* {@link supportsInsertIgnore}.
+	* @since 0.1.148
+	*/
+	insertManyIgnore(_data) {
+		return Promise.reject(new DbError("ON_CONFLICT_NOT_SUPPORTED", [{
+			path: "",
+			message: `The ${this.constructor.name} adapter does not support onConflict "ignore"`
+		}]));
+	}
+	/** Whether {@link insertManyIgnore} is implemented (drives `crud.insert: ["onConflict"]` in `/meta`). @since 0.1.148 */
+	supportsInsertIgnore() {
+		return false;
+	}
+	/**
 	* When true, the adapter can handle column type changes in-place
 	* (e.g. MySQL's ALTER TABLE MODIFY COLUMN) without requiring table recreation.
 	* The generic sync layer will delegate type changes to {@link syncColumns}
@@ -4267,6 +5332,8 @@ var BaseDbAdapter = class {
 //#endregion
 //#region src/strategies/application-integrity.ts
 const MAX_CASCADE_DEPTH = 100;
+/** Rows per pinned-key delete batch (keeps `IN (…)` / `$or` lists bounded). */
+const PIN_BATCH = 1e3;
 const cascadeStorage = new AsyncLocalStorage();
 /**
 * Integrity strategy for adapters without native FK support (e.g. MongoDB).
@@ -4335,6 +5402,12 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 	* - `restrict`: throws if any children exist
 	* - `cascade`: recursively deletes child records
 	* - `setNull`: sets FK fields to null
+	*
+	* When `filter` holds a relational predicate, returns the matched rows
+	* PINNED by primary key (see {@link TCascadePin}): the caller deletes those
+	* rows, never re-evaluating `filter` on data the cascade just changed (a
+	* `$some` over a cascaded child relation would otherwise stop matching and
+	* leave the parent behind). Any other filter → `undefined`.
 	*/
 	async cascadeBeforeDelete(filter, tableName, meta, cascadeResolver, translateFilter, adapter) {
 		const parentCtx = cascadeStorage.getStore();
@@ -4346,6 +5419,11 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 		}]);
 		const targets = cascadeResolver(tableName);
 		if (targets.length === 0) return;
+		const pkPhysical = containsRelationFilter(filter) ? meta.primaryKeys.map((pk) => meta.physicalPath(pk)) : void 0;
+		if (pkPhysical?.length === 0) throw new DbError("REL_FILTER_NOT_SUPPORTED", [{
+			path: "",
+			message: "Cannot delete by a relational predicate with application-level cascades: the table has no primary key"
+		}]);
 		const neededLogical = /* @__PURE__ */ new Set();
 		for (const t of targets) for (const tf of t.fk.targetFields) neededLogical.add(tf);
 		for (const pk of meta.primaryKeys) neededLogical.add(pk);
@@ -4360,7 +5438,8 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 			filter: translateFilter(filter),
 			controls: { $select: new UniquSelect(physicalFields) }
 		});
-		if (rawRecords.length === 0) return;
+		const pin = pkPhysical ? pinByPrimaryKey(rawRecords, pkPhysical) : void 0;
+		if (rawRecords.length === 0) return pin;
 		const allRecords = rawRecords.map((r) => {
 			const mapped = {};
 			for (const [key, val] of Object.entries(r)) mapped[physicalToLogical.get(key) ?? key] = val;
@@ -4376,7 +5455,7 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 			addedKeys.push(key);
 			records.push(record);
 		}
-		if (records.length === 0) return;
+		if (records.length === 0) return pin;
 		try {
 			await cascadeStorage.run({
 				visited,
@@ -4416,6 +5495,7 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 		} finally {
 			for (const key of addedKeys) visited.delete(key);
 		}
+		return pin;
 	}
 	needsCascade(cascadeResolver) {
 		return !!cascadeResolver;
@@ -4456,6 +5536,23 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 		return orFilters.length === 1 ? orFilters[0] : { $or: orFilters };
 	}
 };
+/**
+* Adapter-ready filters addressing exactly `rows` by their (physical) primary
+* key, in batches of {@link PIN_BATCH}: `{ pk: { $in } }` for a single key,
+* `{ $or: [{ a, b }, …] }` for a composite one. Values are the raw stored
+* values the adapter returned, so no value formatting is re-applied.
+*/
+function pinByPrimaryKey(rows, pk) {
+	const out = [];
+	for (let i = 0; i < rows.length; i += PIN_BATCH) {
+		const batch = rows.slice(i, i + PIN_BATCH);
+		if (pk.length === 1) {
+			const field = pk[0];
+			out.push({ [field]: { $in: batch.map((r) => r[field]) } });
+		} else out.push({ $or: batch.map((r) => Object.fromEntries(pk.map((f) => [f, r[f]]))) });
+	}
+	return out;
+}
 //#endregion
 //#region src/patch/array-ops-resolver.ts
 /**
@@ -4954,43 +6051,40 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		}
 		return this.validators.get(purpose);
 	}
-	/**
-	* Inserts a single record. Delegates to {@link insertMany} for unified
-	* nested creation support.
-	*/
 	async insertOne(payload, opts) {
-		return { insertedId: (await this.insertMany([payload], {
+		const result = await this._insertMany([payload], {
 			...opts,
 			_action: "insert"
-		})).insertedIds[0] };
+		});
+		if ("conflicts" in result) {
+			const conflict = result.conflicts.length > 0;
+			return conflict ? { conflict } : {
+				insertedId: result.insertedIds[0],
+				conflict
+			};
+		}
+		return { insertedId: result.insertedIds[0] };
 	}
-	/**
-	* Inserts multiple records with batch-optimized nested creation.
-	*
-	* Supports **nested creation**: if payloads include data for navigation
-	* fields (`@db.rel.to` / `@db.rel.from`), related records are created
-	* automatically in batches. TO dependencies are batch-created first
-	* (their PKs become our FKs), FROM dependents are batch-created after
-	* (they receive our PKs as their FKs). Fully recursive — nested records
-	* with their own nav data trigger further batch inserts at each level.
-	* Recursive up to `maxDepth` (default 3).
-	*
-	* `opts.guard` (since 0.1.128) runs once inside the transaction, after
-	* defaults + validation, with the prepared rows; `opts.check` (since
-	* 0.1.143) runs once after every phase with the inserted rows' primary-key
-	* filters — see {@link TWriteOptions}.
-	*/
 	async insertMany(payloads, opts) {
+		return this._insertMany(payloads, opts);
+	}
+	async _insertMany(payloads, opts) {
 		this._ensureBuilt();
-		const { _depth, _action, maxDepth: userMax, guard, check } = opts ?? {};
+		const { _depth, _action, maxDepth: userMax, guard, check, onConflict } = opts ?? {};
+		if (onConflict !== void 0 && onConflict !== "error" && onConflict !== "ignore") throw new DbError("INVALID_QUERY", [{
+			path: "onConflict",
+			message: `Unknown onConflict mode "${String(onConflict)}"`
+		}]);
+		const ignore = onConflict === "ignore";
 		const maxDepth = userMax ?? 3;
 		const depth = _depth ?? 0;
 		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
 		if (!canNest && this._meta.navFields.size > 0) checkDepthOverflow(payloads, maxDepth, this._meta);
 		return enrichFkViolation(this._meta, () => this.adapter.withTransaction(async () => {
 			const clone = depth === 0 ? _cloneWritePayload : _shallowPrunedClone;
-			const items = payloads.map((p) => this._applyDefaults(clone(p)));
-			const originals = canNest ? items.map((item) => ({ ...item })) : [];
+			let items = payloads.map((p) => this._applyDefaults(clone(p)));
+			if (ignore) this._linkToByKeyInIgnoreMode(items);
+			let originals = canNest ? items.map((item) => ({ ...item })) : [];
 			const validator = this.getValidator("insert");
 			const ctx = {
 				mode: "insert",
@@ -5003,18 +6097,28 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				validateBatch(validator, items, ctx);
 			}
 			await this._encryptItems(items, "write");
+			if (ignore) this._rejectNestedToInIgnoreMode(items);
 			const host = this;
 			if (canNest) await batchInsertNestedTo(host, items, maxDepth, depth);
-			const prepared = [];
+			let prepared = [];
 			for (const data of items) {
 				for (const navField of this._meta.navFields) delete data[navField];
 				prepared.push(this._fieldMapper.prepareForWrite(data, this._meta, this.adapter));
 			}
 			await this._integrity.validateForeignKeys(items, this._meta, this._fkLookupResolver, this._writeTableResolver);
 			if (canNest) await preValidateNestedFrom(host, originals);
-			const result = await this.adapter.insertMany(prepared);
-			if (canNest) await batchInsertNestedFrom(host, originals, result.insertedIds, maxDepth, depth);
-			if (canNest) await batchInsertNestedVia(host, originals, result.insertedIds, maxDepth, depth);
+			let ignored;
+			if (ignore) {
+				ignored = await this._insertIgnoring(prepared);
+				const keep = ignored.inserted;
+				items = keep.map((i) => items[i]);
+				originals = canNest ? keep.map((i) => originals[i]) : originals;
+				prepared = keep.map((i) => prepared[i]);
+			}
+			const result = ignored ?? await this.adapter.insertMany(prepared);
+			const parentIds = result.insertedIds;
+			if (canNest) await batchInsertNestedFrom(host, originals, parentIds, maxDepth, depth);
+			if (canNest) await batchInsertNestedVia(host, originals, parentIds, maxDepth, depth);
 			if (check) await this._runWriteCheck(check, _action ?? "insertMany", this._insertedPkFilters(items, prepared, result.insertedIds));
 			return result;
 		}));
@@ -5331,7 +6435,10 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			const filter = this._andScope(pinned, opts?.scope);
 			const translated = this._fieldMapper.translateFilter(filter, this._meta);
 			if (guard) await guard(new RemoveGuardContext(id, filter, this));
-			if (needsCascade) await this._integrity.cascadeBeforeDelete(filter, this.tableName, this._meta, this._cascadeResolver, (f) => this._fieldMapper.translateFilter(f, this._meta), this.adapter);
+			if (needsCascade) {
+				const pin = await this._integrity.cascadeBeforeDelete(filter, this.tableName, this._meta, this._cascadeResolver, (f) => this._fieldMapper.translateFilter(f, this._meta), this.adapter);
+				if (pin) return pin.length > 0 ? this.adapter.deleteOne(pin[0]) : { deletedCount: 0 };
+			}
 			return this.adapter.deleteOne(translated);
 		};
 		return remapDeleteFkViolation(this.tableName, () => guard || needsCascade || candidates.length > 1 ? this.adapter.withTransaction(run) : run());
@@ -5375,7 +6482,12 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		this._ensureBuilt();
 		this._guardMutationFilter(filter);
 		if (this._integrity.needsCascade(this._cascadeResolver)) return remapDeleteFkViolation(this.tableName, () => this.adapter.withTransaction(async () => {
-			await this._integrity.cascadeBeforeDelete(filter, this.tableName, this._meta, this._cascadeResolver, (f) => this._fieldMapper.translateFilter(f, this._meta), this.adapter);
+			const pin = await this._integrity.cascadeBeforeDelete(filter, this.tableName, this._meta, this._cascadeResolver, (f) => this._fieldMapper.translateFilter(f, this._meta), this.adapter);
+			if (pin) {
+				let deletedCount = 0;
+				for (const batch of pin) deletedCount += (await this.adapter.deleteMany(batch)).deletedCount;
+				return { deletedCount };
+			}
 			return this.adapter.deleteMany(this._fieldMapper.translateFilter(filter, this._meta));
 		}));
 		return remapDeleteFkViolation(this.tableName, () => this.adapter.deleteMany(this._fieldMapper.translateFilter(filter, this._meta)));
@@ -5397,7 +6509,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	/** Engine-agnostic guard for user-supplied mutation filters (updateMany/deleteMany/…). */
 	_guardMutationFilter(filter) {
 		guardFilter(this._meta, this.adapter, filter);
-		guardPaths(this._meta, this.adapter, { filter });
+		guardPaths(this._meta, this.adapter, { filter }, false, relGuardState(true));
 	}
 	/**
 	* Encrypts `@db.encrypted` field values in place on (already validated)
@@ -5567,6 +6679,91 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		});
 	}
 	/**
+	* Ignore mode never writes a related parent — it would be orphaned when the
+	* row is skipped. A TO object that names only the target's key fields
+	* (`{ org: { id: 9 } }`) creates nothing: it is a reference to an existing
+	* parent, so it becomes the row's foreign key (the existence check follows
+	* with the other FK validation). Runs before validation (which would demand
+	* the parent's required fields); any other TO object is left for
+	* {@link _rejectNestedToInIgnoreMode}.
+	*/
+	_linkToByKeyInIgnoreMode(items) {
+		for (const [navField, relation] of this._meta.relations) {
+			if (relation.direction !== "to") continue;
+			const fk = this._findFKForRelation(relation);
+			if (fk === void 0) continue;
+			for (const item of items) {
+				const nav = item[navField];
+				if (nav === void 0 || nav === null || typeof nav !== "object" || Array.isArray(nav)) continue;
+				const target = nav;
+				const keys = Object.keys(target);
+				if (!(keys.length === fk.targetFields.length && fk.targetFields.every((f) => keys.includes(f) && target[f] != null))) continue;
+				fk.localFields.forEach((local, i) => {
+					const value = target[fk.targetFields[i]];
+					if (item[local] !== void 0 && item[local] !== null && !sameKey(item[local], value)) throw new DbError("INVALID_QUERY", [{
+						path: navField,
+						message: `"${navField}" and "${local}" name different parents`
+					}]);
+					item[local] = value;
+				});
+				delete item[navField];
+			}
+		}
+	}
+	/** Ignore mode: whatever TO object is left would create a related parent (see {@link _linkToByKeyInIgnoreMode}). */
+	_rejectNestedToInIgnoreMode(items) {
+		for (const [navField, relation] of this._meta.relations) {
+			if (relation.direction !== "to") continue;
+			if (items.some((item) => item[navField] !== void 0 && item[navField] !== null)) throw new DbError("INVALID_QUERY", [{
+				path: navField,
+				message: "onConflict \"ignore\" cannot create a related parent record — insert it first or reference it by key"
+			}]);
+		}
+	}
+	/**
+	* Conflict-ignoring main insert: marks rows repeating an earlier row's
+	* primary / unique key tuple (NULL components never collide), sends the rest
+	* to the adapter and assembles one slot per input row.
+	*/
+	async _insertIgnoring(prepared) {
+		const keySets = this.uniqueKeySets;
+		const seen = keySets.map(() => /* @__PURE__ */ new Set());
+		const conflictAt = /* @__PURE__ */ new Set();
+		const send = [];
+		for (let i = 0; i < prepared.length; i++) {
+			const row = prepared[i];
+			const tuples = keySets.map((fields) => uniqueKeyTuple(row, fields));
+			if (tuples.some((t, k) => t !== void 0 && seen[k].has(t))) {
+				conflictAt.add(i);
+				continue;
+			}
+			tuples.forEach((t, k) => {
+				if (t !== void 0) seen[k].add(t);
+			});
+			send.push(i);
+		}
+		const slots = send.length ? await this.adapter.insertManyIgnore(send.map((i) => prepared[i])) : [];
+		if (slots.length !== send.length) throw new DbError("INVALID_QUERY", [{
+			path: "",
+			message: "Adapter insertManyIgnore must return one slot per input row"
+		}]);
+		const insertedIds = [];
+		const inserted = [];
+		send.forEach((rowIndex, k) => {
+			const slot = slots[k];
+			if (slot) {
+				inserted.push(rowIndex);
+				insertedIds.push(slot.insertedId);
+			} else conflictAt.add(rowIndex);
+		});
+		return {
+			insertedCount: insertedIds.length,
+			insertedIds,
+			inserted,
+			conflicts: [...conflictAt].toSorted((a, b) => a - b)
+		};
+	}
+	/**
 	* The exact primary-key filter of each inserted row: the logical key from
 	* the row (SDK defaults applied), else the stored key the adapter wrote into
 	* the prepared row (e.g. a driver-assigned `_id`), else — single-field keys
@@ -5794,8 +6991,16 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 };
 //#endregion
 //#region src/table/db-view.ts
-/** The `@db.agg.*` annotations, one per supported aggregate function. */
-const AGG_KEYS = SUPPORTED_AGGREGATE_FNS.map((fn) => `db.agg.${fn}`);
+/**
+* The single `@meta.id` field of a first-row join target (its source type,
+* past `@db.alias`) — the anchor of the join's correlated subquery.
+* @throws when the target declares no or several primary-key fields.
+*/
+function firstJoinKey(view, type, scope) {
+	const ids = type.type.kind === "object" ? [...type.type.props.entries()].filter(([, p]) => p.metadata.has("meta.id")) : [];
+	if (ids.length !== 1) throw new Error(`View "${view}": the first-row join on "${scope}" needs a target with exactly one @meta.id field (found ${ids.length})`);
+	return ids[0][0];
+}
 /**
 * Reads a view field's `@db.agg.*` annotation. The compiled value is
 * `{ field?, condition? }`; models compiled by older versions carry `true`
@@ -5803,7 +7008,7 @@ const AGG_KEYS = SUPPORTED_AGGREGATE_FNS.map((fn) => `db.agg.${fn}`);
 * A missing field or `true` is `'*'` (COUNT(*)).
 */
 function readViewAgg(metadata) {
-	for (const key of AGG_KEYS) {
+	for (const key of AGG_ANNOTATIONS) {
 		const val = metadata?.get(key);
 		if (val === void 0) continue;
 		const aggFn = key.slice(7);
@@ -5881,7 +7086,9 @@ function inheritViewFieldSeals(viewType) {
 	try {
 		const forRef = viewType.metadata.get("db.view.for");
 		const entryType = forRef && refType(forRef);
-		for (const [fieldName, fieldType] of viewType.type.props.entries()) {
+		const props = viewType.type.props;
+		for (const [fieldName, fieldType] of props.entries()) {
+			if (computeOf(fieldType) !== void 0) continue;
 			const { agg, sourceType, sourcePath } = viewFieldSource(fieldName, fieldType, entryType);
 			if (agg?.aggField === "*" || !sourceType) continue;
 			const source = viewSourceOf(sourceType).type;
@@ -5892,6 +7099,14 @@ function inheritViewFieldSeals(viewType) {
 			if (agg) throw new Error(`View "${tableNameOf(viewType)}" field "${fieldName}": @db.agg.${agg.aggFn} over the @db.encrypted field "${sourcePath}" — ciphertext cannot be aggregated`);
 			fieldType.metadata.set("db.encrypted", true);
 		}
+		for (const [fieldName, fieldType] of props.entries()) {
+			const computed = computedOperands(viewType, fieldName);
+			if (!computed) continue;
+			const { operands, via } = computed;
+			const encrypted = operands.find((p) => props.get(p)?.metadata.has("db.encrypted"));
+			if (encrypted) throw new Error(`View "${tableNameOf(viewType)}": @db.compute over the @db.encrypted field "${encrypted}" — ciphertext cannot be computed`);
+			if ([...operands, ...via].some((p) => props.get(p)?.metadata.has("db.writeOnly"))) fieldType.metadata.set("db.writeOnly", true);
+		}
 	} catch (error) {
 		sealedViews.delete(viewType);
 		throw error;
@@ -5954,13 +7169,39 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		if (rawJoins) for (const join of rawJoins) {
 			const targetType = refType(join.target);
 			const target = viewSourceOf(targetType());
-			joins.push({
+			const viewJoin = {
 				targetType,
 				targetTable: target.table,
 				scope: target.name,
 				condition: join.condition,
 				kind: join.kind === "left" ? "left" : "inner"
-			});
+			};
+			if (join.order?.length) {
+				const key = firstJoinKey(this.tableName, target.type, target.name);
+				const order = join.order.map((item) => {
+					const seals = sourceFieldSeals(target.type, item.ref.field);
+					if (seals.encrypted || seals.writeOnly) throw new Error(`View "${this.tableName}": the first-row join on "${target.name}" cannot order by the ${seals.encrypted ? "@db.encrypted" : "@db.writeOnly"} field "${item.ref.field}"`);
+					return {
+						ref: {
+							type: targetType,
+							field: item.ref.field
+						},
+						desc: item.desc === true
+					};
+				});
+				if (!order.some((item) => item.ref.field === key)) order.push({
+					ref: {
+						type: targetType,
+						field: key
+					},
+					desc: false
+				});
+				viewJoin.first = {
+					order,
+					key
+				};
+			}
+			joins.push(viewJoin);
 		}
 		const filter = metadata.get("db.view.filter");
 		const having = metadata.get("db.view.having");
@@ -6037,6 +7278,26 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		this._columnMappings ??= this._buildColumnMappings();
 		return this._columnMappings;
 	}
+	/**
+	* Why the bound adapter cannot render this managed view: one message per
+	* computed column / first-row join whose feature its `viewCapabilities()`
+	* does not list. Empty for an external view or when every feature is
+	* rendered. Schema sync refuses such a view; the adapter's `ensureTable()`
+	* throws for it (fail-closed for adapters that predate the features).
+	* @since 0.1.147
+	*/
+	viewCapabilityProblems() {
+		if (this.isExternal) return [];
+		const caps = this.dbAdapter.viewCapabilities();
+		const problems = [];
+		if (!caps.has("compute")) {
+			for (const col of this.getViewColumnMappings()) if (col.expr !== void 0) problems.push(`View "${this.tableName}" field "${col.viewPath}": computed columns (@db.compute) are not supported by this adapter (viewCapabilities())`);
+		}
+		if (!caps.has("firstJoin")) {
+			for (const join of this.viewPlan.joins) if (join.first) problems.push(`View "${this.tableName}" join "${join.scope}": first-row joins are not supported by this adapter (viewCapabilities())`);
+		}
+		return problems;
+	}
 	_buildColumnMappings() {
 		const plan = this.viewPlan;
 		const mappings = [];
@@ -6051,6 +7312,17 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		const leftJoined = new Set(plan.joins.filter((j) => j.kind === "left").map((j) => j.scope));
 		for (const [fieldName, fieldType] of this._type.type.props.entries()) {
 			if (ignored.has(fieldName)) continue;
+			const expr = computeOf(fieldType);
+			if (expr !== void 0) {
+				mappings.push({
+					viewColumn: viewName(fieldName) ?? fieldName,
+					viewPath: fieldName,
+					sourceTable: plan.entryTable,
+					sourceColumn: "",
+					expr
+				});
+				continue;
+			}
 			const { agg, chained, sourceType, sourcePath } = viewFieldSource(fieldName, fieldType, plan.entryType);
 			const aggField = agg?.aggField;
 			if (aggField === "*" && agg?.aggFn !== "count") fail(fieldName, `aggregate "${agg?.aggFn}" needs a field — only count accepts *`);
@@ -6087,8 +7359,37 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 				...agg
 			} : mapping);
 		}
+		this._checkComputed(mappings, fail);
 		return mappings;
 	}
+	/**
+	* The runtime twin of the compile-time `@db.compute` rules the renderers
+	* rely on: every leaf names a (non-ignored) view column, computed columns
+	* form no cycle; sets each computed mapping's `nullable`.
+	*/
+	_checkComputed(mappings, fail) {
+		const computed = mappings.filter((m) => m.expr !== void 0);
+		if (computed.length === 0) return;
+		const byPath = new Map(mappings.map((m) => [m.viewPath, m]));
+		const props = this._type.type.kind === "object" ? this._type.type.props : void 0;
+		const state = /* @__PURE__ */ new Map();
+		const visit = (m, chain) => {
+			if (state.get(m.viewPath) === "done") return;
+			if (state.get(m.viewPath) === "visiting") fail(m.viewPath, `@db.compute depends on itself: ${[...chain, m.viewPath].join(" → ")}`);
+			state.set(m.viewPath, "visiting");
+			walkViewExpr(m.expr, (path) => {
+				const leaf = byPath.get(path);
+				if (!leaf) fail(m.viewPath, `@db.compute references "${path}", which is not a column of the view`);
+				if (leaf.expr !== void 0) visit(leaf, [...chain, m.viewPath]);
+			});
+			state.set(m.viewPath, "done");
+			if (viewExprNullable(m.expr, (path) => {
+				const leaf = byPath.get(path);
+				return leaf.expr === void 0 ? props?.get(path)?.optional === true : leaf.nullable === true;
+			})) m.nullable = true;
+		};
+		for (const m of computed) visit(m, []);
+	}
 	/** One view column over one physical source (a column or a JSON leaf). */
 	_leafMapping(viewPath, viewColumn, sourceTable, source, joinNullable) {
 		const mapping = {
@@ -6121,6 +7422,62 @@ function isAtscriptDbView(readable) {
 	return readable.isView;
 }
 //#endregion
+//#region src/schema/fk-diff.ts
+/** Canonical key for an FK: sorted local field names, comma-joined. */
+function fkKey(fields) {
+	return [...fields].toSorted().join(",");
+}
+/**
+* Physical local / target column names of a desired FK (`@db.column` renames
+* applied) — what DDL, constraint sync, the FK diff and the snapshot compare.
+*/
+function fkColumns(fk) {
+	return {
+		fields: fk.physicalFields ?? fk.fields,
+		targetFields: fk.physicalTargetFields ?? fk.targetFields
+	};
+}
+/**
+* Compares desired FK constraints against stored snapshot to detect
+* additions, removals, and property changes (target table, target fields,
+* onDelete, onUpdate).
+*/
+function computeForeignKeyDiff(desired, existingSnapshot) {
+	const added = [];
+	const removed = [];
+	const changed = [];
+	const existingByKey = /* @__PURE__ */ new Map();
+	for (const fk of existingSnapshot) existingByKey.set(fkKey(fk.fields), fk);
+	const desiredKeys = /* @__PURE__ */ new Set();
+	for (const fk of desired.values()) {
+		const key = fkKey(fkColumns(fk).fields);
+		desiredKeys.add(key);
+		const existing = existingByKey.get(key);
+		if (!existing) added.push(fk);
+		else if (fkPropertiesDiffer(fk, existing)) changed.push({
+			desired: fk,
+			existing
+		});
+	}
+	for (const [key, fk] of existingByKey) if (!desiredKeys.has(key)) removed.push(fk);
+	return {
+		added,
+		removed,
+		changed
+	};
+}
+/** Whether the FK diff contains any changes. */
+function hasForeignKeyChanges(diff) {
+	return diff.added.length > 0 || diff.removed.length > 0 || diff.changed.length > 0;
+}
+function fkPropertiesDiffer(desired, existing) {
+	if (desired.targetTable !== existing.targetTable) return true;
+	if (fkKey(fkColumns(desired).targetFields) !== fkKey(existing.targetFields)) return true;
+	if ((desired.onDelete ?? void 0) !== (existing.onDelete ?? void 0)) return true;
+	if ((desired.onUpdate ?? void 0) !== (existing.onUpdate ?? void 0)) return true;
+	return false;
+}
+//#endregion
 //#region src/schema/schema-hash.ts
 /**
 * The physical sources a stored view snapshot reads: its entry table and the
@@ -6187,9 +7544,9 @@ function computeTableSnapshot(readable, typeMapper, tableOptions) {
 		}))
 	})).toSorted((a, b) => a.key.localeCompare(b.key));
 	const foreignKeys = [...readable.foreignKeys.values()].map((fk) => ({
-		fields: [...fk.fields].toSorted(),
+		fields: [...fkColumns(fk).fields].toSorted(),
 		targetTable: fk.targetTable,
-		targetFields: [...fk.targetFields].toSorted(),
+		targetFields: [...fkColumns(fk).targetFields].toSorted(),
 		onDelete: fk.onDelete,
 		onUpdate: fk.onUpdate
 	})).toSorted((a, b) => a.fields.join(",").localeCompare(b.fields.join(",")));
@@ -6217,7 +7574,9 @@ function computeViewSnapshot(view) {
 	const plan = view.viewPlan;
 	const qualify = (ref) => view.resolveFieldRef(ref, (n) => n);
 	const canonical = (node) => JSON.stringify(canonicalizeQueryNode(node, qualify));
-	const columns = view.getViewColumnMappings().map((m) => {
+	const mappings = view.getViewColumnMappings();
+	const columnOf = new Map(mappings.map((m) => [m.viewPath, m.viewColumn]));
+	const columns = mappings.map((m) => {
 		const col = {
 			column: m.viewColumn,
 			sourceTable: m.sourceTable,
@@ -6230,6 +7589,7 @@ function computeViewSnapshot(view) {
 		if (m.aggFn) col.aggFn = m.aggFn;
 		if (m.aggField) col.aggField = m.aggField;
 		if (m.aggFilter) col.aggFilter = canonical(m.aggFilter);
+		if (m.expr !== void 0) col.expr = JSON.stringify(canonicalizeViewExpr(m.expr, (path) => columnOf.get(path) ?? path));
 		return col;
 	}).toSorted((a, b) => a.column < b.column ? -1 : a.column > b.column ? 1 : 0);
 	const result = {
@@ -6243,6 +7603,7 @@ function computeViewSnapshot(view) {
 				condition: canonical(j.condition)
 			};
 			if (j.kind === "left") join.kind = "left";
+			if (j.first) join.order = JSON.stringify(j.first.order.map((item) => [qualify(item.ref), item.desc ? -1 : 1]));
 			return join;
 		}),
 		columns
@@ -6281,6 +7642,20 @@ function canonicalizeQueryNode(node, qualify) {
 	return out;
 }
 /**
+* Converts a `@db.compute` expression into a serializable structure whose
+* JSON is a stable function of its meaning: leaves become the view column
+* they read (`column(path)`), literals `{ n }`, operations `{ op, a }`.
+* @since 0.1.147
+*/
+function canonicalizeViewExpr(expr, column) {
+	if (typeof expr === "number") return { n: expr };
+	if ("field" in expr) return { c: column(expr.field) };
+	return {
+		op: expr.op,
+		a: expr.args.map((arg) => canonicalizeViewExpr(arg, column))
+	};
+}
+/**
 * Computes a deterministic hash string from multiple table snapshots.
 * Uses FNV-1a for speed — not cryptographic, just needs stability + collision resistance.
 */
@@ -6344,52 +7719,6 @@ function fnv1a(str) {
 	return Math.trunc(hash).toString(16).padStart(8, "0");
 }
 //#endregion
-//#region src/schema/fk-diff.ts
-/** Canonical key for an FK: sorted local field names, comma-joined. */
-function fkKey(fields) {
-	return [...fields].toSorted().join(",");
-}
-/**
-* Compares desired FK constraints against stored snapshot to detect
-* additions, removals, and property changes (target table, target fields,
-* onDelete, onUpdate).
-*/
-function computeForeignKeyDiff(desired, existingSnapshot) {
-	const added = [];
-	const removed = [];
-	const changed = [];
-	const existingByKey = /* @__PURE__ */ new Map();
-	for (const fk of existingSnapshot) existingByKey.set(fkKey(fk.fields), fk);
-	const desiredKeys = /* @__PURE__ */ new Set();
-	for (const fk of desired.values()) {
-		const key = fkKey(fk.fields);
-		desiredKeys.add(key);
-		const existing = existingByKey.get(key);
-		if (!existing) added.push(fk);
-		else if (fkPropertiesDiffer(fk, existing)) changed.push({
-			desired: fk,
-			existing
-		});
-	}
-	for (const [key, fk] of existingByKey) if (!desiredKeys.has(key)) removed.push(fk);
-	return {
-		added,
-		removed,
-		changed
-	};
-}
-/** Whether the FK diff contains any changes. */
-function hasForeignKeyChanges(diff) {
-	return diff.added.length > 0 || diff.removed.length > 0 || diff.changed.length > 0;
-}
-function fkPropertiesDiffer(desired, existing) {
-	if (desired.targetTable !== existing.targetTable) return true;
-	if (fkKey(desired.targetFields) !== fkKey(existing.targetFields)) return true;
-	if ((desired.onDelete ?? void 0) !== (existing.onDelete ?? void 0)) return true;
-	if ((desired.onUpdate ?? void 0) !== (existing.onUpdate ?? void 0)) return true;
-	return false;
-}
-//#endregion
 //#region src/schema/column-diff.ts
 /**
 * Why a derived column (desired, live, or both) must be dropped and re-added,
@@ -6518,4 +7847,4 @@ function computeColumnDiff(desired, existing, typeMapper, opts) {
 	return diff;
 }
 //#endregion
-export { isGeoIndexableType as $, vectorIndexNotFoundMessage as A, guardAggregate as B, createFailureCollector as C, resolveDesignType as D, AtscriptDbReadable as E, bucketSourceVerdict as F, narrowerFilterOps as G, guardPath as H, canFilterLeaf as I, RelationalFieldMapper as J, sortFieldNames as K, checkHavingKeys as L, ENCRYPTED_REASON as M, acceptedOperatorsHint as N, geoIndexNotFoundMessage as O, assertGeoPoint as P, TableMetadata as Q, classifyQueryPath as R, BaseDbAdapter as S, NativeIntegrity as T, guardPaths as U, guardFilter as V, guardQuery as W, FieldMappingStrategy as X, DocumentFieldMapper as Y, UniquSelect as Z, AtscriptDbTable as _, hasForeignKeyChanges as a, normalizeComputedSelect as at, ApplicationIntegrity as b, computeTableHash as c, snapshotToExistingColumns as d, isGeoPointType as et, snapshotToExistingTableOptions as f, isViewType as g, isAtscriptDbView as h, fkKey as i, jsonValueAncestor as it, ADAPTER_FILTER_REASON as j, searchIndexNotFoundMessage as k, computeTableSnapshot as l, AtscriptDbView as m, isColumnTypeChanged as n, isBucketableField as nt, canonicalizeQueryNode as o, resolveCalendarBuckets as ot, viewSnapshotSources as p, unsupportedOperatorMessage as q, computeForeignKeyDiff as r, isJsonValueField as rt, computeSchemaHash as s, NoopLogger as st, computeColumnDiff as t, aliasTargetOf as tt, computeViewSnapshot as u, assertNoVersionWrites as v, IntegrityStrategy as w, ALL_BUCKET_UNITS as x, decomposePatch as y, collectQueryPaths as z };
+export { FieldMappingStrategy as $, geoIndexNotFoundMessage as A, classifyQueryPath as B, ALL_VIEW_CAPABILITIES as C, NativeIntegrity as D, IntegrityStrategy as E, acceptedOperatorsHint as F, guardPath as G, groupSourceVerdict as H, assertGeoPoint as I, narrowerFilterOps as J, guardPaths as K, bucketSourceVerdict as L, vectorIndexNotFoundMessage as M, ADAPTER_FILTER_REASON as N, AtscriptDbReadable as O, ENCRYPTED_REASON as P, DocumentFieldMapper as Q, canFilterLeaf as R, ALL_BUCKET_UNITS as S, createFailureCollector as T, guardAggregate as U, collectQueryPaths as V, guardFilter as W, unsupportedOperatorMessage as X, sortFieldNames as Y, RelationalFieldMapper as Z, isViewType as _, computeTableHash as a, aliasTargetOf as at, decomposePatch as b, snapshotToExistingColumns as c, jsonValueAncestor as ct, computeForeignKeyDiff as d, NoopLogger as dt, UniquSelect as et, fkColumns as f, isAtscriptDbView as g, AtscriptDbView as h, computeSchemaHash as i, isGeoPointType as it, searchIndexNotFoundMessage as j, resolveDesignType as k, snapshotToExistingTableOptions as l, normalizeComputedSelect as lt, hasForeignKeyChanges as m, isColumnTypeChanged as n, TableMetadata as nt, computeTableSnapshot as o, isBucketableField as ot, fkKey as p, guardQuery as q, canonicalizeQueryNode as r, isGeoIndexableType as rt, computeViewSnapshot as s, isJsonValueField as st, computeColumnDiff as t, numericOperandProblem as tt, viewSnapshotSources as u, resolveCalendarBuckets as ut, AtscriptDbTable as v, BaseDbAdapter as w, ApplicationIntegrity as x, assertNoVersionWrites as y, checkHavingKeys as z };