@atscript/moost-db 0.1.54 → 0.1.56

package/dist/index.mjs

@@ -1,72 +1,9 @@
 import { ValidatorError, defineAnnotatedType, serializeAnnotatedType, throwFeatureDisabled } from "@atscript/typescript/utils";
 import { Body, Delete, Get, HttpError, Patch, Post, Put, Query, Url } from "@moostjs/event-http";
-import { ApplyDecorators, Controller, Inherit, Inject, Intercept, Moost, Param, Provide, TInterceptorPriority, defineInterceptor, useControllerContext } from "moost";
+import { ApplyDecorators, Controller, Inherit, Inject, Intercept, Moost, Param, Provide, Resolve, TInterceptorPriority, defineInterceptor, getMoostMate, useControllerContext } from "moost";
 import { parseUrl } from "@uniqu/url";
 import { DbError } from "@atscript/db";
-//#region src/decorators.ts
-/**
-* DI token under which the {@link AtscriptDbReadable} instance
-* is exposed to the readable controller's constructor via `@Inject`.
-*/
-const READABLE_DEF = "__atscript_db_readable_def";
-/**
-* DI token under which the {@link AtscriptDbTable} instance
-* is exposed to the controller's constructor via `@Inject`.
-* Points to the same token as READABLE_DEF for backward compatibility.
-*/
-const TABLE_DEF = READABLE_DEF;
-/**
-* Combines the boilerplate needed to turn an {@link AsDbController}
-* subclass into a fully wired HTTP controller for a given `@db.table` model.
-*
-* Internally applies three decorators:
-* 1. **Provide** — registers the table instance under {@link TABLE_DEF}.
-* 2. **Controller** — registers the class as a Moost HTTP controller
-*    with an optional route prefix. Defaults to `table.tableName`.
-* 3. **Inherit** — copies metadata (routes, guards, etc.) from the
-*    parent class so they stay active in the derived controller.
-*
-* @param table  The {@link AtscriptDbTable} instance for this controller.
-* @param prefix Optional route prefix. Defaults to `table.tableName`.
-*
-* @example
-* ```ts
-* ‎@TableController(usersTable)
-* export class UsersController extends AsDbController<typeof UserModel> {}
-* ```
-*/
-const TableController = (table, prefix) => {
-	const resolvedPath = prefix || table.type.metadata.get("db.http.path");
-	return ApplyDecorators(Provide(TABLE_DEF, () => table), Controller(resolvedPath || table.tableName), Inherit());
-};
-/**
-* Combines the boilerplate needed to turn an {@link AsDbReadableController}
-* subclass into a fully wired HTTP controller for a given `@db.view` or `@db.table` model.
-*
-* @param readable  The {@link AtscriptDbReadable} instance (table or view).
-* @param prefix    Optional route prefix. Defaults to `readable.tableName`.
-*
-* @example
-* ```ts
-* ‎@ReadableController(activeTasksView)
-* export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
-* ```
-*/
-const ReadableController = (readable, prefix) => {
-	const resolvedPath = prefix || readable.type.metadata.get("db.http.path");
-	return ApplyDecorators(Provide(READABLE_DEF, () => readable), Controller(resolvedPath || readable.tableName), Inherit());
-};
-/**
-* Alias for {@link ReadableController} — use with view-backed controllers.
-*
-* @example
-* ```ts
-* ‎@ViewController(activeTasksView)
-* export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
-* ```
-*/
-const ViewController = ReadableController;
-//#endregion
+import { useBody } from "@wooksjs/http-body";
 //#region src/validation-interceptor.ts
 const dbErrorCodeToStatus = { CONFLICT: 409 };
 function transformValidationError(error, reply) {
@@ -177,16 +114,265 @@ defineAnnotatedType("object", WithFilterDto).propPattern(/./, defineAnnotatedTyp
 defineAnnotatedType("object", SortControlDto).propPattern(/./, defineAnnotatedType("union").item(defineAnnotatedType().designType("number").value(1).$type).item(defineAnnotatedType().designType("number").value(-1).$type).$type);
 defineAnnotatedType("object", SelectControlDto).propPattern(/./, defineAnnotatedType("union").item(defineAnnotatedType().designType("number").value(1).$type).item(defineAnnotatedType().designType("number").value(0).$type).$type);
 //#endregion
-//#region \0@oxc-project+runtime@0.120.0/helpers/decorateMetadata.js
-function __decorateMetadata(k, v) {
-	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+//#region src/gate-utils.ts
+/**
+* Walks a Uniquery filter expression and returns the first field name that
+* fails the `isAllowed` predicate, or `undefined` if every leaf field is
+* allowed. Logical combinators (`$and`, `$or`, `$nor`, `$not`) are traversed;
+* other `$`-prefixed keys are skipped.
+*
+* Shared by the DB readable's `@db.column.filterable` gate and the value-help
+* controller's `@ui.dict.filterable` gate — only the predicate differs.
+*/
+function findFilterOffender(filter, isAllowed) {
+	if (!filter || typeof filter !== "object") return;
+	for (const [key, value] of Object.entries(filter)) {
+		if (key === "$and" || key === "$or" || key === "$nor") {
+			if (Array.isArray(value)) for (const sub of value) {
+				const inner = findFilterOffender(sub, isAllowed);
+				if (inner) return inner;
+			}
+			continue;
+		}
+		if (key === "$not") {
+			const inner = findFilterOffender(value, isAllowed);
+			if (inner) return inner;
+			continue;
+		}
+		if (key.startsWith("$")) continue;
+		if (!isAllowed(key)) return key;
+	}
+}
+/**
+* Walks a Uniquery `$sort` control (accepts string, string[], object, or
+* array-of-{field: dir}) and returns the first field name that fails the
+* `isAllowed` predicate, or `undefined` if every sort key is allowed.
+*
+* Shared by the DB readable's `@db.column.sortable` gate and the value-help
+* controller's `@ui.dict.sortable` gate.
+*/
+function findSortOffender(sort, isAllowed) {
+	if (!sort) return void 0;
+	const check = (name) => isAllowed(name) ? void 0 : name;
+	if (typeof sort === "string") {
+		for (const part of sort.split(",")) {
+			const name = part.trim().replace(/^[-+]/, "").split(":")[0];
+			if (name) {
+				const bad = check(name);
+				if (bad) return bad;
+			}
+		}
+		return;
+	}
+	if (Array.isArray(sort)) {
+		for (const entry of sort) if (typeof entry === "string") {
+			const bad = check(entry.replace(/^[-+]/, ""));
+			if (bad) return bad;
+		} else if (entry && typeof entry === "object") for (const name of Object.keys(entry)) {
+			const bad = check(name);
+			if (bad) return bad;
+		}
+		return;
+	}
+	if (typeof sort === "object") for (const name of Object.keys(sort)) {
+		const bad = check(name);
+		if (bad) return bad;
+	}
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.120.0/helpers/decorateParam.js
-function __decorateParam(paramIndex, decorator) {
-	return function(target, key) {
-		decorator(target, key, paramIndex);
+//#region src/actions/keys.ts
+/** Method-level metadata key — written by `@DbAction(name, opts)`. */
+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. */
+const MOOST_DB_ACTION_PARAM = "atscript_db_action_param";
+/**
+* Shared method-decorator update used by `@DbAction` and `@DbActionDefault`:
+* read the existing `MOOST_DB_ACTION` slot, merge the patch (later-applied
+* fields win), and write it back. `name` is empty until `@DbAction` provides
+* one — `discoverActions` warns and drops actions with no name.
+*/
+function mergeActionMeta(current, patch) {
+	const existing = current[MOOST_DB_ACTION];
+	return {
+		name: patch.name ?? existing?.name ?? "",
+		opts: {
+			...existing?.opts,
+			...patch.opts
+		}
+	};
+}
+//#endregion
+//#region src/actions/discover.ts
+/** Optional fields shared between method opts and class-level entries. */
+const OPTIONAL_FIELDS = [
+	"icon",
+	"intent",
+	"description",
+	"order",
+	"default",
+	"promptText"
+];
+const WARN_PREFIX = "[moost-db actions]";
+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.
+*/
+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);
+	applyDefaultPerLevel(out, logger);
+	actionsCache.set(controllerCtor, out);
+	return out;
+}
+function collectMethodActions(ctor, overview, logger, out) {
+	if (!overview) return;
+	const byMethod = /* @__PURE__ */ new Map();
+	for (const h of overview.handlers) {
+		const list = byMethod.get(h.method);
+		if (list) list.push(h);
+		else byMethod.set(h.method, [h]);
+	}
+	for (const [methodName, handlers] of byMethod) {
+		const methodMeta = handlers[0].meta;
+		const action = methodMeta[MOOST_DB_ACTION];
+		if (!action) continue;
+		if (!action.name) {
+			logger.warn(`${WARN_PREFIX} method "${methodName}" has @DbActionDefault() but no @DbAction(name) — dropping`);
+			continue;
+		}
+		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 with @Body() — dropping`);
+			continue;
+		}
+		const postEntry = handlers.find((h) => h.handler.type === "HTTP" && h.handler.method === "POST");
+		if (!postEntry) {
+			logger.warn(`${WARN_PREFIX} action "${action.name}" requires @Post(...); no POST handler bound to ${methodName} — dropping`);
+			continue;
+		}
+		const path = postEntry.registeredAs[0]?.path;
+		if (!path) {
+			logger.warn(`${WARN_PREFIX} action "${action.name}" — POST handler ${methodName} has no registered path — dropping`);
+			continue;
+		}
+		const label = action.opts.label ?? methodMeta.label;
+		if (!label) {
+			logger.warn(`${WARN_PREFIX} action "${action.name}" requires a label (opts.label or @Label) — dropping`);
+			continue;
+		}
+		const info = {
+			name: action.name,
+			label,
+			level: levelInfer.level,
+			processor: "backend",
+			value: path
+		};
+		copyOptionalFields(info, action.opts);
+		out.push(info);
+	}
+}
+function inferMethodLevel(params, actionName, logger) {
+	let hasPk = false;
+	let hasPks = false;
+	let hasBody = false;
+	for (const p of params) {
+		const kind = p[MOOST_DB_ACTION_PARAM];
+		if (kind === "pk") hasPk = true;
+		else if (kind === "pks") hasPks = true;
+		if (p.paramSource === "BODY") hasBody = true;
+	}
+	if (hasPk && hasPks) {
+		logger.warn(`${WARN_PREFIX} action "${actionName}" has both @DbActionPK and @DbActionPKs — dropping`);
+		return null;
+	}
+	const level = hasPk ? "row" : hasPks ? "rows" : "table";
+	return {
+		level,
+		bodyConflict: hasBody && level !== "table"
+	};
+}
+function collectClassActions(ctor, logger, out) {
+	const list = getMoostMate().read(ctor)?.[MOOST_DB_ACTIONS];
+	if (!list) return;
+	for (const { name, entry, forcedLevel } of list) {
+		const built = buildClassEntry(name, entry, forcedLevel, logger);
+		if (built) out.push(built);
+	}
+}
+function buildClassEntry(name, entry, forcedLevel, logger) {
+	const level = forcedLevel ?? entry.level;
+	if (!level) {
+		logger.warn(`${WARN_PREFIX} class-level action "${name}" requires a level — dropping. Use @DbTableActions/@DbRowActions/@DbRowsActions or set "level" explicitly.`);
+		return null;
+	}
+	if (!entry.label) {
+		logger.warn(`${WARN_PREFIX} class-level action "${name}" requires a label — dropping`);
+		return null;
+	}
+	const processor = entry.processor;
+	let value;
+	if (processor === "navigate" || processor === "backend") {
+		const v = entry.value;
+		if (typeof v !== "string" || v === "") {
+			logger.warn(`${WARN_PREFIX} class-level action "${name}" with processor "${processor}" requires a non-empty "value" — dropping`);
+			return null;
+		}
+		value = v;
+	} else if (processor === "custom") {
+		const v = entry.value;
+		if (v !== void 0 && v !== null) {
+			logger.warn(`${WARN_PREFIX} class-level action "${name}" with processor "custom" forbids "value" (always derived from the dict key) — dropping`);
+			return null;
+		}
+		value = name;
+	} else {
+		logger.warn(`${WARN_PREFIX} class-level action "${name}" has unknown processor "${String(processor)}" — dropping`);
+		return null;
+	}
+	const info = {
+		name,
+		label: entry.label,
+		level,
+		processor,
+		value
 	};
+	copyOptionalFields(info, entry);
+	return info;
+}
+function applyDefaultPerLevel(actions, logger) {
+	const winners = /* @__PURE__ */ new Map();
+	for (const a of actions) {
+		if (!a.default) continue;
+		const existing = winners.get(a.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);
+	}
+}
+function copyOptionalFields(info, source) {
+	for (const key of OPTIONAL_FIELDS) {
+		const value = source[key];
+		if (value !== void 0) info[key] = value;
+	}
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.120.0/helpers/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 //#endregion
 //#region \0@oxc-project+runtime@0.120.0/helpers/decorate.js
@@ -197,24 +383,27 @@ function __decorate(decorators, target, key, desc) {
 	return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 //#endregion
-//#region src/as-db-readable.controller.ts
-var _ref$1, _ref2$1;
-let AsDbReadableController = class AsDbReadableController {
-	/** Reference to the underlying readable (table or view). */
-	readable;
+//#region src/as-readable.controller.ts
+var _ref$4;
+let AsReadableController = class AsReadableController {
+	/** The Atscript interface this controller serves. */
+	boundType;
+	/** Short human-readable name for logging (usually the table/source name). */
+	controllerName;
 	/** Application-scoped logger. */
 	logger;
-	/** Cached serialized type definition (lazy, computed on first access). */
-	_serializedType;
 	/** Moost application instance. */
 	app;
+	/** Cached serialized type definition (lazy, computed on first access). */
+	_serializedType;
 	/** Cached full meta response (computed lazily on first meta() call). */
 	_metaResponse;
-	constructor(readable, app) {
-		this.readable = readable;
+	constructor(boundType, controllerName, app, kindTag = "readable") {
+		this.boundType = boundType;
+		this.controllerName = controllerName;
 		this.app = app;
-		this.logger = app.getLogger(`db [${readable.tableName}]`);
-		this.logger.info(`Initializing ${readable.isView ? "view" : "table"} controller`);
+		this.logger = app.getLogger(`db [${controllerName}]`);
+		this.logger.info(`Initializing ${kindTag} controller`);
 		this._resolveHttpPath();
 		try {
 			const p = this.init();
@@ -235,12 +424,12 @@ let AsDbReadableController = class AsDbReadableController {
 		if (!prefix) prefix = (this.app.getControllersOverview?.()?.find((o) => o.type === this.constructor))?.computedPrefix;
 		if (prefix) {
 			if (!prefix.startsWith("/")) prefix = `/${prefix}`;
-			this.readable.type.metadata.set("db.http.path", prefix);
+			this.boundType.metadata.set("db.http.path", prefix);
 		}
 	}
-	/** Lazily serializes the type (after all controllers have set their @db.http.path). */
+	/** Lazily serializes the bound type (after all controllers have set @db.http.path). */
 	getSerializedType() {
-		if (!this._serializedType) this._serializedType = serializeAnnotatedType(this.readable.type, this.getSerializeOptions());
+		if (!this._serializedType) this._serializedType = serializeAnnotatedType(this.boundType, this.getSerializeOptions());
 		return this._serializedType;
 	}
 	/**
@@ -249,13 +438,23 @@ let AsDbReadableController = class AsDbReadableController {
 	init() {}
 	/**
 	* Returns serialization options for the `/meta` endpoint's type field.
-	* Default: whitelist — keeps `meta.*`, `expect.*`, and `db.rel.*` annotations,
-	* strips all other `db.*` annotations (table, column, index, default, etc.).
-	* Override in subclass to customise what annotations are exposed to clients.
+	*
+	* `refDepth: 0.5` is intentionally static — independent of `@db.depth.limit`
+	* (which is a security guard on nested writes, not a serialization policy).
+	* The shallow shape emits `{ field, type: { id, metadata } }` for every FK,
+	* which carries the target's `db.http.path` so clients can resolve value-help
+	* URLs and lazy-fetch target `/meta` when deeper structure is needed. Nav
+	* props (`@db.rel.from` / `@db.rel.to` / `@db.rel.via`) are not `.ref` nodes
+	* and always expand fully regardless of `refDepth` — the write-payload shape
+	* clients need is unaffected.
+	*
+	* Annotation whitelist: keeps `meta.*`, `expect.*`, and `db.rel.*`; strips
+	* other `db.*` (table, column, index, default, etc.). Override in subclass
+	* to customise.
 	*/
 	getSerializeOptions() {
 		return {
-			refDepth: 1,
+			refDepth: .5,
 			processAnnotation: ({ key, value }) => {
 				if (key.startsWith("meta.") || key.startsWith("expect.") || key.startsWith("db.rel.")) return {
 					key,
@@ -275,7 +474,7 @@ let AsDbReadableController = class AsDbReadableController {
 	}
 	/**
 	* Whether this controller is read-only (no write endpoints).
-	* Returns `true` for readable/view controllers, overridden to `false` in AsDbController.
+	* Returns `true` by default; {@link AsDbController} overrides to `false`.
 	*/
 	_isReadOnly() {
 		return true;
@@ -302,7 +501,7 @@ let AsDbReadableController = class AsDbReadableController {
 	validateInsights(insights) {
 		for (const [key] of insights) {
 			if (key === "*") continue;
-			if (!this.readable.flatMap.has(key)) return `Unknown field "${key}"`;
+			if (!this.hasField(key)) return `Unknown field "${key}"`;
 		}
 	}
 	validateParsed(parsed, type) {
@@ -312,6 +511,201 @@ let AsDbReadableController = class AsDbReadableController {
 			const insightsError = this.validateInsights(parsed.insights);
 			if (insightsError) return new HttpError(400, insightsError);
 		}
+	}
+	/**
+	* Shared filter/sort/search gate check. Subclasses assemble a {@link ReadableGates}
+	* config per request (or once in the constructor when static) and call this to
+	* get a uniform HTTP 400 response for any offending field/control.
+	*/
+	checkGates(filter, controls, gates) {
+		if (gates.filter) {
+			const bad = findFilterOffender(filter, gates.filter.predicate);
+			if (bad) return new HttpError(400, `Filtering on field "${bad}" is not permitted — add ${gates.filter.annotation} to enable.`);
+		}
+		if (gates.sort) {
+			const bad = findSortOffender(controls.$sort, gates.sort.predicate);
+			if (bad) return new HttpError(400, `Sorting on field "${bad}" is not permitted — add ${gates.sort.annotation} to enable.`);
+		}
+		if (gates.search && controls.$search && !gates.search.allowed) return new HttpError(400, gates.search.rejectionMessage);
+	}
+	parseQueryString(url) {
+		const idx = url.indexOf("?");
+		return parseUrl(idx >= 0 ? url.slice(idx + 1) : "");
+	}
+	async returnOne(result) {
+		const item = await result;
+		if (!item) return new HttpError(404);
+		return item;
+	}
+	/**
+	* **GET /meta** — returns the bound interface's metadata envelope.
+	*
+	* Base implementation delegates to {@link buildMetaResponse}, which subclasses
+	* override to add source-specific fields (relations, searchable flags, etc.).
+	* The response is cached on the instance; async overrides must cache any
+	* extra enrichment themselves.
+	*/
+	async meta() {
+		if (this._metaResponse) return this._metaResponse;
+		const response = await this.buildMetaResponse();
+		this._metaResponse = response;
+		return response;
+	}
+	/**
+	* Builds the `/meta` payload. Override in subclasses to populate source-specific
+	* fields. Defaults return a minimal envelope with the serialized type and the
+	* read-only flag; value-help dicts populate their capability hints here.
+	* Subclasses that fully replace the envelope must call {@link buildActions}
+	* directly so `@DbAction*` decorators still surface.
+	*/
+	async buildMetaResponse() {
+		return {
+			searchable: false,
+			vectorSearchable: false,
+			searchIndexes: [],
+			primaryKeys: [],
+			readOnly: this._isReadOnly(),
+			relations: [],
+			fields: {},
+			type: this.getSerializedType(),
+			actions: this.buildActions()
+		};
+	}
+	/**
+	* Discovers `@DbAction*` and `@DbActions`-style class metadata on this
+	* controller and produces the `actions` array. Returns `[]` for value-help
+	* controllers — see {@link AsValueHelpController#buildMetaResponse}.
+	*/
+	buildActions() {
+		return discoverActions(this.constructor, this.app, this.logger);
+	}
+};
+__decorate([
+	Get("meta"),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", []),
+	__decorateMetadata("design:returntype", Promise)
+], AsReadableController.prototype, "meta", null);
+AsReadableController = __decorate([UseValidationErrorTransform(), __decorateMetadata("design:paramtypes", [
+	Object,
+	String,
+	typeof (_ref$4 = typeof Moost !== "undefined" && Moost) === "function" ? _ref$4 : Object,
+	Object
+])], AsReadableController);
+//#endregion
+//#region src/decorators.ts
+/**
+* DI token under which the {@link AtscriptDbReadable} instance
+* is exposed to the readable controller's constructor via `@Inject`.
+*/
+const READABLE_DEF = "__atscript_db_readable_def";
+/**
+* DI token under which the {@link AtscriptDbTable} instance
+* is exposed to the controller's constructor via `@Inject`.
+* Points to the same token as READABLE_DEF for backward compatibility.
+*/
+const TABLE_DEF = READABLE_DEF;
+/**
+* Combines the boilerplate needed to turn an {@link AsDbController}
+* subclass into a fully wired HTTP controller for a given `@db.table` model.
+*
+* Internally applies three decorators:
+* 1. **Provide** — registers the table instance under {@link TABLE_DEF}.
+* 2. **Controller** — registers the class as a Moost HTTP controller
+*    with an optional route prefix. Defaults to `table.tableName`.
+* 3. **Inherit** — copies metadata (routes, guards, etc.) from the
+*    parent class so they stay active in the derived controller.
+*
+* @param table  The {@link AtscriptDbTable} instance for this controller.
+* @param prefix Optional route prefix. Defaults to `table.tableName`.
+*
+* @example
+* ```ts
+* ‎@TableController(usersTable)
+* export class UsersController extends AsDbController<typeof UserModel> {}
+* ```
+*/
+const TableController = (table, prefix) => {
+	const resolvedPath = prefix || table.type.metadata.get("db.http.path");
+	return ApplyDecorators(Provide(TABLE_DEF, () => table), Controller(resolvedPath || table.tableName), Inherit());
+};
+/**
+* Combines the boilerplate needed to turn an {@link AsDbReadableController}
+* subclass into a fully wired HTTP controller for a given `@db.view` or `@db.table` model.
+*
+* @param readable  The {@link AtscriptDbReadable} instance (table or view).
+* @param prefix    Optional route prefix. Defaults to `readable.tableName`.
+*
+* @example
+* ```ts
+* ‎@ReadableController(activeTasksView)
+* export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
+* ```
+*/
+const ReadableController = (readable, prefix) => {
+	const resolvedPath = prefix || readable.type.metadata.get("db.http.path");
+	return ApplyDecorators(Provide(READABLE_DEF, () => readable), Controller(resolvedPath || readable.tableName), Inherit());
+};
+/**
+* Alias for {@link ReadableController} — use with view-backed controllers.
+*
+* @example
+* ```ts
+* ‎@ViewController(activeTasksView)
+* export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
+* ```
+*/
+const ViewController = ReadableController;
+//#endregion
+//#region \0@oxc-project+runtime@0.120.0/helpers/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+//#endregion
+//#region src/as-db-readable.controller.ts
+var _ref$3, _ref2$2;
+let AsDbReadableController = class AsDbReadableController extends AsReadableController {
+	/** Reference to the underlying readable (table or view). */
+	readable;
+	_gates;
+	constructor(readable, app) {
+		super(readable.type, readable.tableName, app, readable.isView ? "view" : "table");
+		this.readable = readable;
+		this._gates = this._buildGates();
+	}
+	_buildGates() {
+		const meta = this.readable.type.metadata;
+		const gates = {};
+		if (meta.get("db.table.filterable") === "manual") {
+			const allowed = this._collectAnnotated("db.column.filterable");
+			gates.filter = {
+				predicate: (f) => allowed.has(f),
+				annotation: "@db.column.filterable"
+			};
+		}
+		if (meta.get("db.table.sortable") === "manual") {
+			const allowed = this._collectAnnotated("db.column.sortable");
+			gates.sort = {
+				predicate: (f) => allowed.has(f),
+				annotation: "@db.column.sortable"
+			};
+		}
+		return gates;
+	}
+	_collectAnnotated(annotation) {
+		const out = /* @__PURE__ */ new Set();
+		for (const [path, entry] of this.readable.flatMap) if (entry.metadata.has(annotation)) out.add(path);
+		return out;
+	}
+	hasField(path) {
+		return this.readable.flatMap.has(path);
+	}
+	/** Validates $with relations against the readable. */
+	validateParsed(parsed, type) {
+		const baseError = super.validateParsed(parsed, type);
+		if (baseError) return baseError;
 		const withRelations = parsed.controls.$with;
 		if (withRelations?.length) {
 			const relations = this.readable.relations;
@@ -347,15 +741,6 @@ let AsDbReadableController = class AsDbReadableController {
 	transformProjection(projection) {
 		return projection;
 	}
-	parseQueryString(url) {
-		const idx = url.indexOf("?");
-		return parseUrl(idx >= 0 ? url.slice(idx + 1) : "");
-	}
-	async returnOne(result) {
-		const item = await result;
-		if (!item) return new HttpError(404);
-		return item;
-	}
 	/**
 	* Extracts a composite identifier object from query params.
 	* Tries composite primary key first, then compound unique indexes.
@@ -410,6 +795,8 @@ let AsDbReadableController = class AsDbReadableController {
 		}
 		const error = this.validateParsed(parsed, "query");
 		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)]);
 		if (controls.$count) return this.readable.count({
 			filter,
@@ -447,6 +834,8 @@ let AsDbReadableController = class AsDbReadableController {
 		const error = this.validateParsed(parsed, "pages");
 		if (error) return error;
 		const controls = parsed.controls;
+		const gateError = this.checkGates(parsed.filter, controls, this._gates);
+		if (gateError) return gateError;
 		const page = Math.max(Number(controls.$page || 1), 1);
 		const size = Math.max(Number(controls.$size || 10), 1);
 		const skip = (page - 1) * size;
@@ -513,28 +902,31 @@ let AsDbReadableController = class AsDbReadableController {
 	/**
 	* **GET /meta** — returns table/view metadata for UI.
 	*
-	* The return type includes `Promise<...>` so subclasses can override with an
-	* async implementation (e.g. to enrich the payload from an external source).
-	* The base cache only covers the base payload — async overrides must cache
-	* their own enrichment if needed.
+	* Overrides the base's minimal envelope to add relations, searchable flags,
+	* vector-searchable flags, field-descriptor-derived filter/sort hints, and
+	* the configured primary keys.
 	*/
-	meta() {
-		if (this._metaResponse) return this._metaResponse;
+	async buildMetaResponse() {
 		const relations = [];
 		for (const [name, rel] of this.readable.relations) relations.push({
 			name,
 			direction: rel.direction,
 			isArray: rel.isArray
 		});
+		const filterableMode = this.readable.type.metadata.get("db.table.filterable") === "manual";
+		const sortableMode = this.readable.type.metadata.get("db.table.sortable") === "manual";
 		const fields = {};
 		for (const fd of this.readable.fieldDescriptors) {
 			if (fd.ignored) continue;
+			const annotations = fd.type?.metadata;
+			const annotatedFilterable = annotations?.has("db.column.filterable") ?? false;
+			const annotatedSortable = annotations?.has("db.column.sortable") ?? false;
 			fields[fd.path] = {
-				sortable: !!fd.isIndexed,
-				filterable: true
+				sortable: sortableMode ? annotatedSortable : !!fd.isIndexed,
+				filterable: filterableMode ? annotatedFilterable : true
 			};
 		}
-		const response = {
+		return {
 			searchable: this.readable.isSearchable(),
 			vectorSearchable: this.readable.isVectorSearchable(),
 			searchIndexes: this.readable.getSearchIndexes(),
@@ -542,10 +934,9 @@ let AsDbReadableController = class AsDbReadableController {
 			readOnly: this._isReadOnly(),
 			relations,
 			fields,
-			type: this.getSerializedType()
+			type: this.getSerializedType(),
+			actions: this.buildActions()
 		};
-		this._metaResponse = response;
-		return response;
 	}
 };
 __decorate([
@@ -575,23 +966,17 @@ __decorate([
 	__decorateParam(0, Query()),
 	__decorateParam(1, Url()),
 	__decorateMetadata("design:type", Function),
-	__decorateMetadata("design:paramtypes", [typeof (_ref2$1 = typeof Record !== "undefined" && Record) === "function" ? _ref2$1 : Object, String]),
+	__decorateMetadata("design:paramtypes", [typeof (_ref2$2 = typeof Record !== "undefined" && Record) === "function" ? _ref2$2 : Object, String]),
 	__decorateMetadata("design:returntype", Promise)
 ], AsDbReadableController.prototype, "getOneComposite", null);
-__decorate([
-	Get("meta"),
-	__decorateMetadata("design:type", Function),
-	__decorateMetadata("design:paramtypes", []),
-	__decorateMetadata("design:returntype", Object)
-], AsDbReadableController.prototype, "meta", null);
 AsDbReadableController = __decorate([
-	UseValidationErrorTransform(),
+	Inherit(),
 	__decorateParam(0, Inject(READABLE_DEF)),
-	__decorateMetadata("design:paramtypes", [Object, typeof (_ref$1 = typeof Moost !== "undefined" && Moost) === "function" ? _ref$1 : Object])
+	__decorateMetadata("design:paramtypes", [Object, typeof (_ref$3 = typeof Moost !== "undefined" && Moost) === "function" ? _ref$3 : Object])
 ], AsDbReadableController);
 //#endregion
 //#region src/as-db.controller.ts
-var _ref, _ref2;
+var _ref$2, _ref2$1;
 let AsDbController = class AsDbController extends AsDbReadableController {
 	/** Reference to the underlying table (typed for write access). */
 	get table() {
@@ -712,13 +1097,573 @@ __decorate([
 	Delete(""),
 	__decorateParam(0, Query()),
 	__decorateMetadata("design:type", Function),
-	__decorateMetadata("design:paramtypes", [typeof (_ref2 = typeof Record !== "undefined" && Record) === "function" ? _ref2 : Object]),
+	__decorateMetadata("design:paramtypes", [typeof (_ref2$1 = typeof Record !== "undefined" && Record) === "function" ? _ref2$1 : Object]),
 	__decorateMetadata("design:returntype", Promise)
 ], AsDbController.prototype, "removeComposite", null);
 AsDbController = __decorate([
 	Inherit(),
 	__decorateParam(0, Inject(TABLE_DEF)),
-	__decorateMetadata("design:paramtypes", [Object, typeof (_ref = typeof Moost !== "undefined" && Moost) === "function" ? _ref : Object])
+	__decorateMetadata("design:paramtypes", [Object, typeof (_ref$2 = typeof Moost !== "undefined" && Moost) === "function" ? _ref$2 : Object])
 ], AsDbController);
 //#endregion
-export { AsDbController, AsDbReadableController, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, validationErrorTransform };
+//#region src/as-value-help.controller.ts
+var _ref$1, _ref2;
+let AsValueHelpController = class AsValueHelpController extends AsReadableController {
+	/** Per-prop metadata map of the bound interface; eagerly built once. */
+	fieldMeta;
+	/**
+	* Fields that participate in `$search` by default. Populated from
+	* `@ui.dict.searchable`:
+	* - If any prop carries `@ui.dict.searchable`, only those props are here.
+	* - Else if the interface carries `@ui.dict.searchable`, every `string`-typed prop is here.
+	* - Else every `string`-typed prop is here (hint is absent — default to all strings).
+	*/
+	searchableFields;
+	/** The `@meta.id` field name on the bound interface, if any. */
+	primaryKey;
+	constructor(boundType, controllerName, app) {
+		super(boundType, controllerName, app, "value-help");
+		const fieldMeta = /* @__PURE__ */ new Map();
+		const explicitlySearchable = [];
+		const stringProps = [];
+		let primaryKey;
+		const interfaceSearchable = boundType.metadata.has("ui.dict.searchable");
+		const asObj = boundType.type;
+		if (asObj?.props) for (const [name, prop] of asObj.props) {
+			const meta = prop.metadata;
+			fieldMeta.set(name, meta);
+			if (!primaryKey && meta.has("meta.id")) primaryKey = name;
+			if (prop.type.designType === "string") stringProps.push(name);
+			if (meta.has("ui.dict.searchable")) explicitlySearchable.push(name);
+		}
+		this.fieldMeta = fieldMeta;
+		this.primaryKey = primaryKey;
+		this.searchableFields = explicitlySearchable.length > 0 ? explicitlySearchable : interfaceSearchable ? stringProps : stringProps;
+	}
+	hasField(path) {
+		return this.fieldMeta.has(path);
+	}
+	/**
+	* **GET /query** — returns an array of matched rows (up to `$limit`).
+	*/
+	async runQuery(url) {
+		const parsed = this.parseQueryString(url);
+		const validateError = this.validateParsed(parsed, "query");
+		if (validateError) return validateError;
+		return (await this.query({
+			filter: parsed.filter,
+			controls: parsed.controls
+		})).data;
+	}
+	/**
+	* **GET /pages** — paginated row window plus total count.
+	*/
+	async runPages(url) {
+		const parsed = this.parseQueryString(url);
+		const validateError = this.validateParsed(parsed, "pages");
+		if (validateError) return validateError;
+		const controls = parsed.controls;
+		const page = Math.max(Number(controls.$page || 1), 1);
+		const size = Math.max(Number(controls.$size || 10), 1);
+		const skip = (page - 1) * size;
+		const result = await this.query({
+			filter: parsed.filter,
+			controls: {
+				...controls,
+				$skip: skip,
+				$limit: size
+			}
+		});
+		return {
+			data: result.data,
+			page,
+			itemsPerPage: size,
+			pages: Math.ceil(result.count / size),
+			count: result.count
+		};
+	}
+	/**
+	* **GET /one/:id** — retrieves a single row by primary key.
+	*/
+	async runGetOne(id) {
+		return this.returnOne(this.getOne(id));
+	}
+	/**
+	* **GET /one?<pk>=<val>** — retrieves a single row by PK query param (fallback).
+	*/
+	async runGetOneComposite(query) {
+		const pk = this.primaryKey;
+		if (!pk) return new HttpError(400, "No primary key (@meta.id) on value-help interface");
+		const id = query[pk];
+		if (id === void 0) return new HttpError(400, `Missing PK field "${pk}"`);
+		return this.returnOne(this.getOne(id));
+	}
+	/**
+	* Meta response surfaces `@ui.dict.*` annotations as **hints** for the
+	* client picker UI (which controls to render); the server does not enforce
+	* these flags at request time.
+	*/
+	async buildMetaResponse() {
+		const fields = {};
+		for (const [path, meta] of this.fieldMeta) fields[path] = {
+			sortable: meta.has("ui.dict.sortable"),
+			filterable: meta.has("ui.dict.filterable")
+		};
+		return {
+			searchable: this.searchableFields.length > 0,
+			vectorSearchable: false,
+			searchIndexes: [],
+			primaryKeys: this.primaryKey ? [this.primaryKey] : [],
+			readOnly: this._isReadOnly(),
+			relations: [],
+			fields,
+			type: this.getSerializedType(),
+			actions: []
+		};
+	}
+	buildActions() {
+		return [];
+	}
+};
+__decorate([
+	Get("query"),
+	__decorateParam(0, Url()),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", Promise)
+], AsValueHelpController.prototype, "runQuery", null);
+__decorate([
+	Get("pages"),
+	__decorateParam(0, Url()),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", Promise)
+], AsValueHelpController.prototype, "runPages", null);
+__decorate([
+	Get("one/:id"),
+	__decorateParam(0, Param("id")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", Promise)
+], AsValueHelpController.prototype, "runGetOne", null);
+__decorate([
+	Get("one"),
+	__decorateParam(0, Query()),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [typeof (_ref2 = typeof Record !== "undefined" && Record) === "function" ? _ref2 : Object]),
+	__decorateMetadata("design:returntype", Promise)
+], AsValueHelpController.prototype, "runGetOneComposite", null);
+AsValueHelpController = __decorate([Inherit(), __decorateMetadata("design:paramtypes", [
+	Object,
+	String,
+	typeof (_ref$1 = typeof Moost !== "undefined" && Moost) === "function" ? _ref$1 : Object
+])], AsValueHelpController);
+//#endregion
+//#region src/as-json-value-help.controller.ts
+var _ref;
+let AsJsonValueHelpController = class AsJsonValueHelpController extends AsValueHelpController {
+	rows;
+	_pkIndex;
+	constructor(boundType, rows, app, controllerName) {
+		const name = controllerName || boundType.metadata.get("db.table") || "value-help";
+		super(boundType, name, app);
+		this.rows = rows;
+		if (this.primaryKey) {
+			const pk = this.primaryKey;
+			const index = /* @__PURE__ */ new Map();
+			for (const row of rows) index.set(String(row[pk]), row);
+			this._pkIndex = index;
+		}
+	}
+	async query(controls) {
+		let rows = this.rows;
+		if (controls.filter && Object.keys(controls.filter).length > 0) rows = rows.filter((row) => matchFilter(row, controls.filter));
+		const search = controls.controls.$search;
+		if (search) {
+			const needle = search.toLowerCase();
+			const fields = this.searchableFields;
+			rows = rows.filter((row) => {
+				for (const field of fields) {
+					const v = row[field];
+					if (typeof v === "string" && v.toLowerCase().includes(needle)) return true;
+				}
+				return false;
+			});
+		}
+		if (controls.controls.$sort) rows = sortRows(rows, controls.controls.$sort);
+		const total = rows.length;
+		const skip = Math.max(0, Number(controls.controls.$skip ?? 0));
+		const limit = Math.max(0, Number(controls.controls.$limit ?? total - skip));
+		return {
+			data: applySelect(rows.slice(skip, skip + limit), controls.controls.$select),
+			count: total
+		};
+	}
+	async getOne(id) {
+		return this._pkIndex?.get(String(id)) ?? null;
+	}
+};
+AsJsonValueHelpController = __decorate([Inherit(), __decorateMetadata("design:paramtypes", [
+	Object,
+	Array,
+	typeof (_ref = typeof Moost !== "undefined" && Moost) === "function" ? _ref : Object,
+	String
+])], AsJsonValueHelpController);
+function matchFilter(row, filter) {
+	if (!filter || typeof filter !== "object") return true;
+	for (const [key, value] of Object.entries(filter)) {
+		if (key === "$and") {
+			if (!Array.isArray(value)) continue;
+			if (!value.every((clause) => matchFilter(row, clause))) return false;
+			continue;
+		}
+		if (key === "$or") {
+			if (!Array.isArray(value)) continue;
+			if (!value.some((clause) => matchFilter(row, clause))) return false;
+			continue;
+		}
+		if (key === "$nor") {
+			if (!Array.isArray(value)) continue;
+			if (value.some((clause) => matchFilter(row, clause))) return false;
+			continue;
+		}
+		if (key === "$not") {
+			if (matchFilter(row, value)) return false;
+			continue;
+		}
+		if (key.startsWith("$")) continue;
+		const fieldValue = row[key];
+		if (!matchFieldPredicate(fieldValue, value)) return false;
+	}
+	return true;
+}
+function matchFieldPredicate(fieldValue, predicate) {
+	if (predicate === null || typeof predicate !== "object" || Array.isArray(predicate)) return fieldValue === predicate;
+	for (const [op, operand] of Object.entries(predicate)) switch (op) {
+		case "$eq":
+			if (fieldValue !== operand) return false;
+			break;
+		case "$ne":
+			if (fieldValue === operand) return false;
+			break;
+		case "$in":
+			if (!Array.isArray(operand) || !operand.includes(fieldValue)) return false;
+			break;
+		case "$nin":
+			if (!Array.isArray(operand) || operand.includes(fieldValue)) return false;
+			break;
+		case "$gt":
+			if (!(fieldValue > operand)) return false;
+			break;
+		case "$gte":
+			if (!(fieldValue >= operand)) return false;
+			break;
+		case "$lt":
+			if (!(fieldValue < operand)) return false;
+			break;
+		case "$lte":
+			if (!(fieldValue <= operand)) return false;
+			break;
+		case "$regex": {
+			const re = operand instanceof RegExp ? operand : new RegExp(String(operand));
+			if (typeof fieldValue !== "string" || !re.test(fieldValue)) return false;
+			break;
+		}
+		default: if (fieldValue !== operand) return false;
+	}
+	return true;
+}
+function sortRows(rows, sort) {
+	const keys = [];
+	const push = (name, explicit) => {
+		const clean = name.replace(/^[-+]/, "");
+		const dir = explicit ?? (name.startsWith("-") ? -1 : 1);
+		if (clean) keys.push({
+			name: clean,
+			dir
+		});
+	};
+	if (typeof sort === "string") for (const part of sort.split(",")) {
+		const trimmed = part.trim();
+		if (!trimmed) continue;
+		const [name, dir] = trimmed.split(":");
+		push(name, dir === "desc" ? -1 : dir === "asc" ? 1 : void 0);
+	}
+	else if (Array.isArray(sort)) {
+		for (const entry of sort) if (typeof entry === "string") push(entry);
+		else if (entry && typeof entry === "object") for (const [name, d] of Object.entries(entry)) push(name, d === "desc" || d === -1 ? -1 : 1);
+	} else if (sort && typeof sort === "object") for (const [name, d] of Object.entries(sort)) push(name, d === "desc" || d === -1 ? -1 : 1);
+	if (keys.length === 0) return rows;
+	const out = rows.slice();
+	out.sort((a, b) => {
+		for (const { name, dir } of keys) {
+			const av = a[name];
+			const bv = b[name];
+			if (av === bv) continue;
+			if (av === void 0 || av === null) return -1 * dir;
+			if (bv === void 0 || bv === null) return 1 * dir;
+			if (av < bv) return -1 * dir;
+			if (av > bv) return 1 * dir;
+		}
+		return 0;
+	});
+	return out;
+}
+function applySelect(rows, select) {
+	if (!select?.length) return rows;
+	return rows.map((row) => {
+		const out = {};
+		for (const key of select) out[key] = row[key];
+		return out;
+	});
+}
+//#endregion
+//#region src/actions/db-action.decorator.ts
+/**
+* Mark a controller method as a database action surfaced via `/meta`.
+*
+* Metadata-only — pair with `@Post(...)` for Moost to bind the route. The
+* meta builder reads this metadata plus the bound POST path lazily and
+* emits the action with `processor: 'backend'`. Order vs.
+* `@DbActionDefault()` does not matter — both merge into the same slot.
+*
+* @example
+* ```ts
+* @Post('actions/block')
+* @DbAction('block', { label: 'Block', icon: 'i-as-block', intent: 'negative' })
+* async blockUser(@DbActionPK() id: string) { ... }
+* ```
+*/
+function DbAction(name, opts = {}) {
+	return getMoostMate().decorate((current) => {
+		const meta = current;
+		return {
+			...current,
+			[MOOST_DB_ACTION]: mergeActionMeta(meta, {
+				name,
+				opts
+			})
+		};
+	});
+}
+//#endregion
+//#region src/actions/db-action-default.decorator.ts
+/**
+* Sugar that flips `default: true` on the same method's `@DbAction` metadata.
+* Equivalent to passing `opts.default = true`. Decorator order does not matter.
+*/
+function DbActionDefault() {
+	return getMoostMate().decorate((current) => {
+		const meta = current;
+		return {
+			...current,
+			[MOOST_DB_ACTION]: mergeActionMeta(meta, { opts: { default: true } })
+		};
+	});
+}
+//#endregion
+//#region src/actions/pk-source.ts
+/**
+* Extract the PK validation source from a controller instance. Looks for
+* `readable` (set by {@link AsDbReadableController}) or `table` (set by
+* {@link AsDbController}).
+*
+* If the controller has no typed table attached (e.g. a value-help
+* controller, or a plain Moost controller without `@TableController`),
+* throws an HTTP 500 — this is a **server misconfiguration**, not a client
+* error. The body parser has nothing to validate against, so the request
+* cannot proceed. Use `@Body()` and parse the PK manually if you need to
+* accept PK-shaped bodies on a controller without an attached table.
+*/
+function resolvePkSource(controller) {
+	const c = controller;
+	const candidate = c.readable ?? c.table;
+	if (!isPkValidationSource(candidate)) throw new HttpError(500, "@DbActionPK/@DbActionPKs requires a controller with an attached table (via @TableController / @ReadableController). Use @Body() instead if your controller has no typed table.");
+	return candidate;
+}
+function isPkValidationSource(value) {
+	if (!value || typeof value !== "object") return false;
+	const v = value;
+	return Array.isArray(v.primaryKeys) && Array.isArray(v.fieldDescriptors);
+}
+/**
+* Build a parameter decorator that parses the JSON request body, validates
+* it against the bound table's PK schema with `validate`, and tags the param
+* so {@link discoverActions} can infer the action's `level`.
+*/
+function createPkParamDecorator(kind, validate, resolverName) {
+	return ApplyDecorators(getMoostMate().decorate(MOOST_DB_ACTION_PARAM, kind), Resolve(async () => {
+		const body = await useBody().parseBody();
+		validate(body, resolvePkSource(useControllerContext().getController()));
+		return body;
+	}, resolverName));
+}
+//#endregion
+//#region src/actions/pk-validation.ts
+/**
+* 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);
+	if (errors.length > 0) throw new ValidatorError(errors);
+}
+/**
+* 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) {
+	if (!Array.isArray(body)) throw new ValidatorError([{
+		path: "",
+		message: "Expected JSON array of primary keys",
+		details: []
+	}]);
+	const errors = [];
+	for (let i = 0; i < body.length; i++) errors.push(...collectPkErrors(body[i], source, `[${i}]`));
+	if (errors.length > 0) throw new ValidatorError(errors);
+}
+function collectPkErrors(value, source, pathPrefix) {
+	const pkFields = source.primaryKeys;
+	if (pkFields.length === 0) return [{
+		path: pathPrefix,
+		message: "Table has no primary key configured",
+		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) {
+		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);
+		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);
+	if (expected === "number" && typeof value !== "number") return scalarMismatch(path, expected, value);
+	if (expected === "boolean" && typeof value !== "boolean") return scalarMismatch(path, expected, value);
+}
+function scalarMismatch(path, expected, value) {
+	return {
+		path,
+		message: `Expected primary-key value to be ${expected}, got ${describe(value)}`,
+		details: []
+	};
+}
+function describe(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/actions/db-action-pk.decorator.ts
+/**
+* Parameter resolver that reads the primary key from the JSON request body
+* and validates it against the bound table's PK schema.
+*
+* - Single-field PK → JSON-encoded scalar (`"abc"`, `42`, `true`).
+* - Composite PK → JSON object with all PK fields.
+*
+* Validation is strict — 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'`.
+*/
+function DbActionPK() {
+	return createPkParamDecorator("pk", validateSinglePk, "dbActionPk");
+}
+//#endregion
+//#region src/actions/db-action-pks.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.
+*
+* - Scalar PK → JSON array of scalars (`["a","b","c"]`).
+* - Composite PK → JSON array of objects.
+*
+* Validation is strict — no type coercion. Marks the param so
+* {@link discoverActions} can infer the action's `level` as `'rows'`.
+*/
+function DbActionPKs() {
+	return createPkParamDecorator("pks", validateMultiPk, "dbActionPks");
+}
+//#endregion
+//#region src/actions/db-actions.decorator.ts
+/**
+* Declare class-level actions on a controller. Entries are flat dicts with
+* `processor: 'navigate' | 'custom' | 'backend'` matching the `/meta` wire
+* shape (see {@link TDbActionsEntry}). Each entry MUST specify `level`. Use
+* 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.
+*
+* Multiple `@DbActions` (and shortcut) decorators on the same class
+* accumulate.
+*/
+function DbActions(dict) {
+	return classLevelActions(dict);
+}
+/** Sugar for `@DbActions` with `level: 'table'` injected into each entry. */
+function DbTableActions(dict) {
+	return classLevelActions(dict, "table");
+}
+/** Sugar for `@DbActions` with `level: 'row'` injected into each entry. */
+function DbRowActions(dict) {
+	return classLevelActions(dict, "row");
+}
+/** Sugar for `@DbActions` with `level: 'rows'` injected into each entry. */
+function DbRowsActions(dict) {
+	return classLevelActions(dict, "rows");
+}
+function classLevelActions(dict, forcedLevel) {
+	const entries = [];
+	for (const [name, entry] of Object.entries(dict)) entries.push({
+		name,
+		entry,
+		forcedLevel
+	});
+	return getMoostMate().decorate((current) => {
+		const existing = current["atscript_db_actions"] ?? [];
+		return {
+			...current,
+			[MOOST_DB_ACTIONS]: [...existing, ...entries]
+		};
+	});
+}
+//#endregion
+export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionPK, DbActionPKs, DbActions, DbRowActions, DbRowsActions, DbTableActions, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, discoverActions, validationErrorTransform };