@atscript/moost-db 0.1.150 → 0.1.152

package/dist/index.d.cts

@@ -6,6 +6,33 @@ import { Mate, Moost, TConsoleBase, TMateParamMeta, TMoostMetadata } from "moost
 import { parseUrl } from "@uniqu/url";
 import { EventContext } from "@wooksjs/event-core";
 
+//#region src/meta/meta-cache.d.ts
+/**
+ * `/meta` identity memo (since 0.1.151). Each layer that turns the cached
+ * envelope into a request's `/meta` object memoizes its output per INPUT
+ * identity and per the request-dependent answers it reads (the key), so
+ * equal inputs give the same object across requests. The final object is
+ * then registered with wooks' `prerenderJson` (JSON serialized once, weak
+ * ETag from the bytes).
+ *
+ * Soundness: a memoized object is never mutated (the `applyMetaOverlay`
+ * contract), so its identity implies its bytes; every key covers every
+ * request-dependent input its layer reads. Inputs that are not themselves
+ * stable (an overlay that builds a fresh object per request) are not memoized —
+ * their output is computed per request, as before, and gets no ETag.
+ */
+/** Memoized variants per input object, then per key — one per controller instance. */
+type TMetaVariants = WeakMap<object, Map<string, object>>;
+/**
+ * Marks a `/meta` payload your override memoizes (an `applyMetaOverlay`
+ * variant, a `metaForm` projection) as reusable: it is deep-frozen and, when
+ * served again, sent from its serialized-once JSON with an `ETag`. Return the
+ * same object for the same inputs only — its bytes are fixed from now on.
+ *
+ * @since 0.1.151
+ */
+declare function stableMeta<T extends object>(obj: T): T;
+//#endregion
 //#region src/http-path.d.ts
 /** The published path of every model one app serves (`null`: mounted, published nowhere). */
 interface THttpPathScope {
@@ -76,6 +103,18 @@ interface TDbRequestContext {
    */
   readonly onConflict?: "ignore";
 }
+/**
+ * HTTP caching of `GET /meta` and `GET /meta/form/:name` — see
+ * {@link AsReadableController.metaHttpCaching}.
+ *
+ * @since 0.1.151
+ */
+interface TDbMetaHttpCaching {
+  /** `Cache-Control` value (default `"private, no-cache"`); not set when the response already has one. */
+  cacheControl?: string;
+  /** Request headers the response varies by, merged into `Vary` (default `["Authorization", "Cookie"]`). */
+  vary?: readonly string[];
+}
 /** Control DTO a {@link AsReadableController.validateControls} call checks against. @since 0.1.143 (`"geo"`) */
 type TDbControlsType = "query" | "pages" | "getOne" | "geo";
 /**
@@ -137,6 +176,12 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   private _metaResponseKey?;
   /** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
   private _formSchemas;
+  /**
+   * @internal Memoized `/meta` variants of this controller (own mount path,
+   * index visibility, decorations, delegated actions) — per input object, then
+   * per layer-prefixed key; see `meta/meta-cache.ts`.
+   */
+  protected readonly _metaVariants: TMetaVariants;
   /**
    * @param opts.canonical Multi-mount models only: marks (`true`) or excludes
    *   (`false`) this controller as the model's published value-help route
@@ -313,8 +358,38 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * static envelope is cached (rebuilt when {@link metaCacheKey} changes);
    * {@link applyMetaOverlay} runs per request so subclasses can prune the
    * response by principal.
+   *
+   * Since 0.1.151 the response is HTTP-cacheable ({@link metaHttpCaching}):
+   * `Cache-Control: private, no-cache`, `Vary: Authorization, Cookie` and —
+   * when the payload is the same object as for an earlier request with the
+   * same inputs — a weak `ETag` computed from the serialized bytes, so a
+   * matching `If-None-Match` answers `304 Not Modified`. The JSON is then
+   * serialized once, not per request.
    */
   meta(): Promise<TMetaResponse>;
+  /**
+   * HTTP caching of `GET /meta` and `GET /meta/form/:name` (since 0.1.151).
+   * Default `{}`: `Cache-Control: private, no-cache` (kept when the response
+   * already carries one), `Vary: Authorization, Cookie` (merged into an
+   * existing `Vary`), and a weak `ETag` from the response bytes with `304`
+   * on a matching `If-None-Match`. Return `false` to send none of it (the
+   * pre-0.1.151 response), or override the header values — e.g.
+   * `{ cacheControl: "no-store" }` for deployments where no browser may keep
+   * a copy.
+   *
+   * The `ETag` is a hash of the final bytes, computed after every overlay:
+   * a request whose principal sees a different `/meta` gets a different tag
+   * (a `200`), so a `304` only ever confirms the bytes the client already
+   * holds. A refused request (`prepareRequest` throwing) is answered with its
+   * error, never `304`.
+   */
+  protected metaHttpCaching(): TDbMetaHttpCaching | false;
+  /**
+   * Applies {@link metaHttpCaching} to the current response and — when `body`
+   * is identity-stable (a cached / memoized object) — registers it for
+   * prerendering with an ETag (deep-frozen in dev / test).
+   */
+  private _serveMeta;
   /**
    * The root of a controller's own `/meta` carries its own mount as
    * `db.http.path` (a secondary mount answers with its own route; references to
@@ -323,6 +398,8 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * cached envelope.
    */
   private _withOwnHttpPath;
+  /** {@link _withOwnHttpPath} for the mount `own`. */
+  private _ownHttpPathOf;
   /**
    * The `/meta` payload for the current request — the cached envelope
    * through {@link applyMetaOverlay} — WITHOUT the `/meta` route's
@@ -386,6 +463,12 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * composables). The cached envelope MUST NOT be mutated — see
    * `docs/http/permissions.md` for the full contract, including the
    * "discoverability only" caveat.
+   *
+   * `/meta`'s serialize-once memo and `ETag` (since 0.1.151) need a stable
+   * object: return the envelope itself when nothing changes, or memoize your
+   * outputs and return them through `stableMeta()` (deep-freezes and marks
+   * them) — never mutate one afterwards. A fresh object per request is
+   * correct, just served without an `ETag`.
    */
   protected applyMetaOverlay(meta: TMetaResponse): TMetaResponse | Promise<TMetaResponse>;
 }
@@ -1106,6 +1189,8 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    */
   protected get capabilities(): FieldCapabilityIndex;
   private _capabilities?;
+  /** The adapter answers {@link capabilities} last confirmed its index against (identity fast path). */
+  private _capabilityInputs?;
   /** The client relational-predicate gate (since 0.1.147), built on first use — see {@link _relationGate}. */
   private _relGate?;
   /**
@@ -1136,6 +1221,12 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private readonly _derivedSource;
   /** `@db.writeOnly` paths of `$with` target readables, collected once per target. */
   private readonly _targetWriteOnly;
+  /** The forced exclusion `$select` per sealed set (see {@link _sealSelect}). */
+  private readonly _exclusionBySealed;
+  /** The objects of {@link _exclusionBySealed}. */
+  private readonly _forcedExclusions;
+  /** {@link widenPreferredIdProjection} of each forced exclusion. */
+  private readonly _widenedExclusions;
   /** Own leaf paths per readable (bound + `$with` targets), see {@link _leavesOf}. */
   private readonly _targetLeaves;
   private _indexFieldPathsCache?;
@@ -1261,6 +1352,10 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
     filter?: FilterExpr;
     controls?: object;
   }): HttpError | undefined;
+  /** {@link checkCapabilities} reusing `refs` (the walk it makes) when the method is not overridden. */
+  private _checkCapabilitiesWith;
+  /** The walk of the `parsed` in flight, handed to {@link checkCapabilities} (sync, cleared after). */
+  private _sharedRefs?;
   /**
    * The core's shared normalizer of `$select` computed entries
    * (`normalizeComputedSelect`) as a 400 with the core's wording and `path`
@@ -1377,6 +1472,8 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * `@db.column.searchable` fallback when any of its fields is visible).
    */
   private _applyIndexVisibility;
+  /** {@link _applyIndexVisibility} for the given answers. */
+  private _narrowIndexVisibility;
   /**
    * Compute an embedding vector from a search term.
    * Override in subclass to integrate with your embedding provider (OpenAI, etc.).
@@ -1541,6 +1638,12 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * read endpoint then passes to {@link _runReadWithActions}.
    */
   private _projectRead;
+  /**
+   * {@link widenPreferredIdProjection} of a sealed `$select` — memoized for the
+   * forced exclusion of a read without `$select` (one object per sealed set,
+   * see {@link _sealSelect}): its widening depends on the controller alone.
+   */
+  private _widenSealed;
   private widenPreferredIdProjection;
   private _widenArrayProjection;
   private _widenMapProjection;
@@ -2555,6 +2658,13 @@ declare class AsJsonValueHelpController<T extends TAtscriptAnnotatedType = TAtsc
     data: DataType[];
     count: number;
   }>;
+  /**
+   * `field`'s lowercased values by position in {@link rows} (the `$search`
+   * haystack). An entry is used only while the row still holds the value it
+   * was lowercased from (`src`), so rows edited in place stay correct.
+   */
+  private _lowercased;
+  private _haystack?;
   protected getOne(id: string | number): Promise<DataType | null>;
   /**
    * Ports the value-help `$sort` grammar to the shared engine's `{ field: 1 |
@@ -3578,4 +3688,4 @@ declare const REL_FILTER_CLIENT_MAX_DEPTH = 3;
  */
 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 TDbResolveQueryInput, TDbResolveQueryOpts, 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 };
+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, TDbMetaHttpCaching, TDbParsedRequest, type TDbQueryTargetOpts, type TDbRemoveGuardContext, TDbRequestContext, TDbRequestEndpoint, type TDbResolveQueryInput, TDbResolveQueryOpts, 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, stableMeta, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, useDbActionTarget, validationErrorTransform };

package/dist/index.d.mts

@@ -6,6 +6,33 @@ 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, 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/meta/meta-cache.d.ts
+/**
+ * `/meta` identity memo (since 0.1.151). Each layer that turns the cached
+ * envelope into a request's `/meta` object memoizes its output per INPUT
+ * identity and per the request-dependent answers it reads (the key), so
+ * equal inputs give the same object across requests. The final object is
+ * then registered with wooks' `prerenderJson` (JSON serialized once, weak
+ * ETag from the bytes).
+ *
+ * Soundness: a memoized object is never mutated (the `applyMetaOverlay`
+ * contract), so its identity implies its bytes; every key covers every
+ * request-dependent input its layer reads. Inputs that are not themselves
+ * stable (an overlay that builds a fresh object per request) are not memoized —
+ * their output is computed per request, as before, and gets no ETag.
+ */
+/** Memoized variants per input object, then per key — one per controller instance. */
+type TMetaVariants = WeakMap<object, Map<string, object>>;
+/**
+ * Marks a `/meta` payload your override memoizes (an `applyMetaOverlay`
+ * variant, a `metaForm` projection) as reusable: it is deep-frozen and, when
+ * served again, sent from its serialized-once JSON with an `ETag`. Return the
+ * same object for the same inputs only — its bytes are fixed from now on.
+ *
+ * @since 0.1.151
+ */
+declare function stableMeta<T extends object>(obj: T): T;
+//#endregion
 //#region src/http-path.d.ts
 /** The published path of every model one app serves (`null`: mounted, published nowhere). */
 interface THttpPathScope {
@@ -76,6 +103,18 @@ interface TDbRequestContext {
    */
   readonly onConflict?: "ignore";
 }
+/**
+ * HTTP caching of `GET /meta` and `GET /meta/form/:name` — see
+ * {@link AsReadableController.metaHttpCaching}.
+ *
+ * @since 0.1.151
+ */
+interface TDbMetaHttpCaching {
+  /** `Cache-Control` value (default `"private, no-cache"`); not set when the response already has one. */
+  cacheControl?: string;
+  /** Request headers the response varies by, merged into `Vary` (default `["Authorization", "Cookie"]`). */
+  vary?: readonly string[];
+}
 /** Control DTO a {@link AsReadableController.validateControls} call checks against. @since 0.1.143 (`"geo"`) */
 type TDbControlsType = "query" | "pages" | "getOne" | "geo";
 /**
@@ -137,6 +176,12 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   private _metaResponseKey?;
   /** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
   private _formSchemas;
+  /**
+   * @internal Memoized `/meta` variants of this controller (own mount path,
+   * index visibility, decorations, delegated actions) — per input object, then
+   * per layer-prefixed key; see `meta/meta-cache.ts`.
+   */
+  protected readonly _metaVariants: TMetaVariants;
   /**
    * @param opts.canonical Multi-mount models only: marks (`true`) or excludes
    *   (`false`) this controller as the model's published value-help route
@@ -313,8 +358,38 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * static envelope is cached (rebuilt when {@link metaCacheKey} changes);
    * {@link applyMetaOverlay} runs per request so subclasses can prune the
    * response by principal.
+   *
+   * Since 0.1.151 the response is HTTP-cacheable ({@link metaHttpCaching}):
+   * `Cache-Control: private, no-cache`, `Vary: Authorization, Cookie` and —
+   * when the payload is the same object as for an earlier request with the
+   * same inputs — a weak `ETag` computed from the serialized bytes, so a
+   * matching `If-None-Match` answers `304 Not Modified`. The JSON is then
+   * serialized once, not per request.
    */
   meta(): Promise<TMetaResponse>;
+  /**
+   * HTTP caching of `GET /meta` and `GET /meta/form/:name` (since 0.1.151).
+   * Default `{}`: `Cache-Control: private, no-cache` (kept when the response
+   * already carries one), `Vary: Authorization, Cookie` (merged into an
+   * existing `Vary`), and a weak `ETag` from the response bytes with `304`
+   * on a matching `If-None-Match`. Return `false` to send none of it (the
+   * pre-0.1.151 response), or override the header values — e.g.
+   * `{ cacheControl: "no-store" }` for deployments where no browser may keep
+   * a copy.
+   *
+   * The `ETag` is a hash of the final bytes, computed after every overlay:
+   * a request whose principal sees a different `/meta` gets a different tag
+   * (a `200`), so a `304` only ever confirms the bytes the client already
+   * holds. A refused request (`prepareRequest` throwing) is answered with its
+   * error, never `304`.
+   */
+  protected metaHttpCaching(): TDbMetaHttpCaching | false;
+  /**
+   * Applies {@link metaHttpCaching} to the current response and — when `body`
+   * is identity-stable (a cached / memoized object) — registers it for
+   * prerendering with an ETag (deep-frozen in dev / test).
+   */
+  private _serveMeta;
   /**
    * The root of a controller's own `/meta` carries its own mount as
    * `db.http.path` (a secondary mount answers with its own route; references to
@@ -323,6 +398,8 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * cached envelope.
    */
   private _withOwnHttpPath;
+  /** {@link _withOwnHttpPath} for the mount `own`. */
+  private _ownHttpPathOf;
   /**
    * The `/meta` payload for the current request — the cached envelope
    * through {@link applyMetaOverlay} — WITHOUT the `/meta` route's
@@ -386,6 +463,12 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * composables). The cached envelope MUST NOT be mutated — see
    * `docs/http/permissions.md` for the full contract, including the
    * "discoverability only" caveat.
+   *
+   * `/meta`'s serialize-once memo and `ETag` (since 0.1.151) need a stable
+   * object: return the envelope itself when nothing changes, or memoize your
+   * outputs and return them through `stableMeta()` (deep-freezes and marks
+   * them) — never mutate one afterwards. A fresh object per request is
+   * correct, just served without an `ETag`.
    */
   protected applyMetaOverlay(meta: TMetaResponse): TMetaResponse | Promise<TMetaResponse>;
 }
@@ -1106,6 +1189,8 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    */
   protected get capabilities(): FieldCapabilityIndex;
   private _capabilities?;
+  /** The adapter answers {@link capabilities} last confirmed its index against (identity fast path). */
+  private _capabilityInputs?;
   /** The client relational-predicate gate (since 0.1.147), built on first use — see {@link _relationGate}. */
   private _relGate?;
   /**
@@ -1136,6 +1221,12 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private readonly _derivedSource;
   /** `@db.writeOnly` paths of `$with` target readables, collected once per target. */
   private readonly _targetWriteOnly;
+  /** The forced exclusion `$select` per sealed set (see {@link _sealSelect}). */
+  private readonly _exclusionBySealed;
+  /** The objects of {@link _exclusionBySealed}. */
+  private readonly _forcedExclusions;
+  /** {@link widenPreferredIdProjection} of each forced exclusion. */
+  private readonly _widenedExclusions;
   /** Own leaf paths per readable (bound + `$with` targets), see {@link _leavesOf}. */
   private readonly _targetLeaves;
   private _indexFieldPathsCache?;
@@ -1261,6 +1352,10 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
     filter?: FilterExpr;
     controls?: object;
   }): HttpError | undefined;
+  /** {@link checkCapabilities} reusing `refs` (the walk it makes) when the method is not overridden. */
+  private _checkCapabilitiesWith;
+  /** The walk of the `parsed` in flight, handed to {@link checkCapabilities} (sync, cleared after). */
+  private _sharedRefs?;
   /**
    * The core's shared normalizer of `$select` computed entries
    * (`normalizeComputedSelect`) as a 400 with the core's wording and `path`
@@ -1377,6 +1472,8 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * `@db.column.searchable` fallback when any of its fields is visible).
    */
   private _applyIndexVisibility;
+  /** {@link _applyIndexVisibility} for the given answers. */
+  private _narrowIndexVisibility;
   /**
    * Compute an embedding vector from a search term.
    * Override in subclass to integrate with your embedding provider (OpenAI, etc.).
@@ -1541,6 +1638,12 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * read endpoint then passes to {@link _runReadWithActions}.
    */
   private _projectRead;
+  /**
+   * {@link widenPreferredIdProjection} of a sealed `$select` — memoized for the
+   * forced exclusion of a read without `$select` (one object per sealed set,
+   * see {@link _sealSelect}): its widening depends on the controller alone.
+   */
+  private _widenSealed;
   private widenPreferredIdProjection;
   private _widenArrayProjection;
   private _widenMapProjection;
@@ -2555,6 +2658,13 @@ declare class AsJsonValueHelpController<T extends TAtscriptAnnotatedType = TAtsc
     data: DataType[];
     count: number;
   }>;
+  /**
+   * `field`'s lowercased values by position in {@link rows} (the `$search`
+   * haystack). An entry is used only while the row still holds the value it
+   * was lowercased from (`src`), so rows edited in place stay correct.
+   */
+  private _lowercased;
+  private _haystack?;
   protected getOne(id: string | number): Promise<DataType | null>;
   /**
    * Ports the value-help `$sort` grammar to the shared engine's `{ field: 1 |
@@ -3578,4 +3688,4 @@ declare const REL_FILTER_CLIENT_MAX_DEPTH = 3;
  */
 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 TDbResolveQueryInput, TDbResolveQueryOpts, 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 };
+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, TDbMetaHttpCaching, TDbParsedRequest, type TDbQueryTargetOpts, type TDbRemoveGuardContext, TDbRequestContext, TDbRequestEndpoint, type TDbResolveQueryInput, TDbResolveQueryOpts, 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, stableMeta, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, useDbActionTarget, validationErrorTransform };