@atscript/db 0.1.134 → 0.1.136

package/dist/{db-view-pgm2dHIo.cjs → db-view-BAzhEUxB.cjs}

@@ -1,7 +1,8 @@
 const require_db_error = require("./db-error-DTkkeu5b.cjs");
+const require_aggregate_fns = require("./aggregate-fns-CGBv3E8S.cjs");
+const require_nested_writer = require("./nested-writer-BZNCuqI6.cjs");
 require("./agg.cjs");
 const require_validator = require("./validator-BtZbcLN2.cjs");
-const require_nested_writer = require("./nested-writer-wk1EFUNY.cjs");
 const require_ops = require("./ops.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _uniqu_core = require("@uniqu/core");
@@ -17,13 +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.
+* column. Aggregate entries are checked against `SUPPORTED_AGGREGATE_FNS`
+* (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
@@ -45,15 +48,21 @@ const NoopLogger = {
 *
 * @throws DbError `INVALID_QUERY` carrying every issue (`path` `$select` / `$groupBy`).
 */
-function resolveCalendarBuckets(controls, fields, aggregate) {
+function normalizeComputedSelect(controls, fields, aggregate) {
 	const res = (0, _uniqu_core.resolveBuckets)(controls, {
 		aggregate,
+		fns: require_aggregate_fns.SUPPORTED_AGGREGATE_FNS,
 		isField: (name) => fields.flatMap.has(name) || fields.navFields.has(name) || fields.physicalNames.has(name)
 	});
 	if (!res.ok) throw new require_db_error.DbError("INVALID_QUERY", res.issues);
 	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
@@ -109,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");
@@ -229,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
@@ -352,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 = require_nested_writer.tableNameOf(fieldType.ref.type());
 				const targetField = fieldType.ref.field;
 				const key = alias || `__auto_${fieldName}`;
 				const existing = this.foreignKeys.get(key);
@@ -496,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);
@@ -518,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
@@ -597,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");
@@ -778,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");
@@ -911,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`.
 	*/
@@ -946,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 ((0, _uniqu_core.isAggregateExpr)(item) || (0, _uniqu_core.isBucketExpr)(item)) return item.$field === "*" ? item : {
-				...item,
-				$field: this.physicalPath(item.$field, meta)
-			};
+			if ((0, _uniqu_core.isAggregateExpr)(item) || (0, _uniqu_core.isBucketExpr)(item)) {
+				if (item.$field === "*") return item;
+				const physical = this.physicalPath(item.$field, meta);
+				if (physical === item.$field) return item;
+				return (0, _uniqu_core.isAggregateExpr)(item) ? {
+					...item,
+					$as: (0, _uniqu_core.resolveAlias)(item),
+					$field: physical
+				} : {
+					...item,
+					$field: physical
+				};
+			}
 			return item;
 		});
 		const translated = {};
@@ -1380,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
@@ -1646,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 = {
@@ -1786,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
@@ -1819,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);
 }
 /**
@@ -1842,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) {
@@ -1864,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 require_db_error.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 ((0, _uniqu_core.isAggregateExpr)(item) && !fns.has(item.$fn)) throw new require_db_error.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`,
@@ -2375,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(),
@@ -2390,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 require_db_error.DbError("INVALID_QUERY", [{
@@ -2407,8 +2463,16 @@ var AtscriptDbReadable = class {
 				path: "$groupBy",
 				message: `Field "${field}" is not a dimension`
 			}]);
-			if ($select) {
-				for (const item of $select) if ((0, _uniqu_core.isAggregateExpr)(item) && item.$field !== "*" && !measSet.has(item.$field)) throw new require_db_error.DbError("INVALID_QUERY", [{
+			if ($select) for (const item of $select) {
+				if (!(0, _uniqu_core.isAggregateExpr)(item) || item.$field === "*" || measSet.has(item.$field)) continue;
+				if (item.$fn === "countDistinct") {
+					if (dimSet.has(item.$field)) continue;
+					throw new require_db_error.DbError("INVALID_QUERY", [{
+						path: "$select",
+						message: `Aggregate field "${item.$field}" is not a dimension or measure`
+					}]);
+				}
+				throw new require_db_error.DbError("INVALID_QUERY", [{
 					path: "$select",
 					message: `Aggregate field "${item.$field}" is not a measure`
 				}]);
@@ -2447,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);
@@ -2737,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 Promise.resolve().then(() => require("./relation-loader-BD4xANQJ.cjs")).then((n) => n.relation_loader_exports);
+		const { loadRelationsImpl } = await Promise.resolve().then(() => require("./relation-loader-6ZB_5KFq.cjs")).then((n) => n.relation_loader_exports);
 		return loadRelationsImpl(rows, withRelations, this);
 	}
 	/**
@@ -3036,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 require_aggregate_fns.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`).
@@ -4605,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 = (0, _atscript_typescript_utils.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 = require_aggregate_fns.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.
 *
@@ -4621,6 +4846,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 */
 var AtscriptDbView = class extends AtscriptDbReadable {
 	_viewPlan;
+	_columnMappings;
 	get isView() {
 		return true;
 	}
@@ -4646,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 = require_nested_writer.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: require_nested_writer.tableNameOf(targetTypeResolved),
+				condition: join.condition,
+				kind: join.kind === "left" ? "left" : "inner"
 			});
 		}
 		const filter = metadata.get("db.view.filter");
@@ -4674,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 query field ref to a quoted `table.column` SQL fragment.
+	* 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: require_nested_writer.tableNameOf(type),
+			source: resolveViewSource(type, ref.field, this._nested)
+		};
+	}
+	/**
+	* 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 = require_nested_writer.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
@@ -4989,6 +5284,12 @@ Object.defineProperty(exports, "narrowerFilterOps", {
 		return narrowerFilterOps;
 	}
 });
+Object.defineProperty(exports, "normalizeComputedSelect", {
+	enumerable: true,
+	get: function() {
+		return normalizeComputedSelect;
+	}
+});
 Object.defineProperty(exports, "resolveCalendarBuckets", {
 	enumerable: true,
 	get: function() {