@atscript/db 0.1.152 → 0.1.154

package/dist/{column-diff-CU7KHj9-.cjs → column-diff-qnzx1o3c.cjs}

@@ -1,12 +1,12 @@
-const require_db_error = require("./db-error-DRQH4sLY.cjs");
-const require_aggregate_fns = require("./aggregate-fns-C-UJRobm.cjs");
-const require_nested_writer = require("./nested-writer-BzbOPSUp.cjs");
+const require_db_error = require("./db-error-JcfJqqpk.cjs");
+const require_aggregate_fns = require("./aggregate-fns-DFtKAv7Q.cjs");
+const require_nested_writer = require("./nested-writer-Bl1SZS7x.cjs");
 const require_search_fields = require("./search-fields-DwrsJUC1.cjs");
 const require_object = require("./object-Djg28csK.cjs");
 require("./agg.cjs");
 const require_aggregate_rules = require("./aggregate-rules-D_bsCpUI.cjs");
 const require_ops = require("./ops.cjs");
-const require_validator = require("./validator-UcuJxHNT.cjs");
+const require_validator = require("./validator-BxWwh3wf.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _uniqu_core = require("@uniqu/core");
 let node_async_hooks = require("node:async_hooks");
@@ -252,6 +252,14 @@ function sourceFieldSeals(sourceType, logicalPath) {
 	return seals;
 }
 /**
+* The annotations of one LOGICAL path of a source table (`undefined` for a
+* path the type does not declare).
+* @since 0.1.153
+*/
+function sourceFieldMetadata(sourceType, logicalPath) {
+	return sourceIndex(sourceType).flatMap.get(logicalPath)?.metadata;
+}
+/**
 * Resolves a LOGICAL path of a source table (a view field's chain ref, an
 * aggregate's field, a predicate operand) to where it is physically stored.
 * Internal — `AtscriptDbView.resolveRefSource` is the public entry.
@@ -400,6 +408,26 @@ function rejectVersionExempt(path, why) {
 	throw new Error(`@db.column.version.exempt on "${path}": ${why}`);
 }
 /**
+* When `fieldType` is a union / tuple / intersection, marks the entries its
+* items already fired at the same `path` (onField is post-order) as members.
+*/
+function markComplexMembers(collected, path, fieldType) {
+	const kind = fieldType.type.kind;
+	if (kind !== "union" && kind !== "tuple" && kind !== "intersection") return;
+	const items = new Set(fieldType.type.items);
+	const childPrefix = `${path}.`;
+	for (let i = collected.length - 1; i >= 0; i--) {
+		const entry = collected[i];
+		if (entry.path === path) {
+			if (items.has(entry.type)) entry.member = true;
+		} else if (!entry.path.startsWith(childPrefix)) break;
+	}
+}
+/** A built-in primitive inlined as a member (`number.int | null`), not a named alias. */
+function isInlinePrimitive(type) {
+	return type.type.kind === "" && type.ref === void 0;
+}
+/**
 * Computed metadata for a database table or view.
 *
 * Contains all field metadata, physical mapping indexes, relation definitions,
@@ -439,6 +467,8 @@ var TableMetadata = class {
 	navFields = /* @__PURE__ */ new Set();
 	ignoredFields = /* @__PURE__ */ new Set();
 	uniqueProps = /* @__PURE__ */ new Set();
+	/** Adapter-contributed multi-field unique keys (logical paths) — see `TMetadataOverrides.addUniqueKeys`. */
+	uniqueKeys = [];
 	defaults = /* @__PURE__ */ new Map();
 	/** Logical path → `@db.column` override (top-level keys only on document storage). */
 	columnMap = /* @__PURE__ */ new Map();
@@ -579,7 +609,7 @@ var TableMetadata = class {
 			topLevelArrayTag: adapter.getTopLevelArrayTag?.() ?? "db.__topLevelArray",
 			excludePhantomTypes: true,
 			onField: (path, fieldType, metadata) => {
-				if (isNavRelation(metadata)) this.navFields.add(path);
+				markComplexMembers(collected, path, fieldType);
 				collected.push({
 					path,
 					type: fieldType,
@@ -587,11 +617,14 @@ var TableMetadata = class {
 				});
 			}
 		});
+		for (const entry of collected) if (!entry.member && isNavRelation(entry.metadata)) this.navFields.add(entry.path);
+		this._dropMemberMetadata(collected);
 		for (const entry of collected) {
 			if (require_object.findAncestorInSet(entry.path, this.navFields) !== void 0) {
 				this.ignoredFields.add(entry.path);
 				continue;
 			}
+			if (entry.member) continue;
 			this._scanGenericAnnotations(entry.path, entry.type, entry.metadata, logger);
 			if (entry.metadata.has("db.column.derived")) this.derivedFields.set(entry.path, this._validateDerivedField(entry.path, entry.type, entry.metadata, type));
 			adapter.onFieldScanned?.(entry.path, entry.type, entry.metadata);
@@ -625,6 +658,35 @@ var TableMetadata = class {
 		}
 	}
 	/**
+	* `flattenAnnotatedType` merges the metadata of every union / tuple member
+	* into the synthetic flat entry of the prop's path, so a member's
+	* annotations would reach the column (DDL type, size, default). Since
+	* atscript 0.1.103 a built-in primitive member carries its built-in
+	* annotations (`number.timestamp.created | null` → `@db.default.now`,
+	* `string.char` → `@expect.maxLength 1`). Rebuild such an entry from the
+	* prop's own annotations plus the non-`db.*` annotations of named members
+	* (aliases, interfaces), so the column is described as before 0.1.103.
+	*/
+	_dropMemberMetadata(collected) {
+		const byPath = /* @__PURE__ */ new Map();
+		for (const entry of collected) {
+			const list = byPath.get(entry.path);
+			if (list) list.push(entry);
+			else byPath.set(entry.path, [entry]);
+		}
+		for (const [path, entries] of byPath) {
+			if (!entries.some((e) => e.member)) continue;
+			const flat = this.flatMap.get(path);
+			if (!flat?.__flat_union) continue;
+			const target = flat.metadata;
+			target.clear();
+			for (const entry of entries) {
+				if (entry.member && isInlinePrimitive(entry.type)) continue;
+				for (const [key, value] of entry.metadata) if (!entry.member || !key.startsWith("db.")) target.set(key, value);
+			}
+		}
+	}
+	/**
 	* Applies adapter-provided metadata overrides atomically.
 	* Processing order: injectFields → removePrimaryKeys → addPrimaryKeys → addUniqueFields.
 	*/
@@ -638,6 +700,7 @@ var TableMetadata = class {
 			for (const field of overrides.addPrimaryKeys) if (!this.primaryKeys.includes(field)) this.primaryKeys.push(field);
 		}
 		if (overrides.addUniqueFields) for (const field of overrides.addUniqueFields) this.uniqueProps.add(field);
+		if (overrides.addUniqueKeys) this.uniqueKeys.push(...overrides.addUniqueKeys.map((key) => [...key]));
 	}
 	/**
 	* Scans `@db.*` and `@meta.id` annotations on a field during flattening.
@@ -992,7 +1055,11 @@ var TableMetadata = class {
 	_buildFieldDescriptors(adapter, rootType) {
 		const descriptors = [];
 		const skipFlattening = this.nestedObjects;
-		const indexedFields = new Set([...this.primaryKeys, ...this.uniqueProps]);
+		const indexedFields = new Set([
+			...this.primaryKeys,
+			...this.uniqueProps,
+			...this.uniqueKeys.flat()
+		]);
 		for (const index of this.indexes.values()) for (const f of index.fields) indexedFields.add(f.name);
 		for (const [path, type] of this.flatMap.entries()) {
 			if (!path) continue;
@@ -1187,6 +1254,8 @@ var TableMetadata = class {
 	*   overrides (`addUniqueFields`); these aren't reflected in
 	*   `this.indexes` but still legitimate addressing identifications.
 	*   Deduped against any single-field unique index already captured.
+	* - `this.uniqueKeys` — multi-field uniques contributed by adapter
+	*   overrides (`addUniqueKeys`).
 	*/
 	_buildIdentifications() {
 		const out = [];
@@ -1211,6 +1280,10 @@ var TableMetadata = class {
 				source: `unique:${field}`
 			});
 		}
+		for (const key of this.uniqueKeys) out.push({
+			fields: [...key],
+			source: `unique:${key.join("+")}`
+		});
 		this._identifications = out;
 	}
 	/** Legitimate row-identifier shapes — primary key first, then each unique index. */
@@ -1575,6 +1648,18 @@ function rewriteIntegerRegex(filter, meta) {
 }
 //#endregion
 //#region src/query/aggregate-expr.ts
+/**
+* Output aliases of the computed `$select` entries of a grouped query —
+* aggregates, expressions and calendar buckets (`$as`, else uniqu's
+* `resolveAlias`).
+*/
+function computedAliases(select) {
+	const aliases = /* @__PURE__ */ new Set();
+	if (!Array.isArray(select)) return aliases;
+	for (const item of select) if ((0, _uniqu_core.isAggregateExpr)(item) || (0, _uniqu_core.isBucketExpr)(item)) aliases.add((0, _uniqu_core.resolveAlias)(item));
+	else if ((0, _uniqu_core.isAggregateOfExpr)(item) || (0, _uniqu_core.isSelectArithExpr)(item)) aliases.add(item.$as);
+	return aliases;
+}
 /** Most nodes a group-level expression may have once the aliases it names are inlined (SQL repeats them). */
 const EXPANDED_MAX_NODES = 4 * _uniqu_core.ARITH_MAX_NODES;
 /** Most expanded nodes ALL the expression entries of one query may have together. */
@@ -2059,7 +2144,7 @@ var FieldMappingStrategy = class {
 	*/
 	translateAggregateQuery(query, meta, buckets, exprs = [], rowOrder) {
 		const controls = query.controls;
-		const aliases = this.computedAliasSet(controls.$select);
+		const aliases = computedAliases(controls.$select);
 		const physicalBuckets = buckets.map((b) => ({
 			...b,
 			field: this.physicalPath(b.field, meta),
@@ -2076,6 +2161,7 @@ var FieldMappingStrategy = class {
 				$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, computed) : void 0,
 				$sort: controls.$sort && this.physicalSort(controls.$sort, meta, aliases),
+				$nulls: controls.$nulls && this.physicalNulls(controls.$nulls, meta, aliases),
 				$having: controls.$having ? this.translateHaving(controls.$having, meta, aliases) : void 0
 			},
 			insights: query.insights
@@ -2099,13 +2185,6 @@ var FieldMappingStrategy = class {
 			...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 ((0, _uniqu_core.isAggregateExpr)(item) || (0, _uniqu_core.isBucketExpr)(item)) aliases.add((0, _uniqu_core.resolveAlias)(item));
-		else if ((0, _uniqu_core.isAggregateOfExpr)(item) || (0, _uniqu_core.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
@@ -2144,7 +2223,8 @@ var FieldMappingStrategy = class {
 		if (rowOrder?.length) {
 			order = rowOrder.map((k) => ({
 				column: this.physicalPath(k.field, meta),
-				desc: k.desc
+				desc: k.desc,
+				...k.nulls && { nulls: k.nulls }
 			}));
 			for (const pk of meta.primaryKeys) {
 				const column = this.physicalPath(pk, meta);
@@ -2194,9 +2274,20 @@ var FieldMappingStrategy = class {
 	}
 	/** `$sort` with physical keys; computed `aliases` (grouped queries) pass through. */
 	physicalSort(sort, meta, aliases) {
-		if (!this.renamesPaths(meta)) return sort;
+		return this.physicalKeys(sort, meta, aliases);
+	}
+	/**
+	* `$nulls` with physical keys, like {@link physicalSort}. The core hands
+	* over only the resolved entries (since 0.1.153).
+	*/
+	physicalNulls(nulls, meta, aliases) {
+		return this.physicalKeys(nulls, meta, aliases);
+	}
+	/** `map` with its field-path keys made physical; computed `aliases` pass through. */
+	physicalKeys(map, meta, aliases) {
+		if (!this.renamesPaths(meta)) return map;
 		const translated = {};
-		for (const [key, dir] of Object.entries(sort)) translated[aliases?.has(key) ? key : this.physicalPath(key, meta)] = dir;
+		for (const [key, value] of Object.entries(map)) translated[aliases?.has(key) ? key : this.physicalPath(key, meta)] = value;
 		return translated;
 	}
 	/**
@@ -2472,7 +2563,8 @@ var DocumentFieldMapper = class extends FieldMappingStrategy {
 				...controls,
 				$with: void 0,
 				$select: select ? new UniquSelect(select, meta.allPhysicalFields) : void 0,
-				$sort: controls?.$sort && this.physicalSort(controls.$sort, meta)
+				$sort: controls?.$sort && this.physicalSort(controls.$sort, meta),
+				$nulls: controls?.$nulls && this.physicalNulls(controls.$nulls, meta)
 			},
 			insights: query.insights
 		};
@@ -2663,6 +2755,7 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 			}
 			result.$sort = translated;
 		}
+		if (controls.$nulls) result.$nulls = this.physicalNulls(controls.$nulls, meta);
 		if (controls.$select) {
 			let translatedRaw;
 			if (Array.isArray(controls.$select)) {
@@ -3244,6 +3337,10 @@ function collectQueryPaths(query, aggregate) {
 	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));
+	const nulls = controls.$nulls;
+	if (require_object.isPlainObject(nulls)) {
+		for (const name of Object.keys(nulls)) if (!aliases.has(name) && !refs.sort.includes(name)) refs.sort.push(name);
+	}
 	if (refs.aggregateMode) collectFilterKeys(controls.$having, (path) => refs.having.push(path), aliases, refs);
 	return refs;
 }
@@ -3515,6 +3612,130 @@ function guardBucketUnits(adapter, buckets) {
 	}]);
 }
 //#endregion
+//#region src/query/nulls.ts
+/** Annotation key of a field's default NULL placement (`@db.sort.nulls`). */
+const SORT_NULLS_ANNOTATION = "db.sort.nulls";
+/**
+* Per-table NULL-placement resolution (since 0.1.153): built once per
+* readable, memoizing the per-path answers every sorted read asks for.
+*/
+var NullsSource = class {
+	_init;
+	_nullable = /* @__PURE__ */ new Map();
+	_hasDefaults;
+	constructor(_init) {
+		this._init = _init;
+	}
+	/** Whether any field carries a `@db.sort.nulls` default. */
+	hasDefaults() {
+		return this._hasDefaults ??= [...this._init.meta.flatMap.keys()].some((path) => this.defaultOf(path) !== void 0);
+	}
+	/** The `@db.sort.nulls` default of the LOGICAL field `path`, if any. */
+	defaultOf(path) {
+		const value = this._init.meta.flatMap.get(path)?.metadata.get(SORT_NULLS_ANNOTATION);
+		return (0, _uniqu_core.isNullsPlacement)(value) ? value : void 0;
+	}
+	/**
+	* Whether ordering by the LOGICAL field `path` can meet NULL (or a missing
+	* value): the field or one of its parent objects is optional, the field is
+	* a derived column, it is not a known field, or the source is a view. A
+	* `$nulls` entry on any other field changes nothing and is dropped, so the
+	* plain `ORDER BY` keeps using the index.
+	*/
+	nullable(path) {
+		let answer = this._nullable.get(path);
+		if (answer === void 0) {
+			answer = this._init.isView || this._nullableField(path);
+			this._nullable.set(path, answer);
+		}
+		return answer;
+	}
+	_nullableField(path) {
+		const { meta } = this._init;
+		const fd = meta.descriptorByPath.get(path);
+		if (!fd || fd.derived) return true;
+		for (let p = path;;) {
+			if (meta.flatMap.get(p)?.optional === true) return true;
+			const dot = p.lastIndexOf(".");
+			if (dot === -1) return false;
+			p = p.slice(0, dot);
+		}
+	}
+	/**
+	* The effective `$nulls` of the `$sort` keys of one read: the request's
+	* entry, else the field's `@db.sort.nulls` default; entries on fields that
+	* cannot be NULL ({@link nullable}) are dropped. `aliases` are the computed
+	* output names of a grouped read — they take a request entry only and are
+	* never dropped. Entries for keys that are not ordered by are ignored. On
+	* an adapter without support a request entry is refused and defaults are
+	* dropped.
+	*
+	* @returns LOGICAL keys (or aliases) → placement; `undefined` when none.
+	* @throws DbError `INVALID_QUERY` on a malformed `$nulls`, or a request
+	*   entry the adapter cannot honour.
+	*/
+	resolveSort(sort, rawNulls, aliases) {
+		const requested = checkNullsControl(rawNulls);
+		if (!require_object.isPlainObject(sort)) return void 0;
+		let nulls;
+		for (const key of Object.keys(sort)) {
+			const asked = requested && Object.hasOwn(requested, key) ? requested[key] : void 0;
+			const placement = aliases?.has(key) ? asked : this._placement(key, asked);
+			if (placement && this._allowed(asked)) (nulls ??= {})[key] = placement;
+		}
+		return nulls;
+	}
+	/**
+	* `$rowOrder` keys (as uniqu resolved them, `nulls` from the request) under
+	* the rules of {@link resolveSort}: defaults filled in, placements on
+	* fields that cannot be NULL (or on an unsupporting adapter) dropped.
+	*/
+	resolveRowOrder(rowOrder) {
+		return rowOrder?.map((key) => {
+			const placement = this._placement(key.field, key.nulls);
+			const nulls = placement && this._allowed(key.nulls) ? placement : void 0;
+			if (nulls === key.nulls) return key;
+			return nulls ? {
+				...key,
+				nulls
+			} : {
+				field: key.field,
+				desc: key.desc
+			};
+		});
+	}
+	/** The placement of field `path` — the request's `asked`, else its default — or `undefined` when it cannot be NULL. */
+	_placement(path, asked) {
+		return this.nullable(path) ? asked ?? this.defaultOf(path) : void 0;
+	}
+	/** Whether a placement may be forwarded; a requested one on an unsupporting adapter is refused. */
+	_allowed(asked) {
+		if (this._init.supported) return true;
+		if (asked) throw new require_db_error.DbError("INVALID_QUERY", [{
+			path: "$nulls",
+			message: `NULL placement ($nulls / :first / :last) is not supported by the adapter of "${this._init.tableName}"`
+		}]);
+		return false;
+	}
+};
+/**
+* The raw `$nulls` control as a checked map, or `undefined` when absent.
+* @throws DbError `INVALID_QUERY` (`path: "$nulls"`) on a non-object or a
+* value other than `'first'` / `'last'`.
+*/
+function checkNullsControl(raw) {
+	if (raw === void 0 || raw === null) return void 0;
+	if (!require_object.isPlainObject(raw)) throw new require_db_error.DbError("INVALID_QUERY", [{
+		path: "$nulls",
+		message: "$nulls must be an object of field → 'first' | 'last'"
+	}]);
+	for (const [field, value] of Object.entries(raw)) if (!(0, _uniqu_core.isNullsPlacement)(value)) throw new require_db_error.DbError("INVALID_QUERY", [{
+		path: "$nulls",
+		message: `$nulls "${field}" must be 'first' or 'last'`
+	}]);
+	return raw;
+}
+//#endregion
 //#region src/shared/index-messages.ts
 /**
 * Wording of the "index not found" errors — one source for the core, every
@@ -3598,6 +3819,26 @@ function resolveDefaultFromMetadata(metadata) {
 	};
 }
 /**
+* `query` with `$groupBy` defaulted to `[]` — an aggregate without one is the
+* ungrouped query (one group), as `$groupBy: []` documents it.
+* @throws DbError `INVALID_QUERY` when `$groupBy` is present but not an array.
+*/
+function withGroupBy(query) {
+	const controls = query.controls ?? {};
+	if (Array.isArray(controls.$groupBy)) return query;
+	if (controls.$groupBy !== void 0 && controls.$groupBy !== null) throw new require_db_error.DbError("INVALID_QUERY", [{
+		path: "$groupBy",
+		message: "$groupBy must be an array of field names"
+	}]);
+	return {
+		...query,
+		controls: {
+			...controls,
+			$groupBy: []
+		}
+	};
+}
+/**
 * Checks whether an id value is type-compatible with a field's design type.
 * Used by `findById` to skip primary-key lookup when the id clearly can't match,
 * falling through to unique-property search instead.
@@ -3739,7 +3980,7 @@ var AtscriptDbReadable = class {
 	_translateForAdapter(query) {
 		this._ensureBuilt();
 		this._guardQuery(query);
-		return this._fieldMapper.translateQuery(query, this._meta);
+		return this._fieldMapper.translateQuery(this._withStableSort(query), this._meta);
 	}
 	/**
 	* Physical rows of THIS table → logical rows (field mapping, value
@@ -3839,7 +4080,8 @@ var AtscriptDbReadable = class {
 	}
 	/**
 	* 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.
+	* followed by every unique index and every adapter-contributed unique field / key. Used by
+	* conflict-ignoring inserts and view read pruning.
 	* @since 0.1.148
 	*/
 	get uniqueKeySets() {
@@ -3856,6 +4098,7 @@ var AtscriptDbReadable = class {
 			const column = this._meta.physicalPath(prop);
 			if (!sets.some((s) => s.length === 1 && s[0] === column)) sets.push([column]);
 		}
+		for (const key of this._meta.uniqueKeys) sets.push(key.map((f) => this._meta.physicalPath(f)));
 		for (const set of sets) Object.freeze(set);
 		return Object.freeze(sets);
 	}
@@ -4100,6 +4343,7 @@ var AtscriptDbReadable = class {
 				widened = widen.added;
 			}
 		}
+		readQuery = this._withStableSort(readQuery);
 		return {
 			translated: this._fieldMapper.translateQuery(readQuery, this._meta),
 			controls: readQuery.controls,
@@ -4121,6 +4365,99 @@ var AtscriptDbReadable = class {
 		}
 		return rows;
 	}
+	/**
+	* `query` with {@link _withPkTieBreak} applied and its `$nulls` resolved
+	* ({@link NullsSource.resolveSort}) — a copy when either changes.
+	*/
+	_withStableSort(query) {
+		const controls = query.controls;
+		const raw = controls?.$nulls;
+		const source = this._nulls;
+		const nulls = raw !== void 0 || source.hasDefaults() ? source.resolveSort(controls?.$sort, raw) : void 0;
+		const sort = this._withPkTieBreak(controls);
+		if (!sort && nulls === raw) return query;
+		const next = { ...controls };
+		if (sort) next.$sort = sort;
+		if (nulls) next.$nulls = nulls;
+		else delete next.$nulls;
+		return {
+			...query,
+			controls: next
+		};
+	}
+	_nullsCache;
+	/** NULL-placement resolution for this table (`$nulls`, `@db.sort.nulls`; since 0.1.153). */
+	get _nulls() {
+		return this._nullsCache ??= new NullsSource({
+			meta: this._meta,
+			tableName: this.tableName,
+			isView: this.isView,
+			supported: this.adapter.supportsNullsPlacement()
+		});
+	}
+	/**
+	* `$sort` with the primary-key tie-breaker appended (since 0.1.153), or
+	* `undefined` when the read keeps its `$sort` as written. Rows that tie on
+	* every `$sort` key otherwise come back in an engine-chosen order that can
+	* differ between two reads, so offset pages overlap or skip rows. The
+	* primary-key fields the `$sort` leaves out are appended in declaration
+	* order, in the direction of the LAST `$sort` key (a backward index scan
+	* serves `amount DESC, id DESC`).
+	*
+	* Unchanged when there is no `$sort` (no order is imposed), when the
+	* `$sort` already names every field of the primary key or of a unique key
+	* over non-nullable fields ({@link _totalOrderKeys}), when the table has no
+	* primary key (a view without `@meta.id`), and on grouped / aggregate /
+	* `$count` reads. Search, vector and geo relevance is never touched: the
+	* key is appended only to an explicit `$sort`. Every read path applies it
+	* ({@link _translateRead}, and {@link _translateForAdapter} for a native
+	* `$with` loader), so nested relation rows get it too.
+	*/
+	_withPkTieBreak(controls) {
+		const sort = controls?.$sort;
+		if (!sort || typeof sort !== "object") return void 0;
+		const keys = Object.keys(sort);
+		if (keys.length === 0 || controls.$count) return void 0;
+		if (Array.isArray(controls.$groupBy) && controls.$groupBy.length > 0) return void 0;
+		const select = controls.$select;
+		if (Array.isArray(select) && select.some((item) => (0, _uniqu_core.isAggregateExpr)(item) || (0, _uniqu_core.isAggregateOfExpr)(item))) return;
+		const pk = this._meta.primaryKeys;
+		if (pk.length === 0) return void 0;
+		const sorted = new Set(keys.map((key) => this._meta.physicalPath(key)));
+		if (this._totalOrderKeys().some((set) => set.every((column) => sorted.has(column)))) return;
+		const dir = sort[keys[keys.length - 1]];
+		const next = { ...sort };
+		for (const field of pk) if (!sorted.has(this._meta.physicalPath(field))) next[field] = dir;
+		return next;
+	}
+	_totalOrderKeysCache;
+	/**
+	* Physical column sets that order rows totally: the primary key, then
+	* every unique index (and adapter-contributed unique field) whose fields
+	* are all non-nullable — a unique key over a nullable column admits
+	* several NULLs, so it does not.
+	*/
+	_totalOrderKeys() {
+		if (this._totalOrderKeysCache) return this._totalOrderKeysCache;
+		const meta = this._meta;
+		const nullable = (logical) => {
+			for (let path = logical;;) {
+				if (meta.flatMap.get(path)?.optional === true) return true;
+				const dot = path.lastIndexOf(".");
+				if (dot === -1) return false;
+				path = path.slice(0, dot);
+			}
+		};
+		const sets = [];
+		if (meta.primaryKeys.length > 0) sets.push(meta.primaryKeys.map((f) => meta.physicalPath(f)));
+		for (const index of meta.indexes.values()) {
+			if (index.type !== "unique") continue;
+			if (index.fields.every((f) => f.optional !== true && !nullable(meta.physicalToPath.get(f.name) ?? f.name))) sets.push(index.fields.map((f) => f.name));
+		}
+		for (const prop of meta.uniqueProps) if (!nullable(prop)) sets.push([meta.physicalPath(prop)]);
+		this._totalOrderKeysCache = sets;
+		return sets;
+	}
 	/** `$select` plus the join keys of `withRelations` it leaves out — `undefined` when none is missing. */
 	_widenSelectForWith(select, withRelations) {
 		const keys = /* @__PURE__ */ new Set();
@@ -4331,6 +4668,7 @@ var AtscriptDbReadable = class {
 	*/
 	async aggregate(query) {
 		this._ensureBuilt();
+		query = withGroupBy(query);
 		const { $groupBy, $select } = query.controls;
 		const computed = resolveComputedSelect(query.controls, this._meta, true);
 		const { buckets } = computed;
@@ -4389,11 +4727,36 @@ var AtscriptDbReadable = class {
 			if (!searchTerm.trim()) return query.controls.$count ? [{ count: 0 }] : [];
 		}
 		guardAggregate(this._meta, this.adapter, query, computed);
-		const dbQuery = this._fieldMapper.translateAggregateQuery(query, this._meta, buckets, computed.exprs, computed.rowOrder);
+		const ordered = this._aggregateNulls(query, computed.rowOrder);
+		const dbQuery = this._fieldMapper.translateAggregateQuery(ordered.query, this._meta, buckets, computed.exprs, ordered.rowOrder);
 		const results = await this.adapter.aggregate(dbQuery);
 		return this._fromRead(results, query.controls, this._aliasFields($select));
 	}
 	/**
+	* A grouped read's `$nulls` resolved for its `$sort` keys (computed aliases
+	* take a request entry only) and its `$rowOrder` keys — see
+	* {@link NullsSource}.
+	*/
+	_aggregateNulls(query, rowOrder) {
+		const controls = query.controls;
+		const source = this._nulls;
+		if (controls.$nulls === void 0 && !source.hasDefaults()) return {
+			query,
+			rowOrder
+		};
+		const nulls = source.resolveSort(controls.$sort, controls.$nulls, computedAliases(controls.$select));
+		const next = { ...controls };
+		if (nulls) next.$nulls = nulls;
+		else delete next.$nulls;
+		return {
+			query: {
+				...query,
+				controls: next
+			},
+			rowOrder: source.resolveRowOrder(rowOrder)
+		};
+	}
+	/**
 	* 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.
@@ -4427,6 +4790,14 @@ var AtscriptDbReadable = class {
 	aggregateFns() {
 		return this.adapter.aggregateFns();
 	}
+	/**
+	* Whether the adapter honours a requested NULL placement (`$nulls`,
+	* `@db.sort.nulls`) — proxies adapter capability.
+	* @since 0.1.153
+	*/
+	supportsNullsPlacement() {
+		return this.adapter.supportsNullsPlacement();
+	}
 	/** Whether the adapter can sort by a given field (proxies adapter capability). */
 	canSortField(fd) {
 		return this.adapter.canSortField(fd);
@@ -4831,7 +5202,7 @@ var AtscriptDbReadable = class {
 	* Public entry point for relation loading. Used by adapters for nested $with delegation.
 	*/
 	async loadRelations(rows, withRelations) {
-		const { loadRelationsImpl } = await Promise.resolve().then(() => require("./relation-loader-fNjHgBMs.cjs")).then((n) => n.relation_loader_exports);
+		const { loadRelationsImpl } = await Promise.resolve().then(() => require("./relation-loader-DeulLrAw.cjs")).then((n) => n.relation_loader_exports);
 		return loadRelationsImpl(rows, withRelations, this);
 	}
 	/**
@@ -5217,6 +5588,24 @@ var BaseDbAdapter = class {
 		return false;
 	}
 	/**
+	* Whether this adapter honours a requested NULL placement: `controls.$nulls`
+	* (PHYSICAL `$sort` keys → `'first'` / `'last'`, or computed aliases on a
+	* grouped read) and `TRowOrderKey.nulls` on the `first` / `last` row
+	* order. NULL (and, on document stores, a missing value) goes before or
+	* after every non-null value whatever the sort direction. The core only
+	* forwards entries for keys that can be NULL; a key without an entry keeps
+	* the adapter's native order (`$sort`) or "NULL is the smallest value"
+	* (grouped / row order). Default `false` (fail-closed): the core refuses a
+	* request naming a placement with `INVALID_QUERY` and drops
+	* `@db.sort.nulls` defaults. moost-db advertises it as
+	* `/meta.nullsPlacement`.
+	*
+	* @since 0.1.153
+	*/
+	supportsNullsPlacement() {
+		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
@@ -5240,6 +5629,18 @@ var BaseDbAdapter = class {
 		return NO_VIEW_CAPABILITIES;
 	}
 	/**
+	* Whether reads of a managed view drop the LEFT joins the query does not
+	* need (`AtscriptDbView.readPlan`) — reading through an inline, pruned
+	* definition instead of the stored view. Only adapters that implement it
+	* honour it; each sets its own default from its constructor options (the
+	* bundled MySQL, SQLite and MongoDB adapters: on; PostgreSQL removes such
+	* joins itself). Set it to `false` on one view's adapter
+	* (`space.getAdapter(View)`) to read that view by name again.
+	*
+	* @since 0.1.153
+	*/
+	viewJoinPruning = false;
+	/**
 	* 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`).
@@ -5617,10 +6018,13 @@ var BaseDbAdapter = class {
 	* 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}.
+	* {@link supportsInsertIgnore}. `opts` (since 0.1.153) tells whether the
+	* call joins a caller's transaction and whether to lock the stored rows the
+	* batch collides with — see {@link TDbInsertIgnoreOptions}; an adapter
+	* without row locks ignores it.
 	* @since 0.1.148
 	*/
-	insertManyIgnore(_data) {
+	insertManyIgnore(_data, _opts) {
 		return Promise.reject(new require_db_error.DbError("ON_CONFLICT_NOT_SUPPORTED", [{
 			path: "",
 			message: `The ${this.constructor.name} adapter does not support onConflict "ignore"`
@@ -6481,12 +6885,18 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	}
 	async _insertMany(payloads, opts) {
 		this._ensureBuilt();
-		const { _depth, _action, maxDepth: userMax, guard, check, onConflict } = opts ?? {};
+		const { _depth, _action, maxDepth: userMax, guard, check, onConflict, lockConflicts } = opts ?? {};
 		if (onConflict !== void 0 && onConflict !== "error" && onConflict !== "ignore") throw new require_db_error.DbError("INVALID_QUERY", [{
 			path: "onConflict",
 			message: `Unknown onConflict mode "${String(onConflict)}"`
 		}]);
 		const ignore = onConflict === "ignore";
+		if (lockConflicts && !ignore) throw new require_db_error.DbError("INVALID_QUERY", [{
+			path: "lockConflicts",
+			message: "lockConflicts requires onConflict \"ignore\""
+		}]);
+		const ignoreOpts = ignore ? { inCallerTransaction: this.adapter.isInTransaction() } : void 0;
+		if (ignoreOpts?.inCallerTransaction && lockConflicts) ignoreOpts.lockConflicts = true;
 		const maxDepth = userMax ?? 3;
 		const depth = _depth ?? 0;
 		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
@@ -6521,7 +6931,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			if (canNest) await require_nested_writer.preValidateNestedFrom(host, originals);
 			let ignored;
 			if (ignore) {
-				ignored = await this._insertIgnoring(prepared);
+				ignored = await this._insertIgnoring(prepared, ignoreOpts);
 				const keep = ignored.inserted;
 				items = keep.map((i) => items[i]);
 				originals = canNest ? keep.map((i) => originals[i]) : originals;
@@ -7170,7 +7580,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* primary / unique key tuple (NULL components never collide), sends the rest
 	* to the adapter and assembles one slot per input row.
 	*/
-	async _insertIgnoring(prepared) {
+	async _insertIgnoring(prepared, opts) {
 		const keySets = this.uniqueKeySets;
 		const seen = keySets.map(() => /* @__PURE__ */ new Set());
 		const conflictAt = /* @__PURE__ */ new Set();
@@ -7187,7 +7597,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			});
 			send.push(i);
 		}
-		const slots = send.length ? await this.adapter.insertManyIgnore(send.map((i) => prepared[i])) : [];
+		const slots = send.length ? await this.adapter.insertManyIgnore(send.map((i) => prepared[i]), opts) : [];
 		if (slots.length !== send.length) throw new require_db_error.DbError("INVALID_QUERY", [{
 			path: "",
 			message: "Adapter insertManyIgnore must return one slot per input row"
@@ -7448,6 +7858,231 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	}
 };
 //#endregion
+//#region src/table/view-read-plan.ts
+/** Design types whose `=` compares one scalar to one scalar on every engine. */
+const SCALAR_TYPES = new Set([
+	"string",
+	"number",
+	"boolean",
+	"decimal",
+	"bigint"
+]);
+/** The comparisons of a pure conjunction (nested `$and`s flattened), or `undefined` for any `$or` / `$not`. */
+function conjuncts(node, out = []) {
+	if ("$and" in node) {
+		for (const child of node.$and) if (!conjuncts(child, out)) return void 0;
+		return out;
+	}
+	if ("$or" in node || "$not" in node) return void 0;
+	out.push(node);
+	return out;
+}
+/** Every scope a predicate references (its field refs' tables). */
+function predicateScopes(host, node, out) {
+	if ("$and" in node || "$or" in node) {
+		const children = node;
+		for (const child of children.$and ?? children.$or ?? []) predicateScopes(host, child, out);
+		return out;
+	}
+	if ("$not" in node) return predicateScopes(host, node.$not, out);
+	const comp = node;
+	out.add(host.resolveRefSource(comp.left).table);
+	if (require_nested_writer.isFieldRef(comp.right)) out.add(host.resolveRefSource(comp.right).table);
+	return out;
+}
+/** Whether a literal `value` compares as the scalar design type `designType` (no implicit casts). */
+function literalMatches(value, designType) {
+	switch (typeof value) {
+		case "string": return designType === "string";
+		case "number": return designType === "number" || designType === "decimal";
+		case "boolean": return designType === "boolean";
+		default: return false;
+	}
+}
+/**
+* Whether the left join `join` matches AT MOST ONE target row per input row,
+* so dropping it (when nothing reads it) leaves every result row in place:
+*
+* - a first-row join (its ON pins the target's primary key to one value);
+* - otherwise its condition is a conjunction whose `=` comparisons pin EVERY
+*   column of one of the target's unique keys (primary key included) to a
+*   value that does not depend on the target — another scope's field of the
+*   same scalar design type that compares alike (collation, type overrides,
+*   table charset), or a literal of that type.
+*   Other conjuncts only narrow the match.
+*
+* Never for an inner join (it filters), a target that is a view (its
+* uniqueness is unknown), or a predicate with `$or` / `$not`. On a document
+* store every pinned key field must also be required: a unique index over an
+* optional field is partial there, and a missing value would match many.
+*/
+function atMostOneMatch(host, join) {
+	if (join.kind !== "left") return false;
+	const keySets = host.uniqueKeySets(join.targetType());
+	if (!keySets) return false;
+	if (join.first) return true;
+	const comparisons = conjuncts(join.condition);
+	if (!comparisons) return false;
+	const pinned = /* @__PURE__ */ new Set();
+	for (const node of comparisons) {
+		const comp = node;
+		if (comp.op !== "$eq" || comp.right === null || comp.right === void 0) continue;
+		const left = host.resolveRefSource(comp.left);
+		const rightRef = require_nested_writer.isFieldRef(comp.right) ? comp.right : void 0;
+		const right = rightRef ? host.resolveRefSource(rightRef) : void 0;
+		let target;
+		let other;
+		if (left.table === join.scope && right?.table !== join.scope) {
+			target = {
+				ref: comp.left,
+				source: left.source
+			};
+			other = right && rightRef ? {
+				ref: rightRef,
+				source: right.source
+			} : void 0;
+		} else if (right && rightRef && right.table === join.scope && left.table !== join.scope) {
+			target = {
+				ref: rightRef,
+				source: right.source
+			};
+			other = {
+				ref: comp.left,
+				source: left.source
+			};
+		} else continue;
+		const { source } = target;
+		if (source.jsonPath || source.flattened || !SCALAR_TYPES.has(source.designType)) continue;
+		if (host.nested && source.optional) continue;
+		const traits = host.fieldTraits(target.ref);
+		if (traits.encrypted) continue;
+		if (other) {
+			const o = other.source;
+			if (o.jsonPath || o.flattened || o.designType !== source.designType) continue;
+			const otherTraits = host.fieldTraits(other.ref);
+			if (otherTraits.encrypted || otherTraits.compare !== traits.compare) continue;
+		} else if (!literalMatches(comp.right, source.designType)) continue;
+		pinned.add(source.column);
+	}
+	return keySets.some((set) => set.length > 0 && set.every((column) => pinned.has(column)));
+}
+function prunerState(host) {
+	const plan = host.viewPlan;
+	if (plan.materialized || !plan.joins.some((j) => j.kind === "left")) return void 0;
+	const columns = host.getViewColumnMappings();
+	if (columns.some((c) => c.aggFn)) return void 0;
+	const joins = plan.joins.map((join) => {
+		const refs = predicateScopes(host, join.condition, /* @__PURE__ */ new Set());
+		for (const { ref } of join.first?.order ?? []) refs.add(host.resolveRefSource(ref).table);
+		refs.delete(join.scope);
+		return {
+			join,
+			droppable: atMostOneMatch(host, join),
+			refs
+		};
+	});
+	if (!joins.some((j) => j.droppable)) return void 0;
+	const base = new Set([plan.entryTable]);
+	if (plan.filter) predicateScopes(host, plan.filter, base);
+	for (const j of joins) if (!j.droppable) base.add(j.join.scope);
+	const byPath = new Map(columns.map((c) => [c.viewPath, c]));
+	const columnScopes = /* @__PURE__ */ new Map();
+	const scopesOf = (c) => {
+		let scopes = columnScopes.get(c);
+		if (scopes) return scopes;
+		scopes = /* @__PURE__ */ new Set();
+		columnScopes.set(c, scopes);
+		if (c.expr === void 0) scopes.add(c.sourceTable);
+		else {
+			const out = scopes;
+			require_nested_writer.walkViewExpr(c.expr, (path) => {
+				const leaf = byPath.get(path);
+				if (!leaf) {
+					for (const j of joins) out.add(j.join.scope);
+					return;
+				}
+				for (const scope of scopesOf(leaf)) out.add(scope);
+			});
+		}
+		return scopes;
+	};
+	for (const c of columns) scopesOf(c);
+	return {
+		base,
+		joins,
+		columnScopes,
+		byColumn: new Map(columns.map((c) => [c.viewColumn, c])),
+		columns
+	};
+}
+/**
+* The read planner of one managed view: memoised per dropped-join set.
+* @since 0.1.153
+*/
+var ViewReadPlanner = class {
+	_host;
+	_state;
+	_variants = /* @__PURE__ */ new Map();
+	constructor(_host) {
+		this._host = _host;
+	}
+	/** Whether any join of the view can ever be dropped. */
+	get prunable() {
+		return this._getState() !== void 0;
+	}
+	_getState() {
+		if (this._state === void 0) try {
+			this._state = prunerState(this._host) ?? null;
+		} catch {
+			this._state = null;
+		}
+		return this._state ?? void 0;
+	}
+	/** The mappings a needed (physical) name reads: exact, or a document path above / below it. */
+	_matching(state, name) {
+		const exact = state.byColumn.get(name);
+		if (exact) return [exact];
+		return state.columns.filter((c) => name.startsWith(`${c.viewColumn}.`) || c.viewColumn.startsWith(`${name}.`));
+	}
+	plan(needed) {
+		const state = this._getState();
+		if (!state) return void 0;
+		const keep = new Set(state.base);
+		const read = needed === void 0 ? state.columns : [...needed].flatMap((n) => this._matching(state, n));
+		for (const c of read) for (const scope of state.columnScopes.get(c)) keep.add(scope);
+		const dropped = [];
+		for (let i = state.joins.length - 1; i >= 0; i--) {
+			const { join, droppable, refs } = state.joins[i];
+			if (droppable && !keep.has(join.scope)) dropped.push(join.scope);
+			else for (const scope of refs) keep.add(scope);
+		}
+		if (dropped.length === 0) return void 0;
+		dropped.reverse();
+		const key = dropped.join("\0");
+		let variant = this._variants.get(key);
+		if (!variant) {
+			const gone = new Set(dropped);
+			const plan = this._host.viewPlan;
+			const columns = [];
+			const droppedColumns = [];
+			for (const c of state.columns) if ([...state.columnScopes.get(c)].some((scope) => gone.has(scope))) droppedColumns.push(c.viewColumn);
+			else columns.push(c);
+			variant = {
+				plan: {
+					...plan,
+					joins: plan.joins.filter((j) => !gone.has(j.scope))
+				},
+				columns,
+				dropped,
+				droppedColumns,
+				key
+			};
+			this._variants.set(key, variant);
+		}
+		return variant;
+	}
+};
+//#endregion
 //#region src/table/db-view.ts
 /**
 * The single `@meta.id` field of a first-row join target (its source type,
@@ -7511,6 +8146,22 @@ function viewFieldSource(fieldName, fieldType, entryType) {
 		sourcePath: aggField && aggField !== "*" ? aggField : fieldName
 	};
 }
+/**
+* Field annotations that change how a column compares (`=`): its collation
+* and engine-type overrides. Two columns of a join condition must agree on
+* them (and on {@link COMPARE_TABLE_KEYS}) for the condition to prove a
+* unique-key match (`AtscriptDbView.readPlan`).
+*/
+const COMPARE_FIELD_KEYS = [
+	"db.column.collate",
+	"db.mysql.type",
+	"db.mysql.collate",
+	"db.mysql.charset",
+	"db.pg.type",
+	"db.pg.collate"
+];
+/** Table annotations that set its columns' default charset / collation. */
+const COMPARE_TABLE_KEYS = ["db.mysql.charset", "db.mysql.collate"];
 /** View types whose fields already carry their inherited seals. */
 const sealedViews = /* @__PURE__ */ new WeakSet();
 /**
@@ -7586,6 +8237,7 @@ function inheritViewFieldSeals(viewType) {
 var AtscriptDbView = class extends AtscriptDbReadable {
 	_viewPlan;
 	_columnMappings;
+	_readPlanner;
 	get isView() {
 		return true;
 	}
@@ -7737,6 +8389,53 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		return this._columnMappings;
 	}
 	/**
+	* The read variant of this managed view for a query that reads only the
+	* `needed` PHYSICAL view columns (`undefined`: every column) — the view
+	* plan with every LEFT join removed that (a) matches at most one row per
+	* input row and (b) feeds no needed column, no other kept join's ON clause
+	* and no `@db.view.filter`. Dropping such a join leaves every row of the
+	* view in place, so a query over the variant returns exactly what it
+	* returns over the view. `undefined` when nothing can be dropped.
+	*
+	* At most one match is proven from the model: a first-row join, or an ON
+	* clause whose `=` conjuncts pin every column of one of the target's unique
+	* keys (primary key included) — see the views guide. Inner joins, joins to
+	* a view, grouped (`@db.agg.*`), materialized and external views are never
+	* pruned. A variant's {@link TViewReadPlan.columns} omit the columns of the
+	* dropped joins, so a column reference the caller failed to declare fails
+	* loudly instead of reading wrong data.
+	*
+	* Memoised per dropped-join set. Adapters use it to read through an
+	* inline, pruned definition instead of the stored view.
+	* @since 0.1.153
+	*/
+	readPlan(needed) {
+		if (this.isExternal) return void 0;
+		this._readPlanner ??= new ViewReadPlanner({
+			viewPlan: this.viewPlan,
+			nested: this._nested,
+			getViewColumnMappings: () => this.getViewColumnMappings(),
+			resolveRefSource: (ref) => this.resolveRefSource(ref),
+			uniqueKeySets: (targetType) => {
+				const source = viewSourceOf(targetType).type;
+				if (isViewType(source) || !this._tableResolver) return void 0;
+				const target = this._tableResolver(source);
+				return target && !target.isView ? target.uniqueKeySets : void 0;
+			},
+			fieldTraits: (ref) => {
+				const source = viewSourceOf(ref.type ? ref.type() : this.viewPlan.entryType()).type;
+				const field = sourceFieldMetadata(source, ref.field);
+				const table = source.metadata;
+				const column = field;
+				return {
+					compare: JSON.stringify([...COMPARE_FIELD_KEYS.map((key) => column?.get(key) ?? null), ...COMPARE_TABLE_KEYS.map((key) => table.get(key) ?? null)]),
+					encrypted: field?.has("db.encrypted") === true
+				};
+			}
+		});
+		return this._readPlanner.plan(needed);
+	}
+	/**
 	* 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