@atscript/moost-db 0.1.126 → 0.1.128

package/dist/index.mjs

@@ -3,26 +3,44 @@ import { ValidatorError, defineAnnotatedType, isAnnotatedType, serializeAnnotate
 import { Body, Delete, Get, HttpError, Patch, Post, Put, Query, Url } from "@moostjs/event-http";
 import { ApplyDecorators, Controller, Inherit, Inject, Intercept, Moost, Optional, Param, Provide, Resolve, TInterceptorPriority, defineBeforeInterceptor, defineInterceptor, getMoostMate, useControllerContext } from "moost";
 import { parseUrl } from "@uniqu/url";
-import { DbError } from "@atscript/db";
+import { DbError, checkHavingKeys, classifyQueryPath, collectQueryPaths, collectQueryPaths as collectQueryPaths$1, findAncestorInSet, isPlainObject, reconcileCas, unsupportedOperatorMessage } from "@atscript/db";
 import { buildMemoryPredicate, projectRow, sortRows } from "@atscript/db-memory";
 import { cached, current, defineWook, key } from "@wooksjs/event-core";
 import { useBody } from "@wooksjs/http-body";
+//#region src/http-errors.ts
+/**
+* The structured error envelope every `moost-db` rejection uses (since
+* 0.1.128 all of them do): `{ message, statusCode, errors: [{ path, message }] }`
+* — the same shape the validation interceptor renders for `ValidatorError` /
+* `DbError`, so clients parse one format.
+*/
+function errorEnvelope(statusCode, message, errors) {
+	return new HttpError(statusCode, {
+		message,
+		statusCode,
+		errors
+	});
+}
+/**
+* A 400 with a single `errors` entry: `path` names the offending logical
+* path / body position, `message` the reason, `top` the envelope's top-level
+* message (defaults to `message`).
+*/
+function badRequest(path, message, top = message) {
+	return errorEnvelope(400, top, [{
+		path,
+		message
+	}]);
+}
+//#endregion
 //#region src/validation-interceptor.ts
-const dbErrorCodeToStatus = { CONFLICT: 409 };
+const dbErrorCodeToStatus = {
+	CONFLICT: 409,
+	TX_WAIT_TIMEOUT: 503
+};
 function transformValidationError(error, reply) {
-	if (error instanceof ValidatorError) reply(new HttpError(400, {
-		message: error.message,
-		statusCode: 400,
-		errors: error.errors
-	}));
-	else if (error instanceof DbError) {
-		const statusCode = dbErrorCodeToStatus[error.code] ?? 400;
-		reply(new HttpError(statusCode, {
-			message: error.message,
-			statusCode,
-			errors: error.errors
-		}));
-	}
+	if (error instanceof ValidatorError) reply(errorEnvelope(400, error.message, error.errors));
+	else if (error instanceof DbError) reply(errorEnvelope(dbErrorCodeToStatus[error.code] ?? 400, error.message, error.errors));
 }
 const validationErrorTransform = () => defineInterceptor({ error: transformValidationError }, TInterceptorPriority.BEFORE_ALL);
 const UseValidationErrorTransform = () => Intercept(validationErrorTransform());
@@ -117,72 +135,6 @@ defineAnnotatedType("object", WithFilterDto).propPattern(/./, defineAnnotatedTyp
 defineAnnotatedType("object", SortControlDto).propPattern(/./, defineAnnotatedType("union").item(defineAnnotatedType().designType("number").value(1).$type).item(defineAnnotatedType().designType("number").value(-1).$type).$type);
 defineAnnotatedType("object", SelectControlDto).propPattern(/./, defineAnnotatedType("union").item(defineAnnotatedType().designType("number").value(1).$type).item(defineAnnotatedType().designType("number").value(0).$type).$type);
 //#endregion
-//#region src/gate-utils.ts
-/**
-* Walks a Uniquery filter expression and returns the first field name that
-* fails the `isAllowed` predicate, or `undefined` if every leaf field is
-* allowed. Logical combinators (`$and`, `$or`, `$nor`, `$not`) are traversed;
-* other `$`-prefixed keys are skipped.
-*
-* Shared by the DB readable's `@db.column.filterable` gate and the value-help
-* controller's `@ui.dict.filterable` gate — only the predicate differs.
-*/
-function findFilterOffender(filter, isAllowed) {
-	if (!filter || typeof filter !== "object") return;
-	for (const [key, value] of Object.entries(filter)) {
-		if (key === "$and" || key === "$or" || key === "$nor") {
-			if (Array.isArray(value)) for (const sub of value) {
-				const inner = findFilterOffender(sub, isAllowed);
-				if (inner) return inner;
-			}
-			continue;
-		}
-		if (key === "$not") {
-			const inner = findFilterOffender(value, isAllowed);
-			if (inner) return inner;
-			continue;
-		}
-		if (key.startsWith("$")) continue;
-		if (!isAllowed(key)) return key;
-	}
-}
-/**
-* Walks a Uniquery `$sort` control (accepts string, string[], object, or
-* array-of-{field: dir}) and returns the first field name that fails the
-* `isAllowed` predicate, or `undefined` if every sort key is allowed.
-*
-* Shared by the DB readable's `@db.column.sortable` gate and the value-help
-* controller's `@ui.dict.sortable` gate.
-*/
-function findSortOffender(sort, isAllowed) {
-	if (!sort) return void 0;
-	const check = (name) => isAllowed(name) ? void 0 : name;
-	if (typeof sort === "string") {
-		for (const part of sort.split(",")) {
-			const name = part.trim().replace(/^[-+]/, "").split(":")[0];
-			if (name) {
-				const bad = check(name);
-				if (bad) return bad;
-			}
-		}
-		return;
-	}
-	if (Array.isArray(sort)) {
-		for (const entry of sort) if (typeof entry === "string") {
-			const bad = check(entry.replace(/^[-+]/, ""));
-			if (bad) return bad;
-		} else if (entry && typeof entry === "object") for (const name of Object.keys(entry)) {
-			const bad = check(name);
-			if (bad) return bad;
-		}
-		return;
-	}
-	if (typeof sort === "object") for (const name of Object.keys(sort)) {
-		const bad = check(name);
-		if (bad) return bad;
-	}
-}
-//#endregion
 //#region src/mate.ts
 /**
 * Returns the shared moost-mate instance, typed against every key that
@@ -526,6 +478,122 @@ function isNonEmptyStringArray(value) {
 	return Array.isArray(value) && value.length > 0 && value.every((v) => typeof v === "string");
 }
 //#endregion
+//#region src/meta/terminal-ref.ts
+const NAV_KEYS = [
+	"db.rel.to",
+	"db.rel.from",
+	"db.rel.via"
+];
+function isNav(metadata) {
+	return NAV_KEYS.some((key) => metadata.has(key));
+}
+/**
+* Resolves a (possibly dotted) prop path against an object type by walking
+* `type.props` one segment at a time. Bails with `undefined` as soon as a hop
+* is not an object type or the segment is missing.
+*/
+function resolveProp(type, field) {
+	let current = type;
+	for (const segment of field.split(".")) {
+		if (!current || current.type.kind !== "object") return void 0;
+		current = current.type.props.get(segment);
+	}
+	return current;
+}
+/**
+* Follows `def.ref` hop by hop until a prop without a `ref` (a primary key or
+* a plain column) is reached. Cycle-safe (visited on `<typeId>.<field>`) and
+* bounded by chain length.
+*/
+function resolveTerminalRef(def) {
+	const ref = def.ref;
+	if (!ref) return void 0;
+	let type = ref.type();
+	let field = ref.field;
+	if (!type) return void 0;
+	let fk = def.metadata.has("db.rel.FK");
+	const visited = new Set([`${type.id ?? ""}.${field}`]);
+	for (;;) {
+		const prop = resolveProp(type, field);
+		if (!prop) break;
+		if (prop.metadata.has("db.rel.FK")) fk = true;
+		const next = prop.ref;
+		if (!next) break;
+		const nextType = next.type();
+		if (!nextType) break;
+		const key = `${nextType.id ?? ""}.${next.field}`;
+		if (visited.has(key)) break;
+		visited.add(key);
+		type = nextType;
+		field = next.field;
+	}
+	return {
+		type,
+		field,
+		fk
+	};
+}
+/**
+* Post-pass over a serialized type in lock-step with its runtime type: every
+* object prop (recursing into nested objects and array elements — never into
+* `ref` bodies or navigation subtrees) whose runtime prop has a `ref` gets its
+* serialized `ref` re-pointed to the terminal field (shallow `{ id, metadata }`
+* target, serialized with the same annotation whitelist) and, when the chain
+* passes an FK, `metadata["db.rel.FK"] = true` (never the hop's alias).
+*
+* Only shallow refs (`refDepth` with a `.5` step) are rewritten; a full-body
+* ref target is left alone. Mutates and returns `serialized`.
+*/
+function applyTerminalRefs(serialized, runtime, options) {
+	const shallowCache = /* @__PURE__ */ new Map();
+	const shallow = (type) => {
+		let target = shallowCache.get(type);
+		if (!target) {
+			target = {
+				id: type.id ?? "",
+				metadata: serializeAnnotatedType(type, {
+					...options,
+					refDepth: 0
+				}).metadata
+			};
+			shallowCache.set(type, target);
+		}
+		return target;
+	};
+	walk(serialized, runtime, shallow);
+	return serialized;
+}
+function walk(node, def, shallow) {
+	const kind = def.type.kind;
+	if (kind === "object") {
+		const sType = node.type;
+		if (sType.kind !== "object" || !sType.props) return;
+		for (const [name, prop] of def.type.props) {
+			const sProp = sType.props[name];
+			if (!sProp) continue;
+			if (isNav(prop.metadata)) continue;
+			if (prop.ref && sProp.ref && !("type" in sProp.ref.type)) {
+				const terminal = resolveTerminalRef(prop);
+				if (terminal) {
+					const direct = prop.ref.type();
+					if (terminal.type !== direct || terminal.field !== prop.ref.field) sProp.ref = {
+						field: terminal.field,
+						type: shallow(terminal.type)
+					};
+					if (terminal.fk && sProp.metadata["db.rel.FK"] === void 0) sProp.metadata["db.rel.FK"] = true;
+				}
+			}
+			walk(sProp, prop, shallow);
+		}
+		return;
+	}
+	if (kind === "array") {
+		const sType = node.type;
+		const of = def.type.of;
+		if (sType.kind === "array" && sType.of && of) walk(sType.of, of, shallow);
+	}
+}
+//#endregion
 //#region \0@oxc-project+runtime@0.133.0/helpers/esm/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
@@ -593,10 +661,21 @@ let AsReadableController = class AsReadableController {
 	}
 	/** Lazily serializes the bound type (after all controllers have set @db.http.path). */
 	getSerializedType() {
-		if (!this._serializedType) this._serializedType = serializeAnnotatedType(this.boundType, this.getSerializeOptions());
+		if (!this._serializedType) this._serializedType = this.serializeForMeta(this.boundType);
 		return this._serializedType;
 	}
 	/**
+	* Serializes a type for the meta surfaces (`/meta`, `/meta/form/:name`)
+	* with {@link getSerializeOptions}, then re-points every reference chain to
+	* its terminal field and inherits the `db.rel.FK` value-help marker through
+	* the chain (since 0.1.128; see `meta/terminal-ref.ts`). Direct references
+	* serialize exactly as before.
+	*/
+	serializeForMeta(type) {
+		const options = this.getSerializeOptions();
+		return applyTerminalRefs(serializeAnnotatedType(type, options), type, options);
+	}
+	/**
 	* One-time initialization hook. Override to seed data, register watchers, etc.
 	*/
 	init() {}
@@ -624,7 +703,7 @@ let AsReadableController = class AsReadableController {
 					key,
 					value
 				};
-				if (key === "db.json" || key === "db.patch.strategy" || key.startsWith("db.default") || key === "db.http.path" || key === "db.writeOnly") return {
+				if (key === "db.json" || key === "db.patch.strategy" || key.startsWith("db.default") || key === "db.http.path" || key === "db.writeOnly" || key === "db.column.version") return {
 					key,
 					value
 				};
@@ -671,24 +750,33 @@ let AsReadableController = class AsReadableController {
 		}
 	}
 	/**
-	* Shared filter/sort/search gate check. Subclasses assemble a {@link ReadableGates}
-	* config per request (or once in the constructor when static) and call this to
-	* get a uniform HTTP 400 response for any offending field/control.
+	* Per-request gate hook, invoked by the DB readable controller right after
+	* its capability gate (`checkCapabilities`) with the parsed query. The
+	* default accepts everything. Return an `HttpError` to reject.
+	*
+	* @deprecated since 0.1.128 — the filter / sort gate is the
+	* `FieldCapabilityIndex` behind `checkCapabilities` (override that, or read
+	* `this.capabilities` on `AsDbReadableController`); this hook only remains
+	* so subclasses that overrode it keep being called.
 	*/
-	checkGates(filter, controls, gates) {
-		if (gates.filter) {
-			const bad = findFilterOffender(filter, gates.filter.predicate);
-			if (bad) return new HttpError(400, `Filtering on field "${bad}" is not permitted — add ${gates.filter.annotation} to enable.`);
-		}
-		if (gates.sort) {
-			const bad = findSortOffender(controls.$sort, gates.sort.predicate);
-			if (bad) return new HttpError(400, `Sorting on field "${bad}" is not permitted — add ${gates.sort.annotation} to enable.`);
-		}
-		if (gates.search && controls.$search && !gates.search.allowed) return new HttpError(400, gates.search.rejectionMessage);
-	}
+	checkGates(_parsed) {}
 	parseQueryString(url) {
 		const idx = url.indexOf("?");
-		return parseUrl(idx >= 0 ? url.slice(idx + 1) : "");
+		return this.parseUrlOr400(idx >= 0 ? url.slice(idx + 1) : "");
+	}
+	/**
+	* The ONE place a query string meets the `@uniqu/url` grammar. A lexer /
+	* parser error (e.g. an unquoted `-` in a value: `?name=json-w1`) is the
+	* client's fault, so since 0.1.128 it is a 400 with the validation envelope
+	* `{ message, statusCode: 400, errors: [{ path: "", message }] }` instead of
+	* an unhandled 500. Quote such values: `?name='json-w1'`.
+	*/
+	parseUrlOr400(queryString) {
+		try {
+			return parseUrl(queryString);
+		} catch (error) {
+			throw badRequest("", `Malformed query string: ${error instanceof Error ? error.message : String(error)}`);
+		}
 	}
 	/**
 	* Parse a URL keeping only `$*` control keywords; report whether any
@@ -703,7 +791,7 @@ let AsReadableController = class AsReadableController {
 		const idx = url.indexOf("?");
 		const qs = idx >= 0 ? url.slice(idx + 1) : "";
 		if (!qs) return {
-			parsed: parseUrl(""),
+			parsed: this.parseUrlOr400(""),
 			hasNonControl: false
 		};
 		const kept = [];
@@ -722,7 +810,7 @@ let AsReadableController = class AsReadableController {
 			else hasNonControl = true;
 		}
 		return {
-			parsed: parseUrl(kept.join("&")),
+			parsed: this.parseUrlOr400(kept.join("&")),
 			hasNonControl
 		};
 	}
@@ -754,7 +842,7 @@ let AsReadableController = class AsReadableController {
 		if (!formType) throw new HttpError(404, `Unknown form "${name}"`);
 		let cached = this._formSchemas.get(name);
 		if (!cached) {
-			cached = serializeAnnotatedType(formType, this.getSerializeOptions());
+			cached = this.serializeForMeta(formType);
 			this._formSchemas.set(name, cached);
 		}
 		return cached;
@@ -1048,6 +1136,251 @@ function resolveBoundReadable(ctor) {
 	throw new Error(`[moost-db] ${ctor?.name || "controller"}: no readable bound. Either pass a table/view to super(...), or decorate the class with @TableController / @ReadableController (model token, lazy factory, or instance form).`);
 }
 //#endregion
+//#region src/meta/field-capabilities.ts
+const REASON_ADAPTER_FILTER = "adapter cannot filter on this storage type.";
+const REASON_ADAPTER_SORT = "adapter cannot sort on this storage type.";
+const REASON_WRITE_ONLY = "field is @db.writeOnly.";
+const REASON_ENCRYPTED = "field is @db.encrypted (ciphertext cannot be compared or ordered).";
+const REASON_ANNOTATION_FILTER = "add @db.column.filterable to enable.";
+const REASON_ANNOTATION_SORT = "add @db.column.sortable to enable.";
+/** Sentence subject per op ("Filtering on field …"). */
+const OP_SUBJECT = {
+	filter: "Filtering on",
+	sort: "Sorting on",
+	select: "Selecting",
+	groupBy: "Grouping by",
+	having: "Filtering ($having) on",
+	aggregate: "Aggregating over"
+};
+/** Lower-case verb per op ("… cannot filter JSON paths"). */
+const OP_VERB = {
+	filter: "filter",
+	sort: "sort by",
+	select: "select",
+	groupBy: "group by",
+	having: "filter ($having) on",
+	aggregate: "aggregate over"
+};
+function leafHint(leaves) {
+	if (leaves.length === 0) return "no leaf fields";
+	const shown = leaves.slice(0, 5).join(", ");
+	return leaves.length > 5 ? `${shown}, …` : shown;
+}
+/**
+* Capability index of one readable, built once per controller.
+*
+* - {@link entries} feeds `/meta.fields` (listed leaves in descriptor order);
+* - {@link check} is the request gate: same inputs, same answer.
+*
+* Paths outside the index are classified by the core's `classifyQueryPath`
+* (the same rules the core backstop applies) — navigation path, nested-object
+* parent, JSON descendant (relational adapters), encrypted descendant,
+* unknown — so the 400 names the storage reason and the alternative.
+*/
+var FieldCapabilityIndex = class {
+	filterableManual;
+	sortableManual;
+	/** Navigation relations (`@db.rel.to/from/via`), incl. nested ones. */
+	navFields;
+	/** `@db.writeOnly` paths. */
+	writeOnly;
+	/** Descriptors stored as one JSON column (relational adapters). */
+	jsonParents;
+	/** Descriptors carrying `@db.encrypted` (the ciphertext column on relational adapters). */
+	encryptedFields;
+	_entries = /* @__PURE__ */ new Map();
+	/** Nested-object parents (never listed, always selectable) → their listed leaves. */
+	_objectParents = /* @__PURE__ */ new Map();
+	/** Listed leaves — the {@link TQueryPathSource} view for `classifyQueryPath`. */
+	get leaves() {
+		return this._entries;
+	}
+	/** Nested-object parents — the {@link TQueryPathSource} view for `classifyQueryPath`. */
+	get objectParents() {
+		return this._objectParents;
+	}
+	constructor(source, writeOnly) {
+		const canFilter = (fd) => source.canFilterField(fd);
+		const canSort = (fd) => source.canSortField(fd);
+		const tableMeta = source.type.metadata;
+		this.filterableManual = tableMeta.get("db.table.filterable") === "manual";
+		this.sortableManual = tableMeta.get("db.table.sortable") === "manual";
+		this.writeOnly = writeOnly;
+		const nav = new Set(source.navFields);
+		if (nav.size === 0) for (const name of source.relations.keys()) nav.add(name);
+		this.navFields = nav;
+		const isNavOrDescendant = (path) => nav.has(path) || findAncestorInSet(path, nav) !== void 0;
+		const flatMap = source.flatMap;
+		const annotated = (fd, key) => {
+			const fromFlat = flatMap.get(fd.path)?.metadata?.has?.(key);
+			if (fromFlat !== void 0) return fromFlat;
+			return fd.type?.metadata?.has?.(key) ?? false;
+		};
+		const jsonParents = /* @__PURE__ */ new Set();
+		const encrypted = /* @__PURE__ */ new Set();
+		for (const fd of source.fieldDescriptors) {
+			if (fd.ignored) continue;
+			if (isNavOrDescendant(fd.path)) continue;
+			if (fd.storage === "json") jsonParents.add(fd.path);
+			if (fd.encrypted) encrypted.add(fd.path);
+			if (fd.designType === "object") {
+				this._objectParents.set(fd.path, []);
+				continue;
+			}
+			this._entries.set(fd.path, this._buildEntry(fd, canFilter, canSort, annotated));
+		}
+		const ignored = source.ignoredFields;
+		for (const [path, entry] of flatMap) {
+			if (!path || this._entries.has(path) || this._objectParents.has(path)) continue;
+			if (entry?.type?.kind !== "object") continue;
+			if (entry.metadata?.has?.("db.json")) continue;
+			if (isNavOrDescendant(path)) continue;
+			if (ignored.has(path)) continue;
+			if (findAncestorInSet(path, jsonParents) !== void 0) continue;
+			if (encrypted.has(path) || findAncestorInSet(path, encrypted) !== void 0) continue;
+			this._objectParents.set(path, []);
+		}
+		for (const [parent, leaves] of this._objectParents) {
+			const prefix = `${parent}.`;
+			for (const path of this._entries.keys()) if (path.startsWith(prefix)) leaves.push(path);
+		}
+		this.jsonParents = jsonParents;
+		this.encryptedFields = encrypted;
+	}
+	_buildEntry(fd, canFilter, canSort, annotated) {
+		const physicalFilter = canFilter(fd);
+		const physicalSort = canSort(fd);
+		const isWriteOnly = this.writeOnly.has(fd.path);
+		let filterable = physicalFilter;
+		let sortable = physicalSort;
+		let filterReason = physicalFilter ? void 0 : REASON_ADAPTER_FILTER;
+		let sortReason = physicalSort ? void 0 : REASON_ADAPTER_SORT;
+		let physicalReason = physicalFilter ? void 0 : REASON_ADAPTER_FILTER;
+		if (fd.encrypted) {
+			filterable = false;
+			sortable = false;
+			filterReason = REASON_ENCRYPTED;
+			sortReason = REASON_ENCRYPTED;
+			physicalReason = REASON_ENCRYPTED;
+		}
+		if (isWriteOnly) {
+			filterable = false;
+			sortable = false;
+			filterReason = REASON_WRITE_ONLY;
+			sortReason = REASON_WRITE_ONLY;
+			physicalReason = REASON_WRITE_ONLY;
+		}
+		if (filterable && this.filterableManual && !annotated(fd, "db.column.filterable")) {
+			filterable = false;
+			filterReason = REASON_ANNOTATION_FILTER;
+		}
+		if (sortable && this.sortableManual && !annotated(fd, "db.column.sortable")) {
+			sortable = false;
+			sortReason = REASON_ANNOTATION_SORT;
+		}
+		const cap = {
+			filterable,
+			sortable,
+			selectable: true,
+			indexed: fd.isIndexed === true
+		};
+		if (filterReason) cap.filterReason = filterReason;
+		if (sortReason) cap.sortReason = sortReason;
+		return {
+			fd,
+			cap,
+			physicalFilterable: physicalFilter && !isWriteOnly && !fd.encrypted,
+			physicalReason
+		};
+	}
+	/** Listed leaves in descriptor order — the `/meta.fields` projection source. */
+	*entries() {
+		for (const [path, entry] of this._entries) yield [
+			path,
+			entry.cap,
+			entry.fd
+		];
+	}
+	/** Physical filter capability (adapter ∧ ¬writeOnly ∧ ¬encrypted) — ignores the manual-mode policy. */
+	isPhysicallyFilterable(path) {
+		return this._entries.get(path)?.physicalFilterable === true;
+	}
+	/**
+	* Gate check for one path in one position. Returns `undefined` when the
+	* path is accepted. Order: navigation paths first (a nav path "exists" on
+	* the target table but is never a column here), then a listed leaf's
+	* capability (no existence lookup needed — every listed leaf is a real
+	* field), then `exists` (the readable's `isValidFieldPath`) and, for paths
+	* that exist but are not leaves, the storage classification.
+	*
+	* Existence deliberately runs BEFORE the JSON / encrypted classification:
+	* an untyped descendant of a JSON column (`address.nope`) is reported as
+	* `Unknown field`, not as "inside JSON-stored column" — clients pin that
+	* wording, so do not "align" it with the core backstop's text.
+	*/
+	check(path, op, exists) {
+		const { kind, parent } = classifyQueryPath(this, path);
+		if (kind === "nav") {
+			if (parent === void 0) return {
+				path,
+				message: `"${path}" is a navigation property — use $with=${path} to load it`
+			};
+			return {
+				path,
+				message: `"${path}" is a navigation path — use $with=${parent}(...) to filter or select fields of the related rows (e.g. $with=${parent}($select=${path.slice(parent.length + 1)}))`
+			};
+		}
+		if (kind === "leaf") {
+			const entry = this._entries.get(path);
+			switch (op) {
+				case "select": return entry.cap.selectable ? void 0 : {
+					path,
+					message: `Selecting field "${path}" is not permitted.`
+				};
+				case "filter": return entry.cap.filterable ? void 0 : {
+					path,
+					message: `Filtering on field "${path}" is not permitted — ${entry.cap.filterReason}`
+				};
+				case "sort": return entry.cap.sortable ? void 0 : {
+					path,
+					message: `Sorting on field "${path}" is not permitted — ${entry.cap.sortReason}`
+				};
+				default: return entry.physicalFilterable ? void 0 : {
+					path,
+					message: `${OP_SUBJECT[op]} field "${path}" is not permitted — ${entry.physicalReason}`
+				};
+			}
+		}
+		if (!exists(path)) return {
+			path,
+			message: `Unknown field "${path}"`
+		};
+		switch (kind) {
+			case "objectParent":
+				if (op === "select") return void 0;
+				return {
+					path,
+					message: `"${path}" is a nested object — filter or sort on one of its leaves (${leafHint(this._objectParents.get(path))})`
+				};
+			case "jsonDescendant": return {
+				path,
+				message: `"${path}" is inside JSON-stored column "${parent}" — this adapter cannot ${OP_VERB[op]} JSON paths; select "${parent}" and read the value client-side.`
+			};
+			case "encryptedDescendant": return op === "select" ? {
+				path,
+				message: `"${path}" is inside encrypted field "${parent}" — select the encrypted parent "${parent}" instead.`
+			} : {
+				path,
+				message: `Cannot ${OP_VERB[op]} encrypted field "${path}"`
+			};
+			default: return {
+				path,
+				message: `Unknown field "${path}"`
+			};
+		}
+	}
+};
+//#endregion
 //#region src/permissions/crud-controls.ts
 /**
 * Static control whitelists per read op. Each list is the matching DTO's
@@ -1085,6 +1418,15 @@ const GEO_CONTROLS = [
 ];
 //#endregion
 //#region src/as-db-readable.controller.ts
+/** The gate positions in check order; `refs[op]` are the paths collected for each. */
+const OPS = [
+	"filter",
+	"sort",
+	"select",
+	"groupBy",
+	"having",
+	"aggregate"
+];
 let AsDbReadableController = class AsDbReadableController extends AsReadableController {
 	/** Reference to the underlying readable (table or view). */
 	readable;
@@ -1100,34 +1442,49 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		if (readable && (readable.isView || typeof readable.insertOne !== "function")) throw new Error(`${this.constructor.name} is bound to a ${readable.isView ? "view" : "non-table readable"} ("${readable.tableName}") — .table is only available for table-bound controllers.`);
 		return readable;
 	}
-	_gates;
+	/**
+	* Per-path capability index (since 0.1.128): the ONE input both `/meta.fields`
+	* and the request gate ({@link checkCapabilities}) are computed from, so
+	* metadata and runtime can never diverge.
+	*/
+	capabilities;
+	/** Bound once: the field-existence check the gate hands to `capabilities.check`. */
+	_exists = (path) => this.hasField(path);
 	_preferredIdSet;
 	_overlayIsNoOp;
 	/** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
 	_quantityRefByPath;
-	/** Paths the adapter vetoes for filtering (e.g. JSON storage on SQL). Symmetric with `/meta` `filterable: false`. */
-	_adapterNonFilterable;
 	/** `@db.column.searchable` paths — the `$search` fallback when the adapter has no native search. */
 	_searchFallbackFields;
 	/** `@db.writeOnly` paths — settable in writes, sealed out of every read surface. */
 	_writeOnlySet;
+	/**
+	* Logical paths an exclusion `$select` inverts into: every listed leaf and
+	* (on nested-object adapters) object parents — never navigation descendants,
+	* which the core path guard rejects.
+	*/
+	_invertibleFields;
 	constructor(app, readable) {
 		const resolved = readable ?? resolveBoundReadable(new.target);
 		super(resolved.type, resolved.tableName, app, resolved.isView ? "view" : "table");
 		this.readable = resolved;
-		this._adapterNonFilterable = this._collectAdapterNonFilterable();
 		this._writeOnlySet = this._collectAnnotated("db.writeOnly");
+		this.capabilities = new FieldCapabilityIndex(resolved, this._writeOnlySet);
+		this._invertibleFields = this._collectInvertibleFields();
 		this._searchFallbackFields = this._collectSearchFallbackFields();
-		this._gates = this._buildGates();
 		this._preferredIdSet = new Set(resolved.preferredId ?? []);
 		this._quantityRefByPath = this._collectQuantityRefs();
 		const defaultOverlay = AsReadableController.prototype.applyMetaOverlay;
 		this._overlayIsNoOp = this.applyMetaOverlay === defaultOverlay;
 	}
-	_collectAdapterNonFilterable() {
-		const out = /* @__PURE__ */ new Set();
-		if (!this.readable.fieldDescriptors || typeof this.readable.canFilterField !== "function") return out;
-		for (const fd of this.readable.fieldDescriptors) if (!fd.ignored && !this.readable.canFilterField(fd)) out.add(fd.path);
+	_collectInvertibleFields() {
+		const out = [];
+		const nav = this.capabilities.navFields;
+		for (const fd of this.readable.fieldDescriptors) {
+			if (fd.ignored) continue;
+			if (nav.has(fd.path) || findAncestorInSet(fd.path, nav) !== void 0) continue;
+			out.push(fd.path);
+		}
 		return out;
 	}
 	_collectQuantityRefs() {
@@ -1140,41 +1497,8 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		}
 		return out;
 	}
-	_buildGates() {
-		const meta = this.readable.type.metadata;
-		const gates = {};
-		if (meta.get("db.table.filterable") === "manual") {
-			const allowed = this._collectAnnotated("db.column.filterable");
-			gates.filter = {
-				predicate: (f) => allowed.has(f),
-				annotation: "@db.column.filterable"
-			};
-		}
-		if (meta.get("db.table.sortable") === "manual") {
-			const allowed = this._collectAnnotated("db.column.sortable");
-			gates.sort = {
-				predicate: (f) => allowed.has(f),
-				annotation: "@db.column.sortable"
-			};
-		}
-		const writeOnly = this._writeOnlySet;
-		if (writeOnly.size > 0) {
-			const prevFilter = gates.filter;
-			gates.filter = {
-				predicate: (f) => !writeOnly.has(f) && (prevFilter ? prevFilter.predicate(f) : true),
-				annotation: prevFilter?.annotation ?? "@db.column.filterable (field is @db.writeOnly)"
-			};
-			const prevSort = gates.sort;
-			gates.sort = {
-				predicate: (f) => !writeOnly.has(f) && (prevSort ? prevSort.predicate(f) : true),
-				annotation: prevSort?.annotation ?? "@db.column.sortable (field is @db.writeOnly)"
-			};
-		}
-		return gates;
-	}
 	_collectAnnotated(annotation) {
 		const out = /* @__PURE__ */ new Set();
-		if (!this.readable.flatMap) return out;
 		for (const [path, entry] of this.readable.flatMap) if (entry?.metadata?.has?.(annotation)) out.add(path);
 		return out;
 	}
@@ -1183,18 +1507,49 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		return this.readable.flatMap.has(path);
 	}
 	/**
-	* Adds an adapter-capability veto on top of the base gate. Distinct from the
-	* `@db.column.filterable` rejection because the message must reference the
-	* adapter, not an annotation the user could add to bypass it. Sort uses
-	* adapter capability differently and is enforced at the SQL builder layer.
+	* Structural capability gate (since 0.1.128): walks the PARSED query —
+	* filter tree, `$sort`, `$select`, `$groupBy`, `$having`, aggregate
+	* `$field`s — and checks every root path against {@link capabilities}, the
+	* same index `/meta.fields` is projected from. Runs on the wire request,
+	* before `transformFilter` / `transformProjection` and before the write-only
+	* seal (a `@db.writeOnly` field is selectable; the seal strips it silently).
+	*
+	* Rejections use the structured envelope `{ message, statusCode: 400,
+	* errors: [{ path, message }] }` — `path` is the offending logical path.
+	* After the per-path checks the core `$having` rule runs (`checkHavingKeys`:
+	* aliases or `$groupBy` fields only), so a readable mock and a real table
+	* answer alike.
 	*/
-	checkGates(filter, controls, gates) {
-		const baseError = super.checkGates(filter, controls, gates);
-		if (baseError) return baseError;
-		if (this._adapterNonFilterable.size === 0) return void 0;
-		const offender = findFilterOffender(filter, (f) => !this._adapterNonFilterable.has(f));
-		if (!offender) return void 0;
-		return new HttpError(400, `Filtering on field "${offender}" is not permitted — adapter cannot filter on this storage type.`);
+	checkCapabilities(parsed) {
+		const refs = collectQueryPaths$1(parsed);
+		if (refs.unsupportedOperator !== void 0) return badRequest(refs.unsupportedOperator, unsupportedOperatorMessage(refs.unsupportedOperator));
+		for (const op of OPS) for (const path of refs[op]) {
+			const verdict = this.capabilities.check(path, op, this._exists);
+			if (verdict) return badRequest(verdict.path, verdict.message);
+		}
+		for (const path of refs.geoFilter) {
+			const verdict = this.capabilities.check(path, "filter", this._exists);
+			if (verdict) return badRequest(verdict.path, verdict.message);
+		}
+		const having = checkHavingKeys(refs);
+		if (having) return badRequest(having.path, having.message);
+		return this.checkGates(parsed);
+	}
+	/**
+	* Root-path existence moved into {@link checkCapabilities}; the insights map
+	* only serves `$with` sub-controls here — the URL parser flattens
+	* `$with=assignee($select=name)` into the insight `assignee.name`, which is
+	* resolved against the target table through `isValidFieldPath`.
+	*/
+	validateInsights(insights) {
+		const nav = this.capabilities.navFields;
+		for (const [key] of insights) {
+			if (key === "*") continue;
+			const dot = key.indexOf(".");
+			if (dot === -1) continue;
+			if (!nav.has(key.slice(0, dot))) continue;
+			if (!this.hasField(key)) return `Unknown field "${key}"`;
+		}
 	}
 	/** Validates $with relations against the readable. */
 	validateParsed(parsed, type) {
@@ -1203,14 +1558,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const withRelations = parsed.controls.$with;
 		if (withRelations?.length) {
 			const relations = this.readable.relations;
-			for (const rel of withRelations) if (!rel.name.includes(".") && !relations.has(rel.name)) return new HttpError(400, {
-				message: `Unknown relation "${rel.name}" in $with. Available relations: ${[...relations.keys()].join(", ") || "(none)"}`,
-				statusCode: 400,
-				errors: [{
-					path: "$with",
-					message: `Unknown relation "${rel.name}"`
-				}]
-			});
+			for (const rel of withRelations) if (!rel.name.includes(".") && !relations.has(rel.name)) return badRequest("$with", `Unknown relation "${rel.name}"`, `Unknown relation "${rel.name}" in $with. Available relations: ${[...relations.keys()].join(", ") || "(none)"}`);
 		}
 	}
 	/**
@@ -1285,7 +1633,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			return widened;
 		}
 		const widened = {};
-		for (const fd of this.readable.fieldDescriptors) if (!fd.ignored && !excluded.has(fd.path)) widened[fd.path] = 1;
+		for (const path of this._invertibleFields) if (!excluded.has(path)) widened[path] = 1;
 		for (const field of this._preferredIdSet) widened[field] = 1;
 		return widened;
 	}
@@ -1354,9 +1702,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		if (included.length > 0 && excluded.length === 0) return included;
 		if (excluded.length > 0 && included.length === 0) {
 			const excludedSet = new Set(excluded);
-			const out = [];
-			for (const fd of this.readable.fieldDescriptors) if (!fd.ignored && !excludedSet.has(fd.path)) out.push(fd.path);
-			return out;
+			return this._invertibleFields.filter((path) => !excludedSet.has(path));
 		}
 		throw new HttpError(500, "[moost-db] mixed inclusion/exclusion projection reached augmenter; widenPreferredIdProjection should have rejected it");
 	}
@@ -1400,15 +1746,18 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			widenedSelect: resolvedProjection === null ? null : this._widenSelectForActions(envelopes, resolvedProjection)
 		};
 	}
-	/** `@db.column.searchable` paths, minus anything the adapter can't filter (JSON storage, encrypted). */
+	/**
+	* `@db.column.searchable` paths, minus anything the adapter can't filter
+	* (JSON storage, encrypted), `@db.writeOnly` fields and navigation
+	* descendants — physical capability only (manual-mode policy does not
+	* apply to `$search`).
+	*/
 	_collectSearchFallbackFields() {
 		const out = [];
-		if (!this.readable.fieldDescriptors) return out;
 		for (const fd of this.readable.fieldDescriptors) {
 			if (fd.ignored) continue;
 			if (!fd.type?.metadata?.has?.("db.column.searchable")) continue;
-			if (this._adapterNonFilterable.has(fd.path)) continue;
-			if (this._writeOnlySet.has(fd.path)) continue;
+			if (!this.capabilities.isPhysicallyFilterable(fd.path)) continue;
 			out.push(fd.path);
 		}
 		return out;
@@ -1533,11 +1882,13 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		if (groupBy?.length && controls.$with?.length) return new HttpError(400, "Cannot combine $with and $groupBy in the same query");
 		const error = this.validateParsed(parsed, "query");
 		if (error) return error;
-		const gateError = this.checkGates(parsed.filter, controls, this._gates);
-		if (gateError) return gateError;
 		if (groupBy?.length) {
 			const sealed = this._findWriteOnlyInAggregate(groupBy, controls.$select);
 			if (sealed) return new HttpError(400, `Field "${sealed}" is @db.writeOnly and cannot be aggregated`);
+		}
+		const gateError = this.checkCapabilities(parsed);
+		if (gateError) return gateError;
+		if (groupBy?.length) {
 			const filter = this.applySearchFallback(await this.transformFilter(parsed.filter), controls);
 			return this.readable.aggregate({
 				filter,
@@ -1584,7 +1935,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const error = this.validateParsed(parsed, "pages");
 		if (error) return error;
 		const controls = parsed.controls;
-		const gateError = this.checkGates(parsed.filter, controls, this._gates);
+		const gateError = this.checkCapabilities(parsed);
 		if (gateError) return gateError;
 		const page = Math.max(Number(controls.$page || 1), 1);
 		const size = Math.max(Number(controls.$size || 10), 1);
@@ -1646,7 +1997,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			const insightsError = this.validateInsights(parsed.insights);
 			if (insightsError) return new HttpError(400, insightsError);
 		}
-		const gateError = this.checkGates(parsed.filter, controls, this._gates);
+		const gateError = this.checkCapabilities(parsed);
 		if (gateError) return gateError;
 		const [filter, transformedSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
 		const select = this.widenPreferredIdProjection(this._sealProjection(transformedSelect));
@@ -1707,6 +2058,8 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		this._coerceActionsControl(parsed.controls);
 		const error = this.validateParsed(parsed, "getOne");
 		if (error) return error;
+		const gateError = this.checkCapabilities(parsed);
+		if (gateError) return gateError;
 		const rawSelect = await this.transformProjection(parsed.controls.$select);
 		const select = this.widenPreferredIdProjection(this._sealProjection(rawSelect));
 		if (select instanceof HttpError) return select;
@@ -1722,6 +2075,10 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		if (idObj instanceof HttpError) return idObj;
 		const { parsed } = this.parseControlsOnlyFromUrl(url);
 		this._coerceActionsControl(parsed.controls);
+		const error = this.validateParsed(parsed, "getOne");
+		if (error) return error;
+		const gateError = this.checkCapabilities(parsed);
+		if (gateError) return gateError;
 		const rawSelect = await this.transformProjection(parsed.controls.$select);
 		const select = this.widenPreferredIdProjection(this._sealProjection(rawSelect));
 		if (select instanceof HttpError) return select;
@@ -1768,32 +2125,21 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			direction: rel.direction,
 			isArray: rel.isArray
 		});
-		const filterableMode = this.readable.type.metadata.get("db.table.filterable") === "manual";
-		const sortableMode = this.readable.type.metadata.get("db.table.sortable") === "manual";
 		const geoIndexedPhysical = /* @__PURE__ */ new Set();
 		if (this.readable.indexes instanceof Map) {
 			for (const index of this.readable.indexes.values()) if (index.type === "geo") for (const f of index.fields) geoIndexedPhysical.add(f.name);
 		}
 		const fields = {};
-		for (const fd of this.readable.fieldDescriptors) {
-			if (fd.ignored) continue;
-			if (fd.designType === "object") continue;
-			const annotations = fd.type?.metadata;
-			const annotatedFilterable = annotations?.has("db.column.filterable") ?? false;
-			const annotatedSortable = annotations?.has("db.column.sortable") ?? false;
-			const adapterCanFilter = this.readable.canFilterField(fd);
-			const adapterCanSort = this.readable.canSortField(fd);
-			fields[fd.path] = {
-				sortable: adapterCanSort && (sortableMode ? annotatedSortable : !!fd.isIndexed),
-				filterable: adapterCanFilter && (filterableMode ? annotatedFilterable : true)
+		for (const [path, cap, fd] of this.capabilities.entries()) {
+			const entry = {
+				sortable: cap.sortable,
+				filterable: cap.filterable
 			};
-			if (fd.encrypted) fields[fd.path].encrypted = true;
-			if (geoIndexedPhysical.has(fd.physicalName)) fields[fd.path].geo = true;
-			if (this._writeOnlySet.has(fd.path)) {
-				fields[fd.path].writeOnly = true;
-				fields[fd.path].filterable = false;
-				fields[fd.path].sortable = false;
-			}
+			if (cap.indexed) entry.indexed = true;
+			if (fd.encrypted) entry.encrypted = true;
+			if (geoIndexedPhysical.has(fd.physicalName)) entry.geo = true;
+			if (this._writeOnlySet.has(path)) entry.writeOnly = true;
+			fields[path] = entry;
 		}
 		return {
 			searchable: this.readable.isSearchable() || this._searchFallbackFields.length > 0,
@@ -1873,30 +2219,27 @@ AsDbReadableController = __decorate([
 registerAsDbReadableController(AsDbReadableController);
 //#endregion
 //#region src/as-db.controller.ts
+var _AsDbController;
+const SHAPE_MESSAGE = "Expected an object";
 /**
-* Strips the version field from a write body and lifts it to `$cas`, in place.
-* Returns `true` iff a `$cas` predicate was actually attached — callers use
-* this to gate the 404/409 disambiguation `findOne`.
-*
-* Per §6.2 of VERSION_PROPOSAL.md, the moost-db controller treats `version` in
-* a write body as a `$cas` directive rather than a SET. No-op (returns `false`)
-* when:
-* - the payload isn't an object (rejected downstream by the SDK validator),
-* - the version field is absent (presence-based opt-out → last-write-wins),
-* - the value is not a finite number (the SDK will reject loudly via
-*   `$cas` validation — we don't shadow that with a controller-local 400).
+* Shape gate (since 0.1.128): a write body must be a plain object (single
+* actions) or an array of plain objects (`*Many`). Anything else — `null`, a
+* primitive, `[1, "x"]` — is rejected with the validator envelope BEFORE any
+* hook runs, so `onWrite` / `guardWrite` never see a non-object.
 */
-function liftVersionToCas(payload, versionColumn) {
-	if (payload === null || typeof payload !== "object") return false;
-	const obj = payload;
-	if (!(versionColumn in obj)) return false;
-	const versionValue = obj[versionColumn];
-	if (typeof versionValue !== "number" || !Number.isFinite(versionValue)) return false;
-	delete obj[versionColumn];
-	obj.$cas = { [versionColumn]: versionValue };
-	return true;
+function assertWriteShape(payload) {
+	if (Array.isArray(payload)) {
+		for (let i = 0; i < payload.length; i++) if (!isPlainObject(payload[i])) throw badRequest(`[${i}]`, SHAPE_MESSAGE);
+		return;
+	}
+	if (!isPlainObject(payload)) throw badRequest("", SHAPE_MESSAGE);
+}
+/** `true` when `data` still has the shape the endpoint received (object, or array of objects for `*Many`). */
+function hasWriteShape(data, many) {
+	if (!many) return isPlainObject(data);
+	return Array.isArray(data) && data.every(isPlainObject);
 }
-let AsDbController = class AsDbController extends AsDbReadableController {
+let AsDbController = _AsDbController = class AsDbController extends AsDbReadableController {
 	constructor(app, table) {
 		super(app, table);
 	}
@@ -1910,80 +2253,189 @@ let AsDbController = class AsDbController extends AsDbReadableController {
 		};
 	}
 	/**
-	* Intercepts write operations. Return `undefined` to abort.
-	* May be async (e.g. to enrich payloads from session / permissions).
+	* Intercepts write operations with the UNTRUSTED body (after the shape gate:
+	* an object, or an array of objects). Runs outside any transaction. Return
+	* the data in the shape received — an object, or an array of objects for
+	* the `*Many` actions; anything else (including `undefined`) aborts with
+	* 500 "Not saved". Return an `Error` instance to respond with that error
+	* (since 0.1.128 — previously passed on as data); throw to respond with
+	* the thrown error's status. May be async (e.g. to enrich payloads from
+	* session / permissions).
 	*/
 	onWrite(action, data) {
 		return data;
 	}
 	/**
-	* Intercepts delete operations. Return `undefined` to abort.
-	* May be async (e.g. to resolve composite ids from external state).
+	* Intercepts delete operations. Return `undefined` to abort (500 "Not
+	* deleted"); return an `Error` instance to respond with that error.
+	* Runs outside any transaction. May be async (e.g. to resolve composite
+	* ids from external state).
 	*/
 	onRemove(id) {
 		return id;
 	}
 	/**
+	* Validated-stage write guard (since 0.1.128). Overriding it is the switch:
+	* the override is passed to the table as its `guard` write option and runs
+	* once inside the table's own transaction, after defaults + validation and
+	* before encryption / nested-relation phases. `ctx.rows` are the validated
+	* rows (defaults applied on insert/replace; `$cas` removed on update) and
+	* may be enriched in place — the table validates them again afterwards.
+	* Reject by throwing (an `HttpError` is recommended): the transaction rolls
+	* back and the error propagates unchanged. Unmodified controllers pass no
+	* guard and pay nothing.
+	*
+	* Do not swallow `DbError`s (on PostgreSQL the transaction is aborted after
+	* a failed statement), and do not await external I/O on SQLite (the guard
+	* holds the connection). On MongoDB replica sets the transaction callback —
+	* and therefore this guard — may run more than once on transient errors.
+	*/
+	guardWrite(_ctx) {}
+	/**
+	* Validated-stage remove guard (since 0.1.128). Same switch semantics as
+	* {@link guardWrite}: the override becomes `deleteOne`'s `guard` option and
+	* runs inside the table's transaction once `onRemove`'s id resolved to a
+	* filter. A missing row still reaches the guard — `ctx.current()` resolves
+	* to `null` and the 404 comes after the guard; only an id that cannot be
+	* resolved to a filter at all (malformed for the key type) is a 404 before
+	* the guard.
+	*/
+	guardRemove(_ctx) {}
+	/**
+	* Runs `fn` inside the bound table's adapter transaction (nested calls
+	* join it). For custom actions and routes that need one transaction across
+	* several table operations.
+	*/
+	withTransaction(fn) {
+		return this.table.getAdapter().withTransaction(fn);
+	}
+	/**
+	* The table write call's trailing options: `[{ guard }]` only when
+	* `guardWrite` is overridden, else nothing (the table is called exactly as
+	* an unmodified controller always called it).
+	*/
+	_writeArgs() {
+		if (this.guardWrite === _AsDbController.prototype.guardWrite) return [];
+		return [{ guard: (ctx) => this.guardWrite(ctx) }];
+	}
+	/** `deleteOne`'s trailing options: `[{ guard }]` only when `guardRemove` is overridden. */
+	_removeArgs() {
+		if (this.guardRemove === _AsDbController.prototype.guardRemove) return [];
+		return [{ guard: (ctx) => this.guardRemove(ctx) }];
+	}
+	/** Resolves a hook result: `undefined` aborts with `abortMessage`, an `Error` is thrown, anything else passes. */
+	async _checkHook(pending, abortMessage) {
+		const result = await pending;
+		if (result === void 0) throw new HttpError(500, abortMessage);
+		if (result instanceof Error) throw result;
+		return result;
+	}
+	/** Runs `onWrite` and re-applies the shape gate to its output (a non-object is a 500 "Not saved"). */
+	async _writeBody(action, payload, many) {
+		const data = await this._checkHook(this.onWrite(action, payload), "Not saved");
+		if (!hasWriteShape(data, many)) throw new HttpError(500, "Not saved");
+		return data;
+	}
+	/**
+	* Normalises the OCC shape of one write item in place through the shared
+	* `reconcileCas` (since 0.1.128): a top-level `version` field in a write
+	* body is a `$cas` directive, not a SET — it is lifted to
+	* `$cas: { [versionColumn]: version }`; a raw SDK-shaped `$cas` is accepted
+	* as sent; both present with different values → 400 at `$cas`; a malformed
+	* `$cas` reports `separateCas`'s own message. Returns `true` iff the item is
+	* CAS-bearing — callers use this to gate the 404/409 disambiguation
+	* `findOne` on `matchedCount === 0`. On a non-versioned table nothing is
+	* lifted and a raw `$cas` reaches the table, which rejects it.
+	*/
+	_resolveCas(item, versionColumn, pathPrefix = "") {
+		if (versionColumn === void 0) return false;
+		try {
+			return reconcileCas(item, versionColumn, "cas") !== void 0;
+		} catch (error) {
+			if (error instanceof DbError) throw errorEnvelope(400, error.message, error.errors.map((e) => ({
+				path: `${pathPrefix}${e.path}`,
+				message: e.message
+			})));
+			throw error;
+		}
+	}
+	/**
+	* Bulk auto-lift: each item carries its own `version` → `$cas`.
+	* NOTE: per-item conflict disambiguation in the response body is deferred
+	* (§6.4) — the aggregate `{ matchedCount, modifiedCount }` surfaces partial
+	* application; callers can detect mismatches via `modifiedCount < N`.
+	*/
+	_resolveBulkCas(rows, versionColumn) {
+		if (versionColumn === void 0) return;
+		for (let i = 0; i < rows.length; i++) this._resolveCas(rows[i], versionColumn, `[${i}].`);
+	}
+	/** Deletes by id (guard forwarded when overridden) and maps "nothing deleted" to 404. */
+	async _deleteOrThrow(id) {
+		const result = await this.table.deleteOne(id, ...this._removeArgs());
+		if (result.deletedCount < 1) throw new HttpError(404);
+		return result;
+	}
+	/**
 	* **POST /** — inserts one or many records.
 	*/
 	async insert(payload) {
+		assertWriteShape(payload);
 		if (Array.isArray(payload)) {
-			const data = await this.onWrite("insertMany", payload);
-			if (data === void 0) return new HttpError(500, "Not saved");
-			return await this.table.insertMany(data);
+			const rows = await this._writeBody("insertMany", payload, true);
+			return this.table.insertMany(rows, ...this._writeArgs());
 		}
-		const data = await this.onWrite("insert", payload);
-		if (data === void 0) return new HttpError(500, "Not saved");
-		return await this.table.insertOne(data);
+		const row = await this._writeBody("insert", payload, false);
+		return this.table.insertOne(row, ...this._writeArgs());
 	}
 	/**
 	* **PUT /** — fully replaces one or many records matched by primary key.
 	*
 	* When the table opts into OCC (`@db.column.version`), a top-level `version`
-	* field in the body is auto-lifted to `$cas` (§6.2 of VERSION_PROPOSAL.md).
-	* On `matchedCount === 0` for a CAS-protected write, this disambiguates
-	* 404 (row gone) vs 409 (version mismatch) via a single `findOne`.
+	* field in the body is auto-lifted to `$cas` (§6.2 of VERSION_PROPOSAL.md);
+	* a raw `$cas` is accepted as sent. On `matchedCount === 0` for a
+	* CAS-bearing write, this disambiguates 404 (row gone) vs 409 (version
+	* mismatch) via a single `findOne` after the table call.
 	*/
 	async replace(payload) {
+		assertWriteShape(payload);
 		const versionColumn = this.table.versionColumn;
 		if (Array.isArray(payload)) {
-			const data = await this.onWrite("replaceMany", payload);
-			if (data === void 0) return new HttpError(500, "Not saved");
-			if (versionColumn !== void 0) for (const item of data) liftVersionToCas(item, versionColumn);
-			return await this.table.bulkReplace(data);
-		}
-		const data = await this.onWrite("replace", payload);
-		if (data === void 0) return new HttpError(500, "Not saved");
-		const hadCasLift = versionColumn !== void 0 && liftVersionToCas(data, versionColumn);
-		const result = await this.table.replaceOne(data);
-		if (hadCasLift && result.matchedCount === 0) return await this._disambiguateMismatch(data, versionColumn);
+			const rows = await this._writeBody("replaceMany", payload, true);
+			this._resolveBulkCas(rows, versionColumn);
+			return this.table.bulkReplace(rows, ...this._writeArgs());
+		}
+		const row = await this._writeBody("replace", payload, false);
+		const hadCas = this._resolveCas(row, versionColumn);
+		const result = await this.table.replaceOne(row, ...this._writeArgs());
+		if (hadCas && result.matchedCount === 0) throw await this._disambiguateMismatch(row, versionColumn);
 		return result;
 	}
 	/**
 	* **PATCH /** — partially updates one or many records matched by primary key.
 	*
-	* Same OCC semantics as {@link replace} (§6.2 / §6.3).
+	* Same OCC semantics as {@link replace} (§6.2 / §6.3). A PK-only body
+	* carrying `version` (or `$cas`) is a real write — the "versioned touch":
+	* the CAS statement executes and bumps the version on a hit.
 	*/
 	async update(payload) {
+		assertWriteShape(payload);
 		const versionColumn = this.table.versionColumn;
 		if (Array.isArray(payload)) {
-			const data = await this.onWrite("updateMany", payload);
-			if (data === void 0) return new HttpError(500, "Not saved");
-			if (versionColumn !== void 0) for (const item of data) liftVersionToCas(item, versionColumn);
-			return await this.table.bulkUpdate(data);
-		}
-		const data = await this.onWrite("update", payload);
-		if (data === void 0) return new HttpError(500, "Not saved");
-		const hadCasLift = versionColumn !== void 0 && liftVersionToCas(data, versionColumn);
-		const result = await this.table.updateOne(data);
-		if (hadCasLift && result.matchedCount === 0) return await this._disambiguateMismatch(data, versionColumn);
+			const rows = await this._writeBody("updateMany", payload, true);
+			this._resolveBulkCas(rows, versionColumn);
+			return this.table.bulkUpdate(rows, ...this._writeArgs());
+		}
+		const row = await this._writeBody("update", payload, false);
+		const hadCas = this._resolveCas(row, versionColumn);
+		const result = await this.table.updateOne(row, ...this._writeArgs());
+		if (hadCas && result.matchedCount === 0) throw await this._disambiguateMismatch(row, versionColumn);
 		return result;
 	}
 	/**
 	* Disambiguates a `matchedCount === 0` result on a CAS-protected write:
 	* returns 404 when the row is genuinely missing, 409 with
 	* `{ error: "version_mismatch", currentVersion: N }` when it's present
-	* but the supplied version is stale (§6.3).
+	* but the supplied version is stale (§6.3). Callers throw the result.
 	*/
 	async _disambiguateMismatch(data, versionColumn) {
 		const filter = this.table.resolveIdFilter(data);
@@ -2003,11 +2455,8 @@ let AsDbController = class AsDbController extends AsDbReadableController {
 	* **DELETE /:id** — removes a single record by primary key.
 	*/
 	async remove(id) {
-		const resolvedId = await this.onRemove(id);
-		if (resolvedId === void 0) return new HttpError(500, "Not deleted");
-		const result = await this.table.deleteOne(resolvedId);
-		if (result.deletedCount < 1) return new HttpError(404);
-		return result;
+		const resolvedId = await this._checkHook(this.onRemove(id), "Not deleted");
+		return this._deleteOrThrow(resolvedId);
 	}
 	/**
 	* **DELETE /?field1=val1&field2=val2** — removes a record by composite key
@@ -2015,12 +2464,9 @@ let AsDbController = class AsDbController extends AsDbReadableController {
 	*/
 	async removeComposite(query) {
 		const idObj = this.extractIdShape(query);
-		if (idObj instanceof HttpError) return idObj;
-		const resolvedId = await this.onRemove(idObj);
-		if (resolvedId === void 0) return new HttpError(500, "Not deleted");
-		const result = await this.table.deleteOne(resolvedId);
-		if (result.deletedCount < 1) return new HttpError(404);
-		return result;
+		if (idObj instanceof HttpError) throw idObj;
+		const resolvedId = await this._checkHook(this.onRemove(idObj), "Not deleted");
+		return this._deleteOrThrow(resolvedId);
 	}
 };
 __decorate([
@@ -2058,7 +2504,7 @@ __decorate([
 	__decorateMetadata("design:paramtypes", [typeof Record === "undefined" ? Object : Record]),
 	__decorateMetadata("design:returntype", Promise)
 ], AsDbController.prototype, "removeComposite", null);
-AsDbController = __decorate([
+AsDbController = _AsDbController = __decorate([
 	Inherit(),
 	__decorateParam(1, Inject(TABLE_DEF)),
 	__decorateParam(1, Optional()),
@@ -2492,7 +2938,7 @@ function validateMultiId(body, source) {
 	return body;
 }
 function collectIdErrors(value, source, pathPrefix) {
-	if (!isPlainObject(value)) return [{
+	if (!isPlainObject$1(value)) return [{
 		path: pathPrefix,
 		message: "Expected JSON object for row identifier",
 		details: []
@@ -2535,7 +2981,7 @@ function describe(value) {
 	if (Array.isArray(value)) return "array";
 	return typeof value;
 }
-function isPlainObject(value) {
+function isPlainObject$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
@@ -3011,4 +3457,4 @@ function InputForm(formType, validatorOpts) {
 */
 const perRow = (fn) => (rows) => rows.map(fn);
 //#endregion
-export { ActionDisabledError, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DEFAULT_DB_SPACE, DbAction, DbActionDefault, DbActionID, DbActionIDs, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, assertExposed, clearDbSpaces, dbActionBodySlot, dbActionInputSlot, discoverActions, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };
+export { ActionDisabledError, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DEFAULT_DB_SPACE, DbAction, DbActionDefault, DbActionID, DbActionIDs, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };