@atscript/db 0.1.147 → 0.1.148

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

@@ -1,13 +1,15 @@
-import { n as CasMismatchError, r as DbError } from "./db-error-D5uilS_A.mjs";
-import { a as SUPPORTED_AGGREGATE_FNS, r as BASE_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-C0BymEqa.mjs";
-import { A as noteRelationFilter, B as tableNameOf, E as createRelationFilterHost, F as findFKEntryForRelation, G as viewExprNullable, H as computedOperands, I as findFKForRelation, K as walkViewExpr, L as findRemoteFK, N as resolveRelationFilterTree, O as hasRelationOp, P as compositeKey, T as containsRelationFilter, V as computeOf, _ 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 relGuardState, 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, y as rowMatchesKey, z as slicePerGroup } from "./nested-writer-D35UsDBT.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, isRelationOp, 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
@@ -1126,6 +1154,194 @@ function computedMeta(rootType, path) {
 	} : 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
 /**
 * Wraps a raw `$select` value and provides lazy-cached conversions
@@ -1137,8 +1353,9 @@ function computedMeta(rootType, path) {
 * 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 {
@@ -1147,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
@@ -1157,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).
@@ -1215,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;
@@ -1318,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;
@@ -1356,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) => ({
@@ -1367,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
@@ -1404,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,
@@ -2030,7 +2385,7 @@ function acceptsScalar(kind, value) {
 		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" || typeof value === "bigint" || typeof value === "string" && NUMERIC_RE.test(value);
+		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;
 	}
@@ -2145,7 +2500,8 @@ function guardFilterValues(meta, filter) {
 }
 /**
 * `$having` values: an aggregate alias is a number (`count`,
-* `countDistinct`, `sum`, `avg`) or its source field's type (`min` / `max`),
+* `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.
 */
@@ -2153,11 +2509,12 @@ 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 (isAggregateExpr(item)) {
-			const fd = item.$fn === "min" || item.$fn === "max" ? meta.descriptorByPath.get(item.$field) : void 0;
+		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(item), fd ? valueTypeOf(meta, fd) : counts ? INTEGER : NUMBER);
-		} else if (isBucketExpr(item)) aliases.set(resolveAlias(item), STRING);
+			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);
@@ -2420,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
@@ -2446,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 };
 }
@@ -2478,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.
 *
@@ -2517,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);
@@ -2529,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;
 }
@@ -2704,7 +3095,7 @@ function guardQuery(meta, adapter, query, state) {
 	if (!query) return;
 	guardFilter(meta, adapter, query.filter);
 	guardSort(meta, query.controls?.$sort);
-	normalizeComputedSelect(query.controls, meta, false);
+	resolveComputedSelect(query.controls, meta, false);
 	guardPaths(meta, adapter, query, false, state);
 }
 /**
@@ -2733,30 +3124,45 @@ function checkHavingKeys(refs) {
 * ({@link checkHavingKeys} — after the path guard so an unknown key still
 * 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)
 * function this adapter does not render (`aggregateFns()`) with
 * `AGG_FN_NOT_SUPPORTED`, before anything is translated — an adapter written
@@ -2937,8 +3343,11 @@ 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._spaceClosed) throw spaceClosedError();
 		if (!this._meta.isBuilt) {
 			this._meta.build(this.type, this.adapter, this.logger);
 			if (this._meta.navFields.size > 0 && this._tableResolver) {
@@ -3104,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();
@@ -3303,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
@@ -3564,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", [{
@@ -3577,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",
@@ -3613,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() {
@@ -3630,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();
@@ -4038,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-C0qE8xgR.mjs").then((n) => n.n);
+		const { loadRelationsImpl } = await import("./relation-loader-ByY1Byrl.mjs").then((n) => n.n);
 		return loadRelationsImpl(rows, withRelations, this);
 	}
 	/**
@@ -4398,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
@@ -4779,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}
@@ -5561,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",
@@ -5610,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;
 		}));
@@ -6182,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
@@ -7265,4 +7847,4 @@ function computeColumnDiff(desired, existing, typeMapper, opts) {
 	return diff;
 }
 //#endregion
-export { UniquSelect as $, geoIndexNotFoundMessage as A, classifyQueryPath as B, ALL_VIEW_CAPABILITIES as C, NativeIntegrity as D, IntegrityStrategy as E, acceptedOperatorsHint as F, guardPaths as G, guardAggregate as H, assertGeoPoint as I, sortFieldNames as J, guardQuery as K, bucketSourceVerdict as L, vectorIndexNotFoundMessage as M, ADAPTER_FILTER_REASON as N, AtscriptDbReadable as O, ENCRYPTED_REASON as P, FieldMappingStrategy as Q, canFilterLeaf as R, ALL_BUCKET_UNITS as S, createFailureCollector as T, guardFilter as U, collectQueryPaths as V, guardPath as W, RelationalFieldMapper as X, unsupportedOperatorMessage as Y, DocumentFieldMapper as Z, isViewType as _, computeTableHash as a, isJsonValueField as at, decomposePatch as b, snapshotToExistingColumns as c, resolveCalendarBuckets as ct, computeForeignKeyDiff as d, TableMetadata as et, fkColumns as f, isAtscriptDbView as g, AtscriptDbView as h, computeSchemaHash as i, isBucketableField as it, searchIndexNotFoundMessage as j, resolveDesignType as k, snapshotToExistingTableOptions as l, NoopLogger as lt, hasForeignKeyChanges as m, isColumnTypeChanged as n, isGeoPointType as nt, computeTableSnapshot as o, jsonValueAncestor as ot, fkKey as p, narrowerFilterOps as q, canonicalizeQueryNode as r, aliasTargetOf as rt, computeViewSnapshot as s, normalizeComputedSelect as st, computeColumnDiff as t, isGeoIndexableType as tt, viewSnapshotSources as u, AtscriptDbTable as v, BaseDbAdapter as w, ApplicationIntegrity as x, assertNoVersionWrites as y, checkHavingKeys 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 };