@atscript/moost-db 0.1.144 → 0.1.146

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { i as resolveDbSpace, n as clearDbSpaces, r as provideDbSpace, t as DEFAULT_DB_SPACE } from "./db-space-registry-CWpYwZ4R.cjs";
 import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, TSerializedAnnotatedType, TValidatorOptions, Validator } from "@atscript/typescript/utils";
-import { AggregateFn, AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudOp as TCrudOp$1, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteCheckContext, TDbWriteCheckContext as TDbWriteCheckContext$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
+import { AggregateFn, AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudOp as TCrudOp$1, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbAvailableActions, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteCheckContext, TDbWriteCheckContext as TDbWriteCheckContext$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
 import { HttpError } from "@moostjs/event-http";
 import { Mate, Moost, TConsoleBase, TMateParamMeta, TMoostMetadata } from "moost";
 import { parseUrl } from "@uniqu/url";
@@ -11,11 +11,12 @@ import { parseUrl } from "@uniqu/url";
  * report `"remove"`; value-help controllers report `query` / `pages` / `one`
  * like DB readables do; every `@DbAction` handler (row, rows and table
  * level) reports `"action"` with the action's name in
- * {@link TDbRequestContext.action}.
+ * {@link TDbRequestContext.action}; `GET /meta/actions/:id` and
+ * `/meta/actions?…` report `"availableActions"` (since 0.1.145).
  *
  * @since 0.1.143
  */
-type TDbRequestEndpoint = "query" | "pages" | "geo" | "one" | "meta" | "metaForm" | "insert" | "replace" | "update" | "remove" | "action";
+type TDbRequestEndpoint = "query" | "pages" | "geo" | "one" | "meta" | "metaForm" | "insert" | "replace" | "update" | "remove" | "action" | "availableActions";
 /**
  * Context passed to {@link AsReadableController.prepareRequest}.
  *
@@ -320,6 +321,15 @@ interface IdValidationSource {
   readonly fieldDescriptors: readonly TDbFieldMeta[];
 }
 //#endregion
+//#region src/actions/row-scope.d.ts
+/**
+ * The key of `AsDbReadableController`'s internal action-overlay method —
+ * `rowOverlay()` AND (since 0.1.145) the action's `actionRowScope`. A
+ * registered symbol: not an overridable seam, and still found when
+ * moost-db loads in two module realms (moost-vite SSR).
+ */
+declare const ACTION_OVERLAY: unique symbol;
+//#endregion
 //#region src/meta/field-capabilities.d.ts
 /**
  * Per-path HTTP capability of a DB readable — the single source that both the
@@ -586,6 +596,12 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private readonly _decorates;
   /** `true` when a subclass overrides {@link transformOne} or {@link transformFilter} (a row overlay may exist). */
   private readonly _hasRowOverlay;
+  /** Per-envelope gate fields, memoized while field visibility is not request-scoped. */
+  private readonly _gateFieldsMemo;
+  /** `true` when a subclass overrides {@link allowedActions}. */
+  private readonly _hasAllowedActions;
+  /** `true` when a subclass overrides {@link actionRowScope} (the gate, `$actions` and `/meta/actions` apply it). */
+  private readonly _hasActionRowScope;
   /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
   private readonly _quantityRefByPath;
   /** `@db.column.searchable` paths — the `$search` fallback when the adapter has no native search. */
@@ -784,6 +800,44 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * `findById`). Override to scope `/one` differently.
    */
   protected transformOne(filter: FilterExpr): FilterExpr | Promise<FilterExpr>;
+  /**
+   * The subset of the row-level action `names` the caller may run (since
+   * 0.1.145) — what `$actions` and `GET /meta/actions/:id` list from. The
+   * default keeps the names present in the per-request `/meta` envelope
+   * (`applyMetaOverlay` over the cached one), or all of them when
+   * `applyMetaOverlay` is not overridden (no call). Override it to answer
+   * from per-action permission checks without building the whole `/meta`
+   * overlay on every `$actions` read. Runs after {@link prepareRequest}.
+   * Names it returns that are not in `names` are ignored.
+   *
+   * @since 0.1.145
+   */
+  protected allowedActions(names: readonly string[]): readonly string[] | Promise<readonly string[]>;
+  /**
+   * The rows the row-level action `actionName` may run on (since 0.1.145),
+   * as an extra row filter; `undefined` or `{}` = no restriction (the
+   * default). Enforced by the action gate — ANDed with the {@link rowOverlay}
+   * the action's ids / rows are loaded under, so an id outside it gets the
+   * same 404 "Row not found for action identifier" as a missing one — and
+   * reflected in `$actions` and `GET /meta/actions`, which list the action
+   * only on rows inside it.
+   *
+   * Runs after {@link prepareRequest}, once per action per request. `$actions`
+   * checks the page's rows with one id-only query per distinct filter
+   * OBJECT (return the same object for several actions to share one query),
+   * straight against the bound readable: the filter may use fields
+   * {@link hasField} hides, and nothing of it reaches the response. Not
+   * overriding it costs nothing.
+   *
+   * ```ts
+   * protected actionRowScope(action: string) {
+   *   return action === "approve" ? { ownerId: currentUserId() } : undefined
+   * }
+   * ```
+   *
+   * @since 0.1.145
+   */
+  protected actionRowScope(_actionName: string): FilterExpr | undefined | Promise<FilterExpr | undefined>;
   /**
    * Transform projection before querying.
    * May return a Promise for async lookups.
@@ -810,7 +864,7 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private _widenQuantityMapProjection;
   /** 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. */
+  /** Row/rows envelopes narrowed to {@link allowedActions}; no hook call when neither it nor `applyMetaOverlay` is overridden. */
   private _resolveAugmentEnvelopes;
   /**
    * Returns a widened `$select` only when at least one `requiredFields` entry
@@ -820,6 +874,32 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    */
   private _widenSelectForActions;
   private _prepareAugmentation;
+  /**
+   * {@link actionRowScope} of every offered action (in parallel, alongside
+   * `overlay`), grouped by filter object; each group's filter is composed
+   * with the row overlay exactly as the gate composes it.
+   */
+  private _resolveActionScopeGroups;
+  /** Per scoped action, a per-row mask of rows outside its scope (one id-only read per group). */
+  private _outOfScopeMasks;
+  /**
+   * The row filter {@link actionRowScope} returns for `action` — `undefined`
+   * when empty or when the hook is not overridden (no call). THE per-action
+   * scope rule: the action gate, `$actions` and `/meta/actions` all read it here.
+   */
+  private _actionScope;
+  /**
+   * The fields `envelope`'s gate loads ({@link actionRowFields} under this
+   * request's field visibility) — memoized unless visibility is request-scoped.
+   */
+  private _gateFields;
+  /**
+   * @internal The action gate's overlay (reached by the `@DbAction`
+   * interceptor through {@link ACTION_OVERLAY}): {@link rowOverlay} AND the
+   * action's {@link actionRowScope} (since 0.1.145) — `undefined` when both
+   * are empty.
+   */
+  [ACTION_OVERLAY](action: string | undefined): Promise<FilterExpr | undefined>;
   /**
    * `@db.column.searchable` paths, minus anything the adapter can't filter
    * (JSON storage, encrypted), `@db.writeOnly` fields and navigation
@@ -894,11 +974,14 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   protected decorateRows?(rows: Record<string, unknown>[], ctx: TDbDecorateContext): void | Promise<void>;
   /**
    * Finishes a read's top-level rows in place: `$actions` augmentation (when
-   * the request asked for it — `prep`), then {@link decorateRows} when a
+   * the request asked for it — `prep`; minus actions whose
+   * {@link actionRowScope} a row misses), then {@link decorateRows} when a
    * subclass implements it. Returns the hook's result — `undefined`, with no
    * promise or microtask, when there is no hook or it is synchronous.
    */
   private _finishRows;
+  /** `$actions` augmentation (when `prep`), then {@link decorateRows} when implemented. */
+  private _augmentAndDecorate;
   /**
    * Shared `query` / `pages` / `geo` pipeline: prepare actions augmentation + read
    * strategy in parallel, pre-widen $select for `requiredFields`, run
@@ -993,6 +1076,29 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * driver there), the sealed projection, the row read and its augmentation.
    */
   private _readOne;
+  /**
+   * **GET /meta/actions/:id** — the row-level actions the caller may run on
+   * the row `id` addresses (the `/one/:id` id forms), as
+   * `{ actions, disabledReasons? }` — no row data (since 0.1.145). Exactly
+   * what calling each action would do: the action survives
+   * {@link applyMetaOverlay}, the row resolves under its gate overlay
+   * ({@link actionOverlay}) and its `disabled` rule passes on the fields the
+   * gate loads. Needs no read grant; an unknown or out-of-scope id answers
+   * `{ actions: [] }`. {@link prepareRequest} runs first with
+   * `endpoint: "availableActions"`.
+   */
+  availableActionsById(id: string): Promise<TDbAvailableActions>;
+  /**
+   * **GET /meta/actions?field1=val1&…** — {@link availableActionsById} by
+   * composite key (composite primary key or compound unique index), the
+   * `/one?…` rules.
+   */
+  availableActions(query: Record<string, string>): Promise<TDbAvailableActions | HttpError>;
+  /**
+   * The row resolves ONCE, like `/one/:id` under {@link rowOverlay}; scoped
+   * actions are then checked on it exactly like `$actions` rows.
+   */
+  private _availableActions;
   /**
    * **GET /meta** — returns table/view metadata for UI.
    *
@@ -1610,6 +1716,7 @@ declare module "moost" {
     atscript_db_action_param?: TDbActionParamKind;
     atscript_db_action_row?: TDbActionRowMarker;
     atscript_db_action_rows?: TDbActionRowMarker;
+    atscript_db_endpoint?: TDbRequestEndpoint;
   }
   interface TMoostParamsMetadata {
     atscript_db_action_param?: TDbActionParamKind;
@@ -1662,6 +1769,12 @@ interface AtscriptDbMeta {
   atscript_db_action_rows?: true;
   /** Class-level — written by `@TableController` / `@ReadableController` / `@ViewController`. */
   atscript_db_readable_binding?: TReadableBindingMeta;
+  /**
+   * Method-level — the `prepareRequest` endpoint a framework handler
+   * delegates its authorization to (since 0.1.145). Read it with
+   * {@link getDbEndpoint}.
+   */
+  atscript_db_endpoint?: TDbRequestEndpoint;
 }
 /**
  * Param-level metadata written by `@atscript/moost-db`'s param
@@ -1883,6 +1996,23 @@ interface TAssertExposedOptions {
  */
 declare function assertExposed(app: Moost, models: readonly TAtscriptAnnotatedType[], options?: TAssertExposedOptions): TAtscriptAnnotatedType[];
 //#endregion
+//#region src/db-endpoint.d.ts
+/**
+ * The `prepareRequest` endpoint a controller handler delegates its
+ * authorization to (since 0.1.145) — `undefined` for a handler that is
+ * authorized on its own like any other route. `target` is the controller
+ * instance or class; the tag is inherited through the class chain (a
+ * subclass override of a tagged handler keeps it). Today only
+ * `GET /meta/actions/:id` and `/meta/actions?…` are tagged
+ * (`"availableActions"`).
+ *
+ * ```ts
+ * const endpoint = getDbEndpoint(controller, methodName);
+ * if (endpoint) return; // prepareRequest({ endpoint }) authorizes this call
+ * ```
+ */
+declare function getDbEndpoint(target: object, method: string | symbol): TDbRequestEndpoint | undefined;
+//#endregion
 //#region src/http-errors.d.ts
 /** One entry of the structured error envelope's `errors` array. */
 interface THttpErrorEntry {
@@ -2096,6 +2226,7 @@ declare function InputForm<T extends TAtscriptAnnotatedType & {
  * so the augmenter can invoke the live `disabled` reference (deliberately
  * absent from the wire `info`).
  */
+/** A discovered action: its `/meta.actions[]` entry plus the server-internal opts it was declared with. */
 interface TDbActionEnvelope {
   info: TDbActionInfo$1;
   raw: DbActionOpts | TDbActionsEntry;
@@ -2104,6 +2235,12 @@ interface TDbActionEnvelope {
 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[];
+/**
+ * The `'row'` / `'rows'`-level subset of {@link discoverActions} (since
+ * 0.1.145 public) — the actions `$actions` and `GET /meta/actions/:id`
+ * consider, in `/meta.actions` order. Memoized per controller class.
+ */
+declare function discoverRowLevelActions(controllerCtor: Function, app: Moost, logger: TConsoleBase): TDbActionEnvelope[];
 //#endregion
 //#region src/actions/id-cache.d.ts
 declare const useDbActionId: import("@wooksjs/event-core").WookComposable<{
@@ -2292,4 +2429,4 @@ declare function resolveTerminalRef(def: TAtscriptAnnotatedType): TTerminalRef |
  */
 declare function applyTerminalRefs(serialized: TSerializedAnnotatedType, runtime: TAtscriptAnnotatedType, options: TSerializeOptions): TSerializedAnnotatedType;
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DB_CRUD_HANDLERS, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionDisabledVerdict, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbClassActionMeta, TDbControlsType, TDbDecorateContext, TDbDecorateEndpoint, TDbFieldVisibility, TDbIndexFieldPaths, TDbParsedRequest, type TDbRemoveGuardContext, TDbRequestContext, TDbRequestEndpoint, type TDbWriteAction, type TDbWriteCheckContext, type TDbWriteGuardContext, type TFieldCapability, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ValueHelpQuery, ValueHelpSelect, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };
+export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DB_CRUD_HANDLERS, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionDisabledVerdict, type TDbActionEnvelope, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbClassActionMeta, TDbControlsType, TDbDecorateContext, TDbDecorateEndpoint, TDbFieldVisibility, TDbIndexFieldPaths, TDbParsedRequest, type TDbRemoveGuardContext, TDbRequestContext, TDbRequestEndpoint, type TDbWriteAction, type TDbWriteCheckContext, type TDbWriteGuardContext, type TFieldCapability, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ValueHelpQuery, ValueHelpSelect, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, discoverRowLevelActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, getDbEndpoint, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };

package/dist/index.d.mts

@@ -3,7 +3,7 @@ import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, TSerializ
 import { HttpError } from "@moostjs/event-http";
 import { Mate, Moost, TConsoleBase, TMateParamMeta, TMoostMetadata } from "moost";
 import { parseUrl } from "@uniqu/url";
-import { AggregateFn, AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudOp as TCrudOp$1, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteCheckContext, TDbWriteCheckContext as TDbWriteCheckContext$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
+import { AggregateFn, AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudOp as TCrudOp$1, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbAvailableActions, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteCheckContext, TDbWriteCheckContext as TDbWriteCheckContext$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
 //#region src/as-readable.controller.d.ts
 /**
  * Endpoint a {@link AsReadableController.prepareRequest} call serves. `/one`
@@ -11,11 +11,12 @@ import { AggregateFn, AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExp
  * report `"remove"`; value-help controllers report `query` / `pages` / `one`
  * like DB readables do; every `@DbAction` handler (row, rows and table
  * level) reports `"action"` with the action's name in
- * {@link TDbRequestContext.action}.
+ * {@link TDbRequestContext.action}; `GET /meta/actions/:id` and
+ * `/meta/actions?…` report `"availableActions"` (since 0.1.145).
  *
  * @since 0.1.143
  */
-type TDbRequestEndpoint = "query" | "pages" | "geo" | "one" | "meta" | "metaForm" | "insert" | "replace" | "update" | "remove" | "action";
+type TDbRequestEndpoint = "query" | "pages" | "geo" | "one" | "meta" | "metaForm" | "insert" | "replace" | "update" | "remove" | "action" | "availableActions";
 /**
  * Context passed to {@link AsReadableController.prepareRequest}.
  *
@@ -320,6 +321,15 @@ interface IdValidationSource {
   readonly fieldDescriptors: readonly TDbFieldMeta[];
 }
 //#endregion
+//#region src/actions/row-scope.d.ts
+/**
+ * The key of `AsDbReadableController`'s internal action-overlay method —
+ * `rowOverlay()` AND (since 0.1.145) the action's `actionRowScope`. A
+ * registered symbol: not an overridable seam, and still found when
+ * moost-db loads in two module realms (moost-vite SSR).
+ */
+declare const ACTION_OVERLAY: unique symbol;
+//#endregion
 //#region src/meta/field-capabilities.d.ts
 /**
  * Per-path HTTP capability of a DB readable — the single source that both the
@@ -586,6 +596,12 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private readonly _decorates;
   /** `true` when a subclass overrides {@link transformOne} or {@link transformFilter} (a row overlay may exist). */
   private readonly _hasRowOverlay;
+  /** Per-envelope gate fields, memoized while field visibility is not request-scoped. */
+  private readonly _gateFieldsMemo;
+  /** `true` when a subclass overrides {@link allowedActions}. */
+  private readonly _hasAllowedActions;
+  /** `true` when a subclass overrides {@link actionRowScope} (the gate, `$actions` and `/meta/actions` apply it). */
+  private readonly _hasActionRowScope;
   /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
   private readonly _quantityRefByPath;
   /** `@db.column.searchable` paths — the `$search` fallback when the adapter has no native search. */
@@ -784,6 +800,44 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * `findById`). Override to scope `/one` differently.
    */
   protected transformOne(filter: FilterExpr): FilterExpr | Promise<FilterExpr>;
+  /**
+   * The subset of the row-level action `names` the caller may run (since
+   * 0.1.145) — what `$actions` and `GET /meta/actions/:id` list from. The
+   * default keeps the names present in the per-request `/meta` envelope
+   * (`applyMetaOverlay` over the cached one), or all of them when
+   * `applyMetaOverlay` is not overridden (no call). Override it to answer
+   * from per-action permission checks without building the whole `/meta`
+   * overlay on every `$actions` read. Runs after {@link prepareRequest}.
+   * Names it returns that are not in `names` are ignored.
+   *
+   * @since 0.1.145
+   */
+  protected allowedActions(names: readonly string[]): readonly string[] | Promise<readonly string[]>;
+  /**
+   * The rows the row-level action `actionName` may run on (since 0.1.145),
+   * as an extra row filter; `undefined` or `{}` = no restriction (the
+   * default). Enforced by the action gate — ANDed with the {@link rowOverlay}
+   * the action's ids / rows are loaded under, so an id outside it gets the
+   * same 404 "Row not found for action identifier" as a missing one — and
+   * reflected in `$actions` and `GET /meta/actions`, which list the action
+   * only on rows inside it.
+   *
+   * Runs after {@link prepareRequest}, once per action per request. `$actions`
+   * checks the page's rows with one id-only query per distinct filter
+   * OBJECT (return the same object for several actions to share one query),
+   * straight against the bound readable: the filter may use fields
+   * {@link hasField} hides, and nothing of it reaches the response. Not
+   * overriding it costs nothing.
+   *
+   * ```ts
+   * protected actionRowScope(action: string) {
+   *   return action === "approve" ? { ownerId: currentUserId() } : undefined
+   * }
+   * ```
+   *
+   * @since 0.1.145
+   */
+  protected actionRowScope(_actionName: string): FilterExpr | undefined | Promise<FilterExpr | undefined>;
   /**
    * Transform projection before querying.
    * May return a Promise for async lookups.
@@ -810,7 +864,7 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private _widenQuantityMapProjection;
   /** 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. */
+  /** Row/rows envelopes narrowed to {@link allowedActions}; no hook call when neither it nor `applyMetaOverlay` is overridden. */
   private _resolveAugmentEnvelopes;
   /**
    * Returns a widened `$select` only when at least one `requiredFields` entry
@@ -820,6 +874,32 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    */
   private _widenSelectForActions;
   private _prepareAugmentation;
+  /**
+   * {@link actionRowScope} of every offered action (in parallel, alongside
+   * `overlay`), grouped by filter object; each group's filter is composed
+   * with the row overlay exactly as the gate composes it.
+   */
+  private _resolveActionScopeGroups;
+  /** Per scoped action, a per-row mask of rows outside its scope (one id-only read per group). */
+  private _outOfScopeMasks;
+  /**
+   * The row filter {@link actionRowScope} returns for `action` — `undefined`
+   * when empty or when the hook is not overridden (no call). THE per-action
+   * scope rule: the action gate, `$actions` and `/meta/actions` all read it here.
+   */
+  private _actionScope;
+  /**
+   * The fields `envelope`'s gate loads ({@link actionRowFields} under this
+   * request's field visibility) — memoized unless visibility is request-scoped.
+   */
+  private _gateFields;
+  /**
+   * @internal The action gate's overlay (reached by the `@DbAction`
+   * interceptor through {@link ACTION_OVERLAY}): {@link rowOverlay} AND the
+   * action's {@link actionRowScope} (since 0.1.145) — `undefined` when both
+   * are empty.
+   */
+  [ACTION_OVERLAY](action: string | undefined): Promise<FilterExpr | undefined>;
   /**
    * `@db.column.searchable` paths, minus anything the adapter can't filter
    * (JSON storage, encrypted), `@db.writeOnly` fields and navigation
@@ -894,11 +974,14 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   protected decorateRows?(rows: Record<string, unknown>[], ctx: TDbDecorateContext): void | Promise<void>;
   /**
    * Finishes a read's top-level rows in place: `$actions` augmentation (when
-   * the request asked for it — `prep`), then {@link decorateRows} when a
+   * the request asked for it — `prep`; minus actions whose
+   * {@link actionRowScope} a row misses), then {@link decorateRows} when a
    * subclass implements it. Returns the hook's result — `undefined`, with no
    * promise or microtask, when there is no hook or it is synchronous.
    */
   private _finishRows;
+  /** `$actions` augmentation (when `prep`), then {@link decorateRows} when implemented. */
+  private _augmentAndDecorate;
   /**
    * Shared `query` / `pages` / `geo` pipeline: prepare actions augmentation + read
    * strategy in parallel, pre-widen $select for `requiredFields`, run
@@ -993,6 +1076,29 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * driver there), the sealed projection, the row read and its augmentation.
    */
   private _readOne;
+  /**
+   * **GET /meta/actions/:id** — the row-level actions the caller may run on
+   * the row `id` addresses (the `/one/:id` id forms), as
+   * `{ actions, disabledReasons? }` — no row data (since 0.1.145). Exactly
+   * what calling each action would do: the action survives
+   * {@link applyMetaOverlay}, the row resolves under its gate overlay
+   * ({@link actionOverlay}) and its `disabled` rule passes on the fields the
+   * gate loads. Needs no read grant; an unknown or out-of-scope id answers
+   * `{ actions: [] }`. {@link prepareRequest} runs first with
+   * `endpoint: "availableActions"`.
+   */
+  availableActionsById(id: string): Promise<TDbAvailableActions>;
+  /**
+   * **GET /meta/actions?field1=val1&…** — {@link availableActionsById} by
+   * composite key (composite primary key or compound unique index), the
+   * `/one?…` rules.
+   */
+  availableActions(query: Record<string, string>): Promise<TDbAvailableActions | HttpError>;
+  /**
+   * The row resolves ONCE, like `/one/:id` under {@link rowOverlay}; scoped
+   * actions are then checked on it exactly like `$actions` rows.
+   */
+  private _availableActions;
   /**
    * **GET /meta** — returns table/view metadata for UI.
    *
@@ -1610,6 +1716,7 @@ declare module "moost" {
     atscript_db_action_param?: TDbActionParamKind;
     atscript_db_action_row?: TDbActionRowMarker;
     atscript_db_action_rows?: TDbActionRowMarker;
+    atscript_db_endpoint?: TDbRequestEndpoint;
   }
   interface TMoostParamsMetadata {
     atscript_db_action_param?: TDbActionParamKind;
@@ -1662,6 +1769,12 @@ interface AtscriptDbMeta {
   atscript_db_action_rows?: true;
   /** Class-level — written by `@TableController` / `@ReadableController` / `@ViewController`. */
   atscript_db_readable_binding?: TReadableBindingMeta;
+  /**
+   * Method-level — the `prepareRequest` endpoint a framework handler
+   * delegates its authorization to (since 0.1.145). Read it with
+   * {@link getDbEndpoint}.
+   */
+  atscript_db_endpoint?: TDbRequestEndpoint;
 }
 /**
  * Param-level metadata written by `@atscript/moost-db`'s param
@@ -1883,6 +1996,23 @@ interface TAssertExposedOptions {
  */
 declare function assertExposed(app: Moost, models: readonly TAtscriptAnnotatedType[], options?: TAssertExposedOptions): TAtscriptAnnotatedType[];
 //#endregion
+//#region src/db-endpoint.d.ts
+/**
+ * The `prepareRequest` endpoint a controller handler delegates its
+ * authorization to (since 0.1.145) — `undefined` for a handler that is
+ * authorized on its own like any other route. `target` is the controller
+ * instance or class; the tag is inherited through the class chain (a
+ * subclass override of a tagged handler keeps it). Today only
+ * `GET /meta/actions/:id` and `/meta/actions?…` are tagged
+ * (`"availableActions"`).
+ *
+ * ```ts
+ * const endpoint = getDbEndpoint(controller, methodName);
+ * if (endpoint) return; // prepareRequest({ endpoint }) authorizes this call
+ * ```
+ */
+declare function getDbEndpoint(target: object, method: string | symbol): TDbRequestEndpoint | undefined;
+//#endregion
 //#region src/http-errors.d.ts
 /** One entry of the structured error envelope's `errors` array. */
 interface THttpErrorEntry {
@@ -2096,6 +2226,7 @@ declare function InputForm<T extends TAtscriptAnnotatedType & {
  * so the augmenter can invoke the live `disabled` reference (deliberately
  * absent from the wire `info`).
  */
+/** A discovered action: its `/meta.actions[]` entry plus the server-internal opts it was declared with. */
 interface TDbActionEnvelope {
   info: TDbActionInfo$1;
   raw: DbActionOpts | TDbActionsEntry;
@@ -2104,6 +2235,12 @@ interface TDbActionEnvelope {
 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[];
+/**
+ * The `'row'` / `'rows'`-level subset of {@link discoverActions} (since
+ * 0.1.145 public) — the actions `$actions` and `GET /meta/actions/:id`
+ * consider, in `/meta.actions` order. Memoized per controller class.
+ */
+declare function discoverRowLevelActions(controllerCtor: Function, app: Moost, logger: TConsoleBase): TDbActionEnvelope[];
 //#endregion
 //#region src/actions/id-cache.d.ts
 declare const useDbActionId: import("@wooksjs/event-core").WookComposable<{
@@ -2292,4 +2429,4 @@ declare function resolveTerminalRef(def: TAtscriptAnnotatedType): TTerminalRef |
  */
 declare function applyTerminalRefs(serialized: TSerializedAnnotatedType, runtime: TAtscriptAnnotatedType, options: TSerializeOptions): TSerializedAnnotatedType;
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DB_CRUD_HANDLERS, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionDisabledVerdict, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbClassActionMeta, TDbControlsType, TDbDecorateContext, TDbDecorateEndpoint, TDbFieldVisibility, TDbIndexFieldPaths, TDbParsedRequest, type TDbRemoveGuardContext, TDbRequestContext, TDbRequestEndpoint, type TDbWriteAction, type TDbWriteCheckContext, type TDbWriteGuardContext, type TFieldCapability, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ValueHelpQuery, ValueHelpSelect, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };
+export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DB_CRUD_HANDLERS, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionDisabledVerdict, type TDbActionEnvelope, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbClassActionMeta, TDbControlsType, TDbDecorateContext, TDbDecorateEndpoint, TDbFieldVisibility, TDbIndexFieldPaths, TDbParsedRequest, type TDbRemoveGuardContext, TDbRequestContext, TDbRequestEndpoint, type TDbWriteAction, type TDbWriteCheckContext, type TDbWriteGuardContext, type TFieldCapability, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ValueHelpQuery, ValueHelpSelect, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, discoverRowLevelActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, getDbEndpoint, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };