@atscript/moost-db 0.1.141 → 0.1.143

package/dist/index.mjs

@@ -3,11 +3,11 @@ 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 { ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, DbError, ENCRYPTED_REASON, acceptedOperatorsHint, aliasTargetOf, bucketSourceVerdict, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, collectQueryPaths as collectQueryPaths$1, findAncestorInSet, isJsonValueField, isPlainObject, narrowerFilterOps, normalizeComputedSelect, reconcileCas, unsupportedOperatorMessage } from "@atscript/db";
-import { BUCKET_UNITS } from "@uniqu/core";
-import { buildMemoryPredicate, projectRow, sortRows } from "@atscript/db-memory";
+import { ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, DbError, ENCRYPTED_REASON, acceptedOperatorsHint, aliasTargetOf, bucketSourceVerdict, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, collectQueryPaths as collectQueryPaths$1, findAncestorInSet, geoIndexNotFoundMessage, isEmptyObject, isJsonValueField, isPlainObject, narrowerFilterOps, normalizeComputedSelect, reconcileCas, searchIndexNotFoundMessage, selfOrAncestor, unsupportedOperatorMessage, vectorIndexNotFoundMessage } from "@atscript/db";
 import { cached, current, defineWook, key } from "@wooksjs/event-core";
 import { useBody } from "@wooksjs/http-body";
+import { BUCKET_UNITS } from "@uniqu/core";
+import { buildMemoryPredicate, projectRow, sortRows } from "@atscript/db-memory";
 //#region src/http-errors.ts
 /**
 * The structured error envelope every `moost-db` rejection uses (since
@@ -33,6 +33,18 @@ function badRequest(path, message, top = message) {
 		message
 	}]);
 }
+/**
+* The 400 of a `$with` relation the request cannot reach — nonexistent, or
+* hidden by `hasField` (the two answer alike): `Unknown relation "<name>"`,
+* the envelope message listing `visible` (the relations the caller CAN
+* load at that level). The single source of this wording — a permission
+* layer that rejects a relation itself should throw this.
+*
+* @since 0.1.143
+*/
+function unknownRelationError(name, visible) {
+	return badRequest("$with", `Unknown relation "${name}"`, `Unknown relation "${name}" in $with. Available relations: ${visible.join(", ") || "(none)"}`);
+}
 //#endregion
 //#region src/validation-interceptor.ts
 const dbErrorCodeToStatus = {
@@ -76,6 +88,15 @@ var GetOneControlsDto = class {
 		throwFeatureDisabled("JSON Schema", "jsonSchema", "emit.jsonSchema");
 	}
 };
+var GeoControlsDto = class {
+	static __is_atscript_annotated_type = true;
+	static type = {};
+	static metadata = /* @__PURE__ */ new Map();
+	static id = "GeoControlsDto";
+	static toJsonSchema() {
+		throwFeatureDisabled("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
 var WithRelationDto = class {
 	static __is_atscript_annotated_type = true;
 	static type = {};
@@ -132,6 +153,15 @@ defineAnnotatedType("object", PagesControlsDto).prop("$page", defineAnnotatedTyp
 	message: "Expected positive number"
 }, true).optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$fuzzy", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$vector", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$threshold", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
 defineAnnotatedType("object", GetOneControlsDto).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
+defineAnnotatedType("object", GeoControlsDto).prop("$center", defineAnnotatedType("union").item(defineAnnotatedType().designType("string").tags("string").$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("number").tags("number").$type).$type).optional().$type).prop("$maxDistance", defineAnnotatedType().designType("number").tags("number").optional().$type).prop("$minDistance", defineAnnotatedType().designType("number").tags("number").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$page", defineAnnotatedType().designType("string").tags("string").annotate("expect.pattern", {
+	pattern: "^\\d+$",
+	flags: "u",
+	message: "Expected positive number"
+}, true).optional().$type).prop("$size", defineAnnotatedType().designType("string").tags("string").annotate("expect.pattern", {
+	pattern: "^\\d+$",
+	flags: "u",
+	message: "Expected positive number"
+}, true).optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
 defineAnnotatedType("object", WithRelationDto).prop("name", defineAnnotatedType().designType("string").tags("string").$type).prop("filter", defineAnnotatedType().refTo(WithFilterDto).optional().$type).prop("controls", defineAnnotatedType().refTo(WithRelationControlsDto).optional().$type).prop("insights", defineAnnotatedType().refTo(WithFilterDto).optional().$type);
 defineAnnotatedType("object", WithRelationControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type);
 defineAnnotatedType("object", WithFilterDto).propPattern(/./, defineAnnotatedType("union").item(defineAnnotatedType().designType("string").tags("string").$type).item(defineAnnotatedType().designType("number").tags("number").$type).item(defineAnnotatedType().designType("boolean").tags("boolean").$type).item(defineAnnotatedType().designType("null").tags("null").$type).item(defineAnnotatedType().refTo(WithFilterDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithFilterDto).$type).$type).$type);
@@ -162,6 +192,26 @@ function getAtscriptDbMate() {
 	return getMoostMate();
 }
 //#endregion
+//#region src/actions/keys.ts
+/** Log-message prefix for warnings emitted from the actions subsystem. */
+const WARN_PREFIX = "[moost-db actions]";
+/**
+* Shared method-decorator update used by `@DbAction` and `@DbActionDefault`:
+* read the existing `atscript_db_action` slot, merge the patch (later-applied
+* fields win), and write it back. `name` is empty until `@DbAction` provides
+* one — `discoverActions` warns and drops actions with no name.
+*/
+function mergeActionMeta(current, patch) {
+	const existing = current.atscript_db_action;
+	return {
+		name: patch.name ?? existing?.name ?? "",
+		opts: {
+			...existing?.opts,
+			...patch.opts
+		}
+	};
+}
+//#endregion
 //#region src/actions/controller-registry.ts
 let asDbReadableCtor = null;
 let asValueHelpCtor = null;
@@ -179,25 +229,33 @@ function isAsValueHelpControllerSubclass(ctor) {
 	if (!asValueHelpCtor) return false;
 	return asValueHelpCtor.prototype.isPrototypeOf(ctor.prototype);
 }
-//#endregion
-//#region src/actions/keys.ts
-/** Log-message prefix for warnings emitted from the actions subsystem. */
-const WARN_PREFIX = "[moost-db actions]";
+/** The error every `@DbAction*` on a value-help controller fails with (since 0.1.143). */
+function valueHelpActionError(ctorName, actions) {
+	return /* @__PURE__ */ new Error(`${WARN_PREFIX} ${ctorName} is a value-help controller — @DbAction / @DbActions are not supported there (found: ${actions.map((a) => `"${a}"`).join(", ")}). Move the action(s) to an AsDbReadableController / AsDbController.`);
+}
+const checkedValueHelp = /* @__PURE__ */ new WeakSet();
 /**
-* Shared method-decorator update used by `@DbAction` and `@DbActionDefault`:
-* read the existing `atscript_db_action` slot, merge the patch (later-applied
-* fields win), and write it back. `name` is empty until `@DbAction` provides
-* one — `discoverActions` warns and drops actions with no name.
+* Bind-time check for value-help controllers (since 0.1.143): throws when the
+* class — or anything it inherits — carries `@DbAction` / `@DbActions*`
+* metadata. The decorators throw on their own when applied to a value-help
+* subclass directly; this catches actions inherited from a non-value-help
+* base. Memoized per class.
 */
-function mergeActionMeta(current, patch) {
-	const existing = current.atscript_db_action;
-	return {
-		name: patch.name ?? existing?.name ?? "",
-		opts: {
-			...existing?.opts,
-			...patch.opts
+function assertNoValueHelpActions(ctor) {
+	if (checkedValueHelp.has(ctor)) return;
+	const mate = getAtscriptDbMate();
+	const found = /* @__PURE__ */ new Set();
+	for (let proto = ctor.prototype; proto && proto !== Object.prototype;) {
+		for (const entry of mate.read(proto.constructor)?.atscript_db_actions ?? []) found.add(entry.name);
+		for (const key of Object.getOwnPropertyNames(proto)) {
+			if (key === "constructor") continue;
+			const action = mate.read(proto, key)?.atscript_db_action;
+			if (action) found.add(action.name || key);
 		}
-	};
+		proto = Object.getPrototypeOf(proto);
+	}
+	if (found.size > 0) throw valueHelpActionError(ctor.name, [...found]);
+	checkedValueHelp.add(ctor);
 }
 //#endregion
 //#region src/actions/param-level.ts
@@ -740,9 +798,13 @@ let AsReadableController = class AsReadableController {
 	* `ref` (`field: ""`) and their bodies always expand fully regardless of
 	* `refDepth` — the write-payload shape clients need is unaffected.
 	*
-	* Annotation whitelist: keeps `meta.*`, `expect.*`, and `db.rel.*`; strips
-	* other `db.*` (table, column, index, default, etc.). Override in subclass
-	* to customise.
+	* Annotation whitelist: keeps `meta.*`, `expect.*`, `db.rel.*`, the `db.*`
+	* keys the shared db validator plugin reads in db-client (`db.json`,
+	* `db.patch.strategy`, `db.default*`, `db.column.version`,
+	* `db.column.derived`) and the client-facing `db.http.path` /
+	* `db.writeOnly`; strips every other `db.*` (table, column, index, etc.).
+	* Override in subclass to customise — keep the validator keys, or client
+	* preflight diverges from the server.
 	*/
 	getSerializeOptions() {
 		return {
@@ -752,7 +814,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" || key === "db.column.version") return {
+				if (key === "db.json" || key === "db.patch.strategy" || key.startsWith("db.default") || key === "db.http.path" || key === "db.writeOnly" || key === "db.column.version" || key === "db.column.derived") return {
 					key,
 					value
 				};
@@ -767,6 +829,7 @@ let AsReadableController = class AsReadableController {
 	_queryControlsValidator;
 	_pagesControlsValidator;
 	_getOneControlsValidator;
+	_geoControlsValidator;
 	get queryControlsValidator() {
 		if (!this._queryControlsValidator) this._queryControlsValidator = QueryControlsDto.validator();
 		return this._queryControlsValidator;
@@ -779,9 +842,52 @@ let AsReadableController = class AsReadableController {
 		if (!this._getOneControlsValidator) this._getOneControlsValidator = GetOneControlsDto.validator();
 		return this._getOneControlsValidator;
 	}
+	/** `/geo` controls validator (since 0.1.143 — `/geo` runs {@link validateParsed} like `/query`). */
+	get geoControlsValidator() {
+		if (!this._geoControlsValidator) this._geoControlsValidator = GeoControlsDto.validator();
+		return this._geoControlsValidator;
+	}
+	async parseRequest(endpoint, url) {
+		let request;
+		if (url !== void 0) {
+			const { parsed, hasNonControl } = endpoint === "one" ? this.parseControlsOnlyFromUrl(url) : {
+				parsed: this.parseQueryString(url),
+				hasNonControl: false
+			};
+			const controls = parsed.controls;
+			if (typeof controls.$actions === "string") controls.$actions = controls.$actions === "true" || controls.$actions === "1" || controls.$actions === "";
+			request = {
+				parsed,
+				controls,
+				hasNonControl
+			};
+		}
+		if (typeof this.prepareRequest === "function") await this.prepareRequest(request ? {
+			endpoint,
+			controls: request.controls
+		} : { endpoint });
+		return request;
+	}
+	/**
+	* Validates the parsed controls against the endpoint's DTO — the hook for
+	* per-control authorization (override, call `super`, add rules). `"geo"`
+	* since 0.1.143 (`/geo` used to skip it).
+	*/
 	validateControls(controls, type) {
 		if (type === "query" && controls.$groupBy !== void 0) return;
-		const v = type === "query" ? this.queryControlsValidator : type === "pages" ? this.pagesControlsValidator : this.getOneControlsValidator;
+		let v;
+		switch (type) {
+			case "query":
+				v = this.queryControlsValidator;
+				break;
+			case "pages":
+				v = this.pagesControlsValidator;
+				break;
+			case "geo":
+				v = this.geoControlsValidator;
+				break;
+			default: v = this.getOneControlsValidator;
+		}
 		if (!v.validate(controls, true)) return v.errors[0]?.message || "Invalid controls";
 	}
 	validateInsights(insights) {
@@ -875,6 +981,19 @@ let AsReadableController = class AsReadableController {
 	* response by principal.
 	*/
 	async meta() {
+		await this.parseRequest("meta");
+		return this.resolveMeta();
+	}
+	/**
+	* The `/meta` payload for the current request — the cached envelope
+	* through {@link applyMetaOverlay} — WITHOUT the `/meta` route's
+	* {@link prepareRequest} call. Internal consumers (e.g. `$actions`
+	* filtering on a read) use this, so the hook runs once per request with
+	* the endpoint actually being served.
+	*
+	* @since 0.1.143
+	*/
+	resolveMeta() {
 		const key = this.metaCacheKey();
 		if (!this._metaResponse || key !== this._metaResponseKey) {
 			this._metaResponse = this.buildMetaResponse();
@@ -895,12 +1014,14 @@ let AsReadableController = class AsReadableController {
 	* compiled `.as` class's `.name`, registered when an action's parameter is
 	* decorated with `@InputForm(FormType)`. Schemas are serialized once and
 	* cached per controller; the response uses the same annotation-allowlist
-	* policy as {@link getSerializeOptions}.
+	* policy as {@link getSerializeOptions}. Since 0.1.143 the form must pass
+	* {@link authorizeForm} — a refused form answers exactly like an unknown one.
 	*/
 	async metaForm(name) {
-		discoverActions(this.constructor, this.app, this.logger);
+		await this.parseRequest("metaForm");
+		const envelopes = discoverActions(this.constructor, this.app, this.logger);
 		const formType = getControllerFormType(this.constructor, name);
-		if (!formType) throw new HttpError(404, `Unknown form "${name}"`);
+		if (!formType || !await this.authorizeForm(name, envelopes.filter((e) => e.info.inputForm === name).map((e) => e.info.name))) throw new HttpError(404, `Unknown form "${name}"`);
 		let cached = this._formSchemas.get(name);
 		if (!cached) {
 			cached = this.serializeForMeta(formType);
@@ -909,6 +1030,18 @@ let AsReadableController = class AsReadableController {
 		return cached;
 	}
 	/**
+	* Per-request gate for `GET /meta/form/:name`: return `false` to refuse the
+	* form — the response is then the same 404 an unknown form gets, so a
+	* refused form's existence does not leak. `actionNames` are the discovered
+	* actions whose input form is `name` (a permission layer typically allows
+	* the form iff the caller may run at least one of them). Default: `true`.
+	*
+	* @since 0.1.143
+	*/
+	authorizeForm(_name, _actionNames) {
+		return true;
+	}
+	/**
 	* Builds the `/meta` payload. Override in subclasses to populate source-specific
 	* fields. Subclasses that fully replace the envelope must call
 	* {@link buildActions} and {@link buildCrud} directly so `@DbAction*`
@@ -1064,67 +1197,346 @@ function augmentRowsWithActions(args) {
 	return rows;
 }
 //#endregion
-//#region src/decorators.ts
+//#region src/actions/current-action.ts
+/** Read the current action's `TDbActionMeta` from the wook context. Returns undefined outside a controller (e.g. direct-wook test paths). */
+function readCurrentActionMeta(ctx) {
+	let ctrl;
+	let methodName;
+	try {
+		const cc = useControllerContext(ctx);
+		ctrl = cc.getController();
+		methodName = cc.getMethod();
+	} catch {
+		return;
+	}
+	if (!ctrl || !methodName) return void 0;
+	return getAtscriptDbMate().read(ctrl.constructor, methodName)?.atscript_db_action;
+}
+//#endregion
+//#region src/actions/input-form-cache.ts
 /**
-* DI token under which the {@link AtscriptDbReadable} instance
-* is exposed to the readable controller's constructor via `@Inject`.
+* Cached parse of the action request body. Centralises the shape check so
+* every per-param resolver (`@DbActionID*`, `@DbActionRow*`, `@InputForm`)
+* reads through the same gate. An array or scalar root is rejected with the
+* same `ValidatorError` envelope as today's strict-shape ID failures.
 */
-const READABLE_DEF = "__atscript_db_readable_def";
+const dbActionBodySlot = cached(async (ctx) => {
+	const raw = await useBody(ctx).parseBody();
+	if (raw == null) return {};
+	if (typeof raw !== "object" || Array.isArray(raw)) throw new ValidatorError([{
+		path: "",
+		message: "Action body must be an object of shape { ids?, input? }"
+	}]);
+	return raw;
+});
+/** Cached `body.input` slot — consumed by `@InputForm()` and `useDbActionInput()`. */
+const dbActionInputSlot = cached(async (ctx) => {
+	return (await ctx.get(dbActionBodySlot)).input;
+});
+/** Composable for in-handler reads of the form input. */
+const useDbActionInput = defineWook((ctx) => ({ load: () => ctx.get(dbActionInputSlot) }));
+//#endregion
+//#region src/actions/prepare-request.ts
 /**
-* DI token under which the {@link AtscriptDbTable} instance
-* is exposed to the controller's constructor via `@Inject`.
-* Points to the same token as READABLE_DEF for backward compatibility.
+* The controller's `prepareRequest({ endpoint: "action", action })` for this
+* `@DbAction` event (since 0.1.143) — started once per event, before the
+* action's ids are validated, its rows loaded or its row overlay built (each
+* of those awaits it first). `undefined` when the controller defines no
+* `prepareRequest` (nothing to await) or outside an action handler.
 */
-const TABLE_DEF = READABLE_DEF;
-function normalizeOptions(prefixOrOptions) {
-	if (typeof prefixOrOptions === "string") return { prefix: prefixOrOptions };
-	return prefixOrOptions ?? {};
+const dbActionPreparedSlot = cached((ctx) => {
+	let ctrl;
+	try {
+		ctrl = useControllerContext(ctx).getController();
+	} catch {
+		return;
+	}
+	const prepare = ctrl?.prepareRequest;
+	if (typeof prepare !== "function") return void 0;
+	const action = readCurrentActionMeta(ctx)?.name;
+	if (action === void 0) return void 0;
+	return (async () => prepare.call(ctrl, {
+		endpoint: "action",
+		action
+	}))();
+});
+/** Awaits the controller's `prepareRequest` for this action event (no-op without one). */
+async function awaitActionPrepared(ctx) {
+	const pending = ctx.get(dbActionPreparedSlot);
+	if (pending) await pending;
 }
+/** Same priority as the action gate: after the guards (auth) ran, before argument resolution. */
+const ACTION_GATE_PRIORITY = TInterceptorPriority.AFTER_GUARD;
 /**
-* Builds the shared binding metadata for a decorator invocation: classifies
-* the binding form, computes the static route prefix, and packages a uniform
-* `resolve()` used by both the DI provide factory and the base controller's
-* `super(app)` fallback.
+* Interceptor for `'table'`-level actions of an `AsReadableController`
+* subclass (the gate / thin interceptor cover `'row'` / `'rows'`): runs the
+* controller's `prepareRequest` before the handler. No `prepareRequest` →
+* returns without awaiting.
 */
-function buildBinding(binding, options, decoratorName) {
-	if (isAnnotatedType(binding)) {
-		const model = binding;
-		const space = options.space ?? model.metadata.get("db.space");
-		const prefix = options.prefix || model.metadata.get("db.http.path") || model.metadata.get("db.table") || model.metadata.get("db.view") || model.id || "";
-		if (!prefix) throw new Error(`[moost-db] @${decoratorName}: cannot derive a route prefix from the model token (no @db.http.path / @db.table / @db.view and no type id). Pass an explicit prefix.`);
-		return {
-			meta: {
-				model,
-				resolve: () => resolveDbSpace(space).get(model)
-			},
-			prefix
-		};
-	}
-	if (typeof binding === "function") {
-		if (!options.prefix) throw new Error(`[moost-db] @${decoratorName}: the lazy factory form needs an explicit route prefix (the readable is not created until app.init()). Pass a prefix, or use the model token form which derives it from @db.http.path / @db.table.`);
-		return {
-			meta: { resolve: binding },
-			prefix: options.prefix
-		};
+const actionPrepareInterceptor = defineBeforeInterceptor(() => current().get(dbActionPreparedSlot), ACTION_GATE_PRIORITY);
+//#endregion
+//#region src/actions/id-validation.ts
+const SOURCE_CACHE = /* @__PURE__ */ new WeakMap();
+function getSourceCache(source) {
+	let cache = SOURCE_CACHE.get(source);
+	if (cache) return cache;
+	const identifications = source.identifications;
+	const byKeySig = /* @__PURE__ */ new Map();
+	for (const ident of identifications) byKeySig.set(fieldsSig(ident.fields), ident);
+	const fieldByName = /* @__PURE__ */ new Map();
+	for (const fd of source.fieldDescriptors) fieldByName.set(fd.path, fd);
+	cache = {
+		byKeySig,
+		fieldByName,
+		formatted: identifications.map((id) => `[${id.fields.join(", ")}]`).join(", ")
+	};
+	SOURCE_CACHE.set(source, cache);
+	return cache;
+}
+function fieldsSig(fields) {
+	return fields.toSorted().join("");
+}
+function isIdValidationSource(value) {
+	if (!value || typeof value !== "object") return false;
+	const v = value;
+	return Array.isArray(v.identifications) && Array.isArray(v.fieldDescriptors);
+}
+function validateSingleId(body, source, path = "") {
+	const errors = collectIdErrors(body, source, path);
+	if (errors.length > 0) throw new ValidatorError(errors);
+	return body;
+}
+/** `maxIds`: an array longer than it is rejected (400) before any per-id work. */
+function validateMultiId(body, source, maxIds = Infinity) {
+	if (!Array.isArray(body)) throw new ValidatorError([{
+		path: "",
+		message: "Expected JSON array of identifier objects",
+		details: []
+	}]);
+	if (body.length > maxIds) throw new ValidatorError([{
+		path: "",
+		message: `Too many identifiers: ${body.length} (at most ${maxIds} per request)`,
+		details: []
+	}]);
+	const errors = [];
+	for (let i = 0; i < body.length; i++) errors.push(...collectIdErrors(body[i], source, `[${i}]`));
+	if (errors.length > 0) throw new ValidatorError(errors);
+	return body;
+}
+function collectIdErrors(value, source, pathPrefix) {
+	if (!isPlainObject$1(value)) return [{
+		path: pathPrefix,
+		message: "Expected JSON object for row identifier",
+		details: []
+	}];
+	const cache = getSourceCache(source);
+	if (cache.byKeySig.size === 0) return [{
+		path: pathPrefix,
+		message: "Table has no identifier configured",
+		details: []
+	}];
+	const match = cache.byKeySig.get(fieldsSig(Object.keys(value)));
+	if (!match) return [{
+		path: pathPrefix,
+		message: `Identifier fields must exactly match one of: ${cache.formatted}`,
+		details: []
+	}];
+	const errors = [];
+	for (const fieldName of match.fields) {
+		const sub = pathPrefix ? `${pathPrefix}.${fieldName}` : fieldName;
+		const err = checkScalar(value[fieldName], cache.fieldByName.get(fieldName), sub);
+		if (err) errors.push(err);
 	}
-	const readable = binding;
-	const prefix = options.prefix || readable.type.metadata.get("db.http.path") || readable.tableName;
+	return errors;
+}
+function checkScalar(value, fd, path) {
+	const expected = fd?.designType ?? "string";
+	if (typeof value === "object" && value !== null) return scalarMismatch(path, "a scalar", value);
+	if (expected === "string" && typeof value !== "string") return scalarMismatch(path, expected, value);
+	if (expected === "number" && typeof value !== "number") return scalarMismatch(path, expected, value);
+	if (expected === "boolean" && typeof value !== "boolean") return scalarMismatch(path, expected, value);
+}
+function scalarMismatch(path, expected, value) {
 	return {
-		meta: {
-			model: readable.type,
-			resolve: () => readable
-		},
-		prefix
+		path,
+		message: `Expected identifier value to be ${expected}, got ${describe(value)}`,
+		details: []
 	};
 }
-function bindReadableController(binding, prefixOrOptions, decoratorName) {
-	const { meta, prefix } = buildBinding(binding, normalizeOptions(prefixOrOptions), decoratorName);
-	return ApplyDecorators(getAtscriptDbMate().decorate((classMeta) => {
-		classMeta.atscript_db_readable_binding = meta;
-		return classMeta;
-	}), Provide(READABLE_DEF, () => meta.resolve()), Controller(prefix), Inherit());
+function describe(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
 }
-/**
+function isPlainObject$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/actions/id-cache.ts
+const boundTableKey = key("atscript_db_action_bound_table");
+function controllerOf(ctx) {
+	return useControllerContext(ctx).getController();
+}
+function controllerTable(ctx) {
+	const ctrl = controllerOf(ctx);
+	return ctrl?.readable ?? ctrl?.table ?? null;
+}
+function getActionTable(ctx) {
+	return (ctx.has(boundTableKey) ? ctx.get(boundTableKey) : void 0) ?? controllerTable(ctx);
+}
+const warnedTags = /* @__PURE__ */ new Set();
+function noTableError(ctx) {
+	const actionName = readCurrentActionMeta(ctx)?.name;
+	const tag = actionName ? `"${actionName}"` : "<unknown>";
+	if (!warnedTags.has(tag)) {
+		warnedTags.add(tag);
+		console.warn(`${WARN_PREFIX} ${tag}: controller has no readable/table property and the action declares no opts.table. Either expose readable/table on the controller, extend AsDbReadableController, or pass opts.table on @DbAction.`);
+	}
+	return new HttpError(500, {
+		statusCode: 500,
+		error: "Internal Server Error",
+		message: "Internal server error",
+		code: "ACTION_TABLE_NOT_BOUND"
+	});
+}
+/**
+* Validates the body's `ids` against the action table's identifications. For
+* the controller's own table that is its `idSource` (since 0.1.134): a unique
+* index over a field `hasField` hides neither addresses a row nor appears in
+* the "must exactly match one of" message. An `opts.table` binding has no
+* visibility hook. The controller's `prepareRequest` (since 0.1.143) runs
+* first, so the visibility the ids are validated against is the request's.
+*/
+async function resolveValidatedId(ctx, validate) {
+	await awaitActionPrepared(ctx);
+	let source = ctx.has(boundTableKey) ? ctx.get(boundTableKey) : void 0;
+	if (!source) {
+		const ctrl = controllerOf(ctx);
+		source = ctrl?.idSource ?? ctrl?.readable ?? ctrl?.table ?? null;
+	}
+	if (!isIdValidationSource(source)) throw noTableError(ctx);
+	const env = await ctx.get(dbActionBodySlot);
+	validate(env.ids, source);
+	return env.ids;
+}
+const dbActionIdSlot = cached((ctx) => resolveValidatedId(ctx, validateSingleId));
+/** Default cap on the identifiers one `'rows'`-level request may carry — see `DbActionOpts.maxIds`. */
+const DEFAULT_MAX_ACTION_IDS = 1e3;
+function maxIdsOf(ctx) {
+	const max = (readCurrentActionMeta(ctx)?.opts)?.maxIds;
+	return typeof max === "number" && Number.isInteger(max) && max > 0 ? max : DEFAULT_MAX_ACTION_IDS;
+}
+const dbActionIdsSlot = cached(async (ctx) => {
+	return await resolveValidatedId(ctx, (body, src) => validateMultiId(body, src, maxIdsOf(ctx)));
+});
+const useDbActionId = defineWook((ctx) => ({ load: () => ctx.get(dbActionIdSlot) }));
+const useDbActionIds = defineWook((ctx) => ({ load: () => ctx.get(dbActionIdsSlot) }));
+//#endregion
+//#region src/actions/row-scope.ts
+/**
+* The controller whose hooks govern this action's rows: only when the action
+* runs against the controller's OWN readable — an `opts.table` binding on a
+* plain controller has no row overlay or visibility hook. Once per event.
+*/
+const scopedControllerSlot = cached((ctx) => {
+	let ctrl;
+	try {
+		ctrl = controllerOf(ctx);
+	} catch {
+		return null;
+	}
+	const table = controllerTable(ctx);
+	if (!ctrl || table == null || getActionTable(ctx) !== table) return null;
+	return ctrl;
+});
+/**
+* The controller's row overlay for action ids / rows — its `rowOverlay()`,
+* the same overlay `/one/:id` ANDs in (no hook call, no extra query when the
+* controller overrides neither `transformOne` nor `transformFilter`), `null`
+* when there is none. Evaluated once per request, after the controller's
+* `prepareRequest` (since 0.1.143).
+*/
+const dbActionOverlaySlot = cached(async (ctx) => {
+	const ctrl = ctx.get(scopedControllerSlot);
+	if (!ctrl?.rowOverlay) return null;
+	await awaitActionPrepared(ctx);
+	return await ctrl.rowOverlay() ?? null;
+});
+/** `filter` AND the overlay (identity without one). */
+function withOverlay(filter, overlay) {
+	return overlay ? { $and: [filter, overlay] } : filter;
+}
+/**
+* The controller's field visibility when request-scoped (`hasField`
+* overridden), else `undefined` — `requiredFields` it hides (a derived field
+* over a hidden source included) are never selected.
+*/
+function actionFieldVisibility(ctx) {
+	const visibility = ctx.get(scopedControllerSlot)?.fieldVisibility;
+	return visibility?.scoped ? visibility.isVisible : void 0;
+}
+//#endregion
+//#region src/decorators.ts
+/**
+* DI token under which the {@link AtscriptDbReadable} instance
+* is exposed to the readable controller's constructor via `@Inject`.
+*/
+const READABLE_DEF = "__atscript_db_readable_def";
+/**
+* DI token under which the {@link AtscriptDbTable} instance
+* is exposed to the controller's constructor via `@Inject`.
+* Points to the same token as READABLE_DEF for backward compatibility.
+*/
+const TABLE_DEF = READABLE_DEF;
+function normalizeOptions(prefixOrOptions) {
+	if (typeof prefixOrOptions === "string") return { prefix: prefixOrOptions };
+	return prefixOrOptions ?? {};
+}
+/**
+* Builds the shared binding metadata for a decorator invocation: classifies
+* the binding form, computes the static route prefix, and packages a uniform
+* `resolve()` used by both the DI provide factory and the base controller's
+* `super(app)` fallback.
+*/
+function buildBinding(binding, options, decoratorName) {
+	if (isAnnotatedType(binding)) {
+		const model = binding;
+		const space = options.space ?? model.metadata.get("db.space");
+		const prefix = options.prefix || model.metadata.get("db.http.path") || model.metadata.get("db.table") || model.metadata.get("db.view") || model.id || "";
+		if (!prefix) throw new Error(`[moost-db] @${decoratorName}: cannot derive a route prefix from the model token (no @db.http.path / @db.table / @db.view and no type id). Pass an explicit prefix.`);
+		return {
+			meta: {
+				model,
+				resolve: () => resolveDbSpace(space).get(model)
+			},
+			prefix
+		};
+	}
+	if (typeof binding === "function") {
+		if (!options.prefix) throw new Error(`[moost-db] @${decoratorName}: the lazy factory form needs an explicit route prefix (the readable is not created until app.init()). Pass a prefix, or use the model token form which derives it from @db.http.path / @db.table.`);
+		return {
+			meta: { resolve: binding },
+			prefix: options.prefix
+		};
+	}
+	const readable = binding;
+	const prefix = options.prefix || readable.type.metadata.get("db.http.path") || readable.tableName;
+	return {
+		meta: {
+			model: readable.type,
+			resolve: () => readable
+		},
+		prefix
+	};
+}
+function bindReadableController(binding, prefixOrOptions, decoratorName) {
+	const { meta, prefix } = buildBinding(binding, normalizeOptions(prefixOrOptions), decoratorName);
+	return ApplyDecorators(getAtscriptDbMate().decorate((classMeta) => {
+		classMeta.atscript_db_readable_binding = meta;
+		return classMeta;
+	}), Provide(READABLE_DEF, () => meta.resolve()), Controller(prefix), Inherit());
+}
+/**
 * Combines the boilerplate needed to turn an {@link AsDbController}
 * subclass into a fully wired HTTP controller for a given `@db.table` model.
 *
@@ -1238,6 +1650,17 @@ const OP_VERB = {
 	aggregate: "aggregate over",
 	bucket: "bucket"
 };
+/**
+* The verdict of a filter / sort on a `@db.writeOnly` path — the same
+* sentence {@link FieldCapabilityIndex.check} answers for this table's own
+* fields; used for `$with` sub-queries on a joined table's.
+*/
+function writeOnlyVerdict(path, op) {
+	return {
+		path,
+		message: `${OP_SUBJECT[op]} field "${path}" is not permitted — ${REASON_WRITE_ONLY}`
+	};
+}
 /** The one "nonexistent path" verdict — hidden paths answer with it byte for byte. */
 function unknownField(path) {
 	return {
@@ -1332,7 +1755,7 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 		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 isNavOrDescendant = (path) => selfOrAncestor(path, nav) !== void 0;
 		const flatMap = source.flatMap;
 		const annotated = (fd, key) => {
 			const fromFlat = flatMap.get(fd.path)?.metadata?.has?.(key);
@@ -1360,7 +1783,7 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 			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;
+			if (selfOrAncestor(path, encrypted) !== void 0) continue;
 			this._objectParents.set(path, []);
 		}
 		for (const [parent, leaves] of this._objectParents) {
@@ -1532,23 +1955,14 @@ const QUERY_CONTROLS = [
 const PAGES_CONTROLS = ["filter", ...dtoControls(PagesControlsDto)];
 const ONE_CONTROLS = dtoControls(GetOneControlsDto);
 /**
-* Controls accepted by the `/geo` endpoint. No backing DTO — `$center` /
-* `$maxDistance` / `$minDistance` are parsed and validated by the handler.
+* Controls accepted by the `/geo` endpoint — `GeoControlsDto` (since 0.1.143;
+* `$center` / `$maxDistance` / `$minDistance` are parsed by the handler
+* before the DTO check) plus the URL-grammar `filter` / `insights`.
 */
 const GEO_CONTROLS = [
 	"filter",
 	"insights",
-	"center",
-	"maxDistance",
-	"minDistance",
-	"index",
-	"select",
-	"skip",
-	"limit",
-	"page",
-	"size",
-	"with",
-	"actions"
+	...dtoControls(GeoControlsDto)
 ];
 //#endregion
 //#region src/as-db-readable.controller.ts
@@ -1562,6 +1976,11 @@ const PATH_OPS = [
 	"aggregate",
 	"bucket"
 ];
+/** The 400 of a filter / sort on a `@db.writeOnly` field. */
+function writeOnlyError(path, op) {
+	const verdict = writeOnlyVerdict(path, op);
+	return badRequest(verdict.path, verdict.message);
+}
 let AsDbReadableController = _AsDbReadableController = class AsDbReadableController extends AsReadableController {
 	/** Reference to the underlying readable (table or view). */
 	readable;
@@ -1600,13 +2019,31 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	metaCacheKey() {
 		return this.capabilities;
 	}
-	/** Bound once: the visibility check ({@link hasField}) the gate hands to `capabilities.check`. */
-	_exists = (path) => this.hasField(path);
 	/**
-	* Id-resolution options (since 0.1.134): `{ isFieldVisible: hasField }`
-	* when a subclass overrides {@link hasField}, else `undefined` (the default
-	* accepts every real path, so resolution stays unfiltered). A unique index
-	* over a hidden field is never an identification.
+	* THE field-visibility answer (since 0.1.143) every read surface consults:
+	* the capability gate, the index gate and `$search` fallback, id
+	* resolution, the `@db.writeOnly` / derived seals of the projection and of
+	* every `$with` level, `$actions` widening and action `requiredFields`
+	* (the actions module reaches it duck-typed, like {@link idSource}).
+	*/
+	fieldVisibility;
+	/** A subclass overrides {@link hasField}: visibility is request-scoped (derived rule, index gate, id options). */
+	_hasFieldOverridden;
+	/** `@db.column.derived` path → its source's logical path, per readable (bound + `$with` targets). */
+	_derivedSources = /* @__PURE__ */ new WeakMap();
+	/** The bound readable's entry of {@link _derivedSources}. */
+	_derivedSource;
+	/** `@db.writeOnly` paths of `$with` target readables, collected once per target. */
+	_targetWriteOnly = /* @__PURE__ */ new WeakMap();
+	_indexFieldPathsCache;
+	/** {@link _nativeSearch} per request, keyed by the request's parsed controls. */
+	_nativeSearchByRequest = /* @__PURE__ */ new WeakMap();
+	/**
+	* Id-resolution options (since 0.1.134): `{ isFieldVisible }` (the
+	* {@link fieldVisibility} check) when a subclass overrides {@link hasField},
+	* else `undefined` (the default accepts every real path, so resolution
+	* stays unfiltered). A unique index over a hidden field is never an
+	* identification.
 	*/
 	_idOpts;
 	/** Narrowed id sources, one stable object per distinct visible-identification set. */
@@ -1615,6 +2052,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	_overlayIsNoOp;
 	/** `true` when a subclass implements {@link decorateRows} (the override switches the hook on). */
 	_decorates;
+	/** `true` when a subclass overrides {@link transformOne} or {@link transformFilter} (a row overlay may exist). */
+	_hasRowOverlay;
 	/** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
 	_quantityRefByPath;
 	/** `@db.column.searchable` paths — the `$search` fallback when the adapter has no native search. */
@@ -1632,6 +2071,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		super(resolved.type, resolved.tableName, app, resolved.isView ? "view" : "table");
 		this.readable = resolved;
 		this._writeOnlySet = this._collectAnnotated("db.writeOnly");
+		this._derivedSource = this._derivedSourcesOf(resolved);
 		this._invertibleFields = this._collectInvertibleFields();
 		this._searchFallbackFields = this._collectSearchFallbackFields();
 		this._preferredIdSet = new Set(resolved.preferredId ?? []);
@@ -1639,7 +2079,21 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		const defaultOverlay = AsReadableController.prototype.applyMetaOverlay;
 		this._overlayIsNoOp = this.applyMetaOverlay === defaultOverlay;
 		this._decorates = typeof this.decorateRows === "function";
-		this._idOpts = this.hasField === _AsDbReadableController.prototype.hasField ? void 0 : { isFieldVisible: this._exists };
+		const proto = _AsDbReadableController.prototype;
+		this._hasRowOverlay = this.transformOne !== proto.transformOne || this.transformFilter !== proto.transformFilter;
+		const scoped = this.hasField !== proto.hasField;
+		this._hasFieldOverridden = scoped;
+		const isVisible = (path) => {
+			if (!this.hasField(path)) return false;
+			const source = scoped ? this._derivedSource.get(path) : void 0;
+			return source === void 0 || this.hasField(source);
+		};
+		this.fieldVisibility = {
+			scoped,
+			isVisible,
+			sealedFor: (readable, prefix = "") => this._sealedFor(readable, prefix)
+		};
+		this._idOpts = scoped ? { isFieldVisible: isVisible } : void 0;
 	}
 	/**
 	* The identifications this request may address rows through (since
@@ -1668,7 +2122,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		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;
+			if (selfOrAncestor(fd.path, nav) !== void 0) continue;
 			out.push(fd.path);
 		}
 		return out;
@@ -1683,6 +2137,17 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		}
 		return out;
 	}
+	/** `readable`'s `@db.column.derived` path → source path map, collected once per readable. */
+	_derivedSourcesOf(readable) {
+		let map = this._derivedSources.get(readable);
+		if (!map) {
+			const out = /* @__PURE__ */ new Map();
+			for (const fd of readable.fieldDescriptors ?? []) if (fd.derived?.sourcePath) out.set(fd.path, fd.derived.sourcePath);
+			map = out;
+			this._derivedSources.set(readable, map);
+		}
+		return map;
+	}
 	_collectAnnotated(annotation) {
 		const out = /* @__PURE__ */ new Set();
 		for (const [path, entry] of this.readable.flatMap) if (entry?.metadata?.has?.(annotation)) out.add(path);
@@ -1702,9 +2167,18 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* an action id (primary key and `preferredId` always are) — and the
 	* nested-object 400 hint lists visible leaves only. The default accepts every real path
 	* (`isValidFieldPath`). `/meta` does NOT consult it — prune hidden fields
-	* there with `applyMetaOverlay`. Native text search and vector search
-	* (`$vector` names an index) run inside the engine over its indexes, out of
-	* this hook's reach — keep hidden fields out of those indexes.
+	* there with `applyMetaOverlay` ({@link indexFieldPaths} names what each
+	* search / geo index reads).
+	*
+	* Since 0.1.143 an override also gates the engine's indexes: a native
+	* text-search index (`$index`, or the default one), a vector index
+	* (`$vector`) or a geo index (`/geo`, `$index`) reading a hidden path
+	* answers exactly like a nonexistent index (400); a hidden DEFAULT text
+	* index falls back to the `@db.column.searchable` substring search over
+	* visible fields (or ignores the term when there are none). A
+	* `@db.column.derived` field is visible only while its source path is,
+	* and one whose source is hidden is sealed out of every read projection
+	* for the request, like a `@db.writeOnly` field.
 	*/
 	hasField(path) {
 		if (typeof this.readable.isValidFieldPath === "function") return this.readable.isValidFieldPath(path);
@@ -1725,23 +2199,26 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* ran first); a bucket's source is checked like any other path (op
 	* `bucket`). 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.
+	* and a real table answer alike. Last (since 0.1.143, when {@link hasField}
+	* is overridden) the index gate: a text / vector / geo index the request
+	* uses must read only visible paths — see {@link indexFieldPaths}.
 	*/
 	checkCapabilities(parsed) {
 		const capabilities = this.capabilities;
+		const isVisible = this.fieldVisibility.isVisible;
 		const refs = collectQueryPaths$1(parsed);
 		if (refs.unsupportedOperator !== void 0) return badRequest(refs.unsupportedOperator, unsupportedOperatorMessage(refs.unsupportedOperator));
 		for (const { path, predicate } of refs.filter) {
-			const verdict = capabilities.check(path, "filter", this._exists, predicate);
+			const verdict = capabilities.check(path, "filter", isVisible, predicate);
 			if (verdict) return badRequest(verdict.path, verdict.message);
 		}
 		for (const op of PATH_OPS) for (const path of refs[op]) {
-			const verdict = capabilities.check(path, op, this._exists);
+			const verdict = capabilities.check(path, op, isVisible);
 			if (verdict) return badRequest(verdict.path, verdict.message);
 		}
 		const having = checkHavingKeys(refs);
 		if (having) return badRequest(having.path, having.message);
-		return this.checkGates(parsed);
+		return this.checkGates(parsed) ?? this._checkIndexGate(parsed.controls ?? {});
 	}
 	/**
 	* The core's shared normalizer of `$select` computed entries
@@ -1784,22 +2261,278 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			if (!this.hasField(key)) return `Unknown field "${key}"`;
 		}
 	}
-	/** {@link checkComputedSelect} (before the controls DTO), then $with relations against the readable. */
+	/**
+	* {@link checkComputedSelect} (before the controls DTO), the controls DTO
+	* ({@link validateControls}), then the `$with` relation names at every
+	* level — BEFORE the `$with` sub-query paths ({@link validateInsights}),
+	* so a hidden or nonexistent nested relation answers `Unknown relation`,
+	* never `Unknown field "rel.sub"` (since 0.1.143) — then the insights and
+	* the joined-row write-only veto.
+	*/
 	validateParsed(parsed, type) {
 		const computedError = this.checkComputedSelect(parsed.controls);
 		if (computedError) return computedError;
-		const baseError = super.validateParsed(parsed, type);
-		if (baseError) return baseError;
-		const withRelations = parsed.controls.$with;
+		const controls = parsed.controls;
+		const controlsError = this.validateControls(controls, type);
+		if (controlsError) return new HttpError(400, controlsError);
+		const withRelations = controls.$with;
+		const unknown = withRelations?.length ? this._checkWithRelations(withRelations, this.readable, "") : void 0;
+		if (unknown) return unknown;
+		if (parsed.insights) {
+			const insightsError = this.validateInsights(parsed.insights);
+			if (insightsError) return new HttpError(400, insightsError);
+		}
 		if (withRelations?.length) {
-			const relations = this.readable.relations;
-			for (const rel of withRelations) {
-				const dot = rel.name.indexOf(".");
-				if (!(dot === -1 ? relations.has(rel.name) && this.hasField(rel.name) : this.hasField(rel.name.slice(0, dot)))) {
-					const visible = [...relations.keys()].filter((name) => this.hasField(name));
-					return badRequest("$with", `Unknown relation "${rel.name}"`, `Unknown relation "${rel.name}" in $with. Available relations: ${visible.join(", ") || "(none)"}`);
+			const vetoed = this._walkWith(withRelations, this.readable, "", (rel, target, path, nested) => {
+				const sealed = this._writeOnlyOf(target);
+				if (sealed.size === 0) return void 0;
+				const refs = collectQueryPaths$1({
+					filter: rel.filter,
+					controls: { $sort: nested.$sort ?? rel.$sort }
+				});
+				const filtered = refs.filter.find((ref) => selfOrAncestor(ref.path, sealed) !== void 0)?.path;
+				if (filtered !== void 0) return writeOnlyError(`${path}.${filtered}`, "filter");
+				const sorted = refs.sort.find((p) => selfOrAncestor(p, sealed) !== void 0);
+				return sorted === void 0 ? void 0 : writeOnlyError(`${path}.${sorted}`, "sort");
+			});
+			if (vetoed instanceof HttpError) return vetoed;
+		}
+	}
+	/**
+	* `$with` relation names at every level (nested `$with` since 0.1.143):
+	* each segment of an entry's (dotted) name must be a relation of its
+	* level's readable that {@link hasField} accepts at its full path from
+	* this controller (`rel`, then `rel.sub` for a nested / dotted one) —
+	* hidden answers exactly like nonexistent: {@link unknownRelationError}
+	* with the entry's name and the relations visible at the level it failed
+	* at. A level whose target readable cannot be resolved is not descended.
+	*/
+	_checkWithRelations(withRels, readable, prefix) {
+		if (!Array.isArray(withRels)) return void 0;
+		for (const rel of withRels) {
+			if (typeof rel?.name !== "string") continue;
+			let level = readable;
+			let path = prefix;
+			for (const segment of rel.name.split(".")) {
+				if (!level) break;
+				const relations = level.relations ?? /* @__PURE__ */ new Map();
+				if (!relations.has(segment) || !this.hasField(path + segment)) {
+					const visible = [...relations.keys()].filter((name) => this.hasField(path + name));
+					return unknownRelationError(rel.name, visible);
 				}
+				path += `${segment}.`;
+				level = typeof level.relatedTable === "function" ? level.relatedTable(segment) : void 0;
 			}
+			if (!level) continue;
+			const nested = this._checkWithRelations(rel.controls?.$with ?? rel.$with, level, path);
+			if (nested) return nested;
+		}
+	}
+	/**
+	* `@db.writeOnly` paths of a `$with` target — its own fields only (its
+	* navigation descendants are sealed one level down, by their own target).
+	*/
+	_writeOnlyOf(readable) {
+		let set = this._targetWriteOnly.get(readable);
+		if (!set) {
+			const own = /* @__PURE__ */ new Set();
+			const nav = readable.navFields ?? /* @__PURE__ */ new Set();
+			for (const [path, entry] of readable.flatMap ?? []) {
+				if (!entry?.metadata?.has?.("db.writeOnly")) continue;
+				if (selfOrAncestor(path, nav) !== void 0) continue;
+				own.add(path);
+			}
+			set = own;
+			this._targetWriteOnly.set(readable, set);
+		}
+		return set;
+	}
+	/** {@link TDbFieldVisibility.sealedFor}. */
+	_sealedFor(readable, prefix) {
+		const writeOnly = readable === this.readable ? this._writeOnlySet : this._writeOnlyOf(readable);
+		if (!this._hasFieldOverridden) return writeOnly;
+		let out;
+		for (const [path, source] of this._derivedSourcesOf(readable)) {
+			if (writeOnly.has(path) || this.hasField(prefix + source)) continue;
+			(out ??= new Set(writeOnly)).add(path);
+		}
+		return out ?? writeOnly;
+	}
+	/** The readable a `$with` entry name (`rel` or dotted `rel.sub`) loads from, if resolvable. */
+	_relTarget(readable, name) {
+		let current = readable;
+		for (const segment of name.split(".")) {
+			if (typeof current?.relatedTable !== "function") return void 0;
+			current = current.relatedTable(segment);
+		}
+		return current;
+	}
+	/**
+	* Walks a `$with` tree pre-order: `visit(rel, target, path, controls)` for
+	* every entry whose target readable resolves (`path` = the entry's dotted
+	* path from this controller, `controls` = its sub-controls). The visitor
+	* returns replacement sub-controls, an `HttpError` to stop the walk (it is
+	* returned as-is), or `undefined` to keep the entry. Returns the rebuilt
+	* tree — the same array when nothing changed.
+	*/
+	_walkWith(withRels, readable, prefix, visit) {
+		if (!Array.isArray(withRels) || withRels.length === 0) return withRels;
+		let out;
+		for (let i = 0; i < withRels.length; i++) {
+			const rel = withRels[i];
+			const target = this._relTarget(readable, rel.name);
+			if (!target) continue;
+			const path = `${prefix}${rel.name}`;
+			const nested = rel.controls ?? {};
+			const visited = visit(rel, target, path, nested);
+			if (visited instanceof HttpError) return visited;
+			const children = nested.$with ?? rel.$with;
+			const walked = this._walkWith(children, target, `${path}.`, visit);
+			if (walked instanceof HttpError) return walked;
+			if (visited === void 0 && walked === children) continue;
+			const controls = { ...visited ?? nested };
+			if (walked !== void 0) controls.$with = walked;
+			out ??= [...withRels];
+			out[i] = {
+				...rel,
+				controls
+			};
+		}
+		return out ?? withRels;
+	}
+	/**
+	* The read controls with every level sealed — the root `$select` (`select`,
+	* the {@link transformProjection} result) and each `$with` entry's
+	* `$select` lose the paths {@link TDbFieldVisibility.sealedFor} names for
+	* their readable (an exclusion is forced when there is no projection), so
+	* sealed values never leave the database. Runs AFTER `transformProjection`
+	* so permission overlays compose: they see the wire `$select`, this
+	* guarantees the seal on whatever they return.
+	*/
+	_sealControls(controls, select) {
+		const vis = this.fieldVisibility;
+		const $with = this._walkWith(controls.$with, this.readable, "", (rel, target, path, nested) => {
+			const sealed = vis.sealedFor(target, `${path}.`);
+			if (sealed.size === 0) return void 0;
+			const sub = nested.$select ?? rel.$select;
+			return {
+				...nested,
+				$select: this._sealSelect(sub, sealed)
+			};
+		});
+		const out = {
+			...controls,
+			$select: this._sealSelect(select, vis.sealedFor(this.readable))
+		};
+		if ($with !== controls.$with) out.$with = $with;
+		return out;
+	}
+	/**
+	* The text / vector / geo indexes of the bound readable with the LOGICAL
+	* field paths each reads, and which one answers when a request names none.
+	* Text and vector entries are the adapter's `getSearchIndexes()` (the names
+	* `$index` / `$vector` address, their `fields` and `isDefault`; an entry
+	* without `fields` lists every field — fail-closed); geo entries are the
+	* `@db.index.geo` indexes. The request gate checks every listed path against
+	* {@link hasField} (only when `hasField` is overridden); permission
+	* overlays use it to prune `/meta` (`searchIndexes`, `searchable`,
+	* `vectorSearchable`, `geoSearchable`). Computed once. Override to describe
+	* an index the model cannot express.
+	*
+	* @since 0.1.143
+	*/
+	indexFieldPaths() {
+		return this._indexFieldPathsCache ??= [...this._searchIndexFieldPaths(), ...this._geoIndexFieldPaths()];
+	}
+	_searchIndexFieldPaths() {
+		const out = (typeof this.readable.getSearchIndexes === "function" ? this.readable.getSearchIndexes() : []).map((info) => ({
+			name: info.name,
+			type: info.type === "vector" ? "vector" : "text",
+			fields: info.fields ?? this._invertibleFields,
+			isDefault: info.isDefault === true
+		}));
+		for (const type of ["text", "vector"]) {
+			const ofType = out.filter((entry) => entry.type === type);
+			if (ofType.some((entry) => entry.isDefault)) continue;
+			const fallback = ofType.find((entry) => entry.name === "DEFAULT") ?? ofType[0];
+			if (fallback) fallback.isDefault = true;
+		}
+		return out;
+	}
+	/** `@db.index.geo` indexes — their fields carry physical names, mapped back to logical paths. */
+	_geoIndexFieldPaths() {
+		const readable = this.readable;
+		if (!(readable.indexes instanceof Map)) return [];
+		const logical = /* @__PURE__ */ new Map();
+		for (const fd of readable.fieldDescriptors) {
+			if (fd.ignored) continue;
+			const prev = logical.get(fd.physicalName);
+			if (prev === void 0 || this._derivedSource.has(prev)) logical.set(fd.physicalName, fd.path);
+		}
+		const out = [];
+		for (const index of readable.indexes.values()) {
+			if (index.type !== "geo") continue;
+			out.push({
+				name: index.name,
+				type: "geo",
+				fields: index.fields.map((field) => logical.get(field.name) ?? field.name),
+				isDefault: out.length === 0
+			});
+		}
+		return out;
+	}
+	/** Every path `entry` reads is visible to this request. */
+	_indexVisible(entry) {
+		return entry.fields.every(this.fieldVisibility.isVisible);
+	}
+	/**
+	* Native text search serves this request: the adapter searches natively
+	* and — under an overridden {@link hasField} — the default index (when the
+	* request names none) reads only visible fields. A named index is gated by
+	* {@link checkCapabilities}. Answered once per request (keyed by its
+	* parsed controls).
+	*/
+	_nativeSearch(controls) {
+		let native = this._nativeSearchByRequest.get(controls);
+		if (native === void 0) {
+			native = this._resolveNativeSearch(controls);
+			this._nativeSearchByRequest.set(controls, native);
+		}
+		return native;
+	}
+	_resolveNativeSearch(controls) {
+		if (!this.readable.isSearchable()) return false;
+		if (!this._hasFieldOverridden) return true;
+		if (typeof controls.$index === "string" && controls.$index) return true;
+		const def = this.indexFieldPaths().find((e) => e.type === "text" && e.isDefault);
+		return def === void 0 || this._indexVisible(def);
+	}
+	/**
+	* Index visibility gate (only when {@link hasField} is overridden), run by
+	* {@link checkCapabilities} on every read: the geo index `/geo` reads
+	* (`$index`, or the default one), the vector index `$vector` names (or the
+	* default one) and the text index `$index` names must read only visible
+	* paths; otherwise the request is answered exactly like one naming a
+	* nonexistent index (the core's wording).
+	*/
+	_checkIndexGate(controls) {
+		if (!this._hasFieldOverridden) return void 0;
+		const name = typeof controls.$index === "string" ? controls.$index : void 0;
+		if (controls.$center !== void 0) {
+			const geoIndexes = this.indexFieldPaths().filter((e) => e.type === "geo");
+			const entry = name === void 0 ? geoIndexes.find((e) => e.isDefault) : geoIndexes.find((e) => e.name === name);
+			if (entry && !this._indexVisible(entry)) return badRequest(name ?? "", geoIndexNotFoundMessage(this.readable.tableName, name));
+		}
+		if (!controls.$search) return void 0;
+		if (controls.$vector !== void 0) {
+			const vectorName = typeof controls.$vector === "string" ? controls.$vector : "";
+			const entry = this.indexFieldPaths().find((e) => e.type === "vector" && (vectorName ? e.name === vectorName : e.isDefault));
+			if (entry && this._indexVisible(entry)) return void 0;
+			return badRequest("$vector", vectorIndexNotFoundMessage(vectorName || void 0));
+		}
+		if (name && this.readable.isSearchable()) {
+			const entry = this.indexFieldPaths().find((e) => e.type === "text" && e.name === name);
+			if (!entry || !this._indexVisible(entry)) return badRequest("$index", searchIndexNotFoundMessage(name));
 		}
 	}
 	/**
@@ -1887,7 +2620,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	*/
 	_invertExclusion(excluded) {
 		return this._invertibleFields.filter((path) => {
-			if (excluded.has(path) || findAncestorInSet(path, excluded) !== void 0) return false;
+			if (selfOrAncestor(path, excluded) !== void 0) return false;
 			const prefix = `${path}.`;
 			for (const key of excluded) if (key.startsWith(prefix)) return false;
 			return true;
@@ -1933,11 +2666,6 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		}
 		return projection;
 	}
-	/** WHY: the URL parser only auto-coerces `$count`; every other boolean control reaches us as `"true"`/`"1"` and would fail DTO validation. */
-	_coerceActionsControl(controls) {
-		const v = controls.$actions;
-		if (typeof v === "string") controls.$actions = v === "true" || v === "1" || v === "";
-	}
 	/** Normalize a post-`widenPreferredIdProjection` $select into `string[] | null` (`null` = all fields). */
 	_resolveProjectionForAugmenter(select) {
 		if (select === void 0) return null;
@@ -1964,12 +2692,17 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		const rowLevelEnvelopes = discoverRowLevelActions(this.constructor, this.app, this.logger);
 		if (rowLevelEnvelopes.length === 0) return null;
 		if (this._overlayIsNoOp) return rowLevelEnvelopes;
-		const overlayMeta = await this.meta();
+		const overlayMeta = await this.resolveMeta();
 		const allowedNames = new Set(overlayMeta.actions.map((a) => a.name));
 		const filtered = rowLevelEnvelopes.filter((e) => allowedNames.has(e.info.name));
 		return filtered.length === 0 ? null : filtered;
 	}
-	/** Returns a widened `$select` only when at least one `requiredFields` entry is missing; `null` means "no widening needed". */
+	/**
+	* Returns a widened `$select` only when at least one `requiredFields` entry
+	* is missing; `null` means "no widening needed". A field the request may
+	* not see (`hasField`, derived source) is never added (since 0.1.143) —
+	* the action predicate sees it as `undefined`.
+	*/
 	_widenSelectForActions(envelopes, baseSelect) {
 		let resultSet = null;
 		let result = null;
@@ -1977,7 +2710,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			const raw = e.raw;
 			if (!Array.isArray(raw.requiredFields)) continue;
 			for (const f of raw.requiredFields) {
-				if (resultSet ? resultSet.has(f) : baseSelect.includes(f)) continue;
+				if ((resultSet ? resultSet.has(f) : baseSelect.includes(f)) || !this.fieldVisibility.isVisible(f)) continue;
 				if (resultSet === null) {
 					resultSet = new Set(baseSelect);
 					result = [...baseSelect];
@@ -2016,14 +2749,11 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		return out;
 	}
 	/**
-	* Removes `@db.writeOnly` fields from any `$select` shape — and forces an
-	* exclusion when no projection was requested — so sealed values never leave
-	* the database on a read. Runs AFTER `transformProjection` so permission
-	* overlays compose (they see the wire `$select`; this guarantees the seal on
-	* whatever they return).
+	* `select` without the `sealed` paths (see {@link _sealControls}); an
+	* exclusion of them is forced when there is no projection, or when every
+	* requested path was sealed.
 	*/
-	_sealProjection(select) {
-		const writeOnly = this._writeOnlySet;
+	_sealSelect(select, writeOnly) {
 		if (writeOnly.size === 0) return select;
 		const exclusion = () => {
 			const out = {};
@@ -2048,7 +2778,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	/** First `@db.writeOnly` field referenced by `$groupBy` / aggregate `$select`, or undefined. */
 	_findWriteOnlyInAggregate(groupBy, select) {
 		if (this._writeOnlySet.size === 0) return void 0;
-		const sealed = (f) => this._writeOnlySet.has(f) && this.hasField(f);
+		const sealed = (f) => this._writeOnlySet.has(f) && this.fieldVisibility.isVisible(f);
 		for (const f of groupBy) if (sealed(f)) return f;
 		if (Array.isArray(select)) for (const item of select) {
 			const field = typeof item === "string" ? item : item.$field;
@@ -2058,18 +2788,20 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	/**
 	* Merges the `$search` fallback into the filter: a case-insensitive literal
 	* substring match OR'd across the `@db.column.searchable` fields, `$and`-combined
-	* with the existing filter. Applies only when the adapter has no native search
-	* (native wins) and the request isn't a vector search (`$vector` consumes the term).
+	* with the existing filter. Applies only when native search does not serve
+	* the request (no native search, or — since 0.1.143 — its default index
+	* reads a field {@link hasField} hides) and the request isn't a vector
+	* search (`$vector` consumes the term).
 	*/
 	applySearchFallback(filter, controls) {
 		const term = controls.$search;
 		if (!term || controls.$vector !== void 0) return filter;
-		if (this.readable.isSearchable()) return filter;
-		const fields = this._searchFallbackFields.filter((f) => this.hasField(f));
+		if (this._nativeSearch(controls)) return filter;
+		const fields = this._searchFallbackFields.filter((f) => this.fieldVisibility.isVisible(f));
 		if (fields.length === 0) return filter;
 		const rx = `/${term.replace(/[.*+?^${}()|[\]\\/]/g, String.raw`\$&`)}/i`;
 		const fragment = { $or: fields.map((f) => ({ [f]: { $regex: rx } })) };
-		return filter && Object.keys(filter).length > 0 ? { $and: [filter, fragment] } : fragment;
+		return filter && !isEmptyObject(filter) ? { $and: [filter, fragment] } : fragment;
 	}
 	/**
 	* The controls a grouped query hands to the adapter. `$search` has two
@@ -2091,7 +2823,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* the same shape as the one this whole path exists to remove.
 	*/
 	_aggregateControls(controls) {
-		if (controls.$search === void 0 || this.readable.isSearchable()) return controls;
+		if (controls.$search === void 0 || this._nativeSearch(controls)) return controls;
 		const rest = { ...controls };
 		delete rest.$search;
 		delete rest.$index;
@@ -2106,7 +2838,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			vector: await this.computeEmbedding(searchTerm, vectorField || void 0),
 			vectorField
 		};
-		if (searchTerm && this.readable.isSearchable()) return {
+		if (searchTerm && this._nativeSearch(controls)) return {
 			kind: "search",
 			term: searchTerm,
 			index: indexName
@@ -2152,6 +2884,56 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		return result;
 	}
 	/**
+	* The filter addressing exactly the ONE row `id` means — the readable's
+	* PK-first `resolveRowFilter` (since 0.1.143) under this request's
+	* identifications (`_idOpts`). `scope` (the row overlay) restricts which
+	* rows count while the id is pinned, so a row outside it never shadows one
+	* inside it. Readables without it (partial mocks) fall back to
+	* `resolveIdFilter`.
+	*/
+	resolveRowFilter(id, scope) {
+		const readable = this.readable;
+		if (typeof readable.resolveRowFilter === "function") return readable.resolveRowFilter(id, scope ? {
+			...this._idOpts,
+			scope
+		} : this._idOpts);
+		return Promise.resolve(readable.resolveIdFilter(id, this._idOpts));
+	}
+	/**
+	* The ONE row `id` addresses, read with `controls`. A hidden unique key is
+	* not an identification (since 0.1.134): the id resolves as if that index
+	* did not exist. Since 0.1.143 it resolves primary key first, counting
+	* only rows inside the overlay — an out-of-scope row never shadows an
+	* in-scope one, so the answer is the same as if it did not exist — in one
+	* step (`findOneByRow`). Readables without it (partial mocks) pin the row
+	* with {@link resolveRowFilter}, then read it.
+	*/
+	async _findRow(id, overlay, controls) {
+		const readable = this.readable;
+		if (typeof readable.findOneByRow === "function") return await readable.findOneByRow(id, {
+			...this._idOpts,
+			scope: overlay,
+			controls
+		});
+		const idFilter = await this.resolveRowFilter(id, overlay);
+		if (!idFilter) return null;
+		return await readable.findOne({
+			filter: withOverlay(idFilter, overlay),
+			controls
+		});
+	}
+	/**
+	* The row overlay id-addressed endpoints (`/one`, `DELETE`) apply:
+	* `transformOne({})` when non-empty, and only when a subclass overrides
+	* {@link transformOne} / {@link transformFilter} — `undefined` otherwise,
+	* at no cost (since 0.1.143).
+	*/
+	async rowOverlay() {
+		if (!this._hasRowOverlay) return void 0;
+		const overlay = await this.transformOne({});
+		return overlay && !isEmptyObject(overlay) ? overlay : void 0;
+	}
+	/**
 	* Pick the first identification (PK or unique index) whose fields are all
 	* present in the query. A unique index over a field {@link hasField} hides
 	* is not a candidate (since 0.1.134) — `?hidden=x` answers exactly like
@@ -2176,9 +2958,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* **GET /query** — returns an array of records or a count.
 	*/
 	async query(url) {
-		const parsed = this.parseQueryString(url);
-		const controls = parsed.controls;
-		this._coerceActionsControl(controls);
+		const { parsed, controls } = await this.parseRequest("query", url);
 		const groupBy = controls.$groupBy;
 		if (groupBy?.length && controls.$with?.length) return new HttpError(400, "Cannot combine $with and $groupBy in the same query");
 		if (groupBy?.length && controls.$vector !== void 0) return new HttpError(400, "Cannot combine $vector and $groupBy in the same query");
@@ -2200,21 +2980,21 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		}
 		const [transformedFilter, transformedSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
 		const filter = this.applySearchFallback(transformedFilter, controls);
-		const rawSelect = this._sealProjection(transformedSelect);
+		const sealed = this._sealControls(controls, transformedSelect);
 		if (controls.$count) return this.readable.count({
 			filter,
 			controls: {
 				...controls,
-				$select: rawSelect
+				$select: sealed.$select
 			}
 		});
-		const select = this.widenPreferredIdProjection(rawSelect);
+		const select = this.widenPreferredIdProjection(sealed.$select);
 		if (select instanceof HttpError) return select;
 		const threshold = controls.$threshold ? Number(controls.$threshold) : void 0;
 		const queryObj = {
 			filter,
 			controls: {
-				...controls,
+				...sealed,
 				$select: select,
 				$limit: controls.$limit || 1e3,
 				$threshold: threshold
@@ -2232,11 +3012,9 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* **GET /pages** — returns paginated records with metadata.
 	*/
 	async pages(url) {
-		const parsed = this.parseQueryString(url);
-		this._coerceActionsControl(parsed.controls);
+		const { parsed, controls } = await this.parseRequest("pages", url);
 		const error = this.validateParsed(parsed, "pages");
 		if (error) return error;
-		const controls = parsed.controls;
 		const gateError = this.checkCapabilities(parsed);
 		if (gateError) return gateError;
 		const page = Math.max(Number(controls.$page || 1), 1);
@@ -2244,14 +3022,14 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		const skip = (page - 1) * size;
 		const [transformedFilter, transformedSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
 		const filter = this.applySearchFallback(transformedFilter, controls);
-		const rawSelect = this._sealProjection(transformedSelect);
-		const select = this.widenPreferredIdProjection(rawSelect);
+		const sealed = this._sealControls(controls, transformedSelect);
+		const select = this.widenPreferredIdProjection(sealed.$select);
 		if (select instanceof HttpError) return select;
 		const threshold = controls.$threshold ? Number(controls.$threshold) : void 0;
 		const query = {
 			filter,
 			controls: {
-				...controls,
+				...sealed,
 				$select: select,
 				$skip: skip,
 				$limit: size,
@@ -2281,12 +3059,12 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* (meters), `$index` (geo index name), plus the standard filter / `$select` /
 	* `$with` / pagination syntax. Each row carries a computed `$distance`
 	* (meters). With `$page` / `$size` the response is the `/pages` envelope;
-	* otherwise a plain row array (`$skip` / `$limit` compose).
+	* otherwise a plain row array (`$skip` / `$limit` compose). Since 0.1.143
+	* the controls pass {@link validateParsed} (type `"geo"`) like `/query`'s,
+	* and the geo index must read only fields {@link hasField} shows.
 	*/
 	async geo(url) {
-		const parsed = this.parseQueryString(url);
-		const controls = parsed.controls;
-		this._coerceActionsControl(controls);
+		const { parsed, controls } = await this.parseRequest("geo", url);
 		const point = this._parseGeoCenter(controls.$center);
 		if (point instanceof HttpError) return point;
 		for (const key of ["$maxDistance", "$minDistance"]) if (controls[key] !== void 0) {
@@ -2295,16 +3073,13 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			controls[key] = num;
 		}
 		const indexName = typeof controls.$index === "string" ? controls.$index : void 0;
-		if (parsed.insights) {
-			const insightsError = this.validateInsights(parsed.insights);
-			if (insightsError) return new HttpError(400, insightsError);
-		}
-		const computedError = this.checkComputedSelect(controls);
-		if (computedError) return computedError;
+		const error = this.validateParsed(parsed, "geo");
+		if (error) return error;
 		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));
+		const sealed = this._sealControls(controls, transformedSelect);
+		const select = this.widenPreferredIdProjection(sealed.$select);
 		if (select instanceof HttpError) return select;
 		const paginated = controls.$page !== void 0 || controls.$size !== void 0;
 		const page = Math.max(Number(controls.$page || 1), 1);
@@ -2312,7 +3087,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		const queryObj = {
 			filter,
 			controls: {
-				...controls,
+				...sealed,
 				$center: void 0,
 				$index: void 0,
 				$select: select,
@@ -2357,17 +3132,9 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* read overlays gate `/one` symmetrically with `/query` / `/pages`.
 	*/
 	async getOne(id, url) {
-		const { parsed, hasNonControl } = this.parseControlsOnlyFromUrl(url);
+		const { parsed, controls, hasNonControl } = await this.parseRequest("one", url);
 		if (hasNonControl) return new HttpError(400, "Filtering is not allowed for \"one\" endpoint");
-		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;
-		return this._findByIdAndAugment(id, parsed.controls, select);
+		return this._readOne(id, parsed, controls);
 	}
 	/**
 	* **GET /one?field1=val1&field2=val2** — retrieves a single record by composite key
@@ -2375,42 +3142,33 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* gating as {@link getOne}.
 	*/
 	async getOneComposite(query, url) {
+		const { parsed, controls } = await this.parseRequest("one", url);
 		const idObj = this.extractIdShape(query);
 		if (idObj instanceof HttpError) return idObj;
-		const { parsed } = this.parseControlsOnlyFromUrl(url);
-		this._coerceActionsControl(parsed.controls);
-		const error = this.validateParsed(parsed, "getOne");
+		return this._readOne(idObj, parsed, controls);
+	}
+	/**
+	* The shared `/one` pipeline: validation + capability gate (since 0.1.128
+	* on the composite form too — an unknown `$select` path used to reach the
+	* driver there), the sealed projection, the row read and its augmentation.
+	*/
+	async _readOne(id, parsed, controls) {
+		const error = this.validateParsed(parsed, "getOne") ?? this.checkCapabilities(parsed);
 		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));
+		const sealed = this._sealControls(controls, await this.transformProjection(controls.$select));
+		const select = this.widenPreferredIdProjection(sealed.$select);
 		if (select instanceof HttpError) return select;
-		return this._findByIdAndAugment(idObj, parsed.controls, select);
-	}
-	async _findByIdAndAugment(id, parsedControls, select) {
-		const prep = await this._prepareAugmentation(parsedControls, select);
-		const initialSelect = prep?.widenedSelect ?? select;
-		const controls = {
-			...parsedControls,
-			$select: initialSelect
+		const [prep, overlay] = await Promise.all([this._prepareAugmentation(controls, select), this.rowOverlay()]);
+		const readControls = {
+			...sealed,
+			$select: prep?.widenedSelect ?? select
 		};
-		const idFilter = this.readable.resolveIdFilter(id, this._idOpts);
-		let row = null;
-		if (idFilter) {
-			const overlay = await this.transformOne({});
-			const filter = overlay && Object.keys(overlay).length > 0 ? { $and: [idFilter, overlay] } : idFilter;
-			row = await this.readable.findOne({
-				filter,
-				controls
-			});
-		}
-		const item = await this.returnOne(Promise.resolve(row));
+		const item = await this.returnOne(this._findRow(id, overlay, readControls));
 		if (item instanceof HttpError) return item;
 		const pending = this._finishRows([item], prep, {
 			endpoint: "one",
 			projection: select,
-			controls: parsedControls
+			controls
 		});
 		if (pending) await pending;
 		return item;
@@ -2453,7 +3211,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			searchable: this.readable.isSearchable() || this._searchFallbackFields.length > 0,
 			vectorSearchable: this.readable.isVectorSearchable(),
 			geoSearchable: this._isGeoSearchable(),
-			searchIndexes: this.readable.getSearchIndexes(),
+			searchIndexes: this.readable.getSearchIndexes().map(({ fields: _fields, ...index }) => index),
 			primaryKeys: [...this.readable.primaryKeys],
 			preferredId: [...this.readable.preferredId],
 			relations,
@@ -2553,7 +3311,7 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	constructor(app, table) {
 		super(app, table);
 		const proto = _AsDbController.prototype;
-		this._writeArgs = this._hookArgs(this.guardWrite !== proto.guardWrite ? (ctx) => this.guardWrite(ctx) : void 0);
+		this._writeArgs = this._hookArgs(this.guardWrite !== proto.guardWrite ? (ctx) => this.guardWrite(ctx) : void 0, this.checkWrite !== proto.checkWrite ? (ctx) => this.checkWrite(ctx) : void 0);
 		this._removeArgs = this._hookArgs(this.guardRemove !== proto.guardRemove ? (ctx) => this.guardRemove(ctx) : void 0);
 	}
 	buildCrud() {
@@ -2615,6 +3373,30 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	*/
 	guardRemove(_ctx) {}
 	/**
+	* Post-write check (since 0.1.143) — a row-level "WITH CHECK". Overriding it
+	* is the switch (as with {@link guardWrite}): the override is passed to the
+	* table as its `check` write option and runs once per insert / replace /
+	* update call (bulk forms included), inside the table's transaction, AFTER
+	* the main write and every nested-relation phase. `ctx.filters` holds one
+	* exact primary-key filter per written row; `ctx.count(filter)` counts
+	* inside the same transaction — e.g. verify every written row still matches
+	* a policy filter:
+	*
+	* ```ts
+	* protected async checkWrite(ctx: TDbWriteCheckContext) {
+	*   const n = await ctx.count({ $and: [{ $or: ctx.filters }, tenantFilter()] })
+	*   if (n !== ctx.filters.length) throw new HttpError(403)
+	* }
+	* ```
+	*
+	* Throw to reject: the transaction rolls back and the error propagates
+	* unchanged. When `ctx.transactional` is `false` (the adapter's
+	* transaction is a pass-through, e.g. a standalone MongoDB) the write is
+	* already durable — validate before the write instead (`guardWrite`).
+	* Removes have no post-image and never call it.
+	*/
+	checkWrite(_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.
@@ -2627,15 +3409,17 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	/** `deleteOne`'s trailing options — see {@link _hookArgs}. */
 	_removeArgs;
 	/**
-	* A table call's trailing options, built once: `guard` only when the guard
-	* hook is overridden, `isFieldVisible` only when `hasField` is (an id or a
-	* PK-less payload never resolves through a hidden unique key) — else
-	* nothing, so an unmodified controller calls the table exactly as before.
+	* A table call's trailing options, built once: `guard` / `check` only when
+	* the matching hook is overridden, `isFieldVisible` only when `hasField`
+	* is (an id or a PK-less payload never resolves through a hidden unique
+	* key) — else nothing, so an unmodified controller calls the table exactly
+	* as before.
 	*/
-	_hookArgs(guard) {
+	_hookArgs(guard, check) {
 		const opts = { ...this._idOpts };
 		if (guard) opts.guard = guard;
-		return Object.keys(opts).length > 0 ? [opts] : [];
+		if (check) opts.check = check;
+		return isEmptyObject(opts) ? [] : [opts];
 	}
 	/** Resolves a hook result: `undefined` aborts with `abortMessage`, an `Error` is thrown, anything else passes. */
 	async _checkHook(pending, abortMessage) {
@@ -2683,9 +3467,20 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 		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. */
+	/**
+	* Deletes by id (guard forwarded when overridden) and maps "nothing
+	* deleted" to 404. Since 0.1.143 the row overlay ({@link rowOverlay}) is
+	* the delete's `scope`: the id is pinned among in-scope rows inside the
+	* table's transaction and an out-of-scope row is not deleted — a 404,
+	* exactly like a missing one.
+	*/
 	async _deleteOrThrow(id) {
-		const result = await this.table.deleteOne(id, ...this._removeArgs);
+		const scope = await this.rowOverlay();
+		const args = scope ? [{
+			...this._removeArgs[0],
+			scope
+		}] : this._removeArgs;
+		const result = await this.table.deleteOne(id, ...args);
 		if (result.deletedCount < 1) throw new HttpError(404);
 		return result;
 	}
@@ -2693,6 +3488,7 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	* **POST /** — inserts one or many records.
 	*/
 	async insert(payload) {
+		await this.parseRequest("insert");
 		assertWriteShape(payload);
 		if (Array.isArray(payload)) {
 			const rows = await this._writeBody("insertMany", payload, true);
@@ -2711,6 +3507,7 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	* mismatch) via a single `findOne` after the table call.
 	*/
 	async replace(payload) {
+		await this.parseRequest("replace");
 		assertWriteShape(payload);
 		const versionColumn = this.table.versionColumn;
 		if (Array.isArray(payload)) {
@@ -2732,6 +3529,7 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	* the CAS statement executes and bumps the version on a hit.
 	*/
 	async update(payload) {
+		await this.parseRequest("update");
 		assertWriteShape(payload);
 		const versionColumn = this.table.versionColumn;
 		if (Array.isArray(payload)) {
@@ -2750,10 +3548,24 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	* 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). Callers throw the result.
+	*
+	* The row is the one the write targeted (since 0.1.143): the table's
+	* `recordFilter` — the write's own resolution, primary key first — so a
+	* payload carrying the full primary key addresses that row only, never a
+	* different row that merely shares a unique value with the payload.
+	* Tables without it (partial mocks) resolve through {@link resolveRowFilter}.
 	*/
 	async _disambiguateMismatch(data, versionColumn) {
-		const filter = this.table.resolveIdFilter(data, this._idOpts);
-		const row = filter ? await this.table.findOne({
+		const table = this.table;
+		let filter;
+		if (typeof table.recordFilter === "function") try {
+			filter = table.recordFilter(data, this._idOpts);
+		} catch (error) {
+			if (!(error instanceof DbError)) throw error;
+			filter = null;
+		}
+		else filter = await this.resolveRowFilter(data);
+		const row = filter ? await table.findOne({
 			filter,
 			controls: {}
 		}) : null;
@@ -2769,6 +3581,7 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	* **DELETE /:id** — removes a single record by primary key.
 	*/
 	async remove(id) {
+		await this.parseRequest("remove");
 		const resolvedId = await this._checkHook(this.onRemove(id), "Not deleted");
 		return this._deleteOrThrow(resolvedId);
 	}
@@ -2777,6 +3590,7 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	* (composite primary key or compound unique index).
 	*/
 	async removeComposite(query) {
+		await this.parseRequest("remove");
 		const idObj = this.extractIdShape(query);
 		if (idObj instanceof HttpError) throw idObj;
 		const resolvedId = await this._checkHook(this.onRemove(idObj), "Not deleted");
@@ -2841,6 +3655,7 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 	primaryKey;
 	constructor(boundType, controllerName, app) {
 		super(boundType, controllerName, app, "value-help");
+		assertNoValueHelpActions(this.constructor);
 		const fieldMeta = /* @__PURE__ */ new Map();
 		const explicitlySearchable = [];
 		const stringProps = [];
@@ -2858,40 +3673,110 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 		this.primaryKey = primaryKey;
 		this.searchableFields = explicitlySearchable.length > 0 ? explicitlySearchable : interfaceSearchable ? stringProps : stringProps;
 	}
+	/**
+	* THE field-visibility hook: `true` when `path` is a field of the bound
+	* interface visible to this request. A path it rejects in the request's
+	* filter / `$sort` / `$select` gets the same `Unknown field "x"` 400 as a
+	* nonexistent one, and a hidden field never takes part in `$search`
+	* (`AsJsonValueHelpController`). Override to hide fields per request — it
+	* gates the request only; strip the column from responses with
+	* {@link transformProjection}.
+	*/
 	hasField(path) {
 		return this.fieldMeta.has(path);
 	}
 	/**
+	* Row overlay — the value-help counterpart of the DB controllers'
+	* `transformFilter`. Receives the request filter of `/query` / `/pages`
+	* and returns the one to run (AND your scope in: `{ $and: [filter, scope] }`).
+	* `/one` evaluates `transformFilter({})` against the found row in memory: a
+	* row outside it answers 404, exactly like a missing one. Default: identity.
+	* May be async.
+	*
+	* @since 0.1.143
+	*/
+	transformFilter(filter) {
+		return filter;
+	}
+	/**
+	* Projection hook — receives the request `$select` (`undefined` when
+	* absent; `/one` always passes `undefined`) and returns the projection to
+	* apply: an inclusion list / `{ path: 1 }` map, or an exclusion
+	* `{ path: 0 }` map. Default: identity. May be async.
+	*
+	* @since 0.1.143
+	*/
+	transformProjection(select) {
+		return select;
+	}
+	/**
+	* Normalizes a value-help `$select` (the raw `parseUrl` form or a
+	* {@link transformProjection} result) to the `@atscript/db-memory`
+	* `{ path: 0 | 1 }` projection map:
+	* - `string[]` (e.g. from `?$select=a,b`) → inclusion map `{ a: 1, b: 1 }`,
+	* - a plain `{ path: 0 | 1 }` object → passed through (0 / falsy → exclude),
+	* - anything else / empty → `undefined` (no projection; whole rows returned).
+	*/
+	normalizeSelect(select) {
+		const out = {};
+		if (Array.isArray(select)) {
+			for (const field of select) if (typeof field === "string" && field) out[field] = 1;
+		} else if (select && typeof select === "object") for (const [path, v] of Object.entries(select)) out[path] = v === 0 || v === false ? 0 : 1;
+		return Object.keys(out).length > 0 ? out : void 0;
+	}
+	/** `filter` through {@link transformFilter} and `controls.$select` through {@link transformProjection}. */
+	async _scopedQuery(filter, controls) {
+		const [scopedFilter, select] = await Promise.all([this.transformFilter(filter), this.transformProjection(controls.$select)]);
+		const out = { ...controls };
+		if (select === void 0) delete out.$select;
+		else out.$select = select;
+		return {
+			filter: scopedFilter,
+			controls: out
+		};
+	}
+	/**
+	* `getOne` + the row overlay (miss → 404) + the projection, applied in
+	* memory — `getOne` is the subclass's own lookup (id coercion included),
+	* so it is not re-expressed as a {@link query} filter.
+	*/
+	async _scopedOne(id) {
+		const [item, overlay, select] = await Promise.all([
+			this.returnOne(this.getOne(id)),
+			this.transformFilter({}),
+			this.transformProjection(void 0)
+		]);
+		if (item instanceof HttpError) return item;
+		if (overlay && !isEmptyObject(overlay)) {
+			if (!buildMemoryPredicate(overlay)(item)) return new HttpError(404);
+		}
+		const projection = this.normalizeSelect(select);
+		return projection ? projectRow(item, projection, { clone: false }) : item;
+	}
+	/**
 	* **GET /query** — returns an array of matched rows (up to `$limit`).
 	*/
 	async runQuery(url) {
-		const parsed = this.parseQueryString(url);
+		const { parsed, controls } = await this.parseRequest("query", url);
 		const validateError = this.validateParsed(parsed, "query");
 		if (validateError) return validateError;
-		return (await this.query({
-			filter: parsed.filter,
-			controls: parsed.controls
-		})).data;
+		return (await this.query(await this._scopedQuery(parsed.filter, controls))).data;
 	}
 	/**
 	* **GET /pages** — paginated row window plus total count.
 	*/
 	async runPages(url) {
-		const parsed = this.parseQueryString(url);
+		const { parsed, controls } = await this.parseRequest("pages", url);
 		const validateError = this.validateParsed(parsed, "pages");
 		if (validateError) return validateError;
-		const controls = parsed.controls;
 		const page = Math.max(Number(controls.$page || 1), 1);
 		const size = Math.max(Number(controls.$size || 10), 1);
 		const skip = (page - 1) * size;
-		const result = await this.query({
-			filter: parsed.filter,
-			controls: {
-				...controls,
-				$skip: skip,
-				$limit: size
-			}
-		});
+		const result = await this.query(await this._scopedQuery(parsed.filter, {
+			...controls,
+			$skip: skip,
+			$limit: size
+		}));
 		return {
 			data: result.data,
 			page,
@@ -2904,17 +3789,19 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 	* **GET /one/:id** — retrieves a single row by primary key.
 	*/
 	async runGetOne(id) {
-		return this.returnOne(this.getOne(id));
+		await this.parseRequest("one", "");
+		return this._scopedOne(id);
 	}
 	/**
 	* **GET /one?<pk>=<val>** — retrieves a single row by PK query param (fallback).
 	*/
 	async runGetOneComposite(query) {
+		await this.parseRequest("one", "");
 		const pk = this.primaryKey;
 		if (!pk) return new HttpError(400, "No primary key (@meta.id) on value-help interface");
 		const id = query[pk];
 		if (id === void 0) return new HttpError(400, `Missing PK field "${pk}"`);
-		return this.returnOne(this.getOne(id));
+		return this._scopedOne(id);
 	}
 	/**
 	* Meta response surfaces `@ui.dict.*` annotations as **hints** for the
@@ -3011,7 +3898,7 @@ let AsJsonValueHelpController = class AsJsonValueHelpController extends AsValueH
 		const search = controls.controls.$search;
 		if (search) {
 			const needle = search.toLowerCase();
-			const fields = this.searchableFields;
+			const fields = this.searchableFields.filter((field) => this.hasField(field));
 			rows = rows.filter((row) => {
 				for (const field of fields) {
 					const v = row[field];
@@ -3063,25 +3950,6 @@ let AsJsonValueHelpController = class AsJsonValueHelpController extends AsValueH
 		}
 		return Object.keys(out).length > 0 ? out : void 0;
 	}
-	/**
-	* Normalizes the raw `parseUrl` `$select` form to the engine's `{ path: 0 |
-	* 1 }` projection map:
-	* - `string[]` (e.g. from `?$select=a,b`) → inclusion map `{ a: 1, b: 1 }`,
-	* - a plain `{ path: 0 | 1 }` object → passed through (0 / falsy → exclude),
-	* - anything else / empty → `undefined` (no projection; whole rows returned).
-	*/
-	normalizeSelect(select) {
-		if (Array.isArray(select)) {
-			const out = {};
-			for (const field of select) if (typeof field === "string" && field) out[field] = 1;
-			return Object.keys(out).length > 0 ? out : void 0;
-		}
-		if (select && typeof select === "object") {
-			const out = {};
-			for (const [path, v] of Object.entries(select)) out[path] = v === 0 || v === false ? 0 : 1;
-			return Object.keys(out).length > 0 ? out : void 0;
-		}
-	}
 };
 AsJsonValueHelpController = __decorate([Inherit(), __decorateMetadata("design:paramtypes", [
 	Object,
@@ -3198,187 +4066,6 @@ var ActionDisabledError = class extends HttpError {
 	}
 };
 //#endregion
-//#region src/actions/current-action.ts
-/** Read the current action's `TDbActionMeta` from the wook context. Returns undefined outside a controller (e.g. direct-wook test paths). */
-function readCurrentActionMeta(ctx) {
-	let ctrl;
-	let methodName;
-	try {
-		const cc = useControllerContext(ctx);
-		ctrl = cc.getController();
-		methodName = cc.getMethod();
-	} catch {
-		return;
-	}
-	if (!ctrl || !methodName) return void 0;
-	return getAtscriptDbMate().read(ctrl.constructor, methodName)?.atscript_db_action;
-}
-//#endregion
-//#region src/actions/input-form-cache.ts
-/**
-* Cached parse of the action request body. Centralises the shape check so
-* every per-param resolver (`@DbActionID*`, `@DbActionRow*`, `@InputForm`)
-* reads through the same gate. An array or scalar root is rejected with the
-* same `ValidatorError` envelope as today's strict-shape ID failures.
-*/
-const dbActionBodySlot = cached(async (ctx) => {
-	const raw = await useBody(ctx).parseBody();
-	if (raw == null) return {};
-	if (typeof raw !== "object" || Array.isArray(raw)) throw new ValidatorError([{
-		path: "",
-		message: "Action body must be an object of shape { ids?, input? }"
-	}]);
-	return raw;
-});
-/** Cached `body.input` slot — consumed by `@InputForm()` and `useDbActionInput()`. */
-const dbActionInputSlot = cached(async (ctx) => {
-	return (await ctx.get(dbActionBodySlot)).input;
-});
-/** Composable for in-handler reads of the form input. */
-const useDbActionInput = defineWook((ctx) => ({ load: () => ctx.get(dbActionInputSlot) }));
-//#endregion
-//#region src/actions/id-validation.ts
-const SOURCE_CACHE = /* @__PURE__ */ new WeakMap();
-function getSourceCache(source) {
-	let cache = SOURCE_CACHE.get(source);
-	if (cache) return cache;
-	const identifications = source.identifications;
-	const byKeySig = /* @__PURE__ */ new Map();
-	for (const ident of identifications) byKeySig.set(fieldsSig(ident.fields), ident);
-	const fieldByName = /* @__PURE__ */ new Map();
-	for (const fd of source.fieldDescriptors) fieldByName.set(fd.path, fd);
-	cache = {
-		byKeySig,
-		fieldByName,
-		formatted: identifications.map((id) => `[${id.fields.join(", ")}]`).join(", ")
-	};
-	SOURCE_CACHE.set(source, cache);
-	return cache;
-}
-function fieldsSig(fields) {
-	return fields.toSorted().join("");
-}
-function isIdValidationSource(value) {
-	if (!value || typeof value !== "object") return false;
-	const v = value;
-	return Array.isArray(v.identifications) && Array.isArray(v.fieldDescriptors);
-}
-function validateSingleId(body, source, path = "") {
-	const errors = collectIdErrors(body, source, path);
-	if (errors.length > 0) throw new ValidatorError(errors);
-	return body;
-}
-function validateMultiId(body, source) {
-	if (!Array.isArray(body)) throw new ValidatorError([{
-		path: "",
-		message: "Expected JSON array of identifier objects",
-		details: []
-	}]);
-	const errors = [];
-	for (let i = 0; i < body.length; i++) errors.push(...collectIdErrors(body[i], source, `[${i}]`));
-	if (errors.length > 0) throw new ValidatorError(errors);
-	return body;
-}
-function collectIdErrors(value, source, pathPrefix) {
-	if (!isPlainObject$1(value)) return [{
-		path: pathPrefix,
-		message: "Expected JSON object for row identifier",
-		details: []
-	}];
-	const cache = getSourceCache(source);
-	if (cache.byKeySig.size === 0) return [{
-		path: pathPrefix,
-		message: "Table has no identifier configured",
-		details: []
-	}];
-	const match = cache.byKeySig.get(fieldsSig(Object.keys(value)));
-	if (!match) return [{
-		path: pathPrefix,
-		message: `Identifier fields must exactly match one of: ${cache.formatted}`,
-		details: []
-	}];
-	const errors = [];
-	for (const fieldName of match.fields) {
-		const sub = pathPrefix ? `${pathPrefix}.${fieldName}` : fieldName;
-		const err = checkScalar(value[fieldName], cache.fieldByName.get(fieldName), sub);
-		if (err) errors.push(err);
-	}
-	return errors;
-}
-function checkScalar(value, fd, path) {
-	const expected = fd?.designType ?? "string";
-	if (expected === "string" && typeof value !== "string") return scalarMismatch(path, expected, value);
-	if (expected === "number" && typeof value !== "number") return scalarMismatch(path, expected, value);
-	if (expected === "boolean" && typeof value !== "boolean") return scalarMismatch(path, expected, value);
-}
-function scalarMismatch(path, expected, value) {
-	return {
-		path,
-		message: `Expected identifier value to be ${expected}, got ${describe(value)}`,
-		details: []
-	};
-}
-function describe(value) {
-	if (value === null) return "null";
-	if (Array.isArray(value)) return "array";
-	return typeof value;
-}
-function isPlainObject$1(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-//#endregion
-//#region src/actions/id-cache.ts
-const boundTableKey = key("atscript_db_action_bound_table");
-function controllerOf(ctx) {
-	return useControllerContext(ctx).getController();
-}
-function controllerTable(ctx) {
-	const ctrl = controllerOf(ctx);
-	return ctrl?.readable ?? ctrl?.table ?? null;
-}
-function getActionTable(ctx) {
-	return (ctx.has(boundTableKey) ? ctx.get(boundTableKey) : void 0) ?? controllerTable(ctx);
-}
-const warnedTags = /* @__PURE__ */ new Set();
-function noTableError(ctx) {
-	const actionName = readCurrentActionMeta(ctx)?.name;
-	const tag = actionName ? `"${actionName}"` : "<unknown>";
-	if (!warnedTags.has(tag)) {
-		warnedTags.add(tag);
-		console.warn(`${WARN_PREFIX} ${tag}: controller has no readable/table property and the action declares no opts.table. Either expose readable/table on the controller, extend AsDbReadableController, or pass opts.table on @DbAction.`);
-	}
-	return new HttpError(500, {
-		statusCode: 500,
-		error: "Internal Server Error",
-		message: "Internal server error",
-		code: "ACTION_TABLE_NOT_BOUND"
-	});
-}
-/**
-* Validates the body's `ids` against the action table's identifications. For
-* the controller's own table that is its `idSource` (since 0.1.134): a unique
-* index over a field `hasField` hides neither addresses a row nor appears in
-* the "must exactly match one of" message. An `opts.table` binding has no
-* visibility hook.
-*/
-async function resolveValidatedId(ctx, validate) {
-	let source = ctx.has(boundTableKey) ? ctx.get(boundTableKey) : void 0;
-	if (!source) {
-		const ctrl = controllerOf(ctx);
-		source = ctrl?.idSource ?? ctrl?.readable ?? ctrl?.table ?? null;
-	}
-	if (!isIdValidationSource(source)) throw noTableError(ctx);
-	const env = await ctx.get(dbActionBodySlot);
-	validate(env.ids, source);
-	return env.ids;
-}
-const dbActionIdSlot = cached((ctx) => resolveValidatedId(ctx, validateSingleId));
-const dbActionIdsSlot = cached(async (ctx) => {
-	return await resolveValidatedId(ctx, validateMultiId);
-});
-const useDbActionId = defineWook((ctx) => ({ load: () => ctx.get(dbActionIdSlot) }));
-const useDbActionIds = defineWook((ctx) => ({ load: () => ctx.get(dbActionIdsSlot) }));
-//#endregion
 //#region src/actions/row-cache.ts
 function asFetchTable(value) {
 	if (!value || typeof value !== "object") return null;
@@ -3398,13 +4085,28 @@ function readActionFieldSet(ctx) {
 	const opts = action.opts;
 	return Array.isArray(opts.requiredFields) ? opts.requiredFields : null;
 }
+/**
+* Id columns plus the action's `requiredFields` — minus any the controller's
+* field visibility hides (since 0.1.143; `hasField`, and a derived field over
+* a hidden source): a hidden column is never loaded, so a `disabled`
+* predicate sees it as `undefined`.
+*/
 function seedActionFields(ctx, table) {
 	const fields = /* @__PURE__ */ new Set();
 	for (const f of table.preferredId ?? table.primaryKeys) fields.add(f);
 	const action = readActionFieldSet(ctx);
-	if (action) for (const f of action) fields.add(f);
+	if (action) {
+		const visible = actionFieldVisibility(ctx);
+		for (const f of action) if (!visible || visible(f)) fields.add(f);
+	}
 	return fields;
 }
+/**
+* Loaded row / rows are ANDed with the controller's row overlay (see
+* `dbActionOverlaySlot`, since 0.1.143): an out-of-scope id loads nothing —
+* exactly like a missing one (the same 404 on `'row'` actions, so the two
+* can't be told apart).
+*/
 async function loadRow(ctx) {
 	const id = await ctx.get(dbActionIdSlot);
 	const table = asFetchTable(getActionTable(ctx));
@@ -3412,7 +4114,7 @@ async function loadRow(ctx) {
 	const fields = seedActionFields(ctx, table);
 	for (const k of Object.keys(id)) fields.add(k);
 	const row = await table.findOne({
-		filter: id,
+		filter: withOverlay(id, await ctx.get(dbActionOverlaySlot)),
 		controls: { $select: [...fields] }
 	});
 	if (row == null) throw new HttpError(404, "Row not found for action identifier");
@@ -3444,7 +4146,7 @@ async function loadRows(ctx) {
 		}
 	}
 	const rows = await table.findMany({
-		filter: { $or: dedupedIds },
+		filter: withOverlay({ $or: dedupedIds }, await ctx.get(dbActionOverlaySlot)),
 		controls: { $select: [...fields] }
 	});
 	const rowByKey = /* @__PURE__ */ new Map();
@@ -3469,7 +4171,6 @@ const useDbActionRow = defineWook((ctx) => ({ load: () => ctx.get(dbActionRowSlo
 const useDbActionRows = defineWook((ctx) => ({ load: () => ctx.get(dbActionRowsSlot) }));
 //#endregion
 //#region src/actions/gate-interceptor.ts
-const GATE_PRIORITY = TInterceptorPriority.AFTER_GUARD;
 function injectBoundTable(fallback) {
 	const ctx = current();
 	if (ctx.has(boundTableKey)) return;
@@ -3479,62 +4180,98 @@ function injectBoundTable(fallback) {
 function buildGateInterceptor(opts) {
 	const { action, level, disabled, onDisabledRows, table } = opts;
 	return defineBeforeInterceptor(async () => {
-		injectBoundTable(table);
 		const ctx = current();
+		await awaitActionPrepared(ctx);
+		injectBoundTable(table);
 		if (level === "row") {
 			const verdicts = disabled([await ctx.get(dbActionRowSlot)]);
 			assertVerdictLength(action, verdicts, 1);
 			if (verdicts[0]) throw new ActionDisabledError(action, await ctx.get(dbActionIdSlot), void 0, [verdictReason(verdicts[0])]);
 			return;
 		}
-		const ids = await ctx.get(dbActionIdsSlot);
-		const rows = await ctx.get(dbActionRowsSlot);
-		const existingRows = [];
-		for (const row of rows) if (row !== void 0) existingRows.push(row);
-		const verdicts = disabled(existingRows);
+		await gateRows(ctx, action, disabled, onDisabledRows);
+	}, ACTION_GATE_PRIORITY);
+}
+/**
+* `'rows'` level: a request id without a loaded row (missing, or outside the
+* row overlay — indistinguishable) fails like a disabled row with no reason;
+* `disabled` (when given) judges the loaded rows. Then `onDisabledRows`
+* applies: `'reject'` → 409 listing every failing id; `'skip'` → the cached
+* ids / rows narrow to the survivors (zero survivors → 409 with every id).
+*/
+async function gateRows(ctx, action, disabled, onDisabledRows) {
+	const ids = await ctx.get(dbActionIdsSlot);
+	const rows = await ctx.get(dbActionRowsSlot);
+	const existingRows = [];
+	for (const row of rows) if (row !== void 0) existingRows.push(row);
+	let verdicts;
+	if (disabled) {
+		verdicts = disabled(existingRows);
 		assertVerdictLength(action, verdicts, existingRows.length);
-		const failingIds = [];
-		const failingReasons = [];
-		const passingRows = [];
-		const passingIds = [];
-		let verdictIndex = 0;
-		for (let i = 0; i < ids.length; i++) {
-			const row = rows[i];
-			const verdict = row === void 0 ? void 0 : verdicts[verdictIndex++];
-			if (row === void 0 || verdict) {
-				failingIds.push(ids[i]);
-				failingReasons.push(verdictReason(verdict));
-			} else {
-				passingRows.push(row);
-				passingIds.push(ids[i]);
-			}
+	}
+	const failingIds = [];
+	const failingReasons = [];
+	const passingRows = [];
+	const passingIds = [];
+	let verdictIndex = 0;
+	for (let i = 0; i < ids.length; i++) {
+		const row = rows[i];
+		const verdict = row === void 0 ? void 0 : verdicts?.[verdictIndex++];
+		if (row === void 0 || verdict) {
+			failingIds.push(ids[i]);
+			failingReasons.push(verdictReason(verdict));
+		} else {
+			passingRows.push(row);
+			passingIds.push(ids[i]);
 		}
-		if (onDisabledRows === "skip") {
-			if (passingRows.length === 0) throw new ActionDisabledError(action, void 0, [...ids], failingReasons);
-			if (failingIds.length > 0) {
-				ctx.set(dbActionRowsSlot, Promise.resolve(passingRows));
-				ctx.set(dbActionIdsSlot, Promise.resolve(passingIds));
-			}
-			return;
+	}
+	if (onDisabledRows === "skip") {
+		if (passingRows.length === 0) throw new ActionDisabledError(action, void 0, [...ids], failingReasons);
+		if (failingIds.length > 0) {
+			ctx.set(dbActionRowsSlot, Promise.resolve(passingRows));
+			ctx.set(dbActionIdsSlot, Promise.resolve(passingIds));
 		}
-		if (failingIds.length > 0) throw new ActionDisabledError(action, void 0, failingIds, failingReasons);
-	}, GATE_PRIORITY);
+		return;
+	}
+	if (failingIds.length > 0) throw new ActionDisabledError(action, void 0, failingIds, failingReasons);
 }
-/** Thin interceptor for `@DbActionRow*` without `disabled` — injects only the bound table. */
+/**
+* Interceptor for `'row'` / `'rows'` actions without `disabled` (and for a
+* `@DbActionRow*` handler of any other level: bound-table injection only):
+* runs the controller's `prepareRequest` (when defined, since 0.1.143),
+* injects the bound table and — only when the controller has a row overlay
+* (`transformOne` / `transformFilter` overridden, non-empty) — verifies the
+* requested ids against it before the handler runs by loading the row(s)
+* the handler would get: `'row'` → the 404 of a missing row; `'rows'` →
+* out-of-scope and missing ids fail like disabled rows with no reason
+* (`onDisabledRows`). No overlay → no query.
+*/
 function buildThinInterceptor(opts) {
-	const { table } = opts;
-	return defineBeforeInterceptor(() => {
+	const { table, scope } = opts;
+	return defineBeforeInterceptor(async () => {
+		const ctx = current();
+		await awaitActionPrepared(ctx);
 		injectBoundTable(table);
-	}, GATE_PRIORITY);
+		if (!scope) return;
+		if (!await ctx.get(dbActionOverlaySlot)) return;
+		if (scope.level === "rows") await gateRows(ctx, scope.action, void 0, scope.onDisabledRows);
+		else await ctx.get(dbActionRowSlot);
+	}, ACTION_GATE_PRIORITY);
 }
 //#endregion
 //#region src/actions/db-action.decorator.ts
 /**
 * Mark a controller method as a database action surfaced via `/meta`. Writes
-* `atscript_db_action` metadata and registers a Moost interceptor when needed
-* (gate when `disabled` is set, thin bound-table injector when only
-* `@DbActionRow*` is present). Stacking two `@DbAction` on the same method
-* is undefined and emits a warning.
+* `atscript_db_action` metadata and, for every `'row'` / `'rows'` action,
+* registers a Moost interceptor: the gate when `disabled` is set, else the
+* bound-table injector that also verifies the ids against the controller's
+* row overlay (since 0.1.143). Either first awaits the controller's
+* `prepareRequest({ endpoint: "action", action })` when it defines one —
+* before any id is validated or row loaded; a `'table'`-level action on an
+* `AsReadableController` subclass gets an interceptor for that alone
+* (since 0.1.143). Stacking two `@DbAction` on the same method
+* is undefined and emits a warning. Throws on a value-help controller
+* (since 0.1.143 — value-help controllers do not support actions).
 *
 * Generic over `TRow` (annotate at the call site: `@DbAction<Order>(...)`)
 * and `R` (the literal `requiredFields` tuple, inferred via `const R`).
@@ -3553,7 +4290,8 @@ function DbAction(name, opts = {}) {
 				opts
 			})
 		}))(target, propertyKey, descriptor);
-		if (isAsValueHelpControllerSubclass(typeof target === "function" ? target : target.constructor)) return descriptor;
+		const ctor = typeof target === "function" ? target : target.constructor;
+		if (isAsValueHelpControllerSubclass(ctor)) throw valueHelpActionError(ctor.name, [name]);
 		const scan = scanParamLevel(mate.read(target, propertyKey)?.params ?? []);
 		const rawOpts = opts;
 		if (typeof rawOpts.disabled === "function" && (scan.level === "row" || scan.level === "rows")) Intercept(buildGateInterceptor({
@@ -3563,7 +4301,17 @@ function DbAction(name, opts = {}) {
 			onDisabledRows: rawOpts.onDisabledRows ?? "reject",
 			table: rawOpts.table
 		}))(target, propertyKey, descriptor);
-		else if (scan.hasRowParam) Intercept(buildThinInterceptor({ table: rawOpts.table }))(target, propertyKey, descriptor);
+		else if (scan.level !== "table" || scan.hasRowParam) {
+			const scope = scan.level === "table" ? void 0 : {
+				action: name,
+				level: scan.level,
+				onDisabledRows: rawOpts.onDisabledRows ?? "reject"
+			};
+			Intercept(buildThinInterceptor({
+				table: rawOpts.table,
+				scope
+			}))(target, propertyKey, descriptor);
+		} else if (typeof target.parseRequest === "function") Intercept(actionPrepareInterceptor)(target, propertyKey, descriptor);
 		return descriptor;
 	});
 }
@@ -3688,7 +4436,7 @@ function DbActionRows() {
 * `disabled` predicate is type-narrowed by its own `requiredFields` literal.
 *
 * Multiple `@DbActions` (and shortcut) decorators on the same class
-* accumulate.
+* accumulate. Throws on a value-help controller (since 0.1.143).
 */
 function DbActions(dict) {
 	return classLevelActions(dict);
@@ -3717,10 +4465,14 @@ function classLevelActions(dict, forcedLevel) {
 			entry: merged
 		});
 	}
-	return getAtscriptDbMate().decorate((current) => ({
+	const decorate = getAtscriptDbMate().decorate((current) => ({
 		...current,
 		atscript_db_actions: [...current.atscript_db_actions ?? [], ...entries]
 	}));
+	return (target) => {
+		if (isAsValueHelpControllerSubclass(target)) throw valueHelpActionError(target.name, entries.map((e) => e.name));
+		return decorate(target);
+	};
 }
 //#endregion
 //#region src/actions/db-action-input-form.decorator.ts
@@ -3818,4 +4570,37 @@ 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, 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 };
+//#region src/permissions/crud-handlers.ts
+/**
+* The handler method(s) serving each CRUD op on `AsDbReadableController` /
+* `AsDbController` — what a permission layer authorizes a `/meta` `crud`
+* entry through (an op is allowed when ANY of its handlers is). `one` is
+* served by `/one/:id` and `/one?…`, `remove` by `DELETE /:id` and
+* `DELETE /?…`. Readables (no writes) serve only the read ops.
+*
+* @since 0.1.143
+*/
+const DB_CRUD_HANDLERS = Object.freeze({
+	query: ["query"],
+	pages: ["pages"],
+	one: ["getOne", "getOneComposite"],
+	geo: ["geo"],
+	insert: ["insert"],
+	update: ["update"],
+	replace: ["replace"],
+	remove: ["remove", "removeComposite"]
+});
+/**
+* The handler method(s) serving each CRUD op on the value-help controllers
+* (`AsValueHelpController` / `AsJsonValueHelpController` — read ops only,
+* no `geo`). Same contract as {@link DB_CRUD_HANDLERS}.
+*
+* @since 0.1.143
+*/
+const VALUE_HELP_CRUD_HANDLERS = Object.freeze({
+	query: ["runQuery"],
+	pages: ["runPages"],
+	one: ["runGetOne", "runGetOneComposite"]
+});
+//#endregion
+export { ActionDisabledError, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DB_CRUD_HANDLERS, 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, VALUE_HELP_CRUD_HANDLERS, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };