@atscript/db 0.1.139 → 0.1.141

package/dist/{column-diff-CgxgFKzx.cjs → column-diff-CfPNcP6e.cjs}

@@ -1,8 +1,9 @@
 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");
+const require_nested_writer = require("./nested-writer-DYsRxZ5f.cjs");
+const require_derived_rules = require("./derived-rules-YstgIxG-.cjs");
+const require_validator = require("./validator-DASnXf1j.cjs");
 require("./agg.cjs");
-const require_validator = require("./validator-BtZbcLN2.cjs");
 const require_ops = require("./ops.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _uniqu_core = require("@uniqu/core");
@@ -101,22 +102,184 @@ function jsonValueAncestor(path, jsonValueParents) {
 	}
 }
 //#endregion
-//#region src/table/table-metadata.ts
-const INDEX_PREFIX = "atscript__";
-function indexKey(type, name) {
-	return `${INDEX_PREFIX}${type}__${name.replace(/[^a-z0-9_.-]/gi, "_").replace(/_+/g, "_").slice(0, 117 - type.length - 2)}`;
+//#region src/table/view-source.ts
+/** Resolves a compiled type reference (a class, a lazy `() => T`, or `{ type: () => T }`). */
+function resolveTypeRef(value) {
+	if ((0, _atscript_typescript_utils.isAnnotatedType)(value)) return value;
+	if (typeof value === "function") {
+		const resolved = value();
+		return (0, _atscript_typescript_utils.isAnnotatedType)(resolved) ? resolved : void 0;
+	}
+	if (value && typeof value === "object" && typeof value.type === "function") return resolveTypeRef(value.type);
 }
 /**
-* Finds the nearest ancestor of `path` that belongs to `set`.
-* Used by both the build pipeline (in `_classifyFields`) and
-* runtime reconstruction on the Readable.
+* The table / view a `@db.alias` type stands for, or `undefined` when `type`
+* is not an alias.
+* @since 0.1.141
 */
-function findAncestorInSet(path, set) {
-	let pos = path.length;
-	while ((pos = path.lastIndexOf(".", pos - 1)) !== -1) {
-		const ancestor = path.slice(0, pos);
-		if (set.has(ancestor)) return ancestor;
+function aliasTargetOf(type) {
+	const target = type?.metadata?.get("db.alias");
+	if (target === void 0) return void 0;
+	const resolved = resolveTypeRef(target);
+	if (!resolved) throw new Error(`@db.alias of "${type?.id ?? ""}" does not resolve to an annotated type`);
+	return resolved;
+}
+/**
+* How a view plan addresses a source type: a plain table or view is scoped
+* by its physical name; a `@db.alias` type is scoped by its own type name
+* over the aliased table / view (`JOIN "employees" AS "Manager"`).
+* @since 0.1.141
+*/
+function viewSourceOf(type) {
+	const target = aliasTargetOf(type);
+	if (!target) {
+		const table = require_nested_writer.tableNameOf(type);
+		return {
+			name: table,
+			table,
+			type
+		};
+	}
+	if (aliasTargetOf(target)) throw new Error(`@db.alias "${type.id ?? ""}" targets "${target.id ?? ""}", which is itself a @db.alias — alias the table or view directly`);
+	return {
+		name: type.id ?? "",
+		table: require_nested_writer.tableNameOf(target),
+		type: target,
+		alias: true
+	};
+}
+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(),
+		derived: /* @__PURE__ */ new Map()
+	};
+	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 || require_validator.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.column.derived") && fieldType.ref?.field) idx.derived.set(path, fieldType.ref.field);
+			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 (require_validator.findAncestorInSet(path, idx.jsonRoots) === void 0 && require_validator.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;
+}
+/**
+* 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 `@db.column.derived` path (since 0.1.141) resolves to its generated
+* column on relational adapters and to its JSON-leaf source path on
+* nested-object adapters — always optional (the extraction yields NULL for a
+* missing or off-type leaf).
+*
+* 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 derivedSource = idx.derived.get(logicalPath);
+	if (node && derivedSource !== void 0) {
+		if (nestedObjects) return {
+			...resolveViewSource(sourceType, derivedSource, true),
+			optional: true
+		};
+		return {
+			column: relationalColumnName(logicalPath, idx.columnMap.get(logicalPath), false),
+			designType: resolveDesignType(node),
+			optional: true
+		};
+	}
+	const jsonRoot = require_validator.selfOrAncestor(logicalPath, idx.jsonRoots);
+	const optional = require_validator.selfOrAncestor(logicalPath, idx.optional) !== void 0 || jsonRoot !== void 0 && jsonRoot !== logicalPath;
+	if (!node) return {
+		column: logicalPath,
+		designType: "unknown",
+		optional
+	};
+	const unstored = require_validator.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 = require_validator.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/table-metadata.ts
+const INDEX_PREFIX = "atscript__";
+function indexKey(type, name) {
+	return `${INDEX_PREFIX}${type}__${name.replace(/[^a-z0-9_.-]/gi, "_").replace(/_+/g, "_").slice(0, 117 - type.length - 2)}`;
 }
 /**
 * Whether a `@db.column` / `@db.column.renamed` on `path` applies: always on
@@ -192,6 +355,22 @@ var TableMetadata = class {
 	nestedObjects;
 	flatMap;
 	fieldDescriptors;
+	/**
+	* The descriptors schema sync manages as columns of this table: the
+	* non-ignored ones — on nested-object adapters without the
+	* `@db.column.derived` fields, which store nothing there (their
+	* `physicalName` is the source's document path). The desired side of every
+	* column diff and the column list of a fresh create.
+	* @since 0.1.141
+	*/
+	columnDescriptors = [];
+	/**
+	* The columns that hold a value of their own — non-ignored and not derived
+	* (a generated column is computed, never assigned): what a table recreation
+	* copies and a full replace assigns.
+	* @since 0.1.141
+	*/
+	storedDescriptors = [];
 	primaryKeys = [];
 	preferredId = [];
 	originalMetaIdFields = [];
@@ -212,6 +391,13 @@ var TableMetadata = class {
 	quantityRefByField = /* @__PURE__ */ new Map();
 	/** Logical paths annotated with `@db.encrypted` — stored as one opaque ciphertext column. */
 	encryptedFields = /* @__PURE__ */ new Set();
+	/**
+	* `@db.column.derived` fields (top-level logical name → what they read),
+	* since 0.1.141. A generated column on relational adapters; on nested-object
+	* adapters nothing is stored — {@link physicalPath} maps the name to the
+	* source's document path and reads fill the field from it.
+	*/
+	derivedFields = /* @__PURE__ */ new Map();
 	pathToPhysical = /* @__PURE__ */ new Map();
 	physicalToPath = /* @__PURE__ */ new Map();
 	flattenedParents = /* @__PURE__ */ new Set();
@@ -268,9 +454,12 @@ var TableMetadata = class {
 	get isBuilt() {
 		return this._built;
 	}
-	/** {@link documentPath} over this table's `columnMap`. */
+	/**
+	* {@link documentPath} over this table's `columnMap`. A `@db.column.derived`
+	* field has no stored path of its own: it maps to its source leaf.
+	*/
 	documentPath(path) {
-		return documentPath(this.columnMap, path);
+		return documentPath(this.columnMap, this.derivedFields.get(path)?.sourcePath ?? path);
 	}
 	/**
 	* Physical name of a logical path: the document path on nested-object
@@ -278,7 +467,17 @@ var TableMetadata = class {
 	* `@db.column` override).
 	*/
 	physicalPath(logical) {
-		return this.nestedObjects ? this.documentPath(logical) : this.pathToPhysical.get(logical) ?? this.columnMap.get(logical) ?? logical;
+		if (this.nestedObjects) return this.documentPath(logical);
+		return this.pathToPhysical.get(logical) ?? this.columnMap.get(logical) ?? logical;
+	}
+	/**
+	* Drops the `@db.column.derived` keys of a write payload in place (a
+	* derived field is always top-level): the column is computed from the row
+	* and never written, so a row read back can be written back as-is.
+	* @since 0.1.141
+	*/
+	stripDerived(data) {
+		for (const field of this.derivedFields.keys()) delete data[field];
 	}
 	/**
 	* Runs the full metadata compilation pipeline. Called once by
@@ -313,11 +512,15 @@ var TableMetadata = class {
 			}
 		});
 		for (const entry of collected) {
-			if (findAncestorInSet(entry.path, this.navFields) !== void 0) continue;
+			if (require_validator.findAncestorInSet(entry.path, this.navFields) !== void 0) {
+				this.ignoredFields.add(entry.path);
+				continue;
+			}
 			this._scanGenericAnnotations(entry.path, entry.type, entry.metadata, logger);
+			if (entry.metadata.has("db.column.derived")) this.derivedFields.set(entry.path, this._validateDerivedField(entry.path, entry.type, entry.metadata, type));
 			adapter.onFieldScanned?.(entry.path, entry.type, entry.metadata);
 		}
-		for (const path of this.encryptedFields) if (findAncestorInSet(path, this.encryptedFields) !== void 0) this.encryptedFields.delete(path);
+		for (const path of this.encryptedFields) if (require_validator.findAncestorInSet(path, this.encryptedFields) !== void 0) this.encryptedFields.delete(path);
 		if (!this.nestedObjects) this._classifyFields();
 		const overrides = adapter.getMetadataOverrides?.(this);
 		if (overrides) this._applyOverrides(overrides);
@@ -337,11 +540,10 @@ var TableMetadata = class {
 		this.jsonFields.clear();
 		this._built = true;
 		adapter.onAfterFlatten?.();
-		if (this.nestedObjects && this.flatMap) {
-			for (const path of this.flatMap.keys()) if (path && !this.ignoredFields.has(path) && !this.navFields.has(path) && findAncestorInSet(path, this.navFields) === void 0) this.allPhysicalFields.push(this.documentPath(path));
-		} else for (const [path, physical] of this.pathToPhysical) {
+		if (this.nestedObjects) for (const fd of this.columnDescriptors) this.allPhysicalFields.push(fd.physicalName);
+		else for (const [path, physical] of this.pathToPhysical) {
 			if (this.navFields.has(path)) continue;
-			if (findAncestorInSet(path, this.navFields) !== void 0) continue;
+			if (require_validator.findAncestorInSet(path, this.navFields) !== void 0) continue;
 			this.allPhysicalFields.push(physical);
 		}
 	}
@@ -485,6 +687,45 @@ var TableMetadata = class {
 		if (metadata.has("db.default.increment") || metadata.has("db.default.now")) reject("@db.default.increment / @db.default.now", "engine-side defaults bypass the encryption transform");
 		if (metadata.get("db.patch.strategy") === "merge") reject("@db.patch.strategy \"merge\"", "ciphertext is opaque — partial merges would silently drop omitted keys");
 	}
+	/**
+	* Build-time diagnostics for `@db.column.derived` (rules D1–D8 of the
+	* derived-column design) — the runtime mirror of the compile-time check, so
+	* pre-compiled models fail fast — and the resolution of what the field
+	* reads: the source leaf's JSON column + path (relational layout, via the
+	* views' `resolveViewSource`) and its declared type.
+	*/
+	_validateDerivedField(fieldName, fieldType, metadata, rootType) {
+		const reject = (why) => {
+			throw new Error(`@db.column.derived on "${fieldName}": ${why}`);
+		};
+		if (fieldName.includes(".")) reject("only a top-level field of a table can be derived");
+		for (const [name, why] of require_derived_rules.DERIVED_INCOMPATIBLE) if (metadata.has(name)) reject(`cannot coexist with @${name} — ${why}`);
+		const ref = fieldType.ref;
+		if (!ref?.field) reject("requires a chain reference into a @db.json field of the same table (e.g. `customerId: Order.payload.customer.id`)");
+		const target = ref.type();
+		if (target !== rootType) reject(`must reference the enclosing table "${rootType.id ?? ""}", not "${target?.id ?? ""}" — a derived column reads its own row`);
+		const sourcePath = ref.field;
+		const segments = sourcePath.split(".");
+		let jsonRoot;
+		for (let i = 1; i <= segments.length; i++) {
+			const prefix = segments.slice(0, i).join(".");
+			const node = this.flatMap.get(prefix);
+			if (!node) reject(`path "${sourcePath}" does not exist on the table`);
+			if (node.metadata.has("db.encrypted")) reject(`path "${sourcePath}" reads inside the @db.encrypted field "${prefix}" — ciphertext cannot be extracted`);
+			if (resolveDesignType(node) === "array") reject(`path "${sourcePath}" crosses the array "${prefix}" — a derived column reads one scalar leaf`);
+			if (jsonRoot === void 0 && node.metadata.has("db.json")) jsonRoot = prefix;
+		}
+		if (jsonRoot === void 0 || jsonRoot === sourcePath) reject(`path "${sourcePath}" does not read inside a @db.json field — a flattened or scalar column needs no derived column`);
+		const leafType = resolveDesignType(this.flatMap.get(sourcePath));
+		if (!require_derived_rules.isJsonLeafType(leafType)) return reject(`path "${sourcePath}" must end at a string, number or boolean leaf (got "${leafType}")`);
+		const source = resolveViewSource(rootType, sourcePath, false);
+		return {
+			sourcePath,
+			sourceColumn: source.column,
+			jsonPath: source.jsonPath,
+			type: leafType
+		};
+	}
 	/** Build-time diagnostics for `@db.index.geo` (§3 of the geo-index spec). */
 	_validateGeoIndexField(fieldName, fieldType, metadata) {
 		const reject = (why) => {
@@ -521,7 +762,7 @@ var TableMetadata = class {
 	_classifyFields() {
 		for (const [path, type] of this.flatMap.entries()) {
 			if (!path) continue;
-			if (this.encryptedFields.has(path) || findAncestorInSet(path, this.encryptedFields)) continue;
+			if (this.encryptedFields.has(path) || require_validator.findAncestorInSet(path, this.encryptedFields)) continue;
 			const designType = resolveDesignType(type);
 			const isJson = this.jsonFields.has(path);
 			const isArray = designType === "array";
@@ -537,9 +778,9 @@ var TableMetadata = class {
 		for (const [path] of this.flatMap.entries()) {
 			if (!path) continue;
 			if (this.flattenedParents.has(path)) continue;
-			if (findAncestorInSet(path, this.jsonFields) !== void 0) continue;
-			if (findAncestorInSet(path, this.encryptedFields) !== void 0) continue;
-			const isFlattened = findAncestorInSet(path, this.flattenedParents) !== void 0;
+			if (require_validator.findAncestorInSet(path, this.jsonFields) !== void 0) continue;
+			if (require_validator.findAncestorInSet(path, this.encryptedFields) !== void 0) continue;
+			const isFlattened = require_validator.findAncestorInSet(path, this.flattenedParents) !== void 0;
 			const physicalName = relationalColumnName(path, this.columnMap.get(path), isFlattened);
 			this.pathToPhysical.set(path, physicalName);
 			this.physicalToPath.set(physicalName, path);
@@ -573,7 +814,7 @@ var TableMetadata = class {
 		for (const fd of this.fieldDescriptors) {
 			physicalNames.add(fd.physicalName);
 			if (fd.ignored) continue;
-			if (this.navFields.has(fd.path) || findAncestorInSet(fd.path, this.navFields) !== void 0) continue;
+			if (this.navFields.has(fd.path) || require_validator.findAncestorInSet(fd.path, this.navFields) !== void 0) continue;
 			this.descriptorByPath.set(fd.path, fd);
 			if (fd.storage === "json") jsonParents.add(fd.path);
 			if (isJsonValueField(fd)) jsonValueParents.add(fd.path);
@@ -617,12 +858,12 @@ var TableMetadata = class {
 		for (const [path, type] of this.flatMap.entries()) {
 			if (!path) continue;
 			if (!skipFlattening && this.flattenedParents.has(path)) continue;
-			if (!skipFlattening && findAncestorInSet(path, this.jsonFields) !== void 0) continue;
+			if (!skipFlattening && require_validator.findAncestorInSet(path, this.jsonFields) !== void 0) continue;
 			const isEncrypted = this.encryptedFields.has(path);
-			const underEncrypted = findAncestorInSet(path, this.encryptedFields) !== void 0;
+			const underEncrypted = require_validator.findAncestorInSet(path, this.encryptedFields) !== void 0;
 			if (!skipFlattening && underEncrypted) continue;
 			const isJson = this.jsonFields.has(path);
-			const isFlattened = !skipFlattening && findAncestorInSet(path, this.flattenedParents) !== void 0;
+			const isFlattened = !skipFlattening && require_validator.findAncestorInSet(path, this.flattenedParents) !== void 0;
 			const designType = isEncrypted ? "string" : isJson ? "json" : resolveDesignType(type);
 			let storage;
 			if (skipFlattening) storage = "column";
@@ -659,12 +900,17 @@ var TableMetadata = class {
 				unitCode,
 				unitRefField,
 				encrypted: isEncrypted || underEncrypted || void 0,
-				isGeoPoint: isGeoPointType(type) || void 0
+				isGeoPoint: isGeoPointType(type) || void 0,
+				derived: this.derivedFields.get(path)
 			});
 		}
 		this._resolveFkTargetFields(descriptors);
+		Object.freeze(descriptors);
+		this.fieldDescriptors = descriptors;
+		this.columnDescriptors = Object.freeze(descriptors.filter((fd) => !fd.ignored && !(skipFlattening && fd.derived)));
+		this.storedDescriptors = Object.freeze(descriptors.filter((fd) => !fd.ignored && !fd.derived));
 		const fmtHook = adapter.formatValue?.bind(adapter);
-		if (fmtHook) for (const fd of descriptors) {
+		if (fmtHook) for (const fd of this.columnDescriptors) {
 			const fmt = fmtHook(fd);
 			if (fmt) if (typeof fmt === "function") {
 				if (!this.toStorageFormatters) this.toStorageFormatters = /* @__PURE__ */ new Map();
@@ -680,8 +926,6 @@ var TableMetadata = class {
 				}
 			}
 		}
-		Object.freeze(descriptors);
-		this.fieldDescriptors = descriptors;
 	}
 	/**
 	* Resolves `fkTargetField` for FK fields in field descriptors.
@@ -915,6 +1159,79 @@ var UniquSelect = class UniquSelect {
 };
 //#endregion
 //#region src/strategies/field-mapping.ts
+const NO_PLAN = {
+	fill: [],
+	prune: [],
+	unexclude: /* @__PURE__ */ new Set()
+};
+/** The no-projection plan of a table (every derived field, nothing pruned) — built once per table. */
+const fullPlans = /* @__PURE__ */ new WeakMap();
+/** An object-form `$select` (inclusion or exclusion) — not an array. */
+function isObjectForm(select) {
+	return select !== null && typeof select === "object" && !Array.isArray(select);
+}
+/** An exclusion projection: object form whose first flag is not `1` / `true`. */
+function isExclusionProjection(select) {
+	if (!isObjectForm(select)) return false;
+	for (const flag of Object.values(select)) return flag !== 1 && flag !== true;
+	return false;
+}
+/**
+* The logical keys a read names, in one pass: the `$groupBy` dimensions
+* (array or single string) and the `$select` inclusions (array-form strings,
+* object-form keys flagged `1` / `true`). Empty without a projection.
+*/
+function requestedKeys(controls) {
+	const out = [];
+	const groupBy = controls?.$groupBy;
+	if (typeof groupBy === "string") out.push(groupBy);
+	else if (Array.isArray(groupBy)) {
+		for (const key of groupBy) if (typeof key === "string") out.push(key);
+	}
+	const select = controls?.$select;
+	if (Array.isArray(select)) {
+		for (const item of select) if (typeof item === "string") out.push(item);
+	} else if (isObjectForm(select)) {
+		for (const [key, flag] of Object.entries(select)) if (flag === 1 || flag === true) out.push(key);
+	}
+	return out;
+}
+/** {@link TPrunePath} of `path`, keeping the ancestors something in `requested` lives under. */
+function prunePath(path, requested) {
+	const segments = path.split(".");
+	for (let depth = segments.length - 1; depth >= 1; depth--) {
+		const prefix = `${segments.slice(0, depth).join(".")}.`;
+		for (const r of requested) if (r.startsWith(prefix)) return {
+			segments,
+			keep: depth
+		};
+	}
+	return {
+		segments,
+		keep: 0
+	};
+}
+/** Deletes a pruned path from a row, then every ancestor it left empty (down to `keep`). */
+function pruneNestedPath(row, { segments, keep }) {
+	require_validator.deletePath(row, segments);
+	for (let depth = segments.length - 1; depth > keep; depth--) {
+		const ancestor = segments.slice(0, depth);
+		const value = require_validator.getPath(row, ancestor);
+		if (!isObjectForm(value) || Object.keys(value).length > 0) return;
+		require_validator.deletePath(row, ancestor);
+	}
+}
+/**
+* Fills the `@db.column.derived` fields a read asked for from their source
+* leaf (as stored — no type guard; `null` for a missing leaf) and removes
+* the source paths the caller did not select, so an inclusion `$select` of
+* a derived field never leaks its source and an exclusion of the source
+* still yields the derived value.
+*/
+function fillDerived(row, plan) {
+	for (const [name, source] of plan.fill) row[name] = require_validator.getPath(row, source) ?? null;
+	for (const path of plan.prune) pruneNestedPath(row, path);
+}
 /** Coerces a storage value (0/1/null) back to a JS boolean. */
 function toBool(value) {
 	if (value === null || value === void 0) return value;
@@ -932,6 +1249,15 @@ function toDecimalString(value) {
 * and `RelationalFieldMapper` (flattened columns, SQL).
 */
 var FieldMappingStrategy = class {
+	/**
+	* {@link reconstructFromRead} over every row of one read — the per-read
+	* work (the derived read plan on document adapters) is done once for all
+	* of them. The default maps the rows one by one.
+	* @since 0.1.141
+	*/
+	reconstructRows(rows, meta, controls) {
+		return rows.map((row) => this.reconstructFromRead(row, meta, controls));
+	}
 	/**
 	* Whether {@link physicalPath} can differ from the logical path for this
 	* table; `false` lets the path translations hand their input back as-is.
@@ -1027,7 +1353,7 @@ var FieldMappingStrategy = class {
 	*/
 	translateFilter(filter, meta) {
 		if (!filter || typeof filter !== "object") return filter;
-		if (!meta.toStorageFormatters && meta.columnMap.size === 0) return filter;
+		if (!meta.toStorageFormatters && meta.columnMap.size === 0 && meta.derivedFields.size === 0) return filter;
 		const result = {};
 		for (const [key, value] of Object.entries(filter)) if (key === "$and" || key === "$or") result[key] = value.map((f) => this.translateFilter(f, meta));
 		else if (key === "$not") result[key] = this.translateFilter(value, meta);
@@ -1161,6 +1487,7 @@ var FieldMappingStrategy = class {
 			if (fieldType) data[pk] = adapter.prepareId(data[pk], fieldType);
 		}
 		for (const field of meta.ignoredFields) if (!field.includes(".")) delete data[field];
+		meta.stripDerived(data);
 	}
 };
 /**
@@ -1169,12 +1496,86 @@ var FieldMappingStrategy = class {
 * value coercion.
 */
 var DocumentFieldMapper = class extends FieldMappingStrategy {
-	reconstructFromRead(row, meta) {
+	reconstructFromRead(row, meta, controls) {
+		return this._reconstruct(row, meta, this._derivedPlanFor(meta, controls));
+	}
+	reconstructRows(rows, meta, controls) {
+		const plan = this._derivedPlanFor(meta, controls);
+		return rows.map((row) => this._reconstruct(row, meta, plan));
+	}
+	_derivedPlanFor(meta, controls) {
+		return meta.derivedFields.size > 0 ? this.derivedReadPlan(controls, meta) : void 0;
+	}
+	_reconstruct(row, meta, plan) {
 		this.coerceFieldValues(row, meta);
 		this.applyFromStorageFormatters(row, meta);
 		if (meta.columnMap.size > 0) this.reverseColumnRenames(row, meta);
+		if (plan) fillDerived(row, plan);
 		return row;
 	}
+	/** See {@link TDerivedReadPlan}. */
+	derivedReadPlan(controls, meta) {
+		if (meta.derivedFields.size === 0) return NO_PLAN;
+		const select = controls?.$select;
+		const groupBy = controls?.$groupBy;
+		if (!(Array.isArray(groupBy) ? groupBy.length > 0 : typeof groupBy === "string") && (select === void 0 || select === null || isObjectForm(select) && Object.keys(select).length === 0)) {
+			let plan = fullPlans.get(meta);
+			if (!plan) {
+				plan = {
+					fill: [...meta.derivedFields].map(([name, d]) => [name, d.sourcePath.split(".")]),
+					prune: [],
+					unexclude: /* @__PURE__ */ new Set()
+				};
+				fullPlans.set(meta, plan);
+			}
+			return plan;
+		}
+		const keys = requestedKeys(controls);
+		const requested = new Set(keys.filter((key) => !meta.derivedFields.has(key)));
+		const fill = [];
+		const prune = /* @__PURE__ */ new Set();
+		if (isExclusionProjection(select)) {
+			const excluded = new Set(Object.entries(select).filter(([, flag]) => flag === 0 || flag === false).map(([key]) => key));
+			const unexclude = /* @__PURE__ */ new Set();
+			for (const [name, derived] of meta.derivedFields) {
+				if (excluded.has(name)) continue;
+				fill.push([name, derived.sourcePath.split(".")]);
+				for (let key = require_validator.selfOrAncestor(derived.sourcePath, excluded); key !== void 0; key = require_validator.findAncestorInSet(key, excluded)) {
+					unexclude.add(key);
+					prune.add(key);
+				}
+			}
+			return {
+				fill,
+				prune: [...prune].map((p) => prunePath(p, requested)),
+				unexclude
+			};
+		}
+		const names = new Set(keys);
+		for (const [name, derived] of meta.derivedFields) {
+			if (!names.has(name)) continue;
+			fill.push([name, derived.sourcePath.split(".")]);
+			if (require_validator.selfOrAncestor(derived.sourcePath, requested) === void 0) prune.add(derived.sourcePath);
+		}
+		return {
+			fill,
+			prune: [...prune].map((p) => prunePath(p, requested)),
+			unexclude: /* @__PURE__ */ new Set()
+		};
+	}
+	/**
+	* {@link FieldMappingStrategy.physicalSelect} plus the derived-field rules
+	* of an exclusion projection: a derived key is not a stored path (dropping
+	* it just leaves the field unfilled), and the source subtree of a wanted
+	* derived field is fetched even when excluded (pruned after the read).
+	*/
+	physicalSelect(select, meta) {
+		if (meta.derivedFields.size === 0 || !isExclusionProjection(select)) return super.physicalSelect(select, meta);
+		const { unexclude } = this.derivedReadPlan({ $select: select }, meta);
+		const stored = {};
+		for (const [key, flag] of Object.entries(select)) if (!meta.derivedFields.has(key) && !unexclude.has(key)) stored[key] = flag;
+		return super.physicalSelect(stored, meta);
+	}
 	/**
 	* Every field-path position goes through `@db.column` renames
 	* ({@link TableMetadata.documentPath}): filter keys, `$select` fields
@@ -1199,7 +1600,7 @@ var DocumentFieldMapper = class extends FieldMappingStrategy {
 		return meta.documentPath(logical);
 	}
 	renamesPaths(meta) {
-		return meta.columnMap.size > 0;
+		return meta.columnMap.size > 0 || meta.derivedFields.size > 0;
 	}
 	prepareForWrite(payload, meta, adapter) {
 		const data = { ...payload };
@@ -1229,7 +1630,7 @@ var DocumentFieldMapper = class extends FieldMappingStrategy {
 * for queries, filters, and controls.
 */
 var RelationalFieldMapper = class extends FieldMappingStrategy {
-	reconstructFromRead(row, meta) {
+	reconstructFromRead(row, meta, _controls) {
 		if (!meta.requiresMappings) return this.applyFromStorageFormatters(this.coerceFieldValues(row, meta), meta);
 		if (meta.onlyColumnRenames) {
 			this.coerceFieldValues(row, meta);
@@ -1462,7 +1863,7 @@ function assertGeoPoint(point, path) {
 	}]);
 }
 function isEncryptedRef(meta, field) {
-	return meta.encryptedFields.has(field) || findAncestorInSet(field, meta.encryptedFields) !== void 0;
+	return meta.encryptedFields.has(field) || require_validator.findAncestorInSet(field, meta.encryptedFields) !== void 0;
 }
 function encryptedRefError(code, field, what) {
 	return new require_db_error.DbError(code, [{
@@ -1764,19 +2165,19 @@ function collectQueryPaths(query, aggregate) {
 */
 function classifyQueryPath(source, path) {
 	if (source.navFields.has(path)) return { kind: "nav" };
-	const navHead = findAncestorInSet(path, source.navFields);
+	const navHead = require_validator.findAncestorInSet(path, source.navFields);
 	if (navHead !== void 0) return {
 		kind: "nav",
 		parent: navHead
 	};
 	if (source.leaves.has(path)) return { kind: "leaf" };
 	if (source.objectParents.has(path)) return { kind: "objectParent" };
-	const jsonParent = findAncestorInSet(path, source.jsonParents);
+	const jsonParent = require_validator.findAncestorInSet(path, source.jsonParents);
 	if (jsonParent !== void 0) return {
 		kind: "jsonDescendant",
 		parent: jsonParent
 	};
-	const encryptedParent = findAncestorInSet(path, source.encryptedFields);
+	const encryptedParent = require_validator.findAncestorInSet(path, source.encryptedFields);
 	if (encryptedParent !== void 0) return {
 		kind: "encryptedDescendant",
 		parent: encryptedParent
@@ -2065,11 +2466,7 @@ var AtscriptDbReadable = class {
 		this._tableResolver = _tableResolver;
 		if (!(0, _atscript_typescript_utils.isAnnotatedType)(_type)) throw new Error("Atscript Annotated Type expected");
 		if (_type.type.kind !== "object") throw new Error("Database type must be an object type");
-		const adapterName = adapter.getAdapterTableName?.(_type);
-		const dbTable = _type.metadata.get("db.table");
-		const dbViewName = _type.metadata.get("db.view");
-		const fallbackName = _type.id || "";
-		this.tableName = adapterName || dbTable || dbViewName || fallbackName;
+		this.tableName = adapter.getAdapterTableName?.(_type) || require_nested_writer.tableNameOf(_type);
 		if (!this.tableName) throw new Error("@db.table or @db.view annotation expected");
 		this.schema = _type.metadata.get("db.schema");
 		this._syncMethod = _type.metadata.get("db.sync.method");
@@ -2239,11 +2636,25 @@ var AtscriptDbReadable = class {
 		return this._metaIdPhysical;
 	}
 	/**
-	* Physical column name of the field annotated with `@db.column.version`, or
-	* `undefined` when the table has no version column. Used by adapters and the
-	* REST integration to drive optimistic concurrency control (OCC).
+	* Logical field name of the field annotated with `@db.column.version`, or
+	* `undefined` when the table has no version column. This is the key used in
+	* `$cas: { <versionColumn>: N }`, in write payloads, in rows read back, and in
+	* `/meta`'s `versionColumn` — a `@db.column 'physical_name'` rename on the
+	* field changes only the storage column (see {@link versionColumnPhysical}).
 	*/
 	get versionColumn() {
+		this._ensureBuilt();
+		return this._meta.versionField;
+	}
+	/**
+	* Physical column name of the `@db.column.version` field (after any
+	* `@db.column` rename), or `undefined` when the table has no version column.
+	* Adapters use it for the auto-bump, the CAS predicate, and the insert-time
+	* `0` backfill — all of which operate on already-mapped physical rows.
+	*
+	* @internal Adapter-facing surface; not part of the consumer API.
+	*/
+	get versionColumnPhysical() {
 		this._ensureBuilt();
 		const field = this._meta.versionField;
 		if (field === void 0) return void 0;
@@ -2278,6 +2689,14 @@ var AtscriptDbReadable = class {
 		this._ensureBuilt();
 		return this._meta.ignoredFields;
 	}
+	/**
+	* `@db.column.derived` fields (logical name → what they read) — computed
+	* from a JSON leaf of the same row, never written. Since 0.1.141.
+	*/
+	get derivedFields() {
+		this._ensureBuilt();
+		return this._meta.derivedFields;
+	}
 	/** Navigational fields (`@db.rel.to` / `@db.rel.from`) — not stored as columns. */
 	get navFields() {
 		this._ensureBuilt();
@@ -2333,6 +2752,14 @@ var AtscriptDbReadable = class {
 		};
 	}
 	/**
+	* Physical rows of one read → logical rows: the field mapper's per-read
+	* work (the derived read plan on document adapters) is done once for all
+	* of them. Every read path funnels through here.
+	*/
+	_fromRead(rows, controls) {
+		return this._fieldMapper.reconstructRows(rows, this._meta, controls);
+	}
+	/**
 	* Pre-computed field metadata for adapter use.
 	*/
 	get fieldDescriptors() {
@@ -2340,6 +2767,26 @@ var AtscriptDbReadable = class {
 		return this._meta.fieldDescriptors;
 	}
 	/**
+	* The descriptors schema sync manages as columns: non-ignored, and on
+	* nested-object adapters without the `@db.column.derived` fields (they store
+	* nothing there). See `TableMetadata.columnDescriptors`.
+	* @since 0.1.141
+	*/
+	get columnDescriptors() {
+		this._ensureBuilt();
+		return this._meta.columnDescriptors;
+	}
+	/**
+	* The columns that hold a value of their own (non-ignored, not derived) —
+	* what a table recreation copies and a full replace assigns. See
+	* `TableMetadata.storedDescriptors`.
+	* @since 0.1.141
+	*/
+	get storedDescriptors() {
+		this._ensureBuilt();
+		return this._meta.storedDescriptors;
+	}
+	/**
 	* The target table of the navigation relation `navField` (since 0.1.134),
 	* resolved through the table resolver this readable was built with (the
 	* `DbSpace`'s). `undefined` when `navField` is not a relation of this table
@@ -2399,7 +2846,7 @@ var AtscriptDbReadable = class {
 		const translatedQuery = this._fieldMapper.translateQuery(query, this._meta);
 		const result = await this.adapter.findOne(translatedQuery);
 		if (!result) return null;
-		const row = this._fieldMapper.reconstructFromRead(result, this._meta);
+		const [row] = this._fromRead([result], query.controls);
 		await this._decryptRows([row]);
 		if (withRelations?.length) await this.loadRelations([row], withRelations);
 		return row;
@@ -2414,7 +2861,8 @@ var AtscriptDbReadable = class {
 		this._guardQuery(query);
 		const withRelations = query.controls?.$with;
 		const translatedQuery = this._fieldMapper.translateQuery(query, this._meta);
-		const rows = (await this.adapter.findMany(translatedQuery)).map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		const results = await this.adapter.findMany(translatedQuery);
+		const rows = this._fromRead(results, query.controls);
 		await this._decryptRows(rows);
 		if (withRelations?.length) await this.loadRelations(rows, withRelations);
 		return rows;
@@ -2440,7 +2888,7 @@ var AtscriptDbReadable = class {
 		const withRelations = query.controls?.$with;
 		const translated = this._fieldMapper.translateQuery(query, this._meta);
 		const result = await this.adapter.findManyWithCount(translated);
-		const rows = result.data.map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		const rows = this._fromRead(result.data, query.controls);
 		await this._decryptRows(rows);
 		if (withRelations?.length) await this.loadRelations(rows, withRelations);
 		return {
@@ -2521,7 +2969,8 @@ var AtscriptDbReadable = class {
 		}
 		guardAggregate(this._meta, this.adapter, query, buckets);
 		const dbQuery = this._fieldMapper.translateAggregateQuery(query, this._meta, buckets);
-		return (await this.adapter.aggregate(dbQuery)).map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		const results = await this.adapter.aggregate(dbQuery);
+		return this._fromRead(results, query.controls);
 	}
 	/** Whether the underlying adapter supports text search. */
 	isSearchable() {
@@ -2556,7 +3005,8 @@ var AtscriptDbReadable = class {
 		this._guardQuery(query);
 		const withRelations = query.controls?.$with;
 		const translated = this._fieldMapper.translateQuery(query, this._meta);
-		const rows = (await this.adapter.search(text, translated, indexName)).map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		const results = await this.adapter.search(text, translated, indexName);
+		const rows = this._fromRead(results, query.controls);
 		await this._decryptRows(rows);
 		if (withRelations?.length) await this.loadRelations(rows, withRelations);
 		return rows;
@@ -2571,7 +3021,7 @@ var AtscriptDbReadable = class {
 		const withRelations = query.controls?.$with;
 		const translated = this._fieldMapper.translateQuery(query, this._meta);
 		const result = await this.adapter.searchWithCount(text, translated, indexName);
-		const rows = result.data.map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		const rows = this._fromRead(result.data, query.controls);
 		await this._decryptRows(rows);
 		if (withRelations?.length) await this.loadRelations(rows, withRelations);
 		return {
@@ -2596,7 +3046,8 @@ var AtscriptDbReadable = class {
 		this._guardQuery(query);
 		const withRelations = (query?.controls)?.$with;
 		const translated = this._fieldMapper.translateQuery(query || {}, this._meta);
-		const rows = (await this.adapter.vectorSearch(vector, translated, indexName)).map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		const results = await this.adapter.vectorSearch(vector, translated, indexName);
+		const rows = this._fromRead(results, query?.controls);
 		await this._decryptRows(rows);
 		if (withRelations?.length) await this.loadRelations(rows, withRelations);
 		return rows;
@@ -2615,7 +3066,7 @@ var AtscriptDbReadable = class {
 		const withRelations = (query?.controls)?.$with;
 		const translated = this._fieldMapper.translateQuery(query || {}, this._meta);
 		const result = await this.adapter.vectorSearchWithCount(vector, translated, indexName);
-		const rows = result.data.map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		const rows = this._fromRead(result.data, query?.controls);
 		await this._decryptRows(rows);
 		if (withRelations?.length) await this.loadRelations(rows, withRelations);
 		return {
@@ -2653,7 +3104,8 @@ var AtscriptDbReadable = class {
 	async geoSearch(pointOrIndex, maybePointOrQuery, maybeQuery) {
 		const { point, query, indexName } = this._resolveGeoSearchArgs(pointOrIndex, maybePointOrQuery, maybeQuery);
 		const { translated, withRelations } = this._prepareGeoSearch(point, query, indexName);
-		const rows = (await this.adapter.geoSearch(point, translated, indexName)).map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		const results = await this.adapter.geoSearch(point, translated, indexName);
+		const rows = this._fromRead(results, query?.controls);
 		await this._decryptRows(rows);
 		if (withRelations?.length) await this.loadRelations(rows, withRelations);
 		return rows;
@@ -2669,7 +3121,7 @@ var AtscriptDbReadable = class {
 		const { point, query, indexName } = this._resolveGeoSearchArgs(pointOrIndex, maybePointOrQuery, maybeQuery);
 		const { translated, withRelations } = this._prepareGeoSearch(point, query, indexName);
 		const result = await this.adapter.geoSearchWithCount(point, translated, indexName);
-		const rows = result.data.map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		const rows = this._fromRead(result.data, query?.controls);
 		await this._decryptRows(rows);
 		if (withRelations?.length) await this.loadRelations(rows, withRelations);
 		return {
@@ -2829,7 +3281,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-6ZB_5KFq.cjs")).then((n) => n.relation_loader_exports);
+		const { loadRelationsImpl } = await Promise.resolve().then(() => require("./relation-loader-CgJ8bK6X.cjs")).then((n) => n.relation_loader_exports);
 		return loadRelationsImpl(rows, withRelations, this);
 	}
 	/**
@@ -4306,6 +4758,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				for (const navField of this._meta.navFields) delete data[navField];
 				const filter = this._extractRecordFilter(data, opts);
 				for (const key of Object.keys(filter)) delete data[key];
+				this._meta.stripDerived(data);
 				if (versionColumn !== void 0) assertNoVersionWrites(data, versionColumn);
 				const translatedFilter = this._fieldMapper.translateFilter(filter, this._meta);
 				if (require_validator.isEmptyObject(data) && expectedVersion === void 0) {
@@ -4455,6 +4908,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		this._guardMutationFilter(filter);
 		await this._integrity.validateForeignKeys([data], this._meta, this._fkLookupResolver, this._writeTableResolver, true);
 		const dataCopy = _cloneWritePayload(data);
+		this._meta.stripDerived(dataCopy);
 		const versionColumn = this.versionColumn;
 		if ("$cas" in dataCopy) throw new require_db_error.DbError("INVALID_QUERY", [{
 			path: "$cas",
@@ -4738,120 +5192,6 @@ 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}`);
@@ -4881,11 +5221,6 @@ function readViewAgg(metadata) {
 		};
 	}
 }
-const JSON_LEAF_TYPES = new Set([
-	"string",
-	"number",
-	"boolean"
-]);
 /**
 * Database view abstraction driven by Atscript `@db.view.*` annotations.
 *
@@ -4927,16 +5262,19 @@ 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 entryTable = require_nested_writer.tableNameOf(entryType());
+		const entry = viewSourceOf(entryType());
+		if (entry.alias) throw new Error(`View "${this.tableName}": @db.view.for "${entry.name}" is a @db.alias — a join alias cannot be the entry table`);
+		const entryTable = entry.table;
 		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 target = viewSourceOf(targetType());
 			joins.push({
 				targetType,
-				targetTable: require_nested_writer.tableNameOf(targetTypeResolved),
+				targetTable: target.table,
+				scope: target.name,
 				condition: join.condition,
 				kind: join.kind === "left" ? "left" : "inner"
 			});
@@ -4960,19 +5298,22 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 	}
 	/**
 	* Resolves a view query field ref (join condition, `@db.view.filter`,
-	* conditional-aggregate predicate) to its table name and PHYSICAL source on
+	* conditional-aggregate predicate) to its scope 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.
+	* absent. An unqualified ref resolves against the entry table. `table` is
+	* the physical table / view name, or the alias name for a `@db.alias`
+	* target (since 0.1.141); a source that is itself a managed view resolves
+	* to that view's own columns.
 	* @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();
+		const src = viewSourceOf(ref.type ? ref.type() : this.viewPlan.entryType());
 		return {
-			table: require_nested_writer.tableNameOf(type),
-			source: resolveViewSource(type, ref.field, this._nested)
+			table: src.name,
+			source: resolveViewSource(src.type, ref.field, this._nested)
 		};
 	}
 	/**
@@ -5024,7 +5365,7 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		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));
+		const leftJoined = new Set(plan.joins.filter((j) => j.kind === "left").map((j) => j.scope));
 		for (const [fieldName, fieldType] of this._type.type.props.entries()) {
 			if (ignored.has(fieldName)) continue;
 			const agg = readViewAgg(fieldType.metadata);
@@ -5032,16 +5373,18 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 			if (aggField === "*" && agg?.aggFn !== "count") fail(fieldName, `aggregate "${agg?.aggFn}" needs a field — only count accepts *`);
 			let sourceType;
 			let sourcePath;
-			if (fieldType.ref) {
-				sourceType = fieldType.ref.type();
-				sourcePath = fieldType.ref.field || fieldName;
+			const chainRef = fieldType.ref?.field ? fieldType.ref : void 0;
+			if (chainRef) {
+				sourceType = chainRef.type();
+				sourcePath = chainRef.field;
 			} else {
 				sourceType = plan.entryType();
 				sourcePath = aggField && aggField !== "*" ? aggField : fieldName;
 			}
-			const sourceTable = require_nested_writer.tableNameOf(sourceType);
+			const src = viewSourceOf(sourceType);
+			const sourceTable = src.name;
 			const joinNullable = leftJoined.has(sourceTable);
-			if (aggField === "*" && !fieldType.ref) {
+			if (aggField === "*" && !chainRef) {
 				mappings.push({
 					viewColumn: viewName(fieldName) ?? fieldName,
 					viewPath: fieldName,
@@ -5051,7 +5394,7 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 				});
 				continue;
 			}
-			const source = resolveViewSource(sourceType, sourcePath, nested);
+			const source = resolveViewSource(src.type, 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");
@@ -5059,7 +5402,7 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 				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);
+					const leaf = resolveViewSource(src.type, leafPath, nested);
 					mappings.push(this._leafMapping(viewPath, viewColumn, sourceTable, leaf, joinNullable));
 				}
 				continue;
@@ -5083,7 +5426,7 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		};
 		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`);
+			if (!require_derived_rules.isJsonLeafType(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
@@ -5106,9 +5449,33 @@ function isAtscriptDbView(readable) {
 }
 //#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) => {
+/**
+* The physical sources a stored view snapshot reads: its entry table and the
+* physical table of every join (an aliased join's `table`). External views
+* (no plan) yield `[]`.
+* @since 0.1.141
+*/
+function viewSnapshotSources(snapshot) {
+	const sources = (snapshot.joinTables ?? []).map((j) => j.table ?? j.targetTable);
+	return snapshot.entryTable ? [snapshot.entryTable, ...sources] : sources;
+}
+/**
+* The descriptors a snapshot lists: the non-ignored ones — plus, on a
+* nested-object adapter, the subfields of navigation properties. Those are
+* `ignored` since 0.1.141 (never columns: out of the plan, the column diff
+* and every write), but earlier releases wrote them into a document
+* adapter's snapshot; they stay listed so the upgrade leaves every stored
+* hash unchanged. {@link snapshotToExistingColumns} (given the readable)
+* leaves them out when a stored snapshot stands in for the live columns.
+*/
+function snapshotFields(readable) {
+	const nav = readable.navFields;
+	if (!nav?.size || !readable.dbAdapter.supportsNestedObjects()) return readable.fieldDescriptors.filter((f) => !f.ignored);
+	return readable.fieldDescriptors.filter((f) => !f.ignored || require_validator.findAncestorInSet(f.path, nav) !== void 0);
+}
+/** Extracts sorted field snapshots from a readable's {@link snapshotFields}. */
+function extractFieldSnapshots(readable, typeMapper) {
+	return snapshotFields(readable).map((f) => {
 		const snap = {
 			physicalName: f.physicalName,
 			designType: f.designType,
@@ -5119,6 +5486,11 @@ function extractFieldSnapshots(fields, typeMapper) {
 		if (f.defaultValue) snap.defaultValue = f.defaultValue;
 		if (typeMapper) snap.mappedType = typeMapper(f);
 		if (f.encrypted) snap.encrypted = true;
+		if (f.derived) snap.derived = {
+			sourceColumn: f.derived.sourceColumn,
+			jsonPath: [...f.derived.jsonPath],
+			type: f.derived.type
+		};
 		return snap;
 	}).toSorted((a, b) => a.physicalName.localeCompare(b.physicalName));
 }
@@ -5132,7 +5504,7 @@ function extractFieldSnapshots(fields, typeMapper) {
 *   for precise type change detection.
 */
 function computeTableSnapshot(readable, typeMapper, tableOptions) {
-	const fields = extractFieldSnapshots(readable.fieldDescriptors, typeMapper);
+	const fields = extractFieldSnapshots(readable, typeMapper);
 	const indexes = [...readable.indexes.values()].map((idx) => ({
 		key: idx.key,
 		type: idx.type,
@@ -5163,7 +5535,7 @@ function computeTableSnapshot(readable, typeMapper, tableOptions) {
 * detecting view definition changes.
 */
 function computeViewSnapshot(view) {
-	const fields = extractFieldSnapshots(view.fieldDescriptors);
+	const fields = extractFieldSnapshots(view);
 	if (view.isExternal) return {
 		tableName: view.tableName,
 		viewType: "E",
@@ -5193,7 +5565,8 @@ function computeViewSnapshot(view) {
 		entryTable: plan.entryTable,
 		joinTables: plan.joins.map((j) => {
 			const join = {
-				targetTable: j.targetTable,
+				targetTable: j.scope,
+				...j.scope !== j.targetTable ? { table: j.targetTable } : {},
 				condition: canonical(j.condition)
 			};
 			if (j.kind === "left") join.kind = "left";
@@ -5255,10 +5628,19 @@ function computeTableHash(snapshot) {
 * native column introspection (e.g., MongoDB).
 *
 * The `type` field uses `mappedType` when available (adapter-specific),
-* falling back to `designType`.
+* falling back to `designType`. Derived fields are left out (since 0.1.141):
+* an adapter without column introspection stores no derived column, and a
+* `physicalName` of one is its SOURCE path — reporting it as an existing
+* column would have the diff drop the source leaf.
+*
+* With `readable`, the subfields of its navigation properties are left out
+* too: a document adapter's snapshot lists them (for hash stability — see
+* `snapshotFields`) although nothing is stored under a nav field — they are
+* not columns to drop.
 */
-function snapshotToExistingColumns(snapshot) {
-	return snapshot.fields.map((f) => ({
+function snapshotToExistingColumns(snapshot, readable) {
+	const navPrefixes = readable && readable.navFields.size > 0 ? readable.fieldDescriptors.filter((fd) => readable.navFields.has(fd.path)).map((fd) => `${fd.physicalName}.`) : [];
+	return snapshot.fields.filter((f) => !f.derived && !navPrefixes.some((p) => f.physicalName.startsWith(p))).map((f) => ({
 		name: f.physicalName,
 		type: f.mappedType ?? f.designType,
 		notnull: !f.optional,
@@ -5337,6 +5719,18 @@ function fkPropertiesDiffer(desired, existing) {
 //#endregion
 //#region src/schema/column-diff.ts
 /**
+* Why a derived column (desired, live, or both) must be dropped and re-added,
+* or `undefined` when it is unchanged. Nullability and defaults are never
+* compared for one: a generated column is nullable and has no DEFAULT.
+*/
+function derivedChangeReason(field, existingCol, typeMapper, snap) {
+	if (!field.derived) return existingCol.generated ? "kind" : void 0;
+	if (!existingCol.generated) return "kind";
+	const stored = snap?.derived;
+	if (stored && (stored.sourceColumn !== field.derived.sourceColumn || stored.type !== field.derived.type || stored.jsonPath.length !== field.derived.jsonPath.length || stored.jsonPath.some((seg, i) => seg !== field.derived.jsonPath[i]))) return "expression";
+	if (typeMapper && isColumnTypeChanged(existingCol.type, typeMapper(field))) return "type";
+}
+/**
 * 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
@@ -5349,15 +5743,22 @@ function isColumnTypeChanged(existingType, expectedType) {
 /**
 * Computes the difference between desired schema fields and existing database columns.
 *
-* @param desired - Field descriptors from the Atscript type (after flattening).
+* @param desired - Field descriptors from the Atscript type (after flattening) —
+*                  the readable's `columnDescriptors`; ignored descriptors are skipped.
 * @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.
+* @param opts.snapshot - The table's stored snapshot (since 0.1.141) — the baseline a
+*                        derived column's expression is compared with (the engine normalizes
+*                        the expression it stores, so the live column cannot be). Without
+*                        one, only a kind or type drift is seen.
 */
-function computeColumnDiff(desired, existing, typeMapper) {
+function computeColumnDiff(desired, existing, typeMapper, opts) {
 	const existingByName = new Map(existing.map((c) => [c.name, c]));
+	const snapshotByName = opts?.snapshot ? new Map(opts.snapshot.fields.map((f) => [f.physicalName, f])) : void 0;
+	const derivedChanged = [];
 	const desiredByName = /* @__PURE__ */ new Map();
 	const renamedOldNames = /* @__PURE__ */ new Set();
 	const added = [];
@@ -5366,44 +5767,60 @@ function computeColumnDiff(desired, existing, typeMapper) {
 	const nullableChanged = [];
 	const defaultChanged = [];
 	const conflicts = [];
+	/**
+	* A derived column (on either side) is compared as a whole — any drift is a
+	* drop + add, and nullability / defaults are not the model's to manage.
+	* `true` when the pair was a derived one (handled here).
+	*/
+	const checkDerived = (field, col, snapKey) => {
+		if (!field.derived && !col.generated) return false;
+		const reason = derivedChangeReason(field, col, typeMapper, snapshotByName?.get(snapKey));
+		if (reason) derivedChanged.push({
+			field,
+			reason
+		});
+		return true;
+	};
 	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({
+		if (existingCol) {
+			if (field.renamedFrom && existingByName.has(field.renamedFrom)) {
+				conflicts.push({
 					field,
-					existingType: existingCol.type
+					oldName: field.renamedFrom,
+					conflictsWith: field.physicalName
 				});
-			}
-			if (!field.isPrimaryKey && !existingCol.pk) {
-				const desiredNotNull = !field.optional;
-				if (existingCol.notnull !== desiredNotNull) nullableChanged.push({
+				renamedOldNames.add(field.renamedFrom);
+			} else if (!checkDerived(field, existingCol, field.physicalName)) {
+				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,
-					wasNullable: !existingCol.notnull
+					oldDefault: existingCol.dflt_value,
+					newDefault: desiredDefault
 				});
 			}
-			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)) {
+		} else if (field.renamedFrom && existingByName.has(field.renamedFrom)) {
 			renamed.push({
 				field,
 				oldName: field.renamedFrom
 			});
 			renamedOldNames.add(field.renamedFrom);
+			checkDerived(field, existingByName.get(field.renamedFrom), field.renamedFrom);
 		} else added.push(field);
 	}
 	const diff = {
@@ -5415,6 +5832,7 @@ function computeColumnDiff(desired, existing, typeMapper) {
 		defaultChanged,
 		conflicts
 	};
+	if (derivedChanged.length > 0) diff.derivedChanged = derivedChanged;
 	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);
@@ -5529,6 +5947,12 @@ Object.defineProperty(exports, "acceptedOperatorsHint", {
 		return acceptedOperatorsHint;
 	}
 });
+Object.defineProperty(exports, "aliasTargetOf", {
+	enumerable: true,
+	get: function() {
+		return aliasTargetOf;
+	}
+});
 Object.defineProperty(exports, "assertGeoPoint", {
 	enumerable: true,
 	get: function() {
@@ -5625,12 +6049,6 @@ Object.defineProperty(exports, "decomposePatch", {
 		return decomposePatch;
 	}
 });
-Object.defineProperty(exports, "findAncestorInSet", {
-	enumerable: true,
-	get: function() {
-		return findAncestorInSet;
-	}
-});
 Object.defineProperty(exports, "fkKey", {
 	enumerable: true,
 	get: function() {
@@ -5763,3 +6181,9 @@ Object.defineProperty(exports, "unsupportedOperatorMessage", {
 		return unsupportedOperatorMessage;
 	}
 });
+Object.defineProperty(exports, "viewSnapshotSources", {
+	enumerable: true,
+	get: function() {
+		return viewSnapshotSources;
+	}
+});