@atscript/moost-db 0.1.146 → 0.1.148

package/dist/index.d.mts

@@ -1,9 +1,11 @@
-import { i as resolveDbSpace, n as clearDbSpaces, r as provideDbSpace, t as DEFAULT_DB_SPACE } from "./db-space-registry-CKR6G-hi.mjs";
+import { a as resolveDbSpace, i as provideDbSpace, n as clearDbSpaces, r as closeDbSpaces, t as DEFAULT_DB_SPACE } from "./db-space-registry-Cvd8s9ql.mjs";
 import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, TSerializedAnnotatedType, TValidatorOptions, Validator } from "@atscript/typescript/utils";
-import { HttpError } from "@moostjs/event-http";
+import { HttpError, MoostHttp } 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, 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 { 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, TDbActionTargetSummary, TDbActionTargetSummary as TDbActionTargetSummary$1, TDbAvailableActions, TDbAvailableActions as TDbAvailableActions$1, 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 { EventContext } from "@wooksjs/event-core";
+
 //#region src/as-readable.controller.d.ts
 /**
  * Endpoint a {@link AsReadableController.prepareRequest} call serves. `/one`
@@ -12,11 +14,14 @@ import { AggregateFn, AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExp
  * like DB readables do; every `@DbAction` handler (row, rows and table
  * level) reports `"action"` with the action's name in
  * {@link TDbRequestContext.action}; `GET /meta/actions/:id` and
- * `/meta/actions?…` report `"availableActions"` (since 0.1.145).
+ * `/meta/actions?…` report `"availableActions"` (since 0.1.145); a view's
+ * `POST /delegated-actions/:name` (a query target for a `@DbActionsFrom`
+ * action — a read of THIS controller's rows) reports `"delegatedAction"` with
+ * the action's name in {@link TDbRequestContext.action} (since 0.1.147).
  *
  * @since 0.1.143
  */
-type TDbRequestEndpoint = "query" | "pages" | "geo" | "one" | "meta" | "metaForm" | "insert" | "replace" | "update" | "remove" | "action" | "availableActions";
+type TDbRequestEndpoint = "query" | "pages" | "geo" | "one" | "meta" | "metaForm" | "insert" | "replace" | "update" | "remove" | "action" | "availableActions" | "delegatedAction";
 /**
  * Context passed to {@link AsReadableController.prepareRequest}.
  *
@@ -32,8 +37,38 @@ interface TDbRequestContext {
    * `metaForm`, writes and actions.
    */
   readonly controls?: Record<string, unknown>;
-  /** `"action"` endpoint only: the `@DbAction` name being run. */
+  /**
+   * The parsed CLIENT filter of `query`, `pages` and `geo` (absent when the
+   * URL carries none, and on every other endpoint) — e.g. for a permission
+   * layer to resolve which relations the request's relational predicates
+   * (`ticket=$some(…)`) touch, alongside `controls.$with`. A deep-frozen
+   * COPY of the parsed filter — reading it is all a hook can do; the request
+   * gate judges the original. Server-side filters (`transformFilter`, …) are
+   * not in it.
+   *
+   * @since 0.1.147
+   */
+  readonly filter?: FilterExpr;
+  /**
+   * Read endpoints (`query`, `pages`, `geo`, `one`): whether {@link filter} holds a relational
+   * predicate (`ticket=$some(…)`) — `false` without a filter. Reading
+   * `filter` copies the whole filter on first access; check this first when
+   * only the predicates matter. `$with` sub-filters are not counted (they are
+   * in `controls.$with`).
+   *
+   * @since 0.1.147
+   */
+  readonly hasRelationFilters?: boolean;
+  /** `"action"` / `"delegatedAction"` endpoints only: the `@DbAction` name being run. */
   readonly action?: string;
+  /**
+   * `"insert"` endpoint only: the `?$onConflict=` mode the request carries
+   * (`"ignore"`); absent for a plain insert. A controller can refuse it by
+   * throwing from `prepareRequest`.
+   *
+   * @since 0.1.148
+   */
+  readonly onConflict?: "ignore";
 }
 /** Control DTO a {@link AsReadableController.validateControls} call checks against. @since 0.1.143 (`"geo"`) */
 type TDbControlsType = "query" | "pages" | "getOne" | "geo";
@@ -183,8 +218,8 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   protected prepareRequest?(ctx: TDbRequestContext): void | Promise<void>;
   /**
    * The ONE request entry of every built-in route: with a `url` (read
-   * endpoints) it parses the query string — `/one` keeps only the `$`
-   * controls ({@link parseControlsOnlyFromUrl}), every other endpoint the
+   * endpoints, and `POST /`) it parses the query string — `/one` and `POST /`
+   * keep only the `$` controls ({@link parseControlsOnlyFromUrl}), every other endpoint the
    * whole query ({@link parseQueryString}) — and coerces boolean controls the
    * URL grammar leaves as strings (`$actions=true`); then it awaits
    * {@link prepareRequest} (when implemented) with the parsed controls.
@@ -321,14 +356,404 @@ interface IdValidationSource {
   readonly fieldDescriptors: readonly TDbFieldMeta[];
 }
 //#endregion
+//#region src/actions/query-target.d.ts
+/**
+ * A query target — the `query` of an action request body: "every row
+ * matching this query" instead of a list of identifiers (since 0.1.147).
+ *
+ * @since 0.1.147
+ */
+interface TDbActionQueryTarget {
+  /** The query string `GET /query` accepts — filter plus `$search` / `$index` ONLY. */
+  q: string;
+  /** Identifiers to leave out (any identification; at most the action's `maxIds`). */
+  exclude?: Record<string, unknown>[];
+  /** Guard: the request fails with 409 `TARGET_CHANGED` when the match count differs. */
+  expectCount?: number;
+  /** Client-side cap (it never raises the server's `maxRows`). */
+  maxRows?: number;
+  /** Resolve and count only — the reply is `{ matched }`, the handler does not run. */
+  dryRun?: boolean;
+}
+/** `queryTarget` of `@DbAction` options. `true` = the defaults. @since 0.1.147 */
+type TDbQueryTargetOpts = boolean | {
+  maxRows?: number;
+  batchSize?: number;
+};
+/**
+ * Key of `AsDbReadableController`'s internal query-target resolver (a
+ * registered symbol, like `ACTION_OVERLAY`).
+ */
+declare const RESOLVE_TARGET: unique symbol;
+/** What {@link RESOLVE_TARGET} resolves. */
+interface TTargetRequest {
+  action: string;
+  /** The raw `query` of the request body — validated by the resolver. */
+  query: unknown;
+  /** The most rows the target may match (server side). */
+  cap: number;
+  /** The most `exclude` entries. */
+  maxExclude: number;
+  /**
+   * The row overlay the target resolves under, besides `queryTargetScope`:
+   * `"action"` — the controller's `rowOverlay()` (its own action runs on the
+   * rows); `"read"` — `transformFilter` (a view resolving rows it delegates).
+   */
+  overlay: "action" | "read";
+  /** Fields of the phase-1 read (sorted by the first identification's fields). */
+  select: readonly string[];
+  /** Key sets `exclude` entries may use besides the controller's identifications. */
+  excludeShapes?: readonly (readonly string[])[];
+}
+/** A resolved query target: the phase-1 snapshot plus its re-check. */
+interface TResolvedTarget {
+  /** Rows matched at phase 1 (after `exclude`). */
+  matched: number;
+  /** The phase-1 rows (`select` fields), ordered by identity. */
+  rows: Record<string, unknown>[];
+  dryRun: boolean;
+  /** The validated `exclude` entries (already applied to {@link rows}). */
+  exclude: Record<string, unknown>[];
+  /**
+   * The rows `ids` address that STILL match the target (filter, search,
+   * overlay, `queryTargetScope`, `exclude`), aligned with `ids`; `select`
+   * plus the id fields. The FIRST call directly follows the snapshot and is
+   * not re-checked (served from {@link rows}, or read by identity alone
+   * when `select` needs more fields); every later call re-checks.
+   */
+  load(ids: readonly Record<string, unknown>[], select: Iterable<string>): Promise<Array<Record<string, unknown> | undefined>>;
+}
+//#endregion
+//#region src/actions/types.d.ts
+/**
+ * One entry of a `disabled` predicate's result. Truthy = the action is
+ * disabled for that row; falsy (`false`, `""`) = enabled. A non-empty string
+ * disables the action AND carries a human-readable reason — surfaced in the
+ * 409 `ActionDisabledError` message/body and in the row's `$disabledReasons`.
+ *
+ * @since 0.1.141 (`string`)
+ */
+type TDbActionDisabledVerdict = boolean | string;
+/** `'rows'`-level batch policy — controls whether failing rows reject or are filtered out. */
+type TOnDisabledRows = "reject" | "skip";
+/**
+ * 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 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>[]> {
+  /**
+   * 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.
+   */
+  requiredFields: R;
+  /**
+   * Sync batch gate predicate — returns a parallel array aligned with the
+   * input. Per entry: truthy = disabled for the corresponding row; a
+   * non-empty string also gives the reason (see
+   * {@link TDbActionDisabledVerdict}). The `rows`
+   * argument is type-narrowed to `Pick<FlatOf<TRow>, R[number]>[]`; reading
+   * a field not listed in `requiredFields` is a compile error.
+   *
+   * Promise return is NOT permitted — the predicate is consumed in the
+   * same tick by the gate and the augmenter.
+   */
+  disabled?: (rows: DisabledRowsArg<TRow, R>) => TDbActionDisabledVerdict[];
+  /**
+   * `'rows'`-level batch policy. Default `'reject'`.
+   *
+   * - `'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[]) => TDbActionDisabledVerdict[];
+  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" | "formUrl" | "owner" | "idMap" | "queryTarget">> {
+  /**
+   * 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.
+   */
+  table?: AtscriptDbTable<any>;
+  /**
+   * `'rows'` level (`@DbActionIDs` / `@DbActionRows`): the most identifiers
+   * one request may carry. Above it the request is rejected with 400 before
+   * any row is loaded. Default `1000`. Server-internal — never on the wire.
+   *
+   * @since 0.1.143
+   */
+  maxIds?: number;
+  /**
+   * `'rows'` level only: the action also accepts a query target — a body
+   * `{ query: { q, exclude?, expectCount?, maxRows?, dryRun? }, input? }`
+   * meaning "every row matching `q`" (the `GET /query` filter plus
+   * `$search` / `$index`) under the caller's read scope (`queryTargetScope`)
+   * and the action's own gate. `true` = `{ maxRows: 10_000, batchSize:
+   * 500 }`. `maxRows` (on the wire as `queryTarget.maxRows`) caps the
+   * matched rows; a `@DbActionTarget()` handler gets them in `batchSize`
+   * batches, a `@DbActionIDs` / `@DbActionRows` handler at once (then also
+   * capped by `maxIds`).
+   *
+   * @since 0.1.147
+   */
+  queryTarget?: TDbQueryTargetOpts;
+}
+/**
+ * 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;
+  intent?: TDbActionIntent$1;
+  description?: string;
+  order?: number;
+  default?: boolean;
+  /** Mirrors {@link TDbActionInfo.promptText} — singular/plural via tuple. */
+  promptText?: string | [string, string];
+  /** Mirrors {@link TDbActionInfo.shortcut} — single-character UI hint. */
+  shortcut?: string;
+  /**
+   * Input form the UI collects before invoking the action:
+   *
+   * - a compiled `.as` interface — registered on THIS controller and served
+   *   by its own `GET /meta/form/:name`; the wire carries `inputForm: Type.name`.
+   * - `{ name, url }` — a form served elsewhere: `name` goes on the wire as
+   *   `inputForm`, `url` (server-absolute path of the serialized schema, e.g.
+   *   `"/api/shipping/meta/form/ShipForm"`) as {@link TDbActionInfo.formUrl}.
+   *
+   * Not allowed with `processor: 'navigate'`. Class-level entries only
+   * describe the action — validating `input` is the target handler's job
+   * (e.g. its own `@InputForm(Type)` param).
+   *
+   * @since 0.1.136
+   */
+  inputForm?: TAtscriptAnnotatedType | {
+    name: string;
+    url: string;
+  };
+}
+type DbActionsEntryWithGate<TRow, R extends readonly FlatKey<TRow>[]> = DbActionsEntryCommonBase & GateOpts<TRow, R>;
+/**
+ * Class-level dict entry. `value` semantics by processor:
+ *
+ * - `'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<TRow = unknown, R extends readonly FlatKey<TRow>[] = []> = (DbActionsEntryWithGate<TRow, R> & {
+  processor: "navigate";
+  value: string;
+  inputForm?: never;
+}) | (DbActionsEntryWithGate<TRow, R> & {
+  processor: "custom";
+  value?: never;
+}) | (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<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>> };
+/**
+ * An id as an id-addressed endpoint received it: a path scalar (always a
+ * string from the URL) or an identification object (`?field=value` forms,
+ * action bodies).
+ *
+ * @since 0.1.148
+ */
+type TDbRowIdInput = string | number | boolean | Record<string, unknown>;
+/**
+ * Which endpoint asks `resolveRowIds`:
+ *
+ * - `"action"` — an action route: the body's validated ids;
+ * - `"available"` — `GET /meta/actions/:id` | `?…` (and a view asking its source);
+ * - `"one"` — `GET /one/:id` | `?…`;
+ * - `"remove"` — `DELETE /:id` | `?…`.
+ *
+ * @since 0.1.148
+ */
+type TDbRowIdPurpose = "action" | "available" | "one" | "remove";
+/**
+ * Context of `AsDbReadableController.resolveRowIds`.
+ *
+ * @since 0.1.148
+ */
+interface TDbRowIdsContext {
+  readonly purpose: TDbRowIdPurpose;
+  /** `"action"` only: the action's name. */
+  readonly action?: string;
+  /** `"action"` only: the action's level. */
+  readonly level?: "row" | "rows";
+  /**
+   * The row overlay the endpoint will apply to the resolved id
+   * (`rowOverlay()`; for actions the gate's overlay), `undefined` when none.
+   * Server data — never sent to the client. Resolve INSIDE it when an alias
+   * could name several rows, so a row the caller can't reach never shadows
+   * one they can.
+   */
+  readonly overlay?: FilterExpr;
+}
+//#endregion
+//#region src/actions/discover.d.ts
+/**
+ * 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`).
+ */
+/** A discovered action: its `/meta.actions[]` entry plus the server-internal opts it was declared with. */
+interface TDbActionEnvelope {
+  info: TDbActionInfo$1;
+  raw: DbActionOpts | TDbActionsEntry;
+}
+/** Lookup helper for `AsReadableController.metaForm()`. */
+declare function getControllerFormType(ctor: Function, name: string): TAtscriptAnnotatedType | undefined;
+/** Discover actions on a controller, memoized per ctor. `info`-only callers map `e => e.info`. */
+declare function discoverActions(controllerCtor: Function, app: Moost, logger: TConsoleBase): TDbActionEnvelope[];
+/**
+ * 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/delegation.d.ts
+/** Internal: a source controller's batch `$actions` verdicts for delegated ids. */
+declare const ACTION_VERDICTS: unique symbol;
+/** Internal: a source controller's `GET /meta/actions/:id` answer for one id. */
+declare const AVAILABLE_ACTIONS: unique symbol;
+/** Internal: the subset of delegated action names a source controller lists for the caller. */
+declare const ALLOWED_ACTIONS: unique symbol;
+/** `true` when the controller class declares `@DbActionsFrom` (inherited included). */
+declare function hasActionDelegations(ctor: Function): boolean;
+//#endregion
+//#region src/actions/rows-by-id.d.ts
+/** One id the client sent, with the {@link identityKey} of the id it resolved to. */
+interface TRequestedId {
+  id: Record<string, unknown>;
+  key: string;
+}
+/**
+ * The result of a `resolveRowIds` call over an action's ids: the resolved
+ * ids with duplicate identities collapsed to the first (what handlers and
+ * the row load see) and — only when an id changed or collapsed — EVERY
+ * request id in request order (`requests`), the single model all refusals,
+ * reasons, summaries and counts are judged and reported in.
+ */
+interface TAppliedIds {
+  ids: Record<string, unknown>[];
+  requests?: readonly TRequestedId[];
+}
+//#endregion
+//#region src/actions/scope-context.d.ts
+/**
+ * Which surface asks {@link TDbActionScopeContext} — see
+ * `AsDbReadableController.actionRowScope`:
+ *
+ * - `"execute"` — the action gate, about to run the action on `ids`;
+ * - `"rows"` — `$actions` on a read (also a view's delegated verdicts);
+ * - `"available"` — `GET /meta/actions/:id` (one row).
+ *
+ * @since 0.1.147
+ */
+type TDbActionScopePurpose = "execute" | "rows" | "available";
+/**
+ * The candidate rows `AsDbReadableController.actionRowScope` is asked about
+ * (since 0.1.147). Every candidate is inside the controller's row overlay;
+ * the hook's result restricts them further.
+ *
+ * Exception (since 0.1.148): at `purpose: "execute"` with NO row overlay, the
+ * hook is asked BEFORE the rows are loaded when the request's ids are in
+ * `preferredId` shape — `ids` are then the request's (resolved) ids, deduped,
+ * and may name rows that do not exist (`loadRows` omits them). A restriction
+ * it returns joins the single row load (`id ∧ scope`); an answer of
+ * `undefined` / `null` / `{}` makes the gate load nothing.
+ *
+ * @since 0.1.147
+ */
+interface TDbActionScopeContext {
+  /**
+   * Which surface asks: `"execute"` — the action gate (≤ `maxIds` ids; one
+   * batch of a query target); `"rows"` — `$actions` on a read (also a view's
+   * delegated verdicts), the read's rows; `"available"` — `GET /meta/actions/:id`,
+   * the one row.
+   */
+  readonly purpose: TDbActionScopePurpose;
+  /**
+   * The candidates' identities (`preferredId`-shaped), deduped and never
+   * empty — at `"execute"` without a row overlay, the request's ids (they may
+   * not exist; see above). ONE array object per evaluation, shared by every action of it —
+   * memoize on it (`WeakMap`) when several actions derive the same filter.
+   */
+  readonly ids: readonly Record<string, unknown>[];
+  /**
+   * The candidates' `fields` (plus the identity fields), read straight from
+   * the bound readable without any overlay (the candidates already passed
+   * it). Memoized per evaluation and field set. Nothing of it reaches the
+   * response.
+   */
+  loadRows(fields: readonly string[]): Promise<readonly Record<string, unknown>[]>;
+}
+//#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).
+ * its `rowOverlay()` (since 0.1.147 without the action's `actionRowScope`,
+ * which needs the candidate rows — see {@link ACTION_SCOPE}). 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;
+/** The controller's internal `actionRowScope` call for candidate rows (since 0.1.147). */
+declare const ACTION_SCOPE: unique symbol;
+/** `true` when the controller overrides `actionRowScope` (since 0.1.147). */
+declare const ACTION_SCOPED: unique symbol;
+/** The controller's internal `resolveRowIds` call for an action's ids (since 0.1.148). */
+declare const ROW_RESOLVE_IDS: unique symbol;
+/** `true` when the controller overrides `resolveRowIds` (since 0.1.148). */
+declare const ROW_RESOLVES: unique symbol;
 //#endregion
 //#region src/meta/field-capabilities.d.ts
 /**
@@ -370,16 +795,37 @@ interface TFieldCapability {
    * `bucketSourceVerdict`). Since 0.1.132.
    */
   bucketable: boolean;
+  /**
+   * `$groupBy` on this path passes the gate: physically filterable (adapter ∧
+   * ¬writeOnly ∧ ¬encrypted) and, on a table declaring dimensions / measures,
+   * a dimension. Since 0.1.148.
+   */
+  groupable: boolean;
+  /** Present when `groupable` is `false` — the reason clause appended to the HTTP 400 message. */
+  groupReason?: string;
   /** Present when `bucketable` is `false` — the reason clause appended to the HTTP 400 message. */
   bucketReason?: string;
+  /**
+   * The path may be an operand of query-time arithmetic: a numeric field
+   * ({@link numericOperandProblem}) that aggregates (`$groupBy` / aggregate
+   * capability, ¬writeOnly, visible). Only on an adapter with
+   * `supportsAggregateExpressions()`. Since 0.1.148.
+   */
+  numeric: boolean;
 }
 /** One rejected path: `path` is the offending logical path, `message` the full sentence. */
 interface TCapabilityVerdict {
   path: string;
   message: string;
 }
+/**
+ * The positions {@link FieldCapabilityIndex.check} judges: the core's path
+ * positions plus the `$select` of an aggregate query (`groupedSelect`), where
+ * a plain field must be a `$groupBy` key — a display-only decoration never is.
+ */
+type TGateOp = TQueryPathOp$1 | "groupedSelect";
 /** The readable members the index reads. */
-type TCapabilityReadable = Pick<AtscriptDbReadable, "type" | "fieldDescriptors" | "flatMap" | "navFields" | "relations" | "ignoredFields" | "canFilterField" | "canSortField" | "isGeoSearchable" | "calendarBucketUnits" | "aggregateFns" | "dimensions" | "measures">;
+type TCapabilityReadable = Pick<AtscriptDbReadable, "type" | "fieldDescriptors" | "flatMap" | "navFields" | "relations" | "ignoredFields" | "canFilterField" | "canSortField" | "isGeoSearchable" | "calendarBucketUnits" | "aggregateFns" | "supportsAggregateExpressions" | "dimensions" | "measures">;
 /**
  * Capability index of one readable.
  *
@@ -413,6 +859,8 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   readonly bucketUnits: readonly BucketUnit[];
   /** Aggregate functions the adapter renders, in canonical `ALL_AGGREGATE_FNS` order (`/meta.aggregateFns`). */
   readonly aggregateFns: readonly AggregateFn[];
+  /** Whether the adapter renders aggregate arithmetic (`/meta.aggregateExpressions`). */
+  readonly aggregateExpressions: boolean;
   /** The adapter-level capabilities this index was built against — see {@link adapterSignature}. */
   readonly signature: string;
   /**
@@ -421,8 +869,19 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
    * {@link signature} differs from this is stale. Any new adapter-level input
    * the index reads must be added here.
    */
-  static adapterSignature(source: Pick<TCapabilityReadable, "isGeoSearchable" | "calendarBucketUnits" | "aggregateFns">): string;
+  static adapterSignature(source: Pick<TCapabilityReadable, "isGeoSearchable" | "calendarBucketUnits" | "aggregateFns" | "supportsAggregateExpressions">): string;
+  /**
+   * The navigation paths of a readable: its `navFields`, else its relation
+   * names (partial readables list only the latter).
+   */
+  static navPathsOf(source: Pick<TCapabilityReadable, "navFields" | "relations">): Set<string>;
   private readonly _entries;
+  /**
+   * Declared display-only decorations (`@DbDecorations`, since 0.1.148) —
+   * virtual entries: key → the readable paths it `requires`. Selectable only;
+   * visible while every required path is.
+   */
+  private readonly _decorations;
   /** Nested-object parents (never listed, always selectable) → their listed leaves. */
   private readonly _objectParents;
   /** What `bucketSourceVerdict` reads of the table (JSON-value parents, dimensions, measures). */
@@ -431,10 +890,16 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   get leaves(): ReadonlyMap<string, unknown>;
   /** Nested-object parents — the {@link TQueryPathSource} view for `classifyQueryPath`. */
   get objectParents(): ReadonlyMap<string, unknown>;
-  constructor(source: TCapabilityReadable, writeOnly: ReadonlySet<string>);
+  constructor(source: TCapabilityReadable, writeOnly: ReadonlySet<string>, decorations?: ReadonlyMap<string, readonly string[]>);
   private _buildEntry;
   /** Listed leaves in descriptor order — the `/meta.fields` projection source. */
   entries(): IterableIterator<[path: string, cap: TFieldCapability, fd: TDbFieldMeta]>;
+  /** The declared decoration keys, in declaration order. */
+  get decorationKeys(): IterableIterator<string>;
+  /** The capability of the declared decoration `key` (selectable only), `undefined` when `key` is none. */
+  decorationCap(key: string): Readonly<TFieldCapability> | undefined;
+  /** The decoration `key` is visible: every path it `requires` passes `exists` (the hidden-field hook). */
+  decorationVisible(key: string, exists: (path: string) => boolean): boolean;
   /** Physical filter capability (adapter ∧ ¬writeOnly ∧ ¬encrypted) — ignores the manual-mode policy. */
   isPhysicallyFilterable(path: string): boolean;
   /**
@@ -457,10 +922,21 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
    * JSON-stored column" — clients pin that wording, so do not "align" it
    * with the core backstop's text.
    *
+   * A declared decoration (`@DbDecorations`) is a virtual entry: `select` while
+   * every path it requires passes `exists`, any other position a display-only
+   * refusal (`groupedSelect` is a `$select` of an aggregate query), and hidden
+   * sources answer `Unknown field` like a nonexistent path.
+   *
    * `predicate` is a filter entry's class (`collectQueryPaths` records it per
    * occurrence); it only matters for `op === "filter"` on a listed leaf.
+   *
+   * `prefix` (since 0.1.147) is this index's readable's dotted path from the
+   * controller when it judges a relational predicate's operand (`"ticket."`):
+   * `exists` still receives the LOCAL path, the verdict's `path` and message
+   * name the prefixed one. A filter on a navigation path names the predicate
+   * alternative (`ticket=$some(status=…)`).
    */
-  check(path: string, op: TQueryPathOp$1, exists: (path: string) => boolean, predicate?: TFilterPredicate): TCapabilityVerdict | undefined;
+  check(local: string, gateOp: TGateOp, exists: (path: string) => boolean, predicate?: TFilterPredicate, prefix?: string): TCapabilityVerdict | undefined;
 }
 //#endregion
 //#region src/as-db-readable.controller.d.ts
@@ -483,6 +959,15 @@ interface TDbDecorateContext {
   projection: UniqueryControls["$select"] | undefined;
   /** The request's parsed controls (`$select`, `$with`, `$actions`, …). Read-only by convention. */
   controls: Record<string, unknown>;
+  /**
+   * The declared decoration keys ([`@DbDecorations`](./decorations/db-decorations.decorator.ts))
+   * this response must carry — the ones the client asked for (all of them
+   * without a `$select`) whose sources are visible and kept by
+   * `transformProjection`. Compute only these; a declared key not listed is
+   * removed from the rows after the hook. Empty when none is declared.
+   * Undeclared (`$`-prefixed) keys are not affected. Since 0.1.148.
+   */
+  decorations: ReadonlySet<string>;
 }
 /**
  * One text / vector / geo index of the bound readable with the LOGICAL field
@@ -515,13 +1000,15 @@ interface TDbFieldVisibility {
   /**
    * `hasField(path)` and — when {@link scoped} — a `@db.column.derived`
    * field of the bound readable only while its source path is visible too
-   * (a derived copy must not outlive a hidden source).
+   * (a derived copy must not outlive a hidden source), a computed view
+   * column (`@db.compute`, since 0.1.147) only while every operand and every
+   * intermediate computed field it reads through is.
    */
   readonly isVisible: (path: string) => boolean;
   /**
    * The paths sealed out of `readable`'s read projection for this request:
    * its `@db.writeOnly` fields plus, when {@link scoped}, its derived fields
-   * whose source `hasField` hides. `prefix` is `readable`'s path from the
+   * whose source `hasField` hides and its computed fields with a hidden operand. `prefix` is `readable`'s path from the
    * controller: `""` for the bound readable, `"rel."` for a `$with` target.
    */
   readonly sealedFor: (readable: AtscriptDbReadable<any>, prefix?: string) => ReadonlySet<string>;
@@ -559,6 +1046,14 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    */
   protected get capabilities(): FieldCapabilityIndex;
   private _capabilities?;
+  /** The client relational-predicate gate (since 0.1.147), built on first use — see {@link _relationGate}. */
+  private _relGate?;
+  /**
+   * The client's `$with` tree per request, keyed by its controls object —
+   * recorded in {@link validateParsed} before {@link validateControls} (see
+   * `snapshotClientWith`).
+   */
+  private readonly _clientWith;
   /** `/meta` is a projection of {@link capabilities}: a rebuilt index rebuilds the cached envelope. */
   protected metaCacheKey(): unknown;
   /**
@@ -571,12 +1066,18 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   protected readonly fieldVisibility: TDbFieldVisibility;
   /** A subclass overrides {@link hasField}: visibility is request-scoped (derived rule, index gate, id options). */
   private readonly _hasFieldOverridden;
-  /** `@db.column.derived` path → its source's logical path, per readable (bound + `$with` targets). */
+  /**
+   * `@db.column.derived` path → its source's logical path, `@db.compute` path
+   * → its operands' paths plus the computed fields it reads through, per
+   * readable (bound + `$with` targets).
+   */
   private readonly _derivedSources;
   /** The bound readable's entry of {@link _derivedSources}. */
   private readonly _derivedSource;
   /** `@db.writeOnly` paths of `$with` target readables, collected once per target. */
   private readonly _targetWriteOnly;
+  /** Own leaf paths per readable (bound + `$with` targets), see {@link _leavesOf}. */
+  private readonly _targetLeaves;
   private _indexFieldPathsCache?;
   /** {@link _nativeSearch} per request, keyed by the request's parsed controls. */
   private readonly _nativeSearchByRequest;
@@ -600,8 +1101,18 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private readonly _gateFieldsMemo;
   /** `true` when a subclass overrides {@link allowedActions}. */
   private readonly _hasAllowedActions;
+  /** The class's validated `@DbDecorations` (since 0.1.148), `undefined` when none is declared. */
+  private readonly _decorations;
+  /** The decoration plumbing of {@link _decorations} — see `DecorationPlanner`. */
+  private readonly _planner;
   /** `true` when a subclass overrides {@link actionRowScope} (the gate, `$actions` and `/meta/actions` apply it). */
   private readonly _hasActionRowScope;
+  /** @internal `true` when a subclass overrides {@link resolveRowIds} (every id-addressed endpoint calls it; since 0.1.148). */
+  readonly [ROW_RESOLVES]: boolean;
+  /** `true` when the class declares `@DbActionsFrom` (since 0.1.147). */
+  private readonly _hasDelegations;
+  /** `transformProjection` is overridden (a delegation's id paths are checked against it). */
+  private readonly _hasProjectionHook;
   /** 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. */
@@ -615,6 +1126,12 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    */
   private readonly _invertibleFields;
   constructor(app: Moost, readable?: AtscriptDbReadable<T>);
+  /**
+   * The class's `@DbDecorations`, validated against the bound readable once
+   * per class and readable (a `[moost-db]` error when invalid); warns once
+   * when `decorateRows` is not implemented.
+   */
+  private _resolveDecorations;
   /**
    * The identifications this request may address rows through (since
    * 0.1.134): the readable's own, minus unique indexes over fields
@@ -624,9 +1141,11 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   get idSource(): IdValidationSource;
   private _collectInvertibleFields;
   private _collectQuantityRefs;
-  /** `readable`'s `@db.column.derived` path → source path map, collected once per readable. */
+  /**
+   * `readable`'s `@db.column.derived` path → source path and `@db.compute`
+   * path → operand paths map, collected once per readable.
+   */
   private _derivedSourcesOf;
-  private _collectAnnotated;
   /**
    * THE field-visibility hook: every gated path consults it before any
    * capability check (since 0.1.133) — filter keys (inside `$and` / `$or` /
@@ -652,7 +1171,9 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * visible fields (or ignores the term when there are none). A
    * `@db.column.derived` field is visible only while its source path is,
    * and one whose source is hidden is sealed out of every read projection
-   * for the request, like a `@db.writeOnly` field.
+   * for the request, like a `@db.writeOnly` field. The same holds for a
+   * computed view column (`@db.compute`) and each of its operands, including
+   * the intermediate computed fields it reads through.
    */
   protected hasField(path: string): boolean;
   /**
@@ -723,8 +1244,6 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private _writeOnlyOf;
   /** {@link TDbFieldVisibility.sealedFor}. */
   private _sealedFor;
-  /** The readable a `$with` entry name (`rel` or dotted `rel.sub`) loads from, if resolvable. */
-  private _relTarget;
   /**
    * Walks a `$with` tree pre-order: `visit(rel, target, path, controls)` for
    * every entry whose target readable resolves (`path` = the entry's dotted
@@ -782,6 +1301,15 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * nonexistent index (the core's wording).
    */
   private _checkIndexGate;
+  /**
+   * `/meta`'s search surface as THIS request may use it (only when
+   * {@link hasField} is overridden — the rule of the index gate): indexes
+   * reading a hidden field are left out of `searchIndexes`; `searchable` /
+   * `vectorSearchable` / `geoSearchable` turn off when the index a request
+   * naming none would use reads one (`searchable` stays on for the
+   * `@db.column.searchable` fallback when any of its fields is visible).
+   */
+  private _applyIndexVisibility;
   /**
    * Compute an embedding vector from a search term.
    * Override in subclass to integrate with your embedding provider (OpenAI, etc.).
@@ -800,6 +1328,42 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * `findById`). Override to scope `/one` differently.
    */
   protected transformOne(filter: FilterExpr): FilterExpr | Promise<FilterExpr>;
+  /**
+   * Rewrites the sub-filter of a CLIENT relational predicate before it runs
+   * — the row overlay of the related table (since 0.1.147). `path` is the
+   * dotted navigation chain from this controller's table: `"ticket"` for
+   * `ticket=$some(…)`, `"ticket.team"` for a predicate nested in its
+   * operand, `"tickets.issues"` for `$with=tickets(issues=$some(…))`.
+   * Default identity.
+   *
+   * Applied to client predicates only (the URL filter and `$with`
+   * sub-filters, on `/query` incl. `$groupBy` and `$count`, `/pages`, `/geo`
+   * and `/one`, and a query target's filter), after the request gate and before {@link transformFilter};
+   * a nested predicate's operand is rewritten before the operand holding it,
+   * and the hook's output is not walked again. Server-side filters
+   * ({@link transformFilter}, {@link transformOne}, {@link actionRowScope})
+   * never pass through it. Return the operand conjoined with the related
+   * rows the caller may see — `$some` then only matches, and `$none` only
+   * excludes, on VISIBLE related rows, exactly as `$with` shows them:
+   *
+   * ```ts
+   * protected transformRelationFilter(path: string, filter: FilterExpr) {
+   *   return path === "ticket" ? { $and: [{ teamId: { $in: currentTeams() } }, filter] } : filter
+   * }
+   * ```
+   *
+   * @since 0.1.147
+   */
+  protected transformRelationFilter(_path: string, filter: FilterExpr): FilterExpr | Promise<FilterExpr>;
+  /** The client relational-predicate gate (since 0.1.147) — one per controller. */
+  private _relationGate;
+  /**
+   * The client filter with every relational predicate operand rewritten by
+   * {@link transformRelationFilter} — and `parsed.controls.$with` replaced by
+   * its rewritten tree (since 0.1.147). Costs nothing unless the hook is
+   * overridden.
+   */
+  private _relationOverlay;
   /**
    * 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
@@ -816,33 +1380,98 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   /**
    * 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.
+   * default). Enforced by the action gate — the action's ids / rows are
+   * loaded under {@link rowOverlay}, then checked against this filter (or —
+   * without an overlay — the filter joins the load), 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.
+   *
+   * The hook receives the candidate rows (`ctx`), so a scope can depend on
+   * them — what `ctx.purpose`, `ctx.ids` and `ctx.loadRows` hold, and when the
+   * hook is asked before any load, is documented on {@link TDbActionScopeContext}.
+   * Called only with at least one candidate, at most once per action per
+   * evaluation. An answer restricting nothing (`undefined`, `null`, `{}`)
+   * makes the gate load no row at all; a restriction is folded into the one
+   * row load. The result only restricts (`ids ∧ rowOverlay ∧ scope`); a throw
+   * fails the request — never a silent "allow". The filter runs straight
+   * against the bound readable: it may use fields {@link hasField} hides, and
+   * nothing of it reaches the response. Runs after {@link prepareRequest} and,
+   * on the action route, after the request body is read and
+   * {@link resolveRowIds}.
+   *
+   * Not overriding it costs nothing; a one-parameter override keeps working.
+   * moost-db always passes `ctx` — it is optional in the signature only so
+   * `super.actionRowScope(name)` calls in existing overrides keep compiling.
+   *
+   * ```ts
+   * protected async actionRowScope(action: string, ctx: TDbActionScopeContext) {
+   *   if (action !== "resolve") return undefined
+   *   const issues = await ctx.loadRows(["ticketKey"])
+   *   const tickets = await ticketTable.findMany({
+   *     filter: { key: { $in: issues.map((i) => i.ticketKey) }, teamId: currentTeamId() },
+   *     controls: { $select: ["key"] },
+   *   })
+   *   return { ticketKey: { $in: tickets.map((t) => t.key) } }
+   * }
+   * ```
+   *
+   * The scope may use relational predicates (since 0.1.147) — a server-side
+   * filter, so no `@db.rel.filterable` opt-in and no
+   * {@link transformRelationFilter} apply. On an Issue controller:
    *
    * ```ts
    * protected actionRowScope(action: string) {
-   *   return action === "approve" ? { ownerId: currentUserId() } : undefined
+   *   return action === "resolve"
+   *     ? { ticket: { $some: { teamId: { $in: currentTeams() }, status: "open" } } }
+   *     : undefined
    * }
    * ```
    *
    * @since 0.1.145
    */
-  protected actionRowScope(_actionName: string): FilterExpr | undefined | Promise<FilterExpr | undefined>;
+  protected actionRowScope(_actionName: string, _ctx?: TDbActionScopeContext): FilterExpr | undefined | Promise<FilterExpr | undefined>;
+  /**
+   * The read scope a query target (an action request `{ query }`, since
+   * 0.1.147) resolves under, on top of the action's row overlay — so "every
+   * row matching the query" never reaches rows the caller cannot list. A
+   * view resolving a delegated action's query target applies it too.
+   * Default: `transformFilter({})` (the read overlay of `/query`). Throw an
+   * `HttpError` to refuse query targets for the caller (e.g. no read grant).
+   *
+   * Runs as a READ of this controller: it is called in a child of the
+   * action event — of the delegating event for a view resolving a delegated
+   * target — (moost `withControllerContext`, the controller's `query`
+   * handler) after `prepareRequest({ endpoint: "query", controls, filter })`
+   * with the target's own filter and controls — so a permission layer's
+   * per-request state is the READ request's (its read grant, the policy of
+   * the relations its predicates touch), never the action's, and nothing of
+   * it leaks back. The target's query (`q` filter and controls, `exclude`)
+   * is validated in that read context ({@link validateControls},
+   * {@link checkCapabilities}, {@link hasField}), where the client
+   * predicates' {@link transformRelationFilter} also runs: a query target
+   * never filters on, nor counts by, a field the caller can't read.
+   *
+   * @since 0.1.147
+   */
+  protected queryTargetScope(_action: string): FilterExpr | undefined | Promise<FilterExpr | undefined>;
   /**
    * Transform projection before querying.
    * May return a Promise for async lookups.
    */
   protected transformProjection(projection?: UniqueryControls["$select"]): UniqueryControls["$select"] | undefined | Promise<UniqueryControls["$select"] | undefined>;
+  /**
+   * The shared projection step of `/query`, `/pages`, `/geo` and `/one`:
+   * splits the declared decoration keys out of the wire `$select`
+   * ({@link DecorationPlanner.plan}), runs {@link transformProjection} on the
+   * rest (decoration keys never reach it — a permission layer needs no
+   * change; their `requires` paths are added so the hook's inputs are read),
+   * then seals every projection level. `finish` completes it once the
+   * endpoint is past its own checks: the preferred-id widening (an
+   * `HttpError` for a mixed `$select`) and the decoration step — what every
+   * read endpoint then passes to {@link _runReadWithActions}.
+   */
+  private _projectRead;
   private widenPreferredIdProjection;
   private _widenArrayProjection;
   private _widenMapProjection;
@@ -866,6 +1495,13 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private _resolveProjectionForAugmenter;
   /** Row/rows envelopes narrowed to {@link allowedActions}; no hook call when neither it nor `applyMetaOverlay` is overridden. */
   private _resolveAugmentEnvelopes;
+  /**
+   * Once per class: `actionRowScope` is overridden (a permission layer always
+   * does) while the controller's OWN row-level actions can't be scoped — the
+   * readable has no identity, so `$actions` withholds every action with a
+   * non-empty row scope. Silent for controllers without own row actions.
+   */
+  private _warnScopeWithoutIdentity;
   /**
    * Returns a widened `$select` only when at least one `requiredFields` entry
    * is missing; `null` means "no widening needed". A field the request may
@@ -875,17 +1511,27 @@ 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.
+   * {@link actionRowScope} of every action in `names` for one evaluation
+   * (`ctx`, in parallel, alongside `overlay`), grouped by filter — object
+   * identity first, then structural equality (`filterKey`), so equal filters
+   * share one query; 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.
+   * Per action of `names`, a per-row mask (parallel to `rows`) of rows
+   * outside its {@link actionRowScope} — one id-only read per distinct
+   * filter. The hook sees the rows' identities (`purpose`); a row lacking
+   * its identity is in no scope. No candidate → no hook call, every row
+   * masked for every action (fail closed). `undefined` when the hook is not
+   * overridden or `rows` is empty.
+   */
+  private _scopeMasks;
+  /**
+   * The row filter {@link actionRowScope} returns for `action` and the
+   * candidates of `ctx` — `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;
   /**
@@ -894,12 +1540,41 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    */
   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.
+   * @internal The action gate's row overlay (reached by the `@DbAction`
+   * interceptor through {@link ACTION_OVERLAY}): {@link rowOverlay}. Since
+   * 0.1.147 the action's {@link actionRowScope} is applied separately to the
+   * loaded candidates ({@link ACTION_SCOPE}).
    */
-  [ACTION_OVERLAY](action: string | undefined): Promise<FilterExpr | undefined>;
+  [ACTION_OVERLAY](): Promise<FilterExpr | undefined>;
+  /**
+   * @internal {@link resolveRowIds} for an action's validated ids (since
+   * 0.1.148): the output validated, duplicate identities collapsed, and the
+   * ids as the client sent them kept for the error bodies and summaries.
+   */
+  [ROW_RESOLVE_IDS](ids: readonly Record<string, unknown>[], ctx: TDbRowIdsContext): Promise<TAppliedIds>;
+  /** @internal {@link actionRowScope} for the gate's loaded candidates (since 0.1.147). */
+  [ACTION_SCOPE](action: string, ctx: TDbActionScopeContext): Promise<FilterExpr | undefined>;
+  /** @internal `true` when {@link actionRowScope} is overridden (since 0.1.147). */
+  get [ACTION_SCOPED](): boolean;
+  /**
+   * @internal Resolves a query target (phase 1, since 0.1.147): the `query`
+   * body validated (shape, `$search` / `$index` only, the read's capability
+   * and index gate), then ONE read of `select` ordered by identity —
+   * `filter (+ $search) ∧ overlay ∧ queryTargetScope ∧ ¬exclude`, at most
+   * `cap + 1` rows. More than the cap → 400 `TARGET_TOO_LARGE`; a count
+   * other than `expectCount` → 409 `TARGET_CHANGED`. `load` re-reads rows
+   * of the snapshot that still match the same target (phase 2) — except for
+   * the first batch, which directly follows the snapshot.
+   */
+  [RESOLVE_TARGET](req: TTargetRequest): Promise<TResolvedTarget>;
+  /**
+   * Runs `fn` as a READ of this controller (since 0.1.147): in a child of
+   * the current event whose controller context is this controller's `query`
+   * handler, after `prepareRequest({ endpoint: "query", controls, filter })` — the
+   * request-scoped state a permission layer builds there (read grant, field
+   * visibility) is the read's and stays in the child.
+   */
+  private _asRead;
   /**
    * `@db.column.searchable` paths, minus anything the adapter can't filter
    * (JSON storage, encrypted), `@db.writeOnly` fields and navigation
@@ -910,11 +1585,13 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   /**
    * `select` without the `sealed` paths (see {@link _sealControls}); an
    * exclusion of them is forced when there is no projection, or when every
-   * requested path was sealed.
+   * requested path was sealed. An inclusion naming a PARENT of a sealed path
+   * (`secret` over a write-only `secret.hash`) is replaced by the parent's
+   * unsealed leaves, so a sealed descendant never rides along with it.
    */
   private _sealSelect;
-  /** First `@db.writeOnly` field referenced by `$groupBy` / aggregate `$select`, or undefined. */
-  private _findWriteOnlyInAggregate;
+  /** Own leaf field paths (no navigation, no ignored field) of `readable`, once per readable. */
+  private _leavesOf;
   /**
    * Merges the `$search` fallback into the filter: a case-insensitive literal
    * substring match OR'd across the `@db.column.searchable` fields, `$and`-combined
@@ -956,11 +1633,17 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * (reach them through the parent row), a `/one` 404, or value-help
    * controllers.
    *
-   * Convention (not enforced): name decoration keys with a `$` prefix, like
-   * `$actions` and `$distance`, so they can never collide with a field name.
-   * Do not overwrite `$actions` or `$disabledReasons`. Columns the
-   * hook needs but the client did not select must be added in
-   * {@link transformProjection} — they are then part of the response.
+   * Two kinds of keys. **Undeclared** keys: name them with a `$` prefix, like
+   * `$actions` and `$distance`, so they can never collide with a field; they
+   * are always kept and a client cannot select them. **Declared** keys
+   * ({@link DbDecorations}, since 0.1.148): list them with `@DbDecorations`,
+   * and a client may name them in `$select`; compute only `ctx.decorations`,
+   * read your inputs from the columns `requires` names, and any declared key
+   * not in `ctx.decorations` — and every column added only for the hook — is
+   * removed from the rows afterwards. Do not overwrite `$actions` or
+   * `$disabledReasons`. Without `@DbDecorations`, columns the hook needs but
+   * the client did not select must be added in {@link transformProjection} —
+   * they are then part of the response.
    *
    * ```ts
    * protected async decorateRows(rows: Record<string, unknown>[], ctx: TDbDecorateContext) {
@@ -979,24 +1662,154 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * 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;
+  private _finishRows;
+  /**
+   * `$actions` augmentation (when `prep`) — own actions, then the delegated
+   * ones (`delegated`: per delegation, per row) — then {@link decorateRows}
+   * when implemented.
+   */
+  private _augmentAndDecorate;
+  /**
+   * The app of the current event, through DI — never the one this
+   * (singleton) instance was constructed in, which may be gone (a re-booted
+   * app, a hot reload).
+   */
+  private _currentApp;
+  /** The class's `@DbActionsFrom` delegations, validated on first use (per app). */
+  private _delegations;
+  /**
+   * The delegations this request may use: every id path visible
+   * ({@link hasField}) and kept by {@link transformProjection} — a
+   * delegation whose ids the request can't read is dropped.
+   */
+  private _activeDelegations;
+  /**
+   * Runs `fn` on the delegation's source controller (this event's instance)
+   * evaluated as itself ({@link runAsController}); a 401 / 403 from its
+   * `prepareRequest` (the caller holds no grant there) yields `refused`.
+   */
+  private _onSource;
+  /** Per row, the source's verdict for the row it maps to (`undefined`: no source id). */
+  private _delegatedRowVerdicts;
+  /** The `/meta.actions` entries of the delegations the caller may run (per its source). */
+  private _delegatedInfos;
+  /**
+   * The cached `/meta` envelope through {@link applyMetaOverlay}, plus —
+   * since 0.1.147 — the `@DbActionsFrom` actions the caller may run as their
+   * source decides (`allowedActions` of the source, evaluated as itself) and,
+   * under an overridden {@link hasField}, the search surface narrowed to the
+   * indexes the request may use (the index gate's rule). Delegated entries
+   * never pass this controller's own `applyMetaOverlay`.
+   */
+  protected resolveMeta(): TMetaResponse | Promise<TMetaResponse>;
+  /**
+   * The delegated part of `GET /meta/actions…` for the source ids `sourceIdOf`
+   * derives from the request (`undefined`: not derivable by key renaming —
+   * the delegation is left out).
+   */
+  private _delegatedAvailable;
+  /**
+   * @internal Source side of a delegation: the `$actions` verdicts of `names`
+   * for `ids` (aligned; `undefined` = not found under the row overlay), as
+   * this controller's own `$actions` / `GET /meta/actions` compute them —
+   * its `prepareRequest("availableActions")`, `allowedActions`, row overlay,
+   * `actionRowScope` (`purpose: "rows"`) and `disabled`.
+   */
+  [ACTION_VERDICTS](ids: Record<string, unknown>[], names: readonly string[]): Promise<Array<TDbAvailableActions$1 | undefined>>;
+  /** @internal Source side of a delegation: `GET /meta/actions` for one id, `names` only. */
+  [AVAILABLE_ACTIONS](id: Record<string, unknown>, names: readonly string[]): Promise<TDbAvailableActions$1>;
+  /** @internal Source side of a delegation: the `names` the caller may run (`allowedActions`). */
+  [ALLOWED_ACTIONS](names: readonly string[]): Promise<readonly string[]>;
+  /** {@link _resolveAugmentEnvelopes} restricted to `names`. */
+  private _envelopesNamed;
+  /**
+   * Shared `query` / `pages` / `geo` 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`, then run {@link decorateRows}. Caller dispatches the
+   * strategy to its read-method family (count vs no-count).
+   */
+  private _runReadWithActions;
+  /**
+   * Maps the ids an id-addressed endpoint received to the rows' current ids
+   * (since 0.1.148) — the seam for stale or alias ids, e.g. a natural key that
+   * was renamed. Called once per request, after {@link prepareRequest} and
+   * after the request's own validation, before anything reads the row, by:
+   *
+   * | `ctx.purpose` | endpoint | `ids` |
+   * | --- | --- | --- |
+   * | `"one"` | `GET /one/:id`, `GET /one?…` | one id: the path string, or the `?`-form identification object |
+   * | `"available"` | `GET /meta/actions/:id`, `?…` (and a view asking its source) | one id, as above |
+   * | `"remove"` | `DELETE /:id`, `DELETE /?…` (`AsDbController`) | one id, as above |
+   * | `"action"` | an action route | the body's validated ids (one for a `'row'` action) |
+   *
+   * Contract:
+   *
+   * - Return one id per input id, index-aligned (anything else is a 500). An
+   *   id that already names a row must come back UNCHANGED — the current
+   *   holder of a key wins over an alias; so must an id you cannot resolve
+   *   (never throw for an unknown alias: a custom error is an oracle — the
+   *   endpoint then answers its normal miss).
+   * - The output is validated (a server bug is a 500, never a client 400): a
+   *   scalar is resolved like a path scalar (primary key first, then the
+   *   visible unique keys, inside the row overlay); an object must be one of
+   *   the visible identifications ({@link idSource}); an `"action"` id must
+   *   be such an object.
+   * - The resolved id is never trusted for access: the endpoint still reads
+   *   or deletes it under {@link rowOverlay} and the visible identifications.
+   *   `ctx.overlay` is that overlay — resolve INSIDE it when an alias could
+   *   name several rows, so a row the caller can't reach never shadows one
+   *   they can. Don't log or return the canonical id in errors.
+   * - Handlers (`@DbActionID()`, `useDbActionId()`), {@link rowOverlay} reads,
+   *   {@link actionRowScope} and `onRemove` / `guardRemove` receive the
+   *   resolved ids; error bodies and `summary()` echo the ids the client sent.
+   * - Write bodies (`POST` / `PUT` / `PATCH`) are not resolved — use
+   *   `onWrite`. Not called by value-help controllers, `$actions` on a read
+   *   or a query target. Not overriding it costs nothing.
+   *
+   * It is NOT overridden by {@link resolveRowFilter}, which does not take part
+   * in `/one` for real tables and views.
+   *
+   * ```ts
+   * protected async resolveRowIds(ids: readonly TDbRowIdInput[], ctx: TDbRowIdsContext) {
+   *   return Promise.all(ids.map(async (id) => {
+   *     const key = typeof id === "object" ? id.code : id
+   *     if (typeof key !== "string") return id
+   *     // the current holder of the key wins; consult the alias table on a miss
+   *     // resolve INSIDE the overlay: a row the caller cannot reach never wins
+   *     const inScope = (code: string) =>
+   *       this.readable.count({ filter: ctx.overlay ? { $and: [{ code }, ctx.overlay] } : { code } })
+   *     if (await inScope(key)) return id
+   *     const alias = await aliases.findOne({ filter: { oldCode: key } })
+   *     if (!alias || !(await inScope(alias.newCode))) return id
+   *     return typeof id === "object" ? { code: alias.newCode } : alias.newCode
+   *   }))
+   * }
+   * ```
+   *
+   * @since 0.1.148
+   */
+  protected resolveRowIds(ids: readonly TDbRowIdInput[], _ctx: TDbRowIdsContext): readonly TDbRowIdInput[] | Promise<readonly TDbRowIdInput[]>;
+  /** {@link resolveRowIds} with its output validated (a server bug is a 500). */
+  private _runResolveRowIds;
   /**
-   * Shared `query` / `pages` / `geo` 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`, then run {@link decorateRows}. Caller dispatches the
-   * strategy to its read-method family (count vs no-count).
+   * @internal The one id of an id-addressed endpoint through
+   * {@link resolveRowIds} (identity, at no cost, when it is not overridden)
+   * and the row overlay it was resolved inside — computed once, for the
+   * endpoint's read or delete under that overlay.
    */
-  private _runReadWithActions;
+  protected _resolveWithOverlay(id: TDbRowIdInput, purpose: Exclude<TDbRowIdPurpose, "action">): Promise<{
+    id: TDbRowIdInput;
+    overlay: FilterExpr | undefined;
+  }>;
   /**
    * The filter addressing exactly the ONE row `id` means — the readable's
    * PK-first `resolveRowFilter` (since 0.1.143) under this request's
    * identifications (`_idOpts`). `scope` (the row overlay) restricts which
    * rows count while the id is pinned, so a row outside it never shadows one
    * inside it. Readables without it (partial mocks) fall back to
-   * `resolveIdFilter`.
+   * `resolveIdFilter`. Not an alias seam: `/one` reads through `findOneByRow`
+   * on every real table or view — map stale ids in {@link resolveRowIds}.
    */
   protected resolveRowFilter(id: unknown, scope?: FilterExpr): Promise<FilterExpr | null>;
   /**
@@ -1087,18 +1900,95 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * `{ actions: [] }`. {@link prepareRequest} runs first with
    * `endpoint: "availableActions"`.
    */
-  availableActionsById(id: string): Promise<TDbAvailableActions>;
+  availableActionsById(id: string): Promise<TDbAvailableActions$1>;
   /**
    * **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>;
+  availableActions(query: Record<string, string>): Promise<TDbAvailableActions$1 | HttpError>;
+  /** Every field of every identification (primary key and unique indexes) the view addresses a row by. */
+  private _identificationFields;
+  /**
+   * A delegation's source id: each source id field from the row's mapped path
+   * of the RESOLVED `id`. A path of ANY of the view's identifications
+   * (`consumed` — not just the one the request matched: `?id=1&code=T-OLD` names
+   * `code` too) is NEVER taken from the raw `?` query: that value may be an
+   * alias `resolveRowIds` rewrote, and the source would see (and answer for)
+   * it. Paths outside the identification fall back to `fallback`'s (the raw
+   * query's) value; `undefined` when a path has none.
+   */
+  private _sourceIdOf;
+  /**
+   * {@link _availableActions} for a request id (`names`: only those actions):
+   * through {@link resolveRowIds} (`"available"`) first, the row overlay
+   * computed once for both — and the resolved id returned as an object (a
+   * scalar is the single-field `preferredId` value) for the delegated part to
+   * derive its source id from.
+   */
+  private _availableResolved;
+  /**
+   * **POST /delegated-actions/:name** — a query target for a `@DbActionsFrom`
+   * action whose source action declares `queryTarget` (since 0.1.147); the
+   * action's `/meta` entry points here (`queryTarget.url`). Body
+   * `{ query: { q, exclude?, expectCount?, maxRows?, dryRun? }, input? }`.
+   *
+   * The source must list the action for the caller (its `allowedActions`,
+   * as `$actions` does) — else 403, dry runs included. This controller then
+   * resolves the rows matching `q` under its own read scope (`transformFilter`
+   * ∧ {@link queryTargetScope} ∧ ¬`exclude` — `exclude` entries use this
+   * controller's identifications or the delegation's id paths, and the
+   * source rows they map to are left out even when other view rows map to
+   * them too), maps them to source ids (a row without one is skipped as
+   * `"unmapped"`), then runs the SOURCE's action route on them in batches
+   * inside this request (`MoostHttp.invoke`) — its guards, `prepareRequest`,
+   * row overlay, `actionRowScope` and `disabled` re-check every batch, and
+   * every body reader of the source sees the batch's `{ ids, input }`. Before
+   * each batch the view rows are re-checked against the target: a source id
+   * none of whose view rows still matches is skipped as `"stale"`; ids the
+   * source's gate refuses are skipped with their reasons. A batch failing
+   * once a source handler started (in it or an earlier batch) stops the run:
+   * the answer is the partial summary with `aborted` and every id not run
+   * listed in `failed`. A failure before any source handler started (a 403,
+   * the source's `@InputForm` 400, …) is the request's error — nothing ran,
+   * and every batch carries the same `input`. The
+   * `message` (string) each batch's handler returned is passed on:
+   * `messages` per batch, `message` the distinct ones joined by newlines. A
+   * dry run answers `{ matched }`; otherwise the answer is the run's
+   * {@link TDbActionTargetSummary}. An action of the delegation that takes no
+   * query target answers 400 `TARGET_INVALID`. `prepareRequest` runs first
+   * with `endpoint: "delegatedAction"`. Registered only on controllers
+   * declaring `@DbActionsFrom`.
+   */
+  runDelegatedOnQuery(): Promise<TDbActionTargetSummary$1 | {
+    matched: number;
+  }>;
+  /**
+   * The id keys (`idMap` fields) of the source rows `exclude` leaves out of a
+   * delegated target — an entry by the id paths names its source row
+   * directly; one by a view identification names the source row of that view
+   * row (read without overlay: excluding can only narrow the run).
+   */
+  private _excludedSourceKeys;
+  /**
+   * The source ids of `batch` that some view row still maps to under the
+   * target's query (phase-2 re-check); the others are recorded in
+   * `summary.skipped` as `"stale"`.
+   */
+  private _stillTargeted;
   /**
    * The row resolves ONCE, like `/one/:id` under {@link rowOverlay}; scoped
-   * actions are then checked on it exactly like `$actions` rows.
+   * actions are then checked on it (`purpose: "available"`) exactly like
+   * `$actions` rows.
    */
   private _availableActions;
+  /**
+   * Per row (`undefined` = not found → no verdict): the actions of
+   * `envelopes` it lists — minus those `masks` put it outside of, and those
+   * whose `disabled` rule refuses it on the fields its gate loads
+   * (`fieldsOf`, parallel to `envelopes`) — with the refusal reasons.
+   */
+  private _verdicts;
   /**
    * **GET /meta** — returns table/view metadata for UI.
    *
@@ -1156,7 +2046,9 @@ declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
    */
   protected onWrite(action: TDbWriteAction$1, data: unknown): unknown;
   /**
-   * Intercepts delete operations. Return `undefined` to abort (500 "Not
+   * Intercepts delete operations. Receives the id {@link resolveRowIds}
+   * resolved (the one the request carried when it is not overridden; since
+   * 0.1.148). Return `undefined` to abort (500 "Not
    * deleted"); return an `Error` instance to respond with that error.
    * Runs outside any transaction. May be async (e.g. to resolve composite
    * ids from external state).
@@ -1264,8 +2156,16 @@ declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
   private _deleteOrThrow;
   /**
    * **POST /** — inserts one or many records.
+   *
+   * `?$onConflict=ignore` (since 0.1.148) skips rows colliding on the primary
+   * key or a unique index instead of answering 409. The response then is
+   * `{ insertedId?, conflict }` for an object body and
+   * `{ insertedCount, insertedIds, inserted, conflicts }` for an array body.
+   * Any other `$` control on POST answers 400.
    */
-  insert(payload: unknown): Promise<unknown>;
+  insert(payload: unknown, url?: string): Promise<unknown>;
+  /** The only POST control: `$onConflict` (`error` | `ignore`). Anything else `$…` → 400. */
+  private _readOnConflict;
   /**
    * **PUT /** — fully replaces one or many records matched by primary key.
    *
@@ -1530,165 +2430,58 @@ declare class AsJsonValueHelpController<T extends TAtscriptAnnotatedType = TAtsc
   private normalizeSort;
 }
 //#endregion
-//#region src/actions/types.d.ts
-/**
- * One entry of a `disabled` predicate's result. Truthy = the action is
- * disabled for that row; falsy (`false`, `""`) = enabled. A non-empty string
- * disables the action AND carries a human-readable reason — surfaced in the
- * 409 `ActionDisabledError` message/body and in the row's `$disabledReasons`.
- *
- * @since 0.1.141 (`string`)
- */
-type TDbActionDisabledVerdict = boolean | string;
-/** `'rows'`-level batch policy — controls whether failing rows reject or are filtered out. */
-type TOnDisabledRows = "reject" | "skip";
-/**
- * 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 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>[]> {
-  /**
-   * 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.
-   */
-  requiredFields: R;
-  /**
-   * Sync batch gate predicate — returns a parallel array aligned with the
-   * input. Per entry: truthy = disabled for the corresponding row; a
-   * non-empty string also gives the reason (see
-   * {@link TDbActionDisabledVerdict}). The `rows`
-   * argument is type-narrowed to `Pick<FlatOf<TRow>, R[number]>[]`; reading
-   * a field not listed in `requiredFields` is a compile error.
-   *
-   * Promise return is NOT permitted — the predicate is consumed in the
-   * same tick by the gate and the augmenter.
-   */
-  disabled?: (rows: DisabledRowsArg<TRow, R>) => TDbActionDisabledVerdict[];
-  /**
-   * `'rows'`-level batch policy. Default `'reject'`.
-   *
-   * - `'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[]) => TDbActionDisabledVerdict[];
-  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" | "formUrl">> {
-  /**
-   * 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.
-   */
-  table?: AtscriptDbTable<any>;
+//#region src/decorations/db-decorations.decorator.d.ts
+/** Options of {@link DbDecorations}. @since 0.1.148 */
+interface TDbDecorationsOpts<D = Record<string, unknown>> {
   /**
-   * `'rows'` level (`@DbActionIDs` / `@DbActionRows`): the most identifiers
-   * one request may carry. Above it the request is rejected with 400 before
-   * any row is loaded. Default `1000`. Server-internal — never on the wire.
-   *
-   * @since 0.1.143
+   * Per decoration key, the bound readable's field paths `decorateRows` reads
+   * to compute it. Those paths are selected (and kept visible) automatically
+   * and stripped from the response unless the client selected them. A
+   * decoration that reveals a field's data MUST list it: the decoration is
+   * then served — and listed in `/meta` — only while that field is visible.
    */
-  maxIds?: number;
+  requires?: { [K in keyof D & string]?: readonly string[] };
 }
-/**
- * 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;
-  intent?: TDbActionIntent$1;
-  description?: string;
-  order?: number;
-  default?: boolean;
-  /** Mirrors {@link TDbActionInfo.promptText} — singular/plural via tuple. */
-  promptText?: string | [string, string];
-  /** Mirrors {@link TDbActionInfo.shortcut} — single-character UI hint. */
-  shortcut?: string;
-  /**
-   * Input form the UI collects before invoking the action:
-   *
-   * - a compiled `.as` interface — registered on THIS controller and served
-   *   by its own `GET /meta/form/:name`; the wire carries `inputForm: Type.name`.
-   * - `{ name, url }` — a form served elsewhere: `name` goes on the wire as
-   *   `inputForm`, `url` (server-absolute path of the serialized schema, e.g.
-   *   `"/api/shipping/meta/form/ShipForm"`) as {@link TDbActionInfo.formUrl}.
-   *
-   * Not allowed with `processor: 'navigate'`. Class-level entries only
-   * describe the action — validating `input` is the target handler's job
-   * (e.g. its own `@InputForm(Type)` param).
-   *
-   * @since 0.1.136
-   */
-  inputForm?: TAtscriptAnnotatedType | {
-    name: string;
-    url: string;
-  };
+/** Class metadata written by {@link DbDecorations}. */
+interface TDbDecorationsMeta {
+  /** The declared interface (a plain object type, no `@db.table` / `@db.view`). */
+  type: TAtscriptAnnotatedType;
+  /** Decoration key → the readable's field paths it reads. */
+  requires: Readonly<Record<string, readonly string[]>>;
 }
-type DbActionsEntryWithGate<TRow, R extends readonly FlatKey<TRow>[]> = DbActionsEntryCommonBase & GateOpts<TRow, R>;
 /**
- * Class-level dict entry. `value` semantics by processor:
+ * Declares display-only (decoration) fields of a table or view controller —
+ * values `decorateRows` computes and attaches to rows (since 0.1.148).
  *
- * - `'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` is a plain atscript interface (no `@db.table` / `@db.view`) whose
+ * top-level props are the decorations: their `@meta.label`, `@expect.*` and
+ * `@ui.*` annotations travel in `/meta.decorations`, each key is listed in
+ * `/meta.fields` with `decoration: true`, and a client may name it in
+ * `$select`. A decoration is never filterable, sortable or groupable, and it
+ * is not part of `/meta.type` (forms and write validation never see it).
+ *
+ * ```ts
+ * @TableController(TicketTable)
+ * @DbDecorations(TicketDecorations, { requires: { ownerName: ["ownerId"] } })
+ * export class TicketsController extends AsDbController<typeof TicketTable> {
+ *   protected async decorateRows(rows: Record<string, unknown>[], ctx: TDbDecorateContext) {
+ *     if (ctx.decorations.has("ownerName")) {
+ *       // read rows[i].ownerId, set rows[i].ownerName
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Validated once per class at first use (a `[moost-db]` error): the type is an
+ * object interface; keys are top-level identifiers that collide with no field
+ * or relation of the readable; every `requires` path is an own, readable
+ * (not `@db.writeOnly`) field or a parent object of own fields (on SQL a nested
+ * object is flattened to leaf columns; the hook still gets the whole object). Inherited under `@Inherit()`. Not supported on
+ * value-help controllers.
+ *
+ * @since 0.1.148
  */
-type TDbActionsEntry<TRow = unknown, R extends readonly FlatKey<TRow>[] = []> = (DbActionsEntryWithGate<TRow, R> & {
-  processor: "navigate";
-  value: string;
-  inputForm?: never;
-}) | (DbActionsEntryWithGate<TRow, R> & {
-  processor: "custom";
-  value?: never;
-}) | (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<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>> };
+declare function DbDecorations<D extends TAtscriptAnnotatedType>(type: D, opts?: TDbDecorationsOpts<TAtscriptDataType<D>>): ClassDecorator;
 //#endregion
 //#region src/actions/keys.d.ts
 type TDbActionRowMarker = true;
@@ -1707,6 +2500,18 @@ interface TDbClassActionMeta {
   name: string;
   entry: TDbActionsEntry;
 }
+/**
+ * Class-level entry written by `@DbActionsFrom(source, opts)` (since
+ * 0.1.147): a controller whose row-level actions this controller delegates.
+ */
+interface TDbActionsFromMeta {
+  /** Lazy reference to the source controller class. */
+  source: () => Function;
+  /** Source identification field → path in this controller's rows. */
+  idMap?: Record<string, string>;
+  /** Subset of the source's row / rows-level action names (default: all). */
+  actions?: readonly string[];
+}
 /** Param marker kind — informs level inference and ID-resolution shape. */
 type TDbActionParamKind = "id" | "ids";
 declare module "moost" {
@@ -1717,12 +2522,15 @@ declare module "moost" {
     atscript_db_action_row?: TDbActionRowMarker;
     atscript_db_action_rows?: TDbActionRowMarker;
     atscript_db_endpoint?: TDbRequestEndpoint;
+    atscript_db_actions_from?: TDbActionsFromMeta[];
+    atscript_db_decorations?: TDbDecorationsMeta;
   }
   interface TMoostParamsMetadata {
     atscript_db_action_param?: TDbActionParamKind;
     atscript_db_action_row?: TDbActionRowMarker;
     atscript_db_action_rows?: TDbActionRowMarker;
     atscript_db_action_input_form?: TDbActionInputFormMeta;
+    atscript_db_action_target?: true;
     atscript_type?: TAtscriptAnnotatedType;
   }
 }
@@ -1775,6 +2583,10 @@ interface AtscriptDbMeta {
    * {@link getDbEndpoint}.
    */
   atscript_db_endpoint?: TDbRequestEndpoint;
+  /** Class-level — written by `@DbActionsFrom(...)` (since 0.1.147). Decorators accumulate. */
+  atscript_db_actions_from?: TDbActionsFromMeta[];
+  /** Class-level — written by `@DbDecorations(...)` (since 0.1.148). */
+  atscript_db_decorations?: TDbDecorationsMeta;
 }
 /**
  * Param-level metadata written by `@atscript/moost-db`'s param
@@ -1788,6 +2600,8 @@ interface AtscriptDbParamsMeta {
   atscript_db_action_row?: true;
   /** Param-level marker — written by `@DbActionRows()`. */
   atscript_db_action_rows?: true;
+  /** Param-level marker — written by `@DbActionTarget()` (since 0.1.147). */
+  atscript_db_action_target?: true;
   /**
    * Param-level — written by `@InputForm(FormType)`. Carries the
    * compiled `.as` class plus its `.name` so `discoverActions` can both
@@ -2051,7 +2865,8 @@ declare const UseValidationErrorTransform: () => ClassDecorator & MethodDecorato
 /**
  * Mark a controller method as a database action surfaced via `/meta`. Writes
  * `atscript_db_action` metadata and, for every `'row'` / `'rows'` action,
- * registers a Moost interceptor: the gate when `disabled` is set, else the
+ * registers a Moost interceptor: the batch gate for a `@DbActionTarget()`
+ * handler (since 0.1.147), the gate when `disabled` is set, else the
  * bound-table injector that also verifies the ids against the controller's
  * row overlay (since 0.1.143). Either first awaits the controller's
  * `prepareRequest({ endpoint: "action", action })` when it defines one —
@@ -2220,28 +3035,6 @@ declare function InputForm<T extends TAtscriptAnnotatedType & {
   readonly name: string;
 }>(formType?: T, validatorOpts?: Partial<TValidatorOptions>): ParameterDecorator;
 //#endregion
-//#region src/actions/discover.d.ts
-/**
- * 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`).
- */
-/** A discovered action: its `/meta.actions[]` entry plus the server-internal opts it was declared with. */
-interface TDbActionEnvelope {
-  info: TDbActionInfo$1;
-  raw: DbActionOpts | TDbActionsEntry;
-}
-/** Lookup helper for `AsReadableController.metaForm()`. */
-declare function getControllerFormType(ctor: Function, name: string): TAtscriptAnnotatedType | undefined;
-/** Discover actions on a controller, memoized per ctor. `info`-only callers map `e => e.info`. */
-declare function discoverActions(controllerCtor: Function, app: Moost, logger: TConsoleBase): TDbActionEnvelope[];
-/**
- * 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<{
   load: () => Promise<Record<string, unknown>>;
@@ -2267,10 +3060,15 @@ declare const useDbActionRows: import("@wooksjs/event-core").WookComposable<{
  *   absent (`'table'`-level).
  * - `input` — present only when the action declares an `@InputForm()`
  *   parameter; carries the form payload the user filled out.
+ * - `query` — a query target instead of `ids` (since 0.1.147): "every row
+ *   matching this query", for `'rows'` actions declaring `queryTarget` — see
+ *   {@link TDbActionQueryTarget}. Never together with `ids`.
  */
 interface DbActionEnvelope {
   ids?: unknown;
   input?: unknown;
+  /** @since 0.1.147 — validated by the action's gate (`TDbActionQueryTarget`). */
+  query?: unknown;
 }
 /**
  * Cached parse of the action request body. Centralises the shape check so
@@ -2339,6 +3137,165 @@ declare class ActionDisabledError extends HttpError<ActionDisabledErrorBody> {
   constructor(action: string, id?: Record<string, unknown>, ids?: Record<string, unknown>[], reasons?: readonly (string | null | undefined)[]);
 }
 //#endregion
+//#region src/actions/action-target-error.d.ts
+/**
+ * Why a query-targeted action request was refused:
+ *
+ * - `TARGET_INVALID` (400) — malformed `query` (unknown key, a control other
+ *   than `$search` / `$index`, `ids` and `query` together, an action that
+ *   accepts no query target);
+ * - `TARGET_TOO_LARGE` (400) — more rows match than the cap (`cap`);
+ * - `TARGET_CHANGED` (409) — the match count differs from `expectCount`
+ *   (`matched` carries the current count).
+ *
+ * @since 0.1.147
+ */
+type TActionTargetErrorCode = "TARGET_INVALID" | "TARGET_TOO_LARGE" | "TARGET_CHANGED";
+/**
+ * Wire body of {@link ActionTargetError} — the moost `ServerError` envelope
+ * plus the `name` discriminator `@atscript/db-client` maps to its typed error.
+ *
+ * @since 0.1.147
+ */
+interface ActionTargetErrorBody {
+  name: "ActionTargetError";
+  message: string;
+  statusCode: 400 | 409;
+  code: TActionTargetErrorCode;
+  action: string;
+  /** `TARGET_CHANGED`: the current match count. */
+  matched?: number;
+  /** `TARGET_TOO_LARGE`: the most rows one request may target. */
+  cap?: number;
+}
+/**
+ * A refused query target (400 / 409) — see {@link TActionTargetErrorCode}.
+ *
+ * @since 0.1.147
+ */
+declare class ActionTargetError extends HttpError<ActionTargetErrorBody> {
+  name: string;
+  constructor(code: TActionTargetErrorCode, action: string, message: string, extra?: {
+    matched?: number;
+    cap?: number;
+  });
+}
+//#endregion
+//#region src/actions/target.d.ts
+/**
+ * The rows a `'rows'` action runs on, as the handler surface of
+ * `@DbActionTarget()` / {@link useDbActionTarget} (since 0.1.147) — the same
+ * for an id target (`{ ids }`) and a query target (`{ query }`).
+ *
+ * @since 0.1.147
+ */
+interface TDbActionTarget<Row = Record<string, unknown>> {
+  /** `"ids"` — the body listed identifiers; `"query"` — a query target. */
+  readonly kind: "ids" | "query";
+  /** Rows the target resolved to (after `exclude`, before the per-batch gate). */
+  readonly matched: number;
+  /**
+   * The target in batches, each already gated: the row overlay, the
+   * action's `actionRowScope` for the batch, `disabled`, and — for a query
+   * target — the query itself (a row that changed out of it is skipped as
+   * `"stale"`). Rows carry the identity fields and the visible
+   * `requiredFields`. Single pass.
+   */
+  batches(): AsyncIterable<{
+    ids: Record<string, unknown>[];
+    rows: Row[];
+  }>;
+  /** Reports a row the handler could not process — listed in {@link summary}. */
+  fail(id: Record<string, unknown>, reason: string): void;
+  /** What happened so far: matched, processed, skipped (by the gate) and failed rows. */
+  summary(): TDbActionTargetSummary$1;
+}
+/**
+ * The current `'rows'` action's {@link TDbActionTarget} (since 0.1.147).
+ * Available in the handler of every `'rows'` action — `@DbActionTarget()`
+ * handlers process it batch by batch; `@DbActionIDs()` / `@DbActionRows()`
+ * handlers read it for `summary()` (the ids `onDisabledRows: 'skip'`
+ * dropped, with their reasons).
+ *
+ * @since 0.1.147
+ */
+declare function useDbActionTarget<Row = Record<string, unknown>>(ctx?: EventContext): TDbActionTarget<Row>;
+/**
+ * Parameter decorator injecting the action's {@link TDbActionTarget}
+ * (since 0.1.147). Makes the action `'rows'` level and switches its gate to
+ * batch mode: the handler iterates `target.batches()`, each batch gated on
+ * its own (skip semantics — rows failing the gate are skipped and reported
+ * in `summary()`, never rejected). Accepts `{ ids }` bodies, and `{ query }`
+ * bodies when the action declares `queryTarget`. Not combinable with
+ * `@DbActionID*` / `@DbActionRow*`.
+ *
+ * ```ts
+ * @Post("actions/close")
+ * @DbAction<Issue>("close", { label: "Close", queryTarget: true })
+ * async close(@DbActionTarget() target: TDbActionTarget<Issue>) {
+ *   for await (const { ids } of target.batches()) await closeIssues(ids)
+ *   return target.summary()
+ * }
+ * ```
+ *
+ * @since 0.1.147
+ */
+declare function DbActionTarget(): ParameterDecorator;
+//#endregion
+//#region src/actions/db-actions-from.decorator.d.ts
+/** Options of {@link DbActionsFrom}. @since 0.1.147 */
+interface TDbActionsFromOpts {
+  /**
+   * Source identification field → the path in THIS controller's rows that
+   * carries its value. Its keys must be exactly one identification of the
+   * source (its primary key or a unique index). Default: derived from the
+   * view definition — the view column that plainly maps each of the
+   * source's `preferredId` fields. Required when this controller is not
+   * bound to a view.
+   */
+  idMap?: Record<string, string>;
+  /** The source's row / rows-level actions to delegate. Default: all of them. */
+  actions?: readonly string[];
+}
+/**
+ * Lists another controller's row / rows-level actions on THIS controller —
+ * typically a `@ViewController` over the table whose actions the view's
+ * rows stand for (since 0.1.147). The actions stay the source's: its route
+ * runs them (`value`), its gate, permissions, `actionRowScope` and
+ * `disabled` decide; the view only maps its rows to source ids.
+ *
+ * - `/meta.actions` lists them with `owner` (the source's base path) and,
+ *   when the ids are renamed, `idMap`; forms come from the source
+ *   (`formUrl`).
+ * - `$actions` on the view's rows carries the source's verdict for the row
+ *   each view row maps to — what the source's own `GET /meta/actions/:id`
+ *   answers for it.
+ * - `GET /meta/actions/:id` on the view answers them when the source id is
+ *   the view id renamed (`idMap` paths ⊆ the id used).
+ * - A source action declaring `queryTarget` also takes a query target on the
+ *   VIEW (`queryTarget.url`): the view resolves "every view row matching the
+ *   query" under its own read scope, maps the rows to source ids and runs the
+ *   source's action route on them in batches — the source re-checks every
+ *   batch.
+ *
+ * Repeatable (several sources, listed in declaration order). The source is
+ * referenced lazily (no import cycles between controllers) and must be
+ * registered with the app. Only a
+ * controller declaring it gets the `POST {prefix}/delegated-actions/:name`
+ * route (subclasses inherit it).
+ *
+ * ```ts
+ * @ViewController(IssueBoard)
+ * @DbActionsFrom(() => IssueController)                       // id → id
+ * export class IssueBoardController extends AsDbReadableController<typeof IssueBoard> {}
+ *
+ * @DbActionsFrom(() => IssueController, { idMap: { id: "issueId" }, actions: ["close"] })
+ * ```
+ *
+ * @since 0.1.147
+ */
+declare function DbActionsFrom(source: () => Function, opts?: TDbActionsFromOpts): ClassDecorator;
+//#endregion
 //#region src/actions/per-row.d.ts
 /**
  * Lift a per-row predicate into the batch shape required by
@@ -2429,4 +3386,37 @@ 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 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 };
+//#region src/relation-predicates.d.ts
+/**
+ * Client relational predicates (`nav=$some(…)` / `nav=$none(…)`, since
+ * 0.1.147) at the HTTP layer: the request gate and the
+ * `transformRelationFilter` overlay walk. Server-side filters
+ * (`transformFilter`, `transformOne`, `actionRowScope`) never pass through
+ * here — they are the authorization rule itself.
+ *
+ * Invariant: a client predicate on relation `n` reveals nothing that
+ * `$with=n(<same filter>)` would not reveal under the same controller policy
+ * — same visibility (`hasField` at `n` and `n.*`), the related table's own
+ * capability rules (encrypted, `@db.writeOnly`, JSON storage,
+ * `@db.table.filterable 'manual'`, geo, …) and the same row overlay
+ * (`transformRelationFilter`). On top, the relation must opt in with
+ * `@db.rel.filterable` (a predicate filters the PARENT rows).
+ */
+/**
+ * Nesting limit of CLIENT relational predicates per predicate chain (`$with`
+ * hops don't count; server-added predicates are not counted). Below the
+ * core's `REL_FILTER_MAX_DEPTH` so server overlays have headroom.
+ *
+ * @since 0.1.147
+ */
+declare const REL_FILTER_CLIENT_MAX_DEPTH = 3;
+/**
+ * Count limit of CLIENT relational predicates per request — root filter and
+ * `$with` sub-filters together. Below the core's `REL_FILTER_MAX_NODES` so
+ * server overlays have headroom.
+ *
+ * @since 0.1.147
+ */
+declare const REL_FILTER_CLIENT_MAX_NODES = 8;
+//#endregion
+export { ActionDisabledError, type ActionDisabledErrorBody, ActionTargetError, type ActionTargetErrorBody, 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, DbActionTarget, DbActions, DbActionsFrom, DbDecorations, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, REL_FILTER_CLIENT_MAX_DEPTH, REL_FILTER_CLIENT_MAX_NODES, ReadableController, TABLE_DEF, type TActionTargetErrorCode, 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 TDbActionQueryTarget, type TDbActionScopeContext, type TDbActionScopePurpose, type TDbActionTarget, type TDbActionTargetSummary, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbActionsFromMeta, type TDbActionsFromOpts, type TDbAvailableActions, type TDbClassActionMeta, TDbControlsType, TDbDecorateContext, TDbDecorateEndpoint, type TDbDecorationsOpts, TDbFieldVisibility, TDbIndexFieldPaths, TDbParsedRequest, type TDbQueryTargetOpts, type TDbRemoveGuardContext, TDbRequestContext, TDbRequestEndpoint, type TDbRowIdInput, type TDbRowIdPurpose, type TDbRowIdsContext, type TDbWriteAction, type TDbWriteCheckContext, type TDbWriteGuardContext, type TFieldCapability, type TGateOp, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ValueHelpQuery, ValueHelpSelect, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, closeDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, discoverRowLevelActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, getDbEndpoint, hasActionDelegations, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, useDbActionTarget, validationErrorTransform };