@atscript/db 0.1.146 → 0.1.147

package/dist/{column-diff-D_Kyuh0S.cjs → column-diff-Dt7EDJsA.cjs}

@@ -1,6 +1,6 @@
 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-xfQwxplL.cjs");
+const require_aggregate_fns = require("./aggregate-fns-CtsRbZn9.cjs");
+const require_nested_writer = require("./nested-writer-SqtYJHF0.cjs");
 const require_derived_rules = require("./derived-rules-YstgIxG-.cjs");
 const require_object = require("./object-Djg28csK.cjs");
 require("./agg.cjs");
@@ -471,6 +471,14 @@ var TableMetadata = class {
 	jsonValueParents = /* @__PURE__ */ new Set();
 	/** Every field descriptor's `physicalName` — reserved names a bucket alias may not take. */
 	physicalNames = /* @__PURE__ */ new Set();
+	/**
+	* Resolves / guards relational filter predicates (`{ nav: { $some: … } }`)
+	* against the related tables — installed by the owning readable when the
+	* table has navigation fields and a table resolver (a `DbSpace`). The field
+	* mappers and the path guard reach the related tables through it.
+	* @since 0.1.147
+	*/
+	relationFilters;
 	_built = false;
 	_identifications;
 	_alwaysAddressable;
@@ -552,7 +560,7 @@ var TableMetadata = class {
 		if (!this.nestedObjects) this._classifyFields();
 		const overrides = adapter.getMetadataOverrides?.(this);
 		if (overrides) this._applyOverrides(overrides);
-		this._buildFieldDescriptors(adapter);
+		this._buildFieldDescriptors(adapter, type);
 		this._buildGuardIndexes();
 		if (!this.nestedObjects) this._buildLeafIndexes();
 		this._buildIdentifications();
@@ -615,12 +623,15 @@ var TableMetadata = class {
 			const isArr = fieldType.type.kind === "array";
 			const elementType = isArr ? fieldType.type.of : fieldType;
 			const resolveTarget = () => elementType?.ref?.type() ?? elementType;
+			const relFilter = metadata.get("db.rel.filter");
 			this.relations.set(fieldName, {
 				direction,
 				alias,
 				targetType: resolveTarget,
 				isArray: isArr,
-				...direction === "via" ? { viaType: raw } : {}
+				...direction === "via" ? { viaType: raw } : {},
+				...metadata.has("db.rel.filterable") ? { filterable: true } : {},
+				...relFilter ? { filter: relFilter } : {}
 			});
 		}
 		if (metadata.has("db.rel.FK")) {
@@ -878,7 +889,7 @@ var TableMetadata = class {
 	* Called once during build() — everything it needs
 	* (flatMap, indexes, columnMap, etc.) is already populated.
 	*/
-	_buildFieldDescriptors(adapter) {
+	_buildFieldDescriptors(adapter, rootType) {
 		const descriptors = [];
 		const skipFlattening = this.nestedObjects;
 		const indexedFields = new Set([...this.primaryKeys, ...this.uniqueProps]);
@@ -929,10 +940,21 @@ var TableMetadata = class {
 				unitRefField,
 				encrypted: isEncrypted || underEncrypted || void 0,
 				isGeoPoint: isGeoPointType(type) || void 0,
-				derived: this.derivedFields.get(path)
+				derived: this.derivedFields.get(path),
+				computed: computedMeta(rootType, path)
 			});
 		}
-		this._resolveFkTargetFields(descriptors);
+		const flatCache = /* @__PURE__ */ new Map();
+		const flatOf = (type) => {
+			let flat = flatCache.get(type);
+			if (!flat) {
+				flat = (0, _atscript_typescript_utils.flattenAnnotatedType)(type);
+				flatCache.set(type, flat);
+			}
+			return flat;
+		};
+		this._resolveFkTargetFields(descriptors, flatOf);
+		this._resolveFkPhysicalFields(flatOf);
 		Object.freeze(descriptors);
 		this.fieldDescriptors = descriptors;
 		this.columnDescriptors = Object.freeze(descriptors.filter((fd) => !fd.ignored && !(skipFlattening && fd.derived)));
@@ -956,9 +978,37 @@ var TableMetadata = class {
 		}
 	}
 	/**
+	* Fills `physicalFields` / `physicalTargetFields` on every FK: the local
+	* side from this table's path maps, the target side from the referenced
+	* type's own `@db.column` renames (same storage rules as this table — a
+	* dotted target path is a flattened column on relational storage, a
+	* renamed top-level key on document storage).
+	*/
+	_resolveFkPhysicalFields(flatOf) {
+		const targetPhysical = (fk, field) => {
+			const targetType = fk.targetTypeRef?.();
+			if (!targetType) return field;
+			const flat = flatOf(targetType);
+			const columnOf = (path) => flat.get(path)?.metadata?.get("db.column");
+			if (this.nestedObjects) {
+				const dot = field.indexOf(".");
+				const top = dot === -1 ? field : field.slice(0, dot);
+				const renamed = columnOf(top);
+				return renamed === void 0 ? field : renamed + field.slice(top.length);
+			}
+			return relationalColumnName(field, columnOf(field), field.includes("."));
+		};
+		for (const fk of this.foreignKeys.values()) {
+			fk.physicalFields = fk.fields.map((f) => this.physicalPath(f));
+			fk.physicalTargetFields = fk.targetFields.map((f) => targetPhysical(fk, f));
+			const targetSchema = fk.targetTypeRef?.()?.metadata?.get("db.schema");
+			if (targetSchema) fk.targetSchema = targetSchema;
+		}
+	}
+	/**
 	* Resolves `fkTargetField` for FK fields in field descriptors.
 	*/
-	_resolveFkTargetFields(descriptors) {
+	_resolveFkTargetFields(descriptors, flatOf) {
 		if (this.foreignKeys.size === 0) return;
 		const fkFieldToTarget = /* @__PURE__ */ new Map();
 		for (const fk of this.foreignKeys.values()) {
@@ -969,18 +1019,12 @@ var TableMetadata = class {
 			});
 		}
 		if (fkFieldToTarget.size === 0) return;
-		const flatCache = /* @__PURE__ */ new Map();
 		for (const descriptor of descriptors) {
 			const target = fkFieldToTarget.get(descriptor.path);
 			if (!target) continue;
 			const targetType = target.targetTypeRef();
 			if (!targetType) continue;
-			let targetFlatMap = flatCache.get(targetType);
-			if (!targetFlatMap) {
-				targetFlatMap = (0, _atscript_typescript_utils.flattenAnnotatedType)(targetType);
-				flatCache.set(targetType, targetFlatMap);
-			}
-			const targetFieldType = targetFlatMap.get(target.targetField);
+			const targetFieldType = flatOf(targetType).get(target.targetField);
 			if (!targetFieldType) continue;
 			const targetMetadata = targetFieldType.metadata;
 			if (targetMetadata?.has("db.encrypted")) throw new Error(`FK field "${descriptor.path}" references encrypted field "${target.targetField}" — joins are impossible over ciphertext`);
@@ -1072,6 +1116,15 @@ var TableMetadata = class {
 		this.preferredId = selected ? [...selected.fields] : [...this.primaryKeys];
 	}
 };
+/** `TDbFieldMeta.computed` of a top-level `@db.compute` view field (since 0.1.147). */
+function computedMeta(rootType, path) {
+	if (path.includes(".")) return void 0;
+	const computed = require_nested_writer.computedOperands(rootType, path);
+	return computed ? {
+		operands: Object.freeze(computed.operands),
+		via: Object.freeze(computed.via)
+	} : void 0;
+}
 //#endregion
 //#region src/query/uniqu-select.ts
 /**
@@ -1372,19 +1425,43 @@ var FieldMappingStrategy = class {
 		return translated;
 	}
 	/**
-	* Recursively walks a filter expression, applying `@db.column` key renames
-	* (document paths — {@link TableMetadata.documentPath}) and adapter-specific
-	* value formatting via `formatFilterValue`.
+	* Translates a logical filter for the adapter: relational predicates are
+	* resolved first (`resolveRelationFilterTree`), then every key and value
+	* goes through {@link translateResolvedFilter}. `depth` is the predicate
+	* level of `filter` itself (0 for a query's own filter; the related tables
+	* translate predicate operands at deeper levels).
+	*/
+	translateFilter(filter, meta, depth = 0) {
+		const has = require_nested_writer.containsRelationFilter(filter);
+		const resolved = has ? require_nested_writer.resolveRelationFilterTree(filter, meta, depth) : filter;
+		return this.noteTranslated(filter, this.translateResolvedFilter(resolved, meta), has);
+	}
+	/**
+	* `out` — the translation of the caller's `filter` — with its pre-scan
+	* result (`has`) cached for the adapter's repeated `containsRelationFilter`
+	* checks; only when the core built it (never the caller's own object).
+	*/
+	noteTranslated(filter, out, has) {
+		if (out !== filter) require_nested_writer.noteRelationFilter(out, has);
+		return out;
+	}
+	/**
+	* Recursively walks a filter expression (predicates already resolved),
+	* applying `@db.column` key renames (document paths —
+	* {@link TableMetadata.documentPath}) and adapter-specific value formatting
+	* via `formatFilterValue`. A resolved predicate passes through under its
+	* navigation-field key.
 	*
 	* The relational mapper overrides this to use `leafByLogical` for deeper
 	* key resolution (flattened nested paths).
 	*/
-	translateFilter(filter, meta) {
+	translateResolvedFilter(filter, meta) {
 		if (!filter || typeof filter !== "object") 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);
+		for (const [key, value] of Object.entries(filter)) if (key === "$and" || key === "$or") result[key] = value.map((f) => this.translateResolvedFilter(f, meta));
+		else if (key === "$not") result[key] = this.translateResolvedFilter(value, meta);
+		else if (meta.navFields.has(key)) result[key] = value;
 		else if (key.startsWith("$")) result[key] = value;
 		else {
 			const physical = this.physicalPath(key, meta);
@@ -1686,10 +1763,13 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 		return result;
 	}
 	translateQuery(query, meta) {
+		const logical = query.filter;
+		const has = require_nested_writer.containsRelationFilter(logical);
+		const filter = has ? require_nested_writer.resolveRelationFilterTree(logical, meta, 0) : logical;
 		if (!meta.requiresMappings) {
 			const controls = query.controls;
 			return {
-				filter: meta.toStorageFormatters ? this.translateFilter(query.filter, meta) : query.filter,
+				filter: meta.toStorageFormatters ? this.noteTranslated(logical, this.translateResolvedFilter(filter, meta), has) : filter,
 				controls: {
 					...controls,
 					$with: void 0,
@@ -1699,7 +1779,7 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 			};
 		}
 		return {
-			filter: this.translateFilterWithRename(query.filter, meta),
+			filter: this.noteTranslated(logical, this.translateFilterWithRename(filter, meta), has),
 			controls: query.controls ? this.translateControls(query.controls, meta) : {},
 			insights: query.insights
 		};
@@ -1709,10 +1789,10 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 		return meta.leafByLogical.get(logical)?.physicalName ?? logical;
 	}
 	/**
-	* Overrides the base `translateFilter` to use `leafByLogical` for key resolution
+	* Overrides the base `translateResolvedFilter` to use `leafByLogical` for key resolution
 	* (handles flattened nested paths like `contact.email` → `contact__email`).
 	*/
-	translateFilter(filter, meta) {
+	translateResolvedFilter(filter, meta) {
 		if (!filter || typeof filter !== "object") return filter;
 		if (!meta.requiresMappings && !meta.toStorageFormatters) return filter;
 		return this.translateFilterWithRename(filter, meta);
@@ -1720,13 +1800,16 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 	/**
 	* Translates filter with key renaming from logical to physical names.
 	* Used by the relational query path where field paths must be mapped
-	* to `__`-separated column names.
+	* to `__`-separated column names. Relational predicates must already be
+	* resolved (`translateFilter` / `translateQuery` do it); a resolved
+	* predicate passes through under its navigation-field key.
 	*/
 	translateFilterWithRename(filter, meta) {
 		if (!filter || typeof filter !== "object") return filter;
 		const result = {};
 		for (const [key, value] of Object.entries(filter)) if (key === "$and" || key === "$or") result[key] = value.map((f) => this.translateFilterWithRename(f, meta));
 		else if (key === "$not") result[key] = this.translateFilterWithRename(value, meta);
+		else if (meta.navFields.has(key)) result[key] = value;
 		else if (key.startsWith("$")) result[key] = value;
 		else {
 			const physical = meta.leafByLogical.get(key)?.physicalName ?? key;
@@ -1856,6 +1939,234 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 	}
 };
 //#endregion
+//#region src/query/filter-values.ts
+const OPAQUE = {
+	kinds: new Set(["any"]),
+	timestamp: false
+};
+const NUMBER = {
+	kinds: new Set(["number"]),
+	timestamp: false
+};
+const INTEGER = {
+	kinds: new Set(["integer"]),
+	timestamp: false
+};
+const STRING = {
+	kinds: new Set(["string"]),
+	timestamp: false
+};
+function collectKinds(type, kinds, out, depth = 0) {
+	const def = type?.type;
+	const metadata = type?.metadata;
+	if (!def || depth > 8) {
+		kinds.add("any");
+		return;
+	}
+	switch (def.kind) {
+		case "": switch (def.designType) {
+			case "string":
+				kinds.add("string");
+				return;
+			case "number": {
+				const timestamp = def.tags?.has("timestamp") === true;
+				if (timestamp) out.timestamp = true;
+				const integer = timestamp || def.tags?.has("int") === true || metadata?.has?.("expect.int") === true;
+				kinds.add(integer ? "integer" : "number");
+				return;
+			}
+			case "decimal":
+				kinds.add("decimal");
+				return;
+			case "boolean":
+				kinds.add("boolean");
+				return;
+			case "null":
+			case "undefined":
+			case "never": return;
+			default:
+				kinds.add("any");
+				return;
+		}
+		case "union":
+			for (const item of def.items ?? []) collectKinds(item, kinds, out, depth + 1);
+			return;
+		case "array":
+			collectKinds(def.of, kinds, out, depth + 1);
+			return;
+		default: kinds.add("any");
+	}
+}
+const typeCache = /* @__PURE__ */ new WeakMap();
+/**
+* The value kinds a filter on `fd` accepts (cached per descriptor). A leaf
+* inside a JSON value (a `@db.json` object or an array, addressable on
+* nested-object adapters) is opaque: its contents are not schema-enforced.
+*/
+function valueTypeOf(meta, fd) {
+	let vt = typeCache.get(fd);
+	if (vt) return vt;
+	if (jsonValueAncestor(fd.path, meta.jsonValueParents) !== void 0 || fd.encrypted || fd.isGeoPoint || fd.designType === "json" || fd.designType === "object" || !fd.type) vt = OPAQUE;
+	else {
+		const kinds = /* @__PURE__ */ new Set();
+		const out = { timestamp: false };
+		collectKinds(fd.type, kinds, out);
+		const metadata = fd.type.metadata;
+		if ((fd.defaultValue?.kind === "fn" && fd.defaultValue.fn !== "uuid" || metadata?.has?.("db.agg.count") === true || metadata?.has?.("db.agg.countDistinct") === true) && kinds.delete("number")) kinds.add("integer");
+		vt = kinds.size === 0 ? OPAQUE : {
+			kinds,
+			timestamp: out.timestamp
+		};
+	}
+	typeCache.set(fd, vt);
+	return vt;
+}
+/** A decimal literal (`5`, `-1.5`, `.5`, `1e3`), surrounding blanks allowed — no hex, no `Infinity`. */
+const NUMERIC_RE = /^\s*[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?\s*$/i;
+/** An integer literal (`5`, `-12`), surrounding blanks allowed. */
+const INTEGER_RE = /^\s*[+-]?\d+\s*$/;
+function acceptsScalar(kind, value) {
+	switch (kind) {
+		case "any": return true;
+		case "string": return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint";
+		case "number":
+		case "decimal": return typeof value === "number" || typeof value === "bigint" || typeof value === "string" && NUMERIC_RE.test(value);
+		case "integer": return typeof value === "number" && Number.isInteger(value) || typeof value === "bigint" || typeof value === "string" && INTEGER_RE.test(value);
+		default: return typeof value === "boolean" || value === 0 || value === 1;
+	}
+}
+/** The first element of `value` (itself when not an array) `vt` rejects, or `undefined`. */
+function rejectedValue(vt, value) {
+	if (vt.kinds.has("any") || value === null || value === void 0) return void 0;
+	if (Array.isArray(value)) {
+		for (const item of value) {
+			const bad = rejectedValue(vt, item);
+			if (bad) return bad;
+		}
+		return;
+	}
+	if (typeof value === "object" && !require_object.isPlainObject(value)) return void 0;
+	for (const kind of vt.kinds) if (acceptsScalar(kind, value)) return void 0;
+	return { value };
+}
+const KIND_LABEL = {
+	string: "a string",
+	number: "a number",
+	integer: "an integer",
+	decimal: "a decimal (number or numeric string)",
+	boolean: "a boolean"
+};
+function expectedOf(vt) {
+	const labels = [];
+	for (const kind of vt.kinds) {
+		if (kind === "any") continue;
+		labels.push(kind === "integer" && vt.timestamp ? "an integer (epoch milliseconds)" : KIND_LABEL[kind]);
+	}
+	return labels.join(" or ");
+}
+function describeValue(value) {
+	if (typeof value === "string") return JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}…` : value);
+	if (require_object.isPlainObject(value)) return "an object";
+	return String(value);
+}
+function valueError(path, op, message) {
+	return new require_db_error.DbError("INVALID_QUERY", [{
+		path,
+		message: `Invalid filter value for "${path}"${op ? ` (${op})` : ""}: ${message}`
+	}]);
+}
+function holdsStrings(vt) {
+	return vt.kinds.has("string") || vt.kinds.has("any");
+}
+function checkRegex(path, vt, op, pattern) {
+	if (!holdsStrings(vt)) throw valueError(path, op, `a pattern match needs a string field, "${path}" holds ${expectedOf(vt)}`);
+	if (typeof pattern !== "string" && !(pattern instanceof RegExp)) throw valueError(path, op, `expected a regular expression, got ${describeValue(pattern)}`);
+}
+function checkValue(path, vt, op, value) {
+	if (value instanceof RegExp) {
+		checkRegex(path, vt, op ?? "RegExp", value);
+		return;
+	}
+	const bad = rejectedValue(vt, value);
+	if (bad) throw valueError(path, op, `expected ${expectedOf(vt)}, got ${describeValue(bad.value)}`);
+}
+/** Operators whose operand is compared with the field's values. */
+const COMPARE_OPS = new Set([
+	"$eq",
+	"$ne",
+	"$gt",
+	"$gte",
+	"$lt",
+	"$lte",
+	"$in",
+	"$nin"
+]);
+/** Checks one filter entry's value (a bare value or an operator map) against `vt`. */
+function checkEntry(path, vt, value) {
+	if (vt.kinds.has("any")) return;
+	if (!require_object.isPlainObject(value)) {
+		checkValue(path, vt, void 0, value);
+		return;
+	}
+	for (const [op, operand] of Object.entries(value)) if (op === "$regex") checkRegex(path, vt, op, operand);
+	else if (COMPARE_OPS.has(op)) checkValue(path, vt, op, operand);
+}
+/**
+* Walks `filter` (through `$and` / `$or` / `$not`; relational predicates are
+* the related table's) and checks every entry whose key `typeOf` knows.
+*/
+function walkFilterValues(filter, typeOf) {
+	if (!require_object.isPlainObject(filter)) return;
+	for (const [key, value] of Object.entries(filter)) {
+		if (key === "$and" || key === "$or") {
+			if (Array.isArray(value)) for (const child of value) walkFilterValues(child, typeOf);
+			continue;
+		}
+		if (key === "$not") {
+			walkFilterValues(value, typeOf);
+			continue;
+		}
+		if (key.startsWith("$") || require_nested_writer.hasRelationOp(value)) continue;
+		const vt = typeOf(key);
+		if (vt) checkEntry(key, vt, value);
+	}
+}
+/**
+* Rejects (`INVALID_QUERY`, `path` = the field) a filter value that cannot
+* denote its field's declared type — see the module notes for the accepted
+* forms. Unknown paths are skipped (the path guard owns them).
+*/
+function guardFilterValues(meta, filter) {
+	if (!filter) return;
+	walkFilterValues(filter, (key) => {
+		const fd = meta.descriptorByPath.get(key);
+		return fd ? valueTypeOf(meta, fd) : void 0;
+	});
+}
+/**
+* `$having` values: an aggregate alias is a number (`count`,
+* `countDistinct`, `sum`, `avg`) or its source field's type (`min` / `max`),
+* a calendar-bucket alias a string label, any other key a `$groupBy`
+* field's own type.
+*/
+function guardHavingValues(meta, controls) {
+	if (!controls?.$having) return;
+	const aliases = /* @__PURE__ */ new Map();
+	if (Array.isArray(controls.$select)) {
+		for (const item of controls.$select) if ((0, _uniqu_core.isAggregateExpr)(item)) {
+			const fd = item.$fn === "min" || item.$fn === "max" ? meta.descriptorByPath.get(item.$field) : void 0;
+			const counts = item.$fn === "count" || item.$fn === "countDistinct";
+			aliases.set((0, _uniqu_core.resolveAlias)(item), fd ? valueTypeOf(meta, fd) : counts ? INTEGER : NUMBER);
+		} else if ((0, _uniqu_core.isBucketExpr)(item)) aliases.set((0, _uniqu_core.resolveAlias)(item), STRING);
+	}
+	walkFilterValues(controls.$having, (key) => {
+		const alias = aliases.get(key);
+		if (alias) return alias;
+		const fd = meta.descriptorByPath.get(key);
+		return fd ? valueTypeOf(meta, fd) : void 0;
+	});
+}
+//#endregion
 //#region src/query/query-guards.ts
 /**
 * Engine-agnostic query-time guards, applied in the core layer BEFORE filter
@@ -1882,6 +2193,9 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 *   {@link canFilterLeaf}) needs → `INVALID_QUERY` (see {@link guardPaths}).
 *   Runs after the checks above so `ENC_*` codes keep firing first for
 *   encrypted subtrees.
+* - every filter / `$having` comparison value must be able to denote its
+*   field's declared type (`?n='x'` on a number) → `INVALID_QUERY`, after
+*   the path guard (see `guardFilterValues`, since 0.1.147).
 */
 /** Validates a `[lng, lat]` tuple (GeoJSON coordinate order). */
 function assertGeoPoint(point, path) {
@@ -1938,6 +2252,10 @@ function guardFilter(meta, adapter, filter, encCode = "ENC_FIELD_FILTER") {
 			continue;
 		}
 		if (key.startsWith("$")) continue;
+		if (require_nested_writer.hasRelationOp(value)) {
+			guardRelationOperands(key, value);
+			continue;
+		}
 		if (hasEncrypted && isEncryptedRef(meta, key)) throw encryptedRefError(encCode, key, "filter on");
 		if (!(0, _uniqu_core.isPrimitive)(value)) {
 			for (const [op, opValue] of Object.entries(value)) if (op === "$geoWithin") guardGeoWithin(meta, adapter, key, opValue);
@@ -1948,6 +2266,23 @@ function guardFilter(meta, adapter, filter, encCode = "ENC_FIELD_FILTER") {
 		}
 	}
 }
+/**
+* Shape rules of a relational predicate's operator map: only `$some` /
+* `$none` (never mixed with comparison operators), each operand a filter
+* object.
+*/
+function guardRelationOperands(key, ops) {
+	for (const [op, operand] of Object.entries(ops)) {
+		if (!(0, _uniqu_core.isRelationOp)(op)) throw new require_db_error.DbError("INVALID_QUERY", [{
+			path: key,
+			message: `Cannot mix "$some" / "$none" with "${op}" on "${key}"`
+		}]);
+		if (!require_object.isPlainObject(operand)) throw new require_db_error.DbError("INVALID_QUERY", [{
+			path: key,
+			message: `"${op}" on "${key}" expects a filter object`
+		}]);
+	}
+}
 /** Rejects `$sort` keys referencing encrypted fields. */
 function guardSort(meta, sort) {
 	if (!sort || typeof sort !== "object" || meta.encryptedFields.size === 0) return;
@@ -2021,8 +2356,18 @@ function filterPredicateOf(value) {
 	const ops = value;
 	if ("$geoWithin" in ops) return "geo";
 	const keys = Object.keys(ops);
+	if (keys.length > 0 && keys.every(_uniqu_core.isRelationOp)) return "relation";
 	return keys.length === 1 && keys[0] === "$exists" ? "exists" : "compare";
 }
+/** The `{ op, filter }` list of a `relation` entry's operator map. */
+function relationOpsOf(value) {
+	const out = [];
+	for (const [op, filter] of Object.entries(value)) if ((0, _uniqu_core.isRelationOp)(op)) out.push({
+		op,
+		filter
+	});
+	return out;
+}
 /**
 * Whether a stored leaf physically supports a filter predicate of this class
 * — the one rule the core path guard and moost-db's HTTP capability index
@@ -2039,6 +2384,7 @@ function filterPredicateOf(value) {
 function canFilterLeaf(fd, predicate, adapter) {
 	if (fd.encrypted) return false;
 	switch (predicate) {
+		case "relation": return false;
 		case "exists": return true;
 		case "geo": return fd.isGeoPoint === true && adapter.isGeoSearchable();
 		default: return adapter.canFilterField(fd);
@@ -2150,10 +2496,17 @@ function collectQueryPaths(query, aggregate) {
 		bucket: [],
 		aggregateMode: false
 	};
-	collectFilterKeys(query.filter, (path, value) => refs.filter.push({
-		path,
-		predicate: filterPredicateOf(value)
-	}), void 0, refs);
+	collectFilterKeys(query.filter, (path, value) => {
+		const predicate = filterPredicateOf(value);
+		refs.filter.push(predicate === "relation" ? {
+			path,
+			predicate,
+			relation: relationOpsOf(value)
+		} : {
+			path,
+			predicate
+		});
+	}, void 0, refs);
 	const controls = query.controls ?? {};
 	const rawGroupBy = controls.$groupBy;
 	const groupBy = Array.isArray(rawGroupBy) ? rawGroupBy.filter((f) => typeof f === "string") : typeof rawGroupBy === "string" ? [rawGroupBy] : [];
@@ -2245,8 +2598,11 @@ function pathSourceOf(meta) {
 function guardPath(meta, adapter, path, op, predicate = "compare") {
 	const verb = OP_VERB[op];
 	const { kind, parent } = classifyQueryPath(pathSourceOf(meta), path);
+	if (predicate === "relation" && kind !== "nav" && kind !== "unknown") throw pathError(path, `"$some" / "$none" are only valid on a navigation relation — "${path}" is not one`);
 	switch (kind) {
-		case "nav": throw pathError(path, `Cannot ${verb} "${path}" — navigation path`);
+		case "nav":
+			if (op === "filter" && predicate === "relation" && parent === void 0) return;
+			throw pathError(path, navPathMessage(path, verb, op, parent));
 		case "leaf": {
 			if (op === "select") return;
 			const fd = meta.descriptorByPath.get(path);
@@ -2271,6 +2627,35 @@ function guardPath(meta, adapter, path, op, predicate = "compare") {
 	}
 }
 /**
+* The rejection of a navigation path in a non-predicate position. A filter
+* names the predicate that expresses it: `ticket.status` →
+* `{ ticket: { $some: { status: … } } }`.
+*/
+function navPathMessage(path, verb, op, parent) {
+	const base = `Cannot ${verb} "${path}" — navigation path`;
+	if (op !== "filter") return base;
+	return `${base}; use { ${parent ?? path}: { $some: ${parent === void 0 ? "…" : `{ ${path.slice(parent.length + 1)}: … }`} } }`;
+}
+/**
+* A `relation` filter entry: the adapter must render predicates in this
+* mode, the table must be wired to its related tables (a `DbSpace`), and
+* each operand is guarded by the related table (depth / count caps, the
+* related table's own path rules) — see `TRelationFilterHost.guard`.
+*/
+function guardRelationRef(meta, adapter, ref, state) {
+	const path = state.path ? `${state.path}.${ref.path}` : ref.path;
+	const mode = state.write ? "write" : "read";
+	if (!adapter.supportsRelationFilters(mode)) throw new require_db_error.DbError("REL_FILTER_NOT_SUPPORTED", [{
+		path,
+		message: `Relational predicates ($some / $none) are not supported by this adapter${state.write ? " in mutation filters" : ""}`
+	}]);
+	if (!meta.relationFilters) throw new require_db_error.DbError("REL_FILTER_NOT_SUPPORTED", [{
+		path,
+		message: `Relational predicate on "${path}" needs the table to come from a DbSpace (no table resolver)`
+	}]);
+	for (const { op, filter } of ref.relation ?? []) meta.relationFilters.guard(ref.path, op, filter, state);
+}
+/**
 * Core backstop for every read / aggregate / mutation-filter entry point:
 * each referenced path (see {@link collectQueryPaths}) must exist on THIS
 * adapter with the physical capability the position needs (see
@@ -2285,20 +2670,29 @@ function guardPath(meta, adapter, path, op, predicate = "compare") {
 * `bucket`), `$groupBy` fields are checked, and computed aliases (`$as` or
 * the default) are exempt in `$sort` / `$having`.
 *
+* Then every filter comparison value must be able to denote its field's
+* declared type (`guardFilterValues`, since 0.1.147) — after the paths, so
+* an unknown or unfilterable field keeps its own rejection.
+*
 * Returns the collected refs so callers can run further structural rules
 * (see {@link checkHavingKeys}) without walking the query again.
 */
-function guardPaths(meta, adapter, query, aggregate = false) {
+function guardPaths(meta, adapter, query, aggregate = false, state) {
 	if (!query) return;
 	const refs = collectQueryPaths(query, aggregate);
 	if (refs.unsupportedOperator !== void 0) throw pathError(refs.unsupportedOperator, unsupportedOperatorMessage(refs.unsupportedOperator));
-	for (const ref of refs.filter) guardPath(meta, adapter, ref.path, "filter", ref.predicate);
+	let relState = state;
+	for (const ref of refs.filter) {
+		guardPath(meta, adapter, ref.path, "filter", ref.predicate);
+		if (ref.predicate === "relation") guardRelationRef(meta, adapter, ref, relState ??= require_nested_writer.relGuardState());
+	}
 	for (const path of refs.sort) guardPath(meta, adapter, path, "sort");
 	for (const path of refs.select) guardPath(meta, adapter, path, "select");
 	for (const path of refs.aggregate) guardPath(meta, adapter, path, "aggregate");
 	for (const path of refs.bucket) guardPath(meta, adapter, path, "bucket");
 	for (const path of refs.groupBy) guardPath(meta, adapter, path, "groupBy");
 	for (const path of refs.having) guardPath(meta, adapter, path, "having");
+	guardFilterValues(meta, query.filter);
 	return refs;
 }
 /**
@@ -2306,12 +2700,12 @@ function guardPaths(meta, adapter, query, aggregate = false) {
 * normalizer (a calendar bucket is invalid outside a grouped query), then
 * the path guard.
 */
-function guardQuery(meta, adapter, query) {
+function guardQuery(meta, adapter, query, state) {
 	if (!query) return;
 	guardFilter(meta, adapter, query.filter);
 	guardSort(meta, query.controls?.$sort);
 	normalizeComputedSelect(query.controls, meta, false);
-	guardPaths(meta, adapter, query);
+	guardPaths(meta, adapter, query, false, state);
 }
 /**
 * `$having` is a post-aggregation filter, so a key is either a computed
@@ -2337,7 +2731,7 @@ function checkHavingKeys(refs) {
 * (`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`).
+* reads `Unknown field`), then the `$having` values (`guardHavingValues`).
 *
 * `buckets` are the query's resolved calendar buckets when the caller already
 * ran `normalizeComputedSelect` (resolved here otherwise).
@@ -2360,6 +2754,7 @@ function guardAggregate(meta, adapter, query, resolved) {
 	guardBucketUnits(adapter, buckets);
 	const having = refs ? checkHavingKeys(refs) : void 0;
 	if (having) throw new require_db_error.DbError("INVALID_QUERY", [having]);
+	guardHavingValues(meta, controls);
 }
 /**
 * Rejects an aggregate whose (known — the normalizer checked the name)
@@ -2544,7 +2939,13 @@ var AtscriptDbReadable = class {
 	}
 	/** Ensures metadata is built. Called before any metadata access. */
 	_ensureBuilt() {
-		if (!this._meta.isBuilt) this._meta.build(this.type, this.adapter, this.logger);
+		if (!this._meta.isBuilt) {
+			this._meta.build(this.type, this.adapter, this.logger);
+			if (this._meta.navFields.size > 0 && this._tableResolver) {
+				const resolver = this._tableResolver;
+				this._meta.relationFilters = require_nested_writer.createRelationFilterHost(this, (type) => resolver(type));
+			}
+		}
 		if (this._meta.encryptedFields.size > 0 && !this._encryption) throw new require_db_error.DbError("ENC_CONFIG_MISSING", [{
 			path: "",
 			message: `Table "${this.tableName}" declares @db.encrypted fields but the DbSpace has no encryption configuration — pass { encryption: { defaultKeyId, keys } } to the DbSpace options`
@@ -2571,6 +2972,56 @@ var AtscriptDbReadable = class {
 	_guardQuery(query) {
 		guardQuery(this._meta, this.adapter, query);
 	}
+	/**
+	* Guards a relational predicate operand against THIS table — the filter
+	* guard and the path guard with the predicate's shared `state` (depth,
+	* count, read/write mode). Called by the source table's relation host.
+	*
+	* @internal Core wiring for relational predicates; not consumer API.
+	*/
+	_guardRelationOperand(filter, state) {
+		this._ensureBuilt();
+		guardFilter(this._meta, this.adapter, filter);
+		guardPaths(this._meta, this.adapter, { filter }, false, state);
+	}
+	/**
+	* Translates a relational predicate operand for THIS table's adapter (its
+	* own field mapper; nested predicates resolved at `depth + 1`).
+	*
+	* @internal Core wiring for relational predicates; not consumer API.
+	*/
+	_resolveRelationOperand(filter, depth) {
+		this._ensureBuilt();
+		return this._fieldMapper.translateFilter(filter, this._meta, depth);
+	}
+	/**
+	* Translates a logical query (filter + controls) for THIS table's adapter
+	* after the read guards — exactly what `findMany` hands the adapter.
+	* For adapters that load `$with` relations natively and must address the
+	* related table's physical names.
+	*
+	* @internal Adapter-facing surface; not part of the consumer API.
+	* @since 0.1.147
+	*/
+	_translateForAdapter(query) {
+		this._ensureBuilt();
+		this._guardQuery(query);
+		return this._fieldMapper.translateQuery(query, this._meta);
+	}
+	/**
+	* Physical rows of THIS table → logical rows (field mapping, value
+	* formatters, decryption) — what every read does before `$with` loading.
+	* `controls` are the logical read controls the rows were read with.
+	*
+	* @internal Adapter-facing surface; not part of the consumer API.
+	* @since 0.1.147
+	*/
+	async _rowsFromAdapter(rows, controls) {
+		this._ensureBuilt();
+		const out = this._fromRead(rows, controls);
+		await this._decryptRows(out);
+		return out;
+	}
 	_encryptedPathsCache;
 	/** Pre-split `encryptedFields` paths — computed once, reused on every read/write. */
 	get _encryptedPaths() {
@@ -2825,6 +3276,15 @@ var AtscriptDbReadable = class {
 		this._ensureBuilt();
 		return this._meta.pathToPhysical;
 	}
+	/**
+	* Physical column (or document path) of a logical field path —
+	* `@db.column` renames and flattening applied.
+	* @since 0.1.147
+	*/
+	physicalPath(logical) {
+		this._ensureBuilt();
+		return this._meta.physicalPath(logical);
+	}
 	/** Precomputed physical column name → logical dot-path map (inverse). */
 	get physicalToPath() {
 		this._ensureBuilt();
@@ -2879,10 +3339,14 @@ var AtscriptDbReadable = class {
 			widened
 		};
 	}
-	/** Reconstructs + decrypts a read's rows, loads its `$with` relations and strips widened keys. */
-	async _finishRead(results, read) {
-		const rows = this._fromRead(results, read.controls);
-		await this._decryptRows(rows);
+	/**
+	* Reconstructs + decrypts a read's rows, keeps the ones `pick` selects (all
+	* by default), loads their `$with` relations and strips widened keys.
+	*/
+	async _finishRead(results, read, pick) {
+		const all = this._fromRead(results, read.controls);
+		await this._decryptRows(all);
+		const rows = pick ? pick(all) : all;
 		if (read.withRelations?.length) {
 			await this.loadRelations(rows, read.withRelations);
 			for (const key of read.widened) for (const row of rows) require_object.deletePath(row, key);
@@ -2991,11 +3455,12 @@ var AtscriptDbReadable = class {
 	* table. Defense-in-depth for query-path validation: `flattenAnnotatedType`
 	* still truncates real self-referential cycles, so paths like
 	* `parent.parent.name` on a self-ref schema would miss `flatMap.has` but
-	* remain valid field references on the target.
+	* remain valid field references on the target — a path may cross the same
+	* relation any number of times (callers cap the depth).
 	*
-	* Cycle-safe via a visited set keyed on `<tableName>:<navField>`.
+	* Terminates on cyclic schemas: every hop consumes one path segment.
 	*/
-	isValidFieldPath(path, _visited) {
+	isValidFieldPath(path) {
 		if (this.flatMap.has(path)) return true;
 		const dotIdx = path.indexOf(".");
 		if (dotIdx === -1) return false;
@@ -3003,11 +3468,7 @@ var AtscriptDbReadable = class {
 		const tail = path.slice(dotIdx + 1);
 		const targetTable = this.relatedTable(head);
 		if (!targetTable || typeof targetTable.isValidFieldPath !== "function") return false;
-		const visited = _visited ?? /* @__PURE__ */ new Set();
-		const cycleKey = `${this.tableName}:${head}`;
-		if (visited.has(cycleKey)) return false;
-		visited.add(cycleKey);
-		return targetTable.isValidFieldPath(tail, visited);
+		return targetTable.isValidFieldPath(tail);
 	}
 	/**
 	* Creates a new validator with custom options.
@@ -3041,6 +3502,22 @@ var AtscriptDbReadable = class {
 		return await this._finishRead(await this.adapter.findMany(read.translated), read);
 	}
 	/**
+	* `findMany` for the generic `$with` loader. With `partitionBy` (logical
+	* fields), `$skip` / `$limit` apply per group of rows sharing those fields'
+	* values (`BaseDbAdapter.findManyPerPartition`); `pick` chooses which of the
+	* read rows to keep before their own `$with` relations load.
+	*
+	* @internal Relation-loader surface; not part of the consumer API.
+	* @since 0.1.147
+	*/
+	async _findManyForRelation(query, opts) {
+		this._ensureBuilt();
+		this._guardQuery(query);
+		const read = this._translateRead(query);
+		const results = opts.partitionBy ? await this.adapter.findManyPerPartition(read.translated, opts.partitionBy.map((field) => this._meta.physicalPath(field))) : await this.adapter.findMany(read.translated);
+		return this._finishRead(results, read, opts.pick);
+	}
+	/**
 	* Counts records matching the query.
 	*/
 	async count(query) {
@@ -3561,7 +4038,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-CBPY6kM7.cjs")).then((n) => n.relation_loader_exports);
+		const { loadRelationsImpl } = await Promise.resolve().then(() => require("./relation-loader-BFhVuJ-B.cjs")).then((n) => n.relation_loader_exports);
 		return loadRelationsImpl(rows, withRelations, this);
 	}
 	/**
@@ -3627,8 +4104,14 @@ function createFailureCollector(what) {
 //#region src/base-adapter.ts
 const EMPTY_DEFAULT_FNS = /* @__PURE__ */ new Set();
 const EMPTY_BUCKET_UNITS = /* @__PURE__ */ new Set();
-/** Every calendar-bucket unit — what an adapter that renders them all returns from `calendarBucketUnits()`. */
+/**
+* Every calendar-bucket unit — what an adapter that renders them all returns
+* from `calendarBucketUnits()`. Includes `'hour'` since 0.1.147.
+*/
 const ALL_BUCKET_UNITS = new Set(_uniqu_core.BUCKET_UNITS);
+const NO_VIEW_CAPABILITIES = /* @__PURE__ */ new Set();
+/** Every view capability — what the bundled adapters return from `viewCapabilities()`. @since 0.1.147 */
+const ALL_VIEW_CAPABILITIES = new Set(["compute", "firstJoin"]);
 const txStorage = new node_async_hooks.AsyncLocalStorage();
 /** The innermost open transaction of `owner` in the current async chain. */
 function findTxContext(owner) {
@@ -3688,6 +4171,26 @@ var BaseDbAdapter = class {
 	registerReadable(readable, logger) {
 		this._table = readable;
 		if (logger) this.logger = logger;
+		if (readable.isView) this._guardViewCapabilities(readable);
+	}
+	/**
+	* Makes `ensureTable()` of a managed view fail closed (since 0.1.147): it
+	* throws before the adapter renders a computed column / first-row join its
+	* {@link viewCapabilities} does not list — schema sync refuses such a view
+	* up front, a direct `ensureTable()` call must not render it as a plain
+	* (row-multiplying) join either. Wraps the subclass's own implementation, so
+	* third-party adapters get the guard without code changes.
+	*/
+	_guardViewCapabilities(readable) {
+		if (Object.prototype.hasOwnProperty.call(this, "ensureTable")) return;
+		const view = readable;
+		if (typeof view.viewCapabilityProblems !== "function") return;
+		const ensureTable = this.ensureTable.bind(this);
+		this.ensureTable = (opts) => {
+			const problems = view.viewCapabilityProblems();
+			if (problems.length > 0) return Promise.reject(new Error(problems.join("; ")));
+			return ensureTable(opts);
+		};
 	}
 	/**
 	* Called by {@link DbSpace} right after its factory builds this adapter —
@@ -3872,8 +4375,10 @@ var BaseDbAdapter = class {
 	* be adopted adapter by adapter. An adapter that returns a unit must group
 	* by the bucket alias in `$groupBy` — see `controls.$select.buckets`
 	* (`TResolvedBucket`: physical `field`, source `fd`) — and return the
-	* `YYYY-MM-DD` label of the bucket's first local day (null for a null or
-	* out-of-range source, uniqu's `bucketLabel` semantics). Since 0.1.132.
+	* `YYYY-MM-DD` label of the bucket's first local day, or for `'hour'` the
+	* local wall-clock hour `YYYY-MM-DDTHH:00` (null for a null or out-of-range
+	* source, uniqu's `bucketLabel` semantics). Since 0.1.132; `'hour'` since
+	* 0.1.147 — an adapter returning {@link ALL_BUCKET_UNITS} must render it.
 	*/
 	calendarBucketUnits() {
 		return EMPTY_BUCKET_UNITS;
@@ -3904,6 +4409,18 @@ var BaseDbAdapter = class {
 	*/
 	viewRenderRevision() {}
 	/**
+	* The managed-view features this adapter renders: `compute` — computed
+	* columns (`@db.compute`); `firstJoin` — first-row joins (the ordered 4th
+	* argument of `@db.view.joins`). Schema sync refuses a view using a feature
+	* not listed. The default is EMPTY (fail-closed): a third-party adapter
+	* opts in once it renders them.
+	*
+	* @since 0.1.147
+	*/
+	viewCapabilities() {
+		return NO_VIEW_CAPABILITIES;
+	}
+	/**
 	* 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`).
@@ -3961,6 +4478,39 @@ var BaseDbAdapter = class {
 		return false;
 	}
 	/**
+	* Whether this adapter renders relational filter predicates
+	* (`{ nav: { $some | $none: … } }`) in `mode` — `read` for find / count /
+	* search / aggregate filters, `write` for mutation filters
+	* (`updateMany`, `deleteMany`, …). Default `false`: the core rejects such
+	* filters with `REL_FILTER_NOT_SUPPORTED` before they reach the adapter.
+	*
+	* An adapter returning `true` receives each predicate already resolved by
+	* the core: the filter visitor's `relation(field, op, operand)` callback
+	* gets a `ResolvedRelationFilter` operand (`kind`, physical
+	* correlation `pairs`, `target` / `junction` tables with their adapters,
+	* and the inner `filter` already translated to the target's physical
+	* names, nested predicates resolved too). Keep `relation` on every
+	* `walkFilter` visitor that may meet such a filter.
+	*
+	* @since 0.1.147
+	*/
+	supportsRelationFilters(_mode) {
+		return false;
+	}
+	/**
+	* Whether `other` serves a table of the SAME store as this adapter, so one
+	* statement / pipeline can correlate both (a relational predicate renders
+	* the related table inside this table's query). Default: same adapter class
+	* and same {@link _transactionOwner} (the driver / pool / client the
+	* adapter was built with). Override when the owner is shared across
+	* separate databases (e.g. one Mongo client over several databases).
+	*
+	* @since 0.1.147
+	*/
+	sharesStoreWith(other) {
+		return other.constructor === this.constructor && other._transactionOwner() === this._transactionOwner();
+	}
+	/**
 	* Loads relations onto result rows using adapter-native operations.
 	* Only called when {@link supportsNativeRelations} returns `true`.
 	*
@@ -4197,6 +4747,31 @@ var BaseDbAdapter = class {
 		};
 	}
 	/**
+	* Reads like {@link findMany}, except that `$skip` / `$limit` apply to each
+	* partition — the rows sharing the values of the `partitionBy` columns
+	* (physical names) — instead of to the whole result. The generic `$with`
+	* loader reads the related rows of many parent rows at once this way, so a
+	* relation's `$skip` / `$limit` page each parent row's related rows.
+	* `$sort` orders the rows within a partition; how partitions interleave is
+	* unspecified.
+	*
+	* Default: one {@link findMany} without `$skip` / `$limit`, paged per
+	* partition in memory. The SQL adapters override it with a `ROW_NUMBER()`
+	* window, so only the kept rows are read.
+	*
+	* @since 0.1.147
+	*/
+	async findManyPerPartition(query, partitionBy) {
+		const { $skip, $limit, ...controls } = query.controls;
+		return require_nested_writer.slicePerGroup(await this.findMany({
+			...query,
+			controls
+		}), (row) => require_nested_writer.compositeKey(partitionBy, row, require_object.getPath), {
+			skip: $skip ?? void 0,
+			limit: $limit ?? void 0
+		});
+	}
+	/**
 	* Executes an aggregate query (GROUP BY + aggregate functions).
 	* Default throws — override in adapters that support aggregation.
 	*/
@@ -4267,6 +4842,8 @@ var BaseDbAdapter = class {
 //#endregion
 //#region src/strategies/application-integrity.ts
 const MAX_CASCADE_DEPTH = 100;
+/** Rows per pinned-key delete batch (keeps `IN (…)` / `$or` lists bounded). */
+const PIN_BATCH = 1e3;
 const cascadeStorage = new node_async_hooks.AsyncLocalStorage();
 /**
 * Integrity strategy for adapters without native FK support (e.g. MongoDB).
@@ -4335,6 +4912,12 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 	* - `restrict`: throws if any children exist
 	* - `cascade`: recursively deletes child records
 	* - `setNull`: sets FK fields to null
+	*
+	* When `filter` holds a relational predicate, returns the matched rows
+	* PINNED by primary key (see {@link TCascadePin}): the caller deletes those
+	* rows, never re-evaluating `filter` on data the cascade just changed (a
+	* `$some` over a cascaded child relation would otherwise stop matching and
+	* leave the parent behind). Any other filter → `undefined`.
 	*/
 	async cascadeBeforeDelete(filter, tableName, meta, cascadeResolver, translateFilter, adapter) {
 		const parentCtx = cascadeStorage.getStore();
@@ -4346,6 +4929,11 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 		}]);
 		const targets = cascadeResolver(tableName);
 		if (targets.length === 0) return;
+		const pkPhysical = require_nested_writer.containsRelationFilter(filter) ? meta.primaryKeys.map((pk) => meta.physicalPath(pk)) : void 0;
+		if (pkPhysical?.length === 0) throw new require_db_error.DbError("REL_FILTER_NOT_SUPPORTED", [{
+			path: "",
+			message: "Cannot delete by a relational predicate with application-level cascades: the table has no primary key"
+		}]);
 		const neededLogical = /* @__PURE__ */ new Set();
 		for (const t of targets) for (const tf of t.fk.targetFields) neededLogical.add(tf);
 		for (const pk of meta.primaryKeys) neededLogical.add(pk);
@@ -4360,7 +4948,8 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 			filter: translateFilter(filter),
 			controls: { $select: new UniquSelect(physicalFields) }
 		});
-		if (rawRecords.length === 0) return;
+		const pin = pkPhysical ? pinByPrimaryKey(rawRecords, pkPhysical) : void 0;
+		if (rawRecords.length === 0) return pin;
 		const allRecords = rawRecords.map((r) => {
 			const mapped = {};
 			for (const [key, val] of Object.entries(r)) mapped[physicalToLogical.get(key) ?? key] = val;
@@ -4376,7 +4965,7 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 			addedKeys.push(key);
 			records.push(record);
 		}
-		if (records.length === 0) return;
+		if (records.length === 0) return pin;
 		try {
 			await cascadeStorage.run({
 				visited,
@@ -4416,6 +5005,7 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 		} finally {
 			for (const key of addedKeys) visited.delete(key);
 		}
+		return pin;
 	}
 	needsCascade(cascadeResolver) {
 		return !!cascadeResolver;
@@ -4456,6 +5046,23 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 		return orFilters.length === 1 ? orFilters[0] : { $or: orFilters };
 	}
 };
+/**
+* Adapter-ready filters addressing exactly `rows` by their (physical) primary
+* key, in batches of {@link PIN_BATCH}: `{ pk: { $in } }` for a single key,
+* `{ $or: [{ a, b }, …] }` for a composite one. Values are the raw stored
+* values the adapter returned, so no value formatting is re-applied.
+*/
+function pinByPrimaryKey(rows, pk) {
+	const out = [];
+	for (let i = 0; i < rows.length; i += PIN_BATCH) {
+		const batch = rows.slice(i, i + PIN_BATCH);
+		if (pk.length === 1) {
+			const field = pk[0];
+			out.push({ [field]: { $in: batch.map((r) => r[field]) } });
+		} else out.push({ $or: batch.map((r) => Object.fromEntries(pk.map((f) => [f, r[f]]))) });
+	}
+	return out;
+}
 //#endregion
 //#region src/patch/array-ops-resolver.ts
 /**
@@ -5331,7 +5938,10 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			const filter = this._andScope(pinned, opts?.scope);
 			const translated = this._fieldMapper.translateFilter(filter, this._meta);
 			if (guard) await guard(new RemoveGuardContext(id, filter, this));
-			if (needsCascade) await this._integrity.cascadeBeforeDelete(filter, this.tableName, this._meta, this._cascadeResolver, (f) => this._fieldMapper.translateFilter(f, this._meta), this.adapter);
+			if (needsCascade) {
+				const pin = await this._integrity.cascadeBeforeDelete(filter, this.tableName, this._meta, this._cascadeResolver, (f) => this._fieldMapper.translateFilter(f, this._meta), this.adapter);
+				if (pin) return pin.length > 0 ? this.adapter.deleteOne(pin[0]) : { deletedCount: 0 };
+			}
 			return this.adapter.deleteOne(translated);
 		};
 		return require_nested_writer.remapDeleteFkViolation(this.tableName, () => guard || needsCascade || candidates.length > 1 ? this.adapter.withTransaction(run) : run());
@@ -5375,7 +5985,12 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		this._ensureBuilt();
 		this._guardMutationFilter(filter);
 		if (this._integrity.needsCascade(this._cascadeResolver)) return require_nested_writer.remapDeleteFkViolation(this.tableName, () => this.adapter.withTransaction(async () => {
-			await this._integrity.cascadeBeforeDelete(filter, this.tableName, this._meta, this._cascadeResolver, (f) => this._fieldMapper.translateFilter(f, this._meta), this.adapter);
+			const pin = await this._integrity.cascadeBeforeDelete(filter, this.tableName, this._meta, this._cascadeResolver, (f) => this._fieldMapper.translateFilter(f, this._meta), this.adapter);
+			if (pin) {
+				let deletedCount = 0;
+				for (const batch of pin) deletedCount += (await this.adapter.deleteMany(batch)).deletedCount;
+				return { deletedCount };
+			}
 			return this.adapter.deleteMany(this._fieldMapper.translateFilter(filter, this._meta));
 		}));
 		return require_nested_writer.remapDeleteFkViolation(this.tableName, () => this.adapter.deleteMany(this._fieldMapper.translateFilter(filter, this._meta)));
@@ -5397,7 +6012,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	/** Engine-agnostic guard for user-supplied mutation filters (updateMany/deleteMany/…). */
 	_guardMutationFilter(filter) {
 		guardFilter(this._meta, this.adapter, filter);
-		guardPaths(this._meta, this.adapter, { filter });
+		guardPaths(this._meta, this.adapter, { filter }, false, require_nested_writer.relGuardState(true));
 	}
 	/**
 	* Encrypts `@db.encrypted` field values in place on (already validated)
@@ -5794,8 +6409,16 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 };
 //#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}`);
+/**
+* The single `@meta.id` field of a first-row join target (its source type,
+* past `@db.alias`) — the anchor of the join's correlated subquery.
+* @throws when the target declares no or several primary-key fields.
+*/
+function firstJoinKey(view, type, scope) {
+	const ids = type.type.kind === "object" ? [...type.type.props.entries()].filter(([, p]) => p.metadata.has("meta.id")) : [];
+	if (ids.length !== 1) throw new Error(`View "${view}": the first-row join on "${scope}" needs a target with exactly one @meta.id field (found ${ids.length})`);
+	return ids[0][0];
+}
 /**
 * Reads a view field's `@db.agg.*` annotation. The compiled value is
 * `{ field?, condition? }`; models compiled by older versions carry `true`
@@ -5803,7 +6426,7 @@ const AGG_KEYS = require_aggregate_fns.SUPPORTED_AGGREGATE_FNS.map((fn) => `db.a
 * A missing field or `true` is `'*'` (COUNT(*)).
 */
 function readViewAgg(metadata) {
-	for (const key of AGG_KEYS) {
+	for (const key of require_aggregate_fns.AGG_ANNOTATIONS) {
 		const val = metadata?.get(key);
 		if (val === void 0) continue;
 		const aggFn = key.slice(7);
@@ -5881,7 +6504,9 @@ function inheritViewFieldSeals(viewType) {
 	try {
 		const forRef = viewType.metadata.get("db.view.for");
 		const entryType = forRef && refType(forRef);
-		for (const [fieldName, fieldType] of viewType.type.props.entries()) {
+		const props = viewType.type.props;
+		for (const [fieldName, fieldType] of props.entries()) {
+			if (require_nested_writer.computeOf(fieldType) !== void 0) continue;
 			const { agg, sourceType, sourcePath } = viewFieldSource(fieldName, fieldType, entryType);
 			if (agg?.aggField === "*" || !sourceType) continue;
 			const source = viewSourceOf(sourceType).type;
@@ -5892,6 +6517,14 @@ function inheritViewFieldSeals(viewType) {
 			if (agg) throw new Error(`View "${require_nested_writer.tableNameOf(viewType)}" field "${fieldName}": @db.agg.${agg.aggFn} over the @db.encrypted field "${sourcePath}" — ciphertext cannot be aggregated`);
 			fieldType.metadata.set("db.encrypted", true);
 		}
+		for (const [fieldName, fieldType] of props.entries()) {
+			const computed = require_nested_writer.computedOperands(viewType, fieldName);
+			if (!computed) continue;
+			const { operands, via } = computed;
+			const encrypted = operands.find((p) => props.get(p)?.metadata.has("db.encrypted"));
+			if (encrypted) throw new Error(`View "${require_nested_writer.tableNameOf(viewType)}": @db.compute over the @db.encrypted field "${encrypted}" — ciphertext cannot be computed`);
+			if ([...operands, ...via].some((p) => props.get(p)?.metadata.has("db.writeOnly"))) fieldType.metadata.set("db.writeOnly", true);
+		}
 	} catch (error) {
 		sealedViews.delete(viewType);
 		throw error;
@@ -5954,13 +6587,39 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		if (rawJoins) for (const join of rawJoins) {
 			const targetType = refType(join.target);
 			const target = viewSourceOf(targetType());
-			joins.push({
+			const viewJoin = {
 				targetType,
 				targetTable: target.table,
 				scope: target.name,
 				condition: join.condition,
 				kind: join.kind === "left" ? "left" : "inner"
-			});
+			};
+			if (join.order?.length) {
+				const key = firstJoinKey(this.tableName, target.type, target.name);
+				const order = join.order.map((item) => {
+					const seals = sourceFieldSeals(target.type, item.ref.field);
+					if (seals.encrypted || seals.writeOnly) throw new Error(`View "${this.tableName}": the first-row join on "${target.name}" cannot order by the ${seals.encrypted ? "@db.encrypted" : "@db.writeOnly"} field "${item.ref.field}"`);
+					return {
+						ref: {
+							type: targetType,
+							field: item.ref.field
+						},
+						desc: item.desc === true
+					};
+				});
+				if (!order.some((item) => item.ref.field === key)) order.push({
+					ref: {
+						type: targetType,
+						field: key
+					},
+					desc: false
+				});
+				viewJoin.first = {
+					order,
+					key
+				};
+			}
+			joins.push(viewJoin);
 		}
 		const filter = metadata.get("db.view.filter");
 		const having = metadata.get("db.view.having");
@@ -6037,6 +6696,26 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		this._columnMappings ??= this._buildColumnMappings();
 		return this._columnMappings;
 	}
+	/**
+	* Why the bound adapter cannot render this managed view: one message per
+	* computed column / first-row join whose feature its `viewCapabilities()`
+	* does not list. Empty for an external view or when every feature is
+	* rendered. Schema sync refuses such a view; the adapter's `ensureTable()`
+	* throws for it (fail-closed for adapters that predate the features).
+	* @since 0.1.147
+	*/
+	viewCapabilityProblems() {
+		if (this.isExternal) return [];
+		const caps = this.dbAdapter.viewCapabilities();
+		const problems = [];
+		if (!caps.has("compute")) {
+			for (const col of this.getViewColumnMappings()) if (col.expr !== void 0) problems.push(`View "${this.tableName}" field "${col.viewPath}": computed columns (@db.compute) are not supported by this adapter (viewCapabilities())`);
+		}
+		if (!caps.has("firstJoin")) {
+			for (const join of this.viewPlan.joins) if (join.first) problems.push(`View "${this.tableName}" join "${join.scope}": first-row joins are not supported by this adapter (viewCapabilities())`);
+		}
+		return problems;
+	}
 	_buildColumnMappings() {
 		const plan = this.viewPlan;
 		const mappings = [];
@@ -6051,6 +6730,17 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		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 expr = require_nested_writer.computeOf(fieldType);
+			if (expr !== void 0) {
+				mappings.push({
+					viewColumn: viewName(fieldName) ?? fieldName,
+					viewPath: fieldName,
+					sourceTable: plan.entryTable,
+					sourceColumn: "",
+					expr
+				});
+				continue;
+			}
 			const { agg, chained, sourceType, sourcePath } = viewFieldSource(fieldName, fieldType, plan.entryType);
 			const aggField = agg?.aggField;
 			if (aggField === "*" && agg?.aggFn !== "count") fail(fieldName, `aggregate "${agg?.aggFn}" needs a field — only count accepts *`);
@@ -6087,8 +6777,37 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 				...agg
 			} : mapping);
 		}
+		this._checkComputed(mappings, fail);
 		return mappings;
 	}
+	/**
+	* The runtime twin of the compile-time `@db.compute` rules the renderers
+	* rely on: every leaf names a (non-ignored) view column, computed columns
+	* form no cycle; sets each computed mapping's `nullable`.
+	*/
+	_checkComputed(mappings, fail) {
+		const computed = mappings.filter((m) => m.expr !== void 0);
+		if (computed.length === 0) return;
+		const byPath = new Map(mappings.map((m) => [m.viewPath, m]));
+		const props = this._type.type.kind === "object" ? this._type.type.props : void 0;
+		const state = /* @__PURE__ */ new Map();
+		const visit = (m, chain) => {
+			if (state.get(m.viewPath) === "done") return;
+			if (state.get(m.viewPath) === "visiting") fail(m.viewPath, `@db.compute depends on itself: ${[...chain, m.viewPath].join(" → ")}`);
+			state.set(m.viewPath, "visiting");
+			require_nested_writer.walkViewExpr(m.expr, (path) => {
+				const leaf = byPath.get(path);
+				if (!leaf) fail(m.viewPath, `@db.compute references "${path}", which is not a column of the view`);
+				if (leaf.expr !== void 0) visit(leaf, [...chain, m.viewPath]);
+			});
+			state.set(m.viewPath, "done");
+			if (require_nested_writer.viewExprNullable(m.expr, (path) => {
+				const leaf = byPath.get(path);
+				return leaf.expr === void 0 ? props?.get(path)?.optional === true : leaf.nullable === true;
+			})) m.nullable = true;
+		};
+		for (const m of computed) visit(m, []);
+	}
 	/** One view column over one physical source (a column or a JSON leaf). */
 	_leafMapping(viewPath, viewColumn, sourceTable, source, joinNullable) {
 		const mapping = {
@@ -6121,6 +6840,62 @@ function isAtscriptDbView(readable) {
 	return readable.isView;
 }
 //#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(",");
+}
+/**
+* Physical local / target column names of a desired FK (`@db.column` renames
+* applied) — what DDL, constraint sync, the FK diff and the snapshot compare.
+*/
+function fkColumns(fk) {
+	return {
+		fields: fk.physicalFields ?? fk.fields,
+		targetFields: fk.physicalTargetFields ?? fk.targetFields
+	};
+}
+/**
+* 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(fkColumns(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(fkColumns(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/schema-hash.ts
 /**
 * The physical sources a stored view snapshot reads: its entry table and the
@@ -6187,9 +6962,9 @@ function computeTableSnapshot(readable, typeMapper, tableOptions) {
 		}))
 	})).toSorted((a, b) => a.key.localeCompare(b.key));
 	const foreignKeys = [...readable.foreignKeys.values()].map((fk) => ({
-		fields: [...fk.fields].toSorted(),
+		fields: [...fkColumns(fk).fields].toSorted(),
 		targetTable: fk.targetTable,
-		targetFields: [...fk.targetFields].toSorted(),
+		targetFields: [...fkColumns(fk).targetFields].toSorted(),
 		onDelete: fk.onDelete,
 		onUpdate: fk.onUpdate
 	})).toSorted((a, b) => a.fields.join(",").localeCompare(b.fields.join(",")));
@@ -6217,7 +6992,9 @@ function computeViewSnapshot(view) {
 	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 mappings = view.getViewColumnMappings();
+	const columnOf = new Map(mappings.map((m) => [m.viewPath, m.viewColumn]));
+	const columns = mappings.map((m) => {
 		const col = {
 			column: m.viewColumn,
 			sourceTable: m.sourceTable,
@@ -6230,6 +7007,7 @@ function computeViewSnapshot(view) {
 		if (m.aggFn) col.aggFn = m.aggFn;
 		if (m.aggField) col.aggField = m.aggField;
 		if (m.aggFilter) col.aggFilter = canonical(m.aggFilter);
+		if (m.expr !== void 0) col.expr = JSON.stringify(canonicalizeViewExpr(m.expr, (path) => columnOf.get(path) ?? path));
 		return col;
 	}).toSorted((a, b) => a.column < b.column ? -1 : a.column > b.column ? 1 : 0);
 	const result = {
@@ -6243,6 +7021,7 @@ function computeViewSnapshot(view) {
 				condition: canonical(j.condition)
 			};
 			if (j.kind === "left") join.kind = "left";
+			if (j.first) join.order = JSON.stringify(j.first.order.map((item) => [qualify(item.ref), item.desc ? -1 : 1]));
 			return join;
 		}),
 		columns
@@ -6281,6 +7060,20 @@ function canonicalizeQueryNode(node, qualify) {
 	return out;
 }
 /**
+* Converts a `@db.compute` expression into a serializable structure whose
+* JSON is a stable function of its meaning: leaves become the view column
+* they read (`column(path)`), literals `{ n }`, operations `{ op, a }`.
+* @since 0.1.147
+*/
+function canonicalizeViewExpr(expr, column) {
+	if (typeof expr === "number") return { n: expr };
+	if ("field" in expr) return { c: column(expr.field) };
+	return {
+		op: expr.op,
+		a: expr.args.map((arg) => canonicalizeViewExpr(arg, column))
+	};
+}
+/**
 * Computes a deterministic hash string from multiple table snapshots.
 * Uses FNV-1a for speed — not cryptographic, just needs stability + collision resistance.
 */
@@ -6344,52 +7137,6 @@ function fnv1a(str) {
 	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
 /**
 * Why a derived column (desired, live, or both) must be dropped and re-added,
@@ -6530,6 +7277,12 @@ Object.defineProperty(exports, "ALL_BUCKET_UNITS", {
 		return ALL_BUCKET_UNITS;
 	}
 });
+Object.defineProperty(exports, "ALL_VIEW_CAPABILITIES", {
+	enumerable: true,
+	get: function() {
+		return ALL_VIEW_CAPABILITIES;
+	}
+});
 Object.defineProperty(exports, "ApplicationIntegrity", {
 	enumerable: true,
 	get: function() {
@@ -6722,6 +7475,12 @@ Object.defineProperty(exports, "decomposePatch", {
 		return decomposePatch;
 	}
 });
+Object.defineProperty(exports, "fkColumns", {
+	enumerable: true,
+	get: function() {
+		return fkColumns;
+	}
+});
 Object.defineProperty(exports, "fkKey", {
 	enumerable: true,
 	get: function() {