@atscript/moost-db 0.1.58 → 0.1.59

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 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 { 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 { 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";
 import { Moost, TConsoleBase } from "moost";
@@ -154,6 +154,9 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   /** Reference to the underlying readable (table or view). */
   protected readable: AtscriptDbReadable<T>;
   private readonly _gates;
+  private readonly _preferredIdSet;
+  private readonly _compositeIdShapes;
+  private readonly _overlayIsNoOp;
   constructor(readable: AtscriptDbReadable<T>, app: Moost);
   private _buildGates;
   private _collectAnnotated;
@@ -176,6 +179,27 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * May return a Promise for async lookups.
    */
   protected transformProjection(projection?: UniqueryControls["$select"]): UniqueryControls["$select"] | undefined | Promise<UniqueryControls["$select"] | undefined>;
+  private widenPreferredIdProjection;
+  private _widenArrayProjection;
+  private _widenMapProjection;
+  /** WHY: the URL parser only auto-coerces `$count`; every other boolean control reaches us as `"true"`/`"1"` and would fail DTO validation. */
+  private _coerceActionsControl;
+  /** Normalize a post-`widenPreferredIdProjection` $select into `string[] | null` (`null` = all fields). */
+  private _resolveProjectionForAugmenter;
+  /** WHY: filter row/rows envelopes by the per-request `applyMetaOverlay` action set; skip `meta()` when overlay is identity. */
+  private _resolveAugmentEnvelopes;
+  /** Returns a widened `$select` only when at least one `requiredFields` entry is missing; `null` means "no widening needed". */
+  private _widenSelectForActions;
+  private _prepareAugmentation;
+  private _resolveReadStrategy;
+  /**
+   * Shared `query` / `pages` pipeline: prepare actions augmentation + read
+   * strategy in parallel, pre-widen $select for `requiredFields`, run
+   * `exec`, and augment `result.data` with `$actions` when the request set
+   * `$actions=true`. Caller dispatches the strategy to its read-method
+   * family (count vs no-count).
+   */
+  private _runReadWithActions;
   /**
    * Extracts a composite identifier object from query params.
    * Tries composite primary key first, then compound unique indexes.
@@ -204,6 +228,7 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * (composite primary key or compound unique index).
    */
   getOneComposite(query: Record<string, string>, url: string): Promise<DataType | HttpError>;
+  private _findByIdAndAugment;
   /**
    * **GET /meta** — returns table/view metadata for UI.
    *
@@ -464,70 +489,81 @@ declare const UseValidationErrorTransform: () => ClassDecorator & MethodDecorato
 /** `'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 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.
+ * Dot-notation field paths of `TRow`'s flat type. Drives both the runtime
+ * projection widening and the type narrowing of the `disabled` predicate's
+ * row argument. Relations are absent from `FlatOf<T>` — listing a relation
+ * field is therefore a compile error.
+ *
+ * Permissive fallback when `TRow = unknown` (no explicit decorator generic):
+ * any string is allowed and the `disabled` predicate's row arg is `any[]`,
+ * preserving the prior loose typing for un-annotated call sites.
  */
-type DbActionOpts<TRow = unknown> = Partial<Omit<TDbActionInfo$1, "name" | "level" | "processor" | "value" | "disabled" | "requiredFields">> & {
+type FlatKey<TRow> = unknown extends TRow ? string : keyof FlatOf<TRow> & string;
+/** Row-shape narrowing for the `disabled` predicate. Falls back to `any` when `TRow = unknown`. */
+type DisabledRowsArg<TRow, R extends readonly FlatKey<TRow>[]> = unknown extends TRow ? any[] : Pick<FlatOf<TRow>, R[number] & keyof FlatOf<TRow>>[];
+interface NoGate {
+  requiredFields?: never;
+  disabled?: never;
+  onDisabledRows?: never;
+}
+interface WithGate<TRow, R extends readonly FlatKey<TRow>[]> {
   /**
-   * 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.
+   * Dot-notation field paths the predicate references. SERVER-INTERNAL —
+   * never emitted on the `/meta` wire. Consumed verbatim to widen the DB
+   * projection so `disabled` always sees the fields it declared.
    */
-  disabled?: (row: TRow) => boolean;
+  requiredFields: R;
   /**
-   * 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.
+   * Sync batch gate predicate — returns a parallel `boolean[]` aligned with
+   * the input. `true` = disabled for the corresponding row. The `rows`
+   * argument is type-narrowed to `Pick<FlatOf<TRow>, R[number]>[]`; reading
+   * a field not listed in `requiredFields` is a compile error.
    *
-   * 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.
+   * Promise return is NOT permitted — the predicate is consumed in the
+   * same tick by the gate and the augmenter.
    */
-  requiredFields?: string[];
+  disabled?: (rows: DisabledRowsArg<TRow, R>) => boolean[];
   /**
    * `'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.
+   * - `'reject'`: evaluate every row before throwing; if any row fails, the
+   *   error body lists ALL failing IDs; handler not invoked.
+   * - `'skip'`: filter cached rows + cached IDs to passing-only; zero
+   *   survivors → reject. Handler runs against the survivors.
    *
    * Ignored for `'row'` and `'table'` level actions.
    */
   onDisabledRows?: TOnDisabledRows;
+}
+/**
+ * Loose gate shape used when `TRow = unknown` (no explicit decorator generic).
+ * Preserves the prior un-typed call-site flexibility; the runtime still drops
+ * actions where `disabled` is set without `requiredFields`.
+ */
+interface LooseGate {
+  requiredFields?: string[];
+  disabled?: (rows: any[]) => boolean[];
+  onDisabledRows?: TOnDisabledRows;
+}
+type GateOpts<TRow, R extends readonly FlatKey<TRow>[]> = unknown extends TRow ? LooseGate : NoGate | WithGate<TRow, R>;
+interface BaseActionOpts extends Partial<Omit<TDbActionInfo$1, "name" | "level" | "processor" | "value" | "disabled">> {
   /**
    * 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`.
+   * `AsDbController`) — the bound table from the controller wins.
    */
   table?: AtscriptDbTable<any>;
-};
-interface DbActionsEntryCommon {
+}
+/**
+ * Options accepted by `@DbAction(name, opts?)`. Generic over `TRow` (the
+ * controller's bound atscript type) and `R` (the literal `requiredFields`
+ * tuple). Both are inferred at the call site via the decorator's `<TRow>`
+ * argument plus `const R` generic.
+ */
+type DbActionOpts<TRow = unknown, R extends readonly FlatKey<TRow>[] = []> = BaseActionOpts & GateOpts<TRow, R>;
+interface DbActionsEntryCommonBase {
   label: string;
   level: TDbActionLevel$1;
   icon?: string;
@@ -539,51 +575,36 @@ interface DbActionsEntryCommon {
   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;
 }
+type DbActionsEntryWithGate<TRow, R extends readonly FlatKey<TRow>[]> = DbActionsEntryCommonBase & GateOpts<TRow, R>;
 /**
  * Class-level dict entry. `value` semantics by processor:
  *
- * - `'navigate'` — REQUIRED, non-empty. The URL template (with `$1` substituted client-side).
- * - `'backend'`  — REQUIRED, non-empty. The full HTTP POST path the UI client should invoke.
- *   For row/rows entries the dev-supplied path MUST point to a `@Post`-bound
- *   handler accepting the PK-shaped JSON body (single PK scalar / composite
- *   object / array thereof) — typically a method using `@DbActionPK()` or
- *   `@DbActionPKs()`. The meta builder does NOT validate this.
+ * - `'navigate'` — REQUIRED, non-empty. URL template (`$1` substituted client-side).
+ * - `'backend'`  — REQUIRED, non-empty. Full HTTP POST path the UI client invokes.
  * - `'custom'`   — `value` is forbidden in the entry; the meta builder fills it
  *   with the dict key.
  */
-type TDbActionsEntry = (DbActionsEntryCommon & {
+type TDbActionsEntry<TRow = unknown, R extends readonly FlatKey<TRow>[] = []> = (DbActionsEntryWithGate<TRow, R> & {
   processor: "navigate";
   value: string;
-}) | (DbActionsEntryCommon & {
+}) | (DbActionsEntryWithGate<TRow, R> & {
   processor: "custom";
   value?: never;
-}) | (DbActionsEntryCommon & {
+}) | (DbActionsEntryWithGate<TRow, R> & {
   processor: "backend";
   value: string;
 });
 /** Distributes `Omit` across the discriminated union members. */
 type DistributiveOmit<T, K extends keyof T> = T extends T ? Omit<T, K> : never;
 /** Same as {@link TDbActionsEntry} but without the `level` field — used by the level-pinned shortcuts. */
-type TDbActionsEntryUnpinned = DistributiveOmit<TDbActionsEntry, "level">;
+type TDbActionsEntryUnpinned<TRow = unknown, R extends readonly FlatKey<TRow>[] = []> = DistributiveOmit<TDbActionsEntry<TRow, R>, "level">;
+type DbActionsDictBase = Record<string, unknown>;
+type EntryRequiredFields<E, TRow> = E extends {
+  requiredFields: infer R;
+} ? R extends readonly FlatKey<TRow>[] ? R : [] : [];
+type ValidatedDict<TRow, D extends DbActionsDictBase> = { [K in keyof D]: TDbActionsEntry<TRow, EntryRequiredFields<D[K], TRow>> };
+type ValidatedUnpinnedDict<TRow, D extends DbActionsDictBase> = { [K in keyof D]: TDbActionsEntryUnpinned<TRow, EntryRequiredFields<D[K], TRow>> };
 //#endregion
 //#region src/actions/db-action.decorator.d.ts
 /**
@@ -592,8 +613,13 @@ type TDbActionsEntryUnpinned = DistributiveOmit<TDbActionsEntry, "level">;
  * (gate when `disabled` is set, thin bound-table injector when only
  * `@DbActionRow*` is present). Stacking two `@DbAction` on the same method
  * is undefined and emits a warning.
+ *
+ * Generic over `TRow` (annotate at the call site: `@DbAction<Order>(...)`)
+ * and `R` (the literal `requiredFields` tuple, inferred via `const R`).
+ * The `disabled` predicate's `rows` argument is type-narrowed to
+ * `Pick<FlatOf<TRow>, R[number]>[]`.
  */
-declare function DbAction<TRow = unknown>(name: string, opts?: DbActionOpts<TRow>): MethodDecorator;
+declare function DbAction<TRow = unknown, const R extends readonly FlatKey<TRow>[] = []>(name: string, opts?: DbActionOpts<TRow, R>): MethodDecorator;
 //#endregion
 //#region src/actions/db-action-default.decorator.d.ts
 /**
@@ -602,49 +628,56 @@ declare function DbAction<TRow = unknown>(name: string, opts?: DbActionOpts<TRow
  */
 declare function DbActionDefault(): MethodDecorator;
 //#endregion
-//#region src/actions/db-action-pk.decorator.d.ts
+//#region src/actions/db-action-id.decorator.d.ts
 /**
- * Parameter resolver that reads the primary key from the JSON request body
- * and validates it against the bound table's PK schema.
+ * Parameter resolver that reads a row identifier from the JSON request body
+ * and validates it against the bound table's legitimate identifiers.
  *
- * - Single-field PK → JSON-encoded scalar (`"abc"`, `42`, `true`).
- * - Composite PK → JSON object with all PK fields.
+ * Body shape is always a JSON object — no scalar form. The object's key set
+ * MUST exactly match one of the table's legitimate identifications:
  *
- * Validation is strict — no type coercion. Mismatches throw a
+ * - Single-field PK → `{ id: "abc" }` (or whatever the PK prop is named).
+ * - Composite PK → `{ tenantId: "...", userId: "..." }`.
+ * - Single-field unique index → `{ slug: "alpha" }`.
+ * - Compound unique index → `{ tenantId: "...", slug: "..." }`.
+ *
+ * Strict — unknown fields are rejected, no type coercion. Mismatches throw a
  * `ValidatorError` which the existing validation interceptor surfaces as
  * HTTP 400 with the same envelope as DTO failures.
  *
  * Marks the param so {@link discoverActions} can infer the action's `level`
  * as `'row'`.
  *
- * Implementation note: the resolver is a thin reader of the cached PK wook
+ * Implementation note: the resolver is a thin reader of the cached ID wook
  * — validation logic lives in the wook factory, which runs once per request
  * regardless of how many readers consume the value.
  */
-declare function DbActionPK(): ParameterDecorator;
+declare function DbActionID(): ParameterDecorator;
 //#endregion
-//#region src/actions/db-action-pks.decorator.d.ts
+//#region src/actions/db-action-ids.decorator.d.ts
 /**
- * Parameter resolver that reads a JSON array of primary keys from the request
- * body and validates each entry against the bound table's PK schema.
+ * Parameter resolver that reads a JSON array of row identifiers from the
+ * request body and validates each entry against the bound table.
  *
- * - Scalar PK → JSON array of scalars (`["a","b","c"]`).
- * - Composite PK → JSON array of objects.
+ * Body shape is always a JSON array of objects — no scalar form. Each
+ * element's key set MUST exactly match one of the table's legitimate
+ * identifications (PK or any unique index). Elements MAY mix shapes:
+ * `[{ id: "1" }, { slug: "alpha" }]` is valid when both `id` is the PK
+ * and `slug` is a unique index.
  *
- * Validation is strict — no type coercion. Marks the param so
- * {@link discoverActions} can infer the action's `level` as `'rows'`.
+ * Strict — unknown fields are rejected, no type coercion. Marks the param
+ * so {@link discoverActions} can infer the action's `level` as `'rows'`.
  *
  * In `'rows'` skip mode the resolved value reflects the gate interceptor's
- * filtered subset (the cached PK slot is overwritten in place); see
- * {@link dbActionPksSlot} for precedence details.
+ * filtered subset (the cached ID slot is overwritten in place); see
+ * {@link dbActionIdsSlot} for precedence details.
  */
-declare function DbActionPKs(): ParameterDecorator;
+declare function DbActionIDs(): 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).
+ * Parameter decorator that injects the row whose identifier was supplied in
+ * the request body.
  *
  * Marks the param so {@link discoverActions} infers the action's `level` as
  * `'row'`. Co-occurrence with `@DbActionRows()` (or any multi-cardinality
@@ -655,8 +688,8 @@ declare function DbActionPKs(): ParameterDecorator;
  */
 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.
+ * Parameter decorator that injects the rows fetched by the identifiers
+ * supplied in the request body.
  *
  * Marks the param so {@link discoverActions} infers the action's `level` as
  * `'rows'`. In `'rows'` + `'skip'` mode the resolved value contains only the
@@ -672,50 +705,46 @@ declare function DbActionRows(): ParameterDecorator;
  * the level-pinned shortcuts (`@DbTableActions`, `@DbRowActions`,
  * `@DbRowsActions`) to avoid repeating `level`.
  *
- * The dictionary key serves as the action `name`. Entries do NOT bind any
- * HTTP route — the meta builder surfaces them in `/meta` only. For
- * `processor: 'backend'`, the dev-supplied `value` MUST point to a real
- * `@Post`-bound endpoint accepting the level-determined body shape.
+ * Generic over `TRow` (annotate at the call site: `@DbActions<Order>(...)`)
+ * and `D` (the literal dict, captured via `const D`). Each entry's
+ * `disabled` predicate is type-narrowed by its own `requiredFields` literal.
  *
  * Multiple `@DbActions` (and shortcut) decorators on the same class
  * accumulate.
  */
-declare function DbActions(dict: Record<string, TDbActionsEntry>): ClassDecorator;
+declare function DbActions<TRow = unknown, const D extends Record<string, unknown> = {}>(dict: D & ValidatedDict<TRow, D>): ClassDecorator;
 /** Sugar for `@DbActions` with `level: 'table'` injected into each entry. */
-declare function DbTableActions(dict: Record<string, TDbActionsEntryUnpinned>): ClassDecorator;
+declare function DbTableActions<TRow = unknown, const D extends Record<string, unknown> = {}>(dict: D & ValidatedUnpinnedDict<TRow, D>): ClassDecorator;
 /** Sugar for `@DbActions` with `level: 'row'` injected into each entry. */
-declare function DbRowActions(dict: Record<string, TDbActionsEntryUnpinned>): ClassDecorator;
+declare function DbRowActions<TRow = unknown, const D extends Record<string, unknown> = {}>(dict: D & ValidatedUnpinnedDict<TRow, D>): ClassDecorator;
 /** Sugar for `@DbActions` with `level: 'rows'` injected into each entry. */
-declare function DbRowsActions(dict: Record<string, TDbActionsEntryUnpinned>): ClassDecorator;
+declare function DbRowsActions<TRow = unknown, const D extends Record<string, unknown> = {}>(dict: D & ValidatedUnpinnedDict<TRow, D>): ClassDecorator;
 //#endregion
 //#region src/actions/discover.d.ts
 /**
- * Discover all actions declared on a controller and produce the `/meta` array.
- * Reads class + method metadata via `getMoostMate()` and resolves bound POST
- * paths through the Moost controller overview.
- *
- * Result is memoized per controller constructor — discovery walks every
- * handler entry and reads decorator metadata, which is wasted work to repeat
- * across instances.
+ * Pairs the wire-shaped `info` with the original decorator opts / dict entry,
+ * so the augmenter can invoke the live `disabled` reference (deliberately
+ * absent from the wire `info`).
  */
-declare function discoverActions(controllerCtor: Function, app: Moost, logger: TConsoleBase): TDbActionInfo$1[];
+interface TDbActionEnvelope {
+  info: TDbActionInfo$1;
+  raw: DbActionOpts | TDbActionsEntry;
+}
+/** 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/pk-validation.d.ts
-/**
- * Minimal shape required to validate PKs against a table — supplied by the
- * controller's underlying `AtscriptDbReadable`/`AtscriptDbTable`.
- */
-interface PkValidationSource {
-  primaryKeys: readonly string[];
+//#region src/actions/id-validation.d.ts
+interface IdValidationSource {
+  getIdentifications(): readonly TIdentification[];
   fieldDescriptors: readonly TDbFieldMeta[];
 }
 //#endregion
-//#region src/actions/pk-cache.d.ts
-declare const useDbActionPk: _wooksjs_event_core0.WookComposable<{
-  load: () => Promise<unknown>;
+//#region src/actions/id-cache.d.ts
+declare const useDbActionId: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<Record<string, unknown>>;
 }>;
-declare const useDbActionPks: _wooksjs_event_core0.WookComposable<{
-  load: () => Promise<unknown[]>;
+declare const useDbActionIds: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<Record<string, unknown>[]>;
 }>;
 //#endregion
 //#region src/actions/row-cache.d.ts
@@ -723,7 +752,7 @@ declare const useDbActionRow: _wooksjs_event_core0.WookComposable<{
   load: () => Promise<unknown>;
 }>;
 declare const useDbActionRows: _wooksjs_event_core0.WookComposable<{
-  load: () => Promise<unknown[]>;
+  load: () => Promise<(Record<string, unknown> | undefined)[]>;
 }>;
 //#endregion
 //#region src/actions/action-disabled-error.d.ts
@@ -736,8 +765,8 @@ declare const useDbActionRows: _wooksjs_event_core0.WookComposable<{
  *
  * - `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.
+ * - `id?` — present only for `'row'`-level rejections.
+ * - `ids?` — 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
@@ -748,27 +777,42 @@ interface ActionDisabledErrorBody {
   message: string;
   statusCode: 409;
   action: string;
-  pk?: unknown;
-  pks?: unknown[];
+  id?: Record<string, unknown>;
+  ids?: Record<string, 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).
+ * - `'row'`-level rejection: pass `(action, id)` — the body emits `id`.
+ * - `'rows'`-level rejection: pass `(action, undefined, ids)` — the body
+ *   emits `ids` (the FULL list of failing IDs in reject mode; the FULL list
+ *   of request IDs in skip mode with zero survivors).
  */
 declare class ActionDisabledError extends HttpError<ActionDisabledErrorBody> {
   name: string;
-  constructor(action: string, pk?: unknown, pks?: unknown[]);
+  constructor(action: string, id?: Record<string, unknown>, ids?: Record<string, unknown>[]);
 }
 //#endregion
+//#region src/actions/per-row.d.ts
+/**
+ * Lift a per-row predicate into the batch shape required by
+ * `@DbAction` opts.`disabled` and class-level dict `disabled`. Polarity is
+ * preserved — `true` from `fn` means the action is disabled for that row.
+ *
+ * ```ts
+ * @DbAction<Order>('archive', {
+ *   requiredFields: ['status'],
+ *   disabled: perRow(r => r.status === 'archived'),
+ * })
+ * ```
+ */
+declare const perRow: <TRow>(fn: (row: TRow) => boolean) => (rows: TRow[]) => boolean[];
+//#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 { 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 };
+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 };