@atscript/db 0.1.130 → 0.1.132

package/dist/index.cjs

@@ -1,11 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_error = require("./db-error-C4JuLcvb.cjs");
-const require_db_view = require("./db-view-hkwQ-fHJ.cjs");
-const require_validator = require("./validator-lkCJKuoo.cjs");
+const require_db_error = require("./db-error-DTkkeu5b.cjs");
+const require_db_view = require("./db-view-CuFAhzwF.cjs");
+const require_validator = require("./validator-BtZbcLN2.cjs");
 const require_consts = require("./consts-BzRfCcH2.cjs");
 const require_ops = require("./ops.cjs");
-let node_crypto = require("node:crypto");
 let _uniqu_core = require("@uniqu/core");
+let node_crypto = require("node:crypto");
 //#region src/encryption.ts
 const ENVELOPE_VERSION = "aes1";
 const ALGORITHM = "aes-256-gcm";
@@ -382,6 +382,7 @@ exports.$remove = require_ops.$remove;
 exports.$replace = require_ops.$replace;
 exports.$update = require_ops.$update;
 exports.$upsert = require_ops.$upsert;
+exports.ALL_BUCKET_UNITS = require_db_view.ALL_BUCKET_UNITS;
 exports.ApplicationIntegrity = require_db_view.ApplicationIntegrity;
 exports.AtscriptDbReadable = require_db_view.AtscriptDbReadable;
 exports.AtscriptDbTable = require_db_view.AtscriptDbTable;
@@ -401,10 +402,13 @@ exports.NoopLogger = require_db_view.NoopLogger;
 exports.RelationalFieldMapper = require_db_view.RelationalFieldMapper;
 exports.TableMetadata = require_db_view.TableMetadata;
 exports.UniquSelect = require_db_view.UniquSelect;
+exports.acceptedOperatorsHint = require_db_view.acceptedOperatorsHint;
 exports.assertGeoPoint = require_db_view.assertGeoPoint;
 exports.assertNoVersionWrites = require_db_view.assertNoVersionWrites;
+exports.bucketTimeZoneUnavailable = require_db_error.bucketTimeZoneUnavailable;
 exports.buildDbValidator = require_validator.buildDbValidator;
 exports.buildValidationContext = require_validator.buildValidationContext;
+exports.canFilterLeaf = require_db_view.canFilterLeaf;
 exports.checkHavingKeys = require_db_view.checkHavingKeys;
 exports.classifyQueryPath = require_db_view.classifyQueryPath;
 exports.collectQueryPaths = require_db_view.collectQueryPaths;
@@ -427,10 +431,12 @@ exports.guardPath = require_db_view.guardPath;
 exports.guardPaths = require_db_view.guardPaths;
 exports.guardQuery = require_db_view.guardQuery;
 exports.isAtscriptDbView = require_db_view.isAtscriptDbView;
+exports.isBucketableField = require_db_view.isBucketableField;
 exports.isDbFieldOp = require_ops.isDbFieldOp;
 exports.isEmptyObject = require_validator.isEmptyObject;
 exports.isGeoIndexableType = require_db_view.isGeoIndexableType;
 exports.isGeoPointType = require_db_view.isGeoPointType;
+exports.isJsonValueField = require_db_view.isJsonValueField;
 exports.isNavRelation = require_validator.isNavRelation;
 exports.isPlainObject = require_validator.isPlainObject;
 Object.defineProperty(exports, "isPrimitive", {
@@ -439,7 +445,10 @@ Object.defineProperty(exports, "isPrimitive", {
 		return _uniqu_core.isPrimitive;
 	}
 });
+exports.jsonValueAncestor = require_db_view.jsonValueAncestor;
+exports.narrowerFilterOps = require_db_view.narrowerFilterOps;
 exports.reconcileCas = require_ops.reconcileCas;
+exports.resolveCalendarBuckets = require_db_view.resolveCalendarBuckets;
 exports.resolveDesignType = require_db_view.resolveDesignType;
 exports.separateCas = require_ops.separateCas;
 exports.separateFieldOps = require_ops.separateFieldOps;

package/dist/index.d.cts

@@ -1,9 +1,10 @@
-import { $ as TDbWriteAction, A as TCrudPermissions, At as findAncestorInSet, B as TDbForeignKey, C as NullableOptional, Ct as TWriteOptions, D as TCascadeTarget, Dt as UniqueryControls, E as TCascadeResolver, Et as Uniquery, F as TDbCollation, Ft as UniquSelect, G as TDbInsertResult, H as TDbIndexField, I as TDbDefaultFn, J as TDbRelation, K as TDbObjectKind, L as TDbDefaultValue, M as TDbActionIntent, Mt as isGeoPointType, N as TDbActionLevel, Nt as NoopLogger, O as TColumnDiff, Ot as WithRelation, P as TDbActionProcessor, Pt as TGenericLogger, Q as TDbUpdateResult, R as TDbDeleteResult, S as NavPropsOf, St as TValueFormatterPair, T as PrimaryKeyOf, Tt as TypedWithRelation, U as TDbIndexType, V as TDbIndex, W as TDbInsertManyResult, X as TDbRemoveGuardContext, Y as TDbRemoveGuard, Z as TDbStorageType, _ as DbQuery, _t as TSearchIndexInfo, a as TDbEncryptionOptions, at as TExistingForeignKey, b as FilterExpr, bt as TTableResolver, c as BaseDbAdapter, ct as TFkLookupResolver, d as AggregateFn, dt as TIdentification, et as TDbWriteGuard, f as AggregateQuery, ft as TMetaResponse, g as DbPatch, gt as TRelationInfo, h as DbControls, ht as TReferencingForeignKey, i as DbEncryption, it as TExistingColumn, j as TDbActionInfo, jt as isGeoIndexableType, k as TCrudOp, kt as TableMetadata, l as AggregateControls, lt as TFkLookupTarget, m as AtscriptDbWritable, mt as TPrimaryKeyChange, n as DbResponse, nt as TDeleteOptions, o as DocumentFieldMapper, ot as TExistingTableOption, p as AggregateResult, pt as TMetadataOverrides, q as TDbReferentialAction, r as resolveDesignType, rt as TEnsureTableOptions, s as FieldMappingStrategy, st as TFieldMeta, t as AtscriptDbReadable, tt as TDbWriteGuardContext, u as AggregateExpr, ut as TIdDescriptor, v as DbRow, vt as TSyncColumnResult, w as OwnPropsOf, wt as TWriteTableResolver, x as FlatOf, xt as TTouchManyOptions, y as FieldOpsFor, yt as TTableOptionDiff, z as TDbFieldMeta } from "./db-readable-B7eYWS5q.cjs";
+import { $ as TDbWriteGuardContext, A as TDbActionIntent, At as isGeoPointType, B as TDbIndexField, Bt as NoopLogger, C as PrimaryKeyOf, Ct as TypedWithRelation, D as TCrudOp, Dt as TableMetadata, E as TColumnDiff, Et as WithRelation, F as TDbDefaultValue, Ft as resolveDesignType, G as TDbReferentialAction, H as TDbInsertManyResult, Ht as UniquSelect, I as TDbDeleteResult, It as DbEncryption, J as TDbRemoveGuardContext, K as TDbRelation, L as TDbFieldMeta, Lt as TDbEncryptionOptions, M as TDbActionProcessor, Mt as BaseDbAdapter, N as TDbCollation, Nt as AtscriptDbReadable, O as TCrudPermissions, Ot as findAncestorInSet, P as TDbDefaultFn, Pt as DbResponse, Q as TDbWriteGuard, R as TDbForeignKey, Rt as DocumentFieldMapper, S as OwnPropsOf, St as TWriteTableResolver, T as TCascadeTarget, Tt as UniqueryControls, U as TDbInsertResult, V as TDbIndexType, Vt as TGenericLogger, W as TDbObjectKind, X as TDbUpdateResult, Y as TDbStorageType, Z as TDbWriteAction, _ as FieldOpsFor, _t as TTableOptionDiff, a as jsonValueAncestor, at as TFieldMeta, b as NavPropsOf, bt as TValueFormatterPair, c as AggregateExpr, ct as TIdDescriptor, d as AggregateResult, dt as TMetadataOverrides, et as TDeleteOptions, f as AtscriptDbWritable, ft as TPrimaryKeyChange, g as DbRow, gt as TSyncColumnResult, h as DbQuery, ht as TSearchIndexInfo, i as isJsonValueField, it as TExistingTableOption, j as TDbActionLevel, jt as ALL_BUCKET_UNITS, k as TDbActionInfo, kt as isGeoIndexableType, l as AggregateFn, lt as TIdentification, m as DbPatch, mt as TRelationInfo, n as TResolvedBucket, nt as TExistingColumn, o as resolveCalendarBuckets, ot as TFkLookupResolver, p as DbControls, pt as TReferencingForeignKey, q as TDbRemoveGuard, r as isBucketableField, rt as TExistingForeignKey, s as AggregateControls, st as TFkLookupTarget, t as TBucketFieldSource, tt as TEnsureTableOptions, u as AggregateQuery, ut as TMetaResponse, v as FilterExpr, vt as TTableResolver, w as TCascadeResolver, wt as Uniquery, x as NullableOptional, xt as TWriteOptions, y as FlatOf, yt as TTouchManyOptions, z as TDbIndex, zt as FieldMappingStrategy } from "./buckets-BvoYYQ2Q.cjs";
 import { _ as separateFieldOps, a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.cjs";
-import { a as TViewColumnMapping, c as AtscriptQueryFieldRef, d as TViewJoin, f as TViewPlan, g as NativeIntegrity, h as IntegrityStrategy, i as AtscriptDbView, l as AtscriptQueryNode, m as AtscriptDbTable, n as TAdapterFactory, o as isAtscriptDbView, p as translateQueryTree, r as TDbSpaceOptions, s as AtscriptQueryComparison, t as DbSpace, u as AtscriptRef } from "./db-space-C2UCnGHd.cjs";
-import { _ as DbErrorCode, a as buildValidationContext, c as isNavRelation, d as TArrayPatch, f as TDbPatch, g as DbError, h as CasMismatchError, l as isEmptyObject, m as CasExhaustedError, n as ValidatorMode, p as getKeyProps, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as isPlainObject } from "./validator-wBARmD68.cjs";
+import { BucketExpr, BucketUnit, CalendarBucketLabel, ComputedExpr, ResolvedBucket, WeekStart } from "./agg.cjs";
+import { a as TViewColumnMapping, c as AtscriptQueryFieldRef, d as TViewJoin, f as TViewPlan, g as NativeIntegrity, h as IntegrityStrategy, i as AtscriptDbView, l as AtscriptQueryNode, m as AtscriptDbTable, n as TAdapterFactory, o as isAtscriptDbView, p as translateQueryTree, r as TDbSpaceOptions, s as AtscriptQueryComparison, t as DbSpace, u as AtscriptRef } from "./db-space-Cslq5Dux.cjs";
+import { _ as DbErrorCode, a as buildValidationContext, c as isNavRelation, d as TArrayPatch, f as TDbPatch, g as DbError, h as CasMismatchError, l as isEmptyObject, m as CasExhaustedError, n as ValidatorMode, p as getKeyProps, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as isPlainObject, v as bucketTimeZoneUnavailable } from "./validator-CewfnGZj.cjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
-import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
+import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, ResolvedBucket as ResolvedBucket$1, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
 
 //#region src/shared/consts.d.ts
 /**
@@ -23,7 +24,8 @@ declare const DEFAULT_DB_SPACE = "default";
 declare class RelationalFieldMapper extends FieldMappingStrategy {
   reconstructFromRead(row: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
   translateQuery(query: Uniquery$1, meta: TableMetadata): DbQuery;
-  translateAggregateQuery(query: AggregateQuery$1, meta: TableMetadata): DbQuery;
+  /** The flattened column of a logical path (`contact.email` → `contact__email`). */
+  protected physicalPath(logical: string, meta: TableMetadata): string;
   /**
    * Overrides the base `translateFilter` to use `leafByLogical` for key resolution
    * (handles flattened nested paths like `contact.email` → `contact__email`).
@@ -100,21 +102,29 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
  * - `$geoWithin` on a non-geoPoint field → `FILTER_TYPE_MISMATCH`
  * - `$geoWithin` with a malformed circle → `INVALID_QUERY`
  * - `$geoWithin` on an adapter without geo support → `GEO_NOT_SUPPORTED`
+ * - `$exists` with a non-boolean operand → `INVALID_QUERY`
+ * - malformed `$select` computed entries / `$groupBy` entries, calendar
+ *   buckets outside grouped queries or with a bad unit / zone / alias →
+ *   `INVALID_QUERY` (the shared normalizer, `resolveCalendarBuckets`)
+ * - a calendar bucket over a non-timestamp field → `INVALID_QUERY`; a unit
+ *   the adapter's `calendarBucketUnits()` lacks → `BUCKET_NOT_SUPPORTED`
  * - every filter / `$sort` / `$select` / `$groupBy` / `$having` / aggregate
  *   path must resolve to physical storage on THIS adapter and pass the
- *   adapter's `canFilterField` / `canSortField` → `INVALID_QUERY`
- *   (see {@link guardPaths}). Runs after the checks above so `ENC_*` codes
- *   keep firing first for encrypted subtrees.
+ *   capability its position (for a filter entry: its predicate class, see
+ *   {@link canFilterLeaf}) needs → `INVALID_QUERY` (see {@link guardPaths}).
+ *   Runs after the checks above so `ENC_*` codes keep firing first for
+ *   encrypted subtrees.
  */
 /** Validates a `[lng, lat]` tuple (GeoJSON coordinate order). */
 declare function assertGeoPoint(point: unknown, path: string): asserts point is [number, number];
 /**
  * Walks a filter expression, rejecting encrypted-field references and
- * validating `$geoWithin` operator nodes.
+ * validating operator operands: `$geoWithin` shapes and the boolean
+ * `$exists` operand (this is the one owner of that rule).
  */
 declare function guardFilter(meta: TableMetadata, adapter: BaseDbAdapter, filter: FilterExpr$1 | undefined, encCode?: "ENC_FIELD_FILTER" | "ENC_FIELD_AGG"): void;
 /** The query positions a field path can appear in. */
-type TQueryPathOp = "filter" | "sort" | "select" | "groupBy" | "having" | "aggregate";
+type TQueryPathOp = "filter" | "sort" | "select" | "groupBy" | "having" | "aggregate" /** The source field of a calendar bucket (`{ $bucket, $field }` in `$select`). Since 0.1.132. */ | "bucket";
 /** Query shape accepted by {@link guardPaths} / {@link collectQueryPaths} — the raw (pre-translation) uniqu controls. */
 interface TGuardedQuery {
   filter?: FilterExpr$1;
@@ -137,23 +147,64 @@ declare function unsupportedOperatorMessage(op: string): string;
  * walker so programmatic callers get the same acceptance set.
  */
 declare function sortFieldNames(sort: unknown): string[];
+/**
+ * The operator class a filter entry needs from its field (since 0.1.132):
+ * - `compare` — value comparison (bare values, `$eq`, `$gt`, `$in`, `$regex`, any mix);
+ * - `geo` — a `$geoWithin` entry;
+ * - `exists` — an entry whose sole operator is `$exists`.
+ */
+type TFilterPredicate = "compare" | "geo" | "exists";
+/** One filter entry, collected per occurrence: its key and the predicate class its operators need. */
+interface TFilterRef {
+  path: string;
+  predicate: TFilterPredicate;
+}
+/** The adapter-shaped capability {@link canFilterLeaf} consults (a `BaseDbAdapter` or a readable). */
+type TFilterCapabilitySource = Pick<BaseDbAdapter, "canFilterField" | "isGeoSearchable">;
+/** The operator each non-`compare` predicate class stands for, in `filterOps` order. */
+/**
+ * Whether a stored leaf physically supports a filter predicate of this class
+ * — the one rule the core path guard and moost-db's HTTP capability index
+ * both apply:
+ *
+ * - `compare` → `adapter.canFilterField(fd)`;
+ * - `exists` → any stored column: it tests whether the column holds a value
+ *   (SQL `IS [NOT] NULL`), never its content, so the scalar veto (JSON /
+ *   array storage on relational adapters) does not apply;
+ * - `geo` → a `db.geoPoint` leaf on a geo-searchable adapter.
+ *
+ * `@db.encrypted` vetoes every class.
+ */
+declare function canFilterLeaf(fd: TDbFieldMeta, predicate: TFilterPredicate, adapter: TFilterCapabilitySource): boolean;
+/**
+ * The operators of the non-`compare` predicate classes a leaf physically
+ * accepts — named in a value-comparison rejection by the core guard, and
+ * listed (under the HTTP policy) as `/meta.fields[P].filterOps`.
+ */
+declare function narrowerFilterOps(fd: TDbFieldMeta, adapter: TFilterCapabilitySource): string[];
+/** The rejection suffix naming {@link narrowerFilterOps} — `""` when there are none. */
+declare function acceptedOperatorsHint(ops: readonly string[]): string;
 /** Every logical path a parsed query references, grouped by position (since 0.1.128). */
 interface TQueryPathRefs {
-  /** Filter keys (recursing through `$and` / `$or` / `$not`), minus the geo predicates below. */
-  filter: string[];
   /**
-   * Filter keys whose predicate is `$geoWithin`. Their shape and index support
-   * are validated by `guardFilter`, so the core path guard skips the adapter's
-   * scalar filter veto for them; the HTTP gate checks them like any filter path.
+   * Filter entries (recursing through `$and` / `$or` / `$not`), one per
+   * occurrence, each with its predicate class (since 0.1.132; replaces the
+   * `string[]` + `geoFilter` split).
    */
-  geoFilter: string[];
+  filter: TFilterRef[];
   sort: string[];
   select: string[];
+  /** Grouped FIELD paths — calendar-bucket aliases are not listed (their sources are in {@link bucket}). */
   groupBy: string[];
   having: string[];
   /** Aggregate `$field`s (`*` excluded). Only populated in aggregate mode. */
   aggregate: string[];
-  /** `true` in aggregate mode: `$select` entries are aggregate expressions, aliases are exempt in `$sort` / `$having`. */
+  /** Calendar-bucket source `$field`s (since 0.1.132). Only populated in aggregate mode. */
+  bucket: string[];
+  /**
+   * `true` in aggregate mode: `$select` computed entries (aggregates, calendar
+   * buckets) are collected and their aliases are exempt in `$sort` / `$having`.
+   */
   aggregateMode: boolean;
   /**
    * First filter-node `$`-key that is not `$and` / `$or` / `$not`. uniqu's
@@ -168,10 +219,13 @@ interface TQueryPathRefs {
  * visited — they are validated against their target relation separately.
  *
  * Aggregate mode is `aggregate` when given, else the presence of `$groupBy`.
- * In aggregate mode `$select` entries are aggregate expressions whose
- * `$field` is collected and whose alias (`$as`, else `fn_field` — the core's
- * `resolveAlias`) is exempted from `$sort` / `$having`; outside it non-string
- * `$select` entries are ignored (the projection seal handles them).
+ * In aggregate mode `$select` computed entries are collected by kind — an
+ * aggregate's `$field` into `aggregate`, a calendar bucket's into `bucket` —
+ * and their aliases (`$as`, else uniqu's `resolveAlias`) are exempted from
+ * `$sort` / `$having`; a bucket alias is also dropped from `groupBy`, which
+ * lists grouped fields only.
+ *
+ * Entry shapes are not checked here — see `resolveCalendarBuckets`.
  */
 declare function collectQueryPaths(query: TGuardedQuery, aggregate?: boolean): TQueryPathRefs;
 /** What a logical path is on THIS readable / adapter (since 0.1.128). */
@@ -211,21 +265,22 @@ declare function classifyQueryPath(source: TQueryPathSource, path: string): {
  * metadata and adapter capability — the classification of
  * {@link classifyQueryPath} plus the position's physical requirement:
  *
- * - a leaf → physical capability (`canFilterField` / `canSortField`;
- *   `$select` always passes);
+ * - a leaf → physical capability (`canSortField` for `$sort`; for a filter
+ *   entry {@link canFilterLeaf} of its `predicate` class; `canFilterField`
+ *   for `$groupBy` / `$having` / aggregate `$field`s; `$select` always passes);
+ *   a calendar-bucket source must also be a timestamp field
+ *   (`isBucketableField`);
  * - a nested-object parent → only `$select`, and only when it expands to
  *   leaf columns (`selectExpansion`);
  * - everything else is rejected.
  *
- * `geoPredicate` marks a filter entry whose operator is `$geoWithin`: its
- * shape and index support were already validated by {@link guardFilter}, so
- * the adapter's scalar `canFilterField` veto does not apply.
+ * `predicate` is a filter entry's class; other positions leave the default.
  *
  * Messages are the short programmatic forms; the HTTP wording (moost-db's
  * `FieldCapabilityIndex`, with `$with` hints and leaf lists) is what clients
  * see and is authoritative — the HTTP gate always answers first.
  */
-declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: string, op: TQueryPathOp, geoPredicate?: boolean): void;
+declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: string, op: TQueryPathOp, predicate?: TFilterPredicate): void;
 /**
  * Core backstop for every read / aggregate / mutation-filter entry point:
  * each referenced path (see {@link collectQueryPaths}) must exist on THIS
@@ -233,21 +288,29 @@ declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: st
  * {@link guardPath}). Adapters may therefore assume every path they receive
  * is physical.
  *
- * In aggregate mode (`aggregate = true`) `$select` entries are aggregate
- * expressions whose `$field` is checked, `$groupBy` fields are checked, and
- * aggregate aliases (`$as` or `fn_field`) are exempt in `$sort` / `$having`.
+ * Entry shapes are the caller's to normalize first (`resolveCalendarBuckets`
+ * — {@link guardQuery} / {@link guardAggregate} do).
+ *
+ * In aggregate mode (`aggregate = true`) `$select` computed entries have
+ * their `$field` checked (aggregates as `aggregate`, calendar buckets as
+ * `bucket`), `$groupBy` fields are checked, and computed aliases (`$as` or
+ * the default) are exempt in `$sort` / `$having`.
  *
  * Returns the collected refs so callers can run further structural rules
  * (see {@link checkHavingKeys}) without walking the query again.
  */
 declare function guardPaths(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined, aggregate?: boolean): TQueryPathRefs | undefined;
-/** Shared read-path guard: filter + $sort encryption checks, then the path guard. */
+/**
+ * Shared read-path guard: filter + $sort encryption checks, the `$select`
+ * normalizer (a calendar bucket is invalid outside a grouped query), then
+ * the path guard.
+ */
 declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined): void;
 /**
- * `$having` is a post-aggregation filter, so a key is either an aggregate
- * alias (`$as`, else `fn_field` — already exempt in {@link collectQueryPaths})
- * or a `$groupBy` field (exact logical-path match: `metadata.clicks` grouped
- * stays valid). Any other key — a real but non-grouped column included — is
+ * `$having` is a post-aggregation filter, so a key is either a computed
+ * alias (aggregate or calendar bucket — already exempt in
+ * {@link collectQueryPaths}) or a `$groupBy` field (exact logical-path
+ * match: `metadata.clicks` grouped stays valid). Any other key — a real but non-grouped column included — is
  * rejected here, once, for SDK and HTTP callers alike, instead of by the
  * engine (PostgreSQL / MySQL error, SQLite tolerance, Mongo `[]`). Returns
  * the first offending key as an error entry (`path` = the bare key, as the
@@ -259,11 +322,15 @@ declare function checkHavingKeys(refs: TQueryPathRefs): {
 } | undefined;
 /**
  * Aggregate-path guard: $groupBy / $select / $having encryption refs + filter
- * + $sort, then the path guard, then the `$having` key rule
+ * + $sort, then the path guard, then the adapter's calendar-bucket units
+ * (`BUCKET_NOT_SUPPORTED`), then the `$having` key rule
  * ({@link checkHavingKeys} — after the path guard so an unknown key still
  * reads `Unknown field`).
+ *
+ * `buckets` are the query's resolved calendar buckets when the caller already
+ * ran `resolveCalendarBuckets` (resolved here otherwise).
  */
-declare function guardAggregate(meta: TableMetadata, adapter: BaseDbAdapter, query: AggregateQuery$1): void;
+declare function guardAggregate(meta: TableMetadata, adapter: BaseDbAdapter, query: AggregateQuery$1, resolved?: readonly ResolvedBucket$1[]): void;
 //#endregion
 //#region src/with-optimistic-retry.d.ts
 interface WithOptimisticRetryOptions {
@@ -362,4 +429,4 @@ declare function createFailureCollector(what: string): {
   throwIfAny: () => void;
 };
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, CasMismatchError, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TDbWriteAction, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGuardedQuery, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReferencingForeignKey, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, findAncestorInSet, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, isAtscriptDbView, isDbFieldOp, isEmptyObject, isGeoIndexableType, isGeoPointType, isNavRelation, isPlainObject, isPrimitive, reconcileCas, resolveDesignType, separateCas, separateFieldOps, sortFieldNames, translateQueryTree, unsupportedOperatorMessage, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ALL_BUCKET_UNITS, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type ResolvedBucket, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TDbWriteAction, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGuardedQuery, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReferencingForeignKey, type TRelationInfo, type TResolvedBucket, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, assertGeoPoint, assertNoVersionWrites, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, findAncestorInSet, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, isAtscriptDbView, isBucketableField, isDbFieldOp, isEmptyObject, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, jsonValueAncestor, narrowerFilterOps, reconcileCas, resolveCalendarBuckets, resolveDesignType, separateCas, separateFieldOps, sortFieldNames, translateQueryTree, unsupportedOperatorMessage, walkFilter, withOptimisticRetry };

package/dist/index.d.mts

@@ -1,9 +1,10 @@
-import { $ as TDbWriteAction, A as TCrudPermissions, At as findAncestorInSet, B as TDbForeignKey, C as NullableOptional, Ct as TWriteOptions, D as TCascadeTarget, Dt as UniqueryControls, E as TCascadeResolver, Et as Uniquery, F as TDbCollation, Ft as UniquSelect, G as TDbInsertResult, H as TDbIndexField, I as TDbDefaultFn, J as TDbRelation, K as TDbObjectKind, L as TDbDefaultValue, M as TDbActionIntent, Mt as isGeoPointType, N as TDbActionLevel, Nt as NoopLogger, O as TColumnDiff, Ot as WithRelation, P as TDbActionProcessor, Pt as TGenericLogger, Q as TDbUpdateResult, R as TDbDeleteResult, S as NavPropsOf, St as TValueFormatterPair, T as PrimaryKeyOf, Tt as TypedWithRelation, U as TDbIndexType, V as TDbIndex, W as TDbInsertManyResult, X as TDbRemoveGuardContext, Y as TDbRemoveGuard, Z as TDbStorageType, _ as DbQuery, _t as TSearchIndexInfo, a as TDbEncryptionOptions, at as TExistingForeignKey, b as FilterExpr, bt as TTableResolver, c as BaseDbAdapter, ct as TFkLookupResolver, d as AggregateFn, dt as TIdentification, et as TDbWriteGuard, f as AggregateQuery, ft as TMetaResponse, g as DbPatch, gt as TRelationInfo, h as DbControls, ht as TReferencingForeignKey, i as DbEncryption, it as TExistingColumn, j as TDbActionInfo, jt as isGeoIndexableType, k as TCrudOp, kt as TableMetadata, l as AggregateControls, lt as TFkLookupTarget, m as AtscriptDbWritable, mt as TPrimaryKeyChange, n as DbResponse, nt as TDeleteOptions, o as DocumentFieldMapper, ot as TExistingTableOption, p as AggregateResult, pt as TMetadataOverrides, q as TDbReferentialAction, r as resolveDesignType, rt as TEnsureTableOptions, s as FieldMappingStrategy, st as TFieldMeta, t as AtscriptDbReadable, tt as TDbWriteGuardContext, u as AggregateExpr, ut as TIdDescriptor, v as DbRow, vt as TSyncColumnResult, w as OwnPropsOf, wt as TWriteTableResolver, x as FlatOf, xt as TTouchManyOptions, y as FieldOpsFor, yt as TTableOptionDiff, z as TDbFieldMeta } from "./db-readable-Bn1bV_eC.mjs";
+import { $ as TDbWriteGuardContext, A as TDbActionIntent, At as isGeoPointType, B as TDbIndexField, Bt as NoopLogger, C as PrimaryKeyOf, Ct as TypedWithRelation, D as TCrudOp, Dt as TableMetadata, E as TColumnDiff, Et as WithRelation, F as TDbDefaultValue, Ft as resolveDesignType, G as TDbReferentialAction, H as TDbInsertManyResult, Ht as UniquSelect, I as TDbDeleteResult, It as DbEncryption, J as TDbRemoveGuardContext, K as TDbRelation, L as TDbFieldMeta, Lt as TDbEncryptionOptions, M as TDbActionProcessor, Mt as BaseDbAdapter, N as TDbCollation, Nt as AtscriptDbReadable, O as TCrudPermissions, Ot as findAncestorInSet, P as TDbDefaultFn, Pt as DbResponse, Q as TDbWriteGuard, R as TDbForeignKey, Rt as DocumentFieldMapper, S as OwnPropsOf, St as TWriteTableResolver, T as TCascadeTarget, Tt as UniqueryControls, U as TDbInsertResult, V as TDbIndexType, Vt as TGenericLogger, W as TDbObjectKind, X as TDbUpdateResult, Y as TDbStorageType, Z as TDbWriteAction, _ as FieldOpsFor, _t as TTableOptionDiff, a as jsonValueAncestor, at as TFieldMeta, b as NavPropsOf, bt as TValueFormatterPair, c as AggregateExpr, ct as TIdDescriptor, d as AggregateResult, dt as TMetadataOverrides, et as TDeleteOptions, f as AtscriptDbWritable, ft as TPrimaryKeyChange, g as DbRow, gt as TSyncColumnResult, h as DbQuery, ht as TSearchIndexInfo, i as isJsonValueField, it as TExistingTableOption, j as TDbActionLevel, jt as ALL_BUCKET_UNITS, k as TDbActionInfo, kt as isGeoIndexableType, l as AggregateFn, lt as TIdentification, m as DbPatch, mt as TRelationInfo, n as TResolvedBucket, nt as TExistingColumn, o as resolveCalendarBuckets, ot as TFkLookupResolver, p as DbControls, pt as TReferencingForeignKey, q as TDbRemoveGuard, r as isBucketableField, rt as TExistingForeignKey, s as AggregateControls, st as TFkLookupTarget, t as TBucketFieldSource, tt as TEnsureTableOptions, u as AggregateQuery, ut as TMetaResponse, v as FilterExpr, vt as TTableResolver, w as TCascadeResolver, wt as Uniquery, x as NullableOptional, xt as TWriteOptions, y as FlatOf, yt as TTouchManyOptions, z as TDbIndex, zt as FieldMappingStrategy } from "./buckets-D2XPrwSC.mjs";
 import { _ as separateFieldOps, a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.mjs";
-import { a as TViewColumnMapping, c as AtscriptQueryFieldRef, d as TViewJoin, f as TViewPlan, g as NativeIntegrity, h as IntegrityStrategy, i as AtscriptDbView, l as AtscriptQueryNode, m as AtscriptDbTable, n as TAdapterFactory, o as isAtscriptDbView, p as translateQueryTree, r as TDbSpaceOptions, s as AtscriptQueryComparison, t as DbSpace, u as AtscriptRef } from "./db-space-DdIPYD0Q.mjs";
-import { _ as DbErrorCode, a as buildValidationContext, c as isNavRelation, d as TArrayPatch, f as TDbPatch, g as DbError, h as CasMismatchError, l as isEmptyObject, m as CasExhaustedError, n as ValidatorMode, p as getKeyProps, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as isPlainObject } from "./validator-wBARmD68.mjs";
+import { BucketExpr, BucketUnit, CalendarBucketLabel, ComputedExpr, ResolvedBucket, WeekStart } from "./agg.mjs";
+import { a as TViewColumnMapping, c as AtscriptQueryFieldRef, d as TViewJoin, f as TViewPlan, g as NativeIntegrity, h as IntegrityStrategy, i as AtscriptDbView, l as AtscriptQueryNode, m as AtscriptDbTable, n as TAdapterFactory, o as isAtscriptDbView, p as translateQueryTree, r as TDbSpaceOptions, s as AtscriptQueryComparison, t as DbSpace, u as AtscriptRef } from "./db-space-BQQEgB3d.mjs";
+import { _ as DbErrorCode, a as buildValidationContext, c as isNavRelation, d as TArrayPatch, f as TDbPatch, g as DbError, h as CasMismatchError, l as isEmptyObject, m as CasExhaustedError, n as ValidatorMode, p as getKeyProps, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as isPlainObject, v as bucketTimeZoneUnavailable } from "./validator-CewfnGZj.mjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
-import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
+import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, ResolvedBucket as ResolvedBucket$1, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
 
 //#region src/shared/consts.d.ts
 /**
@@ -23,7 +24,8 @@ declare const DEFAULT_DB_SPACE = "default";
 declare class RelationalFieldMapper extends FieldMappingStrategy {
   reconstructFromRead(row: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
   translateQuery(query: Uniquery$1, meta: TableMetadata): DbQuery;
-  translateAggregateQuery(query: AggregateQuery$1, meta: TableMetadata): DbQuery;
+  /** The flattened column of a logical path (`contact.email` → `contact__email`). */
+  protected physicalPath(logical: string, meta: TableMetadata): string;
   /**
    * Overrides the base `translateFilter` to use `leafByLogical` for key resolution
    * (handles flattened nested paths like `contact.email` → `contact__email`).
@@ -100,21 +102,29 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
  * - `$geoWithin` on a non-geoPoint field → `FILTER_TYPE_MISMATCH`
  * - `$geoWithin` with a malformed circle → `INVALID_QUERY`
  * - `$geoWithin` on an adapter without geo support → `GEO_NOT_SUPPORTED`
+ * - `$exists` with a non-boolean operand → `INVALID_QUERY`
+ * - malformed `$select` computed entries / `$groupBy` entries, calendar
+ *   buckets outside grouped queries or with a bad unit / zone / alias →
+ *   `INVALID_QUERY` (the shared normalizer, `resolveCalendarBuckets`)
+ * - a calendar bucket over a non-timestamp field → `INVALID_QUERY`; a unit
+ *   the adapter's `calendarBucketUnits()` lacks → `BUCKET_NOT_SUPPORTED`
  * - every filter / `$sort` / `$select` / `$groupBy` / `$having` / aggregate
  *   path must resolve to physical storage on THIS adapter and pass the
- *   adapter's `canFilterField` / `canSortField` → `INVALID_QUERY`
- *   (see {@link guardPaths}). Runs after the checks above so `ENC_*` codes
- *   keep firing first for encrypted subtrees.
+ *   capability its position (for a filter entry: its predicate class, see
+ *   {@link canFilterLeaf}) needs → `INVALID_QUERY` (see {@link guardPaths}).
+ *   Runs after the checks above so `ENC_*` codes keep firing first for
+ *   encrypted subtrees.
  */
 /** Validates a `[lng, lat]` tuple (GeoJSON coordinate order). */
 declare function assertGeoPoint(point: unknown, path: string): asserts point is [number, number];
 /**
  * Walks a filter expression, rejecting encrypted-field references and
- * validating `$geoWithin` operator nodes.
+ * validating operator operands: `$geoWithin` shapes and the boolean
+ * `$exists` operand (this is the one owner of that rule).
  */
 declare function guardFilter(meta: TableMetadata, adapter: BaseDbAdapter, filter: FilterExpr$1 | undefined, encCode?: "ENC_FIELD_FILTER" | "ENC_FIELD_AGG"): void;
 /** The query positions a field path can appear in. */
-type TQueryPathOp = "filter" | "sort" | "select" | "groupBy" | "having" | "aggregate";
+type TQueryPathOp = "filter" | "sort" | "select" | "groupBy" | "having" | "aggregate" /** The source field of a calendar bucket (`{ $bucket, $field }` in `$select`). Since 0.1.132. */ | "bucket";
 /** Query shape accepted by {@link guardPaths} / {@link collectQueryPaths} — the raw (pre-translation) uniqu controls. */
 interface TGuardedQuery {
   filter?: FilterExpr$1;
@@ -137,23 +147,64 @@ declare function unsupportedOperatorMessage(op: string): string;
  * walker so programmatic callers get the same acceptance set.
  */
 declare function sortFieldNames(sort: unknown): string[];
+/**
+ * The operator class a filter entry needs from its field (since 0.1.132):
+ * - `compare` — value comparison (bare values, `$eq`, `$gt`, `$in`, `$regex`, any mix);
+ * - `geo` — a `$geoWithin` entry;
+ * - `exists` — an entry whose sole operator is `$exists`.
+ */
+type TFilterPredicate = "compare" | "geo" | "exists";
+/** One filter entry, collected per occurrence: its key and the predicate class its operators need. */
+interface TFilterRef {
+  path: string;
+  predicate: TFilterPredicate;
+}
+/** The adapter-shaped capability {@link canFilterLeaf} consults (a `BaseDbAdapter` or a readable). */
+type TFilterCapabilitySource = Pick<BaseDbAdapter, "canFilterField" | "isGeoSearchable">;
+/** The operator each non-`compare` predicate class stands for, in `filterOps` order. */
+/**
+ * Whether a stored leaf physically supports a filter predicate of this class
+ * — the one rule the core path guard and moost-db's HTTP capability index
+ * both apply:
+ *
+ * - `compare` → `adapter.canFilterField(fd)`;
+ * - `exists` → any stored column: it tests whether the column holds a value
+ *   (SQL `IS [NOT] NULL`), never its content, so the scalar veto (JSON /
+ *   array storage on relational adapters) does not apply;
+ * - `geo` → a `db.geoPoint` leaf on a geo-searchable adapter.
+ *
+ * `@db.encrypted` vetoes every class.
+ */
+declare function canFilterLeaf(fd: TDbFieldMeta, predicate: TFilterPredicate, adapter: TFilterCapabilitySource): boolean;
+/**
+ * The operators of the non-`compare` predicate classes a leaf physically
+ * accepts — named in a value-comparison rejection by the core guard, and
+ * listed (under the HTTP policy) as `/meta.fields[P].filterOps`.
+ */
+declare function narrowerFilterOps(fd: TDbFieldMeta, adapter: TFilterCapabilitySource): string[];
+/** The rejection suffix naming {@link narrowerFilterOps} — `""` when there are none. */
+declare function acceptedOperatorsHint(ops: readonly string[]): string;
 /** Every logical path a parsed query references, grouped by position (since 0.1.128). */
 interface TQueryPathRefs {
-  /** Filter keys (recursing through `$and` / `$or` / `$not`), minus the geo predicates below. */
-  filter: string[];
   /**
-   * Filter keys whose predicate is `$geoWithin`. Their shape and index support
-   * are validated by `guardFilter`, so the core path guard skips the adapter's
-   * scalar filter veto for them; the HTTP gate checks them like any filter path.
+   * Filter entries (recursing through `$and` / `$or` / `$not`), one per
+   * occurrence, each with its predicate class (since 0.1.132; replaces the
+   * `string[]` + `geoFilter` split).
    */
-  geoFilter: string[];
+  filter: TFilterRef[];
   sort: string[];
   select: string[];
+  /** Grouped FIELD paths — calendar-bucket aliases are not listed (their sources are in {@link bucket}). */
   groupBy: string[];
   having: string[];
   /** Aggregate `$field`s (`*` excluded). Only populated in aggregate mode. */
   aggregate: string[];
-  /** `true` in aggregate mode: `$select` entries are aggregate expressions, aliases are exempt in `$sort` / `$having`. */
+  /** Calendar-bucket source `$field`s (since 0.1.132). Only populated in aggregate mode. */
+  bucket: string[];
+  /**
+   * `true` in aggregate mode: `$select` computed entries (aggregates, calendar
+   * buckets) are collected and their aliases are exempt in `$sort` / `$having`.
+   */
   aggregateMode: boolean;
   /**
    * First filter-node `$`-key that is not `$and` / `$or` / `$not`. uniqu's
@@ -168,10 +219,13 @@ interface TQueryPathRefs {
  * visited — they are validated against their target relation separately.
  *
  * Aggregate mode is `aggregate` when given, else the presence of `$groupBy`.
- * In aggregate mode `$select` entries are aggregate expressions whose
- * `$field` is collected and whose alias (`$as`, else `fn_field` — the core's
- * `resolveAlias`) is exempted from `$sort` / `$having`; outside it non-string
- * `$select` entries are ignored (the projection seal handles them).
+ * In aggregate mode `$select` computed entries are collected by kind — an
+ * aggregate's `$field` into `aggregate`, a calendar bucket's into `bucket` —
+ * and their aliases (`$as`, else uniqu's `resolveAlias`) are exempted from
+ * `$sort` / `$having`; a bucket alias is also dropped from `groupBy`, which
+ * lists grouped fields only.
+ *
+ * Entry shapes are not checked here — see `resolveCalendarBuckets`.
  */
 declare function collectQueryPaths(query: TGuardedQuery, aggregate?: boolean): TQueryPathRefs;
 /** What a logical path is on THIS readable / adapter (since 0.1.128). */
@@ -211,21 +265,22 @@ declare function classifyQueryPath(source: TQueryPathSource, path: string): {
  * metadata and adapter capability — the classification of
  * {@link classifyQueryPath} plus the position's physical requirement:
  *
- * - a leaf → physical capability (`canFilterField` / `canSortField`;
- *   `$select` always passes);
+ * - a leaf → physical capability (`canSortField` for `$sort`; for a filter
+ *   entry {@link canFilterLeaf} of its `predicate` class; `canFilterField`
+ *   for `$groupBy` / `$having` / aggregate `$field`s; `$select` always passes);
+ *   a calendar-bucket source must also be a timestamp field
+ *   (`isBucketableField`);
  * - a nested-object parent → only `$select`, and only when it expands to
  *   leaf columns (`selectExpansion`);
  * - everything else is rejected.
  *
- * `geoPredicate` marks a filter entry whose operator is `$geoWithin`: its
- * shape and index support were already validated by {@link guardFilter}, so
- * the adapter's scalar `canFilterField` veto does not apply.
+ * `predicate` is a filter entry's class; other positions leave the default.
  *
  * Messages are the short programmatic forms; the HTTP wording (moost-db's
  * `FieldCapabilityIndex`, with `$with` hints and leaf lists) is what clients
  * see and is authoritative — the HTTP gate always answers first.
  */
-declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: string, op: TQueryPathOp, geoPredicate?: boolean): void;
+declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: string, op: TQueryPathOp, predicate?: TFilterPredicate): void;
 /**
  * Core backstop for every read / aggregate / mutation-filter entry point:
  * each referenced path (see {@link collectQueryPaths}) must exist on THIS
@@ -233,21 +288,29 @@ declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: st
  * {@link guardPath}). Adapters may therefore assume every path they receive
  * is physical.
  *
- * In aggregate mode (`aggregate = true`) `$select` entries are aggregate
- * expressions whose `$field` is checked, `$groupBy` fields are checked, and
- * aggregate aliases (`$as` or `fn_field`) are exempt in `$sort` / `$having`.
+ * Entry shapes are the caller's to normalize first (`resolveCalendarBuckets`
+ * — {@link guardQuery} / {@link guardAggregate} do).
+ *
+ * In aggregate mode (`aggregate = true`) `$select` computed entries have
+ * their `$field` checked (aggregates as `aggregate`, calendar buckets as
+ * `bucket`), `$groupBy` fields are checked, and computed aliases (`$as` or
+ * the default) are exempt in `$sort` / `$having`.
  *
  * Returns the collected refs so callers can run further structural rules
  * (see {@link checkHavingKeys}) without walking the query again.
  */
 declare function guardPaths(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined, aggregate?: boolean): TQueryPathRefs | undefined;
-/** Shared read-path guard: filter + $sort encryption checks, then the path guard. */
+/**
+ * Shared read-path guard: filter + $sort encryption checks, the `$select`
+ * normalizer (a calendar bucket is invalid outside a grouped query), then
+ * the path guard.
+ */
 declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined): void;
 /**
- * `$having` is a post-aggregation filter, so a key is either an aggregate
- * alias (`$as`, else `fn_field` — already exempt in {@link collectQueryPaths})
- * or a `$groupBy` field (exact logical-path match: `metadata.clicks` grouped
- * stays valid). Any other key — a real but non-grouped column included — is
+ * `$having` is a post-aggregation filter, so a key is either a computed
+ * alias (aggregate or calendar bucket — already exempt in
+ * {@link collectQueryPaths}) or a `$groupBy` field (exact logical-path
+ * match: `metadata.clicks` grouped stays valid). Any other key — a real but non-grouped column included — is
  * rejected here, once, for SDK and HTTP callers alike, instead of by the
  * engine (PostgreSQL / MySQL error, SQLite tolerance, Mongo `[]`). Returns
  * the first offending key as an error entry (`path` = the bare key, as the
@@ -259,11 +322,15 @@ declare function checkHavingKeys(refs: TQueryPathRefs): {
 } | undefined;
 /**
  * Aggregate-path guard: $groupBy / $select / $having encryption refs + filter
- * + $sort, then the path guard, then the `$having` key rule
+ * + $sort, then the path guard, then the adapter's calendar-bucket units
+ * (`BUCKET_NOT_SUPPORTED`), then the `$having` key rule
  * ({@link checkHavingKeys} — after the path guard so an unknown key still
  * reads `Unknown field`).
+ *
+ * `buckets` are the query's resolved calendar buckets when the caller already
+ * ran `resolveCalendarBuckets` (resolved here otherwise).
  */
-declare function guardAggregate(meta: TableMetadata, adapter: BaseDbAdapter, query: AggregateQuery$1): void;
+declare function guardAggregate(meta: TableMetadata, adapter: BaseDbAdapter, query: AggregateQuery$1, resolved?: readonly ResolvedBucket$1[]): void;
 //#endregion
 //#region src/with-optimistic-retry.d.ts
 interface WithOptimisticRetryOptions {
@@ -362,4 +429,4 @@ declare function createFailureCollector(what: string): {
   throwIfAny: () => void;
 };
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, CasMismatchError, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TDbWriteAction, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGuardedQuery, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReferencingForeignKey, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, findAncestorInSet, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, isAtscriptDbView, isDbFieldOp, isEmptyObject, isGeoIndexableType, isGeoPointType, isNavRelation, isPlainObject, isPrimitive, reconcileCas, resolveDesignType, separateCas, separateFieldOps, sortFieldNames, translateQueryTree, unsupportedOperatorMessage, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ALL_BUCKET_UNITS, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type ResolvedBucket, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TDbWriteAction, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGuardedQuery, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReferencingForeignKey, type TRelationInfo, type TResolvedBucket, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, assertGeoPoint, assertNoVersionWrites, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, findAncestorInSet, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, isAtscriptDbView, isBucketableField, isDbFieldOp, isEmptyObject, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, jsonValueAncestor, narrowerFilterOps, reconcileCas, resolveCalendarBuckets, resolveDesignType, separateCas, separateFieldOps, sortFieldNames, translateQueryTree, unsupportedOperatorMessage, walkFilter, withOptimisticRetry };