@atscript/moost-db 0.1.61 → 0.1.63

package/dist/index.cjs

@@ -213,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
@@ -235,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;
@@ -248,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
@@ -271,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);
@@ -356,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({
@@ -370,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) {
@@ -484,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 {
@@ -499,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;
@@ -626,6 +691,42 @@ let AsReadableController = class AsReadableController {
 		const idx = url.indexOf("?");
 		return (0, _uniqu_url.parseUrl)(idx >= 0 ? url.slice(idx + 1) : "");
 	}
+	/**
+	* Parse a URL keeping only `$*` control keywords; report whether any
+	* non-control parts were present. Used by `/one` routes where the
+	* uniquery lexer cannot tokenise PK values containing `-` and other
+	* reserved chars, so non-control parts must be stripped before lexing.
+	* `/one/:id` rejects stray filter params with 400 via `hasNonControl`;
+	* `/one` (composite) ignores it because the composite-key params have
+	* already been extracted via `@Query()`.
+	*/
+	parseControlsOnlyFromUrl(url) {
+		const idx = url.indexOf("?");
+		const qs = idx >= 0 ? url.slice(idx + 1) : "";
+		if (!qs) return {
+			parsed: (0, _uniqu_url.parseUrl)(""),
+			hasNonControl: false
+		};
+		const kept = [];
+		let hasNonControl = false;
+		for (const part of qs.split("&")) {
+			if (!part) continue;
+			const eq = part.indexOf("=");
+			const rawKey = eq === -1 ? part : part.slice(0, eq);
+			let key;
+			try {
+				key = decodeURIComponent(rawKey);
+			} catch {
+				key = rawKey;
+			}
+			if (key.startsWith("$")) kept.push(part);
+			else hasNonControl = true;
+		}
+		return {
+			parsed: (0, _uniqu_url.parseUrl)(kept.join("&")),
+			hasNonControl
+		};
+	}
 	async returnOne(result) {
 		const item = await result;
 		if (!item) return new _moostjs_event_http.HttpError(404);
@@ -641,6 +742,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*`
@@ -694,6 +814,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,
@@ -856,13 +983,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 {
@@ -1214,9 +1334,9 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	* **GET /one/:id** — retrieves a single record by ID or unique property.
 	*/
 	async getOne(id, url) {
-		const parsed = this.parseQueryString(url);
+		const { parsed, hasNonControl } = this.parseControlsOnlyFromUrl(url);
+		if (hasNonControl) return new _moostjs_event_http.HttpError(400, "Filtering is not allowed for \"one\" endpoint");
 		this._coerceActionsControl(parsed.controls);
-		if (Object.keys(parsed.filter).length > 0) return new _moostjs_event_http.HttpError(400, "Filtering is not allowed for \"one\" endpoint");
 		const error = this.validateParsed(parsed, "getOne");
 		if (error) return error;
 		const rawSelect = await this.transformProjection(parsed.controls.$select);
@@ -1231,7 +1351,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	async getOneComposite(query, url) {
 		const idObj = this.extractIdShape(query);
 		if (idObj instanceof _moostjs_event_http.HttpError) return idObj;
-		const parsed = this.parseQueryString(url);
+		const { parsed } = this.parseControlsOnlyFromUrl(url);
 		this._coerceActionsControl(parsed.controls);
 		const rawSelect = await this.transformProjection(parsed.controls.$select);
 		const select = this.widenPreferredIdProjection(rawSelect);
@@ -1847,6 +1967,29 @@ 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) {
@@ -1964,9 +2107,9 @@ function noTableError(ctx) {
 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) => {
@@ -2325,6 +2468,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 +2561,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 +2573,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,6 @@
-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 { parseUrl } 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 +61,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.
    */
@@ -105,6 +107,19 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    */
   protected checkGates(filter: FilterExpr | undefined, controls: Record<string, unknown>, gates: ReadableGates): HttpError | undefined;
   protected parseQueryString(url: string): _uniqu_url0.UrlQuery;
+  /**
+   * Parse a URL keeping only `$*` control keywords; report whether any
+   * non-control parts were present. Used by `/one` routes where the
+   * uniquery lexer cannot tokenise PK values containing `-` and other
+   * reserved chars, so non-control parts must be stripped before lexing.
+   * `/one/:id` rejects stray filter params with 400 via `hasNonControl`;
+   * `/one` (composite) ignores it because the composite-key params have
+   * already been extracted via `@Query()`.
+   */
+  protected parseControlsOnlyFromUrl(url: string): {
+    parsed: ReturnType<typeof parseUrl>;
+    hasNonControl: boolean;
+  };
   protected returnOne(result: Promise<DataType | null>): Promise<DataType | HttpError>;
   /**
    * **GET /meta** — returns the bound interface's metadata envelope. The
@@ -112,6 +127,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
@@ -716,6 +740,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,
@@ -726,6 +782,8 @@ 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
@@ -752,6 +810,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
@@ -812,4 +958,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,9 +1,9 @@
-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";
 import * as _uniqu_url0 from "@uniqu/url";
+import { parseUrl } from "@uniqu/url";
 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 * as _wooksjs_event_core0 from "@wooksjs/event-core";
 
@@ -61,13 +61,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.
    */
@@ -105,6 +107,19 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    */
   protected checkGates(filter: FilterExpr | undefined, controls: Record<string, unknown>, gates: ReadableGates): HttpError | undefined;
   protected parseQueryString(url: string): _uniqu_url0.UrlQuery;
+  /**
+   * Parse a URL keeping only `$*` control keywords; report whether any
+   * non-control parts were present. Used by `/one` routes where the
+   * uniquery lexer cannot tokenise PK values containing `-` and other
+   * reserved chars, so non-control parts must be stripped before lexing.
+   * `/one/:id` rejects stray filter params with 400 via `hasNonControl`;
+   * `/one` (composite) ignores it because the composite-key params have
+   * already been extracted via `@Query()`.
+   */
+  protected parseControlsOnlyFromUrl(url: string): {
+    parsed: ReturnType<typeof parseUrl>;
+    hasNonControl: boolean;
+  };
   protected returnOne(result: Promise<DataType | null>): Promise<DataType | HttpError>;
   /**
    * **GET /meta** — returns the bound interface's metadata envelope. The
@@ -112,6 +127,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
@@ -716,6 +740,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,
@@ -726,6 +782,8 @@ 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
@@ -752,6 +810,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
@@ -812,4 +958,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

@@ -212,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
@@ -234,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;
@@ -247,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
@@ -270,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);
@@ -355,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({
@@ -369,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) {
@@ -483,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 {
@@ -498,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;
@@ -625,6 +690,42 @@ let AsReadableController = class AsReadableController {
 		const idx = url.indexOf("?");
 		return parseUrl(idx >= 0 ? url.slice(idx + 1) : "");
 	}
+	/**
+	* Parse a URL keeping only `$*` control keywords; report whether any
+	* non-control parts were present. Used by `/one` routes where the
+	* uniquery lexer cannot tokenise PK values containing `-` and other
+	* reserved chars, so non-control parts must be stripped before lexing.
+	* `/one/:id` rejects stray filter params with 400 via `hasNonControl`;
+	* `/one` (composite) ignores it because the composite-key params have
+	* already been extracted via `@Query()`.
+	*/
+	parseControlsOnlyFromUrl(url) {
+		const idx = url.indexOf("?");
+		const qs = idx >= 0 ? url.slice(idx + 1) : "";
+		if (!qs) return {
+			parsed: parseUrl(""),
+			hasNonControl: false
+		};
+		const kept = [];
+		let hasNonControl = false;
+		for (const part of qs.split("&")) {
+			if (!part) continue;
+			const eq = part.indexOf("=");
+			const rawKey = eq === -1 ? part : part.slice(0, eq);
+			let key;
+			try {
+				key = decodeURIComponent(rawKey);
+			} catch {
+				key = rawKey;
+			}
+			if (key.startsWith("$")) kept.push(part);
+			else hasNonControl = true;
+		}
+		return {
+			parsed: parseUrl(kept.join("&")),
+			hasNonControl
+		};
+	}
 	async returnOne(result) {
 		const item = await result;
 		if (!item) return new HttpError(404);
@@ -640,6 +741,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*`
@@ -693,6 +813,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,
@@ -855,13 +982,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 {
@@ -1213,9 +1333,9 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	* **GET /one/:id** — retrieves a single record by ID or unique property.
 	*/
 	async getOne(id, url) {
-		const parsed = this.parseQueryString(url);
+		const { parsed, hasNonControl } = this.parseControlsOnlyFromUrl(url);
+		if (hasNonControl) return new HttpError(400, "Filtering is not allowed for \"one\" endpoint");
 		this._coerceActionsControl(parsed.controls);
-		if (Object.keys(parsed.filter).length > 0) return new HttpError(400, "Filtering is not allowed for \"one\" endpoint");
 		const error = this.validateParsed(parsed, "getOne");
 		if (error) return error;
 		const rawSelect = await this.transformProjection(parsed.controls.$select);
@@ -1230,7 +1350,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	async getOneComposite(query, url) {
 		const idObj = this.extractIdShape(query);
 		if (idObj instanceof HttpError) return idObj;
-		const parsed = this.parseQueryString(url);
+		const { parsed } = this.parseControlsOnlyFromUrl(url);
 		this._coerceActionsControl(parsed.controls);
 		const rawSelect = await this.transformProjection(parsed.controls.$select);
 		const select = this.widenPreferredIdProjection(rawSelect);
@@ -1846,6 +1966,29 @@ 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) {
@@ -1963,9 +2106,9 @@ function noTableError(ctx) {
 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) => {
@@ -2324,6 +2467,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 +2519,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.61",
+  "version": "0.1.63",
   "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.61"
+    "@atscript/db": "^0.1.63"
   },
   "scripts": {
     "postinstall": "asc -f dts",