@atscript/moost-db 0.1.147 → 0.1.148

package/dist/index.mjs

@@ -1,9 +1,9 @@
-import { i as resolveDbSpace, n as clearDbSpaces, r as provideDbSpace, t as DEFAULT_DB_SPACE } from "./db-space-registry-C_wft7kl.mjs";
+import { a as resolveDbSpace, i as provideDbSpace, n as clearDbSpaces, r as closeDbSpaces, t as DEFAULT_DB_SPACE } from "./db-space-registry-Cdb0FGCn.mjs";
 import { ValidatorError, defineAnnotatedType, isAnnotatedType, serializeAnnotatedType, throwFeatureDisabled } from "@atscript/typescript/utils";
 import { Body, Delete, Get, HttpError, MoostHttp, Patch, Post, Put, Query, Url } from "@moostjs/event-http";
 import { ApplyDecorators, Controller, Inherit, Inject, Intercept, Moost, Optional, Param, Pipe, Provide, Resolve, TInterceptorPriority, TPipePriority, defineBeforeInterceptor, defineInterceptor, definePipeFn, getMoostMate, useControllerContext, withControllerContext } from "moost";
 import { parseUrl } from "@uniqu/url";
-import { ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, DbError, ENCRYPTED_REASON, acceptedOperatorsHint, aliasTargetOf, andFilters, bucketSourceVerdict, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, collectQueryPaths as collectQueryPaths$1, containsRelationFilter, findAncestorInSet, geoIndexNotFoundMessage, hasRelationOp, isEmptyObject, isJsonValueField, isPlainObject, isRelationOp, narrowerFilterOps, normalizeComputedSelect, reconcileCas, searchIndexNotFoundMessage, selfOrAncestor, unsupportedOperatorMessage, vectorIndexNotFoundMessage } from "@atscript/db";
+import { ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, DbError, ENCRYPTED_REASON, acceptedOperatorsHint, aliasTargetOf, andFilters, bucketSourceVerdict, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, collectQueryPaths as collectQueryPaths$1, containsRelationFilter, findAncestorInSet, geoIndexNotFoundMessage, groupSourceVerdict, hasRelationOp, isEmptyObject, isJsonValueField, isPlainObject, isRelationOp, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, reconcileCas, searchIndexNotFoundMessage, selfOrAncestor, unsupportedOperatorMessage, vectorIndexNotFoundMessage } from "@atscript/db";
 import { cached, current, defineWook, key, useRouteParams } from "@wooksjs/event-core";
 import { useBody } from "@wooksjs/http-body";
 import { BUCKET_UNITS } from "@uniqu/core";
@@ -76,6 +76,7 @@ const dbErrorCodeToStatus = {
 	CONFLICT: 409,
 	CAS_MISMATCH: 409,
 	TX_WAIT_TIMEOUT: 503,
+	SPACE_CLOSED: 503,
 	BUCKET_TZ_UNAVAILABLE: 501
 };
 function transformValidationError(error, reply) {
@@ -514,6 +515,38 @@ function identityKey(id) {
 	return idKey(id, Object.keys(id).toSorted());
 }
 /**
+* `resolved` (index-aligned with `requested`) with duplicate identities
+* collapsed to the first, plus the per-request list ({@link TAppliedIds}).
+*/
+function applyResolvedIds(requested, resolved) {
+	const ids = [];
+	const requests = [];
+	const seen = /* @__PURE__ */ new Set();
+	let changed = false;
+	for (let i = 0; i < resolved.length; i++) {
+		const k = identityKey(resolved[i]);
+		if (k === void 0) {
+			ids.push(resolved[i]);
+			continue;
+		}
+		if (k !== identityKey(requested[i])) changed = true;
+		requests.push({
+			id: requested[i],
+			key: k
+		});
+		if (seen.has(k)) {
+			changed = true;
+			continue;
+		}
+		seen.add(k);
+		ids.push(resolved[i]);
+	}
+	return changed ? {
+		ids,
+		requests
+	} : { ids };
+}
+/**
 * The deduped identities of `rows` over `fields` — a value read by `read`
 * (default: the row's own field) — and, per row, its identity's index in
 * `ids` (`-1`: the row is absent, or a value is missing / null).
@@ -711,6 +744,10 @@ const ACTION_OVERLAY = Symbol.for("atscript-db.actionOverlay");
 const ACTION_SCOPE = Symbol.for("atscript-db.actionScope");
 /** `true` when the controller overrides `actionRowScope` (since 0.1.147). */
 const ACTION_SCOPED = Symbol.for("atscript-db.actionScoped");
+/** The controller's internal `resolveRowIds` call for an action's ids (since 0.1.148). */
+const ROW_RESOLVE_IDS = Symbol.for("atscript-db.resolveRowIds");
+/** `true` when the controller overrides `resolveRowIds` (since 0.1.148). */
+const ROW_RESOLVES = Symbol.for("atscript-db.rowResolves");
 /**
 * 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
@@ -743,10 +780,6 @@ const dbActionOverlaySlot = cached(async (ctx) => {
 	await awaitActionPrepared(ctx);
 	return await overlayOf.call(ctrl) ?? null;
 });
-/** `true` when this action's controller overrides `actionRowScope`. */
-function isActionScoped(ctx) {
-	return ctx.get(scopedControllerSlot)?.[ACTION_SCOPED] === true;
-}
 /**
 * The loaded `rows` (already inside the row overlay) with every row outside
 * the action's `actionRowScope` replaced by `undefined` (since 0.1.147). The
@@ -1179,6 +1212,26 @@ function isNonEmptyStringArray(value) {
 }
 //#endregion
 //#region src/meta/field-capabilities.ts
+/** The display-only refusal clause per position. */
+const DISPLAY_ONLY_POSITION = {
+	filter: "a filter",
+	sort: "$sort",
+	groupedSelect: "a grouped $select",
+	groupBy: "$groupBy",
+	having: "$having",
+	aggregate: "an aggregate",
+	bucket: "a calendar bucket"
+};
+/** The capability of a declared decoration: selectable, nothing else. */
+const DECORATION_CAP = {
+	filterable: false,
+	sortable: false,
+	selectable: true,
+	indexed: false,
+	bucketable: false,
+	groupable: false,
+	numeric: false
+};
 const REASON_ADAPTER_FILTER = `${ADAPTER_FILTER_REASON}.`;
 const REASON_ADAPTER_SORT = "adapter cannot sort on this storage type.";
 const REASON_WRITE_ONLY = "field is @db.writeOnly.";
@@ -1283,6 +1336,8 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 	bucketUnits;
 	/** Aggregate functions the adapter renders, in canonical `ALL_AGGREGATE_FNS` order (`/meta.aggregateFns`). */
 	aggregateFns;
+	/** Whether the adapter renders aggregate arithmetic (`/meta.aggregateExpressions`). */
+	aggregateExpressions;
 	/** The adapter-level capabilities this index was built against — see {@link adapterSignature}. */
 	signature;
 	/**
@@ -1292,9 +1347,24 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 	* the index reads must be added here.
 	*/
 	static adapterSignature(source) {
-		return `${source.isGeoSearchable()}|${[...source.calendarBucketUnits()].join(",")}|${[...source.aggregateFns()].join(",")}`;
+		return `${source.isGeoSearchable()}|${[...source.calendarBucketUnits()].join(",")}|${[...source.aggregateFns()].join(",")}|${source.supportsAggregateExpressions()}`;
+	}
+	/**
+	* The navigation paths of a readable: its `navFields`, else its relation
+	* names (partial readables list only the latter).
+	*/
+	static navPathsOf(source) {
+		const nav = new Set(source.navFields);
+		if (nav.size === 0) for (const name of source.relations.keys()) nav.add(name);
+		return nav;
 	}
 	_entries = /* @__PURE__ */ new Map();
+	/**
+	* Declared display-only decorations (`@DbDecorations`, since 0.1.148) —
+	* virtual entries: key → the readable paths it `requires`. Selectable only;
+	* visible while every required path is.
+	*/
+	_decorations;
 	/** Nested-object parents (never listed, always selectable) → their listed leaves. */
 	_objectParents = /* @__PURE__ */ new Map();
 	/** What `bucketSourceVerdict` reads of the table (JSON-value parents, dimensions, measures). */
@@ -1307,7 +1377,8 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 	get objectParents() {
 		return this._objectParents;
 	}
-	constructor(source, writeOnly) {
+	constructor(source, writeOnly, decorations = /* @__PURE__ */ new Map()) {
+		this._decorations = decorations;
 		const tableMeta = source.type.metadata;
 		this.filterableManual = tableMeta.get("db.table.filterable") === "manual";
 		this.sortableManual = tableMeta.get("db.table.sortable") === "manual";
@@ -1317,6 +1388,7 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 		this.bucketUnits = BUCKET_UNITS.filter((unit) => units.has(unit));
 		const fns = source.aggregateFns();
 		this.aggregateFns = [...ALL_AGGREGATE_FNS].filter((fn) => fns.has(fn));
+		this.aggregateExpressions = source.supportsAggregateExpressions();
 		const physicalNames = /* @__PURE__ */ new Set();
 		const jsonValueParents = /* @__PURE__ */ new Set();
 		for (const fd of source.fieldDescriptors) {
@@ -1329,8 +1401,7 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 			dimensions: source.dimensions,
 			measures: source.measures
 		};
-		const nav = new Set(source.navFields);
-		if (nav.size === 0) for (const name of source.relations.keys()) nav.add(name);
+		const nav = FieldCapabilityIndex.navPathsOf(source);
 		this.navFields = nav;
 		const isNavOrDescendant = (path) => selfOrAncestor(path, nav) !== void 0;
 		const flatMap = source.flatMap;
@@ -1394,13 +1465,18 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 		if (!sortReason && this.sortableManual && !annotated(fd, "db.column.sortable")) sortReason = REASON_ANNOTATION_SORT;
 		const bucket = isWriteOnly ? void 0 : bucketSourceVerdict(fd, this._bucketTable, source);
 		const bucketReason = !bucket ? REASON_WRITE_ONLY : bucket.ok ? void 0 : `${bucket.reason}.`;
+		const group = isWriteOnly ? void 0 : groupSourceVerdict(fd, this._bucketTable, source);
+		const groupReason = !group ? REASON_WRITE_ONLY : group.ok ? void 0 : `${group.reason}.`;
 		const cap = {
 			filterable: filterBy.compare === void 0,
 			sortable: sortReason === void 0,
 			selectable: true,
 			indexed: fd.isIndexed === true,
-			bucketable: bucketReason === void 0
+			bucketable: bucketReason === void 0,
+			groupable: groupReason === void 0,
+			numeric: this.aggregateExpressions && physicalReason === void 0 && numericOperandProblem(fd) === void 0
 		};
+		if (groupReason) cap.groupReason = groupReason;
 		if (filterOps.length > 0) cap.filterOps = filterOps;
 		if (filterBy.compare) cap.filterReason = filterBy.compare;
 		if (sortReason) cap.sortReason = sortReason;
@@ -1421,6 +1497,18 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 			entry.fd
 		];
 	}
+	/** The declared decoration keys, in declaration order. */
+	get decorationKeys() {
+		return this._decorations.keys();
+	}
+	/** The capability of the declared decoration `key` (selectable only), `undefined` when `key` is none. */
+	decorationCap(key) {
+		return this._decorations.has(key) ? DECORATION_CAP : void 0;
+	}
+	/** The decoration `key` is visible: every path it `requires` passes `exists` (the hidden-field hook). */
+	decorationVisible(key, exists) {
+		return this._decorations.get(key)?.every(exists) === true;
+	}
 	/** Physical filter capability (adapter ∧ ¬writeOnly ∧ ¬encrypted) — ignores the manual-mode policy. */
 	isPhysicallyFilterable(path) {
 		return this._entries.get(path)?.physicalFilterable === true;
@@ -1445,6 +1533,11 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 	* JSON-stored column" — clients pin that wording, so do not "align" it
 	* with the core backstop's text.
 	*
+	* A declared decoration (`@DbDecorations`) is a virtual entry: `select` while
+	* every path it requires passes `exists`, any other position a display-only
+	* refusal (`groupedSelect` is a `$select` of an aggregate query), and hidden
+	* sources answer `Unknown field` like a nonexistent path.
+	*
 	* `predicate` is a filter entry's class (`collectQueryPaths` records it per
 	* occurrence); it only matters for `op === "filter"` on a listed leaf.
 	*
@@ -1454,8 +1547,18 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 	* name the prefixed one. A filter on a navigation path names the predicate
 	* alternative (`ticket=$some(status=…)`).
 	*/
-	check(local, op, exists, predicate = "compare", prefix = "") {
+	check(local, gateOp, exists, predicate = "compare", prefix = "") {
 		const path = prefix + local;
+		const requires = prefix === "" ? this._decorations.get(local) : void 0;
+		if (requires) {
+			if (!requires.every(exists)) return unknownField(path);
+			if (gateOp === "select") return void 0;
+			return {
+				path,
+				message: `Field "${path}" is display-only and cannot be used in ${DISPLAY_ONLY_POSITION[gateOp]}`
+			};
+		}
+		const op = gateOp === "groupedSelect" ? "select" : gateOp;
 		if (!exists(local)) return unknownField(path);
 		const { kind, parent: localParent } = classifyQueryPath(this, local);
 		const parent = localParent === void 0 ? void 0 : prefix + localParent;
@@ -1485,6 +1588,10 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 					path,
 					message: `Bucketing field "${path}" is not permitted — ${entry.cap.bucketReason}`
 				};
+				case "groupBy": return entry.cap.groupable ? void 0 : {
+					path,
+					message: `${OP_SUBJECT[op]} field "${path}" is not permitted — ${entry.cap.groupReason}`
+				};
 				default: return entry.physicalFilterable ? void 0 : {
 					path,
 					message: `${OP_SUBJECT[op]} field "${path}" is not permitted — ${entry.physicalReason}`
@@ -1851,6 +1958,10 @@ function hasClientPredicate(filter) {
 * without copying).
 */
 function readRequestContext(endpoint, controls, filter) {
+	if (endpoint === "insert") return controls.$onConflict === "ignore" ? {
+		endpoint,
+		onConflict: "ignore"
+	} : { endpoint };
 	if (!filter || Object.keys(filter).length === 0) return {
 		endpoint,
 		controls,
@@ -2139,7 +2250,7 @@ let AsReadableController = class AsReadableController {
 	async parseRequest(endpoint, url) {
 		let request;
 		if (url !== void 0) {
-			const { parsed, hasNonControl } = endpoint === "one" ? this.parseControlsOnlyFromUrl(url) : {
+			const { parsed, hasNonControl } = endpoint === "one" || endpoint === "insert" ? this.parseControlsOnlyFromUrl(url) : {
 				parsed: this.parseQueryString(url),
 				hasNonControl: false
 			};
@@ -2559,8 +2670,8 @@ function isIdValidationSource(value) {
 	const v = value;
 	return Array.isArray(v.identifications) && Array.isArray(v.fieldDescriptors);
 }
-function validateSingleId(body, source, path = "") {
-	const errors = collectIdErrors(body, source, path);
+function validateSingleId(body, source, opts = {}) {
+	const errors = collectIdErrors(body, source, opts);
 	if (errors.length > 0) throw new ValidatorError(errors);
 	return body;
 }
@@ -2577,11 +2688,12 @@ function validateMultiId(body, source, maxIds = Infinity) {
 		details: []
 	}]);
 	const errors = [];
-	for (let i = 0; i < body.length; i++) errors.push(...collectIdErrors(body[i], source, `[${i}]`));
+	for (let i = 0; i < body.length; i++) errors.push(...collectIdErrors(body[i], source, { path: `[${i}]` }));
 	if (errors.length > 0) throw new ValidatorError(errors);
 	return body;
 }
-function collectIdErrors(value, source, pathPrefix) {
+function collectIdErrors(value, source, opts) {
+	const pathPrefix = opts.path ?? "";
 	if (!isPlainObject$1(value)) return [{
 		path: pathPrefix,
 		message: "Expected JSON object for row identifier",
@@ -2602,14 +2714,21 @@ function collectIdErrors(value, source, pathPrefix) {
 	const errors = [];
 	for (const fieldName of match.fields) {
 		const sub = pathPrefix ? `${pathPrefix}.${fieldName}` : fieldName;
-		const err = checkScalar(value[fieldName], cache.fieldByName.get(fieldName), sub);
+		const err = checkScalar(value[fieldName], sub) ?? (opts.strictTypes === false ? void 0 : checkType(value[fieldName], cache.fieldByName.get(fieldName), sub));
 		if (err) errors.push(err);
 	}
 	return errors;
 }
-function checkScalar(value, fd, path) {
+/**
+* An identifier value is always a scalar: an object would reach the filter
+* as an operator expression (`{ $ne: null }`) whatever the field's type.
+*/
+function checkScalar(value, path) {
+	return typeof value === "object" && value !== null ? scalarMismatch(path, "a scalar", value) : void 0;
+}
+/** The value's type against the field's declared design type (default `string`). */
+function checkType(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);
@@ -2632,14 +2751,70 @@ function isPlainObject$1(value) {
 //#endregion
 //#region src/actions/id-cache.ts
 /**
+* EVERY id the client sent, in request order, with the identity of the id it
+* resolved to (since 0.1.148) — set only when the controller's
+* `resolveRowIds` changed or collapsed an id. The single model: refusals,
+* `reasons`, summaries and counts are judged and reported per request id
+* through {@link echoRequests}; the resolved (deduped) ids serve only the
+* row load and the handler.
+*/
+const dbActionRequestIdsKey = key("atscript_db_action_request_ids");
+/** Number of request ids (`fallback` when no id was resolved to another). */
+function requestCount(ctx, fallback) {
+	return ctx.has(dbActionRequestIdsKey) ? ctx.get(dbActionRequestIdsKey).length : fallback;
+}
+/** Number of request ids that resolved to one of `ids` (`ids.length` when none was rewritten). */
+function requestCountOf(ctx, ids) {
+	if (!ctx.has(dbActionRequestIdsKey)) return ids.length;
+	const keys = new Set(ids.map((id) => identityKey(id)));
+	return ctx.get(dbActionRequestIdsKey).filter((r) => keys.has(r.key)).length;
+}
+/**
+* Entries keyed by a resolved id, reported for every REQUEST id that resolved
+* to it — in request order, each as the client sent it (`id` replaced). Two
+* aliases of one row come back exactly like two distinct rows (same order,
+* same count). Entries whose id no request resolved to stay as they are,
+* after the request ones.
+*/
+function echoRequests(ctx, entries) {
+	if (!ctx.has(dbActionRequestIdsKey)) return [...entries];
+	const byKey = /* @__PURE__ */ new Map();
+	const rest = [];
+	for (const e of entries) {
+		const k = identityKey(e.id);
+		if (k === void 0) rest.push(e);
+		else if (!byKey.has(k)) byKey.set(k, e);
+	}
+	const out = [];
+	const matched = /* @__PURE__ */ new Set();
+	for (const r of ctx.get(dbActionRequestIdsKey)) {
+		const e = byKey.get(r.key);
+		if (!e) continue;
+		matched.add(r.key);
+		out.push({
+			...e,
+			id: r.id
+		});
+	}
+	for (const [k, e] of byKey) if (!matched.has(k)) rest.push(e);
+	return [...out, ...rest];
+}
+/** The id as the client sent it (the first, for an id several requests resolved to). */
+function requestIdOf(ctx, id) {
+	return echoRequests(ctx, [{ id }])[0].id;
+}
+/**
 * 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.
+* Then, when the controller overrides `resolveRowIds` (since 0.1.148), the
+* validated ids go through it — a one-element array for a `'row'` action —
+* and the resolved ids (duplicates collapsed) are what every consumer sees.
 */
-async function resolveValidatedId(ctx, validate) {
+async function resolveValidatedId(ctx, level, validate) {
 	await awaitActionPrepared(ctx);
 	let source = ctx.has(boundTableKey) ? ctx.get(boundTableKey) : void 0;
 	if (!source) {
@@ -2649,9 +2824,21 @@ async function resolveValidatedId(ctx, validate) {
 	if (!isIdValidationSource(source)) throw noTableError(ctx);
 	const env = await ctx.get(dbActionBodySlot);
 	validate(env.ids, source);
-	return env.ids;
+	const scoped = ctx.get(scopedControllerSlot);
+	const resolve = scoped?.[ROW_RESOLVES] ? scoped[ROW_RESOLVE_IDS] : void 0;
+	if (!resolve) return env.ids;
+	const requested = level === "row" ? [env.ids] : env.ids;
+	const overlay = await ctx.get(dbActionOverlaySlot);
+	const { ids, requests } = await resolve.call(scoped, requested, {
+		purpose: "action",
+		action: readCurrentActionMeta(ctx)?.name,
+		level,
+		overlay: overlay ?? void 0
+	});
+	if (requests) ctx.set(dbActionRequestIdsKey, requests);
+	return level === "row" ? ids[0] : ids;
 }
-const dbActionIdSlot = cached((ctx) => resolveValidatedId(ctx, validateSingleId));
+const dbActionIdSlot = cached((ctx) => resolveValidatedId(ctx, "row", validateSingleId));
 /**
 * The `'rows'` action's identifiers: the body's validated `ids`, or — for a
 * query target (`query`, since 0.1.147) — the identities of the rows it
@@ -2661,7 +2848,7 @@ const dbActionIdsSlot = cached(async (ctx) => {
 	await awaitActionPrepared(ctx);
 	const target = await ctx.get(dbActionQueryTargetSlot);
 	if (target) return target.ids;
-	return await resolveValidatedId(ctx, (body, src) => validateMultiId(body, src, actionMaxIds(ctx)));
+	return await resolveValidatedId(ctx, "rows", (body, src) => validateMultiId(body, src, actionMaxIds(ctx)));
 });
 const useDbActionId = defineWook((ctx) => ({ load: () => ctx.get(dbActionIdSlot) }));
 const useDbActionIds = defineWook((ctx) => ({ load: () => ctx.get(dbActionIdsSlot) }));
@@ -2681,29 +2868,70 @@ function asFetchTable(value) {
 function seedActionFields(ctx, table) {
 	return actionRowFields(table, requiredFieldsOf(readCurrentActionMeta(ctx)?.opts), actionFieldVisibility(ctx));
 }
+const UNSCOPED = {
+	kind: "resolved",
+	scope: null
+};
+const DEFERRED = { kind: "deferred" };
+function inPreferredShape(ids, preferred) {
+	return ids.every((id) => {
+		return Object.keys(id).length === preferred.length && preferred.every((f) => f in id);
+	});
+}
+async function resolvePreScope(ctx, level) {
+	const ctrl = ctx.get(scopedControllerSlot);
+	const action = readCurrentActionMeta(ctx)?.name;
+	const scopeOf = ctrl?.[ACTION_SCOPED] ? ctrl[ACTION_SCOPE] : void 0;
+	if (!ctrl || !scopeOf || action === void 0) return UNSCOPED;
+	if (await ctx.get(dbActionOverlaySlot)) return DEFERRED;
+	const table = asFetchTable(getActionTable(ctx));
+	const preferred = table?.preferredId;
+	if (!table || !preferred?.length) return DEFERRED;
+	const [target, requested] = await Promise.all([level === "rows" ? ctx.get(dbActionQueryTargetSlot) : void 0, level === "row" ? ctx.get(dbActionIdSlot).then((id) => [id]) : ctx.get(dbActionIdsSlot)]);
+	if (target || !inPreferredShape(requested, preferred)) return DEFERRED;
+	const ids = level === "row" ? requested : dedupeIdentities(requested, preferred).ids;
+	if (ids.length === 0) return UNSCOPED;
+	return {
+		kind: "resolved",
+		scope: nonEmptyFilter(await scopeOf.call(ctrl, action, createScopeContext("execute", ids, table))) ?? null
+	};
+}
+/**
+* {@link TPreScope} of the current action — once per event. An event runs one
+* action, so the first caller's `level` (`'row'` / `'rows'`) is the action's.
+*/
+const dbActionPreScopeSlot = cached((ctx) => {
+	let pending;
+	return (level) => pending ??= resolvePreScope(ctx, level);
+});
 /**
 * Loaded row / rows are ANDed with the controller's row overlay (see
 * `dbActionOverlaySlot`, since 0.1.143) and, since 0.1.147, checked against
-* the action's `actionRowScope` for the loaded candidates: 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).
+* the action's `actionRowScope`: 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).
 *
 * Order: `prepareRequest` → the row overlay (BEFORE the request body is
-* read: fail-fast authorization) → the ids (body) → the row load →
-* `actionRowScope` (it needs the candidates).
+* read: fail-fast authorization) → the ids (body) → `resolveRowIds` (since
+* 0.1.148) → `actionRowScope` (pre-load, when there is no overlay and the
+* ids are in `preferredId` shape — its restriction joins the one row load;
+* since 0.1.148) → the row load → otherwise `actionRowScope` on the loaded
+* candidates (it needs them).
 */
 async function loadRow(ctx) {
 	const overlay = await ctx.get(dbActionOverlaySlot);
 	const id = await ctx.get(dbActionIdSlot);
 	const table = asFetchTable(getActionTable(ctx));
 	if (!table) throw noTableError(ctx);
+	const pre = await ctx.get(dbActionPreScopeSlot)("row");
 	const fields = seedActionFields(ctx, table);
 	for (const k of Object.keys(id)) fields.add(k);
-	const loaded = await table.findOne({
-		filter: withOverlay(id, overlay),
+	const idFilter = withOverlay(withOverlay(id, overlay), pre.kind === "resolved" ? pre.scope : null);
+	let row = await table.findOne({
+		filter: idFilter,
 		controls: { $select: [...fields] }
-	});
-	const [row] = loaded == null ? [void 0] : await applyActionScope(ctx, table, [loaded]);
+	}) ?? void 0;
+	if (row !== void 0 && pre.kind === "deferred") [row] = await applyActionScope(ctx, table, [row]);
 	if (row === void 0) throw new HttpError(404, "Row not found for action identifier");
 	return row;
 }
@@ -2714,7 +2942,11 @@ async function loadRows(ctx) {
 	if (!table) throw noTableError(ctx);
 	const fields = seedActionFields(ctx, table);
 	const target = await ctx.get(dbActionQueryTargetSlot);
-	if (!target) return applyActionScope(ctx, table, await findRowsByIds(table, ids, overlay, fields));
+	if (!target) {
+		const pre = await ctx.get(dbActionPreScopeSlot)("rows");
+		if (pre.kind === "resolved") return findRowsByIds(table, ids, pre.scope ? withOverlay(pre.scope, overlay) : overlay, fields);
+		return applyActionScope(ctx, table, await findRowsByIds(table, ids, overlay, fields));
+	}
 	const rows = await target.load(ids, fields);
 	const stale = /* @__PURE__ */ new Set();
 	for (let i = 0; i < rows.length; i++) if (rows[i] === void 0) stale.add(i);
@@ -2771,25 +3003,52 @@ function DbActionTarget() {
 var TargetBase = class {
 	kind;
 	matched;
+	ctx;
 	skipped = [];
 	failed = [];
 	processed = 0;
-	constructor(kind, matched) {
+	/** Identities of every id handed to the handler so far. */
+	handedKeys = /* @__PURE__ */ new Set();
+	failedKeys = /* @__PURE__ */ new Set();
+	constructor(kind, matched, ctx) {
 		this.kind = kind;
 		this.matched = matched;
+		this.ctx = ctx;
 	}
+	/**
+	* One failure per id, whether or not `resolveRowIds` rewrote any id: a
+	* second `fail()` of the same identity is ignored (the first reason stands),
+	* so `failed` and `processed` agree in both modes.
+	*/
 	fail(id, reason) {
+		const k = identityKey(id);
+		if (k !== void 0) {
+			if (this.failedKeys.has(k)) return;
+			this.failedKeys.add(k);
+		}
 		this.failed.push({
 			id,
 			reason
 		});
 	}
+	/**
+	* A batch handed to the handler, counted per request id (two aliases of one
+	* row count twice, like two distinct rows).
+	*/
+	countProcessed(ids) {
+		for (const id of ids) {
+			const k = identityKey(id);
+			if (k !== void 0) this.handedKeys.add(k);
+		}
+		this.processed += requestCountOf(this.ctx, ids);
+	}
 	summary() {
+		const failed = echoRequests(this.ctx, this.failed);
 		return {
 			matched: this.matched,
-			processed: Math.max(0, this.processed - this.failed.length),
-			skipped: [...this.skipped],
-			failed: [...this.failed]
+			processed: Math.max(0, this.processed - failed.length),
+			skipped: echoRequests(this.ctx, this.skipped),
+			failed
 		};
 	}
 };
@@ -2801,12 +3060,12 @@ var MaterializedTarget = class extends TargetBase {
 	ids;
 	rows;
 	iterated = false;
-	constructor(kind, matched, ids, rows, skipped) {
-		super(kind, matched);
+	constructor(kind, matched, ids, rows, skipped, ctx) {
+		super(kind, matched, ctx);
 		this.ids = ids;
 		this.rows = rows;
 		this.skipped.push(...skipped);
-		this.processed = ids.length;
+		this.countProcessed(ids);
 	}
 	async *batches() {
 		if (this.iterated) throw new Error("[moost-db actions] target.batches() is single-pass");
@@ -2822,21 +3081,19 @@ async function setMaterializedTarget(ctx) {
 	const target = await resolveActionQueryTarget(ctx, false);
 	const ids = await ctx.get(dbActionIdsSlot);
 	const skipped = ctx.has(dbActionSkippedKey) ? ctx.get(dbActionSkippedKey) : [];
-	ctx.set(dbActionTargetKey, new MaterializedTarget(target ? "query" : "ids", target ? target.matched : ids.length + skipped.length, ids, async () => {
+	ctx.set(dbActionTargetKey, new MaterializedTarget(target ? "query" : "ids", target ? target.matched : requestCount(ctx, ids.length + skipped.length), ids, async () => {
 		return (await ctx.get(dbActionRowsSlot)).filter((r) => r !== void 0);
-	}, skipped));
+	}, skipped, ctx));
 }
 /** The `@DbActionTarget` surface: the target in batches, each gated when it is reached. */
 var StreamedTarget = class extends TargetBase {
-	ctx;
 	source;
 	batchSize;
 	action;
 	disabled;
 	iterated = false;
 	constructor(matched, ctx, source, batchSize, action, disabled) {
-		super(source.kind, matched);
-		this.ctx = ctx;
+		super(source.kind, matched, ctx);
 		this.source = source;
 		this.batchSize = batchSize;
 		this.action = action;
@@ -2854,7 +3111,7 @@ var StreamedTarget = class extends TargetBase {
 			const batch = await this.gate(ids.slice(start, start + this.batchSize));
 			this.next = start + this.batchSize;
 			if (batch.ids.length === 0) continue;
-			this.processed += batch.ids.length;
+			this.countProcessed(batch.ids);
 			this.current = batch.ids;
 			yield batch;
 			this.current = void 0;
@@ -2862,30 +3119,66 @@ var StreamedTarget = class extends TargetBase {
 		this.next = ids.length;
 	}
 	/**
-	* The summary of a run the handler failed after it received a batch: the
-	* batch it held is uncertain (moved to `failed` with the error's message),
-	* the rows not reached are `failed` as `"not run"`, `aborted` set.
+	* The summary of a run the handler failed after it received a batch, judged
+	* per REQUEST id by its own request position — an alias after the abort
+	* point is "not run" even when its row was judged (run, skipped) earlier,
+	* exactly as the same request of distinct rows would be:
+	* - at or after the position the run stopped at: `failed` as `"not run"`;
+	* - before it, a row the handler failed itself: its reason;
+	* - before it, the batch the handler held (uncertain): the error's message;
+	* - before it, a row the gate skipped: `skipped`; a row that ran: `processed`.
+	* `aborted` is set.
 	*/
 	abort(error) {
 		const message = errorMessage(error);
-		const base = this.summary();
-		const holding = this.current ?? [];
-		const reported = new Set(this.failed.map((f) => identityKey(f.id)));
-		const uncertain = holding.filter((id) => !reported.has(identityKey(id)));
+		const ids = this.source.ids;
+		const requests = this.ctx.has(dbActionRequestIdsKey) ? this.ctx.get(dbActionRequestIdsKey) : ids.map((id, i) => ({
+			id,
+			key: identityKey(id) ?? `#${i}`
+		}));
+		const held = new Set((this.current ?? []).map((id) => identityKey(id)));
+		let cutoff = requests.length;
+		if (this.ctx.has(dbActionRequestIdsKey)) {
+			const firstOf = (key) => requests.findIndex((r) => r.key === key);
+			if (held.size > 0) cutoff = 1 + Math.max(...[...held].map(firstOf));
+			else if (this.next < ids.length) cutoff = firstOf(identityKey(ids[this.next]));
+			if (cutoff < 0) cutoff = requests.length;
+		} else if (this.next < ids.length) cutoff = this.next;
+		const failedBy = new Map(this.failed.map((f) => [identityKey(f.id), f]));
+		const skippedBy = /* @__PURE__ */ new Map();
+		for (const row of this.skipped) {
+			const k = identityKey(row.id);
+			if (!skippedBy.has(k)) skippedBy.set(k, row);
+		}
+		const failed = [];
+		const skipped = [];
+		let processed = 0;
+		requests.forEach((r, i) => {
+			const own = failedBy.get(r.key);
+			const skip = skippedBy.get(r.key);
+			if (i >= cutoff) failed.push({
+				id: r.id,
+				reason: "not run"
+			});
+			else if (own) failed.push({
+				id: r.id,
+				reason: own.reason
+			});
+			else if (held.has(r.key)) failed.push({
+				id: r.id,
+				reason: message
+			});
+			else if (skip) skipped.push({
+				...skip,
+				id: r.id
+			});
+			else if (this.handedKeys.has(r.key)) processed++;
+		});
 		return {
-			...base,
-			processed: Math.max(0, base.processed - uncertain.length),
-			failed: [
-				...base.failed,
-				...uncertain.map((id) => ({
-					id,
-					reason: message
-				})),
-				...this.source.ids.slice(this.next).map((id) => ({
-					id,
-					reason: "not run"
-				}))
-			],
+			matched: this.matched,
+			processed,
+			skipped,
+			failed,
 			aborted: {
 				status: errorStatus(error),
 				message
@@ -2980,7 +3273,7 @@ async function setStreamedTarget(ctx, action, disabled) {
 			return findRowsByIds(table, batch, overlay, select);
 		}
 	};
-	const target = new StreamedTarget(query ? query.matched : source.ids.length, ctx, source, batchSize, action, disabled);
+	const target = new StreamedTarget(query ? query.matched : requestCount(ctx, source.ids.length), ctx, source, batchSize, action, disabled);
 	ctx.set(dbActionTargetKey, target);
 	return {
 		target,
@@ -3009,6 +3302,8 @@ const ACTION_SLOTS = [
 	dbActionInputSlot,
 	dbActionIdSlot,
 	dbActionIdsSlot,
+	dbActionRequestIdsKey,
+	dbActionPreScopeSlot,
 	dbActionRowSlot,
 	dbActionRowsSlot,
 	dbActionOverlaySlot,
@@ -3316,6 +3611,398 @@ function getDbEndpoint(target, method) {
 	}
 }
 //#endregion
+//#region src/decorations/decoration-index.ts
+/** A decoration key is a valid `$select` URL name: top-level, no `$` prefix, no dots. */
+const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+* The own readable paths a `requires` path stands for: itself when it is an
+* own field, else — a parent object of a flattened (SQL) readable — every own
+* field below it. Empty when the path is neither.
+*/
+function ownLeaves(path, ownPaths) {
+	if (ownPaths.has(path)) return [path];
+	const prefix = `${path}.`;
+	return [...ownPaths].filter((own) => own.startsWith(prefix));
+}
+/**
+* Validates `@DbDecorations` metadata against the bound readable and indexes
+* it. Throws `[moost-db]` errors (once per class — the caller memoizes).
+*/
+function buildDecorationIndex(controller, meta, source) {
+	const fail = (message) => {
+		throw new Error(`[moost-db] ${controller}: @DbDecorations ${message}`);
+	};
+	const { type } = meta;
+	if (type.type.kind !== "object") fail("expects an object interface");
+	if (type.metadata.has("db.table") || type.metadata.has("db.view")) fail("expects a plain interface — it must not carry @db.table or @db.view");
+	const keys = [...type.type.props.keys()];
+	const fieldPaths = /* @__PURE__ */ new Set();
+	for (const path of source.flatMap?.keys() ?? []) for (let at = path.indexOf(".");; at = path.indexOf(".", at + 1)) {
+		fieldPaths.add(at < 0 ? path : path.slice(0, at));
+		if (at < 0) break;
+	}
+	const isField = (path) => fieldPaths.has(path);
+	for (const key of keys) {
+		if (!KEY_RE.test(key)) fail(`key "${key}" must be a plain top-level identifier (no "$" prefix, no dots)`);
+		if (isField(key) || source.relations?.has(key) || source.navFields.has(key)) fail(`key "${key}" collides with a field or relation of the bound readable`);
+	}
+	const requires = /* @__PURE__ */ new Map();
+	const leavesOf = /* @__PURE__ */ new Map();
+	const nested = (path) => {
+		const prefix = `${path}.`;
+		const below = [...source.flatMap?.keys() ?? []].filter((p) => p.startsWith(prefix));
+		return below.filter((p) => selfOrAncestor(p, source.navFields) === void 0 && !below.some((other) => other.startsWith(`${p}.`)));
+	};
+	for (const key of keys) requires.set(key, []);
+	for (const [key, paths] of Object.entries(meta.requires)) {
+		if (!requires.has(key)) fail(`\`requires\` names "${key}", which is not a declared decoration`);
+		const resolved = [];
+		for (const path of paths) {
+			const leaves = ownLeaves(path, source.ownPaths);
+			if (leaves.length === 0) fail(`"${key}" requires "${path}", which is not an own field of the bound readable`);
+			for (const leaf of leaves) if ([...source.writeOnly].some((wo) => wo.startsWith(`${leaf}.`)) || selfOrAncestor(leaf, source.writeOnly) !== void 0) fail(`"${key}" requires "${path}", which is @db.writeOnly (a sealed value cannot be read)`);
+			for (const leaf of leaves) {
+				if (leavesOf.has(leaf)) continue;
+				const below = nested(leaf);
+				if (below.length > 0) leavesOf.set(leaf, below);
+			}
+			resolved.push(...leaves);
+		}
+		requires.set(key, [...new Set(resolved)]);
+	}
+	const visibleOn = /* @__PURE__ */ new Map();
+	for (const [key, paths] of requires) {
+		const all = new Set(paths);
+		for (const path of paths) for (const leaf of leavesOf.get(path) ?? []) all.add(leaf);
+		visibleOn.set(key, [...all]);
+	}
+	return {
+		type,
+		keys,
+		keySet: new Set(keys),
+		requires,
+		visibleOn,
+		leavesOf,
+		memo: { meta: /* @__PURE__ */ new WeakMap() }
+	};
+}
+//#endregion
+//#region src/select-shape.ts
+/** The included (`1` / `true`) and excluded (`0` / `false`) keys of a `$select` map. */
+function mapShape(map) {
+	const included = [];
+	const excluded = [];
+	for (const [key, value] of Object.entries(map)) if (value === 1 || value === true) included.push(key);
+	else if (value === 0 || value === false) excluded.push(key);
+	return {
+		included,
+		excluded
+	};
+}
+/** The one splitter every `$select` consumer in the controller reads. */
+function selectShape(raw) {
+	if (raw === void 0 || raw === null) return { kind: "all" };
+	if (Array.isArray(raw)) return {
+		kind: "list",
+		items: raw
+	};
+	const map = raw;
+	return {
+		kind: "map",
+		map,
+		...mapShape(map)
+	};
+}
+//#endregion
+//#region src/decorations/decoration-planner.ts
+const NO_DECORATIONS = /* @__PURE__ */ new Set();
+/**
+* The decoration plumbing of one controller (`@DbDecorations`, since 0.1.148):
+* rewrites a read's `$select` ({@link plan}), decides what the response
+* carries once the final projection is known ({@link serve}), and builds the
+* `/meta` view ({@link meta}). The request gate is not here — decorations are
+* virtual entries of the {@link FieldCapabilityIndex}.
+*/
+var DecorationPlanner = class {
+	index;
+	host;
+	constructor(index, host) {
+		this.index = index;
+		this.host = host;
+	}
+	visible(key) {
+		return this.host.capabilities().decorationVisible(key, this.host.isVisible);
+	}
+	requiresOf(keys) {
+		return [...new Set(keys.flatMap((key) => this.index.requires.get(key)))];
+	}
+	/**
+	* Splits the wire `$select` of a read (non-grouped: the gate already
+	* refused a decoration in a grouped one): `requested` is every declared
+	* decoration key whose sources are visible and that the client named — or,
+	* without a `$select`, all of them (an exclusion map: all minus the excluded
+	* ones). The real `$select` is widened by the requested keys' `requires`;
+	* the paths added only for the hook (`requiresOnly`) are stripped again.
+	* The result keeps the representation of `raw` (array or map).
+	*/
+	plan(raw) {
+		const { keySet, keys } = this.index;
+		const shape = selectShape(raw);
+		if (shape.kind === "all") return {
+			select: void 0,
+			requested: keys.filter((k) => this.visible(k)),
+			requiresOnly: []
+		};
+		const passthrough = {
+			select: raw,
+			requested: [],
+			requiresOnly: []
+		};
+		if (shape.kind === "list") {
+			const named = shape.items.filter((item) => typeof item === "string" && keySet.has(item));
+			if (named.length === 0) return passthrough;
+			const real = shape.items.filter((item) => !(typeof item === "string" && keySet.has(item)));
+			const have = new Set(real.filter((item) => typeof item === "string"));
+			return this.inclusion([...new Set(named)], real, have, (list) => list);
+		}
+		const { map, included, excluded } = shape;
+		if (included.length === 0 && excluded.length > 0) {
+			const skip = new Set(excluded);
+			const requested = keys.filter((key) => !skip.has(key) && this.visible(key));
+			const real = Object.fromEntries(Object.entries(map).filter(([k]) => !keySet.has(k)));
+			const requiresOnly = /* @__PURE__ */ new Set();
+			const remaining = new Set(Object.keys(real));
+			const unexclude = (key) => {
+				requiresOnly.add(key);
+				remaining.delete(key);
+				delete real[key];
+			};
+			for (const path of this.requiresOf(requested)) {
+				const hit = selfOrAncestor(path, remaining);
+				if (hit !== void 0) {
+					unexclude(hit);
+					continue;
+				}
+				const prefix = `${path}.`;
+				for (const key of remaining) if (key.startsWith(prefix)) unexclude(key);
+			}
+			return {
+				select: Object.keys(real).length > 0 ? real : void 0,
+				requested,
+				requiresOnly: [...requiresOnly]
+			};
+		}
+		const named = included.filter((k) => keySet.has(k));
+		if (named.length === 0) return passthrough;
+		const real = included.filter((k) => !keySet.has(k));
+		return this.inclusion(named, real, new Set(real), (list) => Object.fromEntries(list.map((k) => [k, 1])));
+	}
+	/**
+	* The inclusion forms: `real` (the client's own selection) plus the
+	* requested decorations' `requires` that it lacks, re-emitted by `emit`.
+	*/
+	inclusion(named, real, have, emit) {
+		const requested = named.filter((key) => this.visible(key));
+		const extra = this.requiresOf(requested).filter((path) => selfOrAncestor(path, have) === void 0);
+		const { list, added } = this.nonEmptyInclusion([...real, ...extra]);
+		return {
+			select: emit(list),
+			requested,
+			requiresOnly: [...extra.filter((path) => !this.host.preferred.has(path)), ...added],
+			selected: [...have]
+		};
+	}
+	/**
+	* An inclusion list is never empty (an empty one selects everything): a
+	* request naming only decorations with nothing to read selects the
+	* `preferredId` fields (which the response carries anyway) or, without one,
+	* a single visible field that is stripped again (`added`).
+	*/
+	nonEmptyInclusion(list) {
+		if (list.length > 0) return {
+			list,
+			added: []
+		};
+		const { preferred } = this.host;
+		if (preferred.size > 0) return {
+			list: [...preferred],
+			added: []
+		};
+		const field = this.host.firstVisibleField();
+		return field === void 0 ? {
+			list,
+			added: []
+		} : {
+			list: [field],
+			added: [field]
+		};
+	}
+	/**
+	* The decoration step once the final projection is known: a requested key
+	* is served only if every `requires` path survived `transformProjection`,
+	* the seal and the preferred-id widening (a policy that strips a source
+	* silently drops the decoration, as it drops a field). `kept` is the final
+	* projection's paths (`null` = every field).
+	*/
+	serve(plan, kept) {
+		const { keys, requires, leavesOf } = this.index;
+		const carried = (path, set) => selfOrAncestor(path, set) !== void 0 || (leavesOf.get(path)?.every((leaf) => selfOrAncestor(leaf, set) !== void 0) ?? false);
+		const dropPaths = plan.requiresOnly.map((path) => path.split("."));
+		const keepPaths = plan.requiresOnly.map((path) => (plan.selected ?? []).filter((sel) => sel.startsWith(`${path}.`)).map((sel) => sel.split(".")));
+		const selectedPaths = plan.selected?.map((sel) => sel.split("."));
+		if (plan.requested.length === 0) return {
+			served: NO_DECORATIONS,
+			dropKeys: keys,
+			dropPaths,
+			keepPaths,
+			selectedPaths
+		};
+		const keptSet = kept === null ? void 0 : new Set(kept);
+		const served = new Set(plan.requested.filter((key) => keptSet === void 0 || requires.get(key).every((path) => carried(path, keptSet))));
+		return {
+			served,
+			dropKeys: keys.filter((key) => !served.has(key)),
+			dropPaths,
+			keepPaths,
+			selectedPaths
+		};
+	}
+	/**
+	* The `/meta` envelope with the declared decorations: each one still
+	* present in `decorations` (an overlay may delete props to hide a
+	* decoration per principal) whose sources are visible is kept and gets its
+	* `fields[key]` entry (from its virtual capability-index entry); the others
+	* are pruned, and `decorations` is dropped when none is left. Runs after
+	* `applyMetaOverlay` — an overlay never sees the decoration `fields`
+	* entries. Memoized per input while visibility is not request-scoped.
+	*/
+	meta(meta) {
+		if (!meta.decorations) return meta;
+		const { memo, keySet } = this.index;
+		const memoize = !this.host.scoped;
+		const hit = memoize ? memo.meta.get(meta) : void 0;
+		if (hit) return hit;
+		const capabilities = this.host.capabilities();
+		const props = meta.decorations.type.props ?? {};
+		const kept = {};
+		const fields = { ...meta.fields };
+		for (const [key, prop] of Object.entries(props)) {
+			const cap = keySet.has(key) && this.visible(key) ? capabilities.decorationCap(key) : void 0;
+			if (!cap) continue;
+			kept[key] = prop;
+			fields[key] = {
+				sortable: cap.sortable,
+				filterable: cap.filterable,
+				decoration: true
+			};
+		}
+		let out;
+		if (Object.keys(kept).length === 0) {
+			const { decorations: _dropped, ...rest } = meta;
+			out = rest;
+		} else out = {
+			...meta,
+			fields,
+			decorations: {
+				...meta.decorations,
+				type: {
+					...meta.decorations.type,
+					props: kept
+				}
+			}
+		};
+		if (memoize) memo.meta.set(meta, out);
+		return out;
+	}
+	/** The declared interface serialized for `/meta.decorations`, once per class. */
+	serialized(serialize) {
+		return this.index.memo.serialized ??= serialize();
+	}
+};
+/** Removes what a read must not carry — the unserved declared keys and the hook-only paths — from `rows`. */
+function stripDecorations(rows, read) {
+	const { dropKeys, dropPaths, keepPaths, selectedPaths } = read;
+	if (dropKeys.length === 0 && dropPaths.length === 0) return;
+	const owned = (prefix) => selectedPaths !== void 0 && selectedPaths.some((sel) => prefix.every((part, i) => sel[i] === part));
+	for (const row of rows) {
+		for (const key of dropKeys) delete row[key];
+		dropPaths.forEach((parts, i) => {
+			const keep = keepPaths[i] ?? [];
+			if (keep.length === 0) deleteDescending(row, parts, 0, selectedPaths !== void 0, owned);
+			else pruneExcept(row, parts, 0, keep);
+		});
+	}
+}
+/** An object without keys, or an array (of any nesting) holding nothing but such values (what a strip left of a parent). */
+function isHollow(value) {
+	if (Array.isArray(value)) return value.every((el) => isHollow(el));
+	return isPlainObject(value) && Object.keys(value).length === 0;
+}
+/**
+* Deletes the path `parts` below `value`, descending through arrays of objects
+* (`items.qty` strips every element's `qty`). With `clean` (an inclusion read),
+* a parent the strip emptied — or a `null` one — goes too, unless the client
+* selected something at or below it.
+*/
+function deleteDescending(value, parts, depth, clean, owned) {
+	if (Array.isArray(value)) {
+		const dropEmptied = clean && depth > 0 && !owned(parts.slice(0, depth));
+		for (let i = value.length - 1; i >= 0; i--) {
+			const el = value[i];
+			const wasHollow = isHollow(el);
+			deleteDescending(el, parts, depth, clean, owned);
+			if (dropEmptied && !wasHollow && isHollow(el)) value.splice(i, 1);
+		}
+		return;
+	}
+	if (!isPlainObject(value)) return;
+	const key = parts[depth];
+	if (depth === parts.length - 1) {
+		delete value[key];
+		return;
+	}
+	const child = value[key];
+	const prefix = parts.slice(0, depth + 1);
+	if (child === null && clean && !owned(prefix)) {
+		delete value[key];
+		return;
+	}
+	deleteDescending(child, parts, depth + 1, clean, owned);
+	if (clean && isHollow(child) && !owned(prefix)) delete value[key];
+}
+/**
+* Below `parts`, deletes everything except the branches leading to `keep`
+* (client-selected descendants), through arrays of objects as well.
+*/
+function pruneExcept(value, parts, depth, keep) {
+	if (Array.isArray(value)) {
+		for (const el of value) pruneExcept(el, parts, depth, keep);
+		return;
+	}
+	if (!isPlainObject(value)) return;
+	if (depth < parts.length) {
+		pruneExcept(value[parts[depth]], parts, depth + 1, keep);
+		return;
+	}
+	prune(value, parts.length, keep.filter((k) => k.length > parts.length));
+}
+function prune(value, depth, branches) {
+	if (Array.isArray(value)) {
+		for (const el of value) prune(el, depth, branches);
+		return;
+	}
+	if (!isPlainObject(value)) return;
+	for (const key of Object.keys(value)) {
+		const next = branches.filter((b) => b[depth] === key);
+		if (next.length === 0) delete value[key];
+		else if (next.some((b) => b.length > depth + 1)) prune(value[key], depth + 1, next);
+	}
+}
+/** `true` when stripping `read` changes nothing — skip the post-hook step. */
+function stripsNothing(read) {
+	return read === void 0 || read.dropKeys.length === 0 && read.dropPaths.length === 0;
+}
+//#endregion
 //#region src/decorators.ts
 /**
 * DI token under which the {@link AtscriptDbReadable} instance
@@ -3475,7 +4162,8 @@ const QUERY_CONTROLS = [
 	"filter",
 	"insights",
 	...dtoControls(QueryControlsDto),
-	"groupBy"
+	"groupBy",
+	"rowOrder"
 ];
 const PAGES_CONTROLS = ["filter", ...dtoControls(PagesControlsDto)];
 const ONE_CONTROLS = dtoControls(GetOneControlsDto);
@@ -3506,6 +4194,12 @@ function writeOnlyError(path, op) {
 	const verdict = writeOnlyVerdict(path, op);
 	return badRequest(verdict.path, verdict.message);
 }
+/**
+* Validated `@DbDecorations` per readable and controller class — a
+* `FOR_EVENT` controller is constructed per event, and must not re-validate
+* (nor re-serialize) its declaration each time.
+*/
+const decorationIndexes = /* @__PURE__ */ new WeakMap();
 /** Controller classes already warned that `actionRowScope` has no row identity to match by. */
 const warnedNoIdentity = /* @__PURE__ */ new WeakSet();
 let AsDbReadableController = _AsDbReadableController = class AsDbReadableController extends AsReadableController {
@@ -3537,7 +4231,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	get capabilities() {
 		const current = this._capabilities;
 		if (current && current.signature === FieldCapabilityIndex.adapterSignature(this.readable)) return current;
-		const index = new FieldCapabilityIndex(this.readable, this._writeOnlySet);
+		const index = new FieldCapabilityIndex(this.readable, this._writeOnlySet, this._decorations?.visibleOn);
 		this._capabilities = index;
 		return index;
 	}
@@ -3574,6 +4268,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	_derivedSource;
 	/** `@db.writeOnly` paths of `$with` target readables, collected once per target. */
 	_targetWriteOnly = /* @__PURE__ */ new WeakMap();
+	/** Own leaf paths per readable (bound + `$with` targets), see {@link _leavesOf}. */
+	_targetLeaves = /* @__PURE__ */ new WeakMap();
 	_indexFieldPathsCache;
 	/** {@link _nativeSearch} per request, keyed by the request's parsed controls. */
 	_nativeSearchByRequest = /* @__PURE__ */ new WeakMap();
@@ -3597,8 +4293,14 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	_gateFieldsMemo = /* @__PURE__ */ new WeakMap();
 	/** `true` when a subclass overrides {@link allowedActions}. */
 	_hasAllowedActions;
+	/** The class's validated `@DbDecorations` (since 0.1.148), `undefined` when none is declared. */
+	_decorations;
+	/** The decoration plumbing of {@link _decorations} — see `DecorationPlanner`. */
+	_planner;
 	/** `true` when a subclass overrides {@link actionRowScope} (the gate, `$actions` and `/meta/actions` apply it). */
 	_hasActionRowScope;
+	/** @internal `true` when a subclass overrides {@link resolveRowIds} (every id-addressed endpoint calls it; since 0.1.148). */
+	[ROW_RESOLVES];
 	/** `true` when the class declares `@DbActionsFrom` (since 0.1.147). */
 	_hasDelegations;
 	/** `transformProjection` is overridden (a delegation's id paths are checked against it). */
@@ -3622,15 +4324,17 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		this._writeOnlySet = this._writeOnlyOf(resolved);
 		this._derivedSource = this._derivedSourcesOf(resolved);
 		this._invertibleFields = this._collectInvertibleFields();
+		this._decorates = typeof this.decorateRows === "function";
+		this._decorations = this._resolveDecorations(new.target);
 		this._searchFallbackFields = this._collectSearchFallbackFields();
 		this._preferredIdSet = new Set(resolved.preferredId ?? []);
 		this._quantityRefByPath = this._collectQuantityRefs();
 		const defaultOverlay = AsReadableController.prototype.applyMetaOverlay;
 		this._overlayIsNoOp = this.applyMetaOverlay === defaultOverlay;
-		this._decorates = typeof this.decorateRows === "function";
 		const proto = _AsDbReadableController.prototype;
 		this._hasRowOverlay = this.transformOne !== proto.transformOne || this.transformFilter !== proto.transformFilter;
 		this._hasActionRowScope = this.actionRowScope !== proto.actionRowScope;
+		this[ROW_RESOLVES] = this.resolveRowIds !== proto.resolveRowIds;
 		this._hasProjectionHook = this.transformProjection !== proto.transformProjection;
 		this._hasAllowedActions = this.allowedActions !== proto.allowedActions;
 		this._hasDelegations = hasActionDelegations(new.target);
@@ -3647,6 +4351,37 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			sealedFor: (readable, prefix = "") => this._sealedFor(readable, prefix)
 		};
 		this._idOpts = scoped ? { isFieldVisible: isVisible } : void 0;
+		this._planner = this._decorations && new DecorationPlanner(this._decorations, {
+			isVisible,
+			scoped,
+			preferred: this._preferredIdSet,
+			capabilities: () => this.capabilities,
+			firstVisibleField: () => this._invertibleFields.find((path) => isVisible(path))
+		});
+	}
+	/**
+	* The class's `@DbDecorations`, validated against the bound readable once
+	* per class and readable (a `[moost-db]` error when invalid); warns once
+	* when `decorateRows` is not implemented.
+	*/
+	_resolveDecorations(ctor) {
+		const meta = getAtscriptDbMate().read(ctor)?.atscript_db_decorations;
+		if (!meta) return void 0;
+		let perCtor = decorationIndexes.get(this.readable);
+		if (!perCtor) decorationIndexes.set(this.readable, perCtor = /* @__PURE__ */ new Map());
+		let index = perCtor.get(ctor);
+		if (!index) {
+			index = buildDecorationIndex(ctor.name, meta, {
+				flatMap: this.readable.flatMap,
+				relations: this.readable.relations,
+				navFields: FieldCapabilityIndex.navPathsOf(this.readable),
+				ownPaths: new Set(this._invertibleFields),
+				writeOnly: this._writeOnlySet
+			});
+			perCtor.set(ctor, index);
+			if (!this._decorates) this.logger.warn(`@DbDecorations declares ${index.keys.join(", ")} but ${ctor.name} does not implement decorateRows() — the keys are never filled`);
+		}
+		return index;
 	}
 	/**
 	* The identifications this request may address rows through (since
@@ -3672,7 +4407,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	}
 	_collectInvertibleFields() {
 		const out = [];
-		const nav = this.capabilities.navFields;
+		const nav = FieldCapabilityIndex.navPathsOf(this.readable);
 		for (const fd of this.readable.fieldDescriptors) {
 			if (fd.ignored) continue;
 			if (selfOrAncestor(fd.path, nav) !== void 0) continue;
@@ -3762,7 +4497,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	checkCapabilities(parsed) {
 		const capabilities = this.capabilities;
 		const isVisible = this.fieldVisibility.isVisible;
-		const refs = collectQueryPaths$1(parsed);
+		const select = parsed.controls?.$select;
+		const refs = collectQueryPaths$1(parsed, Array.isArray(select) && select.some((item) => typeof item !== "string") || void 0);
 		if (refs.unsupportedOperator !== void 0) return badRequest(refs.unsupportedOperator, unsupportedOperatorMessage(refs.unsupportedOperator));
 		const relState = { nodes: 0 };
 		for (const ref of refs.filter) {
@@ -3778,9 +4514,12 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		const recorded = parsed.controls ? this._clientWith.get(parsed.controls) : void 0;
 		const withRelError = this._relationGate().checkWith(recorded === void 0 ? liveWith : recorded?.tree, relState);
 		if (withRelError) return withRelError;
-		for (const op of PATH_OPS) for (const path of refs[op]) {
-			const verdict = capabilities.check(path, op, isVisible);
-			if (verdict) return badRequest(verdict.path, verdict.message);
+		for (const op of PATH_OPS) {
+			const gateOp = op === "select" && refs.aggregateMode ? "groupedSelect" : op;
+			for (const path of refs[op]) {
+				const verdict = capabilities.check(path, gateOp, isVisible);
+				if (verdict) return badRequest(verdict.path, verdict.message);
+			}
 		}
 		const having = checkHavingKeys(refs);
 		if (having) return badRequest(having.path, having.message);
@@ -3806,7 +4545,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				navFields: capabilities.navFields
 			});
 		} catch (error) {
-			if (!(error instanceof DbError)) throw error;
+			if (!(error instanceof DbError) || error.code !== "INVALID_QUERY") throw error;
 			const [issue] = error.errors;
 			return badRequest(issue.path, issue.message);
 		}
@@ -3984,12 +4723,12 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			const sub = nested.$select ?? rel.$select;
 			return {
 				...nested,
-				$select: this._sealSelect(sub, sealed)
+				$select: this._sealSelect(sub, sealed, target)
 			};
 		});
 		const out = {
 			...controls,
-			$select: this._sealSelect(select, vis.sealedFor(this.readable))
+			$select: this._sealSelect(select, vis.sealedFor(this.readable), this.readable)
 		};
 		if ($with !== controls.$with) out.$with = $with;
 		return out;
@@ -4258,34 +4997,24 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* The rows the row-level action `actionName` may run on (since 0.1.145),
 	* as an extra row filter; `undefined` or `{}` = no restriction (the
 	* default). Enforced by the action gate — the action's ids / rows are
-	* loaded under {@link rowOverlay}, then checked against this filter, so an
-	* id outside it gets the same 404 "Row not found for action identifier"
+	* loaded under {@link rowOverlay}, then checked against this filter (or —
+	* without an overlay — the filter joins the load), so an id outside it gets
+	* the same 404 "Row not found for action identifier"
 	* as a missing one — and reflected in `$actions` and
 	* `GET /meta/actions`, which list the action only on rows inside it.
 	*
-	* Since 0.1.147 the hook receives the candidate rows (`ctx`), so a scope
-	* can depend on them — e.g. derive `{ ticketKey: { $in: … } }` from a
-	* related table read for exactly these rows:
-	*
-	* | `ctx.purpose` | asked by | `ctx.ids` |
-	* | --- | --- | --- |
-	* | `"execute"` | the action gate | the loaded ids / rows (≤ `maxIds`; one batch of a query target) |
-	* | `"rows"` | `$actions` on a read (and a view's delegated verdicts) | the read's rows |
-	* | `"available"` | `GET /meta/actions/:id` | the one row |
-	*
-	* - Called only with at least one candidate, at most once per action per
-	*   evaluation; `ctx.ids` is the same array object for every action of
-	*   one evaluation (memoize on it with a `WeakMap`).
-	* - Candidates are already inside the row overlay — ids that do not exist
-	*   or fall outside it never reach the hook.
-	* - The result only restricts (`ids ∧ rowOverlay ∧ scope`); a throw fails
-	*   the request — never a silent "allow".
-	* - The filter runs straight against the bound readable: it may use
-	*   fields {@link hasField} hides, and nothing of it (nor of
-	*   `ctx.loadRows`) reaches the response. Equal filters — the same object,
-	*   or structurally equal ones — share one id-only query.
-	* - Runs after {@link prepareRequest} and, on the action route, after the
-	*   request body is read (it needs the ids).
+	* The hook receives the candidate rows (`ctx`), so a scope can depend on
+	* them — what `ctx.purpose`, `ctx.ids` and `ctx.loadRows` hold, and when the
+	* hook is asked before any load, is documented on {@link TDbActionScopeContext}.
+	* Called only with at least one candidate, at most once per action per
+	* evaluation. An answer restricting nothing (`undefined`, `null`, `{}`)
+	* makes the gate load no row at all; a restriction is folded into the one
+	* row load. The result only restricts (`ids ∧ rowOverlay ∧ scope`); a throw
+	* fails the request — never a silent "allow". The filter runs straight
+	* against the bound readable: it may use fields {@link hasField} hides, and
+	* nothing of it reaches the response. Runs after {@link prepareRequest} and,
+	* on the action route, after the request body is read and
+	* {@link resolveRowIds}.
 	*
 	* Not overriding it costs nothing; a one-parameter override keeps working.
 	* moost-db always passes `ctx` — it is optional in the signature only so
@@ -4351,6 +5080,37 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	transformProjection(projection) {
 		return projection;
 	}
+	/**
+	* The shared projection step of `/query`, `/pages`, `/geo` and `/one`:
+	* splits the declared decoration keys out of the wire `$select`
+	* ({@link DecorationPlanner.plan}), runs {@link transformProjection} on the
+	* rest (decoration keys never reach it — a permission layer needs no
+	* change; their `requires` paths are added so the hook's inputs are read),
+	* then seals every projection level. `finish` completes it once the
+	* endpoint is past its own checks: the preferred-id widening (an
+	* `HttpError` for a mixed `$select`) and the decoration step — what every
+	* read endpoint then passes to {@link _runReadWithActions}.
+	*/
+	async _projectRead(controls) {
+		const plan = this._planner?.plan(controls.$select);
+		const transformed = await this.transformProjection(plan ? plan.select : controls.$select);
+		const sealed = this._sealControls(controls, transformed);
+		const finish = () => {
+			const select = this.widenPreferredIdProjection(sealed.$select);
+			if (select instanceof HttpError) return select;
+			let kept;
+			const keptPaths = () => kept === void 0 ? kept = this._resolveProjectionForAugmenter(select) : kept;
+			return {
+				select,
+				kept: keptPaths,
+				read: plan && this._planner.serve(plan, keptPaths())
+			};
+		};
+		return {
+			sealed,
+			finish
+		};
+	}
 	widenPreferredIdProjection(projection) {
 		const widened = this.widenQuantityRefProjection(projection);
 		if (widened instanceof HttpError) return widened;
@@ -4372,12 +5132,10 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		return out;
 	}
 	_widenMapProjection(projection) {
-		const entries = Object.entries(projection);
-		if (entries.length === 0) return projection;
-		const included = /* @__PURE__ */ new Set();
-		const excluded = /* @__PURE__ */ new Set();
-		for (const [k, v] of entries) if (v === 1 || v === true) included.add(k);
-		else if (v === 0 || v === false) excluded.add(k);
+		if (Object.keys(projection).length === 0) return projection;
+		const shape = mapShape(projection);
+		const included = new Set(shape.included);
+		const excluded = new Set(shape.excluded);
 		if (included.size > 0 && excluded.size > 0) return new HttpError(400, "Mixed inclusion/exclusion $select maps are not supported");
 		if (excluded.size === 0) {
 			let allPresent = true;
@@ -4433,12 +5191,10 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		return [...projection, ...toAdd];
 	}
 	_widenQuantityMapProjection(projection) {
-		const entries = Object.entries(projection);
-		if (entries.length === 0) return projection;
-		const included = /* @__PURE__ */ new Set();
-		const excluded = /* @__PURE__ */ new Set();
-		for (const [k, v] of entries) if (v === 1 || v === true) included.add(k);
-		else if (v === 0 || v === false) excluded.add(k);
+		if (Object.keys(projection).length === 0) return projection;
+		const shape = mapShape(projection);
+		const included = new Set(shape.included);
+		const excluded = new Set(shape.excluded);
 		if (included.size > 0 && excluded.size > 0) return new HttpError(400, "Mixed inclusion/exclusion $select maps are not supported");
 		if (excluded.size === 0) {
 			const toAdd = [];
@@ -4453,22 +5209,11 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	}
 	/** Normalize a post-`widenPreferredIdProjection` $select into `string[] | null` (`null` = all fields). */
 	_resolveProjectionForAugmenter(select) {
-		if (select === void 0) return null;
-		if (Array.isArray(select)) {
-			const out = [];
-			const seen = /* @__PURE__ */ new Set();
-			for (const item of select) if (typeof item === "string" && !seen.has(item)) {
-				seen.add(item);
-				out.push(item);
-			}
-			return out;
-		}
-		const obj = select;
-		const included = [];
-		const excluded = [];
-		for (const [k, v] of Object.entries(obj)) if (v === 1 || v === true) included.push(k);
-		else if (v === 0 || v === false) excluded.push(k);
-		if (included.length > 0 && excluded.length === 0) return included;
+		const shape = selectShape(select);
+		if (shape.kind === "all") return null;
+		if (shape.kind === "list") return [...new Set(shape.items.filter((item) => typeof item === "string"))];
+		const { included, excluded } = shape;
+		if (included.length > 0 && excluded.length === 0) return [...included];
 		if (excluded.length > 0 && included.length === 0) return this._invertExclusion(new Set(excluded));
 		throw new HttpError(500, "[moost-db] mixed inclusion/exclusion projection reached augmenter; widenPreferredIdProjection should have rejected it");
 	}
@@ -4514,7 +5259,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		}
 		return result;
 	}
-	async _prepareAugmentation(controls, select) {
+	async _prepareAugmentation(controls, projected) {
 		if (!controls.$actions) return null;
 		const [own, delegations] = await Promise.all([this._resolveAugmentEnvelopes(), this._activeDelegations()]);
 		if (own === null && delegations.length === 0) return null;
@@ -4524,7 +5269,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			scopeOverlay = this.rowOverlay();
 			scopeOverlay.catch(() => {});
 		}
-		let resolvedProjection = this._resolveProjectionForAugmenter(select);
+		let resolvedProjection = projected.kept();
 		let widenedSelect = resolvedProjection === null ? null : this._widenSelectForActions(envelopes, resolvedProjection);
 		if (resolvedProjection !== null && delegations.length > 0) {
 			const base = widenedSelect ?? resolvedProjection;
@@ -4629,6 +5374,14 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	[ACTION_OVERLAY]() {
 		return this.rowOverlay();
 	}
+	/**
+	* @internal {@link resolveRowIds} for an action's validated ids (since
+	* 0.1.148): the output validated, duplicate identities collapsed, and the
+	* ids as the client sent them kept for the error bodies and summaries.
+	*/
+	async [ROW_RESOLVE_IDS](ids, ctx) {
+		return applyResolvedIds(ids, await this._runResolveRowIds(ids, ctx));
+	}
 	/** @internal {@link actionRowScope} for the gate's loaded candidates (since 0.1.147). */
 	[ACTION_SCOPE](action, ctx) {
 		return this._actionScope(action, ctx);
@@ -4757,9 +5510,11 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	/**
 	* `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.
+	* requested path was sealed. An inclusion naming a PARENT of a sealed path
+	* (`secret` over a write-only `secret.hash`) is replaced by the parent's
+	* unsealed leaves, so a sealed descendant never rides along with it.
 	*/
-	_sealSelect(select, writeOnly) {
+	_sealSelect(select, writeOnly, readable) {
 		if (writeOnly.size === 0) return select;
 		const exclusion = () => {
 			const out = {};
@@ -4767,29 +5522,47 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			return out;
 		};
 		if (select === void 0) return exclusion();
+		const expand = (path) => {
+			if (writeOnly.has(path)) return [];
+			const prefix = `${path}.`;
+			let parent = false;
+			for (const sealed of writeOnly) if (sealed.startsWith(prefix)) {
+				parent = true;
+				break;
+			}
+			if (!parent) return [path];
+			return this._leavesOf(readable).filter((leaf) => leaf.startsWith(prefix) && selfOrAncestor(leaf, writeOnly) === void 0);
+		};
 		if (Array.isArray(select)) {
-			const kept = select.filter((item) => typeof item === "string" ? !writeOnly.has(item) : !writeOnly.has(item.$field ?? ""));
+			const kept = [];
+			for (const item of select) if (typeof item === "string") kept.push(...expand(item));
+			else if (!writeOnly.has(item.$field ?? "")) kept.push(item);
 			return kept.length > 0 ? kept : exclusion();
 		}
 		const entries = Object.entries(select);
 		if (entries.length > 0 && (entries[0][1] === 1 || entries[0][1] === true)) {
 			const out = {};
-			for (const [k, v] of entries) if (!writeOnly.has(k)) out[k] = v;
+			for (const [k, v] of entries) for (const path of expand(k)) out[path] = v;
 			return Object.keys(out).length > 0 ? out : exclusion();
 		}
 		const out = { ...select };
 		for (const f of writeOnly) out[f] = 0;
 		return out;
 	}
-	/** 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.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;
-			if (field && sealed(field)) return field;
+	/** Own leaf field paths (no navigation, no ignored field) of `readable`, once per readable. */
+	_leavesOf(readable) {
+		let leaves = this._targetLeaves.get(readable);
+		if (!leaves) {
+			const paths = [...readable.flatMap?.keys() ?? []].filter((path) => path !== "");
+			const parents = /* @__PURE__ */ new Set();
+			for (const path of paths) for (let at = path.indexOf("."); at >= 0; at = path.indexOf(".", at + 1)) parents.add(path.slice(0, at));
+			const nav = readable.navFields ?? /* @__PURE__ */ new Set();
+			const ignored = /* @__PURE__ */ new Set();
+			for (const fd of readable.fieldDescriptors) if (fd.ignored) ignored.add(fd.path);
+			leaves = paths.filter((path) => !parents.has(path) && selfOrAncestor(path, nav) === void 0 && selfOrAncestor(path, ignored) === void 0);
+			this._targetLeaves.set(readable, leaves);
 		}
+		return leaves;
 	}
 	/**
 	* Merges the `$search` fallback into the filter: a case-insensitive literal
@@ -4859,13 +5632,13 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* subclass implements it. Returns the hook's result — `undefined`, with no
 	* promise or microtask, when there is no hook or it is synchronous.
 	*/
-	_finishRows(rows, prep, ctx) {
+	_finishRows(rows, prep, ctx, read) {
 		const overlay = prep?.scopeOverlay;
-		if (!prep || !overlay && prep.delegations.length === 0) return this._augmentAndDecorate(rows, prep, ctx);
+		if (!prep || !overlay && prep.delegations.length === 0) return this._augmentAndDecorate(rows, prep, ctx, read);
 		return (async () => {
 			const names = prep.envelopes.map((e) => e.info.name);
 			const [masks, delegated] = await Promise.all([overlay ? this._scopeMasks(rows, names, "rows", overlay) : void 0, Promise.all(prep.delegations.map((d) => this._delegatedRowVerdicts(rows, d)))]);
-			await this._augmentAndDecorate(rows, prep, ctx, masks, delegated);
+			await this._augmentAndDecorate(rows, prep, ctx, read, masks, delegated);
 		})();
 	}
 	/**
@@ -4873,7 +5646,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* ones (`delegated`: per delegation, per row) — then {@link decorateRows}
 	* when implemented.
 	*/
-	_augmentAndDecorate(rows, prep, ctx, outOfScope, delegated) {
+	_augmentAndDecorate(rows, prep, ctx, read, outOfScope, delegated) {
 		if (prep) {
 			augmentRowsWithActions({
 				envelopes: prep.envelopes,
@@ -4884,7 +5657,11 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			});
 			if (prep.delegations.length > 0) mergeDelegatedActions(rows, delegated ?? []);
 		}
-		return this._decorates ? this.decorateRows(rows, ctx) : void 0;
+		const decorated = this._decorates ? this.decorateRows(rows, ctx) : void 0;
+		if (!read || stripsNothing(read)) return decorated;
+		const strip = () => stripDecorations(rows, read);
+		if (decorated === void 0) return strip();
+		return Promise.resolve(decorated).then(strip);
 	}
 	/**
 	* The app of the current event, through DI — never the one this
@@ -4960,9 +5737,10 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	*/
 	resolveMeta() {
 		const own = super.resolveMeta();
-		if (!this._hasDelegations && !this._hasFieldOverridden) return own;
+		if (!this._hasDelegations && !this._hasFieldOverridden && !this._planner) return own;
 		return (async () => {
-			const [meta, delegated] = await Promise.all([own, this._hasDelegations ? this._delegatedInfos() : []]);
+			const [overlaid, delegated] = await Promise.all([own, this._hasDelegations ? this._delegatedInfos() : []]);
+			const meta = this._planner ? this._planner.meta(overlaid) : overlaid;
 			const visible = this._applyIndexVisibility(meta);
 			return delegated.length > 0 ? {
 				...visible,
@@ -5016,7 +5794,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	/** @internal Source side of a delegation: `GET /meta/actions` for one id, `names` only. */
 	async [AVAILABLE_ACTIONS](id, names) {
 		await this.parseRequest("availableActions");
-		return this._availableActions(id, names);
+		return (await this._availableResolved(id, names)).own;
 	}
 	/** @internal Source side of a delegation: the `names` the caller may run (`allowedActions`). */
 	async [ALLOWED_ACTIONS](names) {
@@ -5035,8 +5813,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* `$actions=true`, then run {@link decorateRows}. Caller dispatches the
 	* strategy to its read-method family (count vs no-count).
 	*/
-	async _runReadWithActions(endpoint, queryObj, controls, select, exec) {
-		const [prep, strategy] = await Promise.all([this._prepareAugmentation(controls, select), this._resolveReadStrategy(controls)]);
+	async _runReadWithActions(endpoint, queryObj, controls, projected, exec) {
+		const [prep, strategy] = await Promise.all([this._prepareAugmentation(controls, projected), this._resolveReadStrategy(controls)]);
 		const result = await exec(prep?.widenedSelect ? {
 			...queryObj,
 			controls: {
@@ -5046,19 +5824,120 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		} : queryObj, strategy);
 		const pending = this._finishRows(result.data, prep, {
 			endpoint,
-			projection: select,
-			controls
-		});
+			projection: projected.select,
+			controls,
+			decorations: projected.read?.served ?? NO_DECORATIONS
+		}, projected.read);
 		if (pending) await pending;
 		return result;
 	}
 	/**
+	* Maps the ids an id-addressed endpoint received to the rows' current ids
+	* (since 0.1.148) — the seam for stale or alias ids, e.g. a natural key that
+	* was renamed. Called once per request, after {@link prepareRequest} and
+	* after the request's own validation, before anything reads the row, by:
+	*
+	* | `ctx.purpose` | endpoint | `ids` |
+	* | --- | --- | --- |
+	* | `"one"` | `GET /one/:id`, `GET /one?…` | one id: the path string, or the `?`-form identification object |
+	* | `"available"` | `GET /meta/actions/:id`, `?…` (and a view asking its source) | one id, as above |
+	* | `"remove"` | `DELETE /:id`, `DELETE /?…` (`AsDbController`) | one id, as above |
+	* | `"action"` | an action route | the body's validated ids (one for a `'row'` action) |
+	*
+	* Contract:
+	*
+	* - Return one id per input id, index-aligned (anything else is a 500). An
+	*   id that already names a row must come back UNCHANGED — the current
+	*   holder of a key wins over an alias; so must an id you cannot resolve
+	*   (never throw for an unknown alias: a custom error is an oracle — the
+	*   endpoint then answers its normal miss).
+	* - The output is validated (a server bug is a 500, never a client 400): a
+	*   scalar is resolved like a path scalar (primary key first, then the
+	*   visible unique keys, inside the row overlay); an object must be one of
+	*   the visible identifications ({@link idSource}); an `"action"` id must
+	*   be such an object.
+	* - The resolved id is never trusted for access: the endpoint still reads
+	*   or deletes it under {@link rowOverlay} and the visible identifications.
+	*   `ctx.overlay` is that overlay — resolve INSIDE it when an alias could
+	*   name several rows, so a row the caller can't reach never shadows one
+	*   they can. Don't log or return the canonical id in errors.
+	* - Handlers (`@DbActionID()`, `useDbActionId()`), {@link rowOverlay} reads,
+	*   {@link actionRowScope} and `onRemove` / `guardRemove` receive the
+	*   resolved ids; error bodies and `summary()` echo the ids the client sent.
+	* - Write bodies (`POST` / `PUT` / `PATCH`) are not resolved — use
+	*   `onWrite`. Not called by value-help controllers, `$actions` on a read
+	*   or a query target. Not overriding it costs nothing.
+	*
+	* It is NOT overridden by {@link resolveRowFilter}, which does not take part
+	* in `/one` for real tables and views.
+	*
+	* ```ts
+	* protected async resolveRowIds(ids: readonly TDbRowIdInput[], ctx: TDbRowIdsContext) {
+	*   return Promise.all(ids.map(async (id) => {
+	*     const key = typeof id === "object" ? id.code : id
+	*     if (typeof key !== "string") return id
+	*     // the current holder of the key wins; consult the alias table on a miss
+	*     // resolve INSIDE the overlay: a row the caller cannot reach never wins
+	*     const inScope = (code: string) =>
+	*       this.readable.count({ filter: ctx.overlay ? { $and: [{ code }, ctx.overlay] } : { code } })
+	*     if (await inScope(key)) return id
+	*     const alias = await aliases.findOne({ filter: { oldCode: key } })
+	*     if (!alias || !(await inScope(alias.newCode))) return id
+	*     return typeof id === "object" ? { code: alias.newCode } : alias.newCode
+	*   }))
+	* }
+	* ```
+	*
+	* @since 0.1.148
+	*/
+	resolveRowIds(ids, _ctx) {
+		return ids;
+	}
+	/** {@link resolveRowIds} with its output validated (a server bug is a 500). */
+	async _runResolveRowIds(ids, ctx) {
+		const out = await this.resolveRowIds(ids, ctx);
+		if (!Array.isArray(out) || out.length !== ids.length) throw new HttpError(500, "resolveRowIds must return one id per request id");
+		const source = this.idSource;
+		for (const id of out) {
+			if ((typeof id === "string" || typeof id === "number" || typeof id === "boolean") && ctx.purpose !== "action") continue;
+			try {
+				validateSingleId(id, source, { strictTypes: ctx.purpose === "action" });
+			} catch (error) {
+				if (error instanceof ValidatorError) throw new HttpError(500, "resolveRowIds returned an invalid id");
+				throw error;
+			}
+		}
+		return out;
+	}
+	/**
+	* @internal The one id of an id-addressed endpoint through
+	* {@link resolveRowIds} (identity, at no cost, when it is not overridden)
+	* and the row overlay it was resolved inside — computed once, for the
+	* endpoint's read or delete under that overlay.
+	*/
+	async _resolveWithOverlay(id, purpose) {
+		const overlay = await this.rowOverlay();
+		if (!this[ROW_RESOLVES]) return {
+			id,
+			overlay
+		};
+		const [resolved] = await this._runResolveRowIds([id], {
+			purpose,
+			overlay
+		});
+		return {
+			id: resolved,
+			overlay
+		};
+	}
+	/**
 	* 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`.
+	* `resolveIdFilter`. Not an alias seam: `/one` reads through `findOneByRow`
+	* on every real table or view — map stale ids in {@link resolveRowIds}.
 	*/
 	resolveRowFilter(id, scope) {
 		const readable = this.readable;
@@ -5132,8 +6011,15 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		if (groupBy?.length && controls.$vector !== void 0) return new HttpError(400, "Cannot combine $vector and $groupBy in the same query");
 		const error = this.validateParsed(parsed, "query");
 		if (error) return error;
-		if (groupBy?.length) {
-			const sealed = this._findWriteOnlyInAggregate(groupBy, controls.$select);
+		if (groupBy?.length && this._writeOnlySet.size > 0) {
+			const refs = collectQueryPaths$1(parsed, true);
+			const sealed = [
+				...refs.groupBy,
+				...refs.aggregate,
+				...refs.bucket,
+				...refs.select,
+				...refs.sort
+			].find((path) => this._writeOnlySet.has(path) && this.fieldVisibility.isVisible(path));
 			if (sealed) return new HttpError(400, `Field "${sealed}" is @db.writeOnly and cannot be aggregated`);
 		}
 		const gateError = this.checkCapabilities(parsed);
@@ -5147,9 +6033,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				insights: parsed.insights
 			});
 		}
-		const [transformedFilter, transformedSelect] = await Promise.all([this.transformFilter(clientFilter), this.transformProjection(controls.$select)]);
+		const [transformedFilter, { sealed, finish }] = await Promise.all([this.transformFilter(clientFilter), this._projectRead(controls)]);
 		const filter = this.applySearchFallback(transformedFilter, controls);
-		const sealed = this._sealControls(controls, transformedSelect);
 		if (controls.$count) return this.readable.count({
 			filter,
 			controls: {
@@ -5157,19 +6042,19 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				$select: sealed.$select
 			}
 		});
-		const select = this.widenPreferredIdProjection(sealed.$select);
-		if (select instanceof HttpError) return select;
+		const projected = finish();
+		if (projected instanceof HttpError) return projected;
 		const threshold = controls.$threshold ? Number(controls.$threshold) : void 0;
 		const queryObj = {
 			filter,
 			controls: {
 				...sealed,
-				$select: select,
+				$select: projected.select,
 				$limit: controls.$limit || 1e3,
 				$threshold: threshold
 			}
 		};
-		return (await this._runReadWithActions("query", queryObj, controls, select, async (q, strategy) => {
+		return (await this._runReadWithActions("query", queryObj, controls, projected, async (q, strategy) => {
 			switch (strategy.kind) {
 				case "vector": return { data: await (strategy.vectorField ? this.readable.vectorSearch(strategy.vectorField, strategy.vector, q) : this.readable.vectorSearch(strategy.vector, q)) };
 				case "search": return { data: await this.readable.search(strategy.term, q, strategy.index) };
@@ -5190,23 +6075,22 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		const page = Math.max(Number(controls.$page || 1), 1);
 		const size = Math.max(Number(controls.$size || 10), 1);
 		const skip = (page - 1) * size;
-		const [transformedFilter, transformedSelect] = await Promise.all([this.transformFilter(clientFilter), this.transformProjection(controls.$select)]);
+		const [transformedFilter, { sealed, finish }] = await Promise.all([this.transformFilter(clientFilter), this._projectRead(controls)]);
 		const filter = this.applySearchFallback(transformedFilter, controls);
-		const sealed = this._sealControls(controls, transformedSelect);
-		const select = this.widenPreferredIdProjection(sealed.$select);
-		if (select instanceof HttpError) return select;
+		const projected = finish();
+		if (projected instanceof HttpError) return projected;
 		const threshold = controls.$threshold ? Number(controls.$threshold) : void 0;
 		const query = {
 			filter,
 			controls: {
 				...sealed,
-				$select: select,
+				$select: projected.select,
 				$skip: skip,
 				$limit: size,
 				$threshold: threshold
 			}
 		};
-		const result = await this._runReadWithActions("pages", query, controls, select, async (q, strategy) => {
+		const result = await this._runReadWithActions("pages", query, controls, projected, async (q, strategy) => {
 			switch (strategy.kind) {
 				case "vector": return strategy.vectorField ? this.readable.vectorSearchWithCount(strategy.vectorField, strategy.vector, q) : this.readable.vectorSearchWithCount(strategy.vector, q);
 				case "search": return this.readable.searchWithCount(strategy.term, q, strategy.index);
@@ -5248,10 +6132,9 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		const gateError = this.checkCapabilities(parsed);
 		if (gateError) return gateError;
 		const clientFilter = await this._relationOverlay(parsed);
-		const [filter, transformedSelect] = await Promise.all([this.transformFilter(clientFilter), this.transformProjection(controls.$select)]);
-		const sealed = this._sealControls(controls, transformedSelect);
-		const select = this.widenPreferredIdProjection(sealed.$select);
-		if (select instanceof HttpError) return select;
+		const [filter, { sealed, finish }] = await Promise.all([this.transformFilter(clientFilter), this._projectRead(controls)]);
+		const projected = finish();
+		if (projected instanceof HttpError) return projected;
 		const paginated = controls.$page !== void 0 || controls.$size !== void 0;
 		const page = Math.max(Number(controls.$page || 1), 1);
 		const size = Math.max(Number(controls.$size || 10), 1);
@@ -5261,7 +6144,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				...sealed,
 				$center: void 0,
 				$index: void 0,
-				$select: select,
+				$select: projected.select,
 				...paginated ? {
 					$skip: (page - 1) * size,
 					$limit: size
@@ -5269,7 +6152,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			}
 		};
 		if (paginated) {
-			const result = await this._runReadWithActions("geo", queryObj, controls, select, async (q) => indexName ? this.readable.geoSearchWithCount(indexName, point, q) : this.readable.geoSearchWithCount(point, q));
+			const result = await this._runReadWithActions("geo", queryObj, controls, projected, async (q) => indexName ? this.readable.geoSearchWithCount(indexName, point, q) : this.readable.geoSearchWithCount(point, q));
 			return {
 				data: result.data,
 				page,
@@ -5278,7 +6161,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				count: result.count
 			};
 		}
-		return (await this._runReadWithActions("geo", queryObj, controls, select, async (q) => ({ data: await (indexName ? this.readable.geoSearch(indexName, point, q) : this.readable.geoSearch(point, q)) }))).data;
+		return (await this._runReadWithActions("geo", queryObj, controls, projected, async (q) => ({ data: await (indexName ? this.readable.geoSearch(indexName, point, q) : this.readable.geoSearch(point, q)) }))).data;
 	}
 	/** Parses the `$center` control: `"lng,lat"` string (or tuple) → `[number, number]`. */
 	_parseGeoCenter(raw) {
@@ -5327,21 +6210,22 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		const error = this.validateParsed(parsed, "getOne") ?? this.checkCapabilities(parsed);
 		if (error) return error;
 		await this._relationOverlay(parsed);
-		const sealed = this._sealControls(controls, await this.transformProjection(controls.$select));
-		const select = this.widenPreferredIdProjection(sealed.$select);
-		if (select instanceof HttpError) return select;
-		const [prep, overlay] = await Promise.all([this._prepareAugmentation(controls, select), this.rowOverlay()]);
+		const { sealed, finish } = await this._projectRead(controls);
+		const projected = finish();
+		if (projected instanceof HttpError) return projected;
+		const [prep, { id: resolvedId, overlay }] = await Promise.all([this._prepareAugmentation(controls, projected), this._resolveWithOverlay(id, "one")]);
 		const readControls = {
 			...sealed,
-			$select: prep?.widenedSelect ?? select
+			$select: prep?.widenedSelect ?? projected.select
 		};
-		const item = await this.returnOne(this._findRow(id, overlay, readControls));
+		const item = await this.returnOne(this._findRow(resolvedId, overlay, readControls));
 		if (item instanceof HttpError) return item;
 		const pending = this._finishRows([item], prep, {
 			endpoint: "one",
-			projection: select,
-			controls
-		});
+			projection: projected.select,
+			controls,
+			decorations: projected.read?.served ?? NO_DECORATIONS
+		}, projected.read);
 		if (pending) await pending;
 		return item;
 	}
@@ -5358,10 +6242,9 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	*/
 	async availableActionsById(id) {
 		await this.parseRequest("availableActions");
-		const own = await this._availableActions(id);
+		const { own, id: resolved } = await this._availableResolved(id);
 		if (!this._hasDelegations) return own;
-		const preferred = this.readable.preferredId;
-		return this._delegatedAvailable(own, (d) => preferred.length === 1 && d.paths.every((p) => p === preferred[0]) ? Object.fromEntries(Object.keys(d.idMap).map((f) => [f, id])) : void 0);
+		return this._delegatedAvailable(own, (d) => this._sourceIdOf(d, resolved));
 	}
 	/**
 	* **GET /meta/actions?field1=val1&…** — {@link availableActionsById} by
@@ -5371,13 +6254,50 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	async availableActions(query) {
 		await this.parseRequest("availableActions");
 		const idObj = this.extractIdShape(query);
-		const sourceIdOf = (d) => d.paths.every((p) => query[p] !== void 0) ? Object.fromEntries(Object.entries(d.idMap).map(([f, p]) => [f, query[p]])) : void 0;
 		if (idObj instanceof HttpError) {
-			if (!(await this._activeDelegations()).some((d) => sourceIdOf(d) !== void 0)) return idObj;
-			return this._delegatedAvailable({ actions: [] }, sourceIdOf);
+			if (!(await this._activeDelegations()).some((d) => this._sourceIdOf(d, void 0, query) !== void 0)) return idObj;
+			return this._delegatedAvailable({ actions: [] }, (d) => this._sourceIdOf(d, void 0, query));
 		}
-		const own = await this._availableActions(idObj);
-		return this._hasDelegations ? this._delegatedAvailable(own, sourceIdOf) : own;
+		const { own, id: resolved } = await this._availableResolved(idObj);
+		if (!this._hasDelegations) return own;
+		return this._delegatedAvailable(own, (d) => this._sourceIdOf(d, resolved, query, this._identificationFields()));
+	}
+	/** Every field of every identification (primary key and unique indexes) the view addresses a row by. */
+	_identificationFields() {
+		return [...new Set(this.idSource.identifications.flatMap((i) => i.fields))];
+	}
+	/**
+	* A delegation's source id: each source id field from the row's mapped path
+	* of the RESOLVED `id`. A path of ANY of the view's identifications
+	* (`consumed` — not just the one the request matched: `?id=1&code=T-OLD` names
+	* `code` too) is NEVER taken from the raw `?` query: that value may be an
+	* alias `resolveRowIds` rewrote, and the source would see (and answer for)
+	* it. Paths outside the identification fall back to `fallback`'s (the raw
+	* query's) value; `undefined` when a path has none.
+	*/
+	_sourceIdOf(d, id, fallback, consumed = []) {
+		const value = (path) => id?.[path] ?? (consumed.includes(path) ? void 0 : fallback?.[path]);
+		return d.paths.every((path) => value(path) !== void 0) ? Object.fromEntries(Object.entries(d.idMap).map(([field, path]) => [field, value(path)])) : void 0;
+	}
+	/**
+	* {@link _availableActions} for a request id (`names`: only those actions):
+	* through {@link resolveRowIds} (`"available"`) first, the row overlay
+	* computed once for both — and the resolved id returned as an object (a
+	* scalar is the single-field `preferredId` value) for the delegated part to
+	* derive its source id from.
+	*/
+	async _availableResolved(id, names) {
+		const { id: resolved, overlay } = await this._resolveWithOverlay(id, "available");
+		const own = await this._availableActions(resolved, overlay, names);
+		if (typeof resolved === "object") return {
+			own,
+			id: resolved
+		};
+		const preferred = this.readable.preferredId;
+		return {
+			own,
+			id: preferred.length === 1 ? { [preferred[0]]: resolved } : void 0
+		};
 	}
 	/**
 	* **POST /delegated-actions/:name** — a query target for a `@DbActionsFrom`
@@ -5549,8 +6469,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* actions are then checked on it (`purpose: "available"`) exactly like
 	* `$actions` rows.
 	*/
-	async _availableActions(id, names) {
-		const [envelopes, overlay] = await Promise.all([names ? this._envelopesNamed(names) : this._resolveAugmentEnvelopes(), this.rowOverlay()]);
+	async _availableActions(id, overlay, names) {
+		const envelopes = await (names ? this._envelopesNamed(names) : this._resolveAugmentEnvelopes());
 		if (!envelopes?.length) return { actions: [] };
 		const idKeys = id !== null && typeof id === "object" ? Object.keys(id) : [];
 		const fieldsOf = envelopes.map((e) => {
@@ -5631,7 +6551,9 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			if (fd.encrypted) entry.encrypted = true;
 			if (geoIndexedPhysical.has(fd.physicalName)) entry.geo = true;
 			if (this._writeOnlySet.has(path)) entry.writeOnly = true;
+			if (cap.groupable) entry.groupable = true;
 			if (cap.bucketable) entry.bucketable = true;
+			if (cap.numeric) entry.numeric = true;
 			if (fd.derived) entry.derived = true;
 			if (fd.computed) entry.computed = true;
 			fields[path] = entry;
@@ -5646,11 +6568,13 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			relations,
 			fields,
 			type: this.getSerializedType(),
+			...this._decorations && { decorations: this._planner.serialized(() => this.serializeForMeta(this._decorations.type)) },
 			actions: this.buildActions(),
 			crud: this.buildCrud(),
 			versionColumn: this.readable.versionColumn,
 			...capabilities.bucketUnits.length > 0 && { bucketUnits: [...capabilities.bucketUnits] },
-			aggregateFns: [...capabilities.aggregateFns]
+			aggregateFns: [...capabilities.aggregateFns],
+			aggregateExpressions: capabilities.aggregateExpressions
 		};
 	}
 	buildCrud() {
@@ -5781,7 +6705,7 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	buildCrud() {
 		return {
 			...super.buildCrud(),
-			insert: [],
+			insert: this.readable.dbAdapter?.supportsInsertIgnore() ? ["onConflict"] : [],
 			update: [],
 			replace: [],
 			remove: []
@@ -5801,7 +6725,9 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 		return data;
 	}
 	/**
-	* Intercepts delete operations. Return `undefined` to abort (500 "Not
+	* Intercepts delete operations. Receives the id {@link resolveRowIds}
+	* resolved (the one the request carried when it is not overridden; since
+	* 0.1.148). Return `undefined` to abort (500 "Not
 	* deleted"); return an `Error` instance to respond with that error.
 	* Runs outside any transaction. May be async (e.g. to resolve composite
 	* ids from external state).
@@ -5938,8 +6864,7 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	* table's transaction and an out-of-scope row is not deleted — a 404,
 	* exactly like a missing one.
 	*/
-	async _deleteOrThrow(id) {
-		const scope = await this.rowOverlay();
+	async _deleteOrThrow(id, scope) {
 		const args = scope ? [{
 			...this._removeArgs[0],
 			scope
@@ -5950,16 +6875,34 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	}
 	/**
 	* **POST /** — inserts one or many records.
+	*
+	* `?$onConflict=ignore` (since 0.1.148) skips rows colliding on the primary
+	* key or a unique index instead of answering 409. The response then is
+	* `{ insertedId?, conflict }` for an object body and
+	* `{ insertedCount, insertedIds, inserted, conflicts }` for an array body.
+	* Any other `$` control on POST answers 400.
 	*/
-	async insert(payload) {
-		await this.parseRequest("insert");
+	async insert(payload, url) {
+		const { controls } = await this.parseRequest("insert", url ?? "");
+		const onConflict = this._readOnConflict(controls);
 		assertWriteShape(payload);
+		const args = onConflict ? [{
+			...this._writeArgs[0],
+			onConflict
+		}] : this._writeArgs;
 		if (Array.isArray(payload)) {
 			const rows = await this._writeBody("insertMany", payload, true);
-			return this.table.insertMany(rows, ...this._writeArgs);
+			return this.table.insertMany(rows, ...args);
 		}
 		const row = await this._writeBody("insert", payload, false);
-		return this.table.insertOne(row, ...this._writeArgs);
+		return this.table.insertOne(row, ...args);
+	}
+	/** The only POST control: `$onConflict` (`error` | `ignore`). Anything else `$…` → 400. */
+	_readOnConflict(controls) {
+		for (const key of Object.keys(controls)) if (key !== "$onConflict") throw badRequest("", `Unsupported control "${key}" on insert`);
+		const mode = controls.$onConflict;
+		if (mode !== void 0 && mode !== "error" && mode !== "ignore") throw badRequest("", `$onConflict must be "error" or "ignore", got ${JSON.stringify(mode)}`);
+		return mode === "ignore" ? "ignore" : void 0;
 	}
 	/**
 	* **PUT /** — fully replaces one or many records matched by primary key.
@@ -6025,7 +6968,7 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 		if (typeof table.recordFilter === "function") try {
 			filter = table.recordFilter(data, this._idOpts);
 		} catch (error) {
-			if (!(error instanceof DbError)) throw error;
+			if (!(error instanceof DbError) || error.code === "SPACE_CLOSED") throw error;
 			filter = null;
 		}
 		else filter = await this.resolveRowFilter(data);
@@ -6046,8 +6989,9 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	*/
 	async remove(id) {
 		await this.parseRequest("remove");
-		const resolvedId = await this._checkHook(this.onRemove(id), "Not deleted");
-		return this._deleteOrThrow(resolvedId);
+		const { id: resolved, overlay } = await this._resolveWithOverlay(id, "remove");
+		const resolvedId = await this._checkHook(this.onRemove(resolved), "Not deleted");
+		return this._deleteOrThrow(resolvedId, overlay);
 	}
 	/**
 	* **DELETE /?field1=val1&field2=val2** — removes a record by composite key
@@ -6057,15 +7001,17 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 		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");
-		return this._deleteOrThrow(resolvedId);
+		const { id: resolved, overlay } = await this._resolveWithOverlay(idObj, "remove");
+		const resolvedId = await this._checkHook(this.onRemove(resolved), "Not deleted");
+		return this._deleteOrThrow(resolvedId, overlay);
 	}
 };
 __decorate([
 	Post(""),
 	__decorateParam(0, Body()),
+	__decorateParam(1, Url()),
 	__decorateMetadata("design:type", Function),
-	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:paramtypes", [Object, String]),
 	__decorateMetadata("design:returntype", Promise)
 ], AsDbController.prototype, "insert", null);
 __decorate([
@@ -6562,7 +7508,7 @@ function buildGateInterceptor(opts) {
 		await ctx.get(dbActionOverlaySlot);
 		if (level === "row") {
 			const verdict = judgeRow(action, disabled, await ctx.get(dbActionRowSlot));
-			if (verdict) throw new ActionDisabledError(action, await ctx.get(dbActionIdSlot), void 0, [verdictReason(verdict)]);
+			if (verdict) throw rowDisabledError(ctx, action, await ctx.get(dbActionIdSlot), verdictReason(verdict));
 			return;
 		}
 		if (await queryTargetReply(ctx, reply)) return;
@@ -6586,8 +7532,7 @@ async function gateRows(ctx, action, disabled, onDisabledRows) {
 	const existingRows = [];
 	for (const row of rows) if (row !== void 0) existingRows.push(row);
 	const verdicts = disabled ? judgeRows(action, disabled, existingRows) : void 0;
-	const failingIds = [];
-	const failingReasons = [];
+	const failing = [];
 	const passingRows = [];
 	const passingIds = [];
 	const skipped = [];
@@ -6598,8 +7543,10 @@ async function gateRows(ctx, action, disabled, onDisabledRows) {
 		const verdict = row === void 0 ? void 0 : verdicts?.[verdictIndex++];
 		if (row === void 0 || verdict) {
 			const reason = verdictReason(verdict);
-			failingIds.push(ids[i]);
-			failingReasons.push(reason);
+			failing.push({
+				id: ids[i],
+				reason
+			});
 			const skipReason = reason ?? (stale?.has(i) ? "stale" : void 0);
 			skipped.push(skipReason === void 0 ? { id: ids[i] } : {
 				id: ids[i],
@@ -6611,27 +7558,47 @@ async function gateRows(ctx, action, disabled, onDisabledRows) {
 		}
 	}
 	if (onDisabledRows === "skip") {
-		if (passingRows.length === 0) throw new ActionDisabledError(action, void 0, [...ids], failingReasons);
-		if (failingIds.length > 0) {
+		if (passingRows.length === 0) throw disabledError(ctx, action, failing);
+		if (failing.length > 0) {
 			ctx.set(dbActionRowsSlot, Promise.resolve(passingRows));
 			ctx.set(dbActionIdsSlot, Promise.resolve(passingIds));
 			ctx.set(dbActionSkippedKey, skipped);
 		}
 		return;
 	}
-	if (failingIds.length > 0) throw new ActionDisabledError(action, void 0, failingIds, failingReasons);
+	if (failing.length > 0) throw disabledError(ctx, action, failing);
+}
+/**
+* The 409 of a `'rows'` gate: every failing REQUEST id in request order, each
+* as the client sent it, with its own reason (`resolveRowIds`, since 0.1.148)
+* — {@link echoRequests} is the one place that maps resolved ids back.
+*/
+function disabledError(ctx, action, failing) {
+	const echoed = echoRequests(ctx, failing);
+	return new ActionDisabledError(action, void 0, echoed.map((f) => f.id), echoed.map((f) => f.reason));
+}
+/** The 409 of a `'row'` gate: the id as the client sent it. */
+function rowDisabledError(ctx, action, id, reason) {
+	return new ActionDisabledError(action, requestIdOf(ctx, id), void 0, [reason]);
+}
+/** The action's scope restricts (or needs the loaded rows to decide) — see `TPreScope`. */
+async function needsScopeLoad(ctx, level) {
+	const pre = await ctx.get(dbActionPreScopeSlot)(level);
+	return pre.kind === "deferred" || pre.scope !== null;
 }
 /**
 * 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), overrides
-* `actionRowScope` (since 0.1.145) or the request is a query target (since
-* 0.1.147) — verifies the requested ids 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`). Nothing to verify → no query.
+* injects the bound table and — only when there is something to verify —
+* checks the requested ids 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`). Something to verify: a row overlay (`transformOne` /
+* `transformFilter` overridden, non-empty), a non-empty `actionRowScope` for
+* the action (the hook is asked first, with the request's ids — an override
+* that restricts nothing verifies nothing; since 0.1.148), or a query target
+* (since 0.1.147). Nothing to verify → no query.
 */
 function buildThinInterceptor(opts) {
 	const { table, scope } = opts;
@@ -6642,12 +7609,12 @@ function buildThinInterceptor(opts) {
 		if (!scope) return;
 		const overlay = await ctx.get(dbActionOverlaySlot);
 		if (scope.level === "row") {
-			if (overlay || isActionScoped(ctx)) await ctx.get(dbActionRowSlot);
+			if (overlay || await needsScopeLoad(ctx, "row")) await ctx.get(dbActionRowSlot);
 			return;
 		}
 		if (await queryTargetReply(ctx, reply)) return;
 		const target = await ctx.get(dbActionQueryTargetSlot);
-		if (overlay || target || isActionScoped(ctx)) await gateRows(ctx, scope.action, void 0, scope.onDisabledRows);
+		if (overlay || target || await needsScopeLoad(ctx, "rows")) await gateRows(ctx, scope.action, void 0, scope.onDisabledRows);
 		await setMaterializedTarget(ctx);
 	}, ACTION_GATE_PRIORITY);
 }
@@ -7070,6 +8037,52 @@ function DbActionsFrom(source, opts = {}) {
 */
 const perRow = (fn) => (rows) => rows.map(fn);
 //#endregion
+//#region src/decorations/db-decorations.decorator.ts
+/**
+* Declares display-only (decoration) fields of a table or view controller —
+* values `decorateRows` computes and attaches to rows (since 0.1.148).
+*
+* `type` is a plain atscript interface (no `@db.table` / `@db.view`) whose
+* top-level props are the decorations: their `@meta.label`, `@expect.*` and
+* `@ui.*` annotations travel in `/meta.decorations`, each key is listed in
+* `/meta.fields` with `decoration: true`, and a client may name it in
+* `$select`. A decoration is never filterable, sortable or groupable, and it
+* is not part of `/meta.type` (forms and write validation never see it).
+*
+* ```ts
+* @TableController(TicketTable)
+* @DbDecorations(TicketDecorations, { requires: { ownerName: ["ownerId"] } })
+* export class TicketsController extends AsDbController<typeof TicketTable> {
+*   protected async decorateRows(rows: Record<string, unknown>[], ctx: TDbDecorateContext) {
+*     if (ctx.decorations.has("ownerName")) {
+*       // read rows[i].ownerId, set rows[i].ownerName
+*     }
+*   }
+* }
+* ```
+*
+* Validated once per class at first use (a `[moost-db]` error): the type is an
+* object interface; keys are top-level identifiers that collide with no field
+* or relation of the readable; every `requires` path is an own, readable
+* (not `@db.writeOnly`) field or a parent object of own fields (on SQL a nested
+* object is flattened to leaf columns; the hook still gets the whole object). Inherited under `@Inherit()`. Not supported on
+* value-help controllers.
+*
+* @since 0.1.148
+*/
+function DbDecorations(type, opts = {}) {
+	if (!isAnnotatedType(type)) throw new Error("[moost-db] @DbDecorations: expects a compiled atscript interface");
+	const meta = {
+		type,
+		requires: Object.fromEntries(Object.entries(opts.requires ?? {}).map(([key, paths]) => [key, [...paths ?? []]]))
+	};
+	const decorate = getAtscriptDbMate().decorate("atscript_db_decorations", meta);
+	return (target) => {
+		if (isAsValueHelpControllerSubclass(target)) throw new Error(`[moost-db] ${target.name} is a value-help controller — @DbDecorations is not supported there.`);
+		return decorate(target);
+	};
+}
+//#endregion
 //#region src/permissions/crud-handlers.ts
 /**
 * The handler method(s) serving each CRUD op on `AsDbReadableController` /
@@ -7103,4 +8116,4 @@ const VALUE_HELP_CRUD_HANDLERS = Object.freeze({
 	one: ["runGetOne", "runGetOneComposite"]
 });
 //#endregion
-export { ActionDisabledError, ActionTargetError, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DB_CRUD_HANDLERS, DEFAULT_DB_SPACE, DbAction, DbActionDefault, DbActionID, DbActionIDs, DbActionRow, DbActionRows, DbActionTarget, DbActions, DbActionsFrom, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, REL_FILTER_CLIENT_MAX_DEPTH, REL_FILTER_CLIENT_MAX_NODES, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, discoverRowLevelActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, getDbEndpoint, hasActionDelegations, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, useDbActionTarget, validationErrorTransform };
+export { ActionDisabledError, ActionTargetError, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DB_CRUD_HANDLERS, DEFAULT_DB_SPACE, DbAction, DbActionDefault, DbActionID, DbActionIDs, DbActionRow, DbActionRows, DbActionTarget, DbActions, DbActionsFrom, DbDecorations, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, REL_FILTER_CLIENT_MAX_DEPTH, REL_FILTER_CLIENT_MAX_NODES, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, closeDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, discoverRowLevelActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, getDbEndpoint, hasActionDelegations, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, useDbActionTarget, validationErrorTransform };