@atscript/db 0.1.135 → 0.1.136

package/dist/{db-view-Doh8vPg3.mjs → db-view-BrAtbaOx.mjs}

@@ -1,7 +1,8 @@
 import { n as CasMismatchError, r as DbError } from "./db-error-D5uilS_A.mjs";
-import { a as SUPPORTED_AGGREGATE_FNS, i as resolveAlias } from "./agg-CvXDGnKi.mjs";
+import { i as SUPPORTED_AGGREGATE_FNS, n as BASE_AGGREGATE_FNS } from "./aggregate-fns-CfsveE1w.mjs";
+import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, g as findRemoteFK, h as findFKForRelation, i as batchPatchNestedFrom, l as batchReplaceNestedVia, m as remapDeleteFkViolation, n as batchInsertNestedTo, o as batchPatchNestedVia, p as enrichFkViolation, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow, v as tableNameOf } from "./nested-writer-FWD5oOYh.mjs";
+import { resolveAlias } from "./agg.mjs";
 import { a as forceNavNonOptional, c as getKeyProps, i as dbPlugin, l as isEmptyObject, n as buildPatchPartial, t as buildDbValidator, u as isPlainObject } from "./validator-Ch7UIQl9.mjs";
-import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, g as findRemoteFK, h as findFKForRelation, i as batchPatchNestedFrom, l as batchReplaceNestedVia, m as remapDeleteFkViolation, n as batchInsertNestedTo, o as batchPatchNestedVia, p as enrichFkViolation, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-CqL24ojl.mjs";
 import { separateCas, separateFieldOps } from "./ops.mjs";
 import { flattenAnnotatedType, isAnnotatedType } from "@atscript/typescript/utils";
 import { BUCKET_UNITS, isAggregateExpr, isBucketExpr, isPrimitive, resolveBuckets } from "@uniqu/core";
@@ -17,14 +18,15 @@ const NoopLogger = {
 //#endregion
 //#region src/query/buckets.ts
 /**
-* The one normalizer of `$select` computed entries (since 0.1.132) — uniqu's
+* The one normalizer of `$select` computed entries — uniqu's
 * `resolveBuckets` (entry shapes, unit, time zone canonicalization, week
 * start, alias syntax and uniqueness, "grouped queries only", "must also
 * appear in $groupBy", string `$groupBy` entries) with the table's names as
 * the collision set: a bucket alias may not equal a logical path, a physical
 * column or a navigation field, so a label is never reverse-mapped as a
 * column. Aggregate entries are checked against `SUPPORTED_AGGREGATE_FNS`
-* (and `'*'` is `count`'s only).
+* (and `'*'` is `count`'s only); whether the adapter renders a function is
+* `guardAggregate`'s (`aggregateFns()` → `AGG_FN_NOT_SUPPORTED`).
 *
 * Which layer validates what:
 * - **Shapes** (this normalizer) run FIRST at every entry point — the core's
@@ -46,7 +48,7 @@ const NoopLogger = {
 *
 * @throws DbError `INVALID_QUERY` carrying every issue (`path` `$select` / `$groupBy`).
 */
-function resolveCalendarBuckets(controls, fields, aggregate) {
+function normalizeComputedSelect(controls, fields, aggregate) {
 	const res = resolveBuckets(controls, {
 		aggregate,
 		fns: SUPPORTED_AGGREGATE_FNS,
@@ -56,6 +58,11 @@ function resolveCalendarBuckets(controls, fields, aggregate) {
 	return res.buckets;
 }
 /**
+* @deprecated since 0.1.136 — renamed {@link normalizeComputedSelect} (it
+* normalizes every computed `$select` entry, aggregates included).
+*/
+const resolveCalendarBuckets = normalizeComputedSelect;
+/**
 * Whether a field's TYPE allows it to be the source of a calendar bucket: a
 * `number` / `integer` leaf carrying the `timestamp` tag
 * (`number.timestamp`, `.created`, `.updated`) that is not
@@ -111,6 +118,37 @@ function findAncestorInSet(path, set) {
 		if (set.has(ancestor)) return ancestor;
 	}
 }
+/**
+* Logical field path → its physical path in document storage (nested
+* objects kept inline). `@db.column` renames (`columnMap`) apply to the
+* annotated key, and a document renames the TOP-LEVEL key only — nested keys
+* are stored as-is — so a dotted path under a renamed top-level object
+* renames its first segment: `profile.bio` under `@db.column 'prof'` →
+* `prof.bio`.
+*/
+function documentPath(columnMap, path) {
+	const direct = columnMap.get(path);
+	if (direct !== void 0) return direct;
+	const dot = path.indexOf(".");
+	if (dot === -1) return path;
+	const top = columnMap.get(path.slice(0, dot));
+	return top === void 0 ? path : top + path.slice(dot);
+}
+/** The `__`-separated parent prefix of a dotted path (`a.b.c` → `a__b__`), `""` for a top-level path. */
+function flattenedPrefix(path) {
+	const lastDot = path.lastIndexOf(".");
+	return lastDot >= 0 ? `${path.slice(0, lastDot).replace(/\./g, "__")}__` : "";
+}
+/**
+* Relational column of a column-stored path: a top-level field is its
+* `@db.column` (`override`) or its name; a leaf of a `flattened` object is
+* its parent segments joined with `__` plus its `@db.column` or own segment
+* (`address.zip` with `@db.column 'zip_code'` → `address__zip_code`).
+*/
+function relationalColumnName(path, override, flattened) {
+	if (override) return flattened ? flattenedPrefix(path) + override : override;
+	return flattened ? path.replace(/\./g, "__") : path;
+}
 /** Returns true if `metadata` indicates a navigation relation field. */
 function isNavRelation(metadata) {
 	return metadata.has("db.rel.to") || metadata.has("db.rel.from") || metadata.has("db.rel.via");
@@ -231,12 +269,7 @@ var TableMetadata = class {
 	* first segment: `profile.bio` under `@db.column 'prof'` → `prof.bio`.
 	*/
 	documentPath(path) {
-		const direct = this.columnMap.get(path);
-		if (direct !== void 0) return direct;
-		const dot = path.indexOf(".");
-		if (dot === -1) return path;
-		const top = this.columnMap.get(path.slice(0, dot));
-		return top === void 0 ? path : top + path.slice(dot);
+		return documentPath(this.columnMap, path);
 	}
 	/**
 	* Runs the full metadata compilation pipeline. Called once by
@@ -354,8 +387,7 @@ var TableMetadata = class {
 			const raw = metadata.get("db.rel.FK");
 			const alias = raw === true ? void 0 : raw;
 			if (fieldType.ref) {
-				const refTarget = fieldType.ref.type();
-				const targetTable = refTarget?.metadata?.get("db.table") || refTarget?.id || "";
+				const targetTable = tableNameOf(fieldType.ref.type());
 				const targetField = fieldType.ref.field;
 				const key = alias || `__auto_${fieldName}`;
 				const existing = this.foreignKeys.get(key);
@@ -498,10 +530,7 @@ var TableMetadata = class {
 			if (findAncestorInSet(path, this.jsonFields) !== void 0) continue;
 			if (findAncestorInSet(path, this.encryptedFields) !== void 0) continue;
 			const isFlattened = findAncestorInSet(path, this.flattenedParents) !== void 0;
-			const columnOverride = this.columnMap.get(path);
-			let physicalName;
-			if (columnOverride) physicalName = isFlattened ? this._flattenedPrefix(path) + columnOverride : columnOverride;
-			else physicalName = isFlattened ? path.replace(/\./g, "__") : path;
+			const physicalName = relationalColumnName(path, this.columnMap.get(path), isFlattened);
 			this.pathToPhysical.set(path, physicalName);
 			this.physicalToPath.set(physicalName, path);
 			const fieldType = this.flatMap.get(path);
@@ -520,11 +549,6 @@ var TableMetadata = class {
 		this.onlyColumnRenames = this.columnMap.size > 0 && this.flattenedParents.size === 0 && this.jsonFields.size === 0;
 		this.requiresMappings = this.flattenedParents.size > 0 || this.jsonFields.size > 0 || this.onlyColumnRenames;
 	}
-	/** Returns the `__`-separated parent prefix for a dot-separated path, or empty string for top-level paths. */
-	_flattenedPrefix(path) {
-		const lastDot = path.lastIndexOf(".");
-		return lastDot >= 0 ? `${path.slice(0, lastDot).replace(/\./g, "__")}__` : "";
-	}
 	/** Nearest `@db.encrypted` ancestor of `path` (exclusive), or `undefined`. */
 	/**
 	* Indexes non-ignored descriptors by logical path and retains the JSON-parent
@@ -599,7 +623,7 @@ var TableMetadata = class {
 			const physicalName = skipFlattening ? this.columnMap.get(path) ?? path : this.pathToPhysical.get(path) ?? this.columnMap.get(path) ?? path;
 			const fromLocal = this._columnFromMap.get(path);
 			let renamedFrom;
-			if (fromLocal) renamedFrom = isFlattened ? this._flattenedPrefix(path) + fromLocal : fromLocal;
+			if (fromLocal) renamedFrom = isFlattened ? flattenedPrefix(path) + fromLocal : fromLocal;
 			const currencyCode = type.metadata.get("db.amount.currency");
 			const currencyRefField = type.metadata.get("db.amount.currency.ref");
 			const unitCode = type.metadata.get("db.unit");
@@ -780,7 +804,7 @@ var TableMetadata = class {
 * 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
-* (`resolveCalendarBuckets` rejects any other shape before translation).
+* (`normalizeComputedSelect` rejects any other shape before translation).
 */
 var UniquSelect = class UniquSelect {
 	static UNRESOLVED = Symbol("unresolved");
@@ -913,7 +937,7 @@ var FieldMappingStrategy = class {
 	* equals a field name).
 	*
 	* `buckets` are the query's calendar buckets as the core's normalizer
-	* resolved them (`resolveCalendarBuckets` — `AtscriptDbReadable.aggregate`
+	* resolved them (`normalizeComputedSelect` — `AtscriptDbReadable.aggregate`
 	* runs it before the guards); they reach adapters with `field` made
 	* physical and the source descriptor as `fd`.
 	*/
@@ -948,16 +972,28 @@ var FieldMappingStrategy = class {
 	/**
 	* `$select` with its field paths made physical: array-form names and
 	* computed `$field`s (`'*'` kept), or the keys of the object
-	* (inclusion / exclusion) form.
+	* (inclusion / exclusion) form. An aggregate's output alias is fixed
+	* (`$as`) from its LOGICAL field first, so a default alias never leaks a
+	* physical name (`sum(amount)` over `@db.column 'amount_cents'` stays
+	* `sum_amount`); a bucket's alias is already resolved.
 	*/
 	physicalSelect(select, meta) {
 		if (!this.renamesPaths(meta)) return select;
 		if (Array.isArray(select)) return select.map((item) => {
 			if (typeof item === "string") return this.physicalPath(item, meta);
-			if (isAggregateExpr(item) || isBucketExpr(item)) return item.$field === "*" ? item : {
-				...item,
-				$field: this.physicalPath(item.$field, meta)
-			};
+			if (isAggregateExpr(item) || isBucketExpr(item)) {
+				if (item.$field === "*") return item;
+				const physical = this.physicalPath(item.$field, meta);
+				if (physical === item.$field) return item;
+				return isAggregateExpr(item) ? {
+					...item,
+					$as: resolveAlias(item),
+					$field: physical
+				} : {
+					...item,
+					$field: physical
+				};
+			}
 			return item;
 		});
 		const translated = {};
@@ -1382,7 +1418,7 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 * - `$exists` with a non-boolean operand → `INVALID_QUERY`
 * - malformed `$select` computed entries / `$groupBy` entries, calendar
 *   buckets outside grouped queries or with a bad unit / zone / alias →
-*   `INVALID_QUERY` (the shared normalizer, `resolveCalendarBuckets`)
+*   `INVALID_QUERY` (the shared normalizer, `normalizeComputedSelect`)
 * - a calendar bucket over a field that is not a bucket source
 *   (`bucketSourceVerdict`) → `INVALID_QUERY`, or `BUCKET_NOT_SUPPORTED`
 *   when the adapter has no calendar buckets at all; a unit the adapter's
@@ -1648,7 +1684,7 @@ function collectFilterKeys(filter, push, skip, refs) {
 * `$sort` / `$having`; a bucket alias is also dropped from `groupBy`, which
 * lists grouped fields only.
 *
-* Entry shapes are not checked here — see `resolveCalendarBuckets`.
+* Entry shapes are not checked here — see `normalizeComputedSelect`.
 */
 function collectQueryPaths(query, aggregate) {
 	const refs = {
@@ -1788,7 +1824,7 @@ function guardPath(meta, adapter, path, op, predicate = "compare") {
 * {@link guardPath}). Adapters may therefore assume every path they receive
 * is physical.
 *
-* Entry shapes are the caller's to normalize first (`resolveCalendarBuckets`
+* Entry shapes are the caller's to normalize first (`normalizeComputedSelect`
 * — {@link guardQuery} / {@link guardAggregate} do).
 *
 * In aggregate mode (`aggregate = true`) `$select` computed entries have
@@ -1821,7 +1857,7 @@ function guardQuery(meta, adapter, query) {
 	if (!query) return;
 	guardFilter(meta, adapter, query.filter);
 	guardSort(meta, query.controls?.$sort);
-	resolveCalendarBuckets(query.controls, meta, false);
+	normalizeComputedSelect(query.controls, meta, false);
 	guardPaths(meta, adapter, query);
 }
 /**
@@ -1844,16 +1880,17 @@ function checkHavingKeys(refs) {
 }
 /**
 * Aggregate-path guard: $groupBy / $select / $having encryption refs + filter
-* + $sort, then the path guard, then the adapter's calendar-bucket units
+* + $sort, then the path guard, then the adapter's aggregate functions
+* (`AGG_FN_NOT_SUPPORTED`) and calendar-bucket units
 * (`BUCKET_NOT_SUPPORTED`), then the `$having` key rule
 * ({@link checkHavingKeys} — after the path guard so an unknown key still
 * reads `Unknown field`).
 *
 * `buckets` are the query's resolved calendar buckets when the caller already
-* ran `resolveCalendarBuckets` (resolved here otherwise).
+* ran `normalizeComputedSelect` (resolved here otherwise).
 */
 function guardAggregate(meta, adapter, query, resolved) {
-	const buckets = resolved ?? resolveCalendarBuckets(query.controls, meta, true);
+	const buckets = resolved ?? normalizeComputedSelect(query.controls, meta, true);
 	guardFilter(meta, adapter, query.filter);
 	const controls = query.controls;
 	if (meta.encryptedFields.size > 0) {
@@ -1866,11 +1903,26 @@ function guardAggregate(meta, adapter, query, resolved) {
 		guardSort(meta, controls.$sort);
 	}
 	const refs = guardPaths(meta, adapter, query, true);
+	guardAggregateFns(adapter, controls.$select);
 	guardBucketUnits(adapter, buckets);
 	const having = refs ? checkHavingKeys(refs) : void 0;
 	if (having) throw new DbError("INVALID_QUERY", [having]);
 }
 /**
+* 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
+* before a function existed never receives it.
+*/
+function guardAggregateFns(adapter, select) {
+	if (!select) return;
+	const fns = adapter.aggregateFns();
+	for (const item of select) if (isAggregateExpr(item) && !fns.has(item.$fn)) throw new DbError("AGG_FN_NOT_SUPPORTED", [{
+		path: "$select",
+		message: `Aggregate function "${item.$fn}" is not supported by this adapter`
+	}]);
+}
+/**
 * Rejects a calendar bucket whose unit this adapter cannot group by
 * (`calendarBucketUnits()`; an adapter with none was already answered per
 * source by `bucketSourceVerdict`) with `BUCKET_NOT_SUPPORTED`,
@@ -2377,13 +2429,15 @@ var AtscriptDbReadable = class {
 	*
 	* Validates:
 	* - `$select` computed entries and calendar buckets (the shared normalizer,
-	*   `resolveCalendarBuckets`: shapes, unit, zone, alias, grouping)
+	*   `normalizeComputedSelect`: shapes, unit, zone, alias, grouping)
 	* - Plain fields in $select are a subset of $groupBy
 	* - When dimensions/measures are defined (strict mode): $groupBy fields
-	*   must be dimensions, aggregate $field values must be measures (or '*')
+	*   must be dimensions, aggregate $field values must be measures (or '*';
+	*   a `countDistinct` field may also be a dimension)
 	* - the path guard (a bucket source must pass `bucketSourceVerdict` —
 	*   timestamp type, no JSON ancestor, a dimension in strict mode, an
-	*   adapter with calendar buckets) and the adapter's calendar-bucket units
+	*   adapter with calendar buckets), the adapter's aggregate functions
+	*   (`AGG_FN_NOT_SUPPORTED`) and calendar-bucket units
 	*   (`BUCKET_NOT_SUPPORTED`)
 	*
 	* Translates field names, delegates to adapter.aggregate(),
@@ -2392,7 +2446,7 @@ var AtscriptDbReadable = class {
 	async aggregate(query) {
 		this._ensureBuilt();
 		const { $groupBy, $select } = query.controls;
-		const buckets = resolveCalendarBuckets(query.controls, this._meta, true);
+		const buckets = normalizeComputedSelect(query.controls, this._meta, true);
 		if ($select) {
 			const groupBySet = new Set($groupBy);
 			for (const item of $select) if (typeof item === "string" && !groupBySet.has(item)) throw new DbError("INVALID_QUERY", [{
@@ -2409,8 +2463,16 @@ var AtscriptDbReadable = class {
 				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)) throw new DbError("INVALID_QUERY", [{
+			if ($select) for (const item of $select) {
+				if (!isAggregateExpr(item) || item.$field === "*" || measSet.has(item.$field)) continue;
+				if (item.$fn === "countDistinct") {
+					if (dimSet.has(item.$field)) continue;
+					throw new DbError("INVALID_QUERY", [{
+						path: "$select",
+						message: `Aggregate field "${item.$field}" is not a dimension or measure`
+					}]);
+				}
+				throw new DbError("INVALID_QUERY", [{
 					path: "$select",
 					message: `Aggregate field "${item.$field}" is not a measure`
 				}]);
@@ -2449,6 +2511,10 @@ var AtscriptDbReadable = class {
 	calendarBucketUnits() {
 		return this.adapter.calendarBucketUnits();
 	}
+	/** Aggregate functions the adapter renders (proxies adapter capability). @since 0.1.136 */
+	aggregateFns() {
+		return this.adapter.aggregateFns();
+	}
 	/** Whether the adapter can sort by a given field (proxies adapter capability). */
 	canSortField(fd) {
 		return this.adapter.canSortField(fd);
@@ -2739,7 +2805,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-B68R1LET.mjs").then((n) => n.n);
+		const { loadRelationsImpl } = await import("./relation-loader-CTFaZpVa.mjs").then((n) => n.n);
 		return loadRelationsImpl(rows, withRelations, this);
 	}
 	/**
@@ -3038,6 +3104,20 @@ var BaseDbAdapter = class {
 		return EMPTY_BUCKET_UNITS;
 	}
 	/**
+	* Aggregate functions (`{ $fn, $field }` in an aggregate `$select`) this
+	* adapter renders. The default is `sum`, `count`, `avg`, `min` and `max`;
+	* an adapter that also implements `countDistinct` (distinct non-null
+	* values) returns `ALL_AGGREGATE_FNS`. The core rejects a known function
+	* missing from this set with `AGG_FN_NOT_SUPPORTED` before dispatch, so
+	* `aggregate()` only ever receives functions listed here; moost-db's
+	* `/meta` advertises the set as `aggregateFns`.
+	*
+	* @since 0.1.136
+	*/
+	aggregateFns() {
+		return BASE_AGGREGATE_FNS;
+	}
+	/**
 	* 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`).
@@ -4607,7 +4687,150 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	}
 };
 //#endregion
+//#region src/table/view-source.ts
+const indexCache = /* @__PURE__ */ new WeakMap();
+function sourceIndex(type) {
+	let idx = indexCache.get(type);
+	if (idx) return idx;
+	idx = {
+		flatMap: /* @__PURE__ */ new Map(),
+		columnMap: /* @__PURE__ */ new Map(),
+		unstored: /* @__PURE__ */ new Set(),
+		jsonRoots: /* @__PURE__ */ new Set(),
+		encrypted: /* @__PURE__ */ new Set(),
+		optional: /* @__PURE__ */ new Set()
+	};
+	if (type.type.kind === "object") {
+		const navFields = /* @__PURE__ */ new Set();
+		const collected = [];
+		idx.flatMap = flattenAnnotatedType(type, {
+			excludePhantomTypes: true,
+			onField: (path, fieldType, metadata) => {
+				if (isNavRelation(metadata)) navFields.add(path);
+				collected.push([
+					path,
+					fieldType,
+					metadata
+				]);
+			}
+		});
+		const storage = [];
+		for (const [path, fieldType, metadata] of collected) {
+			if (!path || findAncestorInSet(path, navFields) !== void 0) continue;
+			const column = metadata.get("db.column");
+			if (column) idx.columnMap.set(path, column);
+			if (metadata.has("db.ignore") || navFields.has(path)) idx.unstored.add(path);
+			if (metadata.has("db.encrypted")) storage.push([path, false]);
+			else if (metadata.has("db.json") || resolveDesignType(fieldType) === "array") storage.push([path, true]);
+		}
+		storage.sort(([a], [b]) => a.split(".").length - b.split(".").length);
+		for (const [path, json] of storage) if (findAncestorInSet(path, idx.jsonRoots) === void 0 && findAncestorInSet(path, idx.encrypted) === void 0) (json ? idx.jsonRoots : idx.encrypted).add(path);
+		for (const [path, node] of idx.flatMap) if (path && node.optional) idx.optional.add(path);
+	}
+	indexCache.set(type, idx);
+	return idx;
+}
+/** `path` itself if it is in `set`, else its nearest ancestor in `set`. */
+function selfOrAncestor(path, set) {
+	return set.has(path) ? path : findAncestorInSet(path, set);
+}
+/**
+* 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.
+*
+* Relational rules (`TableMetadata`'s): the outermost `@db.json` or array
+* node with segments remaining is the column and the rest becomes
+* {@link TViewSource.jsonPath}; a flattened leaf is its parent segments
+* joined with `__` plus its `@db.column` (or segment); a top-level field is
+* its `@db.column` or name. Nested-object adapters use the document path
+* (only a top-level key is renamed) and never a JSON path.
+*
+* A path the type does not declare resolves to itself — the database
+* reports the unknown column, as before.
+* @throws for a path without storage (`@db.ignore`, a navigation relation,
+*   or inside one), and — relational — for a path inside an `@db.encrypted` field.
+*/
+function resolveViewSource(sourceType, logicalPath, nestedObjects) {
+	const idx = sourceIndex(sourceType);
+	const node = idx.flatMap.get(logicalPath);
+	const jsonRoot = selfOrAncestor(logicalPath, idx.jsonRoots);
+	const optional = selfOrAncestor(logicalPath, idx.optional) !== void 0 || jsonRoot !== void 0 && jsonRoot !== logicalPath;
+	if (!node) return {
+		column: logicalPath,
+		designType: "unknown",
+		optional
+	};
+	const unstored = selfOrAncestor(logicalPath, idx.unstored);
+	if (unstored !== void 0) throw new Error(`"${logicalPath}" has no column — "${unstored}" is @db.ignore or a navigation relation`);
+	const designType = resolveDesignType(node);
+	if (nestedObjects) return {
+		column: documentPath(idx.columnMap, logicalPath),
+		designType,
+		optional
+	};
+	const encrypted = findAncestorInSet(logicalPath, idx.encrypted);
+	if (encrypted !== void 0) throw new Error(`"${logicalPath}" is inside the @db.encrypted field "${encrypted}" — reference "${encrypted}" itself`);
+	if (jsonRoot !== void 0) {
+		const column = relationalColumnName(jsonRoot, idx.columnMap.get(jsonRoot), jsonRoot.includes("."));
+		return jsonRoot === logicalPath ? {
+			column,
+			designType,
+			optional
+		} : {
+			column,
+			jsonPath: logicalPath.slice(jsonRoot.length + 1).split("."),
+			designType,
+			optional
+		};
+	}
+	if (designType === "object" && !idx.encrypted.has(logicalPath)) return {
+		column: logicalPath.replace(/\./g, "__"),
+		designType,
+		flattened: true,
+		optional
+	};
+	return {
+		column: relationalColumnName(logicalPath, idx.columnMap.get(logicalPath), logicalPath.includes(".")),
+		designType,
+		optional
+	};
+}
+//#endregion
 //#region src/table/db-view.ts
+/** The `@db.agg.*` annotations, one per supported aggregate function. */
+const AGG_KEYS = SUPPORTED_AGGREGATE_FNS.map((fn) => `db.agg.${fn}`);
+/**
+* Reads a view field's `@db.agg.*` annotation. The compiled value is
+* `{ field?, condition? }`; models compiled by older versions carry `true`
+* (bare `@db.agg.count`) or a string (the field), which are read the same way.
+* A missing field or `true` is `'*'` (COUNT(*)).
+*/
+function readViewAgg(metadata) {
+	for (const key of AGG_KEYS) {
+		const val = metadata?.get(key);
+		if (val === void 0) continue;
+		const aggFn = key.slice(7);
+		if (typeof val === "string") return {
+			aggFn,
+			aggField: val
+		};
+		if (val === null || typeof val !== "object") return {
+			aggFn,
+			aggField: "*"
+		};
+		return {
+			aggFn,
+			aggField: val.field ?? "*",
+			...val.condition ? { aggFilter: val.condition } : {}
+		};
+	}
+}
+const JSON_LEAF_TYPES = new Set([
+	"string",
+	"number",
+	"boolean"
+]);
 /**
 * Database view abstraction driven by Atscript `@db.view.*` annotations.
 *
@@ -4623,6 +4846,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 */
 var AtscriptDbView = class extends AtscriptDbReadable {
 	_viewPlan;
+	_columnMappings;
 	get isView() {
 		return true;
 	}
@@ -4648,19 +4872,18 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		const metadata = this._type.metadata;
 		const forRef = metadata.get("db.view.for");
 		const entryType = typeof forRef === "function" ? forRef : forRef.type;
-		const entryTypeResolved = entryType();
-		const entryTable = entryTypeResolved?.metadata?.get("db.table") || entryTypeResolved?.id || "";
+		const entryTable = tableNameOf(entryType());
 		const rawJoins = metadata.get("db.view.joins");
 		const joins = [];
 		if (rawJoins) for (const join of rawJoins) {
 			const targetRef = join.target;
 			const targetType = typeof targetRef === "function" ? targetRef : targetRef.type;
 			const targetTypeResolved = targetType();
-			const targetTable = targetTypeResolved?.metadata?.get("db.table") || targetTypeResolved?.id || "";
 			joins.push({
 				targetType,
-				targetTable,
-				condition: join.condition
+				targetTable: tableNameOf(targetTypeResolved),
+				condition: join.condition,
+				kind: join.kind === "left" ? "left" : "inner"
 			});
 		}
 		const filter = metadata.get("db.view.filter");
@@ -4676,73 +4899,143 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		};
 		return this._viewPlan;
 	}
+	/** Whether the adapter stores nested objects natively (document paths, no JSON columns). */
+	get _nested() {
+		return this.adapter.supportsNestedObjects();
+	}
+	/**
+	* Resolves a view query field ref (join condition, `@db.view.filter`,
+	* conditional-aggregate predicate) to its table name and PHYSICAL source on
+	* this view's adapter — the column (or document path) with `TableMetadata`'s
+	* layout rules, the path inside a JSON column, and whether the value may be
+	* absent. An unqualified ref resolves against the entry table.
+	* @throws for a ref without storage (`@db.ignore`, navigation relation) or
+	*   inside an `@db.encrypted` field (relational adapters).
+	* @since 0.1.136
+	*/
+	resolveRefSource(ref) {
+		const type = ref.type ? ref.type() : this.viewPlan.entryType();
+		return {
+			table: tableNameOf(type),
+			source: resolveViewSource(type, ref.field, this._nested)
+		};
+	}
 	/**
-	* Resolves a query field ref to a quoted `table.column` SQL fragment.
+	* Resolves a query field ref (join condition, `@db.view.filter`) to a
+	* quoted `table.column` SQL fragment — the PHYSICAL column (flattened
+	* `__` name, `@db.column` rename). An unqualified ref
+	* resolves against the entry table.
 	*
 	* @param ref - The field reference from the query tree.
 	* @param qi - Identifier quoting function (e.g. backtick for MySQL, double-quote for SQLite).
 	*             Defaults to double-quote wrapping for backwards compatibility.
+	* @throws when the ref reads inside a JSON column (not supported in view conditions).
 	*/
 	resolveFieldRef(ref, qi = (n) => `"${n}"`) {
-		if (!ref.type) {
-			const plan = this.viewPlan;
-			return `${qi(plan.entryTable)}.${qi(ref.field)}`;
-		}
-		const resolved = ref.type();
-		return `${qi(resolved?.metadata?.get("db.table") || resolved?.id || "")}.${qi(ref.field)}`;
+		const { table, source } = this.resolveRefSource(ref);
+		if (source.jsonPath) throw new Error(`View "${this.tableName}": "${ref.field}" reads inside a JSON column — JSON paths are not supported in view conditions`);
+		return `${qi(table)}.${qi(source.column)}`;
 	}
 	/**
-	* Maps each view field to its source table and column via ref chain.
-	* Fields without refs (inline definitions) map to the entry table with the same name.
+	* Maps each view column to its source table and PHYSICAL source column.
+	*
+	* View fields resolve through their chain ref; fields without a ref read
+	* the entry table under the same name; aggregates read their `@db.agg.*`
+	* field from the entry table (or their ref). Source names are
+	* physical (flattened `__` names, `@db.column`, document paths), `viewColumn`
+	* is the view's own physical name, an object field whose source is a
+	* flattened object expands to one mapping per leaf, and a primitive leaf
+	* inside a JSON column carries `json` (rendered by adapters that support
+	* JSON extraction).
+	*
+	* Computed once per view (the plan and the type are immutable).
+	*
+	* @throws for an object field over a JSON column without `@db.json` on the
+	*   view field, a JSON leaf that is not a string / number / boolean, or an
+	*   aggregate other than `count` over `'*'`.
 	*/
 	getViewColumnMappings() {
+		this._columnMappings ??= this._buildColumnMappings();
+		return this._columnMappings;
+	}
+	_buildColumnMappings() {
 		const plan = this.viewPlan;
 		const mappings = [];
 		if (this._type.type.kind !== "object") return mappings;
-		const aggKeys = [
-			"db.agg.sum",
-			"db.agg.avg",
-			"db.agg.count",
-			"db.agg.min",
-			"db.agg.max"
-		];
 		const ignored = this.ignoredFields;
+		const meta = this.getMetadata();
+		const nested = this._nested;
+		const viewName = (path) => nested ? meta.documentPath(path) : meta.pathToPhysical.get(path);
+		const fail = (field, message) => {
+			throw new Error(`View "${this.tableName}" field "${field}": ${message}`);
+		};
+		const leftJoined = new Set(plan.joins.filter((j) => j.kind === "left").map((j) => j.targetTable));
 		for (const [fieldName, fieldType] of this._type.type.props.entries()) {
 			if (ignored.has(fieldName)) continue;
-			let aggFn;
-			let aggField;
-			for (const key of aggKeys) {
-				const val = fieldType.metadata?.get(key);
-				if (val !== void 0) {
-					aggFn = key.split(".")[2];
-					aggField = typeof val === "string" ? val : "*";
-					break;
-				}
-			}
+			const agg = readViewAgg(fieldType.metadata);
+			const aggField = agg?.aggField;
+			if (aggField === "*" && agg?.aggFn !== "count") fail(fieldName, `aggregate "${agg?.aggFn}" needs a field — only count accepts *`);
+			let sourceType;
+			let sourcePath;
 			if (fieldType.ref) {
-				const resolved = fieldType.ref.type();
-				const sourceTable = resolved?.metadata?.get("db.table") || resolved?.id || "";
-				const sourceColumn = fieldType.ref.field || fieldName;
-				mappings.push({
-					viewColumn: fieldName,
-					sourceTable,
-					sourceColumn,
-					aggFn,
-					aggField
-				});
+				sourceType = fieldType.ref.type();
+				sourcePath = fieldType.ref.field || fieldName;
 			} else {
-				const sourceColumn = aggField && aggField !== "*" ? aggField : fieldName;
+				sourceType = plan.entryType();
+				sourcePath = aggField && aggField !== "*" ? aggField : fieldName;
+			}
+			const sourceTable = tableNameOf(sourceType);
+			const joinNullable = leftJoined.has(sourceTable);
+			if (aggField === "*" && !fieldType.ref) {
 				mappings.push({
-					viewColumn: fieldName,
-					sourceTable: plan.entryTable,
-					sourceColumn,
-					aggFn,
-					aggField
+					viewColumn: viewName(fieldName) ?? fieldName,
+					viewPath: fieldName,
+					sourceTable,
+					sourceColumn: "*",
+					...agg
 				});
+				continue;
+			}
+			const source = resolveViewSource(sourceType, sourcePath, nested);
+			const ownColumn = viewName(fieldName);
+			if (ownColumn === void 0 && !nested) {
+				if (!source.flattened) fail(fieldName, "source is a JSON column — add @db.json to the view field");
+				const prefix = `${fieldName}.`;
+				for (const [viewPath, viewColumn] of meta.pathToPhysical) {
+					if (!viewPath.startsWith(prefix) || ignored.has(viewPath)) continue;
+					const leafPath = `${sourcePath}.${viewPath.slice(prefix.length)}`;
+					const leaf = resolveViewSource(sourceType, leafPath, nested);
+					mappings.push(this._leafMapping(viewPath, viewColumn, sourceTable, leaf, joinNullable));
+				}
+				continue;
 			}
+			if (source.flattened) fail(fieldName, "source is a flattened object — remove @db.json from the view field");
+			const mapping = this._leafMapping(fieldName, ownColumn ?? fieldName, sourceTable, source, joinNullable);
+			mappings.push(agg ? {
+				...mapping,
+				...agg
+			} : mapping);
 		}
 		return mappings;
 	}
+	/** One view column over one physical source (a column or a JSON leaf). */
+	_leafMapping(viewPath, viewColumn, sourceTable, source, joinNullable) {
+		const mapping = {
+			viewColumn,
+			viewPath,
+			sourceTable,
+			sourceColumn: source.column
+		};
+		if (joinNullable || source.optional || source.designType === "unknown") mapping.nullable = true;
+		if (source.jsonPath) {
+			if (!JSON_LEAF_TYPES.has(source.designType)) throw new Error(`View "${this.tableName}" field "${viewPath}": JSON extraction supports string, number and boolean leaves only`);
+			mapping.json = {
+				path: source.jsonPath,
+				type: source.designType
+			};
+		}
+		return mapping;
+	}
 };
 /**
 * Structural type guard for views: `true` when the readable reports
@@ -4757,4 +5050,4 @@ function isAtscriptDbView(readable) {
 	return readable.isView;
 }
 //#endregion
-export { unsupportedOperatorMessage as A, isJsonValueField as B, guardAggregate as C, guardQuery as D, guardPaths as E, TableMetadata as F, resolveCalendarBuckets as H, findAncestorInSet as I, isGeoIndexableType as L, DocumentFieldMapper as M, FieldMappingStrategy as N, narrowerFilterOps as O, UniquSelect as P, isGeoPointType as R, collectQueryPaths as S, guardPath as T, NoopLogger as U, jsonValueAncestor as V, assertGeoPoint as _, decomposePatch as a, checkHavingKeys as b, BaseDbAdapter as c, NativeIntegrity as d, AtscriptDbReadable as f, acceptedOperatorsHint as g, ENCRYPTED_REASON as h, assertNoVersionWrites as i, RelationalFieldMapper as j, sortFieldNames as k, createFailureCollector as l, ADAPTER_FILTER_REASON as m, isAtscriptDbView as n, ApplicationIntegrity as o, resolveDesignType as p, AtscriptDbTable as r, ALL_BUCKET_UNITS as s, AtscriptDbView as t, IntegrityStrategy as u, bucketSourceVerdict as v, guardFilter as w, classifyQueryPath as x, canFilterLeaf as y, isBucketableField as z };
+export { unsupportedOperatorMessage as A, isJsonValueField as B, guardAggregate as C, guardQuery as D, guardPaths as E, TableMetadata as F, normalizeComputedSelect as H, findAncestorInSet as I, isGeoIndexableType as L, DocumentFieldMapper as M, FieldMappingStrategy as N, narrowerFilterOps as O, UniquSelect as P, isGeoPointType as R, collectQueryPaths as S, guardPath as T, resolveCalendarBuckets as U, jsonValueAncestor as V, NoopLogger as W, assertGeoPoint as _, decomposePatch as a, checkHavingKeys as b, BaseDbAdapter as c, NativeIntegrity as d, AtscriptDbReadable as f, acceptedOperatorsHint as g, ENCRYPTED_REASON as h, assertNoVersionWrites as i, RelationalFieldMapper as j, sortFieldNames as k, createFailureCollector as l, ADAPTER_FILTER_REASON as m, isAtscriptDbView as n, ApplicationIntegrity as o, resolveDesignType as p, AtscriptDbTable as r, ALL_BUCKET_UNITS as s, AtscriptDbView as t, IntegrityStrategy as u, bucketSourceVerdict as v, guardFilter as w, classifyQueryPath as x, canFilterLeaf as y, isBucketableField as z };