@atscript/moost-db 0.1.58 → 0.1.59

package/dist/index.mjs

@@ -98,7 +98,7 @@ var SelectControlDto = class {
 		throwFeatureDisabled("JSON Schema", "jsonSchema", "emit.jsonSchema");
 	}
 };
-defineAnnotatedType("object", QueryControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$count", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$vector", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$threshold", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type);
+defineAnnotatedType("object", QueryControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$count", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$vector", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$threshold", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
 defineAnnotatedType("object", PagesControlsDto).prop("$page", defineAnnotatedType().designType("string").tags("string").annotate("expect.pattern", {
 	pattern: "^\\d+$",
 	flags: "u",
@@ -107,8 +107,8 @@ defineAnnotatedType("object", PagesControlsDto).prop("$page", defineAnnotatedTyp
 	pattern: "^\\d+$",
 	flags: "u",
 	message: "Expected positive number"
-}, true).optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$vector", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$threshold", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type);
-defineAnnotatedType("object", GetOneControlsDto).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type);
+}, true).optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$vector", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$threshold", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
+defineAnnotatedType("object", GetOneControlsDto).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
 defineAnnotatedType("object", WithRelationDto).prop("name", defineAnnotatedType().designType("string").tags("string").$type).prop("filter", defineAnnotatedType().refTo(WithFilterDto).optional().$type).prop("controls", defineAnnotatedType().refTo(WithRelationControlsDto).optional().$type).prop("insights", defineAnnotatedType().refTo(WithFilterDto).optional().$type);
 defineAnnotatedType("object", WithRelationControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type);
 defineAnnotatedType("object", WithFilterDto).propPattern(/./, defineAnnotatedType("union").item(defineAnnotatedType().designType("string").tags("string").$type).item(defineAnnotatedType().designType("number").tags("number").$type).item(defineAnnotatedType().designType("boolean").tags("boolean").$type).item(defineAnnotatedType().designType("null").tags("null").$type).item(defineAnnotatedType().refTo(WithFilterDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithFilterDto).$type).$type).$type);
@@ -209,7 +209,7 @@ const WARN_PREFIX = "[moost-db actions]";
 const MOOST_DB_ACTION = "atscript_db_action";
 /** Class-level metadata key — written by `@DbActions` and the level-pinned shortcuts. Stored as an array; decorators accumulate. */
 const MOOST_DB_ACTIONS = "atscript_db_actions";
-/** Param-level metadata key — written by `@DbActionPK()` / `@DbActionPKs()`. Drives level inference. */
+/** Param-level metadata key — written by `@DbActionID()` / `@DbActionIDs()`. Drives level inference. */
 const MOOST_DB_ACTION_PARAM = "atscript_db_action_param";
 /** Param-level marker keys — written by `@DbActionRow()` / `@DbActionRows()`. */
 const MOOST_DB_ACTION_ROW = "atscript_db_action_row";
@@ -239,8 +239,8 @@ function scanParamLevel(params) {
 	let hasBody = false;
 	for (const p of params) {
 		const kind = p[MOOST_DB_ACTION_PARAM];
-		if (kind === "pk") single = true;
-		else if (kind === "pks") multi = true;
+		if (kind === "id") single = true;
+		else if (kind === "ids") multi = true;
 		if (p["atscript_db_action_row"]) {
 			single = true;
 			hasRowParam = true;
@@ -261,11 +261,7 @@ function scanParamLevel(params) {
 }
 //#endregion
 //#region src/actions/discover.ts
-/**
-* Pure structural-copy fields. `disabled` and `requiredFields` are handled
-* as special cases in {@link emitInfo} so the function-to-string transform
-* stays out of the copy loop.
-*/
+/** Structural-copy fields; `disabled` is handled separately in {@link emitInfo} (function-to-string transform). */
 const OPTIONAL_FIELDS = [
 	"icon",
 	"intent",
@@ -276,27 +272,29 @@ const OPTIONAL_FIELDS = [
 	"shortcut"
 ];
 const actionsCache = /* @__PURE__ */ new WeakMap();
-/**
-* Discover all actions declared on a controller and produce the `/meta` array.
-* Reads class + method metadata via `getMoostMate()` and resolves bound POST
-* paths through the Moost controller overview.
-*
-* Result is memoized per controller constructor — discovery walks every
-* handler entry and reads decorator metadata, which is wasted work to repeat
-* across instances.
-*/
+const rowLevelActionsCache = /* @__PURE__ */ new WeakMap();
+/** Discover actions on a controller, memoized per ctor. `info`-only callers map `e => e.info`. */
 function discoverActions(controllerCtor, app, logger) {
 	const cached = actionsCache.get(controllerCtor);
 	if (cached) return cached;
 	const overview = app.getControllersOverview?.()?.find((o) => o.type === controllerCtor);
 	const out = [];
-	collectMethodActions(controllerCtor, overview, logger, out);
-	collectClassActions(controllerCtor, logger, out);
+	const seen = /* @__PURE__ */ new Set();
+	collectMethodActions(controllerCtor, overview, logger, out, seen);
+	collectClassActions(controllerCtor, logger, out, seen);
 	applyDefaultPerLevel(out, logger);
 	actionsCache.set(controllerCtor, out);
 	return out;
 }
-function collectMethodActions(ctor, overview, logger, out) {
+/** Row/rows-level subset of {@link discoverActions}; memoized per ctor. */
+function discoverRowLevelActions(controllerCtor, app, logger) {
+	const cached = rowLevelActionsCache.get(controllerCtor);
+	if (cached) return cached;
+	const filtered = discoverActions(controllerCtor, app, logger).filter((e) => e.info.level === "row" || e.info.level === "rows");
+	rowLevelActionsCache.set(controllerCtor, filtered);
+	return filtered;
+}
+function collectMethodActions(ctor, overview, logger, out, seen) {
 	if (!overview) return;
 	const byMethod = /* @__PURE__ */ new Map();
 	for (const h of overview.handlers) {
@@ -315,13 +313,17 @@ function collectMethodActions(ctor, overview, logger, out) {
 		const levelInfer = inferMethodLevel(methodMeta.params ?? [], action.name, logger);
 		if (!levelInfer) continue;
 		if (levelInfer.bodyConflict) {
-			logger.warn(`${WARN_PREFIX} action "${action.name}" cannot mix @DbActionPK*/@DbActionPKs/@DbActionRow*/@DbActionRows with @Body() — dropping`);
+			logger.warn(`${WARN_PREFIX} action "${action.name}" cannot mix @DbActionID*/@DbActionIDs/@DbActionRow*/@DbActionRows with @Body() — dropping`);
 			continue;
 		}
 		if (levelInfer.level === "table" && action.opts.disabled !== void 0) {
 			logger.warn(`${WARN_PREFIX} action "${action.name}" — \`disabled\` is not allowed at the 'table' level; row-state predicates are not meaningful when no row is in scope. Use @Authenticate / arbac for table-level access — dropping`);
 			continue;
 		}
+		if (action.opts.disabled !== void 0 && !isNonEmptyStringArray(action.opts.requiredFields)) {
+			logger.warn(`${WARN_PREFIX} action "${action.name}" — \`disabled\` requires a non-empty \`requiredFields\` array (the predicate's field dependencies must be declared explicitly) — dropping`);
+			continue;
+		}
 		if (action.opts.disabled !== void 0 || levelInfer.hasRowParam) {
 			const extendsReadable = isAsDbReadableControllerSubclass(ctor);
 			const hasOptsTable = action.opts.table != null;
@@ -345,6 +347,10 @@ function collectMethodActions(ctor, overview, logger, out) {
 			logger.warn(`${WARN_PREFIX} action "${action.name}" requires a label (opts.label or @Label) — dropping`);
 			continue;
 		}
+		if (seen.has(action.name)) {
+			logger.warn(`${WARN_PREFIX} duplicate action name "${action.name}" within controller — dropping the second declaration`);
+			continue;
+		}
 		const info = {
 			name: action.name,
 			label,
@@ -352,14 +358,18 @@ function collectMethodActions(ctor, overview, logger, out) {
 			processor: "backend",
 			value: path
 		};
-		emitInfo(info, action.opts, action.name, logger);
-		out.push(info);
+		emitInfo(info, action.opts);
+		seen.add(action.name);
+		out.push({
+			info,
+			raw: action.opts
+		});
 	}
 }
 function inferMethodLevel(params, actionName, logger) {
 	const scan = scanParamLevel(params);
 	if (scan.single && scan.multi) {
-		logger.warn(`${WARN_PREFIX} action "${actionName}" mixes single-cardinality and multi-cardinality decorators (@DbActionPK / @DbActionRow vs @DbActionPKs / @DbActionRows) — dropping`);
+		logger.warn(`${WARN_PREFIX} action "${actionName}" mixes single-cardinality and multi-cardinality decorators (@DbActionID / @DbActionRow vs @DbActionIDs / @DbActionRows) — dropping`);
 		return null;
 	}
 	return {
@@ -368,12 +378,22 @@ function inferMethodLevel(params, actionName, logger) {
 		hasRowParam: scan.hasRowParam
 	};
 }
-function collectClassActions(ctor, logger, out) {
+function collectClassActions(ctor, logger, out, seen) {
 	const list = getMoostMate().read(ctor)?.[MOOST_DB_ACTIONS];
 	if (!list) return;
 	for (const { name, entry } of list) {
+		if (seen.has(name)) {
+			logger.warn(`${WARN_PREFIX} duplicate action name "${name}" within controller — dropping the second declaration`);
+			continue;
+		}
 		const built = buildClassEntry(name, entry, logger);
-		if (built) out.push(built);
+		if (built) {
+			seen.add(name);
+			out.push({
+				info: built,
+				raw: entry
+			});
+		}
 	}
 }
 function buildClassEntry(name, entry, logger) {
@@ -390,6 +410,10 @@ function buildClassEntry(name, entry, logger) {
 		logger.warn(`${WARN_PREFIX} class-level action "${name}" — \`disabled\` is not allowed at the 'table' level — dropping`);
 		return null;
 	}
+	if (entry.disabled !== void 0 && !isNonEmptyStringArray(entry.requiredFields)) {
+		logger.warn(`${WARN_PREFIX} class-level action "${name}" — \`disabled\` requires a non-empty \`requiredFields\` array (the predicate's field dependencies must be declared explicitly) — dropping`);
+		return null;
+	}
 	const processor = entry.processor;
 	let value;
 	if (processor === "navigate" || processor === "backend") {
@@ -417,39 +441,27 @@ function buildClassEntry(name, entry, logger) {
 		processor,
 		value
 	};
-	emitInfo(info, entry, name, logger);
+	emitInfo(info, entry);
 	return info;
 }
-function applyDefaultPerLevel(actions, logger) {
+function applyDefaultPerLevel(envelopes, logger) {
 	const winners = /* @__PURE__ */ new Map();
-	for (const a of actions) {
-		if (!a.default) continue;
-		const existing = winners.get(a.level);
+	for (const { info } of envelopes) {
+		if (!info.default) continue;
+		const existing = winners.get(info.level);
 		if (existing) {
-			a.default = false;
-			logger.warn(`${WARN_PREFIX} duplicate default action at level "${a.level}": "${existing}" wins, "${a.name}" demoted`);
-		} else winners.set(a.level, a.name);
+			info.default = false;
+			logger.warn(`${WARN_PREFIX} duplicate default action at level "${info.level}": "${existing}" wins, "${info.name}" demoted`);
+		} else winners.set(info.level, info.name);
 	}
 }
-/**
-* Emit structural-copy fields plus `disabled` (stringified) and
-* `requiredFields` (forwarded verbatim — server doesn't auto-derive).
-* `requiredFields` without `disabled` is dropped with a warning before the
-* structural copy runs, so method-decorator and class-level-dict origins
-* stay symmetric.
-*/
-function emitInfo(info, source, name, logger) {
+/** Emit structural-copy fields plus stringified `disabled`. `requiredFields` is server-internal (never on the wire). */
+function emitInfo(info, source) {
 	const disabled = source.disabled;
 	const hasDisabled = typeof disabled === "function";
-	let requiredFields = source.requiredFields;
-	if (!hasDisabled && requiredFields !== void 0) {
-		logger.warn(`${WARN_PREFIX} action "${name}" has \`requiredFields\` without \`disabled\` — \`requiredFields\` is purely a UI hint and meaningless without a predicate. Dropping \`requiredFields\` from /meta.`);
-		requiredFields = void 0;
-	}
 	copyOptionalFields(info, source);
 	if (Array.isArray(info.promptText)) info.promptText = info.promptText.slice();
 	if (hasDisabled) info.disabled = disabled.toString();
-	if (Array.isArray(requiredFields)) info.requiredFields = requiredFields.slice();
 }
 function copyOptionalFields(info, source) {
 	for (const key of OPTIONAL_FIELDS) {
@@ -457,6 +469,9 @@ function copyOptionalFields(info, source) {
 		if (value !== void 0) info[key] = value;
 	}
 }
+function isNonEmptyStringArray(value) {
+	return Array.isArray(value) && value.length > 0 && value.every((v) => typeof v === "string");
+}
 //#endregion
 //#region \0@oxc-project+runtime@0.120.0/helpers/decorateMetadata.js
 function __decorateMetadata(k, v) {
@@ -639,6 +654,7 @@ let AsReadableController = class AsReadableController {
 			vectorSearchable: false,
 			searchIndexes: [],
 			primaryKeys: [],
+			preferredId: [],
 			relations: [],
 			fields: {},
 			type: this.getSerializedType(),
@@ -652,7 +668,7 @@ let AsReadableController = class AsReadableController {
 	* controllers — see {@link AsValueHelpController#buildMetaResponse}.
 	*/
 	buildActions() {
-		return discoverActions(this.constructor, this.app, this.logger);
+		return discoverActions(this.constructor, this.app, this.logger).map((e) => e.info);
 	}
 	/**
 	* Declares the built-in CRUD operations this controller exposes. Subclasses
@@ -687,6 +703,80 @@ AsReadableController = __decorate([UseValidationErrorTransform(), __decorateMeta
 	Object
 ])], AsReadableController);
 //#endregion
+//#region src/actions/verdict.ts
+/** Assert that a `disabled` predicate returned a `boolean[]` of the expected length; throws HTTP 500 otherwise. */
+function assertVerdictLength(action, verdicts, expected) {
+	if (!Array.isArray(verdicts) || verdicts.length !== expected) throw new HttpError(500, `Action "${action}" disabled predicate returned an invalid verdict array`);
+}
+//#endregion
+//#region src/actions/list-augmenter.ts
+const candidateCache = /* @__PURE__ */ new WeakMap();
+/** WHY: envelopes are immutable post-discovery, so derived `Candidate` shape is cached for the envelope's lifetime; `null` sentinel pins table-level skip. */
+function getCandidate(e) {
+	const cached = candidateCache.get(e);
+	if (cached !== void 0) return cached;
+	if (e.info.level !== "row" && e.info.level !== "rows") {
+		candidateCache.set(e, null);
+		return null;
+	}
+	const raw = e.raw;
+	const c = {
+		envelope: e,
+		disabledFn: typeof raw.disabled === "function" ? raw.disabled : void 0,
+		requiredFields: Array.isArray(raw.requiredFields) ? raw.requiredFields : []
+	};
+	candidateCache.set(e, c);
+	return c;
+}
+function collectCandidates(envelopes) {
+	const out = [];
+	for (const e of envelopes) {
+		const c = getCandidate(e);
+		if (c !== null) out.push(c);
+	}
+	return out;
+}
+function computeStripFields(candidates, resolvedProjection) {
+	let userSet = null;
+	let strip = null;
+	for (const c of candidates) for (const f of c.requiredFields) {
+		if (userSet === null) userSet = new Set(resolvedProjection);
+		if (userSet.has(f)) continue;
+		if (strip === null) strip = /* @__PURE__ */ new Set();
+		strip.add(f);
+	}
+	return strip;
+}
+function augmentRowsWithActions(args) {
+	const { envelopes, rows, resolvedProjection } = args;
+	const candidates = collectCandidates(envelopes);
+	if (candidates.length === 0 || rows.length === 0) return rows;
+	const verdicts = candidates.map((c) => {
+		if (!c.disabledFn) return void 0;
+		const out = c.disabledFn(rows);
+		assertVerdictLength(c.envelope.info.name, out, rows.length);
+		return out;
+	});
+	for (let i = 0; i < rows.length; i++) {
+		const row = rows[i];
+		const names = [];
+		for (let j = 0; j < candidates.length; j++) {
+			const v = verdicts[j];
+			if (v === void 0) {
+				names.push(candidates[j].envelope.info.name);
+				continue;
+			}
+			if (!v[i]) names.push(candidates[j].envelope.info.name);
+		}
+		row.$actions = names;
+	}
+	if (resolvedProjection !== null) {
+		const stripFields = computeStripFields(candidates, resolvedProjection);
+		if (stripFields !== null) for (const row of rows) for (const f of stripFields) delete row[f];
+	}
+	return rows;
+}
+//#endregion
 //#region src/decorators.ts
 /**
 * DI token under which the {@link AtscriptDbReadable} instance
@@ -781,10 +871,17 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	/** Reference to the underlying readable (table or view). */
 	readable;
 	_gates;
+	_preferredIdSet;
+	_compositeIdShapes;
+	_overlayIsNoOp;
 	constructor(readable, app) {
 		super(readable.type, readable.tableName, app, readable.isView ? "view" : "table");
 		this.readable = readable;
 		this._gates = this._buildGates();
+		this._preferredIdSet = new Set(readable.preferredId ?? []);
+		this._compositeIdShapes = (readable.identifications ?? []).filter((id) => id.fields.length >= 2);
+		const defaultOverlay = AsReadableController.prototype.applyMetaOverlay;
+		this._overlayIsNoOp = this.applyMetaOverlay === defaultOverlay;
 	}
 	_buildGates() {
 		const meta = this.readable.type.metadata;
@@ -852,16 +949,169 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	transformProjection(projection) {
 		return projection;
 	}
+	widenPreferredIdProjection(projection) {
+		if (this._preferredIdSet.size === 0 || projection === void 0) return projection;
+		if (Array.isArray(projection)) return this._widenArrayProjection(projection);
+		return this._widenMapProjection(projection);
+	}
+	_widenArrayProjection(projection) {
+		const stringItems = /* @__PURE__ */ new Set();
+		for (const item of projection) if (typeof item === "string") stringItems.add(item);
+		let allPresent = true;
+		for (const field of this._preferredIdSet) if (!stringItems.has(field)) {
+			allPresent = false;
+			break;
+		}
+		if (allPresent) return projection;
+		const out = [...projection];
+		for (const field of this._preferredIdSet) if (!stringItems.has(field)) out.push(field);
+		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 (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;
+			for (const field of this._preferredIdSet) if (!included.has(field)) {
+				allPresent = false;
+				break;
+			}
+			if (allPresent) return projection;
+			const widened = {};
+			for (const k of included) widened[k] = 1;
+			for (const field of this._preferredIdSet) widened[field] = 1;
+			return widened;
+		}
+		const widened = {};
+		for (const fd of this.readable.fieldDescriptors) if (!fd.ignored && !excluded.has(fd.path)) widened[fd.path] = 1;
+		for (const field of this._preferredIdSet) widened[field] = 1;
+		return widened;
+	}
+	/** WHY: the URL parser only auto-coerces `$count`; every other boolean control reaches us as `"true"`/`"1"` and would fail DTO validation. */
+	_coerceActionsControl(controls) {
+		const v = controls.$actions;
+		if (typeof v === "string") controls.$actions = v === "true" || v === "1" || v === "";
+	}
+	/** Normalize a post-`widenPreferredIdProjection` $select into `string[] | null` (`null` = all fields). */
+	_resolveProjectionForAugmenter(select) {
+		if (select === void 0) return null;
+		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;
+		if (excluded.length > 0 && included.length === 0) {
+			const excludedSet = new Set(excluded);
+			const out = [];
+			for (const fd of this.readable.fieldDescriptors) if (!fd.ignored && !excludedSet.has(fd.path)) out.push(fd.path);
+			return out;
+		}
+		throw new HttpError(500, "[moost-db] mixed inclusion/exclusion projection reached augmenter; widenPreferredIdProjection should have rejected it");
+	}
+	/** WHY: filter row/rows envelopes by the per-request `applyMetaOverlay` action set; skip `meta()` when overlay is identity. */
+	async _resolveAugmentEnvelopes() {
+		const rowLevelEnvelopes = discoverRowLevelActions(this.constructor, this.app, this.logger);
+		if (rowLevelEnvelopes.length === 0) return null;
+		if (this._overlayIsNoOp) return rowLevelEnvelopes;
+		const overlayMeta = await this.meta();
+		const allowedNames = new Set(overlayMeta.actions.map((a) => a.name));
+		const filtered = rowLevelEnvelopes.filter((e) => allowedNames.has(e.info.name));
+		return filtered.length === 0 ? null : filtered;
+	}
+	/** Returns a widened `$select` only when at least one `requiredFields` entry is missing; `null` means "no widening needed". */
+	_widenSelectForActions(envelopes, baseSelect) {
+		let resultSet = null;
+		let result = null;
+		for (const e of envelopes) {
+			const raw = e.raw;
+			if (!Array.isArray(raw.requiredFields)) continue;
+			for (const f of raw.requiredFields) {
+				if (resultSet ? resultSet.has(f) : baseSelect.includes(f)) continue;
+				if (resultSet === null) {
+					resultSet = new Set(baseSelect);
+					result = [...baseSelect];
+				}
+				resultSet.add(f);
+				result.push(f);
+			}
+		}
+		return result;
+	}
+	async _prepareAugmentation(controls, select) {
+		if (!controls.$actions) return null;
+		const envelopes = await this._resolveAugmentEnvelopes();
+		if (envelopes === null) return null;
+		const resolvedProjection = this._resolveProjectionForAugmenter(select);
+		return {
+			envelopes,
+			resolvedProjection,
+			widenedSelect: resolvedProjection === null ? null : this._widenSelectForActions(envelopes, resolvedProjection)
+		};
+	}
+	async _resolveReadStrategy(controls) {
+		const searchTerm = controls.$search;
+		const indexName = controls.$index;
+		const vectorField = controls.$vector;
+		if (vectorField !== void 0 && searchTerm) return {
+			kind: "vector",
+			vector: await this.computeEmbedding(searchTerm, vectorField || void 0),
+			vectorField
+		};
+		if (searchTerm && this.readable.isSearchable()) return {
+			kind: "search",
+			term: searchTerm,
+			index: indexName
+		};
+		return { kind: "plain" };
+	}
+	/**
+	* Shared `query` / `pages` pipeline: prepare actions augmentation + read
+	* strategy in parallel, pre-widen $select for `requiredFields`, run
+	* `exec`, and augment `result.data` with `$actions` when the request set
+	* `$actions=true`. Caller dispatches the strategy to its read-method
+	* family (count vs no-count).
+	*/
+	async _runReadWithActions(queryObj, controls, select, exec) {
+		const [prep, strategy] = await Promise.all([this._prepareAugmentation(controls, select), this._resolveReadStrategy(controls)]);
+		const result = await exec(prep?.widenedSelect ? {
+			...queryObj,
+			controls: {
+				...queryObj.controls,
+				$select: prep.widenedSelect
+			}
+		} : queryObj, strategy);
+		if (!prep) return result;
+		result.data = augmentRowsWithActions({
+			envelopes: prep.envelopes,
+			rows: result.data,
+			resolvedProjection: prep.resolvedProjection
+		});
+		return result;
+	}
 	/**
 	* Extracts a composite identifier object from query params.
 	* Tries composite primary key first, then compound unique indexes.
 	*/
 	extractCompositeId(query) {
-		const pkFields = this.readable.primaryKeys;
-		if (pkFields.length > 1) {
+		for (const id of this._compositeIdShapes) {
 			const idObj = {};
 			let allPresent = true;
-			for (const field of pkFields) {
+			for (const field of id.fields) {
 				if (query[field] === void 0) {
 					allPresent = false;
 					break;
@@ -870,19 +1120,6 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			}
 			if (allPresent) return idObj;
 		}
-		for (const index of this.readable.indexes.values()) {
-			if (index.type !== "unique" || index.fields.length < 2) continue;
-			const idObj = {};
-			let allPresent = true;
-			for (const indexField of index.fields) {
-				if (query[indexField.name] === void 0) {
-					allPresent = false;
-					break;
-				}
-				idObj[indexField.name] = query[indexField.name];
-			}
-			if (allPresent) return idObj;
-		}
 		return new HttpError(400, "Query params do not match any composite primary key or compound unique index");
 	}
 	/**
@@ -891,6 +1128,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	async query(url) {
 		const parsed = this.parseQueryString(url);
 		const controls = parsed.controls;
+		this._coerceActionsControl(controls);
 		if (controls.$groupBy?.length) {
 			if (controls.$with?.length) return new HttpError(400, "Cannot combine $with and $groupBy in the same query");
 			if (parsed.insights) {
@@ -908,17 +1146,16 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		if (error) return error;
 		const gateError = this.checkGates(parsed.filter, controls, this._gates);
 		if (gateError) return gateError;
-		const [filter, select] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
+		const [filter, rawSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
 		if (controls.$count) return this.readable.count({
 			filter,
 			controls: {
 				...controls,
-				$select: select
+				$select: rawSelect
 			}
 		});
-		const searchTerm = controls.$search;
-		const indexName = controls.$index;
-		const vectorField = controls.$vector;
+		const select = this.widenPreferredIdProjection(rawSelect);
+		if (select instanceof HttpError) return select;
 		const threshold = controls.$threshold ? Number(controls.$threshold) : void 0;
 		const queryObj = {
 			filter,
@@ -929,19 +1166,20 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 				$threshold: threshold
 			}
 		};
-		if (vectorField !== void 0 && searchTerm) {
-			const vector = await this.computeEmbedding(searchTerm, vectorField || void 0);
-			if (vectorField) return this.readable.vectorSearch(vectorField, vector, queryObj);
-			return this.readable.vectorSearch(vector, queryObj);
-		}
-		if (searchTerm && this.readable.isSearchable()) return this.readable.search(searchTerm, queryObj, indexName);
-		return this.readable.findMany(queryObj);
+		return (await this._runReadWithActions(queryObj, controls, select, 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) };
+				case "plain": return { data: await this.readable.findMany(q) };
+			}
+		})).data;
 	}
 	/**
 	* **GET /pages** — returns paginated records with metadata.
 	*/
 	async pages(url) {
 		const parsed = this.parseQueryString(url);
+		this._coerceActionsControl(parsed.controls);
 		const error = this.validateParsed(parsed, "pages");
 		if (error) return error;
 		const controls = parsed.controls;
@@ -950,10 +1188,9 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const page = Math.max(Number(controls.$page || 1), 1);
 		const size = Math.max(Number(controls.$size || 10), 1);
 		const skip = (page - 1) * size;
-		const [filter, select] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
-		const searchTerm = controls.$search;
-		const indexName = controls.$index;
-		const vectorField = controls.$vector;
+		const [filter, rawSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
+		const select = this.widenPreferredIdProjection(rawSelect);
+		if (select instanceof HttpError) return select;
 		const threshold = controls.$threshold ? Number(controls.$threshold) : void 0;
 		const query = {
 			filter,
@@ -965,13 +1202,13 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 				$threshold: threshold
 			}
 		};
-		let result;
-		if (vectorField !== void 0 && searchTerm) {
-			const vector = await this.computeEmbedding(searchTerm, vectorField || void 0);
-			if (vectorField) result = await this.readable.vectorSearchWithCount(vectorField, vector, query);
-			else result = await this.readable.vectorSearchWithCount(vector, query);
-		} else if (searchTerm && this.readable.isSearchable()) result = await this.readable.searchWithCount(searchTerm, query, indexName);
-		else result = await this.readable.findManyWithCount(query);
+		const result = await this._runReadWithActions(query, controls, select, 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);
+				case "plain": return this.readable.findManyWithCount(q);
+			}
+		});
 		return {
 			data: result.data,
 			page,
@@ -985,15 +1222,14 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	*/
 	async getOne(id, url) {
 		const parsed = this.parseQueryString(url);
+		this._coerceActionsControl(parsed.controls);
 		if (Object.keys(parsed.filter).length > 0) return new HttpError(400, "Filtering is not allowed for \"one\" endpoint");
 		const error = this.validateParsed(parsed, "getOne");
 		if (error) return error;
-		const select = await this.transformProjection(parsed.controls.$select);
-		const controls = {
-			...parsed.controls,
-			$select: select
-		};
-		return this.returnOne(this.readable.findById(id, { controls }));
+		const rawSelect = await this.transformProjection(parsed.controls.$select);
+		const select = this.widenPreferredIdProjection(rawSelect);
+		if (select instanceof HttpError) return select;
+		return this._findByIdAndAugment(id, parsed.controls, select);
 	}
 	/**
 	* **GET /one?field1=val1&field2=val2** — retrieves a single record by composite key
@@ -1003,12 +1239,29 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const idObj = this.extractCompositeId(query);
 		if (idObj instanceof HttpError) return idObj;
 		const parsed = this.parseQueryString(url);
-		const select = await this.transformProjection(parsed.controls.$select);
+		this._coerceActionsControl(parsed.controls);
+		const rawSelect = await this.transformProjection(parsed.controls.$select);
+		const select = this.widenPreferredIdProjection(rawSelect);
+		if (select instanceof HttpError) return select;
+		return this._findByIdAndAugment(idObj, parsed.controls, select);
+	}
+	async _findByIdAndAugment(id, parsedControls, select) {
+		const prep = await this._prepareAugmentation(parsedControls, select);
+		const initialSelect = prep?.widenedSelect ?? select;
 		const controls = {
-			...parsed.controls,
-			$select: select
+			...parsedControls,
+			$select: initialSelect
 		};
-		return this.returnOne(this.readable.findById(idObj, { controls }));
+		const row = await this.readable.findById(id, { controls });
+		const item = await this.returnOne(Promise.resolve(row));
+		if (item instanceof HttpError) return item;
+		if (!prep) return item;
+		const [augmented] = augmentRowsWithActions({
+			envelopes: prep.envelopes,
+			rows: [item],
+			resolvedProjection: prep.resolvedProjection
+		});
+		return augmented;
 	}
 	/**
 	* **GET /meta** — returns table/view metadata for UI.
@@ -1042,6 +1295,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			vectorSearchable: this.readable.isVectorSearchable(),
 			searchIndexes: this.readable.getSearchIndexes(),
 			primaryKeys: [...this.readable.primaryKeys],
+			preferredId: [...this.readable.preferredId],
 			relations,
 			fields,
 			type: this.getSerializedType(),
@@ -1340,6 +1594,7 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 			vectorSearchable: false,
 			searchIndexes: [],
 			primaryKeys: this.primaryKey ? [this.primaryKey] : [],
+			preferredId: this.primaryKey ? [this.primaryKey] : [],
 			relations: [],
 			fields,
 			type: this.getSerializedType(),
@@ -1554,8 +1809,8 @@ function applySelect(rows, select) {
 }
 //#endregion
 //#region src/actions/action-disabled-error.ts
-function buildMessage(action, pks) {
-	if (pks !== void 0) return `Action "${action}" is disabled for ${pks.length} of the selected rows`;
+function buildMessage(action, ids) {
+	if (ids !== void 0) return `Action "${action}" is disabled for ${ids.length} of the selected rows`;
 	return `Action "${action}" is disabled for this row`;
 }
 /**
@@ -1563,95 +1818,110 @@ function buildMessage(action, pks) {
 * with Moost's existing error mapper to produce HTTP 409 with the wire body
 * defined by {@link ActionDisabledErrorBody}.
 *
-* - `'row'`-level rejection: pass `(action, pk)` — the body emits `pk`.
-* - `'rows'`-level rejection: pass `(action, undefined, pks)` — the body
-*   emits `pks` (the FULL list of failing PKs in reject mode; the FULL list
-*   of request PKs in skip mode with zero survivors).
+* - `'row'`-level rejection: pass `(action, id)` — the body emits `id`.
+* - `'rows'`-level rejection: pass `(action, undefined, ids)` — the body
+*   emits `ids` (the FULL list of failing IDs in reject mode; the FULL list
+*   of request IDs in skip mode with zero survivors).
 */
 var ActionDisabledError = class extends HttpError {
 	name = "ActionDisabledError";
-	constructor(action, pk, pks) {
+	constructor(action, id, ids) {
 		const body = {
 			name: "ActionDisabledError",
-			message: buildMessage(action, pks),
+			message: buildMessage(action, ids),
 			statusCode: 409,
 			action
 		};
-		if (pks !== void 0) body.pks = pks;
-		else if (pk !== void 0) body.pk = pk;
+		if (ids !== void 0) body.ids = ids;
+		else if (id !== void 0) body.id = id;
 		super(409, body);
 	}
 };
 //#endregion
-//#region src/actions/pk-validation.ts
-function isPkValidationSource(value) {
+//#region src/actions/current-action.ts
+/** Read the current action's `TDbActionMeta` from the wook context. Returns undefined outside a controller (e.g. direct-wook test paths). */
+function readCurrentActionMeta(ctx) {
+	let ctrl;
+	let methodName;
+	try {
+		const cc = useControllerContext(ctx);
+		ctrl = cc.getController();
+		methodName = cc.getMethod();
+	} catch {
+		return;
+	}
+	if (!ctrl || !methodName) return void 0;
+	return getMoostMate().read(ctrl.constructor, methodName)?.[MOOST_DB_ACTION];
+}
+//#endregion
+//#region src/actions/id-validation.ts
+const SOURCE_CACHE = /* @__PURE__ */ new WeakMap();
+function getSourceCache(source) {
+	let cache = SOURCE_CACHE.get(source);
+	if (cache) return cache;
+	const identifications = source.getIdentifications();
+	const byKeySig = /* @__PURE__ */ new Map();
+	for (const ident of identifications) byKeySig.set(fieldsSig(ident.fields), ident);
+	const fieldByName = /* @__PURE__ */ new Map();
+	for (const fd of source.fieldDescriptors) fieldByName.set(fd.path, fd);
+	cache = {
+		byKeySig,
+		fieldByName,
+		formatted: identifications.map((id) => `[${id.fields.join(", ")}]`).join(", ")
+	};
+	SOURCE_CACHE.set(source, cache);
+	return cache;
+}
+function fieldsSig(fields) {
+	return fields.toSorted().join("");
+}
+function isIdValidationSource(value) {
 	if (!value || typeof value !== "object") return false;
 	const v = value;
-	return Array.isArray(v.primaryKeys) && Array.isArray(v.fieldDescriptors);
+	return typeof v.getIdentifications === "function" && Array.isArray(v.fieldDescriptors);
 }
-/**
-* Validate a JSON-decoded body against a single-row PK shape (scalar or
-* composite). Throws {@link ValidatorError} with structured `errors` so the
-* existing validation interceptor returns HTTP 400.
-*/
-function validateSinglePk(body, source, path = "") {
-	const errors = collectPkErrors(body, source, path);
+function validateSingleId(body, source, path = "") {
+	const errors = collectIdErrors(body, source, path);
 	if (errors.length > 0) throw new ValidatorError(errors);
+	return body;
 }
-/**
-* Validate a JSON-decoded body against an array of PK shapes (`@DbActionPKs`).
-* The body MUST be an array; each element is validated against the PK schema.
-*/
-function validateMultiPk(body, source) {
+function validateMultiId(body, source) {
 	if (!Array.isArray(body)) throw new ValidatorError([{
 		path: "",
-		message: "Expected JSON array of primary keys",
+		message: "Expected JSON array of identifier objects",
 		details: []
 	}]);
 	const errors = [];
-	for (let i = 0; i < body.length; i++) errors.push(...collectPkErrors(body[i], source, `[${i}]`));
+	for (let i = 0; i < body.length; i++) errors.push(...collectIdErrors(body[i], source, `[${i}]`));
 	if (errors.length > 0) throw new ValidatorError(errors);
+	return body;
 }
-function collectPkErrors(value, source, pathPrefix) {
-	const pkFields = source.primaryKeys;
-	if (pkFields.length === 0) return [{
+function collectIdErrors(value, source, pathPrefix) {
+	if (!isPlainObject(value)) return [{
+		path: pathPrefix,
+		message: "Expected JSON object for row identifier",
+		details: []
+	}];
+	const cache = getSourceCache(source);
+	if (cache.byKeySig.size === 0) return [{
+		path: pathPrefix,
+		message: "Table has no identifier configured",
+		details: []
+	}];
+	const match = cache.byKeySig.get(fieldsSig(Object.keys(value)));
+	if (!match) return [{
 		path: pathPrefix,
-		message: "Table has no primary key configured",
+		message: `Identifier fields must exactly match one of: ${cache.formatted}`,
 		details: []
 	}];
 	const errors = [];
-	if (pkFields.length === 1) {
-		const err = checkScalar(value, findFieldDescriptor(source, pkFields[0]), pathPrefix);
-		if (err) errors.push(err);
-		return errors;
-	}
-	if (!isPlainObject(value)) {
-		errors.push({
-			path: pathPrefix,
-			message: "Expected JSON object for composite primary key",
-			details: []
-		});
-		return errors;
-	}
-	for (const fieldName of pkFields) {
+	for (const fieldName of match.fields) {
 		const sub = pathPrefix ? `${pathPrefix}.${fieldName}` : fieldName;
-		if (!(fieldName in value)) {
-			errors.push({
-				path: sub,
-				message: `Missing primary-key field "${fieldName}"`,
-				details: []
-			});
-			continue;
-		}
-		const fd = findFieldDescriptor(source, fieldName);
-		const err = checkScalar(value[fieldName], fd, sub);
+		const err = checkScalar(value[fieldName], cache.fieldByName.get(fieldName), sub);
 		if (err) errors.push(err);
 	}
 	return errors;
 }
-function findFieldDescriptor(source, name) {
-	for (const fd of source.fieldDescriptors) if (fd.path === name) return fd;
-}
 function checkScalar(value, fd, path) {
 	const expected = fd?.designType ?? "string";
 	if (expected === "string" && typeof value !== "string") return scalarMismatch(path, expected, value);
@@ -1661,7 +1931,7 @@ function checkScalar(value, fd, path) {
 function scalarMismatch(path, expected, value) {
 	return {
 		path,
-		message: `Expected primary-key value to be ${expected}, got ${describe(value)}`,
+		message: `Expected identifier value to be ${expected}, got ${describe(value)}`,
 		details: []
 	};
 }
@@ -1674,105 +1944,115 @@ function isPlainObject(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
-//#region src/actions/pk-cache.ts
+//#region src/actions/id-cache.ts
 const boundTableKey = key("atscript_db_action_bound_table");
 function getActionTable(ctx) {
-	if (ctx.has(boundTableKey)) {
-		const fromSlot = ctx.get(boundTableKey);
-		if (fromSlot) return fromSlot;
-	}
+	const fromSlot = ctx.has(boundTableKey) ? ctx.get(boundTableKey) : void 0;
+	if (fromSlot) return fromSlot;
 	const ctrl = useControllerContext(ctx).getController();
-	if (ctrl) {
-		const t = ctrl.readable ?? ctrl.table;
-		if (t) return t;
-	}
-	return null;
+	return ctrl?.readable ?? ctrl?.table ?? null;
 }
 function noTableError(ctx) {
-	const cc = useControllerContext(ctx);
-	const ctrl = cc.getController();
-	const methodName = cc.getMethod();
-	let actionName;
-	if (ctrl && methodName) actionName = getMoostMate().read(ctrl.constructor, methodName)?.[MOOST_DB_ACTION]?.name;
+	const actionName = readCurrentActionMeta(ctx)?.name;
 	return new HttpError(500, `${WARN_PREFIX} ${actionName ? `"${actionName}"` : "<unknown>"}: controller has no readable/table property and the action declares no opts.table. Either expose readable/table on the controller, extend AsDbReadableController, or pass opts.table on @DbAction.`);
 }
-async function resolveValidatedPk(ctx, validate) {
+async function resolveValidatedId(ctx, validate) {
 	const table = getActionTable(ctx);
-	if (!isPkValidationSource(table)) throw noTableError(ctx);
+	if (!isIdValidationSource(table)) throw noTableError(ctx);
 	const body = await useBody(ctx).parseBody();
 	validate(body, table);
 	return body;
 }
-const dbActionPkSlot = cached((ctx) => resolveValidatedPk(ctx, validateSinglePk));
-const dbActionPksSlot = cached(async (ctx) => {
-	return await resolveValidatedPk(ctx, validateMultiPk);
+const dbActionIdSlot = cached((ctx) => resolveValidatedId(ctx, validateSingleId));
+const dbActionIdsSlot = cached(async (ctx) => {
+	return await resolveValidatedId(ctx, validateMultiId);
 });
-const useDbActionPk = defineWook((ctx) => ({ load: () => ctx.get(dbActionPkSlot) }));
-const useDbActionPks = defineWook((ctx) => ({ load: () => ctx.get(dbActionPksSlot) }));
+const useDbActionId = defineWook((ctx) => ({ load: () => ctx.get(dbActionIdSlot) }));
+const useDbActionIds = defineWook((ctx) => ({ load: () => ctx.get(dbActionIdsSlot) }));
 //#endregion
 //#region src/actions/row-cache.ts
 function asFetchTable(value) {
 	if (!value || typeof value !== "object") return null;
 	const v = value;
-	return Array.isArray(v.primaryKeys) && typeof v.findById === "function" && typeof v.findMany === "function" ? v : null;
+	if (Array.isArray(v.primaryKeys) && typeof v.findOne === "function" && typeof v.findMany === "function") return v;
+	return null;
+}
+function stringifyScalar(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	return String(value);
+}
+/** Returns the action's `requiredFields` or null when called outside a controller context (e.g. direct wook usage in tests). */
+function readActionFieldSet(ctx) {
+	const action = readCurrentActionMeta(ctx);
+	if (!action) return null;
+	const opts = action.opts;
+	return Array.isArray(opts.requiredFields) ? opts.requiredFields : null;
 }
-function noTable() {
-	throw new HttpError(500, `${WARN_PREFIX} cached row wook: no bound table`);
+function seedActionFields(ctx, table) {
+	const fields = /* @__PURE__ */ new Set();
+	for (const f of table.preferredId ?? table.primaryKeys) fields.add(f);
+	const action = readActionFieldSet(ctx);
+	if (action) for (const f of action) fields.add(f);
+	return fields;
 }
 async function loadRow(ctx) {
-	const pk = await ctx.get(dbActionPkSlot);
-	const row = await (asFetchTable(getActionTable(ctx)) ?? noTable()).findById(pk);
-	if (row == null) throw new HttpError(404, "Row not found for action PK");
+	const id = await ctx.get(dbActionIdSlot);
+	const table = asFetchTable(getActionTable(ctx));
+	if (!table) throw noTableError(ctx);
+	const fields = seedActionFields(ctx, table);
+	for (const k of Object.keys(id)) fields.add(k);
+	const row = await table.findOne({
+		filter: id,
+		controls: { $select: [...fields] }
+	});
+	if (row == null) throw new HttpError(404, "Row not found for action identifier");
 	return row;
 }
 async function loadRows(ctx) {
-	const pks = await ctx.get(dbActionPksSlot);
-	const table = asFetchTable(getActionTable(ctx)) ?? noTable();
-	if (pks.length === 0) return [];
-	const { primaryKeys } = table;
-	const rows = await table.findMany({ filter: buildPksFilter(pks, primaryKeys) });
-	if (primaryKeys.length === 1) {
-		const field = primaryKeys[0];
-		const byKey = /* @__PURE__ */ new Map();
-		for (const row of rows) byKey.set(row[field], row);
-		const ordered = [];
-		for (const pk of pks) {
-			const found = byKey.get(pk);
-			if (found !== void 0) ordered.push(found);
+	const ids = await ctx.get(dbActionIdsSlot);
+	const table = asFetchTable(getActionTable(ctx));
+	if (!table) throw noTableError(ctx);
+	if (ids.length === 0) return [];
+	const fields = seedActionFields(ctx, table);
+	const idKeys = [];
+	const shapes = /* @__PURE__ */ new Map();
+	const dedupedIds = [];
+	const seenKeys = /* @__PURE__ */ new Set();
+	for (const id of ids) {
+		const sortedFields = Object.keys(id).toSorted();
+		const sig = sortedFields.join("");
+		let key = "";
+		for (const f of sortedFields) {
+			fields.add(f);
+			key += `${f}\x1f${stringifyScalar(id[f])}\x1e`;
+		}
+		idKeys.push(key);
+		if (!shapes.has(sig)) shapes.set(sig, sortedFields);
+		if (!seenKeys.has(key)) {
+			seenKeys.add(key);
+			dedupedIds.push(id);
 		}
-		return ordered;
-	}
-	const byKey = /* @__PURE__ */ new Map();
-	for (const row of rows) byKey.set(compositeKey(row, primaryKeys), row);
-	const ordered = [];
-	for (const pk of pks) {
-		const found = byKey.get(compositeKey(pk, primaryKeys));
-		if (found !== void 0) ordered.push(found);
-	}
-	return ordered;
-}
-function buildPksFilter(pks, primaryKeys) {
-	if (primaryKeys.length === 1) return { [primaryKeys[0]]: { $in: pks } };
-	return { $or: pks.map((pk) => {
-		const obj = pk;
-		const clause = {};
-		for (const field of primaryKeys) clause[field] = obj[field];
-		return clause;
-	}) };
-}
-function compositeKey(obj, primaryKeys) {
-	let out = "";
-	for (const f of primaryKeys) {
-		if (out !== "") out += "\0";
-		const v = obj[f];
-		if (v === null) out += "
n";
-		else if (v === void 0) out += "
u";
-		else if (typeof v === "string") out += `s\x02${v}`;
-		else if (typeof v === "number") out += `n\x02${v}`;
-		else if (typeof v === "boolean") out += `b\x02${v}`;
-		else out += `j\x02${JSON.stringify(v)}`;
 	}
-	return out;
+	const rows = await table.findMany({
+		filter: { $or: dedupedIds },
+		controls: { $select: [...fields] }
+	});
+	const rowByKey = /* @__PURE__ */ new Map();
+	for (const row of rows) for (const sortedFields of shapes.values()) {
+		let key = "";
+		let ok = true;
+		for (const f of sortedFields) {
+			const v = row[f];
+			if (v === void 0) {
+				ok = false;
+				break;
+			}
+			key += `${f}\x1f${stringifyScalar(v)}\x1e`;
+		}
+		if (ok && !rowByKey.has(key)) rowByKey.set(key, row);
+	}
+	return ids.map((_, i) => rowByKey.get(idKeys[i]));
 }
 const dbActionRowSlot = cached((ctx) => loadRow(ctx));
 const dbActionRowsSlot = cached((ctx) => loadRows(ctx));
@@ -1797,28 +2077,38 @@ function buildGateInterceptor(opts) {
 		injectBoundTable(table);
 		const ctx = current();
 		if (level === "row") {
-			if (disabled(await ctx.get(dbActionRowSlot))) throw new ActionDisabledError(action, await ctx.get(dbActionPkSlot));
+			const verdicts = disabled([await ctx.get(dbActionRowSlot)]);
+			assertVerdictLength(action, verdicts, 1);
+			if (verdicts[0]) throw new ActionDisabledError(action, await ctx.get(dbActionIdSlot));
 			return;
 		}
-		const pks = await ctx.get(dbActionPksSlot);
+		const ids = await ctx.get(dbActionIdsSlot);
 		const rows = await ctx.get(dbActionRowsSlot);
-		const failingPks = [];
+		const existingRows = [];
+		for (const row of rows) if (row !== void 0) existingRows.push(row);
+		const verdicts = disabled(existingRows);
+		assertVerdictLength(action, verdicts, existingRows.length);
+		const failingIds = [];
 		const passingRows = [];
-		const passingPks = [];
-		for (let i = 0; i < rows.length; i++) if (disabled(rows[i])) failingPks.push(pks[i]);
-		else {
-			passingRows.push(rows[i]);
-			passingPks.push(pks[i]);
+		const passingIds = [];
+		let verdictIndex = 0;
+		for (let i = 0; i < ids.length; i++) {
+			const row = rows[i];
+			if (row === void 0 || verdicts[verdictIndex++]) failingIds.push(ids[i]);
+			else {
+				passingRows.push(row);
+				passingIds.push(ids[i]);
+			}
 		}
 		if (onDisabledRows === "skip") {
-			if (passingRows.length === 0) throw new ActionDisabledError(action, void 0, [...pks]);
-			if (failingPks.length > 0) {
+			if (passingRows.length === 0) throw new ActionDisabledError(action, void 0, [...ids]);
+			if (failingIds.length > 0) {
 				ctx.set(dbActionRowsSlot, Promise.resolve(passingRows));
-				ctx.set(dbActionPksSlot, Promise.resolve(passingPks));
+				ctx.set(dbActionIdsSlot, Promise.resolve(passingIds));
 			}
 			return;
 		}
-		if (failingPks.length > 0) throw new ActionDisabledError(action, void 0, failingPks);
+		if (failingIds.length > 0) throw new ActionDisabledError(action, void 0, failingIds);
 	}, GATE_PRIORITY);
 }
 /** Thin interceptor for `@DbActionRow*` without `disabled` — injects only the bound table. */
@@ -1836,6 +2126,11 @@ function buildThinInterceptor(opts) {
 * (gate when `disabled` is set, thin bound-table injector when only
 * `@DbActionRow*` is present). Stacking two `@DbAction` on the same method
 * is undefined and emits a warning.
+*
+* Generic over `TRow` (annotate at the call site: `@DbAction<Order>(...)`)
+* and `R` (the literal `requiredFields` tuple, inferred via `const R`).
+* The `disabled` predicate's `rows` argument is type-narrowed to
+* `Pick<FlatOf<TRow>, R[number]>[]`.
 */
 function DbAction(name, opts = {}) {
 	const mate = getMoostMate();
@@ -1854,14 +2149,15 @@ function DbAction(name, opts = {}) {
 		})(target, propertyKey, descriptor);
 		if (isAsValueHelpControllerSubclass(typeof target === "function" ? target : target.constructor)) return descriptor;
 		const scan = scanParamLevel(mate.read(target, propertyKey)?.params ?? []);
-		if (!!opts.disabled && (scan.level === "row" || scan.level === "rows")) Intercept(buildGateInterceptor({
+		const rawOpts = opts;
+		if (typeof rawOpts.disabled === "function" && (scan.level === "row" || scan.level === "rows")) Intercept(buildGateInterceptor({
 			action: name,
 			level: scan.level,
-			disabled: opts.disabled,
-			onDisabledRows: opts.onDisabledRows ?? "reject",
-			table: opts.table
+			disabled: rawOpts.disabled,
+			onDisabledRows: rawOpts.onDisabledRows ?? "reject",
+			table: rawOpts.table
 		}))(target, propertyKey, descriptor);
-		else if (scan.hasRowParam) Intercept(buildThinInterceptor({ table: opts.table }))(target, propertyKey, descriptor);
+		else if (scan.hasRowParam) Intercept(buildThinInterceptor({ table: rawOpts.table }))(target, propertyKey, descriptor);
 		return descriptor;
 	});
 }
@@ -1881,62 +2177,70 @@ function DbActionDefault() {
 	});
 }
 //#endregion
-//#region src/actions/pk-source.ts
+//#region src/actions/id-source.ts
 /**
-* Build a parameter decorator that reads its value from the cached PK wook
+* Build a parameter decorator that reads its value from the cached ID wook
 * (single or multi). Validation runs inside the wook factory exactly once
-* per request, regardless of how many readers consume the value (`@DbActionPK*`
+* per request, regardless of how many readers consume the value (`@DbActionID*`
 * resolver, gate interceptor, cached row wook, in-handler composables).
 *
 * Marks the param so {@link discoverActions} can infer the action's `level`.
 */
-function createPkParamDecorator(kind) {
+function createIdParamDecorator(kind) {
 	const mate = getMoostMate();
-	const slot = kind === "pk" ? dbActionPkSlot : dbActionPksSlot;
-	const resolverName = kind === "pk" ? "dbActionPk" : "dbActionPks";
-	return ApplyDecorators(mate.decorate(MOOST_DB_ACTION_PARAM, kind), Resolve(async () => current().get(slot), resolverName));
+	const resolverName = kind === "id" ? "dbActionId" : "dbActionIds";
+	const resolver = kind === "id" ? async () => current().get(dbActionIdSlot) : async () => current().get(dbActionIdsSlot);
+	return ApplyDecorators(mate.decorate(MOOST_DB_ACTION_PARAM, kind), Resolve(resolver, resolverName));
 }
 //#endregion
-//#region src/actions/db-action-pk.decorator.ts
+//#region src/actions/db-action-id.decorator.ts
 /**
-* Parameter resolver that reads the primary key from the JSON request body
-* and validates it against the bound table's PK schema.
+* Parameter resolver that reads a row identifier from the JSON request body
+* and validates it against the bound table's legitimate identifiers.
+*
+* Body shape is always a JSON object — no scalar form. The object's key set
+* MUST exactly match one of the table's legitimate identifications:
 *
-* - Single-field PK → JSON-encoded scalar (`"abc"`, `42`, `true`).
-* - Composite PK → JSON object with all PK fields.
+* - Single-field PK → `{ id: "abc" }` (or whatever the PK prop is named).
+* - Composite PK → `{ tenantId: "...", userId: "..." }`.
+* - Single-field unique index → `{ slug: "alpha" }`.
+* - Compound unique index → `{ tenantId: "...", slug: "..." }`.
 *
-* Validation is strict — no type coercion. Mismatches throw a
+* Strict — unknown fields are rejected, no type coercion. Mismatches throw a
 * `ValidatorError` which the existing validation interceptor surfaces as
 * HTTP 400 with the same envelope as DTO failures.
 *
 * Marks the param so {@link discoverActions} can infer the action's `level`
 * as `'row'`.
 *
-* Implementation note: the resolver is a thin reader of the cached PK wook
+* Implementation note: the resolver is a thin reader of the cached ID wook
 * — validation logic lives in the wook factory, which runs once per request
 * regardless of how many readers consume the value.
 */
-function DbActionPK() {
-	return createPkParamDecorator("pk");
+function DbActionID() {
+	return createIdParamDecorator("id");
 }
 //#endregion
-//#region src/actions/db-action-pks.decorator.ts
+//#region src/actions/db-action-ids.decorator.ts
 /**
-* Parameter resolver that reads a JSON array of primary keys from the request
-* body and validates each entry against the bound table's PK schema.
+* Parameter resolver that reads a JSON array of row identifiers from the
+* request body and validates each entry against the bound table.
 *
-* - Scalar PK → JSON array of scalars (`["a","b","c"]`).
-* - Composite PK → JSON array of objects.
+* Body shape is always a JSON array of objects — no scalar form. Each
+* element's key set MUST exactly match one of the table's legitimate
+* identifications (PK or any unique index). Elements MAY mix shapes:
+* `[{ id: "1" }, { slug: "alpha" }]` is valid when both `id` is the PK
+* and `slug` is a unique index.
 *
-* Validation is strict — no type coercion. Marks the param so
-* {@link discoverActions} can infer the action's `level` as `'rows'`.
+* Strict — unknown fields are rejected, no type coercion. Marks the param
+* so {@link discoverActions} can infer the action's `level` as `'rows'`.
 *
 * In `'rows'` skip mode the resolved value reflects the gate interceptor's
-* filtered subset (the cached PK slot is overwritten in place); see
-* {@link dbActionPksSlot} for precedence details.
+* filtered subset (the cached ID slot is overwritten in place); see
+* {@link dbActionIdsSlot} for precedence details.
 */
-function DbActionPKs() {
-	return createPkParamDecorator("pks");
+function DbActionIDs() {
+	return createIdParamDecorator("ids");
 }
 //#endregion
 //#region src/actions/db-action-row.decorator.ts
@@ -1944,9 +2248,8 @@ function createRowParamDecorator(metaKey, slot, resolverName) {
 	return ApplyDecorators(getMoostMate().decorate(metaKey, true), Resolve(async () => current().get(slot), resolverName));
 }
 /**
-* Parameter decorator that injects the row whose PK was supplied in the
-* request body. Reads from the cached row wook (fetched once per request,
-* shared with the gate interceptor when `disabled` is set).
+* Parameter decorator that injects the row whose identifier was supplied in
+* the request body.
 *
 * Marks the param so {@link discoverActions} infers the action's `level` as
 * `'row'`. Co-occurrence with `@DbActionRows()` (or any multi-cardinality
@@ -1959,8 +2262,8 @@ function DbActionRow() {
 	return createRowParamDecorator(MOOST_DB_ACTION_ROW, dbActionRowSlot, "dbActionRow");
 }
 /**
-* Parameter decorator that injects the rows-array fetched by primary keys
-* from the request body. Reads from the cached row-array wook.
+* Parameter decorator that injects the rows fetched by the identifiers
+* supplied in the request body.
 *
 * Marks the param so {@link discoverActions} infers the action's `level` as
 * `'rows'`. In `'rows'` + `'skip'` mode the resolved value contains only the
@@ -1978,10 +2281,9 @@ function DbActionRows() {
 * the level-pinned shortcuts (`@DbTableActions`, `@DbRowActions`,
 * `@DbRowsActions`) to avoid repeating `level`.
 *
-* The dictionary key serves as the action `name`. Entries do NOT bind any
-* HTTP route — the meta builder surfaces them in `/meta` only. For
-* `processor: 'backend'`, the dev-supplied `value` MUST point to a real
-* `@Post`-bound endpoint accepting the level-determined body shape.
+* Generic over `TRow` (annotate at the call site: `@DbActions<Order>(...)`)
+* and `D` (the literal dict, captured via `const D`). Each entry's
+* `disabled` predicate is type-narrowed by its own `requiredFields` literal.
 *
 * Multiple `@DbActions` (and shortcut) decorators on the same class
 * accumulate.
@@ -2022,4 +2324,19 @@ function classLevelActions(dict, forcedLevel) {
 	});
 }
 //#endregion
-export { ActionDisabledError, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionPK, DbActionPKs, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, discoverActions, useDbActionPk, useDbActionPks, useDbActionRow, useDbActionRows, validationErrorTransform };
+//#region src/actions/per-row.ts
+/**
+* Lift a per-row predicate into the batch shape required by
+* `@DbAction` opts.`disabled` and class-level dict `disabled`. Polarity is
+* preserved — `true` from `fn` means the action is disabled for that row.
+*
+* ```ts
+* @DbAction<Order>('archive', {
+*   requiredFields: ['status'],
+*   disabled: perRow(r => r.status === 'archived'),
+* })
+* ```
+*/
+const perRow = (fn) => (rows) => rows.map(fn);
+//#endregion
+export { ActionDisabledError, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionID, DbActionIDs, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, discoverActions, perRow, useDbActionId, useDbActionIds, useDbActionRow, useDbActionRows, validationErrorTransform };