@atscript/moost-db 0.1.131 → 0.1.133

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";
@@ -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).
@@ -40,10 +42,16 @@ 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);
-  /** 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;
@@ -126,10 +134,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 +196,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`) is the core's `bucketSourceVerdict`
+ * (the same function the core path guard runs) under the HTTP-only
+ * `@db.writeOnly` veto.
  */
 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 +220,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 (¬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. */
+  bucketReason?: string;
 }
 /** One rejected path: `path` is the offending logical path, `message` the full sentence. */
 interface TCapabilityVerdict {
@@ -201,13 +234,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 +262,24 @@ 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;
+  /** 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`. */
@@ -239,18 +292,28 @@ 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.
    *
-   * 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.
+   * `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.
+   *
+   * 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.
    */
-  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,9 +339,18 @@ 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;
-  /** Bound once: the field-existence check the gate hands to `capabilities.check`. */
+   *
+   * 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 visibility check ({@link hasField}) the gate hands to `capabilities.check`. */
   private readonly _exists;
   private readonly _preferredIdSet;
   private readonly _overlayIsNoOp;
@@ -298,6 +370,20 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   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). 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 —
@@ -309,14 +395,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 +425,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.
@@ -22,7 +22,9 @@ import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, FlatOf, TCrudOp, TCrud
  *
  * 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).
@@ -40,10 +42,16 @@ 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);
-  /** 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;
@@ -126,10 +134,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 +196,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`) is the core's `bucketSourceVerdict`
+ * (the same function the core path guard runs) under the HTTP-only
+ * `@db.writeOnly` veto.
  */
 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 +220,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 (¬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. */
+  bucketReason?: string;
 }
 /** One rejected path: `path` is the offending logical path, `message` the full sentence. */
 interface TCapabilityVerdict {
@@ -201,13 +234,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 +262,24 @@ 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;
+  /** 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`. */
@@ -239,18 +292,28 @@ 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.
    *
-   * 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.
+   * `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.
+   *
+   * 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.
    */
-  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,9 +339,18 @@ 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;
-  /** Bound once: the field-existence check the gate hands to `capabilities.check`. */
+   *
+   * 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 visibility check ({@link hasField}) the gate hands to `capabilities.check`. */
   private readonly _exists;
   private readonly _preferredIdSet;
   private readonly _overlayIsNoOp;
@@ -298,6 +370,20 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   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). 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 —
@@ -309,14 +395,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 +425,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.