@atscript/moost-db 0.1.60 → 0.1.62

package/dist/index.cjs

@@ -199,9 +199,6 @@ function isAsValueHelpControllerSubclass(ctor) {
 	if (!asValueHelpCtor) return false;
 	return asValueHelpCtor.prototype.isPrototypeOf(ctor.prototype);
 }
-function isAsDbReadableControllerInstance(value) {
-	return !!asDbReadableCtor && value instanceof asDbReadableCtor;
-}
 //#endregion
 //#region src/actions/keys.ts
 /** Log-message prefix for warnings emitted from the actions subsystem. */
@@ -216,6 +213,21 @@ const MOOST_DB_ACTION_PARAM = "atscript_db_action_param";
 const MOOST_DB_ACTION_ROW = "atscript_db_action_row";
 const MOOST_DB_ACTION_ROWS = "atscript_db_action_rows";
 /**
+* Param-level metadata key — written by `@InputForm(FormType)`. Carries the
+* compiled `.as` class plus its `.name` so {@link discoverActions} can both
+* emit `inputForm` on `/meta` and register the type in the controller's form
+* registry for `GET /meta/form/:name`.
+*/
+const MOOST_DB_ACTION_INPUT_FORM = "atscript_db_action_input_form";
+/**
+* Generic param-level metadata key — written by `@InputForm(FormType)`
+* alongside {@link MOOST_DB_ACTION_INPUT_FORM}. Holds just the type ref so a
+* generic atscript-aware Moost pipe (installed globally via
+* `app.applyGlobalPipes(...)` or scoped via `@Pipe(...)`) can validate the
+* resolved value without knowing about the moost-db-specific key.
+*/
+const MOOST_ATSCRIPT_TYPE = "atscript_type";
+/**
 * 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
@@ -238,6 +250,8 @@ function scanParamLevel(params) {
 	let multi = false;
 	let hasRowParam = false;
 	let hasBody = false;
+	let inputForm;
+	let hasDuplicateInputForm = false;
 	for (const p of params) {
 		const kind = p[MOOST_DB_ACTION_PARAM];
 		if (kind === "id") single = true;
@@ -251,13 +265,18 @@ function scanParamLevel(params) {
 			hasRowParam = true;
 		}
 		if (p.paramSource === "BODY") hasBody = true;
+		const form = p[MOOST_DB_ACTION_INPUT_FORM];
+		if (form) if (inputForm) hasDuplicateInputForm = true;
+		else inputForm = form;
 	}
 	return {
 		level: single && multi ? "table" : single ? "row" : multi ? "rows" : "table",
 		single,
 		multi,
 		hasRowParam,
-		hasBody
+		hasBody,
+		inputForm,
+		hasDuplicateInputForm
 	};
 }
 //#endregion
@@ -274,6 +293,34 @@ const OPTIONAL_FIELDS = [
 ];
 const actionsCache = /* @__PURE__ */ new WeakMap();
 const rowLevelActionsCache = /* @__PURE__ */ new WeakMap();
+/**
+* Per-controller registry of form names → compiled `.as` classes, populated
+* during {@link discoverActions} when a method param carries
+* {@link MOOST_DB_ACTION_INPUT_FORM}. Backs `GET /meta/form/:name`.
+*
+* Same name + same type ref across multiple actions is fine (forms can be
+* reused). Same name + *different* type refs is an ambiguity — discovery
+* warns and drops the second action.
+*/
+const formRegistry = /* @__PURE__ */ new WeakMap();
+/** Lookup helper for `AsReadableController.metaForm()`. */
+function getControllerFormType(ctor, name) {
+	return formRegistry.get(ctor)?.get(name);
+}
+function registerFormType(ctor, meta, actionName, logger) {
+	let map = formRegistry.get(ctor);
+	if (!map) {
+		map = /* @__PURE__ */ new Map();
+		formRegistry.set(ctor, map);
+	}
+	const existing = map.get(meta.name);
+	if (existing && existing !== meta.type) {
+		logger.warn(`${WARN_PREFIX} action "${actionName}" — form name "${meta.name}" already registered on this controller with a different type. Reusing the same FormType across actions is fine; clashing names are not — dropping`);
+		return false;
+	}
+	if (!existing) map.set(meta.name, meta.type);
+	return true;
+}
 /** 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);
@@ -359,6 +406,10 @@ function collectMethodActions(ctor, overview, logger, out, seen) {
 			processor: "backend",
 			value: path
 		};
+		if (levelInfer.inputForm) {
+			if (!registerFormType(ctor, levelInfer.inputForm, action.name, logger)) continue;
+			info.inputForm = levelInfer.inputForm.name;
+		}
 		emitInfo(info, action.opts);
 		seen.add(action.name);
 		out.push({
@@ -373,10 +424,12 @@ function inferMethodLevel(params, actionName, logger) {
 		logger.warn(`${WARN_PREFIX} action "${actionName}" mixes single-cardinality and multi-cardinality decorators (@DbActionID / @DbActionRow vs @DbActionIDs / @DbActionRows) — dropping`);
 		return null;
 	}
+	if (scan.hasDuplicateInputForm) logger.warn(`${WARN_PREFIX} action "${actionName}" has more than one @InputForm() param — only the first is honored. Compose multiple inputs into a single form interface.`);
 	return {
 		level: scan.level,
 		bodyConflict: scan.hasBody && scan.level !== "table",
-		hasRowParam: scan.hasRowParam
+		hasRowParam: scan.hasRowParam,
+		inputForm: scan.inputForm
 	};
 }
 function collectClassActions(ctor, logger, out, seen) {
@@ -487,6 +540,13 @@ function __decorate(decorators, target, key, desc) {
 	return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 //#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-readable.controller.ts
 var _ref$4;
 let AsReadableController = class AsReadableController {
@@ -502,6 +562,8 @@ let AsReadableController = class AsReadableController {
 	_serializedType;
 	/** Cached full meta response (computed lazily on first meta() call). */
 	_metaResponse;
+	/** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
+	_formSchemas = /* @__PURE__ */ new Map();
 	constructor(boundType, controllerName, app, kindTag = "readable") {
 		this.boundType = boundType;
 		this.controllerName = controllerName;
@@ -644,6 +706,25 @@ let AsReadableController = class AsReadableController {
 		return this.applyMetaOverlay(this._metaResponse);
 	}
 	/**
+	* **GET /meta/form/:name** — returns the serialized schema of a form
+	* referenced by an action's `inputForm` field. The form name is the
+	* compiled `.as` class's `.name`, registered when an action's parameter is
+	* decorated with `@InputForm(FormType)`. Schemas are serialized once and
+	* cached per controller; the response uses the same annotation-allowlist
+	* policy as {@link getSerializeOptions}.
+	*/
+	async metaForm(name) {
+		discoverActions(this.constructor, this.app, this.logger);
+		const formType = getControllerFormType(this.constructor, name);
+		if (!formType) throw new _moostjs_event_http.HttpError(404, `Unknown form "${name}"`);
+		let cached = this._formSchemas.get(name);
+		if (!cached) {
+			cached = (0, _atscript_typescript_utils.serializeAnnotatedType)(formType, this.getSerializeOptions());
+			this._formSchemas.set(name, cached);
+		}
+		return cached;
+	}
+	/**
 	* Builds the `/meta` payload. Override in subclasses to populate source-specific
 	* fields. Subclasses that fully replace the envelope must call
 	* {@link buildActions} and {@link buildCrud} directly so `@DbAction*`
@@ -697,6 +778,13 @@ __decorate([
 	__decorateMetadata("design:paramtypes", []),
 	__decorateMetadata("design:returntype", Promise)
 ], AsReadableController.prototype, "meta", null);
+__decorate([
+	(0, _moostjs_event_http.Get)("meta/form/:name"),
+	__decorateParam(0, (0, moost.Param)("name")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", Promise)
+], AsReadableController.prototype, "metaForm", null);
 AsReadableController = __decorate([UseValidationErrorTransform(), __decorateMetadata("design:paramtypes", [
 	Object,
 	String,
@@ -859,13 +947,6 @@ const QUERY_CONTROLS = [
 const PAGES_CONTROLS = ["filter", ...dtoControls(PagesControlsDto)];
 const ONE_CONTROLS = dtoControls(GetOneControlsDto);
 //#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 {
@@ -873,14 +954,12 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	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;
 	}
@@ -1104,12 +1183,9 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		});
 		return result;
 	}
-	/**
-	* Extracts a composite identifier object from query params.
-	* Tries composite primary key first, then compound unique indexes.
-	*/
-	extractCompositeId(query) {
-		for (const id of this._compositeIdShapes) {
+	/** Pick the first identification (PK or unique index) whose fields are all present in the query. */
+	extractIdShape(query) {
+		for (const id of this.readable.identifications) {
 			const idObj = {};
 			let allPresent = true;
 			for (const field of id.fields) {
@@ -1121,7 +1197,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			}
 			if (allPresent) return idObj;
 		}
-		return new _moostjs_event_http.HttpError(400, "Query params do not match any composite primary key or compound unique index");
+		return new _moostjs_event_http.HttpError(400, "Query params do not match any primary key or unique index");
 	}
 	/**
 	* **GET /query** — returns an array of records or a count.
@@ -1237,7 +1313,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	* (composite primary key or compound unique index).
 	*/
 	async getOneComposite(query, url) {
-		const idObj = this.extractCompositeId(query);
+		const idObj = this.extractIdShape(query);
 		if (idObj instanceof _moostjs_event_http.HttpError) return idObj;
 		const parsed = this.parseQueryString(url);
 		this._coerceActionsControl(parsed.controls);
@@ -1437,7 +1513,7 @@ let AsDbController = class AsDbController extends AsDbReadableController {
 	* (composite primary key or compound unique index).
 	*/
 	async removeComposite(query) {
-		const idObj = this.extractCompositeId(query);
+		const idObj = this.extractIdShape(query);
 		if (idObj instanceof _moostjs_event_http.HttpError) return idObj;
 		const resolvedId = await this.onRemove(idObj);
 		if (resolvedId === void 0) return new _moostjs_event_http.HttpError(500, "Not deleted");
@@ -1855,12 +1931,35 @@ function readCurrentActionMeta(ctx) {
 	return (0, moost.getMoostMate)().read(ctrl.constructor, methodName)?.[MOOST_DB_ACTION];
 }
 //#endregion
+//#region src/actions/input-form-cache.ts
+/**
+* Cached parse of the action request body. Centralises the shape check so
+* every per-param resolver (`@DbActionID*`, `@DbActionRow*`, `@InputForm`)
+* reads through the same gate. An array or scalar root is rejected with the
+* same `ValidatorError` envelope as today's strict-shape ID failures.
+*/
+const dbActionBodySlot = (0, _wooksjs_event_core.cached)(async (ctx) => {
+	const raw = await (0, _wooksjs_http_body.useBody)(ctx).parseBody();
+	if (raw == null) return {};
+	if (typeof raw !== "object" || Array.isArray(raw)) throw new _atscript_typescript_utils.ValidatorError([{
+		path: "",
+		message: "Action body must be an object of shape { ids?, input? }"
+	}]);
+	return raw;
+});
+/** Cached `body.input` slot — consumed by `@InputForm()` and `useDbActionInput()`. */
+const dbActionInputSlot = (0, _wooksjs_event_core.cached)(async (ctx) => {
+	return (await ctx.get(dbActionBodySlot)).input;
+});
+/** Composable for in-handler reads of the form input. */
+const useDbActionInput = (0, _wooksjs_event_core.defineWook)((ctx) => ({ load: () => ctx.get(dbActionInputSlot) }));
+//#endregion
 //#region src/actions/id-validation.ts
 const SOURCE_CACHE = /* @__PURE__ */ new WeakMap();
 function getSourceCache(source) {
 	let cache = SOURCE_CACHE.get(source);
 	if (cache) return cache;
-	const identifications = source.getIdentifications();
+	const identifications = source.identifications;
 	const byKeySig = /* @__PURE__ */ new Map();
 	for (const ident of identifications) byKeySig.set(fieldsSig(ident.fields), ident);
 	const fieldByName = /* @__PURE__ */ new Map();
@@ -1879,7 +1978,7 @@ function fieldsSig(fields) {
 function isIdValidationSource(value) {
 	if (!value || typeof value !== "object") return false;
 	const v = value;
-	return typeof v.getIdentifications === "function" && Array.isArray(v.fieldDescriptors);
+	return Array.isArray(v.identifications) && Array.isArray(v.fieldDescriptors);
 }
 function validateSingleId(body, source, path = "") {
 	const errors = collectIdErrors(body, source, path);
@@ -1947,22 +2046,34 @@ function isPlainObject(value) {
 //#endregion
 //#region src/actions/id-cache.ts
 const boundTableKey = (0, _wooksjs_event_core.key)("atscript_db_action_bound_table");
-function getActionTable(ctx) {
-	const fromSlot = ctx.has(boundTableKey) ? ctx.get(boundTableKey) : void 0;
-	if (fromSlot) return fromSlot;
+function controllerTable(ctx) {
 	const ctrl = (0, moost.useControllerContext)(ctx).getController();
 	return ctrl?.readable ?? ctrl?.table ?? null;
 }
+function getActionTable(ctx) {
+	return (ctx.has(boundTableKey) ? ctx.get(boundTableKey) : void 0) ?? controllerTable(ctx);
+}
+const warnedTags = /* @__PURE__ */ new Set();
 function noTableError(ctx) {
 	const actionName = readCurrentActionMeta(ctx)?.name;
-	return new _moostjs_event_http.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.`);
+	const tag = actionName ? `"${actionName}"` : "<unknown>";
+	if (!warnedTags.has(tag)) {
+		warnedTags.add(tag);
+		console.warn(`${WARN_PREFIX} ${tag}: controller has no readable/table property and the action declares no opts.table. Either expose readable/table on the controller, extend AsDbReadableController, or pass opts.table on @DbAction.`);
+	}
+	return new _moostjs_event_http.HttpError(500, {
+		statusCode: 500,
+		error: "Internal Server Error",
+		message: "Internal server error",
+		code: "ACTION_TABLE_NOT_BOUND"
+	});
 }
 async function resolveValidatedId(ctx, validate) {
 	const table = getActionTable(ctx);
 	if (!isIdValidationSource(table)) throw noTableError(ctx);
-	const body = await (0, _wooksjs_http_body.useBody)(ctx).parseBody();
-	validate(body, table);
-	return body;
+	const env = await ctx.get(dbActionBodySlot);
+	validate(env.ids, table);
+	return env.ids;
 }
 const dbActionIdSlot = (0, _wooksjs_event_core.cached)((ctx) => resolveValidatedId(ctx, validateSingleId));
 const dbActionIdsSlot = (0, _wooksjs_event_core.cached)(async (ctx) => {
@@ -2062,15 +2173,11 @@ const useDbActionRows = (0, _wooksjs_event_core.defineWook)((ctx) => ({ load: ()
 //#endregion
 //#region src/actions/gate-interceptor.ts
 const GATE_PRIORITY = moost.TInterceptorPriority.AFTER_GUARD;
-function injectBoundTable(table) {
+function injectBoundTable(fallback) {
 	const ctx = (0, _wooksjs_event_core.current)();
 	if (ctx.has(boundTableKey)) return;
-	const controller = (0, moost.useControllerContext)(ctx).getController();
-	if (isAsDbReadableControllerInstance(controller)) {
-		ctx.set(boundTableKey, controller.readable);
-		return;
-	}
-	if (table != null) ctx.set(boundTableKey, table);
+	const t = controllerTable(ctx) ?? fallback;
+	if (t != null) ctx.set(boundTableKey, t);
 }
 function buildGateInterceptor(opts) {
 	const { action, level, disabled, onDisabledRows, table } = opts;
@@ -2325,6 +2432,43 @@ function classLevelActions(dict, forcedLevel) {
 	});
 }
 //#endregion
+//#region src/actions/db-action-input-form.decorator.ts
+/**
+* Parameter decorator that injects the `input` field of the action request
+* envelope (`{ ids?, input? }`) into the handler.
+*
+* Pairs the resolved value with two pieces of param-level metadata:
+*
+* 1. {@link MOOST_DB_ACTION_INPUT_FORM} — the compiled `.as` class plus its
+*    name, consumed by {@link discoverActions} to:
+*    - emit `inputForm: FormType.name` on the action's `/meta` entry, and
+*    - register the type in the controller's form registry so
+*      `GET /meta/form/:name` can serve the serialized schema.
+* 2. {@link MOOST_ATSCRIPT_TYPE} — just the type ref, providing a generic
+*    hook any atscript-aware Moost pipe can read without knowing about the
+*    moost-db-specific key.
+*
+* Validation is intentionally *not* performed here. To validate `input`
+* against `FormType`, install an atscript validator pipe globally
+* (`app.applyGlobalPipes(...)`) or scope it via `@Pipe(...)`. The pipe reads
+* `MOOST_ATSCRIPT_TYPE` off the param and runs `FormType.validator()`.
+*
+* Only one `@InputForm()` per action is supported. To collect multiple
+* structured inputs, compose them into a single `.as` interface and pass an
+* array form on the field whose user-facing intent is "list of items".
+*
+* @param formType A compiled `.as` interface class (carries `.validator()`,
+*                 `.metadata`, etc.).
+*/
+function InputForm(formType) {
+	const mate = (0, moost.getMoostMate)();
+	const meta = {
+		type: formType,
+		name: formType.name
+	};
+	return (0, moost.ApplyDecorators)(mate.decorate(MOOST_DB_ACTION_INPUT_FORM, meta), mate.decorate(MOOST_ATSCRIPT_TYPE, formType), (0, moost.Resolve)(async () => (0, _wooksjs_event_core.current)().get(dbActionInputSlot), "dbActionInputForm"));
+}
+//#endregion
 //#region src/actions/per-row.ts
 /**
 * Lift a per-row predicate into the batch shape required by
@@ -2381,6 +2525,9 @@ exports.DbActions = DbActions;
 exports.DbRowActions = DbRowActions;
 exports.DbRowsActions = DbRowsActions;
 exports.DbTableActions = DbTableActions;
+exports.InputForm = InputForm;
+exports.MOOST_ATSCRIPT_TYPE = MOOST_ATSCRIPT_TYPE;
+exports.MOOST_DB_ACTION_INPUT_FORM = MOOST_DB_ACTION_INPUT_FORM;
 exports.ONE_CONTROLS = ONE_CONTROLS;
 exports.PAGES_CONTROLS = PAGES_CONTROLS;
 exports.QUERY_CONTROLS = QUERY_CONTROLS;
@@ -2390,10 +2537,14 @@ exports.TABLE_DEF = TABLE_DEF;
 exports.TableController = TableController;
 exports.UseValidationErrorTransform = UseValidationErrorTransform;
 exports.ViewController = ViewController;
+exports.dbActionBodySlot = dbActionBodySlot;
+exports.dbActionInputSlot = dbActionInputSlot;
 exports.discoverActions = discoverActions;
+exports.getControllerFormType = getControllerFormType;
 exports.perRow = perRow;
 exports.useDbActionId = useDbActionId;
 exports.useDbActionIds = useDbActionIds;
+exports.useDbActionInput = useDbActionInput;
 exports.useDbActionRow = useDbActionRow;
 exports.useDbActionRows = useDbActionRows;
 exports.validationErrorTransform = validationErrorTransform;

package/dist/index.d.cts

@@ -1,6 +1,5 @@
-import * as _atscript_typescript_utils0 from "@atscript/typescript/utils";
-import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, Validator } from "@atscript/typescript/utils";
 import * as _uniqu_url0 from "@uniqu/url";
+import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, TSerializedAnnotatedType, Validator } from "@atscript/typescript/utils";
 import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, FlatOf, TCrudOp, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TIdentification, TMetaResponse, Uniquery, UniqueryControls } from "@atscript/db";
 import { HttpError } from "@moostjs/event-http";
 import * as moost from "moost";
@@ -61,13 +60,15 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   private _serializedType?;
   /** Cached full meta response (computed lazily on first meta() call). */
   private _metaResponse?;
+  /** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
+  private _formSchemas;
   constructor(boundType: T, controllerName: string, app: Moost, kindTag?: string);
   /** Subclass contract: return `true` if `path` addresses a valid field on the bound source. */
   protected abstract hasField(path: string): boolean;
   /** Sets @db.http.path on the type metadata from the controller's computed prefix. */
   private _resolveHttpPath;
   /** Lazily serializes the bound type (after all controllers have set @db.http.path). */
-  protected getSerializedType(): _atscript_typescript_utils0.TSerializedAnnotatedType;
+  protected getSerializedType(): TSerializedAnnotatedType;
   /**
    * One-time initialization hook. Override to seed data, register watchers, etc.
    */
@@ -112,6 +113,15 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * subclasses can prune the response by principal.
    */
   meta(): Promise<TMetaResponse>;
+  /**
+   * **GET /meta/form/:name** — returns the serialized schema of a form
+   * referenced by an action's `inputForm` field. The form name is the
+   * compiled `.as` class's `.name`, registered when an action's parameter is
+   * decorated with `@InputForm(FormType)`. Schemas are serialized once and
+   * cached per controller; the response uses the same annotation-allowlist
+   * policy as {@link getSerializeOptions}.
+   */
+  metaForm(name: string): Promise<TSerializedAnnotatedType>;
   /**
    * Builds the `/meta` payload. Override in subclasses to populate source-specific
    * fields. Subclasses that fully replace the envelope must call
@@ -155,7 +165,6 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   protected readable: AtscriptDbReadable<T>;
   private readonly _gates;
   private readonly _preferredIdSet;
-  private readonly _compositeIdShapes;
   private readonly _overlayIsNoOp;
   constructor(readable: AtscriptDbReadable<T>, app: Moost);
   private _buildGates;
@@ -200,11 +209,8 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * family (count vs no-count).
    */
   private _runReadWithActions;
-  /**
-   * Extracts a composite identifier object from query params.
-   * Tries composite primary key first, then compound unique indexes.
-   */
-  protected extractCompositeId(query: Record<string, string>): Record<string, unknown> | HttpError;
+  /** Pick the first identification (PK or unique index) whose fields are all present in the query. */
+  protected extractIdShape(query: Record<string, string>): Record<string, unknown> | HttpError;
   /**
    * **GET /query** — returns an array of records or a count.
    */
@@ -720,6 +726,38 @@ declare function DbRowActions<TRow = unknown, const D extends Record<string, unk
 /** Sugar for `@DbActions` with `level: 'rows'` injected into each entry. */
 declare function DbRowsActions<TRow = unknown, const D extends Record<string, unknown> = {}>(dict: D & ValidatedUnpinnedDict<TRow, D>): ClassDecorator;
 //#endregion
+//#region src/actions/db-action-input-form.decorator.d.ts
+/**
+ * Parameter decorator that injects the `input` field of the action request
+ * envelope (`{ ids?, input? }`) into the handler.
+ *
+ * Pairs the resolved value with two pieces of param-level metadata:
+ *
+ * 1. {@link MOOST_DB_ACTION_INPUT_FORM} — the compiled `.as` class plus its
+ *    name, consumed by {@link discoverActions} to:
+ *    - emit `inputForm: FormType.name` on the action's `/meta` entry, and
+ *    - register the type in the controller's form registry so
+ *      `GET /meta/form/:name` can serve the serialized schema.
+ * 2. {@link MOOST_ATSCRIPT_TYPE} — just the type ref, providing a generic
+ *    hook any atscript-aware Moost pipe can read without knowing about the
+ *    moost-db-specific key.
+ *
+ * Validation is intentionally *not* performed here. To validate `input`
+ * against `FormType`, install an atscript validator pipe globally
+ * (`app.applyGlobalPipes(...)`) or scope it via `@Pipe(...)`. The pipe reads
+ * `MOOST_ATSCRIPT_TYPE` off the param and runs `FormType.validator()`.
+ *
+ * Only one `@InputForm()` per action is supported. To collect multiple
+ * structured inputs, compose them into a single `.as` interface and pass an
+ * array form on the field whose user-facing intent is "list of items".
+ *
+ * @param formType A compiled `.as` interface class (carries `.validator()`,
+ *                 `.metadata`, etc.).
+ */
+declare function InputForm<T extends TAtscriptAnnotatedType & {
+  readonly name: string;
+}>(formType: T): ParameterDecorator;
+//#endregion
 //#region src/actions/discover.d.ts
 /**
  * Pairs the wire-shaped `info` with the original decorator opts / dict entry,
@@ -730,13 +768,16 @@ interface TDbActionEnvelope {
   info: TDbActionInfo$1;
   raw: DbActionOpts | TDbActionsEntry;
 }
+/** Lookup helper for `AsReadableController.metaForm()`. */
+declare function getControllerFormType(ctor: Function, name: string): TAtscriptAnnotatedType | undefined;
 /** Discover actions on a controller, memoized per ctor. `info`-only callers map `e => e.info`. */
 declare function discoverActions(controllerCtor: Function, app: Moost, logger: TConsoleBase): TDbActionEnvelope[];
 //#endregion
 //#region src/actions/id-validation.d.ts
+/** Duck-typed shape; matches `AtscriptDbReadable`'s public surface. */
 interface IdValidationSource {
-  getIdentifications(): readonly TIdentification[];
-  fieldDescriptors: readonly TDbFieldMeta[];
+  readonly identifications: readonly TIdentification[];
+  readonly fieldDescriptors: readonly TDbFieldMeta[];
 }
 //#endregion
 //#region src/actions/id-cache.d.ts
@@ -755,6 +796,94 @@ declare const useDbActionRows: _wooksjs_event_core0.WookComposable<{
   load: () => Promise<(Record<string, unknown> | undefined)[]>;
 }>;
 //#endregion
+//#region src/actions/input-form-cache.d.ts
+/**
+ * Wire-shape of an action request body. Both fields are optional:
+ *
+ * - `ids` — what previously sat at the body root: a single identifier object
+ *   (`'row'`-level), an array of identifier objects (`'rows'`-level), or
+ *   absent (`'table'`-level).
+ * - `input` — present only when the action declares an `@InputForm()`
+ *   parameter; carries the form payload the user filled out.
+ */
+interface DbActionEnvelope {
+  ids?: unknown;
+  input?: unknown;
+}
+/**
+ * Cached parse of the action request body. Centralises the shape check so
+ * every per-param resolver (`@DbActionID*`, `@DbActionRow*`, `@InputForm`)
+ * reads through the same gate. An array or scalar root is rejected with the
+ * same `ValidatorError` envelope as today's strict-shape ID failures.
+ */
+declare const dbActionBodySlot: moost.Cached<Promise<DbActionEnvelope>>;
+/** Cached `body.input` slot — consumed by `@InputForm()` and `useDbActionInput()`. */
+declare const dbActionInputSlot: moost.Cached<Promise<unknown>>;
+/** Composable for in-handler reads of the form input. */
+declare const useDbActionInput: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<unknown>;
+}>;
+//#endregion
+//#region src/actions/keys.d.ts
+/** Method-level metadata key — written by `@DbAction(name, opts)`. */
+declare 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. */
+declare const MOOST_DB_ACTIONS = "atscript_db_actions";
+/** Param-level metadata key — written by `@DbActionID()` / `@DbActionIDs()`. Drives level inference. */
+declare const MOOST_DB_ACTION_PARAM = "atscript_db_action_param";
+/** Param-level marker keys — written by `@DbActionRow()` / `@DbActionRows()`. */
+declare const MOOST_DB_ACTION_ROW = "atscript_db_action_row";
+declare const MOOST_DB_ACTION_ROWS = "atscript_db_action_rows";
+/**
+ * Param-level metadata key — written by `@InputForm(FormType)`. Carries the
+ * compiled `.as` class plus its `.name` so {@link discoverActions} can both
+ * emit `inputForm` on `/meta` and register the type in the controller's form
+ * registry for `GET /meta/form/:name`.
+ */
+declare const MOOST_DB_ACTION_INPUT_FORM = "atscript_db_action_input_form";
+/**
+ * Generic param-level metadata key — written by `@InputForm(FormType)`
+ * alongside {@link MOOST_DB_ACTION_INPUT_FORM}. Holds just the type ref so a
+ * generic atscript-aware Moost pipe (installed globally via
+ * `app.applyGlobalPipes(...)` or scoped via `@Pipe(...)`) can validate the
+ * resolved value without knowing about the moost-db-specific key.
+ */
+declare const MOOST_ATSCRIPT_TYPE = "atscript_type";
+type TDbActionRowMarker = true;
+/** Stamped by `@InputForm(FormType)` — the compiled `.as` class + the wire name (`FormType.name`). */
+interface TDbActionInputFormMeta {
+  type: TAtscriptAnnotatedType;
+  name: string;
+}
+/** Method-level action metadata written by `@DbAction(name, opts)`. */
+interface TDbActionMeta {
+  name: string;
+  opts: DbActionOpts;
+}
+/** Class-level entry — a `TDbActionsEntry` plus its dictionary key. */
+interface TDbClassActionMeta {
+  name: string;
+  entry: TDbActionsEntry;
+}
+/** Param marker kind — informs level inference and ID-resolution shape. */
+type TDbActionParamKind = "id" | "ids";
+declare module "moost" {
+  interface TMoostMetadata {
+    [MOOST_DB_ACTION]?: TDbActionMeta;
+    [MOOST_DB_ACTIONS]?: TDbClassActionMeta[];
+    [MOOST_DB_ACTION_PARAM]?: TDbActionParamKind;
+    [MOOST_DB_ACTION_ROW]?: TDbActionRowMarker;
+    [MOOST_DB_ACTION_ROWS]?: TDbActionRowMarker;
+  }
+  interface TMoostParamsMetadata {
+    [MOOST_DB_ACTION_PARAM]?: TDbActionParamKind;
+    [MOOST_DB_ACTION_ROW]?: TDbActionRowMarker;
+    [MOOST_DB_ACTION_ROWS]?: TDbActionRowMarker;
+    [MOOST_DB_ACTION_INPUT_FORM]?: TDbActionInputFormMeta;
+    [MOOST_ATSCRIPT_TYPE]?: TAtscriptAnnotatedType;
+  }
+}
+//#endregion
 //#region src/actions/action-disabled-error.d.ts
 /**
  * Wire-body shape for server-side gate rejections. The `name` discriminator
@@ -815,4 +944,4 @@ declare const QUERY_CONTROLS: readonly string[];
 declare const PAGES_CONTROLS: readonly string[];
 declare const ONE_CONTROLS: readonly string[];
 //#endregion
-export { ActionDisabledError, ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionID, DbActionIDs, DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, IdValidationSource, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, TDbActionsEntry, TDbActionsEntryUnpinned, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, discoverActions, perRow, useDbActionId, useDbActionIds, useDbActionRow, useDbActionRows, validationErrorTransform };
+export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, type IdValidationSource, InputForm, MOOST_ATSCRIPT_TYPE, MOOST_DB_ACTION_INPUT_FORM, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, dbActionBodySlot, dbActionInputSlot, discoverActions, getControllerFormType, perRow, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };

package/dist/index.d.mts

@@ -1,5 +1,4 @@
-import * as _atscript_typescript_utils0 from "@atscript/typescript/utils";
-import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, Validator } from "@atscript/typescript/utils";
+import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, TSerializedAnnotatedType, Validator } from "@atscript/typescript/utils";
 import { HttpError } from "@moostjs/event-http";
 import * as moost from "moost";
 import { Moost, TConsoleBase } from "moost";
@@ -61,13 +60,15 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   private _serializedType?;
   /** Cached full meta response (computed lazily on first meta() call). */
   private _metaResponse?;
+  /** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
+  private _formSchemas;
   constructor(boundType: T, controllerName: string, app: Moost, kindTag?: string);
   /** Subclass contract: return `true` if `path` addresses a valid field on the bound source. */
   protected abstract hasField(path: string): boolean;
   /** Sets @db.http.path on the type metadata from the controller's computed prefix. */
   private _resolveHttpPath;
   /** Lazily serializes the bound type (after all controllers have set @db.http.path). */
-  protected getSerializedType(): _atscript_typescript_utils0.TSerializedAnnotatedType;
+  protected getSerializedType(): TSerializedAnnotatedType;
   /**
    * One-time initialization hook. Override to seed data, register watchers, etc.
    */
@@ -112,6 +113,15 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * subclasses can prune the response by principal.
    */
   meta(): Promise<TMetaResponse>;
+  /**
+   * **GET /meta/form/:name** — returns the serialized schema of a form
+   * referenced by an action's `inputForm` field. The form name is the
+   * compiled `.as` class's `.name`, registered when an action's parameter is
+   * decorated with `@InputForm(FormType)`. Schemas are serialized once and
+   * cached per controller; the response uses the same annotation-allowlist
+   * policy as {@link getSerializeOptions}.
+   */
+  metaForm(name: string): Promise<TSerializedAnnotatedType>;
   /**
    * Builds the `/meta` payload. Override in subclasses to populate source-specific
    * fields. Subclasses that fully replace the envelope must call
@@ -155,7 +165,6 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   protected readable: AtscriptDbReadable<T>;
   private readonly _gates;
   private readonly _preferredIdSet;
-  private readonly _compositeIdShapes;
   private readonly _overlayIsNoOp;
   constructor(readable: AtscriptDbReadable<T>, app: Moost);
   private _buildGates;
@@ -200,11 +209,8 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * family (count vs no-count).
    */
   private _runReadWithActions;
-  /**
-   * Extracts a composite identifier object from query params.
-   * Tries composite primary key first, then compound unique indexes.
-   */
-  protected extractCompositeId(query: Record<string, string>): Record<string, unknown> | HttpError;
+  /** Pick the first identification (PK or unique index) whose fields are all present in the query. */
+  protected extractIdShape(query: Record<string, string>): Record<string, unknown> | HttpError;
   /**
    * **GET /query** — returns an array of records or a count.
    */
@@ -720,6 +726,38 @@ declare function DbRowActions<TRow = unknown, const D extends Record<string, unk
 /** Sugar for `@DbActions` with `level: 'rows'` injected into each entry. */
 declare function DbRowsActions<TRow = unknown, const D extends Record<string, unknown> = {}>(dict: D & ValidatedUnpinnedDict<TRow, D>): ClassDecorator;
 //#endregion
+//#region src/actions/db-action-input-form.decorator.d.ts
+/**
+ * Parameter decorator that injects the `input` field of the action request
+ * envelope (`{ ids?, input? }`) into the handler.
+ *
+ * Pairs the resolved value with two pieces of param-level metadata:
+ *
+ * 1. {@link MOOST_DB_ACTION_INPUT_FORM} — the compiled `.as` class plus its
+ *    name, consumed by {@link discoverActions} to:
+ *    - emit `inputForm: FormType.name` on the action's `/meta` entry, and
+ *    - register the type in the controller's form registry so
+ *      `GET /meta/form/:name` can serve the serialized schema.
+ * 2. {@link MOOST_ATSCRIPT_TYPE} — just the type ref, providing a generic
+ *    hook any atscript-aware Moost pipe can read without knowing about the
+ *    moost-db-specific key.
+ *
+ * Validation is intentionally *not* performed here. To validate `input`
+ * against `FormType`, install an atscript validator pipe globally
+ * (`app.applyGlobalPipes(...)`) or scope it via `@Pipe(...)`. The pipe reads
+ * `MOOST_ATSCRIPT_TYPE` off the param and runs `FormType.validator()`.
+ *
+ * Only one `@InputForm()` per action is supported. To collect multiple
+ * structured inputs, compose them into a single `.as` interface and pass an
+ * array form on the field whose user-facing intent is "list of items".
+ *
+ * @param formType A compiled `.as` interface class (carries `.validator()`,
+ *                 `.metadata`, etc.).
+ */
+declare function InputForm<T extends TAtscriptAnnotatedType & {
+  readonly name: string;
+}>(formType: T): ParameterDecorator;
+//#endregion
 //#region src/actions/discover.d.ts
 /**
  * Pairs the wire-shaped `info` with the original decorator opts / dict entry,
@@ -730,13 +768,16 @@ interface TDbActionEnvelope {
   info: TDbActionInfo$1;
   raw: DbActionOpts | TDbActionsEntry;
 }
+/** Lookup helper for `AsReadableController.metaForm()`. */
+declare function getControllerFormType(ctor: Function, name: string): TAtscriptAnnotatedType | undefined;
 /** Discover actions on a controller, memoized per ctor. `info`-only callers map `e => e.info`. */
 declare function discoverActions(controllerCtor: Function, app: Moost, logger: TConsoleBase): TDbActionEnvelope[];
 //#endregion
 //#region src/actions/id-validation.d.ts
+/** Duck-typed shape; matches `AtscriptDbReadable`'s public surface. */
 interface IdValidationSource {
-  getIdentifications(): readonly TIdentification[];
-  fieldDescriptors: readonly TDbFieldMeta[];
+  readonly identifications: readonly TIdentification[];
+  readonly fieldDescriptors: readonly TDbFieldMeta[];
 }
 //#endregion
 //#region src/actions/id-cache.d.ts
@@ -755,6 +796,94 @@ declare const useDbActionRows: _wooksjs_event_core0.WookComposable<{
   load: () => Promise<(Record<string, unknown> | undefined)[]>;
 }>;
 //#endregion
+//#region src/actions/input-form-cache.d.ts
+/**
+ * Wire-shape of an action request body. Both fields are optional:
+ *
+ * - `ids` — what previously sat at the body root: a single identifier object
+ *   (`'row'`-level), an array of identifier objects (`'rows'`-level), or
+ *   absent (`'table'`-level).
+ * - `input` — present only when the action declares an `@InputForm()`
+ *   parameter; carries the form payload the user filled out.
+ */
+interface DbActionEnvelope {
+  ids?: unknown;
+  input?: unknown;
+}
+/**
+ * Cached parse of the action request body. Centralises the shape check so
+ * every per-param resolver (`@DbActionID*`, `@DbActionRow*`, `@InputForm`)
+ * reads through the same gate. An array or scalar root is rejected with the
+ * same `ValidatorError` envelope as today's strict-shape ID failures.
+ */
+declare const dbActionBodySlot: moost.Cached<Promise<DbActionEnvelope>>;
+/** Cached `body.input` slot — consumed by `@InputForm()` and `useDbActionInput()`. */
+declare const dbActionInputSlot: moost.Cached<Promise<unknown>>;
+/** Composable for in-handler reads of the form input. */
+declare const useDbActionInput: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<unknown>;
+}>;
+//#endregion
+//#region src/actions/keys.d.ts
+/** Method-level metadata key — written by `@DbAction(name, opts)`. */
+declare 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. */
+declare const MOOST_DB_ACTIONS = "atscript_db_actions";
+/** Param-level metadata key — written by `@DbActionID()` / `@DbActionIDs()`. Drives level inference. */
+declare const MOOST_DB_ACTION_PARAM = "atscript_db_action_param";
+/** Param-level marker keys — written by `@DbActionRow()` / `@DbActionRows()`. */
+declare const MOOST_DB_ACTION_ROW = "atscript_db_action_row";
+declare const MOOST_DB_ACTION_ROWS = "atscript_db_action_rows";
+/**
+ * Param-level metadata key — written by `@InputForm(FormType)`. Carries the
+ * compiled `.as` class plus its `.name` so {@link discoverActions} can both
+ * emit `inputForm` on `/meta` and register the type in the controller's form
+ * registry for `GET /meta/form/:name`.
+ */
+declare const MOOST_DB_ACTION_INPUT_FORM = "atscript_db_action_input_form";
+/**
+ * Generic param-level metadata key — written by `@InputForm(FormType)`
+ * alongside {@link MOOST_DB_ACTION_INPUT_FORM}. Holds just the type ref so a
+ * generic atscript-aware Moost pipe (installed globally via
+ * `app.applyGlobalPipes(...)` or scoped via `@Pipe(...)`) can validate the
+ * resolved value without knowing about the moost-db-specific key.
+ */
+declare const MOOST_ATSCRIPT_TYPE = "atscript_type";
+type TDbActionRowMarker = true;
+/** Stamped by `@InputForm(FormType)` — the compiled `.as` class + the wire name (`FormType.name`). */
+interface TDbActionInputFormMeta {
+  type: TAtscriptAnnotatedType;
+  name: string;
+}
+/** Method-level action metadata written by `@DbAction(name, opts)`. */
+interface TDbActionMeta {
+  name: string;
+  opts: DbActionOpts;
+}
+/** Class-level entry — a `TDbActionsEntry` plus its dictionary key. */
+interface TDbClassActionMeta {
+  name: string;
+  entry: TDbActionsEntry;
+}
+/** Param marker kind — informs level inference and ID-resolution shape. */
+type TDbActionParamKind = "id" | "ids";
+declare module "moost" {
+  interface TMoostMetadata {
+    [MOOST_DB_ACTION]?: TDbActionMeta;
+    [MOOST_DB_ACTIONS]?: TDbClassActionMeta[];
+    [MOOST_DB_ACTION_PARAM]?: TDbActionParamKind;
+    [MOOST_DB_ACTION_ROW]?: TDbActionRowMarker;
+    [MOOST_DB_ACTION_ROWS]?: TDbActionRowMarker;
+  }
+  interface TMoostParamsMetadata {
+    [MOOST_DB_ACTION_PARAM]?: TDbActionParamKind;
+    [MOOST_DB_ACTION_ROW]?: TDbActionRowMarker;
+    [MOOST_DB_ACTION_ROWS]?: TDbActionRowMarker;
+    [MOOST_DB_ACTION_INPUT_FORM]?: TDbActionInputFormMeta;
+    [MOOST_ATSCRIPT_TYPE]?: TAtscriptAnnotatedType;
+  }
+}
+//#endregion
 //#region src/actions/action-disabled-error.d.ts
 /**
  * Wire-body shape for server-side gate rejections. The `name` discriminator
@@ -815,4 +944,4 @@ declare const QUERY_CONTROLS: readonly string[];
 declare const PAGES_CONTROLS: readonly string[];
 declare const ONE_CONTROLS: readonly string[];
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, type IdValidationSource, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, discoverActions, perRow, useDbActionId, useDbActionIds, useDbActionRow, useDbActionRows, validationErrorTransform };
+export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, type IdValidationSource, InputForm, MOOST_ATSCRIPT_TYPE, MOOST_DB_ACTION_INPUT_FORM, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, dbActionBodySlot, dbActionInputSlot, discoverActions, getControllerFormType, perRow, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };

package/dist/index.mjs

@@ -198,9 +198,6 @@ function isAsValueHelpControllerSubclass(ctor) {
 	if (!asValueHelpCtor) return false;
 	return asValueHelpCtor.prototype.isPrototypeOf(ctor.prototype);
 }
-function isAsDbReadableControllerInstance(value) {
-	return !!asDbReadableCtor && value instanceof asDbReadableCtor;
-}
 //#endregion
 //#region src/actions/keys.ts
 /** Log-message prefix for warnings emitted from the actions subsystem. */
@@ -215,6 +212,21 @@ const MOOST_DB_ACTION_PARAM = "atscript_db_action_param";
 const MOOST_DB_ACTION_ROW = "atscript_db_action_row";
 const MOOST_DB_ACTION_ROWS = "atscript_db_action_rows";
 /**
+* Param-level metadata key — written by `@InputForm(FormType)`. Carries the
+* compiled `.as` class plus its `.name` so {@link discoverActions} can both
+* emit `inputForm` on `/meta` and register the type in the controller's form
+* registry for `GET /meta/form/:name`.
+*/
+const MOOST_DB_ACTION_INPUT_FORM = "atscript_db_action_input_form";
+/**
+* Generic param-level metadata key — written by `@InputForm(FormType)`
+* alongside {@link MOOST_DB_ACTION_INPUT_FORM}. Holds just the type ref so a
+* generic atscript-aware Moost pipe (installed globally via
+* `app.applyGlobalPipes(...)` or scoped via `@Pipe(...)`) can validate the
+* resolved value without knowing about the moost-db-specific key.
+*/
+const MOOST_ATSCRIPT_TYPE = "atscript_type";
+/**
 * 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
@@ -237,6 +249,8 @@ function scanParamLevel(params) {
 	let multi = false;
 	let hasRowParam = false;
 	let hasBody = false;
+	let inputForm;
+	let hasDuplicateInputForm = false;
 	for (const p of params) {
 		const kind = p[MOOST_DB_ACTION_PARAM];
 		if (kind === "id") single = true;
@@ -250,13 +264,18 @@ function scanParamLevel(params) {
 			hasRowParam = true;
 		}
 		if (p.paramSource === "BODY") hasBody = true;
+		const form = p[MOOST_DB_ACTION_INPUT_FORM];
+		if (form) if (inputForm) hasDuplicateInputForm = true;
+		else inputForm = form;
 	}
 	return {
 		level: single && multi ? "table" : single ? "row" : multi ? "rows" : "table",
 		single,
 		multi,
 		hasRowParam,
-		hasBody
+		hasBody,
+		inputForm,
+		hasDuplicateInputForm
 	};
 }
 //#endregion
@@ -273,6 +292,34 @@ const OPTIONAL_FIELDS = [
 ];
 const actionsCache = /* @__PURE__ */ new WeakMap();
 const rowLevelActionsCache = /* @__PURE__ */ new WeakMap();
+/**
+* Per-controller registry of form names → compiled `.as` classes, populated
+* during {@link discoverActions} when a method param carries
+* {@link MOOST_DB_ACTION_INPUT_FORM}. Backs `GET /meta/form/:name`.
+*
+* Same name + same type ref across multiple actions is fine (forms can be
+* reused). Same name + *different* type refs is an ambiguity — discovery
+* warns and drops the second action.
+*/
+const formRegistry = /* @__PURE__ */ new WeakMap();
+/** Lookup helper for `AsReadableController.metaForm()`. */
+function getControllerFormType(ctor, name) {
+	return formRegistry.get(ctor)?.get(name);
+}
+function registerFormType(ctor, meta, actionName, logger) {
+	let map = formRegistry.get(ctor);
+	if (!map) {
+		map = /* @__PURE__ */ new Map();
+		formRegistry.set(ctor, map);
+	}
+	const existing = map.get(meta.name);
+	if (existing && existing !== meta.type) {
+		logger.warn(`${WARN_PREFIX} action "${actionName}" — form name "${meta.name}" already registered on this controller with a different type. Reusing the same FormType across actions is fine; clashing names are not — dropping`);
+		return false;
+	}
+	if (!existing) map.set(meta.name, meta.type);
+	return true;
+}
 /** 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);
@@ -358,6 +405,10 @@ function collectMethodActions(ctor, overview, logger, out, seen) {
 			processor: "backend",
 			value: path
 		};
+		if (levelInfer.inputForm) {
+			if (!registerFormType(ctor, levelInfer.inputForm, action.name, logger)) continue;
+			info.inputForm = levelInfer.inputForm.name;
+		}
 		emitInfo(info, action.opts);
 		seen.add(action.name);
 		out.push({
@@ -372,10 +423,12 @@ function inferMethodLevel(params, actionName, logger) {
 		logger.warn(`${WARN_PREFIX} action "${actionName}" mixes single-cardinality and multi-cardinality decorators (@DbActionID / @DbActionRow vs @DbActionIDs / @DbActionRows) — dropping`);
 		return null;
 	}
+	if (scan.hasDuplicateInputForm) logger.warn(`${WARN_PREFIX} action "${actionName}" has more than one @InputForm() param — only the first is honored. Compose multiple inputs into a single form interface.`);
 	return {
 		level: scan.level,
 		bodyConflict: scan.hasBody && scan.level !== "table",
-		hasRowParam: scan.hasRowParam
+		hasRowParam: scan.hasRowParam,
+		inputForm: scan.inputForm
 	};
 }
 function collectClassActions(ctor, logger, out, seen) {
@@ -486,6 +539,13 @@ function __decorate(decorators, target, key, desc) {
 	return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 //#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-readable.controller.ts
 var _ref$4;
 let AsReadableController = class AsReadableController {
@@ -501,6 +561,8 @@ let AsReadableController = class AsReadableController {
 	_serializedType;
 	/** Cached full meta response (computed lazily on first meta() call). */
 	_metaResponse;
+	/** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
+	_formSchemas = /* @__PURE__ */ new Map();
 	constructor(boundType, controllerName, app, kindTag = "readable") {
 		this.boundType = boundType;
 		this.controllerName = controllerName;
@@ -643,6 +705,25 @@ let AsReadableController = class AsReadableController {
 		return this.applyMetaOverlay(this._metaResponse);
 	}
 	/**
+	* **GET /meta/form/:name** — returns the serialized schema of a form
+	* referenced by an action's `inputForm` field. The form name is the
+	* compiled `.as` class's `.name`, registered when an action's parameter is
+	* decorated with `@InputForm(FormType)`. Schemas are serialized once and
+	* cached per controller; the response uses the same annotation-allowlist
+	* policy as {@link getSerializeOptions}.
+	*/
+	async metaForm(name) {
+		discoverActions(this.constructor, this.app, this.logger);
+		const formType = getControllerFormType(this.constructor, name);
+		if (!formType) throw new HttpError(404, `Unknown form "${name}"`);
+		let cached = this._formSchemas.get(name);
+		if (!cached) {
+			cached = serializeAnnotatedType(formType, this.getSerializeOptions());
+			this._formSchemas.set(name, cached);
+		}
+		return cached;
+	}
+	/**
 	* Builds the `/meta` payload. Override in subclasses to populate source-specific
 	* fields. Subclasses that fully replace the envelope must call
 	* {@link buildActions} and {@link buildCrud} directly so `@DbAction*`
@@ -696,6 +777,13 @@ __decorate([
 	__decorateMetadata("design:paramtypes", []),
 	__decorateMetadata("design:returntype", Promise)
 ], AsReadableController.prototype, "meta", null);
+__decorate([
+	Get("meta/form/:name"),
+	__decorateParam(0, Param("name")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", Promise)
+], AsReadableController.prototype, "metaForm", null);
 AsReadableController = __decorate([UseValidationErrorTransform(), __decorateMetadata("design:paramtypes", [
 	Object,
 	String,
@@ -858,13 +946,6 @@ const QUERY_CONTROLS = [
 const PAGES_CONTROLS = ["filter", ...dtoControls(PagesControlsDto)];
 const ONE_CONTROLS = dtoControls(GetOneControlsDto);
 //#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 {
@@ -872,14 +953,12 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	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;
 	}
@@ -1103,12 +1182,9 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		});
 		return result;
 	}
-	/**
-	* Extracts a composite identifier object from query params.
-	* Tries composite primary key first, then compound unique indexes.
-	*/
-	extractCompositeId(query) {
-		for (const id of this._compositeIdShapes) {
+	/** Pick the first identification (PK or unique index) whose fields are all present in the query. */
+	extractIdShape(query) {
+		for (const id of this.readable.identifications) {
 			const idObj = {};
 			let allPresent = true;
 			for (const field of id.fields) {
@@ -1120,7 +1196,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			}
 			if (allPresent) return idObj;
 		}
-		return new HttpError(400, "Query params do not match any composite primary key or compound unique index");
+		return new HttpError(400, "Query params do not match any primary key or unique index");
 	}
 	/**
 	* **GET /query** — returns an array of records or a count.
@@ -1236,7 +1312,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	* (composite primary key or compound unique index).
 	*/
 	async getOneComposite(query, url) {
-		const idObj = this.extractCompositeId(query);
+		const idObj = this.extractIdShape(query);
 		if (idObj instanceof HttpError) return idObj;
 		const parsed = this.parseQueryString(url);
 		this._coerceActionsControl(parsed.controls);
@@ -1436,7 +1512,7 @@ let AsDbController = class AsDbController extends AsDbReadableController {
 	* (composite primary key or compound unique index).
 	*/
 	async removeComposite(query) {
-		const idObj = this.extractCompositeId(query);
+		const idObj = this.extractIdShape(query);
 		if (idObj instanceof HttpError) return idObj;
 		const resolvedId = await this.onRemove(idObj);
 		if (resolvedId === void 0) return new HttpError(500, "Not deleted");
@@ -1854,12 +1930,35 @@ function readCurrentActionMeta(ctx) {
 	return getMoostMate().read(ctrl.constructor, methodName)?.[MOOST_DB_ACTION];
 }
 //#endregion
+//#region src/actions/input-form-cache.ts
+/**
+* Cached parse of the action request body. Centralises the shape check so
+* every per-param resolver (`@DbActionID*`, `@DbActionRow*`, `@InputForm`)
+* reads through the same gate. An array or scalar root is rejected with the
+* same `ValidatorError` envelope as today's strict-shape ID failures.
+*/
+const dbActionBodySlot = cached(async (ctx) => {
+	const raw = await useBody(ctx).parseBody();
+	if (raw == null) return {};
+	if (typeof raw !== "object" || Array.isArray(raw)) throw new ValidatorError([{
+		path: "",
+		message: "Action body must be an object of shape { ids?, input? }"
+	}]);
+	return raw;
+});
+/** Cached `body.input` slot — consumed by `@InputForm()` and `useDbActionInput()`. */
+const dbActionInputSlot = cached(async (ctx) => {
+	return (await ctx.get(dbActionBodySlot)).input;
+});
+/** Composable for in-handler reads of the form input. */
+const useDbActionInput = defineWook((ctx) => ({ load: () => ctx.get(dbActionInputSlot) }));
+//#endregion
 //#region src/actions/id-validation.ts
 const SOURCE_CACHE = /* @__PURE__ */ new WeakMap();
 function getSourceCache(source) {
 	let cache = SOURCE_CACHE.get(source);
 	if (cache) return cache;
-	const identifications = source.getIdentifications();
+	const identifications = source.identifications;
 	const byKeySig = /* @__PURE__ */ new Map();
 	for (const ident of identifications) byKeySig.set(fieldsSig(ident.fields), ident);
 	const fieldByName = /* @__PURE__ */ new Map();
@@ -1878,7 +1977,7 @@ function fieldsSig(fields) {
 function isIdValidationSource(value) {
 	if (!value || typeof value !== "object") return false;
 	const v = value;
-	return typeof v.getIdentifications === "function" && Array.isArray(v.fieldDescriptors);
+	return Array.isArray(v.identifications) && Array.isArray(v.fieldDescriptors);
 }
 function validateSingleId(body, source, path = "") {
 	const errors = collectIdErrors(body, source, path);
@@ -1946,22 +2045,34 @@ function isPlainObject(value) {
 //#endregion
 //#region src/actions/id-cache.ts
 const boundTableKey = key("atscript_db_action_bound_table");
-function getActionTable(ctx) {
-	const fromSlot = ctx.has(boundTableKey) ? ctx.get(boundTableKey) : void 0;
-	if (fromSlot) return fromSlot;
+function controllerTable(ctx) {
 	const ctrl = useControllerContext(ctx).getController();
 	return ctrl?.readable ?? ctrl?.table ?? null;
 }
+function getActionTable(ctx) {
+	return (ctx.has(boundTableKey) ? ctx.get(boundTableKey) : void 0) ?? controllerTable(ctx);
+}
+const warnedTags = /* @__PURE__ */ new Set();
 function noTableError(ctx) {
 	const actionName = readCurrentActionMeta(ctx)?.name;
-	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.`);
+	const tag = actionName ? `"${actionName}"` : "<unknown>";
+	if (!warnedTags.has(tag)) {
+		warnedTags.add(tag);
+		console.warn(`${WARN_PREFIX} ${tag}: controller has no readable/table property and the action declares no opts.table. Either expose readable/table on the controller, extend AsDbReadableController, or pass opts.table on @DbAction.`);
+	}
+	return new HttpError(500, {
+		statusCode: 500,
+		error: "Internal Server Error",
+		message: "Internal server error",
+		code: "ACTION_TABLE_NOT_BOUND"
+	});
 }
 async function resolveValidatedId(ctx, validate) {
 	const table = getActionTable(ctx);
 	if (!isIdValidationSource(table)) throw noTableError(ctx);
-	const body = await useBody(ctx).parseBody();
-	validate(body, table);
-	return body;
+	const env = await ctx.get(dbActionBodySlot);
+	validate(env.ids, table);
+	return env.ids;
 }
 const dbActionIdSlot = cached((ctx) => resolveValidatedId(ctx, validateSingleId));
 const dbActionIdsSlot = cached(async (ctx) => {
@@ -2061,15 +2172,11 @@ const useDbActionRows = defineWook((ctx) => ({ load: () => ctx.get(dbActionRowsS
 //#endregion
 //#region src/actions/gate-interceptor.ts
 const GATE_PRIORITY = TInterceptorPriority.AFTER_GUARD;
-function injectBoundTable(table) {
+function injectBoundTable(fallback) {
 	const ctx = current();
 	if (ctx.has(boundTableKey)) return;
-	const controller = useControllerContext(ctx).getController();
-	if (isAsDbReadableControllerInstance(controller)) {
-		ctx.set(boundTableKey, controller.readable);
-		return;
-	}
-	if (table != null) ctx.set(boundTableKey, table);
+	const t = controllerTable(ctx) ?? fallback;
+	if (t != null) ctx.set(boundTableKey, t);
 }
 function buildGateInterceptor(opts) {
 	const { action, level, disabled, onDisabledRows, table } = opts;
@@ -2324,6 +2431,43 @@ function classLevelActions(dict, forcedLevel) {
 	});
 }
 //#endregion
+//#region src/actions/db-action-input-form.decorator.ts
+/**
+* Parameter decorator that injects the `input` field of the action request
+* envelope (`{ ids?, input? }`) into the handler.
+*
+* Pairs the resolved value with two pieces of param-level metadata:
+*
+* 1. {@link MOOST_DB_ACTION_INPUT_FORM} — the compiled `.as` class plus its
+*    name, consumed by {@link discoverActions} to:
+*    - emit `inputForm: FormType.name` on the action's `/meta` entry, and
+*    - register the type in the controller's form registry so
+*      `GET /meta/form/:name` can serve the serialized schema.
+* 2. {@link MOOST_ATSCRIPT_TYPE} — just the type ref, providing a generic
+*    hook any atscript-aware Moost pipe can read without knowing about the
+*    moost-db-specific key.
+*
+* Validation is intentionally *not* performed here. To validate `input`
+* against `FormType`, install an atscript validator pipe globally
+* (`app.applyGlobalPipes(...)`) or scope it via `@Pipe(...)`. The pipe reads
+* `MOOST_ATSCRIPT_TYPE` off the param and runs `FormType.validator()`.
+*
+* Only one `@InputForm()` per action is supported. To collect multiple
+* structured inputs, compose them into a single `.as` interface and pass an
+* array form on the field whose user-facing intent is "list of items".
+*
+* @param formType A compiled `.as` interface class (carries `.validator()`,
+*                 `.metadata`, etc.).
+*/
+function InputForm(formType) {
+	const mate = getMoostMate();
+	const meta = {
+		type: formType,
+		name: formType.name
+	};
+	return ApplyDecorators(mate.decorate(MOOST_DB_ACTION_INPUT_FORM, meta), mate.decorate(MOOST_ATSCRIPT_TYPE, formType), Resolve(async () => current().get(dbActionInputSlot), "dbActionInputForm"));
+}
+//#endregion
 //#region src/actions/per-row.ts
 /**
 * Lift a per-row predicate into the batch shape required by
@@ -2339,4 +2483,4 @@ function classLevelActions(dict, forcedLevel) {
 */
 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 };
+export { ActionDisabledError, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionID, DbActionIDs, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, InputForm, MOOST_ATSCRIPT_TYPE, MOOST_DB_ACTION_INPUT_FORM, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, dbActionBodySlot, dbActionInputSlot, discoverActions, getControllerFormType, perRow, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/moost-db",
-  "version": "0.1.60",
+  "version": "0.1.62",
   "description": "Generic database controller for Moost with Atscript.",
   "keywords": [
     "annotations",
@@ -58,7 +58,7 @@
     "@wooksjs/event-core": "^0.7.10",
     "@wooksjs/http-body": "^0.7.10",
     "moost": "^0.6.8",
-    "@atscript/db": "^0.1.60"
+    "@atscript/db": "^0.1.62"
   },
   "scripts": {
     "postinstall": "asc -f dts",