@atscript/moost-db 0.1.131 → 0.1.132

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, 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, 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, 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";
@@ -40,6 +40,8 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   private _serializedType?;
   /** Cached full meta response (computed lazily on first meta() call). */
   private _metaResponse?;
+  /** {@link metaCacheKey} the cached response was built for. */
+  private _metaResponseKey?;
   /** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
   private _formSchemas;
   constructor(boundType: T, controllerName: string, app: Moost, kindTag?: string);
@@ -126,10 +128,18 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   protected returnOne(result: Promise<DataType | null>): Promise<DataType | HttpError>;
   /**
    * **GET /meta** — returns the bound interface's metadata envelope. The
-   * static envelope is cached; {@link applyMetaOverlay} runs per request so
-   * subclasses can prune the response by principal.
+   * static envelope is cached (rebuilt when {@link metaCacheKey} changes);
+   * {@link applyMetaOverlay} runs per request so subclasses can prune the
+   * response by principal.
    */
   meta(): Promise<TMetaResponse>;
+  /**
+   * Identity of the inputs the cached `/meta` envelope is built from — a new
+   * value rebuilds it. Default: constant (built once). The DB readable
+   * controller returns its capability index, which is rebuilt when the
+   * adapter's capabilities change (since 0.1.132).
+   */
+  protected metaCacheKey(): unknown;
   /**
    * **GET /meta/form/:name** — returns the serialized schema of a form
    * referenced by an action's `inputForm` field. The form name is the
@@ -180,10 +190,20 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
  * `@db.table.filterable / sortable 'manual'` + `@db.column.*`). Policy applies
  * to filters and `$sort` only; `$groupBy`, `$having` keys and aggregate
  * `$field`s use the physical capability alone.
+ *
+ * A filter entry is judged by its predicate class (the core's `canFilterLeaf`):
+ * `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.
  */
 interface TFieldCapability {
-  /** A filter on this path passes the gate (adapter ∧ ¬writeOnly ∧ ¬encrypted ∧ policy). */
+  /** A value-comparison filter on this path passes the gate (adapter ∧ ¬writeOnly ∧ ¬encrypted ∧ policy). */
   filterable: boolean;
+  /** Present when `filterable` is `false` yet narrower predicates (`$exists`, `$geoWithin`) pass the gate. */
+  filterOps?: string[];
   /** A `$sort` on this path passes the gate (adapter ∧ ¬writeOnly ∧ ¬encrypted ∧ policy). */
   sortable: boolean;
   /** The path may appear in `$select`. `@db.writeOnly` fields are selectable — the seal strips them after the gate. */
@@ -194,6 +214,13 @@ interface TFieldCapability {
   filterReason?: string;
   /** 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.
+   */
+  bucketable: boolean;
+  /** Present when `bucketable` is `false` — the reason clause appended to the HTTP 400 message. */
+  bucketReason?: string;
 }
 /** One rejected path: `path` is the offending logical path, `message` the full sentence. */
 interface TCapabilityVerdict {
@@ -201,13 +228,18 @@ interface TCapabilityVerdict {
   message: string;
 }
 /** The readable members the index reads. */
-type TCapabilityReadable = Pick<AtscriptDbReadable, "type" | "fieldDescriptors" | "flatMap" | "navFields" | "relations" | "ignoredFields" | "canFilterField" | "canSortField">;
+type TCapabilityReadable = Pick<AtscriptDbReadable, "type" | "fieldDescriptors" | "flatMap" | "navFields" | "relations" | "ignoredFields" | "canFilterField" | "canSortField" | "isGeoSearchable" | "calendarBucketUnits" | "dimensions" | "measures">;
 /**
- * Capability index of one readable, built once per controller.
+ * Capability index of one readable.
  *
  * - {@link entries} feeds `/meta.fields` (listed leaves in descriptor order);
  * - {@link check} is the request gate: same inputs, same answer.
  *
+ * Built from the adapter's capabilities as they are NOW. Some are only known
+ * after schema sync (PostgreSQL learns PostGIS there), so owners rebuild the
+ * index when {@link adapterSignature} changes (see `AsDbReadableController`'s
+ * `capabilities` getter) instead of keeping a constructor-time snapshot.
+ *
  * Paths outside the index are classified by the core's `classifyQueryPath`
  * (the same rules the core backstop applies) — navigation path, nested-object
  * parent, JSON descendant (relational adapters), encrypted descendant,
@@ -224,9 +256,30 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   readonly jsonParents: ReadonlySet<string>;
   /** Descriptors carrying `@db.encrypted` (the ciphertext column on relational adapters). */
   readonly encryptedFields: ReadonlySet<string>;
+  /** Every field descriptor's `physicalName` — names a calendar-bucket alias may not take. */
+  readonly physicalNames: ReadonlySet<string>;
+  /** Calendar-bucket units the adapter groups by, in `BUCKET_UNITS` order (`/meta.bucketUnits`). */
+  readonly bucketUnits: readonly BucketUnit[];
+  /** The adapter-level capabilities this index was built against — see {@link adapterSignature}. */
+  readonly signature: string;
+  /**
+   * The adapter-level capabilities that can change after construction (geo
+   * support, calendar-bucket units): an index whose {@link signature}
+   * differs from this is stale. Any new adapter-level input the index reads
+   * must be added here.
+   */
+  static adapterSignature(source: Pick<TCapabilityReadable, "isGeoSearchable" | "calendarBucketUnits">): string;
   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;
   /** Listed leaves — the {@link TQueryPathSource} view for `classifyQueryPath`. */
   get leaves(): ReadonlyMap<string, unknown>;
   /** Nested-object parents — the {@link TQueryPathSource} view for `classifyQueryPath`. */
@@ -249,8 +302,11 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
    * 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.
    */
-  check(path: string, op: TQueryPathOp$1, exists: (path: string) => boolean): TCapabilityVerdict | undefined;
+  check(path: string, op: TQueryPathOp$1, exists: (path: string) => boolean, predicate?: TFilterPredicate): TCapabilityVerdict | undefined;
 }
 //#endregion
 //#region src/as-db-readable.controller.d.ts
@@ -276,8 +332,17 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * Per-path capability index (since 0.1.128): the ONE input both `/meta.fields`
    * and the request gate ({@link checkCapabilities}) are computed from, so
    * metadata and runtime can never diverge.
-   */
-  protected readonly capabilities: FieldCapabilityIndex;
+   *
+   * Built on first use and rebuilt whenever the adapter-level capabilities
+   * change (`FieldCapabilityIndex.adapterSignature`: geo support, calendar
+   * buckets) — PostgreSQL learns PostGIS only during schema sync, which may
+   * run after this controller is constructed, so a constructor-time snapshot
+   * would keep advertising (and gating) the pre-sync answer (since 0.1.132).
+   */
+  protected get capabilities(): FieldCapabilityIndex;
+  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`. */
   private readonly _exists;
   private readonly _preferredIdSet;
@@ -309,14 +374,29 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    *
    * Rejections use the structured envelope `{ message, statusCode: 400,
    * errors: [{ path, message }] }` — `path` is the offending logical path.
-   * After the per-path checks the core `$having` rule runs (`checkHavingKeys`:
-   * aliases or `$groupBy` fields only), so a readable mock and a real table
-   * answer alike.
+   *
+   * Expects normalized `$select` computed entries ({@link checkComputedSelect}
+   * ran first); a bucket's source is checked like any other path (op
+   * `bucket`). After the per-path checks the core `$having` rule runs
+   * (`checkHavingKeys`: aliases or `$groupBy` fields only), so a readable mock
+   * and a real table answer alike.
    */
   protected checkCapabilities(parsed: {
     filter?: FilterExpr;
     controls?: object;
   }): HttpError | undefined;
+  /**
+   * The core's shared normalizer of `$select` computed entries
+   * (`resolveCalendarBuckets`) as a 400 with the core's wording and `path`
+   * (`$select` / `$groupBy`): entry shapes, calendar-bucket unit / zone /
+   * week start / alias, "grouped queries only", "must also appear in
+   * $groupBy", alias collisions with this table's fields. Runs once per
+   * request, before {@link checkCapabilities}: at the head of
+   * {@link validateParsed} — ahead of the controls DTO, which would otherwise
+   * answer a bucket in a non-grouped query with a generic type mismatch — or
+   * explicitly on the endpoint that skips it (`geo`).
+   */
+  protected checkComputedSelect(controls: object | undefined): HttpError | undefined;
   /**
    * Root-path existence moved into {@link checkCapabilities}; the insights map
    * only serves `$with` sub-controls here — the URL parser flattens
@@ -324,7 +404,7 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * resolved against the target table through `isValidFieldPath`.
    */
   protected validateInsights(insights: Map<string, unknown>): string | undefined;
-  /** Validates $with relations against the readable. */
+  /** {@link checkComputedSelect} (before the controls DTO), then $with relations against the readable. */
   protected validateParsed(parsed: Uniquery, type: "query" | "pages" | "getOne"): HttpError | undefined;
   /**
    * Compute an embedding vector from a search term.

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, 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, 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, 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.
@@ -40,6 +40,8 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   private _serializedType?;
   /** Cached full meta response (computed lazily on first meta() call). */
   private _metaResponse?;
+  /** {@link metaCacheKey} the cached response was built for. */
+  private _metaResponseKey?;
   /** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
   private _formSchemas;
   constructor(boundType: T, controllerName: string, app: Moost, kindTag?: string);
@@ -126,10 +128,18 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   protected returnOne(result: Promise<DataType | null>): Promise<DataType | HttpError>;
   /**
    * **GET /meta** — returns the bound interface's metadata envelope. The
-   * static envelope is cached; {@link applyMetaOverlay} runs per request so
-   * subclasses can prune the response by principal.
+   * static envelope is cached (rebuilt when {@link metaCacheKey} changes);
+   * {@link applyMetaOverlay} runs per request so subclasses can prune the
+   * response by principal.
    */
   meta(): Promise<TMetaResponse>;
+  /**
+   * Identity of the inputs the cached `/meta` envelope is built from — a new
+   * value rebuilds it. Default: constant (built once). The DB readable
+   * controller returns its capability index, which is rebuilt when the
+   * adapter's capabilities change (since 0.1.132).
+   */
+  protected metaCacheKey(): unknown;
   /**
    * **GET /meta/form/:name** — returns the serialized schema of a form
    * referenced by an action's `inputForm` field. The form name is the
@@ -180,10 +190,20 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
  * `@db.table.filterable / sortable 'manual'` + `@db.column.*`). Policy applies
  * to filters and `$sort` only; `$groupBy`, `$having` keys and aggregate
  * `$field`s use the physical capability alone.
+ *
+ * A filter entry is judged by its predicate class (the core's `canFilterLeaf`):
+ * `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.
  */
 interface TFieldCapability {
-  /** A filter on this path passes the gate (adapter ∧ ¬writeOnly ∧ ¬encrypted ∧ policy). */
+  /** A value-comparison filter on this path passes the gate (adapter ∧ ¬writeOnly ∧ ¬encrypted ∧ policy). */
   filterable: boolean;
+  /** Present when `filterable` is `false` yet narrower predicates (`$exists`, `$geoWithin`) pass the gate. */
+  filterOps?: string[];
   /** A `$sort` on this path passes the gate (adapter ∧ ¬writeOnly ∧ ¬encrypted ∧ policy). */
   sortable: boolean;
   /** The path may appear in `$select`. `@db.writeOnly` fields are selectable — the seal strips them after the gate. */
@@ -194,6 +214,13 @@ interface TFieldCapability {
   filterReason?: string;
   /** 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.
+   */
+  bucketable: boolean;
+  /** Present when `bucketable` is `false` — the reason clause appended to the HTTP 400 message. */
+  bucketReason?: string;
 }
 /** One rejected path: `path` is the offending logical path, `message` the full sentence. */
 interface TCapabilityVerdict {
@@ -201,13 +228,18 @@ interface TCapabilityVerdict {
   message: string;
 }
 /** The readable members the index reads. */
-type TCapabilityReadable = Pick<AtscriptDbReadable, "type" | "fieldDescriptors" | "flatMap" | "navFields" | "relations" | "ignoredFields" | "canFilterField" | "canSortField">;
+type TCapabilityReadable = Pick<AtscriptDbReadable, "type" | "fieldDescriptors" | "flatMap" | "navFields" | "relations" | "ignoredFields" | "canFilterField" | "canSortField" | "isGeoSearchable" | "calendarBucketUnits" | "dimensions" | "measures">;
 /**
- * Capability index of one readable, built once per controller.
+ * Capability index of one readable.
  *
  * - {@link entries} feeds `/meta.fields` (listed leaves in descriptor order);
  * - {@link check} is the request gate: same inputs, same answer.
  *
+ * Built from the adapter's capabilities as they are NOW. Some are only known
+ * after schema sync (PostgreSQL learns PostGIS there), so owners rebuild the
+ * index when {@link adapterSignature} changes (see `AsDbReadableController`'s
+ * `capabilities` getter) instead of keeping a constructor-time snapshot.
+ *
  * Paths outside the index are classified by the core's `classifyQueryPath`
  * (the same rules the core backstop applies) — navigation path, nested-object
  * parent, JSON descendant (relational adapters), encrypted descendant,
@@ -224,9 +256,30 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   readonly jsonParents: ReadonlySet<string>;
   /** Descriptors carrying `@db.encrypted` (the ciphertext column on relational adapters). */
   readonly encryptedFields: ReadonlySet<string>;
+  /** Every field descriptor's `physicalName` — names a calendar-bucket alias may not take. */
+  readonly physicalNames: ReadonlySet<string>;
+  /** Calendar-bucket units the adapter groups by, in `BUCKET_UNITS` order (`/meta.bucketUnits`). */
+  readonly bucketUnits: readonly BucketUnit[];
+  /** The adapter-level capabilities this index was built against — see {@link adapterSignature}. */
+  readonly signature: string;
+  /**
+   * The adapter-level capabilities that can change after construction (geo
+   * support, calendar-bucket units): an index whose {@link signature}
+   * differs from this is stale. Any new adapter-level input the index reads
+   * must be added here.
+   */
+  static adapterSignature(source: Pick<TCapabilityReadable, "isGeoSearchable" | "calendarBucketUnits">): string;
   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;
   /** Listed leaves — the {@link TQueryPathSource} view for `classifyQueryPath`. */
   get leaves(): ReadonlyMap<string, unknown>;
   /** Nested-object parents — the {@link TQueryPathSource} view for `classifyQueryPath`. */
@@ -249,8 +302,11 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
    * 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.
    */
-  check(path: string, op: TQueryPathOp$1, exists: (path: string) => boolean): TCapabilityVerdict | undefined;
+  check(path: string, op: TQueryPathOp$1, exists: (path: string) => boolean, predicate?: TFilterPredicate): TCapabilityVerdict | undefined;
 }
 //#endregion
 //#region src/as-db-readable.controller.d.ts
@@ -276,8 +332,17 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * Per-path capability index (since 0.1.128): the ONE input both `/meta.fields`
    * and the request gate ({@link checkCapabilities}) are computed from, so
    * metadata and runtime can never diverge.
-   */
-  protected readonly capabilities: FieldCapabilityIndex;
+   *
+   * Built on first use and rebuilt whenever the adapter-level capabilities
+   * change (`FieldCapabilityIndex.adapterSignature`: geo support, calendar
+   * buckets) — PostgreSQL learns PostGIS only during schema sync, which may
+   * run after this controller is constructed, so a constructor-time snapshot
+   * would keep advertising (and gating) the pre-sync answer (since 0.1.132).
+   */
+  protected get capabilities(): FieldCapabilityIndex;
+  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`. */
   private readonly _exists;
   private readonly _preferredIdSet;
@@ -309,14 +374,29 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    *
    * Rejections use the structured envelope `{ message, statusCode: 400,
    * errors: [{ path, message }] }` — `path` is the offending logical path.
-   * After the per-path checks the core `$having` rule runs (`checkHavingKeys`:
-   * aliases or `$groupBy` fields only), so a readable mock and a real table
-   * answer alike.
+   *
+   * Expects normalized `$select` computed entries ({@link checkComputedSelect}
+   * ran first); a bucket's source is checked like any other path (op
+   * `bucket`). After the per-path checks the core `$having` rule runs
+   * (`checkHavingKeys`: aliases or `$groupBy` fields only), so a readable mock
+   * and a real table answer alike.
    */
   protected checkCapabilities(parsed: {
     filter?: FilterExpr;
     controls?: object;
   }): HttpError | undefined;
+  /**
+   * The core's shared normalizer of `$select` computed entries
+   * (`resolveCalendarBuckets`) as a 400 with the core's wording and `path`
+   * (`$select` / `$groupBy`): entry shapes, calendar-bucket unit / zone /
+   * week start / alias, "grouped queries only", "must also appear in
+   * $groupBy", alias collisions with this table's fields. Runs once per
+   * request, before {@link checkCapabilities}: at the head of
+   * {@link validateParsed} — ahead of the controls DTO, which would otherwise
+   * answer a bucket in a non-grouped query with a generic type mismatch — or
+   * explicitly on the endpoint that skips it (`geo`).
+   */
+  protected checkComputedSelect(controls: object | undefined): HttpError | undefined;
   /**
    * Root-path existence moved into {@link checkCapabilities}; the insights map
    * only serves `$with` sub-controls here — the URL parser flattens
@@ -324,7 +404,7 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * resolved against the target table through `isValidFieldPath`.
    */
   protected validateInsights(insights: Map<string, unknown>): string | undefined;
-  /** Validates $with relations against the readable. */
+  /** {@link checkComputedSelect} (before the controls DTO), then $with relations against the readable. */
   protected validateParsed(parsed: Uniquery, type: "query" | "pages" | "getOne"): HttpError | undefined;
   /**
    * Compute an embedding vector from a search term.