@atscript/db 0.1.135 → 0.1.137

package/dist/{db-view-Dm7MpUGB.cjs → column-diff-CgxgFKzx.cjs}

@@ -1,7 +1,8 @@
 const require_db_error = require("./db-error-DTkkeu5b.cjs");
-const require_agg = require("./agg-EcIbAFnJ.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,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,16 +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_agg.SUPPORTED_AGGREGATE_FNS,
+		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
@@ -111,6 +118,43 @@ function findAncestorInSet(path, set) {
 		if (set.has(ancestor)) return ancestor;
 	}
 }
+/**
+* Whether a `@db.column` / `@db.column.renamed` on `path` applies: always on
+* relational storage; on document storage (`nestedObjects`) for top-level
+* fields only — nested keys are stored as-is. Column maps are built with it.
+*/
+function columnOverrideApplies(path, nestedObjects) {
+	return !nestedObjects || !path.includes(".");
+}
+/**
+* Logical field path → its physical path in document storage (nested
+* objects kept inline). A document renames the TOP-LEVEL key only — nested
+* keys are stored as-is, so a `@db.column` on a nested leaf renames nothing
+* (`address.zip` stays `address.zip`; see {@link columnOverrideApplies}) —
+* and 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 dot = path.indexOf(".");
+	if (dot === -1) return columnMap.get(path) ?? 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");
@@ -158,6 +202,7 @@ var TableMetadata = class {
 	ignoredFields = /* @__PURE__ */ new Set();
 	uniqueProps = /* @__PURE__ */ new Set();
 	defaults = /* @__PURE__ */ new Map();
+	/** Logical path → `@db.column` override (top-level keys only on document storage). */
 	columnMap = /* @__PURE__ */ new Map();
 	dimensions = [];
 	measures = [];
@@ -223,20 +268,17 @@ var TableMetadata = class {
 	get isBuilt() {
 		return this._built;
 	}
+	/** {@link documentPath} over this table's `columnMap`. */
+	documentPath(path) {
+		return documentPath(this.columnMap, path);
+	}
 	/**
-	* Logical field path → its physical path in document storage (nested
-	* objects kept inline). `@db.column` renames 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`.
+	* Physical name of a logical path: the document path on nested-object
+	* adapters, else the relational column (`pathToPhysical`, then the
+	* `@db.column` override).
 	*/
-	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);
+	physicalPath(logical) {
+		return this.nestedObjects ? this.documentPath(logical) : this.pathToPhysical.get(logical) ?? this.columnMap.get(logical) ?? logical;
 	}
 	/**
 	* Runs the full metadata compilation pipeline. Called once by
@@ -326,10 +368,11 @@ var TableMetadata = class {
 			this.primaryKeys.push(fieldName);
 			this.originalMetaIdFields.push(fieldName);
 		}
+		const renamable = columnOverrideApplies(fieldName, this.nestedObjects);
 		const column = metadata.get("db.column");
-		if (column) this.columnMap.set(fieldName, column);
+		if (column && renamable) this.columnMap.set(fieldName, column);
 		const columnFrom = metadata.get("db.column.renamed");
-		if (columnFrom) this._columnFromMap.set(fieldName, columnFrom);
+		if (columnFrom && renamable) this._columnFromMap.set(fieldName, columnFrom);
 		const resolvedDefault = resolveDefaultFromMetadata(metadata);
 		if (resolvedDefault) this.defaults.set(fieldName, resolvedDefault);
 		if (metadata.has("db.ignore")) this.ignoredFields.add(fieldName);
@@ -354,8 +397,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);
@@ -498,10 +540,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 +559,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
@@ -596,10 +630,10 @@ var TableMetadata = class {
 			else if (isJson) storage = "json";
 			else if (isFlattened) storage = "flattened";
 			else storage = "column";
-			const physicalName = skipFlattening ? this.columnMap.get(path) ?? path : this.pathToPhysical.get(path) ?? this.columnMap.get(path) ?? path;
+			const physicalName = this.physicalPath(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");
@@ -700,7 +734,7 @@ var TableMetadata = class {
 				field.optional = ftype.optional === true;
 				field.designType = ftype.type.tags?.has("objectId") ? "objectId" : resolveDesignType(ftype);
 			}
-			field.name = this.pathToPhysical.get(field.name) ?? this.columnMap.get(field.name) ?? field.name;
+			field.name = this.physicalPath(field.name);
 		}
 	}
 	/**
@@ -780,7 +814,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 +947,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 +982,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 = {};
@@ -987,11 +1033,24 @@ var FieldMappingStrategy = class {
 		else if (key === "$not") result[key] = this.translateFilter(value, meta);
 		else if (key.startsWith("$")) result[key] = value;
 		else {
-			const formatKey = meta.columnMap.get(key) ?? key;
-			result[meta.documentPath(key)] = this.formatFilterValue(formatKey, value, meta);
+			const physical = this.physicalPath(key, meta);
+			result[physical] = this.formatFilterValue(physical, value, meta);
 		}
 		return result;
 	}
+	/** `$inc` / `$mul` field-op keys to physical names ({@link physicalPath}). */
+	translateOpsKeys(ops, meta) {
+		if (!this.renamesPaths(meta)) return ops;
+		const physical = (rec) => {
+			const out = {};
+			for (const key in rec) out[this.physicalPath(key, meta)] = rec[key];
+			return out;
+		};
+		return {
+			inc: ops.inc && physical(ops.inc),
+			mul: ops.mul && physical(ops.mul)
+		};
+	}
 	/**
 	* Reverse-maps `@db.column` renames on a row read from storage.
 	* Renames physical keys back to logical names in-place.
@@ -1151,10 +1210,11 @@ var DocumentFieldMapper = class extends FieldMappingStrategy {
 		}
 		return this.formatWriteValues(data, meta);
 	}
+	/** Patch keys (top-level or decomposed dotted) to document paths. */
 	translatePatchKeys(update, meta) {
-		if (meta.columnMap.size > 0) {
+		if (this.renamesPaths(meta)) {
 			const result = {};
-			for (const key of Object.keys(update)) result[meta.columnMap.get(key) ?? key] = update[key];
+			for (const key of Object.keys(update)) result[this.physicalPath(key, meta)] = update[key];
 			return this.formatWriteValues(result, meta);
 		}
 		return this.formatWriteValues(update, meta);
@@ -1382,7 +1442,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 +1708,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 +1848,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 +1881,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 +1904,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 +1927,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`,
@@ -2187,7 +2263,7 @@ var AtscriptDbReadable = class {
 	get syncMethod() {
 		return this._syncMethod;
 	}
-	/** Logical → physical column name mapping from `@db.column`. */
+	/** Logical → physical column name mapping from `@db.column` (top-level only on document storage). */
 	get columnMap() {
 		this._ensureBuilt();
 		return this._meta.columnMap;
@@ -2377,13 +2453,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 +2470,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", [{
@@ -2409,8 +2487,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`
 				}]);
@@ -2449,6 +2535,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 +2829,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);
 	}
 	/**
@@ -2868,6 +2958,15 @@ var BaseDbAdapter = class {
 		if (logger) this.logger = logger;
 	}
 	/**
+	* Called by {@link DbSpace} right after its factory builds this adapter —
+	* the administrative one included — before {@link registerReadable}. No-op
+	* by default: override it to share state across a space's adapters when the
+	* adapter has no driver to share it through (the memory adapter keeps one
+	* store per space).
+	* @since 0.1.137
+	*/
+	registerSpace(_space) {}
+	/**
 	* Enables or disables verbose (debug-level) logging for this adapter.
 	* When disabled, no log strings are constructed — zero overhead.
 	*/
@@ -3038,6 +3137,31 @@ 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;
+	}
+	/**
+	* 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
+	* adapter once on the next sync — return a new value whenever a rendering
+	* fix changes what an existing view returns. `undefined` (the default)
+	* leaves the snapshot, and its hash, as before. External views ignore it.
+	*
+	* @since 0.1.137
+	*/
+	viewRenderRevision() {}
+	/**
 	* 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`).
@@ -3326,6 +3450,26 @@ var BaseDbAdapter = class {
 	*/
 	supportsColumnModify;
 	/**
+	* Drops a table by name (without needing a registered readable).
+	* Used by schema sync to remove tables no longer in the schema. A missing
+	* table is not an error (`DROP TABLE IF EXISTS`). The default throws —
+	* schema sync then reports the removed table as an `error` entry and keeps
+	* it tracked. Since 0.1.137; before, the method was optional and a drop the
+	* adapter lacked was skipped silently while sync reported it done.
+	*/
+	async dropTableByName(tableName) {
+		throw new Error(`Cannot drop table "${tableName}": dropTableByName is not supported by this adapter`);
+	}
+	/**
+	* Drops a view by name (without needing a registered readable).
+	* Used by schema sync to remove views no longer in the schema, and to drop
+	* a managed view before recreating it. A missing view is not an error. The
+	* default throws, with the same history as {@link dropTableByName}.
+	*/
+	async dropViewByName(viewName) {
+		throw new Error(`Cannot drop view "${viewName}": dropViewByName is not supported by this adapter`);
+	}
+	/**
 	* Drops several tables that reference each other (a foreign-key cycle) as
 	* one operation. Schema sync only calls this for cycles whose members are
 	* ALL being removed. Default: {@link dropTableByName} in the given order —
@@ -3335,7 +3479,7 @@ var BaseDbAdapter = class {
 	* @since 0.1.128
 	*/
 	async dropTablesByName(tableNames) {
-		for (const name of tableNames) await this.dropTableByName?.(name);
+		for (const name of tableNames) await this.dropTableByName(name);
 	}
 	/**
 	* Whether the table has at least one row. Schema sync uses it in the
@@ -3447,7 +3591,7 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 		const physicalToLogical = /* @__PURE__ */ new Map();
 		const physicalFields = [];
 		for (const logical of neededLogical) {
-			const physical = meta.pathToPhysical.get(logical) ?? meta.columnMap.get(logical) ?? logical;
+			const physical = meta.physicalPath(logical);
 			physicalFields.push(physical);
 			physicalToLogical.set(physical, logical);
 		}
@@ -3915,19 +4059,6 @@ var RemoveGuardContext = class {
 		return this._pending;
 	}
 };
-/** Translates a single ops record from logical to physical column names. */
-function _translateOpsRecord(rec, meta) {
-	const out = {};
-	for (const key in rec) out[meta.leafByLogical.get(key)?.physicalName ?? key] = rec[key];
-	return out;
-}
-/** Translates ops keys from logical field names to physical column names. */
-function _translateOpsKeys(ops, meta) {
-	return {
-		inc: ops.inc ? _translateOpsRecord(ops.inc, meta) : void 0,
-		mul: ops.mul ? _translateOpsRecord(ops.mul, meta) : void 0
-	};
-}
 /** Upper bound of keys per `touchMany` UPDATE statement (parameter-count safety). */
 const TOUCH_MANY_CHUNK = 500;
 /** `touchMany` input rejection — always `INVALID_QUERY`, path names the key. */
@@ -4188,13 +4319,13 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				let result;
 				if (this.adapter.supportsNativePatch()) {
 					const ops = require_ops.separateFieldOps(data);
-					const translatedOps = ops ? _translateOpsKeys(ops, this._meta) : void 0;
+					const translatedOps = ops ? this._fieldMapper.translateOpsKeys(ops, this._meta) : void 0;
 					const translatedData = this._fieldMapper.translatePatchKeys(data, this._meta);
 					result = await this.adapter.nativePatch(translatedFilter, translatedData, translatedOps, expectedVersion);
 				} else {
 					const update = decomposePatch(data, this);
 					const ops = require_ops.separateFieldOps(update);
-					const translatedOps = ops ? _translateOpsKeys(ops, this._meta) : void 0;
+					const translatedOps = ops ? this._fieldMapper.translateOpsKeys(ops, this._meta) : void 0;
 					const translatedUpdate = this._fieldMapper.translatePatchKeys(update, this._meta);
 					if (getArrayOpsFields(translatedUpdate).size > 0) {
 						const resolved = resolveArrayOps(translatedUpdate, await this.adapter.findOne({
@@ -4333,7 +4464,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		await this._encryptItems([dataCopy], "patch");
 		const update = decomposePatch(dataCopy, this);
 		const ops = require_ops.separateFieldOps(update);
-		const translatedOps = ops ? _translateOpsKeys(ops, this._meta) : void 0;
+		const translatedOps = ops ? this._fieldMapper.translateOpsKeys(ops, this._meta) : void 0;
 		const translatedUpdate = this._fieldMapper.translatePatchKeys(update, this._meta);
 		const translatedFilter = this._fieldMapper.translateFilter(filter, this._meta);
 		if (translatedOps === void 0 && require_validator.isEmptyObject(translatedUpdate)) return {
@@ -4607,7 +4738,154 @@ 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(),
+		documentColumnMap: /* @__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 (columnOverrideApplies(path, true)) idx.documentColumnMap.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.documentColumnMap, 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.
 *
@@ -4623,6 +4901,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 */
 var AtscriptDbView = class extends AtscriptDbReadable {
 	_viewPlan;
+	_columnMappings;
 	get isView() {
 		return true;
 	}
@@ -4648,19 +4927,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");
@@ -4676,73 +4954,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.physicalPath(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
@@ -4757,6 +5105,328 @@ function isAtscriptDbView(readable) {
 	return readable.isView;
 }
 //#endregion
+//#region src/schema/schema-hash.ts
+/** Extracts sorted field snapshots from a readable's field descriptors. */
+function extractFieldSnapshots(fields, typeMapper) {
+	return fields.filter((f) => !f.ignored).map((f) => {
+		const snap = {
+			physicalName: f.physicalName,
+			designType: f.designType,
+			optional: f.optional,
+			isPrimaryKey: f.isPrimaryKey,
+			storage: f.storage
+		};
+		if (f.defaultValue) snap.defaultValue = f.defaultValue;
+		if (typeMapper) snap.mappedType = typeMapper(f);
+		if (f.encrypted) snap.encrypted = true;
+		return snap;
+	}).toSorted((a, b) => a.physicalName.localeCompare(b.physicalName));
+}
+/**
+* Extracts a canonical, serializable snapshot from a readable's metadata.
+* Sorted deterministically so the hash is stable across runs.
+*
+* @param readable - The table/view readable.
+* @param typeMapper - Optional adapter-specific type mapper. When provided,
+*   each field's mapped type (e.g., "VARCHAR(255)") is stored in the snapshot
+*   for precise type change detection.
+*/
+function computeTableSnapshot(readable, typeMapper, tableOptions) {
+	const fields = extractFieldSnapshots(readable.fieldDescriptors, typeMapper);
+	const indexes = [...readable.indexes.values()].map((idx) => ({
+		key: idx.key,
+		type: idx.type,
+		fields: idx.fields.map((f) => ({
+			name: f.name,
+			sort: f.sort
+		}))
+	})).toSorted((a, b) => a.key.localeCompare(b.key));
+	const foreignKeys = [...readable.foreignKeys.values()].map((fk) => ({
+		fields: [...fk.fields].toSorted(),
+		targetTable: fk.targetTable,
+		targetFields: [...fk.targetFields].toSorted(),
+		onDelete: fk.onDelete,
+		onUpdate: fk.onUpdate
+	})).toSorted((a, b) => a.fields.join(",").localeCompare(b.fields.join(",")));
+	const snapshot = {
+		tableName: readable.tableName,
+		fields,
+		indexes,
+		foreignKeys
+	};
+	if (tableOptions?.length) snapshot.tableOptions = [...tableOptions].toSorted((a, b) => a.key.localeCompare(b.key));
+	return snapshot;
+}
+/**
+* Extracts a canonical, serializable snapshot from a view's metadata.
+* Captures view plan (entry table, joins, filter, materialization) for
+* detecting view definition changes.
+*/
+function computeViewSnapshot(view) {
+	const fields = extractFieldSnapshots(view.fieldDescriptors);
+	if (view.isExternal) return {
+		tableName: view.tableName,
+		viewType: "E",
+		fields
+	};
+	const plan = view.viewPlan;
+	const qualify = (ref) => view.resolveFieldRef(ref, (n) => n);
+	const canonical = (node) => JSON.stringify(canonicalizeQueryNode(node, qualify));
+	const columns = view.getViewColumnMappings().map((m) => {
+		const col = {
+			column: m.viewColumn,
+			sourceTable: m.sourceTable,
+			sourceColumn: m.sourceColumn
+		};
+		if (m.json) {
+			col.jsonPath = JSON.stringify(m.json.path);
+			col.jsonType = m.json.type;
+		}
+		if (m.aggFn) col.aggFn = m.aggFn;
+		if (m.aggField) col.aggField = m.aggField;
+		if (m.aggFilter) col.aggFilter = canonical(m.aggFilter);
+		return col;
+	}).toSorted((a, b) => a.column < b.column ? -1 : a.column > b.column ? 1 : 0);
+	const result = {
+		tableName: view.tableName,
+		viewType: plan.materialized ? "M" : "V",
+		entryTable: plan.entryTable,
+		joinTables: plan.joins.map((j) => {
+			const join = {
+				targetTable: j.targetTable,
+				condition: canonical(j.condition)
+			};
+			if (j.kind === "left") join.kind = "left";
+			return join;
+		}),
+		columns
+	};
+	if (plan.filter) result.filterHash = fnv1a(canonical(plan.filter));
+	if (plan.having) result.havingHash = fnv1a(canonical(plan.having));
+	if (plan.materialized) result.materialized = true;
+	const renderRevision = view.dbAdapter.viewRenderRevision();
+	if (renderRevision !== void 0) result.renderRevision = renderRevision;
+	return {
+		...result,
+		fields
+	};
+}
+/**
+* Converts a view predicate (join condition, `@db.view.filter`,
+* `@db.view.having`) into a serializable structure whose JSON is a stable
+* function of its MEANING: field refs become `qualify(ref)` — the view's
+* `resolveFieldRef(ref, (n) => n)`, i.e. `"<table>.<field>"`, so a predicate
+* retargeted to another table with the same field name changes — operators
+* and literal values are kept as-is, `$and`/`$or` keep declaration order, and
+* no function references survive. Two identical models produce byte-identical
+* JSON.
+* @since 0.1.128
+*/
+function canonicalizeQueryNode(node, qualify) {
+	if ("$and" in node) return { and: node.$and.map((n) => canonicalizeQueryNode(n, qualify)) };
+	if ("$or" in node) return { or: node.$or.map((n) => canonicalizeQueryNode(n, qualify)) };
+	if ("$not" in node) return { not: canonicalizeQueryNode(node.$not, qualify) };
+	const comp = node;
+	const out = {
+		l: qualify(comp.left),
+		op: comp.op
+	};
+	if (comp.right !== void 0) out.r = comp.right !== null && typeof comp.right === "object" && "field" in comp.right ? { f: qualify(comp.right) } : comp.right;
+	return out;
+}
+/**
+* Computes a deterministic hash string from multiple table snapshots.
+* Uses FNV-1a for speed — not cryptographic, just needs stability + collision resistance.
+*/
+function computeSchemaHash(snapshots) {
+	const sorted = [...snapshots].toSorted((a, b) => a.tableName.localeCompare(b.tableName));
+	return fnv1a(JSON.stringify(sorted));
+}
+/**
+* Computes a hash for a single table/view snapshot.
+* Used for per-table change detection via stored snapshots.
+*/
+function computeTableHash(snapshot) {
+	return fnv1a(JSON.stringify(snapshot));
+}
+/**
+* Converts stored snapshot fields to `TExistingColumn[]` format
+* for use with `computeColumnDiff`. Used by adapters that lack
+* native column introspection (e.g., MongoDB).
+*
+* The `type` field uses `mappedType` when available (adapter-specific),
+* falling back to `designType`.
+*/
+function snapshotToExistingColumns(snapshot) {
+	return snapshot.fields.map((f) => ({
+		name: f.physicalName,
+		type: f.mappedType ?? f.designType,
+		notnull: !f.optional,
+		pk: f.isPrimaryKey,
+		dflt_value: serializeDefaultValue(f.defaultValue)
+	}));
+}
+/**
+* Extracts table options from a stored snapshot for diff comparison.
+* Used as fallback when an adapter lacks native table option introspection.
+*/
+function snapshotToExistingTableOptions(snapshot) {
+	return snapshot.tableOptions ?? [];
+}
+/** Serializes a TDbDefaultValue to a comparable string. */
+function serializeDefaultValue(dv) {
+	if (!dv) return;
+	if (dv.kind === "value") return dv.value;
+	return `fn:${dv.fn}`;
+}
+/** FNV-1a 32-bit hash → hex string */
+function fnv1a(str) {
+	let hash = 2166136261;
+	for (let i = 0; i < str.length; i++) {
+		hash ^= str.codePointAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return Math.trunc(hash).toString(16).padStart(8, "0");
+}
+//#endregion
+//#region src/schema/fk-diff.ts
+/** Canonical key for an FK: sorted local field names, comma-joined. */
+function fkKey(fields) {
+	return [...fields].toSorted().join(",");
+}
+/**
+* Compares desired FK constraints against stored snapshot to detect
+* additions, removals, and property changes (target table, target fields,
+* onDelete, onUpdate).
+*/
+function computeForeignKeyDiff(desired, existingSnapshot) {
+	const added = [];
+	const removed = [];
+	const changed = [];
+	const existingByKey = /* @__PURE__ */ new Map();
+	for (const fk of existingSnapshot) existingByKey.set(fkKey(fk.fields), fk);
+	const desiredKeys = /* @__PURE__ */ new Set();
+	for (const fk of desired.values()) {
+		const key = fkKey(fk.fields);
+		desiredKeys.add(key);
+		const existing = existingByKey.get(key);
+		if (!existing) added.push(fk);
+		else if (fkPropertiesDiffer(fk, existing)) changed.push({
+			desired: fk,
+			existing
+		});
+	}
+	for (const [key, fk] of existingByKey) if (!desiredKeys.has(key)) removed.push(fk);
+	return {
+		added,
+		removed,
+		changed
+	};
+}
+/** Whether the FK diff contains any changes. */
+function hasForeignKeyChanges(diff) {
+	return diff.added.length > 0 || diff.removed.length > 0 || diff.changed.length > 0;
+}
+function fkPropertiesDiffer(desired, existing) {
+	if (desired.targetTable !== existing.targetTable) return true;
+	if (fkKey(desired.targetFields) !== fkKey(existing.targetFields)) return true;
+	if ((desired.onDelete ?? void 0) !== (existing.onDelete ?? void 0)) return true;
+	if ((desired.onUpdate ?? void 0) !== (existing.onUpdate ?? void 0)) return true;
+	return false;
+}
+//#endregion
+//#region src/schema/column-diff.ts
+/**
+* Whether a live column's type differs from the type the adapter's
+* `typeMapper` gives the field — the one rule schema sync diffs column types
+* by (case-insensitive). Exported for adapters that must agree with it (the
+* PostgreSQL recreate converts exactly the columns this reports changed).
+* @since 0.1.137
+*/
+function isColumnTypeChanged(existingType, expectedType) {
+	return existingType.toUpperCase() !== expectedType.toUpperCase();
+}
+/**
+* Computes the difference between desired schema fields and existing database columns.
+*
+* @param desired - Field descriptors from the Atscript type (after flattening).
+* @param existing - Columns currently in the database (from introspection).
+* @param typeMapper - Optional function to map field metadata to DB-native type strings.
+*                     Receives the full field meta (design type, annotations, PK status, etc.)
+*                     so adapters can produce context-aware types (e.g., `VARCHAR(255)` from maxLength).
+*                     Required for type change detection.
+*/
+function computeColumnDiff(desired, existing, typeMapper) {
+	const existingByName = new Map(existing.map((c) => [c.name, c]));
+	const desiredByName = /* @__PURE__ */ new Map();
+	const renamedOldNames = /* @__PURE__ */ new Set();
+	const added = [];
+	const renamed = [];
+	const typeChanged = [];
+	const nullableChanged = [];
+	const defaultChanged = [];
+	const conflicts = [];
+	for (const field of desired) {
+		if (field.ignored) continue;
+		desiredByName.set(field.physicalName, field);
+		const existingCol = existingByName.get(field.physicalName);
+		if (existingCol) if (field.renamedFrom && existingByName.has(field.renamedFrom)) {
+			conflicts.push({
+				field,
+				oldName: field.renamedFrom,
+				conflictsWith: field.physicalName
+			});
+			renamedOldNames.add(field.renamedFrom);
+		} else {
+			if (typeMapper) {
+				if (isColumnTypeChanged(existingCol.type, typeMapper(field))) typeChanged.push({
+					field,
+					existingType: existingCol.type
+				});
+			}
+			if (!field.isPrimaryKey && !existingCol.pk) {
+				const desiredNotNull = !field.optional;
+				if (existingCol.notnull !== desiredNotNull) nullableChanged.push({
+					field,
+					wasNullable: !existingCol.notnull
+				});
+			}
+			const desiredDefault = serializeDefaultValue(field.defaultValue);
+			if (existingCol.dflt_value !== void 0 && existingCol.dflt_value !== desiredDefault) defaultChanged.push({
+				field,
+				oldDefault: existingCol.dflt_value,
+				newDefault: desiredDefault
+			});
+		}
+		else if (field.renamedFrom && existingByName.has(field.renamedFrom)) {
+			renamed.push({
+				field,
+				oldName: field.renamedFrom
+			});
+			renamedOldNames.add(field.renamedFrom);
+		} else added.push(field);
+	}
+	const diff = {
+		added,
+		removed: existing.filter((c) => !desiredByName.has(c.name) && !renamedOldNames.has(c.name)),
+		renamed,
+		typeChanged,
+		nullableChanged,
+		defaultChanged,
+		conflicts
+	};
+	if (existing.length > 0) {
+		const newNameByOld = new Map(renamed.map((r) => [r.oldName, r.field.physicalName]));
+		const from = existing.filter((c) => c.pk).map((c) => newNameByOld.get(c.name) ?? c.name);
+		const to = desired.filter((f) => !f.ignored && f.isPrimaryKey).map((f) => f.physicalName);
+		if (fkKey(from) !== fkKey(to)) diff.primaryKeyChanged = {
+			from,
+			to
+		};
+	}
+	return diff;
+}
+//#endregion
 Object.defineProperty(exports, "ADAPTER_FILTER_REASON", {
 	enumerable: true,
 	get: function() {
@@ -4883,6 +5553,12 @@ Object.defineProperty(exports, "canFilterLeaf", {
 		return canFilterLeaf;
 	}
 });
+Object.defineProperty(exports, "canonicalizeQueryNode", {
+	enumerable: true,
+	get: function() {
+		return canonicalizeQueryNode;
+	}
+});
 Object.defineProperty(exports, "checkHavingKeys", {
 	enumerable: true,
 	get: function() {
@@ -4901,6 +5577,42 @@ Object.defineProperty(exports, "collectQueryPaths", {
 		return collectQueryPaths;
 	}
 });
+Object.defineProperty(exports, "computeColumnDiff", {
+	enumerable: true,
+	get: function() {
+		return computeColumnDiff;
+	}
+});
+Object.defineProperty(exports, "computeForeignKeyDiff", {
+	enumerable: true,
+	get: function() {
+		return computeForeignKeyDiff;
+	}
+});
+Object.defineProperty(exports, "computeSchemaHash", {
+	enumerable: true,
+	get: function() {
+		return computeSchemaHash;
+	}
+});
+Object.defineProperty(exports, "computeTableHash", {
+	enumerable: true,
+	get: function() {
+		return computeTableHash;
+	}
+});
+Object.defineProperty(exports, "computeTableSnapshot", {
+	enumerable: true,
+	get: function() {
+		return computeTableSnapshot;
+	}
+});
+Object.defineProperty(exports, "computeViewSnapshot", {
+	enumerable: true,
+	get: function() {
+		return computeViewSnapshot;
+	}
+});
 Object.defineProperty(exports, "createFailureCollector", {
 	enumerable: true,
 	get: function() {
@@ -4919,6 +5631,12 @@ Object.defineProperty(exports, "findAncestorInSet", {
 		return findAncestorInSet;
 	}
 });
+Object.defineProperty(exports, "fkKey", {
+	enumerable: true,
+	get: function() {
+		return fkKey;
+	}
+});
 Object.defineProperty(exports, "guardAggregate", {
 	enumerable: true,
 	get: function() {
@@ -4949,6 +5667,12 @@ Object.defineProperty(exports, "guardQuery", {
 		return guardQuery;
 	}
 });
+Object.defineProperty(exports, "hasForeignKeyChanges", {
+	enumerable: true,
+	get: function() {
+		return hasForeignKeyChanges;
+	}
+});
 Object.defineProperty(exports, "isAtscriptDbView", {
 	enumerable: true,
 	get: function() {
@@ -4961,6 +5685,12 @@ Object.defineProperty(exports, "isBucketableField", {
 		return isBucketableField;
 	}
 });
+Object.defineProperty(exports, "isColumnTypeChanged", {
+	enumerable: true,
+	get: function() {
+		return isColumnTypeChanged;
+	}
+});
 Object.defineProperty(exports, "isGeoIndexableType", {
 	enumerable: true,
 	get: function() {
@@ -4991,6 +5721,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() {
@@ -5003,6 +5739,18 @@ Object.defineProperty(exports, "resolveDesignType", {
 		return resolveDesignType;
 	}
 });
+Object.defineProperty(exports, "snapshotToExistingColumns", {
+	enumerable: true,
+	get: function() {
+		return snapshotToExistingColumns;
+	}
+});
+Object.defineProperty(exports, "snapshotToExistingTableOptions", {
+	enumerable: true,
+	get: function() {
+		return snapshotToExistingTableOptions;
+	}
+});
 Object.defineProperty(exports, "sortFieldNames", {
 	enumerable: true,
 	get: function() {