@aooth/arbac-moost 0.1.71 → 0.1.73

package/dist/index.d.mts

@@ -1,12 +1,201 @@
-import { a as ArbacDbScope, c as enforceControlsPolicy, d as NavRelationKey, f as NavTarget, i as conjoinArbacDbScopes, l as extractUsedControlValues, m as ProjectionOf, n as ArbacUserProviderToken, o as AsArbacDbController, p as OwnFieldKey, r as AoothArbacClaims, s as applyAllowedFieldsAndSet, t as ArbacUserProvider, u as ControlsOf } from "./user.provider-C5BrFNxg.mjs";
-import { Arbac, Arbac as Arbac$1, TArbacCompiledRule, TArbacEvalResult, TArbacRole, TArbacRoleForResource, TArbacRule, arbacPatternToRegex } from "@aooth/arbac-core";
+import { _ as ProjectionOf, a as conjoinArbacDbScopes, b as TArbacMeta, c as ArbacDbScope, d as extractUsedControlValues, f as applyAllowedFieldsAndSet, g as OwnFieldKey, h as NavTarget, i as ConjoinArbacDbScopesOptions, l as AsArbacDbController, m as NavRelationKey, n as ArbacUserProviderToken, o as RefForeignKey, p as ControlsOf, r as AoothArbacClaims, s as RefTableSource, t as ArbacUserProvider, u as enforceControlsPolicy, v as ARBAC_DELEGATED_AUTH, x as getArbacMate, y as ArbacDelegatedAuth } from "./user.provider-NMSzynGK.mjs";
+import { Arbac, Arbac as Arbac$1, TArbacCompiledRule, TArbacEvalResult, TArbacEvalResult as TArbacEvalResult$1, TArbacRole, TArbacRoleForResource, TArbacRule, arbacPatternToRegex } from "@aooth/arbac-core";
 import { TAuthGuardDef } from "@moostjs/event-http";
 import { EventContext } from "@wooksjs/event-core";
-import { Mate, TMateParamMeta, TMoostMetadata } from "moost";
-import { ControlGate, TProjection } from "@aooth/arbac";
-import { TMetaResponse } from "@atscript/db";
-import { AsDbReadableController } from "@atscript/moost-db";
-import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
+import { ControlGate, TProjection, TScopeFieldRules, TScopeFilter } from "@aooth/arbac";
+import { FilterExpr, TDbRemoveGuardContext, TDbWriteCheckContext, TDbWriteGuardContext, TDeleteOptions, TMetaResponse, TRowResolveOptions, TWriteOptions } from "@atscript/db";
+import { AsDbReadableController, AsJsonValueHelpController, AsValueHelpController, TDbControlsType, TDbIndexFieldPaths, TDbRequestContext, ValueHelpSelect } from "@atscript/moost-db";
+import { TAtscriptAnnotatedType, TAtscriptDataType } from "@atscript/typescript/utils";
+//#region src/db/visibility.d.ts
+/**
+ * The slice of an atscript-db readable (table / view) the visibility walk
+ * reads — a moost-db controller's `this.readable` satisfies it: identifiers
+ * (always visible), nav relations (to reach the joined table), the
+ * flattened schema (to split `$select` parents by scope) and the field
+ * descriptors (atomic JSON columns, derived-column sources).
+ */
+interface VisibilityTableSource {
+  primaryKeys: readonly string[];
+  preferredId: readonly string[];
+  relations?: ReadonlyMap<string, unknown>;
+  /**
+   * The target table of nav relation `navField` (atscript-db's
+   * `readable.relatedTable`); absent / `undefined` → the joined table's
+   * identifiers are not exempted.
+   */
+  relatedTable?(navField: string): VisibilityTableSource | undefined;
+  /** Flattened schema (dot-paths) — used to split `$select` parents by scope. */
+  flatMap?: ReadonlyMap<string, unknown>;
+  /** Navigation field paths — their joined descendants are not own columns. */
+  navFields?: ReadonlySet<string>;
+  /**
+   * The readable's annotated type — the `$with` target registry key and the
+   * owner a self-`ref` points at.
+   *
+   * @since 0.1.72
+   */
+  type?: object;
+  /**
+   * Field descriptors: `derived` marks a `@db.column.derived` field
+   * (visible only while its source is).
+   *
+   * @since 0.1.72
+   */
+  fieldDescriptors?: ReadonlyArray<{
+    path: string;
+    derived?: {
+      sourcePath: string;
+    };
+  }>;
+  /**
+   * Paths stored as ONE JSON column (atscript-db's `readable.jsonParents`,
+   * relational adapters): visible whole or not at all.
+   *
+   * @since 0.1.72
+   */
+  jsonParents?: ReadonlySet<string>;
+  /** Whether the adapter searches natively (`/meta` search-surface pruning). @since 0.1.72 */
+  isSearchable?(): boolean;
+}
+/** Relation name → the visibility its joined rows obey, or `null` when hidden. */
+type ArbacRelationResolution = ReadonlyMap<string, MetaVisibility | null>;
+/**
+ * The principal's field-visibility verdict set, assembled once per request
+ * (or per `/meta` overlay) and threaded through the pruning walk.
+ */
+interface MetaVisibility {
+  /**
+   * Projection union for this level's own fields. `{}` (the universe) means
+   * unrestricted — possible when only a `with` sub-scope restricts anything.
+   */
+  allowed: TProjection;
+  /**
+   * Identifier fields reads ALWAYS return regardless of projection (the read
+   * path widens `preferredId` back in, and PK addressing requires the key) —
+   * hiding them would advertise less than reads deliver and break `/one/:id`.
+   */
+  alwaysVisible: ReadonlySet<string>;
+  /** Relation names declared via `with.<name>` (see {@link collectWithGrantNames}). */
+  withGrants: ReadonlySet<string>;
+  /**
+   * Visibility of a relation's JOINED fields: for a declared relation, the
+   * union of its `with.<name>` sub-scopes; for an undeclared one, the
+   * caller's own read scopes on the related table (resolved per request —
+   * `undefined` when the relation is hidden). The related table's own
+   * identifiers are always visible. A path `rel.x.y` is checked as `x.y`
+   * against it, recursively. A hand-built visibility without it lets
+   * declared paths through unchecked (legacy behavior).
+   */
+  relation?: (name: string) => MetaVisibility | undefined;
+  /**
+   * Relations of this level's table. An undeclared one is visible only when
+   * the projection union allows its name AND {@link relation} resolves it
+   * (the `$with` inherit-target policy); absent → relation names are
+   * ordinary projection paths (legacy).
+   */
+  relationNames?: ReadonlySet<string>;
+  /**
+   * Precompiled `isFieldAllowed(path, allowed)` — plus the derived-column
+   * rule (a `@db.column.derived` field is visible only while its source is).
+   * Supplied by {@link buildScopeVisibility}; a hand-built visibility falls
+   * back to `isFieldAllowed`.
+   */
+  isAllowed?: (path: string) => boolean;
+  /** The scopes this level was built from (set by {@link buildScopeVisibility}). */
+  scopes?: ArbacDbScope[];
+  /** The table this level describes, when known (set by {@link buildScopeVisibility}). */
+  table?: VisibilityTableSource;
+  /**
+   * Fields the principal's WRITE scopes allow (union of `allowedFields`, or
+   * `"all"` for an unrestricted write grant). A field that is writable but not
+   * read-visible is NOT pruned from `/meta` — it survives with a `db.writeOnly`
+   * stamp (type only; rows/projections never carry it), so generic forms and
+   * client preflight validators can still SET sealed fields (e.g. credentials
+   * behind a read projection). Absent → nothing extra survives.
+   */
+  writable?: ReadonlySet<string> | "all";
+  /**
+   * Nav relations the WRITE scopes opt into nested writes (union of
+   * `nestedWrites`). A relation path is writable only when listed here (and
+   * covered by {@link writable}) — mirroring the 403 the write endpoints
+   * answer for any other nav key. Absent → no relation is writable.
+   *
+   * @since 0.1.72
+   */
+  nestedWrites?: ReadonlySet<string>;
+}
+/**
+ * Union the per-scope `projection` whitelists into the single access-control
+ * projection used for FIELD-EXISTENCE decisions (`hasField` parity + `/meta`
+ * pruning). Returns `undefined` when the union imposes no restriction — no
+ * scopes at all, or any scope without a `projection` (a universal grant makes
+ * `unionProjections` collapse to the universe `{}`).
+ */
+declare function unionScopeProjection(scopes: ArbacDbScope[]): TProjection | undefined;
+/**
+ * Relation names any scope explicitly declares via `with.<name>` — those
+ * relations are governed by the declared sub-scopes alone (parent authority),
+ * and the declaration implies the relation EXISTS for this principal even
+ * when the projection union does not name it (see {@link ArbacDbScope.with}).
+ */
+declare function collectWithGrantNames(scopes: ArbacDbScope[]): ReadonlySet<string>;
+/**
+ * Union of write-scope `allowedFields`; `"all"` for field-unrestricted write
+ * access. The whitelist exists only when at least one scope carries an
+ * `allowedFields` array — scoped-but-unlisted writes are field-unrestricted.
+ */
+declare function collectWritableFields(scopes: ArbacDbScope[], unrestricted: boolean): ReadonlySet<string> | "all" | undefined;
+/**
+ * Whether a flattened dot-path field exists for this principal.
+ *
+ * - A relation declared via `with.<name>` is visible; a path under it
+ *   (`rel.x.y`) is checked as `x.y` against its sub-scope visibility.
+ * - An undeclared relation of the table (see {@link MetaVisibility.relationNames})
+ *   is visible only when the projection allows its name and the caller's own
+ *   grant on the related table resolved ({@link MetaVisibility.relation});
+ *   paths under it are checked against that grant.
+ * - Anything else follows the projection union (and the derived-column rule).
+ *
+ * So a field a joined table hides is as unknown in a `$with` sub-query as a
+ * top-level hidden column is in the main query (no filter/sort value oracle).
+ */
+declare function isMetaFieldVisible(path: string, vis: MetaVisibility): boolean;
+/**
+ * PK + `preferredId` for a controller's table/readable — the
+ * {@link MetaVisibility.alwaysVisible} set. Kept for compatibility: the
+ * controllers now pass `this.readable` and it is derived there.
+ */
+declare function metaAlwaysVisibleFields(_controller: object, source: {
+  primaryKeys: readonly string[];
+  preferredId: readonly string[];
+}): ReadonlySet<string>;
+/** Options of {@link buildScopeVisibility}. @since 0.1.72 */
+interface ScopeVisibilityOptions {
+  /** Identifiers exempt from the projection; default: the table's PK + `preferredId`. */
+  alwaysVisible?: ReadonlySet<string>;
+  /**
+   * The undeclared relations resolved for this level (the caller's own grant
+   * on each related table — see `resolveRelationTree`); an undeclared
+   * relation missing here is hidden.
+   */
+  relations?: ArbacRelationResolution;
+}
+/**
+ * Build the {@link MetaVisibility} a set of read scopes implies — the single
+ * structure behind `hasField`, `/meta` pruning, `$select` value stripping
+ * and the `$with` overlay, so they cannot drift. Own fields: the projection
+ * union (`{}` when unrestricted), normalized for atomic JSON columns and
+ * derived-column sources, precompiled into `isAllowed`. Relations: an
+ * undeclared one → its node in `relations` (none → hidden); a declared
+ * `with.<name>` → the union of its sub-scopes (lazily built when `relations`
+ * has no node for it). The related table's own PK / `preferredId` stay
+ * visible.
+ *
+ * @param opts - {@link ScopeVisibilityOptions}; a bare identifier set is the
+ *   0.1.71 `alwaysVisible` argument
+ */
+declare function buildScopeVisibility(scopes: ArbacDbScope[], table: VisibilityTableSource | undefined, opts?: ScopeVisibilityOptions | ReadonlySet<string>): MetaVisibility;
+//#endregion
 //#region src/arbac.composables.d.ts
 /**
  * The scopes cached for the current event (`undefined` before the authorize
@@ -17,13 +206,26 @@ import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
  * `TScope` is a caller-side type witness (see `evaluate` below).
  */
 declare function getArbacScopes<TScope extends object>(ctx?: EventContext): TScope[] | undefined;
+/** Options of `useArbac().evaluate()` / `evaluateOrThrow()`. */
+interface ArbacEvaluateOptions {
+  /** Resource to evaluate; defaults to the current handler's. */
+  resource?: string;
+  /** Action to evaluate; defaults to the current handler's. */
+  action?: string;
+  /**
+   * The atscript-db readable whose schema a credential-attenuation
+   * conjunction uses to subtract nested exclusions exactly — pass the
+   * related table when evaluating a grant on it (e.g. a `$with` target).
+   * Defaults to the current controller's `readable`.
+   *
+   * @since 0.1.72
+   */
+  table?: VisibilityTableSource;
+}
 interface ArbacBindings {
   getScopes: <TScope extends object>() => TScope[] | undefined;
   setScopes: <TScope extends object>(scope: TScope[] | undefined) => void;
-  evaluate: <TScope extends object>(opts?: {
-    resource?: string;
-    action?: string;
-  }) => Promise<{
+  evaluate: <TScope extends object>(opts?: ArbacEvaluateOptions) => Promise<{
     allowed: boolean;
     scopes?: TScope[];
     userId: string;
@@ -37,10 +239,7 @@ interface ArbacBindings {
    * with another policy, to filter UI metadata, or to fall through to a
    * different authorization path).
    */
-  evaluateOrThrow: <TScope extends object>(opts?: {
-    resource?: string;
-    action?: string;
-  }) => Promise<{
+  evaluateOrThrow: <TScope extends object>(opts?: ArbacEvaluateOptions) => Promise<{
     allowed: true;
     scopes?: TScope[];
     userId: string;
@@ -91,138 +290,164 @@ declare const ArbacResource: (name: string) => MethodDecorator & ClassDecorator
  */
 declare const ArbacAction: (name: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 //#endregion
-//#region src/arbac.mate.d.ts
-/**
- * ARBAC metadata fields attached to classes and methods by ARBAC decorators.
- *
- * Augments the shared `TMoostMetadata` workspace via TypeScript declaration
- * merging so other moost-aware tooling (and `getArbacMate()` readers) sees
- * these fields with full type safety.
- */
-interface TArbacMeta {
-  arbacResourceId?: string;
-  arbacActionId?: string;
-  arbacPublic?: boolean;
-}
-declare module "moost" {
-  interface TMoostMetadata extends TArbacMeta {}
-}
-type ArbacMate = Mate<TMoostMetadata & {
-  params: TMateParamMeta[];
-}, TMoostMetadata & {
-  params: TMateParamMeta[];
-}>;
-/**
- * Returns the shared `Mate` instance typed with ARBAC metadata fields.
- *
- * All ARBAC decorators write through this typed wrapper so reads and writes
- * stay type-checked against `TArbacMeta`.
- */
-declare function getArbacMate(): ArbacMate;
-//#endregion
 //#region src/db/as-arbac-db-readable-controller.d.ts
 /**
  * Read-only mirror of {@link AsArbacDbController} for view-style controllers
  * built on top of `@atscript/moost-db`'s {@link AsDbReadableController}.
- * Applies the same filter / projection / controls overlays — no write-side
- * hooks because the parent exposes none.
+ * Applies the same fail-closed `prepareRequest` and filter / projection /
+ * controls overlays — no write-side hooks because the parent exposes none.
  */
 declare class AsArbacDbReadableController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType> extends AsDbReadableController<T> {
-  protected transformFilter(filter: Record<string, unknown> | undefined): Promise<Record<string, unknown>>;
-  protected transformProjection(projection?: TProjection): TProjection | undefined | Promise<TProjection | undefined>;
-  protected validateControls(controls: Record<string, unknown>, type: "query" | "pages" | "getOne"): string | undefined;
-  /**
-   * Same ARBAC `/meta` overlay as the writable controller (actions/crud
-   * filtering + BUG-3 field-surface pruning by the read scopes' projection
-   * union) — view-style metas leak hidden field names identically.
-   */
+  /** Makes this controller the `$with` policy source for its table's ARBAC resource. */
+  protected readonly _arbacRelationTarget: true;
+  /** Same contract as {@link AsArbacDbController.prepareRequest}. */
+  protected prepareRequest(ctx: TDbRequestContext): Promise<void>;
+  /** Same contract as {@link AsArbacDbController.transformFilter}. */
+  protected transformFilter(filter: Record<string, unknown> | undefined): Record<string, unknown>;
+  /** Same contract as {@link AsArbacDbController.transformProjection}. */
+  protected transformProjection(projection?: TProjection): TProjection | undefined;
+  /** Same contract as {@link AsArbacDbController.validateControls}. */
+  protected validateControls(controls: Record<string, unknown>, type: TDbControlsType): string | undefined;
+  /** Same contract as {@link AsArbacDbController.applyMetaOverlay}. */
   protected applyMetaOverlay(meta: TMetaResponse): Promise<TMetaResponse>;
-  /**
-   * Scope-aware field visibility — same contract as
-   * {@link AsArbacDbController.hasField}.
-   */
+  /** Same contract as {@link AsArbacDbController.authorizeForm}. */
+  protected authorizeForm(_name: string, actionNames: readonly string[]): Promise<boolean>;
+  /** Same contract as {@link AsArbacDbController.actionRowScope}. */
+  protected actionRowScope(name: string): Promise<Record<string, unknown> | undefined>;
+  /** Same contract as {@link AsArbacDbController.allowedActions}. */
+  protected allowedActions(names: readonly string[]): Promise<string[]>;
+  /** Same contract as {@link AsArbacDbController.[ARBAC_DELEGATED_AUTH]}. */
+  [ARBAC_DELEGATED_AUTH](method: string): boolean;
+  /** Same contract as {@link AsArbacDbController.hasField}. */
   protected hasField(path: string): boolean;
 }
 //#endregion
-//#region src/db/meta-projection.d.ts
+//#region src/db/as-arbac-value-help-controller.d.ts
 /**
- * Union the per-scope `projection` whitelists into the single access-control
- * projection used for FIELD-EXISTENCE decisions (`hasField` parity + `/meta`
- * pruning). Returns `undefined` when the union imposes no restriction — no
- * scopes at all, or any scope without a `projection` (a universal grant makes
- * `unionProjections` collapse to the universe `{}`).
+ * ARBAC-scoped mirror of `@atscript/moost-db`'s {@link AsValueHelpController}
+ * (bring your own backing source): the same scope contract as
+ * {@link AsArbacDbController} applied through the value-help seams.
+ *
+ * - `prepareRequest` — every route (`/query`, `/pages`, `/one`, `/meta`)
+ *   resolves the scopes first: the authorize interceptor's cached ones, else
+ *   a fresh evaluation. Denied → 403. `@Public()` / `arbacPublic` does NOT
+ *   bypass it, and a missing interceptor fails closed rather than open.
+ * - `transformFilter` — the request filter ∧ the union of scope `filter`s
+ *   (denied → match-nothing). `/one` outside the scope answers 404.
+ * - `transformProjection` — `$select` restricted to the scopes' projection
+ *   union; the PK is always kept.
+ * - `hasField` — a scope-hidden field is `Unknown field "x"` (400) in
+ *   filter / `$sort` / `$select`, and never matches `$search`.
+ * - `validateControls` — per-scope `controls` gates (e.g. `$search: false`).
+ * - `/meta` — `crud` filtered per action, `fields` / `type` pruned by the
+ *   read scopes' projection union, `searchable` dropped when no searchable
+ *   field survives.
+ *
+ * **Action names**: the data routes are re-tagged with the standard table
+ * READ action ids — `runQuery` → `query`, `runPages` → `pages`, `runGetOne`
+ * → `getOne`, `runGetOneComposite` → `getOneComposite` (`meta` / `metaForm`
+ * already match) — so `allowTableRead(resource, { scope })` grants a
+ * value-help source exactly like a table. The resource is the controller's
+ * `@ArbacResource(...)` (else the ARBAC fallback: controller id, then class
+ * name).
+ *
+ * Implementations of `query` must honor {@link hasField} for `$search` (skip
+ * hidden fields) — the ARBAC layer cannot see inside a custom search.
+ *
+ * @since 0.1.72
  */
-declare function unionScopeProjection(scopes: ArbacDbScope[]): TProjection | undefined;
+declare abstract class AsArbacValueHelpController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsValueHelpController<T, DataType> {
+  private _arbacHost?;
+  private get arbacHost();
+  protected prepareRequest(_ctx: TDbRequestContext): Promise<void>;
+  protected transformFilter(filter: FilterExpr): FilterExpr;
+  protected transformProjection(select: ValueHelpSelect<DataType> | undefined): ValueHelpSelect<DataType> | undefined;
+  protected hasField(path: string): boolean;
+  protected validateControls(controls: Record<string, unknown>, type: TDbControlsType): string | undefined;
+  protected applyMetaOverlay(meta: TMetaResponse): Promise<TMetaResponse>;
+  runQuery(url: string): Promise<import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody> | DataType[]>;
+  runPages(url: string): Promise<import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody> | {
+    data: DataType[];
+    page: number;
+    itemsPerPage: number;
+    pages: number;
+    count: number;
+  }>;
+  runGetOne(id: string): Promise<DataType | import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody>>;
+  runGetOneComposite(query: Record<string, string>): Promise<DataType | import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody>>;
+}
 /**
- * Relation names any scope explicitly grants via `with.<name>` — an explicit
- * content grant implies the relation EXISTS for this principal even when the
- * projection union does not name it (the sub-scope, not the projection, owns
- * the joined rows' policy — see {@link ArbacDbScope.with}).
+ * ARBAC-scoped mirror of `@atscript/moost-db`'s
+ * {@link AsJsonValueHelpController} (a static in-memory row set) — the same
+ * contract, action names and resource naming as
+ * {@link AsArbacValueHelpController}; `$search` already skips scope-hidden
+ * fields.
+ *
+ * ```ts
+ * @Controller('dicts/status')
+ * @ArbacResource('dict-status')
+ * class StatusDictController extends AsArbacJsonValueHelpController<typeof StatusDict> {
+ *   constructor(app: Moost) { super(StatusDict, STATUS_ROWS, app) }
+ * }
+ * // grant: allowTableRead('dict-status', { scope: () => ({ filter: { active: true } }) })
+ * ```
+ *
+ * @since 0.1.72
  */
-declare function collectWithGrantNames(scopes: ArbacDbScope[]): ReadonlySet<string>;
+declare class AsArbacJsonValueHelpController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsJsonValueHelpController<T, DataType> {
+  private _arbacHost?;
+  private get arbacHost();
+  protected prepareRequest(_ctx: TDbRequestContext): Promise<void>;
+  protected transformFilter(filter: FilterExpr): FilterExpr;
+  protected transformProjection(select: ValueHelpSelect<DataType> | undefined): ValueHelpSelect<DataType> | undefined;
+  protected hasField(path: string): boolean;
+  protected validateControls(controls: Record<string, unknown>, type: TDbControlsType): string | undefined;
+  protected applyMetaOverlay(meta: TMetaResponse): Promise<TMetaResponse>;
+  runQuery(url: string): Promise<import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody> | DataType[]>;
+  runPages(url: string): Promise<import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody> | {
+    data: DataType[];
+    page: number;
+    itemsPerPage: number;
+    pages: number;
+    count: number;
+  }>;
+  runGetOne(id: string): Promise<import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody> | DataType>;
+  runGetOneComposite(query: Record<string, string>): Promise<import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody> | DataType>;
+}
+//#endregion
+//#region src/db/relation-policy.d.ts
 /**
- * The principal's field-visibility verdict set, assembled once per request
- * (or per `/meta` overlay) and threaded through the pruning walk.
+ * Register an ARBAC DB controller as an owner of its readable's ARBAC
+ * resource, so a `$with` from another controller can evaluate the caller's
+ * own grant on the joined table. Called once per controller instance (a
+ * field initializer of the ARBAC DB controllers). Scoped per moost app and
+ * keyed by the readable's annotated type; a newer instance of the same class
+ * replaces the older one.
+ *
+ * @returns `true` (so it can initialize a field)
+ * @since 0.1.72
  */
-interface MetaVisibility {
-  /**
-   * Projection union for this level's own fields. `{}` (the universe) means
-   * unrestricted — possible when only a `with` sub-scope restricts anything.
-   */
-  allowed: TProjection;
-  /**
-   * Identifier fields reads ALWAYS return regardless of projection (the read
-   * path widens `preferredId` back in, and PK addressing requires the key) —
-   * hiding them would advertise less than reads deliver and break `/one/:id`.
-   */
-  alwaysVisible: ReadonlySet<string>;
-  /** Relation names granted via `with.<name>` (see {@link collectWithGrantNames}). */
-  withGrants: ReadonlySet<string>;
-  /**
-   * Visibility of a `with`-granted relation's JOINED fields, built from the
-   * union of its `with.<name>` sub-scopes (with the related table's own
-   * identifiers always visible). A path `rel.x.y` is checked as `x.y`
-   * against it, recursively for nested relations. The scope-driven builders
-   * ({@link buildScopeVisibility}) always supply it; a hand-built visibility
-   * without it lets granted paths through unchecked (legacy behavior).
-   */
-  relation?: (name: string) => MetaVisibility | undefined;
-  /**
-   * Precompiled `isFieldAllowed(path, allowed)`. Supplied by
-   * {@link buildScopeVisibility}; a hand-built visibility falls back to
-   * `isFieldAllowed`.
-   */
-  isAllowed?: (path: string) => boolean;
-  /** The scopes this level was built from (set by {@link buildScopeVisibility}). */
-  scopes?: ArbacDbScope[];
-  /** The table this level describes, when known (set by {@link buildScopeVisibility}). */
-  table?: VisibilityTableSource;
-  /**
-   * Fields the principal's WRITE scopes allow (union of `allowedFields`, or
-   * `"all"` for an unrestricted write grant). A field that is writable but not
-   * read-visible is NOT pruned from `/meta` — it survives with a `db.writeOnly`
-   * stamp (type only; rows/projections never carry it), so generic forms and
-   * client preflight validators can still SET sealed fields (e.g. credentials
-   * behind a read projection). Absent → nothing extra survives.
-   */
-  writable?: ReadonlySet<string> | "all";
-}
+declare function registerArbacDbTarget(controller: object): true;
 /**
- * Union of write-scope `allowedFields`; `"all"` for field-unrestricted write
- * access. Mirrors `prepareScopeOverlay`: the whitelist exists only when at
- * least one scope carries an `allowedFields` array — scoped-but-unlisted
- * writes are field-unrestricted.
+ * The ARBAC resource + action a controller's handler is authorized as — the
+ * precedence `useArbac()` applies while that handler serves a request.
+ * Resource: method `@ArbacResource` → class `@ArbacResource` → controller id
+ * → class name. Action: method `@ArbacAction` → `@DbAction` name → class
+ * `@ArbacAction` → method `@Id` → method name.
+ *
+ * @since 0.1.72
  */
-declare function collectWritableFields(scopes: ArbacDbScope[], unrestricted: boolean): ReadonlySet<string> | "all" | undefined;
+declare function resolveHandlerArbacIds(instance: object, methodName: string): {
+  resource: string;
+  action: string;
+};
+//#endregion
+//#region src/db/meta-projection.d.ts
 /**
- * Whether a flattened dot-path field exists for this principal. A
- * `with`-granted relation itself is always visible (the grant implies it);
- * a path UNDER it (`rel.x.y`) is checked as `x.y` against the relation's
- * sub-scope visibility ({@link MetaVisibility.relation}) — so a field the
- * sub-scope hides is as unknown in a `$with` sub-query as a top-level hidden
- * column is in the main query (no filter/sort value oracle).
+ * Foreign `ref` targets for `/meta` pruning: annotated type → the caller's
+ * visibility on it, or `null` when the caller cannot read it.
  */
-declare function isMetaFieldVisible(path: string, vis: MetaVisibility): boolean;
+type MetaRefTargets = ReadonlyMap<object, MetaVisibility | null>;
 /**
  * Prune a `/meta` envelope down to the fields the principal's read scopes can
  * ever surface, so a scoped UI cannot even OFFER an out-of-scope column (the
@@ -231,96 +456,50 @@ declare function isMetaFieldVisible(path: string, vis: MetaVisibility): boolean;
  *
  * - `fields` — the flat capability map (sortable/filterable flags).
  * - `type` — the serialized annotated type (what dynamic clients build
- *   tables/forms from); nested object props prune by dot-path. A relation
- *   prop visible through the projection survives whole; a `with`-granted
- *   one is pruned by its sub-scope (recursively), matching `hasField`.
- * - `relations` — entries neither projected nor `with`-granted.
+ *   tables/forms from); nested object props prune by dot-path. A visible
+ *   relation's nav prop is pruned by that relation's visibility (declared
+ *   sub-scope or the caller's own grant on the target), recursively. A
+ *   `ref` whose target field is hidden (own table) or whose target table the
+ *   caller cannot read (`refTargets`) is stripped.
+ * - `relations` — hidden relations dropped.
  * - `versionColumn` — dropped when the OCC column itself is hidden.
  *
  * NEVER mutates the input — the base controller caches the static envelope
  * (`applyMetaOverlay` contract); every pruned branch is a fresh object.
  */
-declare function pruneMetaByVisibility(meta: TMetaResponse, vis: MetaVisibility): TMetaResponse;
+declare function pruneMetaByVisibility(meta: TMetaResponse, vis: MetaVisibility, refTargets?: MetaRefTargets): TMetaResponse;
 /**
- * The slice of an atscript-db readable (table / view) the visibility walk
- * reads — a moost-db controller's `this.readable` satisfies it: identifiers
- * (always visible), nav relations (to reach the joined table) and the
- * flattened schema (to split `$select` parents by scope).
- */
-interface VisibilityTableSource {
-  primaryKeys: readonly string[];
-  preferredId: readonly string[];
-  relations?: ReadonlyMap<string, unknown>;
-  /**
-   * The target table of nav relation `navField` (atscript-db's
-   * `readable.relatedTable`); absent / `undefined` → the joined table's
-   * identifiers are not exempted.
-   */
-  relatedTable?(navField: string): VisibilityTableSource | undefined;
-  /** Flattened schema (dot-paths) — used to split `$select` parents by scope. */
-  flatMap?: ReadonlyMap<string, unknown>;
-  /** Navigation field paths — their joined descendants are not own columns. */
-  navFields?: ReadonlySet<string>;
-}
-/**
- * Build the {@link MetaVisibility} a set of read scopes implies — the single
- * structure behind `hasField`, `/meta` pruning, `$select` value stripping
- * and the `$with` overlay, so they cannot drift. Own fields: the projection
- * union (`{}` when unrestricted), precompiled into `isAllowed`. A
- * `with`-granted relation: a lazily built (memoized) child visibility over
- * the union of its `with.<name>` sub-scopes — the same sub-scopes joined rows
- * are stripped with — whose `alwaysVisible` is the related table's own PK /
- * `preferredId` (reached through `table.relatedTable`; without it, no
- * related identifier is exempt).
+ * The full ARBAC `/meta` overlay, shared by the ARBAC DB and value-help
+ * controllers.
  *
- * @param alwaysVisible - identifiers exempt from the projection; defaults to
- *   the table's PK + `preferredId`
- */
-declare function buildScopeVisibility(scopes: ArbacDbScope[], table: VisibilityTableSource | undefined, alwaysVisible?: ReadonlySet<string>): MetaVisibility;
-/**
- * Shared body of both ARBAC controllers' `hasField` overrides (BUG-3 twin of
- * the `/meta` pruning): a field outside the read-scope projection union —
- * or, for a `rel.x` path under a `with`-granted relation, outside that
- * relation's sub-scope union — must be indistinguishable from a field that
- * does not exist. Returns `true` when there are no scopes (unscoped grant).
+ * 1. `actions` and `crud` are filtered by evaluating each one exactly as its
+ *    handler is authorized (`useArbac` precedence): a crud op through its
+ *    handler method(s) — `one` via `getOne` / `getOneComposite`, `remove`
+ *    via `remove` / `removeComposite` (allowed when any is) — and an action
+ *    through its method (`@ArbacAction` → `@DbAction` name → …).
+ * 2. The FIELD surface (`fields`, serialized `type`, `relations`,
+ *    `versionColumn`) is pruned by the read scopes' visibility: the
+ *    projection union, derived-column sources, atomic JSON columns, and the
+ *    `$with` relation policy (declared `with` sub-scopes, else the caller's
+ *    own grant on the related table — no grant → relation and nav type
+ *    dropped). `ref`s to hidden targets are stripped. An allowed read op
+ *    without scopes is an unscoped grant (no field restriction; relations
+ *    still follow the relation policy). No read op allowed → no pruning:
+ *    `crud` already advertises no read surface, and write-only principals
+ *    still need `type` for their insert/update forms. PK + `preferredId` are
+ *    never pruned.
+ * 3. The search surface: `searchIndexes` reading a hidden field are dropped,
+ *    `searchable` / `vectorSearchable` / `geoSearchable` recomputed, and the
+ *    `query` / `pages` control lists lose the controls that became unusable
+ *    (`crud.geo` goes when no geo index is left).
  *
- * @param source - the controller's `this.readable`; an identifier set (the
- *   0.1.67 signature) still works, without related-table identifiers
+ * @param source - the controller's `this.readable` (identifiers, relations
+ *   and schema rules are derived from it); an identifier set (the 0.1.67
+ *   signature) still works, without them
+ * @param indexes - the controller's `indexFieldPaths()`; defaults to calling
+ *   it on the current controller when it has one
  */
-declare function isScopedFieldVisible(scopes: ArbacDbScope[], path: string, source: VisibilityTableSource | ReadonlySet<string>): boolean;
-/**
- * PK + `preferredId` for a controller's table/readable — the
- * {@link MetaVisibility.alwaysVisible} set. Kept for compatibility: the
- * controllers now pass `this.readable` and it is derived there.
- */
-declare function metaAlwaysVisibleFields(_controller: object, source: {
-  primaryKeys: readonly string[];
-  preferredId: readonly string[];
-}): ReadonlySet<string>;
-/**
- * The full ARBAC `/meta` overlay, shared by `AsArbacDbController` and
- * `AsArbacDbReadableController`: filter `actions` + `crud` by per-action
- * evaluation, then prune the FIELD surface (`fields`, serialized `type`,
- * `relations`, `versionColumn`) by the read scopes' projection union.
- *
- * Field pruning (BUG-3): a scope projection must remove fields from the META
- * entirely — `transformProjection` already strips their VALUES from every
- * read, but the envelope still advertised the full field map, so a scoped UI
- * offered columns that could never populate, and secret-bearing column NAMES
- * leaked. The pruning union comes from the read-op evaluations already
- * computed for the `crud` overlay (same `unionProjections` the read path
- * applies). An allowed read op WITHOUT scopes is an unscoped grant —
- * universe, no pruning (unchanged behavior for unscoped roles). No read op
- * allowed → the projection union is empty → no pruning: `crud` already
- * advertises no read surface, and write-only principals still need `type`
- * for their insert/update forms. PK + `preferredId` are never pruned —
- * reads always return those fields (projection widening / id addressing).
- *
- * @param source - the controller's `this.readable` (identifiers and related
- *   tables are derived from it); an identifier set (the 0.1.67 signature)
- *   still works, without related-table identifiers
- */
-declare function applyArbacMetaOverlay(meta: TMetaResponse, source: VisibilityTableSource | ReadonlySet<string>): Promise<TMetaResponse>;
+declare function applyArbacMetaOverlay(meta: TMetaResponse, source: VisibilityTableSource | ReadonlySet<string>, indexes?: readonly TDbIndexFieldPaths[]): Promise<TMetaResponse>;
 /**
  * Test-friendly internal helper — exported for unit tests and helper
  * composition; regular consumers should not call this directly.
@@ -335,6 +514,277 @@ declare function applyArbacMetaOverlay(meta: TMetaResponse, source: VisibilityTa
  */
 declare function collectMethodNames(instance: object): string[];
 //#endregion
+//#region src/db/request-scopes.d.ts
+/**
+ * The scopes resolved for the current event, or `undefined` before
+ * {@link resolveRequestScopes} ran.
+ *
+ * @since 0.1.72
+ */
+declare function cachedRequestScopes(): ArbacDbScope[] | undefined;
+/**
+ * Resolve the current event's scopes once: the ones the authorize
+ * interceptor cached, else an ARBAC evaluation of the handler's
+ * resource/action. The empty-scope rule (`normalizeScopes` from
+ * `@aooth/arbac`): an allowed grant without scopes is unrestricted (`[{}]`),
+ * a scope predicate returning nothing contributes nothing, and an allowed
+ * evaluation left with NO scope is a deny. A deny throws 403.
+ *
+ * @since 0.1.72
+ */
+declare function resolveRequestScopes(): Promise<ArbacDbScope[]>;
+/**
+ * The resolved scopes, synchronously — for the hooks that run after the
+ * entry point (`validateControls`, `transformFilter`, the write guards …).
+ * Unresolved scopes are a 403, never "unrestricted".
+ *
+ * @since 0.1.72
+ */
+declare function requireRequestScopes(): ArbacDbScope[];
+/**
+ * Shared body of the ARBAC controllers' `hasField` overrides: a field
+ * outside the read-scope visibility — hidden by the projection union, a
+ * derived field whose source is hidden, a path inside a hidden atomic JSON
+ * column, a hidden relation, or a `rel.x` path the relation's policy hides —
+ * is indistinguishable from a field that does not exist. Unresolved scopes
+ * hide every field.
+ *
+ * @since 0.1.72
+ */
+declare function requestFieldVisible(path: string, source: VisibilityTableSource | ReadonlySet<string>): boolean;
+/**
+ * Whether `path` is visible to `scopes` over `source` (see
+ * {@link requestFieldVisible}, which reads the request's scopes).
+ *
+ * @param source - the controller's `this.readable`; an identifier set (the
+ *   0.1.67 signature) still works, without relation / schema rules
+ */
+declare function isScopedFieldVisible(scopes: ArbacDbScope[], path: string, source: VisibilityTableSource | ReadonlySet<string>): boolean;
+/**
+ * Body of the ARBAC DB / value-help controllers' `prepareRequest` — every
+ * endpoint, `@DbAction` handlers included (`endpoint: "action"`, before any
+ * action id / row is read): resolve the request's scopes
+ * ({@link resolveRequestScopes} — 403 on denial, `arbacPublic` does not
+ * bypass) and, on read endpoints, the `$with` relation policy for the
+ * requested relations.
+ *
+ * @since 0.1.72
+ */
+declare function prepareArbacRequest(ctx: TDbRequestContext, readable?: VisibilityTableSource): Promise<void>;
+/**
+ * `authorizeForm` for the ARBAC DB controllers: a form is served iff the
+ * caller may run at least one of the actions that take it as input — each
+ * evaluated as the resource/action its handler is authorized as.
+ *
+ * @since 0.1.72
+ */
+declare function authorizeArbacForm(actionNames: readonly string[]): Promise<boolean>;
+/**
+ * Body of the ARBAC DB controllers' `allowedActions`: the action `names` the
+ * caller holds a grant on — each evaluated as {@link actionArbacIds} names
+ * it, exactly the `/meta` overlay's action rule (memoized per event, so the
+ * evaluations `prepareRequest` / the overlay already ran are reused).
+ *
+ * @since 0.1.72
+ */
+declare function arbacAllowedActions(names: readonly string[]): Promise<string[]>;
+/**
+ * Body of the ARBAC DB controllers' `actionRowScope`: the rows the
+ * `@DbAction` `name` may run on — the filter of the caller's grant on the
+ * action ({@link actionArbacIds}: every handler method of the action, or a
+ * class-level entry's fallback ids), including custom-field row filters and
+ * credential attenuation. No grant → a match-nothing filter (fail closed);
+ * an unrestricted grant → `undefined`. When the current request IS that
+ * action (its resolved scopes are the same evaluation), the row overlay
+ * already applies it → `undefined`. Equal filters are returned as ONE
+ * object per request.
+ *
+ * @since 0.1.72
+ */
+declare function arbacActionRowScope(name: string): Promise<Record<string, unknown> | undefined>;
+/**
+ * Body of the ARBAC controllers' `transformFilter` (and so of the row
+ * overlay `/one`, `DELETE` and `@DbAction` ids use): the user filter
+ * CONJOINED with the union of the request's scope filters.
+ *
+ * @since 0.1.72
+ */
+declare function arbacRowFilter(filter: Record<string, unknown> | undefined): Record<string, unknown>;
+//#endregion
+//#region src/db/shared-read-helpers.d.ts
+/**
+ * Restrict the user-supplied `$select` to the scopes' projection union.
+ * Returns the original projection untouched when no scope declares a
+ * projection (so caller sees the unrestricted shape). Reads the same cached
+ * visibility (`vis.allowed`) `hasField` / `/meta` pruning use, so value
+ * stripping and name hiding cannot drift.
+ *
+ * `projection` is the `$select` as moost-db parsed it: an inclusion is an
+ * ARRAY of names, an exclusion an object — both are normalized first. A
+ * requested parent (`$select=a`) narrows to what the scope shows: to the
+ * whitelisted descendants (`a.b: 1`), or — for a hidden descendant
+ * (`a.c: 0`) — to its visible children via `childrenOf` (without a schema
+ * the parent is dropped). Never the whole object, and never the empty
+ * (universe) projection: when nothing survives, the scope's own projection
+ * applies (`restrictProjection`'s ceiling fallback).
+ *
+ * An exclusion result names nested-object parents by their leaves
+ * (`{ a: 0 }` → `{ "a.b": 0, "a.c": 0 }`): flattening adapters invert an
+ * exclusion against their leaf columns, so a parent key alone would strip
+ * nothing (a scope `{ a: 0 }` would otherwise return all of `a`).
+ *
+ * @since 0.1.72
+ */
+declare function applyArbacProjection(projection: unknown, scopes: ArbacDbScope[], readable?: VisibilityTableSource): TProjection | undefined;
+/**
+ * Enforce the union of per-scope `controls` gates against the parsed
+ * Uniquery controls. Throws `HttpError(403)` on the first violation.
+ *
+ * @since 0.1.72
+ */
+declare function applyArbacControls(controls: Record<string, unknown>, scopes: ArbacDbScope[]): void;
+/**
+ * Walk the user-supplied `$with` items in `controls` and overlay each joined
+ * relation with the policy of its rows (the `$with` inherit-target policy):
+ * a relation some scope declares `with.<name>` for gets the union of those
+ * sub-scopes (parent authority — silent roles contribute nothing); any other
+ * gets the caller's OWN read scopes on the related table, as resolved in
+ * `prepareRequest` (for the request's own scopes). Filter conjoined, `$select`
+ * restricted, per-relation `controls` gates enforced, recursively.
+ *
+ * Mutates `controls` in place (matches the `validateControls` contract).
+ * Throws `HttpError(403)` if a per-relation control policy is violated. A
+ * hidden relation is skipped: moost-db (≥ 0.1.143) rejects it at every
+ * level through `hasField`, byte-for-byte like a nonexistent one.
+ *
+ * @since 0.1.72
+ */
+declare function applyArbacRelationScopes(controls: Record<string, unknown>, scopes: ArbacDbScope[], readable?: VisibilityTableSource): void;
+//#endregion
+//#region src/db/write-policy.d.ts
+/** The table surface the write guards need (`AtscriptDbTable` satisfies it). */
+interface ArbacWriteTable {
+  count(query: {
+    filter: TScopeFilter;
+    controls?: Record<string, never>;
+  }): Promise<number>;
+  getAdapter(): {
+    isInTransaction(): boolean;
+  };
+}
+/**
+ * The in-transaction write guard of the ARBAC DB layer — the body of
+ * `AsArbacDbController.guardWrite` and of `useArbacDbScope().writeOptions()`'s
+ * `guard`:
+ *
+ * - USING — every update / replace target (the exact record filter the
+ *   write uses) must match the scope filter — one count, no pre-image read
+ *   (missing or out of scope → 404);
+ * - `checkRefs` — every enforced FK the write sets must reference rows the
+ *   caller can read on the target table (→ 403);
+ * - WITH CHECK when the adapter cannot roll back — validated here, before
+ *   the write (see {@link checkArbacWrite} for the transactional path).
+ */
+declare function guardArbacWrite(ctx: TDbWriteGuardContext, scopes: readonly ArbacDbScope[], table: ArbacWriteTable, refs: RefTableSource): Promise<void>;
+/**
+ * WITH CHECK after the write, inside its transaction: every written row must
+ * match the scopes' `check` (default `filter`) — else 403 and the write rolls
+ * back. Non-transactional adapters were checked in {@link guardArbacWrite}.
+ */
+declare function checkArbacWrite(ctx: TDbWriteCheckContext, scopes: readonly ArbacDbScope[]): Promise<void>;
+/** USING for deletes: the exact row the delete targets must match the scope filter (else 404). */
+declare function guardArbacRemove(ctx: TDbRemoveGuardContext, scopes: readonly ArbacDbScope[], table: Pick<ArbacWriteTable, "count">): Promise<void>;
+//#endregion
+//#region src/db/use-arbac-db-scope.d.ts
+/**
+ * The slice of an atscript-db table {@link ArbacDbScopeHelpers.assertRowsInScope}
+ * needs — satisfied by `AtscriptDbTable` / a controller's `this.table`.
+ */
+interface ArbacScopedTable extends VisibilityTableSource {
+  resolveRowFilter(id: unknown, opts?: TRowResolveOptions): Promise<object | null | undefined>;
+  count(query: {
+    filter: TScopeFilter;
+    controls?: Record<string, never>;
+  }): Promise<number>;
+}
+/**
+ * The table surface {@link ArbacDbScopeHelpers.writeOptions} /
+ * {@link ArbacDbScopeHelpers.removeOptions} guard — satisfied by
+ * `AtscriptDbTable` / a controller's `this.table`.
+ *
+ * @since 0.1.72
+ */
+type ArbacGuardedTable = ArbacScopedTable & ArbacWriteTable & RefTableSource;
+/** The current event's merged ARBAC DB scope — returned by {@link useArbacDbScope}. */
+interface ArbacDbScopeHelpers<T = unknown> {
+  /** The evaluated scopes (one per matching rule; one composite when attenuated). */
+  scopes: ArbacDbScope<T>[];
+  /**
+   * Union of the scopes' row filters CONJOINED (`$and`) with `extra` — never
+   * spread, so `extra` can only narrow. `{}` when unrestricted.
+   */
+  filter(extra?: TScopeFilter): TScopeFilter;
+  /** Merged `set` overrides (later scopes win) — overlay them on inserted / updated data. */
+  set(): Record<string, unknown>;
+  /**
+   * Union of the scopes' effective WITH CHECK filters (`check`, defaulting to
+   * `filter`; `{}` = none) — what a written row must match. `{}` when unrestricted.
+   */
+  check(): TScopeFilter;
+  /**
+   * 404 `Not found` unless every id resolves (PK first, else a visible unique
+   * key — exactly one row per id) to a row inside the scope filter. Duplicate
+   * ids count once.
+   */
+  assertRowsInScope(table: ArbacScopedTable, ids: readonly unknown[]): Promise<void>;
+  /**
+   * `checkRefs` for rows a handler is about to insert: 403 `Referenced row
+   * "<field>" is outside your scope` unless every foreign key the scopes
+   * enforce (see {@link ArbacDbScope.checkRefs}, union rule included)
+   * references a row the caller can read on the target table. Null / absent
+   * FKs pass. The same check the ARBAC DB controllers run on their CRUD writes.
+   *
+   * @since 0.1.72
+   */
+  assertRefsInScope(table: RefTableSource, rows: ReadonlyArray<Record<string, unknown>>): Promise<void>;
+  /**
+   * `TWriteOptions` for `table.insertOne/Many`, `replaceOne` / `bulkReplace`,
+   * `updateOne` / `bulkUpdate` in a handler: the same in-transaction
+   * enforcement the ARBAC DB controllers' CRUD writes get — nested writes
+   * (`nestedWrites`, 403), USING (pre-image in scope, 404), `checkRefs` (403)
+   * and WITH CHECK (403, rolled back). `allowedFields` / `set` are not applied
+   * — overlay {@link set} yourself.
+   *
+   * @since 0.1.72
+   */
+  writeOptions<Row extends object = Record<string, unknown>>(table: ArbacGuardedTable): TWriteOptions<Row>;
+  /**
+   * `TDeleteOptions` for `table.deleteOne` in a handler: the id is pinned
+   * among in-scope rows and the row must match the scope filter (else 404) —
+   * the ARBAC DB controllers' `DELETE` enforcement.
+   *
+   * @since 0.1.72
+   */
+  removeOptions<Row extends object = Record<string, unknown>>(table: ArbacGuardedTable): TDeleteOptions<Row>;
+}
+/**
+ * The current event's merged ARBAC DB scope, for custom routes and
+ * `@DbAction` handlers that query the table directly. Resolves the event's
+ * scopes once (the ones the authorize interceptor cached, else an ARBAC
+ * evaluation of the current resource/action) — a deny, or an allowed
+ * evaluation with no scope left, throws 403.
+ *
+ * @example
+ * ```ts
+ * const scope = await useArbacDbScope<typeof Task>();
+ * await scope.assertRowsInScope(this.table, [id]);
+ * await this.table.updateMany(scope.filter({ id }), { ...patch, ...scope.set() });
+ * // A handler-side insert with the CRUD endpoints' write enforcement.
+ * await this.table.insertOne({ ...row, ...scope.set() }, scope.writeOptions(this.table));
+ * ```
+ */
+declare function useArbacDbScope<T = unknown>(): Promise<ArbacDbScopeHelpers<T>>;
+//#endregion
 //#region src/moost-arbac.d.ts
 /**
  * A DI-enabled extension of the `Arbac` class for use within Moost.
@@ -347,6 +797,55 @@ declare function collectMethodNames(instance: object): string[];
  * @template TUserAttrs - The type representing user attributes relevant to access control.
  * @template TScope - The type representing access control scopes.
  */
-declare class MoostArbac<TUserAttrs extends object, TScope extends object> extends Arbac$1<TUserAttrs, TScope> {}
+declare class MoostArbac<TUserAttrs extends object, TScope extends object> extends Arbac$1<TUserAttrs, TScope> {
+  private scopeFieldRules;
+  /**
+   * Register the conjunction rule of custom (declaration-merged) scope
+   * fields — used wherever two scope lists are conjoined into one composite
+   * scope (credential attenuation, and the `with` sub-scopes it builds). A
+   * custom field present in a conjunction without a rule fails the request
+   * with a generic 500 (never dropped: a dropped field would read as
+   * unrestricted). A rule's optional `rowFilter` turns the field into a ROW
+   * restriction every framework row path enforces (folded into each
+   * evaluated scope's `filter`). Each field is registered once; a built-in
+   * `ArbacDbScope` key is rejected.
+   *
+   * @example
+   * ```ts
+   * arbac.registerScopeFields({
+   *   teams: {
+   *     conjoin: (user, cred) => intersectTeams(user, cred),
+   *     rowFilter: (teams) => ({ teamId: { $in: teams } }),
+   *   },
+   * });
+   * ```
+   * @since 0.1.72
+   */
+  registerScopeFields(rules: TScopeFieldRules<TScope>): this;
+  /**
+   * The engine's evaluation with every custom field's `rowFilter` folded
+   * into each evaluated scope's `filter` (both passes of an attenuated
+   * evaluation, each with its own scopes) — so every consumer, direct
+   * engine calls included, sees the row restriction. A non-built-in scope
+   * key without a registered rule is warned about once.
+   */
+  evaluate<T extends string | undefined>(res: {
+    resource: string;
+    action: string;
+  }, user: {
+    id: T;
+    roles: string[];
+    attrs: TUserAttrs | ((userId: T) => TUserAttrs | Promise<TUserAttrs>);
+    attenuate?: {
+      roles?: string[];
+      attrs?: Partial<TUserAttrs>;
+      allowUnheldRoles?: boolean;
+    };
+  }): Promise<TArbacEvalResult$1<TScope>>;
+  private readonly warnedFields;
+  private readonly warnUnknownField;
+  /** The registered custom scope field rules. @since 0.1.72 */
+  getScopeFields(): TScopeFieldRules<TScope>;
+}
 //#endregion
-export { type AoothArbacClaims, Arbac, ArbacAction, ArbacAuthorize, ArbacDbScope, ArbacResource, ArbacUserProvider, ArbacUserProviderToken, AsArbacDbController, AsArbacDbReadableController, type ControlGate, type ControlsOf, type MetaVisibility, MoostArbac, type NavRelationKey, type NavTarget, type OwnFieldKey, type ProjectionOf, type TArbacCompiledRule, type TArbacEvalResult, TArbacMeta, type TArbacRole, type TArbacRoleForResource, type TArbacRule, type VisibilityTableSource, applyAllowedFieldsAndSet, applyArbacMetaOverlay, arbacAuthorizeInterceptor, arbacPatternToRegex, buildScopeVisibility, collectMethodNames, collectWithGrantNames, collectWritableFields, conjoinArbacDbScopes, enforceControlsPolicy, extractUsedControlValues, getArbacMate, getArbacScopes, isMetaFieldVisible, isScopedFieldVisible, metaAlwaysVisibleFields, pruneMetaByVisibility, unionScopeProjection, useArbac };
+export { ARBAC_DELEGATED_AUTH, type AoothArbacClaims, Arbac, ArbacAction, ArbacAuthorize, ArbacDbScope, type ArbacDbScopeHelpers, ArbacDelegatedAuth, ArbacEvaluateOptions, type ArbacGuardedTable, type ArbacRelationResolution, ArbacResource, type ArbacScopedTable, ArbacUserProvider, ArbacUserProviderToken, type ArbacWriteTable, AsArbacDbController, AsArbacDbReadableController, AsArbacJsonValueHelpController, AsArbacValueHelpController, type ConjoinArbacDbScopesOptions, type ControlGate, type ControlsOf, type MetaVisibility, MoostArbac, type NavRelationKey, type NavTarget, type OwnFieldKey, type ProjectionOf, type RefForeignKey, type RefTableSource, type ScopeVisibilityOptions, type TArbacCompiledRule, type TArbacEvalResult, TArbacMeta, type TArbacRole, type TArbacRoleForResource, type TArbacRule, type VisibilityTableSource, applyAllowedFieldsAndSet, applyArbacControls, applyArbacMetaOverlay, applyArbacProjection, applyArbacRelationScopes, arbacActionRowScope, arbacAllowedActions, arbacAuthorizeInterceptor, arbacPatternToRegex, arbacRowFilter, authorizeArbacForm, buildScopeVisibility, cachedRequestScopes, checkArbacWrite, collectMethodNames, collectWithGrantNames, collectWritableFields, conjoinArbacDbScopes, enforceControlsPolicy, extractUsedControlValues, getArbacMate, getArbacScopes, guardArbacRemove, guardArbacWrite, isMetaFieldVisible, isScopedFieldVisible, metaAlwaysVisibleFields, prepareArbacRequest, pruneMetaByVisibility, registerArbacDbTarget, requestFieldVisible, requireRequestScopes, resolveHandlerArbacIds, resolveRequestScopes, unionScopeProjection, useArbac, useArbacDbScope };