@atscript/moost-db 0.1.132 → 0.1.134

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { i as resolveDbSpace, n as clearDbSpaces, r as provideDbSpace, t as DEFAULT_DB_SPACE } from "./db-space-registry-CWpYwZ4R.cjs";
 import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, TSerializedAnnotatedType, TValidatorOptions, Validator } from "@atscript/typescript/utils";
-import { AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
+import { AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
 import { HttpError } from "@moostjs/event-http";
 import { Mate, Moost, TConsoleBase, TMateParamMeta, TMoostMetadata } from "moost";
 import { parseUrl } from "@uniqu/url";
@@ -22,7 +22,9 @@ import { parseUrl } from "@uniqu/url";
  *
  * Subclass responsibilities:
  * - Pass the bound interface + logical name + (optional) kind tag through super().
- * - Implement {@link hasField} so insights validation can reject unknown keys.
+ * - Implement {@link hasField} — the field-visibility hook every validated
+ *   path consults; a path it rejects gets the same `Unknown field` 400 as a
+ *   nonexistent one, so overriding it hides fields per request.
  * - Register the `/query`, `/pages`, `/one(/:id)` routes with the concrete
  *   handlers that match the data source's contract (DB readables route into
  *   aggregate/vector/search; value-help controllers just filter/sort/paginate).
@@ -45,7 +47,11 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   /** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
   private _formSchemas;
   constructor(boundType: T, controllerName: string, app: Moost, kindTag?: string);
-  /** Subclass contract: return `true` if `path` addresses a valid field on the bound source. */
+  /**
+   * Subclass contract: return `true` if `path` addresses a field that exists
+   * AND is visible to the current request — see the DB controller's override
+   * for the full list of positions that consult it.
+   */
   protected abstract hasField(path: string): boolean;
   /** Sets @db.http.path on the type metadata from the controller's computed prefix. */
   private _resolveHttpPath;
@@ -179,6 +185,13 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   protected applyMetaOverlay(meta: TMetaResponse): TMetaResponse | Promise<TMetaResponse>;
 }
 //#endregion
+//#region src/actions/id-validation.d.ts
+/** Duck-typed shape; matches `AtscriptDbReadable`'s public surface. */
+interface IdValidationSource {
+  readonly identifications: readonly TIdentification[];
+  readonly fieldDescriptors: readonly TDbFieldMeta[];
+}
+//#endregion
 //#region src/meta/field-capabilities.d.ts
 /**
  * Per-path HTTP capability of a DB readable — the single source that both the
@@ -195,9 +208,9 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
  * `filterable` is the value-comparison verdict, `filterOps` the narrower
  * predicates that still pass where it is `false`.
  *
- * A calendar-bucket source (`bucketable`) needs the physical capability, a
- * `number.timestamp` type, dimension status on a strict (dimension / measure
- * declaring) table, and an adapter with calendar-bucket units.
+ * A calendar-bucket source (`bucketable`) is the core's `bucketSourceVerdict`
+ * (the same function the core path guard runs) under the HTTP-only
+ * `@db.writeOnly` veto.
  */
 interface TFieldCapability {
   /** A value-comparison filter on this path passes the gate (adapter ∧ ¬writeOnly ∧ ¬encrypted ∧ policy). */
@@ -215,8 +228,8 @@ interface TFieldCapability {
   /** Present when `sortable` is `false` — the reason clause appended to the HTTP 400 message. */
   sortReason?: string;
   /**
-   * A calendar bucket over this path passes the gate (physical ∧ timestamp ∧
-   * (¬strict ∨ dimension) ∧ adapter has calendar buckets). Since 0.1.132.
+   * A calendar bucket over this path passes the gate (¬writeOnly ∧ the core's
+   * `bucketSourceVerdict`). Since 0.1.132.
    */
   bucketable: boolean;
   /** Present when `bucketable` is `false` — the reason clause appended to the HTTP 400 message. */
@@ -272,14 +285,8 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   private readonly _entries;
   /** Nested-object parents (never listed, always selectable) → their listed leaves. */
   private readonly _objectParents;
-  /**
-   * Declared dimensions when the table is strict (declares dimensions or
-   * measures), else `undefined` — the core rule: a grouping source, a
-   * bucketed field included, must then be a dimension.
-   */
-  private readonly _dimensions;
-  /** Paths of every JSON-value descriptor (`isJsonValueField`) — see `jsonValueAncestor`. */
-  private readonly _jsonValueParents;
+  /** What `bucketSourceVerdict` reads of the table (JSON-value parents, dimensions, measures). */
+  private readonly _bucketTable;
   /** Listed leaves — the {@link TQueryPathSource} view for `classifyQueryPath`. */
   get leaves(): ReadonlyMap<string, unknown>;
   /** Nested-object parents — the {@link TQueryPathSource} view for `classifyQueryPath`. */
@@ -292,16 +299,23 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   isPhysicallyFilterable(path: string): boolean;
   /**
    * Gate check for one path in one position. Returns `undefined` when the
-   * path is accepted. Order: navigation paths first (a nav path "exists" on
-   * the target table but is never a column here), then a listed leaf's
-   * capability (no existence lookup needed — every listed leaf is a real
-   * field), then `exists` (the readable's `isValidFieldPath`) and, for paths
-   * that exist but are not leaves, the storage classification.
+   * path is accepted.
+   *
+   * `exists` runs FIRST, for every path (since 0.1.133): it is the
+   * controller's `hasField`, the visibility hook subclasses narrow per
+   * request (e.g. a projection-scoped viewer). A path it rejects answers
+   * `Unknown field "x"` exactly like a nonexistent one — never a capability
+   * or navigation hint, which would reveal the field and let a filter or
+   * sort on it act as a value oracle. Before 0.1.133 listed leaves and
+   * navigation paths skipped it.
    *
-   * Existence deliberately runs BEFORE the JSON / encrypted classification:
-   * an untyped descendant of a JSON column (`address.nope`) is reported as
-   * `Unknown field`, not as "inside JSON-stored column" — clients pin that
-   * wording, so do not "align" it with the core backstop's text.
+   * Then: navigation paths (a nav path exists on the target table but is
+   * never a column here), a listed leaf's capability, and for other paths
+   * the storage classification. Existence also runs BEFORE the JSON /
+   * encrypted classification: an untyped descendant of a JSON column
+   * (`address.nope`) is reported as `Unknown field`, not as "inside
+   * JSON-stored column" — clients pin that wording, so do not "align" it
+   * with the core backstop's text.
    *
    * `predicate` is a filter entry's class (`collectQueryPaths` records it per
    * occurrence); it only matters for `op === "filter"` on a listed leaf.
@@ -343,8 +357,17 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private _capabilities?;
   /** `/meta` is a projection of {@link capabilities}: a rebuilt index rebuilds the cached envelope. */
   protected metaCacheKey(): unknown;
-  /** Bound once: the field-existence check the gate hands to `capabilities.check`. */
+  /** Bound once: the visibility check ({@link hasField}) the gate hands to `capabilities.check`. */
   private readonly _exists;
+  /**
+   * Id-resolution options (since 0.1.134): `{ isFieldVisible: hasField }`
+   * when a subclass overrides {@link hasField}, else `undefined` (the default
+   * accepts every real path, so resolution stays unfiltered). A unique index
+   * over a hidden field is never an identification.
+   */
+  protected readonly _idOpts: TIdResolveOptions | undefined;
+  /** Narrowed id sources, one stable object per distinct visible-identification set. */
+  private readonly _idSources;
   private readonly _preferredIdSet;
   private readonly _overlayIsNoOp;
   /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
@@ -360,9 +383,34 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    */
   private readonly _invertibleFields;
   constructor(app: Moost, readable?: AtscriptDbReadable<T>);
+  /**
+   * The identifications this request may address rows through (since
+   * 0.1.134): the readable's own, minus unique indexes over fields
+   * {@link hasField} hides. Used by `/one?…`, `DELETE /?…` and action `ids`.
+   * Stable per distinct outcome, so per-source caches keyed on it hit.
+   */
+  get idSource(): IdValidationSource;
   private _collectInvertibleFields;
   private _collectQuantityRefs;
   private _collectAnnotated;
+  /**
+   * THE field-visibility hook: every gated path consults it before any
+   * capability check (since 0.1.133) — filter keys (inside `$and` / `$or` /
+   * `$not`, existence predicates included), `$sort`, `$select`,
+   * `$groupBy`, `$having` keys, aggregate and calendar-bucket `$field`s,
+   * `$with` relation names and sub-query paths, and the `$search` fallback
+   * fields. A path it rejects is answered exactly like a nonexistent one
+   * (`Unknown field "x"` / `Unknown relation "x"`), so override it to hide
+   * fields per request (read scopes). Since 0.1.134 it also governs row
+   * identification — a unique index over a hidden field is not an
+   * identification for `/one/:id`, `/one?…`, `DELETE`, a PK-less `PATCH` or
+   * an action id (primary key and `preferredId` always are) — and the
+   * nested-object 400 hint lists visible leaves only. The default accepts every real path
+   * (`isValidFieldPath`). `/meta` does NOT consult it — prune hidden fields
+   * there with `applyMetaOverlay`. Native text search and vector search
+   * (`$vector` names an index) run inside the engine over its indexes, out of
+   * this hook's reach — keep hidden fields out of those indexes.
+   */
   protected hasField(path: string): boolean;
   /**
    * Structural capability gate (since 0.1.128): walks the PARSED query —
@@ -432,6 +480,14 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private widenPreferredIdProjection;
   private _widenArrayProjection;
   private _widenMapProjection;
+  /**
+   * The logical paths an exclusion keeps. A path goes when it, an ancestor
+   * or a descendant is excluded: excluding an object parent excludes its
+   * whole subtree, and a kept parent would carry an excluded child back
+   * (its other leaves stay listed on their own). Before 0.1.134 only the
+   * exact paths were dropped, so `$select=-a` still returned `a`'s leaves.
+   */
+  private _invertExclusion;
   /**
    * Auto-includes the sibling-ref field whenever its `@db.amount.currency.ref`
    * / `@db.unit.ref` quantity is selected — UI must never get a value without
@@ -502,7 +558,12 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * family (count vs no-count).
    */
   private _runReadWithActions;
-  /** Pick the first identification (PK or unique index) whose fields are all present in the query. */
+  /**
+   * Pick the first identification (PK or unique index) whose fields are all
+   * present in the query. A unique index over a field {@link hasField} hides
+   * is not a candidate (since 0.1.134) — `?hidden=x` answers exactly like
+   * `?nope=x`, so it cannot probe whether a row with that value exists.
+   */
   protected extractIdShape(query: Record<string, string>): Record<string, unknown> | HttpError;
   /**
    * **GET /query** — returns an array of records or a count.
@@ -643,14 +704,17 @@ declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
    * several table operations.
    */
   protected withTransaction<R>(fn: () => Promise<R>): Promise<R>;
+  /** The table write call's trailing options — see {@link _hookArgs}. */
+  private readonly _writeArgs;
+  /** `deleteOne`'s trailing options — see {@link _hookArgs}. */
+  private readonly _removeArgs;
   /**
-   * The table write call's trailing options: `[{ guard }]` only when
-   * `guardWrite` is overridden, else nothing (the table is called exactly as
-   * an unmodified controller always called it).
+   * A table call's trailing options, built once: `guard` only when the guard
+   * hook is overridden, `isFieldVisible` only when `hasField` is (an id or a
+   * PK-less payload never resolves through a hidden unique key) — else
+   * nothing, so an unmodified controller calls the table exactly as before.
    */
-  private _writeArgs;
-  /** `deleteOne`'s trailing options: `[{ guard }]` only when `guardRemove` is overridden. */
-  private _removeArgs;
+  private _hookArgs;
   /** Resolves a hook result: `undefined` aborts with `abortMessage`, an `Error` is thrown, anything else passes. */
   private _checkHook;
   /** Runs `onWrite` and re-applies the shape gate to its output (a non-object is a 500 "Not saved"). */
@@ -1507,13 +1571,6 @@ declare function getControllerFormType(ctor: Function, name: string): TAtscriptA
 /** Discover actions on a controller, memoized per ctor. `info`-only callers map `e => e.info`. */
 declare function discoverActions(controllerCtor: Function, app: Moost, logger: TConsoleBase): TDbActionEnvelope[];
 //#endregion
-//#region src/actions/id-validation.d.ts
-/** Duck-typed shape; matches `AtscriptDbReadable`'s public surface. */
-interface IdValidationSource {
-  readonly identifications: readonly TIdentification[];
-  readonly fieldDescriptors: readonly TDbFieldMeta[];
-}
-//#endregion
 //#region src/actions/id-cache.d.ts
 declare const useDbActionId: import("@wooksjs/event-core").WookComposable<{
   load: () => Promise<Record<string, unknown>>;

package/dist/index.d.mts

@@ -3,7 +3,7 @@ import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, TSerializ
 import { HttpError } from "@moostjs/event-http";
 import { Mate, Moost, TConsoleBase, TMateParamMeta, TMoostMetadata } from "moost";
 import { parseUrl } from "@uniqu/url";
-import { AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
+import { AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
 //#region src/as-readable.controller.d.ts
 /**
  * Abstract base class for read-only HTTP controllers over an Atscript interface.
@@ -22,7 +22,9 @@ import { AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TC
  *
  * Subclass responsibilities:
  * - Pass the bound interface + logical name + (optional) kind tag through super().
- * - Implement {@link hasField} so insights validation can reject unknown keys.
+ * - Implement {@link hasField} — the field-visibility hook every validated
+ *   path consults; a path it rejects gets the same `Unknown field` 400 as a
+ *   nonexistent one, so overriding it hides fields per request.
  * - Register the `/query`, `/pages`, `/one(/:id)` routes with the concrete
  *   handlers that match the data source's contract (DB readables route into
  *   aggregate/vector/search; value-help controllers just filter/sort/paginate).
@@ -45,7 +47,11 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   /** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
   private _formSchemas;
   constructor(boundType: T, controllerName: string, app: Moost, kindTag?: string);
-  /** Subclass contract: return `true` if `path` addresses a valid field on the bound source. */
+  /**
+   * Subclass contract: return `true` if `path` addresses a field that exists
+   * AND is visible to the current request — see the DB controller's override
+   * for the full list of positions that consult it.
+   */
   protected abstract hasField(path: string): boolean;
   /** Sets @db.http.path on the type metadata from the controller's computed prefix. */
   private _resolveHttpPath;
@@ -179,6 +185,13 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   protected applyMetaOverlay(meta: TMetaResponse): TMetaResponse | Promise<TMetaResponse>;
 }
 //#endregion
+//#region src/actions/id-validation.d.ts
+/** Duck-typed shape; matches `AtscriptDbReadable`'s public surface. */
+interface IdValidationSource {
+  readonly identifications: readonly TIdentification[];
+  readonly fieldDescriptors: readonly TDbFieldMeta[];
+}
+//#endregion
 //#region src/meta/field-capabilities.d.ts
 /**
  * Per-path HTTP capability of a DB readable — the single source that both the
@@ -195,9 +208,9 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
  * `filterable` is the value-comparison verdict, `filterOps` the narrower
  * predicates that still pass where it is `false`.
  *
- * A calendar-bucket source (`bucketable`) needs the physical capability, a
- * `number.timestamp` type, dimension status on a strict (dimension / measure
- * declaring) table, and an adapter with calendar-bucket units.
+ * A calendar-bucket source (`bucketable`) is the core's `bucketSourceVerdict`
+ * (the same function the core path guard runs) under the HTTP-only
+ * `@db.writeOnly` veto.
  */
 interface TFieldCapability {
   /** A value-comparison filter on this path passes the gate (adapter ∧ ¬writeOnly ∧ ¬encrypted ∧ policy). */
@@ -215,8 +228,8 @@ interface TFieldCapability {
   /** Present when `sortable` is `false` — the reason clause appended to the HTTP 400 message. */
   sortReason?: string;
   /**
-   * A calendar bucket over this path passes the gate (physical ∧ timestamp ∧
-   * (¬strict ∨ dimension) ∧ adapter has calendar buckets). Since 0.1.132.
+   * A calendar bucket over this path passes the gate (¬writeOnly ∧ the core's
+   * `bucketSourceVerdict`). Since 0.1.132.
    */
   bucketable: boolean;
   /** Present when `bucketable` is `false` — the reason clause appended to the HTTP 400 message. */
@@ -272,14 +285,8 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   private readonly _entries;
   /** Nested-object parents (never listed, always selectable) → their listed leaves. */
   private readonly _objectParents;
-  /**
-   * Declared dimensions when the table is strict (declares dimensions or
-   * measures), else `undefined` — the core rule: a grouping source, a
-   * bucketed field included, must then be a dimension.
-   */
-  private readonly _dimensions;
-  /** Paths of every JSON-value descriptor (`isJsonValueField`) — see `jsonValueAncestor`. */
-  private readonly _jsonValueParents;
+  /** What `bucketSourceVerdict` reads of the table (JSON-value parents, dimensions, measures). */
+  private readonly _bucketTable;
   /** Listed leaves — the {@link TQueryPathSource} view for `classifyQueryPath`. */
   get leaves(): ReadonlyMap<string, unknown>;
   /** Nested-object parents — the {@link TQueryPathSource} view for `classifyQueryPath`. */
@@ -292,16 +299,23 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   isPhysicallyFilterable(path: string): boolean;
   /**
    * Gate check for one path in one position. Returns `undefined` when the
-   * path is accepted. Order: navigation paths first (a nav path "exists" on
-   * the target table but is never a column here), then a listed leaf's
-   * capability (no existence lookup needed — every listed leaf is a real
-   * field), then `exists` (the readable's `isValidFieldPath`) and, for paths
-   * that exist but are not leaves, the storage classification.
+   * path is accepted.
+   *
+   * `exists` runs FIRST, for every path (since 0.1.133): it is the
+   * controller's `hasField`, the visibility hook subclasses narrow per
+   * request (e.g. a projection-scoped viewer). A path it rejects answers
+   * `Unknown field "x"` exactly like a nonexistent one — never a capability
+   * or navigation hint, which would reveal the field and let a filter or
+   * sort on it act as a value oracle. Before 0.1.133 listed leaves and
+   * navigation paths skipped it.
    *
-   * Existence deliberately runs BEFORE the JSON / encrypted classification:
-   * an untyped descendant of a JSON column (`address.nope`) is reported as
-   * `Unknown field`, not as "inside JSON-stored column" — clients pin that
-   * wording, so do not "align" it with the core backstop's text.
+   * Then: navigation paths (a nav path exists on the target table but is
+   * never a column here), a listed leaf's capability, and for other paths
+   * the storage classification. Existence also runs BEFORE the JSON /
+   * encrypted classification: an untyped descendant of a JSON column
+   * (`address.nope`) is reported as `Unknown field`, not as "inside
+   * JSON-stored column" — clients pin that wording, so do not "align" it
+   * with the core backstop's text.
    *
    * `predicate` is a filter entry's class (`collectQueryPaths` records it per
    * occurrence); it only matters for `op === "filter"` on a listed leaf.
@@ -343,8 +357,17 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private _capabilities?;
   /** `/meta` is a projection of {@link capabilities}: a rebuilt index rebuilds the cached envelope. */
   protected metaCacheKey(): unknown;
-  /** Bound once: the field-existence check the gate hands to `capabilities.check`. */
+  /** Bound once: the visibility check ({@link hasField}) the gate hands to `capabilities.check`. */
   private readonly _exists;
+  /**
+   * Id-resolution options (since 0.1.134): `{ isFieldVisible: hasField }`
+   * when a subclass overrides {@link hasField}, else `undefined` (the default
+   * accepts every real path, so resolution stays unfiltered). A unique index
+   * over a hidden field is never an identification.
+   */
+  protected readonly _idOpts: TIdResolveOptions | undefined;
+  /** Narrowed id sources, one stable object per distinct visible-identification set. */
+  private readonly _idSources;
   private readonly _preferredIdSet;
   private readonly _overlayIsNoOp;
   /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
@@ -360,9 +383,34 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    */
   private readonly _invertibleFields;
   constructor(app: Moost, readable?: AtscriptDbReadable<T>);
+  /**
+   * The identifications this request may address rows through (since
+   * 0.1.134): the readable's own, minus unique indexes over fields
+   * {@link hasField} hides. Used by `/one?…`, `DELETE /?…` and action `ids`.
+   * Stable per distinct outcome, so per-source caches keyed on it hit.
+   */
+  get idSource(): IdValidationSource;
   private _collectInvertibleFields;
   private _collectQuantityRefs;
   private _collectAnnotated;
+  /**
+   * THE field-visibility hook: every gated path consults it before any
+   * capability check (since 0.1.133) — filter keys (inside `$and` / `$or` /
+   * `$not`, existence predicates included), `$sort`, `$select`,
+   * `$groupBy`, `$having` keys, aggregate and calendar-bucket `$field`s,
+   * `$with` relation names and sub-query paths, and the `$search` fallback
+   * fields. A path it rejects is answered exactly like a nonexistent one
+   * (`Unknown field "x"` / `Unknown relation "x"`), so override it to hide
+   * fields per request (read scopes). Since 0.1.134 it also governs row
+   * identification — a unique index over a hidden field is not an
+   * identification for `/one/:id`, `/one?…`, `DELETE`, a PK-less `PATCH` or
+   * an action id (primary key and `preferredId` always are) — and the
+   * nested-object 400 hint lists visible leaves only. The default accepts every real path
+   * (`isValidFieldPath`). `/meta` does NOT consult it — prune hidden fields
+   * there with `applyMetaOverlay`. Native text search and vector search
+   * (`$vector` names an index) run inside the engine over its indexes, out of
+   * this hook's reach — keep hidden fields out of those indexes.
+   */
   protected hasField(path: string): boolean;
   /**
    * Structural capability gate (since 0.1.128): walks the PARSED query —
@@ -432,6 +480,14 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private widenPreferredIdProjection;
   private _widenArrayProjection;
   private _widenMapProjection;
+  /**
+   * The logical paths an exclusion keeps. A path goes when it, an ancestor
+   * or a descendant is excluded: excluding an object parent excludes its
+   * whole subtree, and a kept parent would carry an excluded child back
+   * (its other leaves stay listed on their own). Before 0.1.134 only the
+   * exact paths were dropped, so `$select=-a` still returned `a`'s leaves.
+   */
+  private _invertExclusion;
   /**
    * Auto-includes the sibling-ref field whenever its `@db.amount.currency.ref`
    * / `@db.unit.ref` quantity is selected — UI must never get a value without
@@ -502,7 +558,12 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * family (count vs no-count).
    */
   private _runReadWithActions;
-  /** Pick the first identification (PK or unique index) whose fields are all present in the query. */
+  /**
+   * Pick the first identification (PK or unique index) whose fields are all
+   * present in the query. A unique index over a field {@link hasField} hides
+   * is not a candidate (since 0.1.134) — `?hidden=x` answers exactly like
+   * `?nope=x`, so it cannot probe whether a row with that value exists.
+   */
   protected extractIdShape(query: Record<string, string>): Record<string, unknown> | HttpError;
   /**
    * **GET /query** — returns an array of records or a count.
@@ -643,14 +704,17 @@ declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
    * several table operations.
    */
   protected withTransaction<R>(fn: () => Promise<R>): Promise<R>;
+  /** The table write call's trailing options — see {@link _hookArgs}. */
+  private readonly _writeArgs;
+  /** `deleteOne`'s trailing options — see {@link _hookArgs}. */
+  private readonly _removeArgs;
   /**
-   * The table write call's trailing options: `[{ guard }]` only when
-   * `guardWrite` is overridden, else nothing (the table is called exactly as
-   * an unmodified controller always called it).
+   * A table call's trailing options, built once: `guard` only when the guard
+   * hook is overridden, `isFieldVisible` only when `hasField` is (an id or a
+   * PK-less payload never resolves through a hidden unique key) — else
+   * nothing, so an unmodified controller calls the table exactly as before.
    */
-  private _writeArgs;
-  /** `deleteOne`'s trailing options: `[{ guard }]` only when `guardRemove` is overridden. */
-  private _removeArgs;
+  private _hookArgs;
   /** Resolves a hook result: `undefined` aborts with `abortMessage`, an `Error` is thrown, anything else passes. */
   private _checkHook;
   /** Runs `onWrite` and re-applies the shape gate to its output (a non-object is a 500 "Not saved"). */
@@ -1507,13 +1571,6 @@ declare function getControllerFormType(ctor: Function, name: string): TAtscriptA
 /** Discover actions on a controller, memoized per ctor. `info`-only callers map `e => e.info`. */
 declare function discoverActions(controllerCtor: Function, app: Moost, logger: TConsoleBase): TDbActionEnvelope[];
 //#endregion
-//#region src/actions/id-validation.d.ts
-/** Duck-typed shape; matches `AtscriptDbReadable`'s public surface. */
-interface IdValidationSource {
-  readonly identifications: readonly TIdentification[];
-  readonly fieldDescriptors: readonly TDbFieldMeta[];
-}
-//#endregion
 //#region src/actions/id-cache.d.ts
 declare const useDbActionId: import("@wooksjs/event-core").WookComposable<{
   load: () => Promise<Record<string, unknown>>;