@atscript/moost-db 0.1.57 → 0.1.58

package/dist/index.d.cts

@@ -5,6 +5,7 @@ import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, TCrudOp, TCrudPermissi
 import { HttpError } from "@moostjs/event-http";
 import * as moost from "moost";
 import { Moost, TConsoleBase } from "moost";
+import * as _wooksjs_event_core0 from "@wooksjs/event-core";
 
 //#region src/as-readable.controller.d.ts
 /**
@@ -460,15 +461,72 @@ declare const validationErrorTransform: () => moost.TInterceptorDef;
 declare const UseValidationErrorTransform: () => ClassDecorator & MethodDecorator;
 //#endregion
 //#region src/actions/types.d.ts
+/** `'rows'`-level batch policy — controls whether failing rows reject or are filtered out. */
+type TOnDisabledRows = "reject" | "skip";
 /**
  * Options accepted by `@DbAction(name, opts?)`. Structurally derived from
- * {@link TDbActionInfo} so every addition to the wire shape automatically
- * propagates here. Fields owned by the framework (`name`, `level`, `processor`,
- * `value`) are excluded — `name` comes from the decorator argument, `level` is
- * inferred from `@DbActionPK*` usage, `processor` is fixed to `'backend'` for
- * method-decorator actions, and `value` is filled from the `@Post` path.
+ * {@link TDbActionInfo} so every wire-shape addition propagates here, EXCEPT
+ * `disabled` and `requiredFields` which differ in shape between decorator
+ * opts (function / dev-supplied) and the wire (string / forwarded verbatim).
+ *
+ * Fields owned by the framework (`name`, `level`, `processor`, `value`) are
+ * excluded — `name` comes from the decorator argument, `level` is inferred
+ * from `@DbActionPK*` / `@DbActionRow*` usage, `processor` is fixed to
+ * `'backend'` for method-decorator actions, and `value` is filled from the
+ * `@Post` path.
+ *
+ * Generic over `TRow` so the `disabled` predicate can be type-checked against
+ * the bound table's row shape. Note: TS decorators cannot infer `TRow` from
+ * the enclosing controller's class generic, so the dev MUST annotate the row
+ * arg explicitly (`(row: Order) => …`) to get type-checking.
  */
-type DbActionOpts = Partial<Omit<TDbActionInfo$1, "name" | "level" | "processor" | "value">>;
+type DbActionOpts<TRow = unknown> = Partial<Omit<TDbActionInfo$1, "name" | "level" | "processor" | "value" | "disabled" | "requiredFields">> & {
+  /**
+   * Per-row gate predicate. Truthy → action is disabled for that row.
+   * Server enforces (via the gate interceptor); UI evaluates the same
+   * expression to grey-out / hide the button.
+   *
+   * The dev MUST annotate the row arg explicitly (`(row: Order) => …`) —
+   * TS decorators cannot infer `TRow` from the enclosing class generic.
+   */
+  disabled?: (row: TRow) => boolean;
+  /**
+   * Optional dot-notation field paths the UI should union into `$select`.
+   * Plain `string[]` in v1.
+   *
+   * TODO: upgrade to typed `PathOf<TRow>[]` in a follow-up — the recursive
+   * type pattern is finicky for nested objects/arrays/optionals and isn't
+   * blocking v1.
+   *
+   * When omitted, the UI parses the stringified `disabled` itself to extract
+   * row-property accesses. When present, the UI uses this list verbatim — the
+   * server does NOT auto-derive or merge.
+   */
+  requiredFields?: string[];
+  /**
+   * `'rows'`-level batch policy. Default `'reject'`.
+   *
+   * - `'reject'`: evaluate every row (FULL scan, NOT short-circuit) before
+   *   throwing; if any row fails, the error body lists ALL failing PKs;
+   *   handler not invoked.
+   * - `'skip'`: filter cached rows + cached PKs to passing-only;
+   *   zero survivors → reject. Handler runs against the survivors.
+   *
+   * Ignored for `'row'` and `'table'` level actions.
+   */
+  onDisabledRows?: TOnDisabledRows;
+  /**
+   * Bound table reference. REQUIRED on non-`AsDbReadableController` classes
+   * when `disabled` is set OR a `@DbActionRow*` parameter is declared.
+   *
+   * Silently ignored on `AsDbReadableController` subclasses (which include
+   * `AsDbController`) — the bound table from the controller wins; the
+   * gate / thin interceptor probes `instanceof AsDbReadableController` and
+   * populates the bound-table slot from `controller.readable` before
+   * checking `opts.table`.
+   */
+  table?: AtscriptDbTable<any>;
+};
 interface DbActionsEntryCommon {
   label: string;
   level: TDbActionLevel$1;
@@ -477,7 +535,28 @@ interface DbActionsEntryCommon {
   description?: string;
   order?: number;
   default?: boolean;
-  promptText?: string;
+  /** Mirrors {@link TDbActionInfo.promptText} — singular/plural via tuple. */
+  promptText?: string | [string, string];
+  /** Mirrors {@link TDbActionInfo.shortcut} — single-character UI hint. */
+  shortcut?: string;
+  /**
+   * UI-only gate predicate (class-level dict entries do NOT register a
+   * server-side gate interceptor — the dict entry's `value` may point at an
+   * endpoint in another controller). The wire emits `fn.toString()` so the
+   * UI can grey-out / hide the button. For symmetric server enforcement at
+   * the actual `@Post`-bound handler, declare `@DbAction(name, { disabled })`
+   * on that handler too.
+   *
+   * Not generic over `TRow` — devs type the row arg explicitly.
+   */
+  disabled?: (row: any) => boolean;
+  /** Same as method-decorator `requiredFields`. UI hint, not server-derived. */
+  requiredFields?: string[];
+  /**
+   * Reserved for future API symmetry with method-decorator opts. Currently a
+   * no-op for class-level dict entries (no gate interceptor registers).
+   */
+  onDisabledRows?: TOnDisabledRows;
 }
 /**
  * Class-level dict entry. `value` semantics by processor:
@@ -508,21 +587,13 @@ type TDbActionsEntryUnpinned = DistributiveOmit<TDbActionsEntry, "level">;
 //#endregion
 //#region src/actions/db-action.decorator.d.ts
 /**
- * Mark a controller method as a database action surfaced via `/meta`.
- *
- * Metadata-only — pair with `@Post(...)` for Moost to bind the route. The
- * meta builder reads this metadata plus the bound POST path lazily and
- * emits the action with `processor: 'backend'`. Order vs.
- * `@DbActionDefault()` does not matter — both merge into the same slot.
- *
- * @example
- * ```ts
- * @Post('actions/block')
- * @DbAction('block', { label: 'Block', icon: 'i-as-block', intent: 'negative' })
- * async blockUser(@DbActionPK() id: string) { ... }
- * ```
+ * Mark a controller method as a database action surfaced via `/meta`. Writes
+ * `MOOST_DB_ACTION` metadata and registers a Moost interceptor when needed
+ * (gate when `disabled` is set, thin bound-table injector when only
+ * `@DbActionRow*` is present). Stacking two `@DbAction` on the same method
+ * is undefined and emits a warning.
  */
-declare function DbAction(name: string, opts?: DbActionOpts): MethodDecorator;
+declare function DbAction<TRow = unknown>(name: string, opts?: DbActionOpts<TRow>): MethodDecorator;
 //#endregion
 //#region src/actions/db-action-default.decorator.d.ts
 /**
@@ -545,6 +616,10 @@ declare function DbActionDefault(): MethodDecorator;
  *
  * Marks the param so {@link discoverActions} can infer the action's `level`
  * as `'row'`.
+ *
+ * Implementation note: the resolver is a thin reader of the cached PK wook
+ * — validation logic lives in the wook factory, which runs once per request
+ * regardless of how many readers consume the value.
  */
 declare function DbActionPK(): ParameterDecorator;
 //#endregion
@@ -558,9 +633,37 @@ declare function DbActionPK(): ParameterDecorator;
  *
  * Validation is strict — no type coercion. Marks the param so
  * {@link discoverActions} can infer the action's `level` as `'rows'`.
+ *
+ * In `'rows'` skip mode the resolved value reflects the gate interceptor's
+ * filtered subset (the cached PK slot is overwritten in place); see
+ * {@link dbActionPksSlot} for precedence details.
  */
 declare function DbActionPKs(): ParameterDecorator;
 //#endregion
+//#region src/actions/db-action-row.decorator.d.ts
+/**
+ * Parameter decorator that injects the row whose PK was supplied in the
+ * request body. Reads from the cached row wook (fetched once per request,
+ * shared with the gate interceptor when `disabled` is set).
+ *
+ * Marks the param so {@link discoverActions} infers the action's `level` as
+ * `'row'`. Co-occurrence with `@DbActionRows()` (or any multi-cardinality
+ * decorator) drops the action with a warning.
+ *
+ * In `'skip'` mode this returns the gate's filtered row; the original
+ * request-body row is not retrievable.
+ */
+declare function DbActionRow(): ParameterDecorator;
+/**
+ * Parameter decorator that injects the rows-array fetched by primary keys
+ * from the request body. Reads from the cached row-array wook.
+ *
+ * Marks the param so {@link discoverActions} infers the action's `level` as
+ * `'rows'`. In `'rows'` + `'skip'` mode the resolved value contains only the
+ * gate's surviving rows.
+ */
+declare function DbActionRows(): ParameterDecorator;
+//#endregion
 //#region src/actions/db-actions.decorator.d.ts
 /**
  * Declare class-level actions on a controller. Entries are flat dicts with
@@ -607,9 +710,65 @@ interface PkValidationSource {
   fieldDescriptors: readonly TDbFieldMeta[];
 }
 //#endregion
+//#region src/actions/pk-cache.d.ts
+declare const useDbActionPk: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<unknown>;
+}>;
+declare const useDbActionPks: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<unknown[]>;
+}>;
+//#endregion
+//#region src/actions/row-cache.d.ts
+declare const useDbActionRow: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<unknown>;
+}>;
+declare const useDbActionRows: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<unknown[]>;
+}>;
+//#endregion
+//#region src/actions/action-disabled-error.d.ts
+/**
+ * Wire-body shape for server-side gate rejections. The `name` discriminator
+ * lets `@atscript/db-client` recognise the response and construct the typed
+ * `ActionDisabledError` subclass. The shape extends Moost's standard
+ * `ServerError` envelope (`{ message, statusCode, errors? }`) with three
+ * additional fields:
+ *
+ * - `name: 'ActionDisabledError'` — discriminator the client matches.
+ * - `action` — the `@DbAction` name that rejected the request.
+ * - `pk?` — present only for `'row'`-level rejections.
+ * - `pks?` — present only for `'rows'`-level rejections.
+ *
+ * `message` is populated with a human-readable string so generic
+ * `ClientError` consumers (which read `body.message`) still get something
+ * useful without typed-catch dispatch.
+ */
+interface ActionDisabledErrorBody {
+  name: "ActionDisabledError";
+  message: string;
+  statusCode: 409;
+  action: string;
+  pk?: unknown;
+  pks?: unknown[];
+}
+/**
+ * Thrown by the gate interceptor when `disabled` returns truthy. Composes
+ * with Moost's existing error mapper to produce HTTP 409 with the wire body
+ * defined by {@link ActionDisabledErrorBody}.
+ *
+ * - `'row'`-level rejection: pass `(action, pk)` — the body emits `pk`.
+ * - `'rows'`-level rejection: pass `(action, undefined, pks)` — the body
+ *   emits `pks` (the FULL list of failing PKs in reject mode; the FULL list
+ *   of request PKs in skip mode with zero survivors).
+ */
+declare class ActionDisabledError extends HttpError<ActionDisabledErrorBody> {
+  name: string;
+  constructor(action: string, pk?: unknown, pks?: unknown[]);
+}
+//#endregion
 //#region src/permissions/crud-controls.d.ts
 declare const QUERY_CONTROLS: readonly string[];
 declare const PAGES_CONTROLS: readonly string[];
 declare const ONE_CONTROLS: readonly string[];
 //#endregion
-export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionOpts, DbActionPK, DbActionPKs, DbActions, DbRowActions, DbRowsActions, DbTableActions, ONE_CONTROLS, PAGES_CONTROLS, PkValidationSource, 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, validationErrorTransform };
+export { ActionDisabledError, ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionOpts, DbActionPK, DbActionPKs, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, ONE_CONTROLS, PAGES_CONTROLS, PkValidationSource, 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, useDbActionPk, useDbActionPks, useDbActionRow, useDbActionRows, validationErrorTransform };

package/dist/index.d.mts

@@ -5,6 +5,7 @@ import * as moost from "moost";
 import { Moost, TConsoleBase } from "moost";
 import * as _uniqu_url0 from "@uniqu/url";
 import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, TCrudOp, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TMetaResponse, Uniquery, UniqueryControls } from "@atscript/db";
+import * as _wooksjs_event_core0 from "@wooksjs/event-core";
 
 //#region src/as-readable.controller.d.ts
 /**
@@ -460,15 +461,72 @@ declare const validationErrorTransform: () => moost.TInterceptorDef;
 declare const UseValidationErrorTransform: () => ClassDecorator & MethodDecorator;
 //#endregion
 //#region src/actions/types.d.ts
+/** `'rows'`-level batch policy — controls whether failing rows reject or are filtered out. */
+type TOnDisabledRows = "reject" | "skip";
 /**
  * Options accepted by `@DbAction(name, opts?)`. Structurally derived from
- * {@link TDbActionInfo} so every addition to the wire shape automatically
- * propagates here. Fields owned by the framework (`name`, `level`, `processor`,
- * `value`) are excluded — `name` comes from the decorator argument, `level` is
- * inferred from `@DbActionPK*` usage, `processor` is fixed to `'backend'` for
- * method-decorator actions, and `value` is filled from the `@Post` path.
+ * {@link TDbActionInfo} so every wire-shape addition propagates here, EXCEPT
+ * `disabled` and `requiredFields` which differ in shape between decorator
+ * opts (function / dev-supplied) and the wire (string / forwarded verbatim).
+ *
+ * Fields owned by the framework (`name`, `level`, `processor`, `value`) are
+ * excluded — `name` comes from the decorator argument, `level` is inferred
+ * from `@DbActionPK*` / `@DbActionRow*` usage, `processor` is fixed to
+ * `'backend'` for method-decorator actions, and `value` is filled from the
+ * `@Post` path.
+ *
+ * Generic over `TRow` so the `disabled` predicate can be type-checked against
+ * the bound table's row shape. Note: TS decorators cannot infer `TRow` from
+ * the enclosing controller's class generic, so the dev MUST annotate the row
+ * arg explicitly (`(row: Order) => …`) to get type-checking.
  */
-type DbActionOpts = Partial<Omit<TDbActionInfo$1, "name" | "level" | "processor" | "value">>;
+type DbActionOpts<TRow = unknown> = Partial<Omit<TDbActionInfo$1, "name" | "level" | "processor" | "value" | "disabled" | "requiredFields">> & {
+  /**
+   * Per-row gate predicate. Truthy → action is disabled for that row.
+   * Server enforces (via the gate interceptor); UI evaluates the same
+   * expression to grey-out / hide the button.
+   *
+   * The dev MUST annotate the row arg explicitly (`(row: Order) => …`) —
+   * TS decorators cannot infer `TRow` from the enclosing class generic.
+   */
+  disabled?: (row: TRow) => boolean;
+  /**
+   * Optional dot-notation field paths the UI should union into `$select`.
+   * Plain `string[]` in v1.
+   *
+   * TODO: upgrade to typed `PathOf<TRow>[]` in a follow-up — the recursive
+   * type pattern is finicky for nested objects/arrays/optionals and isn't
+   * blocking v1.
+   *
+   * When omitted, the UI parses the stringified `disabled` itself to extract
+   * row-property accesses. When present, the UI uses this list verbatim — the
+   * server does NOT auto-derive or merge.
+   */
+  requiredFields?: string[];
+  /**
+   * `'rows'`-level batch policy. Default `'reject'`.
+   *
+   * - `'reject'`: evaluate every row (FULL scan, NOT short-circuit) before
+   *   throwing; if any row fails, the error body lists ALL failing PKs;
+   *   handler not invoked.
+   * - `'skip'`: filter cached rows + cached PKs to passing-only;
+   *   zero survivors → reject. Handler runs against the survivors.
+   *
+   * Ignored for `'row'` and `'table'` level actions.
+   */
+  onDisabledRows?: TOnDisabledRows;
+  /**
+   * Bound table reference. REQUIRED on non-`AsDbReadableController` classes
+   * when `disabled` is set OR a `@DbActionRow*` parameter is declared.
+   *
+   * Silently ignored on `AsDbReadableController` subclasses (which include
+   * `AsDbController`) — the bound table from the controller wins; the
+   * gate / thin interceptor probes `instanceof AsDbReadableController` and
+   * populates the bound-table slot from `controller.readable` before
+   * checking `opts.table`.
+   */
+  table?: AtscriptDbTable<any>;
+};
 interface DbActionsEntryCommon {
   label: string;
   level: TDbActionLevel$1;
@@ -477,7 +535,28 @@ interface DbActionsEntryCommon {
   description?: string;
   order?: number;
   default?: boolean;
-  promptText?: string;
+  /** Mirrors {@link TDbActionInfo.promptText} — singular/plural via tuple. */
+  promptText?: string | [string, string];
+  /** Mirrors {@link TDbActionInfo.shortcut} — single-character UI hint. */
+  shortcut?: string;
+  /**
+   * UI-only gate predicate (class-level dict entries do NOT register a
+   * server-side gate interceptor — the dict entry's `value` may point at an
+   * endpoint in another controller). The wire emits `fn.toString()` so the
+   * UI can grey-out / hide the button. For symmetric server enforcement at
+   * the actual `@Post`-bound handler, declare `@DbAction(name, { disabled })`
+   * on that handler too.
+   *
+   * Not generic over `TRow` — devs type the row arg explicitly.
+   */
+  disabled?: (row: any) => boolean;
+  /** Same as method-decorator `requiredFields`. UI hint, not server-derived. */
+  requiredFields?: string[];
+  /**
+   * Reserved for future API symmetry with method-decorator opts. Currently a
+   * no-op for class-level dict entries (no gate interceptor registers).
+   */
+  onDisabledRows?: TOnDisabledRows;
 }
 /**
  * Class-level dict entry. `value` semantics by processor:
@@ -508,21 +587,13 @@ type TDbActionsEntryUnpinned = DistributiveOmit<TDbActionsEntry, "level">;
 //#endregion
 //#region src/actions/db-action.decorator.d.ts
 /**
- * Mark a controller method as a database action surfaced via `/meta`.
- *
- * Metadata-only — pair with `@Post(...)` for Moost to bind the route. The
- * meta builder reads this metadata plus the bound POST path lazily and
- * emits the action with `processor: 'backend'`. Order vs.
- * `@DbActionDefault()` does not matter — both merge into the same slot.
- *
- * @example
- * ```ts
- * @Post('actions/block')
- * @DbAction('block', { label: 'Block', icon: 'i-as-block', intent: 'negative' })
- * async blockUser(@DbActionPK() id: string) { ... }
- * ```
+ * Mark a controller method as a database action surfaced via `/meta`. Writes
+ * `MOOST_DB_ACTION` metadata and registers a Moost interceptor when needed
+ * (gate when `disabled` is set, thin bound-table injector when only
+ * `@DbActionRow*` is present). Stacking two `@DbAction` on the same method
+ * is undefined and emits a warning.
  */
-declare function DbAction(name: string, opts?: DbActionOpts): MethodDecorator;
+declare function DbAction<TRow = unknown>(name: string, opts?: DbActionOpts<TRow>): MethodDecorator;
 //#endregion
 //#region src/actions/db-action-default.decorator.d.ts
 /**
@@ -545,6 +616,10 @@ declare function DbActionDefault(): MethodDecorator;
  *
  * Marks the param so {@link discoverActions} can infer the action's `level`
  * as `'row'`.
+ *
+ * Implementation note: the resolver is a thin reader of the cached PK wook
+ * — validation logic lives in the wook factory, which runs once per request
+ * regardless of how many readers consume the value.
  */
 declare function DbActionPK(): ParameterDecorator;
 //#endregion
@@ -558,9 +633,37 @@ declare function DbActionPK(): ParameterDecorator;
  *
  * Validation is strict — no type coercion. Marks the param so
  * {@link discoverActions} can infer the action's `level` as `'rows'`.
+ *
+ * In `'rows'` skip mode the resolved value reflects the gate interceptor's
+ * filtered subset (the cached PK slot is overwritten in place); see
+ * {@link dbActionPksSlot} for precedence details.
  */
 declare function DbActionPKs(): ParameterDecorator;
 //#endregion
+//#region src/actions/db-action-row.decorator.d.ts
+/**
+ * Parameter decorator that injects the row whose PK was supplied in the
+ * request body. Reads from the cached row wook (fetched once per request,
+ * shared with the gate interceptor when `disabled` is set).
+ *
+ * Marks the param so {@link discoverActions} infers the action's `level` as
+ * `'row'`. Co-occurrence with `@DbActionRows()` (or any multi-cardinality
+ * decorator) drops the action with a warning.
+ *
+ * In `'skip'` mode this returns the gate's filtered row; the original
+ * request-body row is not retrievable.
+ */
+declare function DbActionRow(): ParameterDecorator;
+/**
+ * Parameter decorator that injects the rows-array fetched by primary keys
+ * from the request body. Reads from the cached row-array wook.
+ *
+ * Marks the param so {@link discoverActions} infers the action's `level` as
+ * `'rows'`. In `'rows'` + `'skip'` mode the resolved value contains only the
+ * gate's surviving rows.
+ */
+declare function DbActionRows(): ParameterDecorator;
+//#endregion
 //#region src/actions/db-actions.decorator.d.ts
 /**
  * Declare class-level actions on a controller. Entries are flat dicts with
@@ -607,9 +710,65 @@ interface PkValidationSource {
   fieldDescriptors: readonly TDbFieldMeta[];
 }
 //#endregion
+//#region src/actions/pk-cache.d.ts
+declare const useDbActionPk: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<unknown>;
+}>;
+declare const useDbActionPks: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<unknown[]>;
+}>;
+//#endregion
+//#region src/actions/row-cache.d.ts
+declare const useDbActionRow: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<unknown>;
+}>;
+declare const useDbActionRows: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<unknown[]>;
+}>;
+//#endregion
+//#region src/actions/action-disabled-error.d.ts
+/**
+ * Wire-body shape for server-side gate rejections. The `name` discriminator
+ * lets `@atscript/db-client` recognise the response and construct the typed
+ * `ActionDisabledError` subclass. The shape extends Moost's standard
+ * `ServerError` envelope (`{ message, statusCode, errors? }`) with three
+ * additional fields:
+ *
+ * - `name: 'ActionDisabledError'` — discriminator the client matches.
+ * - `action` — the `@DbAction` name that rejected the request.
+ * - `pk?` — present only for `'row'`-level rejections.
+ * - `pks?` — present only for `'rows'`-level rejections.
+ *
+ * `message` is populated with a human-readable string so generic
+ * `ClientError` consumers (which read `body.message`) still get something
+ * useful without typed-catch dispatch.
+ */
+interface ActionDisabledErrorBody {
+  name: "ActionDisabledError";
+  message: string;
+  statusCode: 409;
+  action: string;
+  pk?: unknown;
+  pks?: unknown[];
+}
+/**
+ * Thrown by the gate interceptor when `disabled` returns truthy. Composes
+ * with Moost's existing error mapper to produce HTTP 409 with the wire body
+ * defined by {@link ActionDisabledErrorBody}.
+ *
+ * - `'row'`-level rejection: pass `(action, pk)` — the body emits `pk`.
+ * - `'rows'`-level rejection: pass `(action, undefined, pks)` — the body
+ *   emits `pks` (the FULL list of failing PKs in reject mode; the FULL list
+ *   of request PKs in skip mode with zero survivors).
+ */
+declare class ActionDisabledError extends HttpError<ActionDisabledErrorBody> {
+  name: string;
+  constructor(action: string, pk?: unknown, pks?: unknown[]);
+}
+//#endregion
 //#region src/permissions/crud-controls.d.ts
 declare const QUERY_CONTROLS: readonly string[];
 declare const PAGES_CONTROLS: readonly string[];
 declare const ONE_CONTROLS: readonly string[];
 //#endregion
-export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, type DbActionOpts, DbActionPK, DbActionPKs, DbActions, DbRowActions, DbRowsActions, DbTableActions, ONE_CONTROLS, PAGES_CONTROLS, type PkValidationSource, 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, validationErrorTransform };
+export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, type DbActionOpts, DbActionPK, DbActionPKs, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, ONE_CONTROLS, PAGES_CONTROLS, type PkValidationSource, 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, useDbActionPk, useDbActionPks, useDbActionRow, useDbActionRows, validationErrorTransform };