@atscript/db 0.1.131 → 0.1.133

package/dist/{db-view-BYH4HJ-U.mjs → db-view-caPATLmX.mjs}

@@ -1,9 +1,10 @@
-import { n as CasMismatchError, r as DbError } from "./db-error-COrO58t5.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, i as dbPlugin, l as isEmptyObject, n as buildPatchPartial, t as buildDbValidator, u as isPlainObject } from "./validator-CeD_fqyW.mjs";
+import { n as CasMismatchError, r as DbError } from "./db-error-D5uilS_A.mjs";
 import { resolveAlias } from "./agg.mjs";
-import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, g as findRemoteFK, h as findFKForRelation, i as batchPatchNestedFrom, l as batchReplaceNestedVia, m as remapDeleteFkViolation, n as batchInsertNestedTo, o as batchPatchNestedVia, p as enrichFkViolation, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-CkDo-ZfH.mjs";
+import { a as forceNavNonOptional, c as getKeyProps, i as dbPlugin, l as isEmptyObject, n as buildPatchPartial, t as buildDbValidator, u as isPlainObject } from "./validator-Ch7UIQl9.mjs";
+import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, g as findRemoteFK, h as findFKForRelation, i as batchPatchNestedFrom, l as batchReplaceNestedVia, m as remapDeleteFkViolation, n as batchInsertNestedTo, o as batchPatchNestedVia, p as enrichFkViolation, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-CqL24ojl.mjs";
 import { separateCas, separateFieldOps } from "./ops.mjs";
 import { flattenAnnotatedType, isAnnotatedType } from "@atscript/typescript/utils";
+import { BUCKET_UNITS, isAggregateExpr, isBucketExpr, isPrimitive, resolveBuckets } from "@uniqu/core";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/logger.ts
 const NoopLogger = {
@@ -14,6 +15,83 @@ const NoopLogger = {
 	debug: () => {}
 };
 //#endregion
+//#region src/query/buckets.ts
+/**
+* The one normalizer of `$select` computed entries (since 0.1.132) — uniqu's
+* `resolveBuckets` (entry shapes, unit, time zone canonicalization, week
+* start, alias syntax and uniqueness, "grouped queries only", "must also
+* appear in $groupBy", string `$groupBy` entries) with the table's names as
+* the collision set: a bucket alias may not equal a logical path, a physical
+* column or a navigation field, so a label is never reverse-mapped as a
+* column.
+*
+* Which layer validates what:
+* - **Shapes** (this normalizer) run FIRST at every entry point — the core's
+*   read path (`guardQuery`), its aggregate path (`AtscriptDbReadable.aggregate`,
+*   which hands the result on to `guardAggregate` and the field mapper), and
+*   moost-db's HTTP gate — so both layers answer with the same wording.
+*   Everything downstream (`collectQueryPaths`, the field mappers,
+*   `UniquSelect`, adapters) assumes normalized input and does not re-check.
+* - **The source field** (encryption, JSON ancestor, timestamp type,
+*   physical filterability, strict-mode dimension, an adapter with calendar
+*   buckets) is `bucketSourceVerdict` — ONE function, called by the path
+*   guard (`guardPath` op `bucket`) and by moost-db's capability index, so
+*   `/meta.fields[P].bucketable` and the core cannot disagree.
+* - **The unit** (`calendarBucketUnits()` lacks it) is `guardAggregate`'s
+*   (`BUCKET_NOT_SUPPORTED`); SQL builders only re-assert the inlined
+*   literals (defense in depth).
+*
+* `aggregate` defaults to "`$groupBy` is non-empty".
+*
+* @throws DbError `INVALID_QUERY` carrying every issue (`path` `$select` / `$groupBy`).
+*/
+function resolveCalendarBuckets(controls, fields, aggregate) {
+	const res = resolveBuckets(controls, {
+		aggregate,
+		isField: (name) => fields.flatMap.has(name) || fields.navFields.has(name) || fields.physicalNames.has(name)
+	});
+	if (!res.ok) throw new DbError("INVALID_QUERY", res.issues);
+	return res.buckets;
+}
+/**
+* Whether a field's TYPE allows it to be the source of a calendar bucket: a
+* `number` / `integer` leaf carrying the `timestamp` tag
+* (`number.timestamp`, `.created`, `.updated`) that is not
+* `@db.encrypted`. The type is the declaration — no annotation opts a field
+* in.
+*
+* @deprecated since 0.1.133 — the type rule alone; use `bucketSourceVerdict`,
+* the full bucket-source rule the core and moost-db apply.
+*/
+function isBucketableField(fd) {
+	if (fd.encrypted) return false;
+	if (fd.designType !== "number" && fd.designType !== "integer") return false;
+	return ((fd.type?.type)?.tags)?.has("timestamp") === true;
+}
+/**
+* Whether a field holds a JSON value — a `@db.json` object / JSON-stored
+* column or an array. The members of `TableMetadata.jsonValueParents` (and
+* moost-db's equivalent set) — see {@link jsonValueAncestor}.
+*/
+function isJsonValueField(fd) {
+	return fd.storage === "json" || fd.designType === "json" || fd.designType === "array";
+}
+/**
+* The outermost ancestor of `path` in `jsonValueParents` (the paths of the
+* {@link isJsonValueField} descriptors), or `undefined`. A timestamp inside a
+* JSON value is never a bucket source — relational adapters cannot address
+* it and nested-object adapters (which can) must not diverge from them.
+*/
+function jsonValueAncestor(path, jsonValueParents) {
+	if (jsonValueParents.size === 0) return void 0;
+	let pos = path.indexOf(".");
+	while (pos !== -1) {
+		const ancestor = path.slice(0, pos);
+		if (jsonValueParents.has(ancestor)) return ancestor;
+		pos = path.indexOf(".", pos + 1);
+	}
+}
+//#endregion
 //#region src/table/table-metadata.ts
 const INDEX_PREFIX = "atscript__";
 function indexKey(type, name) {
@@ -124,6 +202,14 @@ var TableMetadata = class {
 	* dotted paths as descriptors).
 	*/
 	jsonParents = /* @__PURE__ */ new Set();
+	/**
+	* Logical paths holding a JSON value (`isJsonValueField`: JSON-stored, `json`
+	* or `array` design type; non-ignored, nav-free descriptors) — a timestamp
+	* beneath one is never a calendar-bucket source (`jsonValueAncestor`).
+	*/
+	jsonValueParents = /* @__PURE__ */ new Set();
+	/** Every field descriptor's `physicalName` — reserved names a bucket alias may not take. */
+	physicalNames = /* @__PURE__ */ new Set();
 	_built = false;
 	_identifications;
 	_collateMap = /* @__PURE__ */ new Map();
@@ -135,6 +221,21 @@ var TableMetadata = class {
 		return this._built;
 	}
 	/**
+	* Logical field path → its physical path in document storage (nested
+	* objects kept inline). `@db.column` renames apply to the annotated key,
+	* and a document renames the TOP-LEVEL key only — nested keys are stored
+	* as-is — so a dotted path under a renamed top-level object renames its
+	* first segment: `profile.bio` under `@db.column 'prof'` → `prof.bio`.
+	*/
+	documentPath(path) {
+		const direct = this.columnMap.get(path);
+		if (direct !== void 0) return direct;
+		const dot = path.indexOf(".");
+		if (dot === -1) return path;
+		const top = this.columnMap.get(path.slice(0, dot));
+		return top === void 0 ? path : top + path.slice(dot);
+	}
+	/**
 	* Runs the full metadata compilation pipeline. Called once by
 	* `AtscriptDbReadable._ensureBuilt()` on first metadata access.
 	*
@@ -187,7 +288,7 @@ var TableMetadata = class {
 		this._built = true;
 		adapter.onAfterFlatten?.();
 		if (this.nestedObjects && this.flatMap) {
-			for (const path of this.flatMap.keys()) if (path && !this.ignoredFields.has(path) && !this.navFields.has(path) && findAncestorInSet(path, this.navFields) === void 0) this.allPhysicalFields.push(path);
+			for (const path of this.flatMap.keys()) if (path && !this.ignoredFields.has(path) && !this.navFields.has(path) && findAncestorInSet(path, this.navFields) === void 0) this.allPhysicalFields.push(this.documentPath(path));
 		} else for (const [path, physical] of this.pathToPhysical) {
 			if (this.navFields.has(path)) continue;
 			if (findAncestorInSet(path, this.navFields) !== void 0) continue;
@@ -419,19 +520,25 @@ var TableMetadata = class {
 	/** Nearest `@db.encrypted` ancestor of `path` (exclusive), or `undefined`. */
 	/**
 	* Indexes non-ignored descriptors by logical path and retains the JSON-parent
-	* set. Navigation relations and their descendants are skipped even when the
+	* sets (plus every descriptor's physical name). Navigation relations and their descendants are skipped even when the
 	* adapter keeps them as descriptors (nested-object adapters do) — they are
 	* loaded with `$with`, never addressed as columns of this table.
 	*/
 	_buildGuardIndexes() {
 		const jsonParents = /* @__PURE__ */ new Set();
+		const jsonValueParents = /* @__PURE__ */ new Set();
+		const physicalNames = /* @__PURE__ */ new Set();
 		for (const fd of this.fieldDescriptors) {
+			physicalNames.add(fd.physicalName);
 			if (fd.ignored) continue;
 			if (this.navFields.has(fd.path) || findAncestorInSet(fd.path, this.navFields) !== void 0) continue;
 			this.descriptorByPath.set(fd.path, fd);
 			if (fd.storage === "json") jsonParents.add(fd.path);
+			if (isJsonValueField(fd)) jsonValueParents.add(fd.path);
 		}
 		this.jsonParents = jsonParents;
+		this.jsonValueParents = jsonValueParents;
+		this.physicalNames = physicalNames;
 	}
 	/**
 	* Indexes `fieldDescriptors` into two lookup maps for unified
@@ -653,6 +760,11 @@ var TableMetadata = class {
 * `controls.$select` is `UniquSelect | undefined`.
 *
 * For exclusion → inclusion inversion, pass `allFields` (physical field names).
+*
+* An array `$select` holds plain field names and computed entries —
+* aggregates (`{ $fn, $field }`, {@link aggregates}) and calendar buckets
+* (`{ $bucket, $field }`, {@link buckets}). Entries arrive normalized
+* (`resolveCalendarBuckets` rejects any other shape before translation).
 */
 var UniquSelect = class UniquSelect {
 	static UNRESOLVED = Symbol("unresolved");
@@ -661,17 +773,29 @@ var UniquSelect = class UniquSelect {
 	_array = UniquSelect.UNRESOLVED;
 	_projection = UniquSelect.UNRESOLVED;
 	_aggregates = UniquSelect.UNRESOLVED;
-	constructor(raw, allFields) {
+	/**
+	* The calendar buckets of an aggregate `$select`, normalized (canonical
+	* zone, week start, alias) with the PHYSICAL source `field` and its
+	* descriptor `fd`. `undefined` when there are none. A `$groupBy` key equal
+	* to a bucket's `alias` groups by that bucket (aliases never collide with
+	* columns). Since 0.1.132.
+	*/
+	buckets;
+	/**
+	* @param raw - the `$select` value (field paths already physical).
+	* @param allFields - physical field names, for exclusion-form inversion.
+	* @param buckets - the resolved calendar buckets of the raw `$select`'s
+	*   `{ $bucket }` entries (the field mappers supply them — physical `field`,
+	*   source `fd`).
+	*/
+	constructor(raw, allFields, buckets) {
 		this._raw = raw;
 		this._allFields = allFields;
-	}
-	/** Type guard: checks if a value is an AggregateExpr ({$fn, $field}). */
-	static _isAggregateExpr(v) {
-		return typeof v === "object" && v !== null && "$fn" in v && "$field" in v;
+		this.buckets = buckets?.length ? buckets : void 0;
 	}
 	/**
 	* Resolved inclusion array of plain field names (strings only).
-	* AggregateExpr objects are filtered out.
+	* Computed entries (aggregates, calendar buckets) are filtered out.
 	* For exclusion form, inverts using `allFields` from constructor.
 	*/
 	get asArray() {
@@ -726,7 +850,7 @@ var UniquSelect = class UniquSelect {
 			this._aggregates = void 0;
 			return;
 		}
-		const aggs = this._raw.filter((v) => UniquSelect._isAggregateExpr(v));
+		const aggs = this._raw.filter(isAggregateExpr);
 		this._aggregates = aggs.length > 0 ? aggs : void 0;
 		return this._aggregates;
 	}
@@ -734,6 +858,10 @@ var UniquSelect = class UniquSelect {
 	get hasAggregates() {
 		return !!this.aggregates?.length;
 	}
+	/** The calendar bucket whose alias is `key`, if any — how adapters resolve a `$groupBy` / `$having` key. */
+	bucketByAlias(key) {
+		return this.buckets?.find((b) => b.alias === key);
+	}
 };
 //#endregion
 //#region src/strategies/field-mapping.ts
@@ -754,9 +882,83 @@ function toDecimalString(value) {
 * and `RelationalFieldMapper` (flattened columns, SQL).
 */
 var FieldMappingStrategy = class {
+	/**
+	* Whether {@link physicalPath} can differ from the logical path for this
+	* table; `false` lets the path translations hand their input back as-is.
+	*/
+	renamesPaths(_meta) {
+		return true;
+	}
+	/**
+	* Translates a grouped query to physical names: the filter and `$having`
+	* through {@link translateFilter}, and every field path in `$groupBy`,
+	* `$select` (plain and computed `$field`s) and `$sort` through
+	* {@link physicalPath}. Computed aliases pass through (a bucket alias never
+	* equals a field name).
+	*
+	* `buckets` are the query's calendar buckets as the core's normalizer
+	* resolved them (`resolveCalendarBuckets` — `AtscriptDbReadable.aggregate`
+	* runs it before the guards); they reach adapters with `field` made
+	* physical and the source descriptor as `fd`.
+	*/
+	translateAggregateQuery(query, meta, buckets) {
+		const controls = query.controls;
+		const aliases = this.computedAliasSet(controls.$select);
+		const physicalBuckets = buckets.map((b) => ({
+			...b,
+			field: this.physicalPath(b.field, meta),
+			fd: meta.descriptorByPath.get(b.field)
+		}));
+		const select = controls.$select && this.physicalSelect(controls.$select, meta);
+		return {
+			filter: this.translateFilter(query.filter ?? {}, meta),
+			controls: {
+				...controls,
+				$with: void 0,
+				$groupBy: this.renamesPaths(meta) ? controls.$groupBy.map((key) => aliases.has(key) ? key : this.physicalPath(key, meta)) : controls.$groupBy,
+				$select: select ? new UniquSelect(select, meta.allPhysicalFields, physicalBuckets) : void 0,
+				$sort: controls.$sort && this.physicalSort(controls.$sort, meta, aliases),
+				$having: controls.$having ? this.translateFilter(controls.$having, meta) : void 0
+			},
+			insights: query.insights
+		};
+	}
+	/** Output aliases of the computed `$select` entries (aggregates and calendar buckets). */
+	computedAliasSet(select) {
+		const aliases = /* @__PURE__ */ new Set();
+		for (const item of select ?? []) if (isAggregateExpr(item) || isBucketExpr(item)) aliases.add(resolveAlias(item));
+		return aliases;
+	}
+	/**
+	* `$select` with its field paths made physical: array-form names and
+	* computed `$field`s (`'*'` kept), or the keys of the object
+	* (inclusion / exclusion) form.
+	*/
+	physicalSelect(select, meta) {
+		if (!this.renamesPaths(meta)) return select;
+		if (Array.isArray(select)) return select.map((item) => {
+			if (typeof item === "string") return this.physicalPath(item, meta);
+			if (isAggregateExpr(item) || isBucketExpr(item)) return item.$field === "*" ? item : {
+				...item,
+				$field: this.physicalPath(item.$field, meta)
+			};
+			return item;
+		});
+		const translated = {};
+		for (const [key, flag] of Object.entries(select)) translated[this.physicalPath(key, meta)] = flag;
+		return translated;
+	}
+	/** `$sort` with physical keys; computed `aliases` (grouped queries) pass through. */
+	physicalSort(sort, meta, aliases) {
+		if (!this.renamesPaths(meta)) return sort;
+		const translated = {};
+		for (const [key, dir] of Object.entries(sort)) translated[aliases?.has(key) ? key : this.physicalPath(key, meta)] = dir;
+		return translated;
+	}
 	/**
 	* Recursively walks a filter expression, applying `@db.column` key renames
-	* via `columnMap` and adapter-specific value formatting via `formatFilterValue`.
+	* (document paths — {@link TableMetadata.documentPath}) and adapter-specific
+	* value formatting via `formatFilterValue`.
 	*
 	* The relational mapper overrides this to use `leafByLogical` for deeper
 	* key resolution (flattened nested paths).
@@ -769,8 +971,8 @@ var FieldMappingStrategy = class {
 		else if (key === "$not") result[key] = this.translateFilter(value, meta);
 		else if (key.startsWith("$")) result[key] = value;
 		else {
-			const physical = meta.columnMap.get(key) ?? key;
-			result[physical] = this.formatFilterValue(physical, value, meta);
+			const formatKey = meta.columnMap.get(key) ?? key;
+			result[meta.documentPath(key)] = this.formatFilterValue(formatKey, value, meta);
 		}
 		return result;
 	}
@@ -898,29 +1100,31 @@ var DocumentFieldMapper = class extends FieldMappingStrategy {
 		if (meta.columnMap.size > 0) this.reverseColumnRenames(row, meta);
 		return row;
 	}
+	/**
+	* Every field-path position goes through `@db.column` renames
+	* ({@link TableMetadata.documentPath}): filter keys, `$select` fields
+	* (array, inclusion and exclusion forms) and `$sort` keys.
+	*/
 	translateQuery(query, meta) {
 		const controls = query.controls;
+		const select = controls?.$select && this.physicalSelect(controls.$select, meta);
 		return {
 			filter: this.translateFilter(query.filter, meta),
 			controls: {
 				...controls,
 				$with: void 0,
-				$select: controls?.$select ? new UniquSelect(controls.$select, meta.allPhysicalFields) : void 0
+				$select: select ? new UniquSelect(select, meta.allPhysicalFields) : void 0,
+				$sort: controls?.$sort && this.physicalSort(controls.$sort, meta)
 			},
 			insights: query.insights
 		};
 	}
-	translateAggregateQuery(query, meta) {
-		const controls = query.controls;
-		return {
-			filter: this.translateFilter(query.filter ?? {}, meta),
-			controls: {
-				...controls,
-				$with: void 0,
-				$select: controls.$select ? new UniquSelect(controls.$select, meta.allPhysicalFields) : void 0
-			},
-			insights: query.insights
-		};
+	/** A document path with `@db.column` renames ({@link TableMetadata.documentPath}). */
+	physicalPath(logical, meta) {
+		return meta.documentPath(logical);
+	}
+	renamesPaths(meta) {
+		return meta.columnMap.size > 0;
 	}
 	prepareForWrite(payload, meta, adapter) {
 		const data = { ...payload };
@@ -995,46 +1199,9 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 			insights: query.insights
 		};
 	}
-	translateAggregateQuery(query, meta) {
-		const controls = query.controls;
-		const filter = meta.requiresMappings ? this.translateFilterWithRename(query.filter ?? {}, meta) : meta.toStorageFormatters ? this.translateFilter(query.filter ?? {}, meta) : query.filter ?? {};
-		const groupBy = controls.$groupBy.map((field) => meta.leafByLogical.get(field)?.physicalName ?? field);
-		let select;
-		if (controls.$select) select = controls.$select.map((item) => {
-			if (typeof item === "string") return meta.leafByLogical.get(item)?.physicalName ?? item;
-			if (item.$field === "*") return item;
-			return {
-				...item,
-				$field: meta.leafByLogical.get(item.$field)?.physicalName ?? item.$field
-			};
-		});
-		const aliases = /* @__PURE__ */ new Set();
-		if (controls.$select) {
-			for (const item of controls.$select) if (typeof item !== "string") aliases.add(resolveAlias(item));
-		}
-		let sort;
-		if (controls.$sort) {
-			const translated = {};
-			for (const [key, dir] of Object.entries(controls.$sort)) if (aliases.has(key)) translated[key] = dir;
-			else {
-				const physical = meta.leafByLogical.get(key)?.physicalName ?? key;
-				translated[physical] = dir;
-			}
-			sort = translated;
-		}
-		let having;
-		if (controls.$having) having = meta.requiresMappings ? this.translateFilterWithRename(controls.$having, meta) : meta.toStorageFormatters ? this.translateFilter(controls.$having, meta) : controls.$having;
-		return {
-			filter,
-			controls: {
-				...controls,
-				$groupBy: groupBy,
-				$select: select ? new UniquSelect(select, meta.allPhysicalFields) : void 0,
-				$sort: sort,
-				$having: having
-			},
-			insights: query.insights
-		};
+	/** The flattened column of a logical path (`contact.email` → `contact__email`). */
+	physicalPath(logical, meta) {
+		return meta.leafByLogical.get(logical)?.physicalName ?? logical;
 	}
 	/**
 	* Overrides the base `translateFilter` to use `leafByLogical` for key resolution
@@ -1196,11 +1363,20 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 * - `$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 field that is not a bucket source
+*   (`bucketSourceVerdict`) → `INVALID_QUERY`, or `BUCKET_NOT_SUPPORTED`
+*   when the adapter has no calendar buckets at all; 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). */
 function assertGeoPoint(point, path) {
@@ -1241,7 +1417,8 @@ function guardGeoWithin(meta, adapter, field, value) {
 }
 /**
 * 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).
 */
 function guardFilter(meta, adapter, filter, encCode = "ENC_FIELD_FILTER") {
 	if (!filter || typeof filter !== "object") return;
@@ -1257,8 +1434,12 @@ function guardFilter(meta, adapter, filter, encCode = "ENC_FIELD_FILTER") {
 		}
 		if (key.startsWith("$")) continue;
 		if (hasEncrypted && isEncryptedRef(meta, key)) throw encryptedRefError(encCode, key, "filter on");
-		if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+		if (!isPrimitive(value)) {
 			for (const [op, opValue] of Object.entries(value)) if (op === "$geoWithin") guardGeoWithin(meta, adapter, key, opValue);
+			else if (op === "$exists" && typeof opValue !== "boolean") throw new DbError("INVALID_QUERY", [{
+				path: key,
+				message: `$exists on "${key}" expects true or false`
+			}]);
 		}
 	}
 }
@@ -1273,10 +1454,11 @@ const OP_VERB = {
 	select: "select",
 	groupBy: "group by",
 	having: "filter ($having) on",
-	aggregate: "aggregate over"
+	aggregate: "aggregate over",
+	bucket: "bucket"
 };
-function pathError(path, message) {
-	return new DbError("INVALID_QUERY", [{
+function pathError(path, message, code = "INVALID_QUERY") {
+	return new DbError(code, [{
 		path,
 		message
 	}]);
@@ -1313,16 +1495,120 @@ function sortFieldNames(sort) {
 	if (typeof sort === "object") return Object.keys(sort);
 	return [];
 }
-function collectFilterKeys(filter, out, geo, skip, refs) {
+/**
+* The reason clause for a leaf the adapter cannot filter (value comparison).
+* @internal Shared wording for moost-db's capability index — not consumer API.
+*/
+const ADAPTER_FILTER_REASON = "adapter cannot filter on this storage type";
+/**
+* The reason clause for an `@db.encrypted` leaf in a comparing / ordering position.
+* @internal Shared wording for moost-db's capability index — not consumer API.
+*/
+const ENCRYPTED_REASON = "field is @db.encrypted (ciphertext cannot be compared or ordered)";
+/** The operator each non-`compare` predicate class stands for, in `filterOps` order. */
+const FILTER_PREDICATE_OPS = {
+	exists: "$exists",
+	geo: "$geoWithin"
+};
+/** Classifies one filter entry's value (`{ key: value }`); operand validity is `guardFilter`'s. */
+function filterPredicateOf(value) {
+	if (isPrimitive(value)) return "compare";
+	const ops = value;
+	if ("$geoWithin" in ops) return "geo";
+	const keys = Object.keys(ops);
+	return keys.length === 1 && keys[0] === "$exists" ? "exists" : "compare";
+}
+/**
+* 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.
+*/
+function canFilterLeaf(fd, predicate, adapter) {
+	if (fd.encrypted) return false;
+	switch (predicate) {
+		case "exists": return true;
+		case "geo": return fd.isGeoPoint === true && adapter.isGeoSearchable();
+		default: return adapter.canFilterField(fd);
+	}
+}
+/**
+* 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`.
+*/
+function narrowerFilterOps(fd, adapter) {
+	const ops = [];
+	for (const [predicate, op] of Object.entries(FILTER_PREDICATE_OPS)) if (canFilterLeaf(fd, predicate, adapter)) ops.push(op);
+	return ops;
+}
+/** The rejection suffix naming {@link narrowerFilterOps} — `""` when there are none. */
+function acceptedOperatorsHint(ops) {
+	return ops.length > 0 ? ` (accepted operators: ${ops.join(", ")})` : "";
+}
+/**
+* Strict mode: a table declaring dimensions or measures groups only by
+* dimensions (a calendar bucket's source included) and aggregates only
+* measures.
+*/
+function isStrictTable(table) {
+	return table.dimensions.length > 0 || table.measures.length > 0;
+}
+function rejectSource(code, reason) {
+	return {
+		ok: false,
+		code,
+		reason
+	};
+}
+/**
+* Whether the stored leaf `fd` may be the source of a calendar bucket
+* (since 0.1.133) — every schema and adapter rule, once, for the core path
+* guard ({@link guardPath} op `bucket`) and moost-db's capability index
+* (`/meta.fields[P].bucketable` and the HTTP gate) alike. First failing rule
+* wins, in this order:
+*
+* 1. `encrypted` — `@db.encrypted` (ciphertext has no calendar);
+* 2. `jsonDescendant` — inside a JSON value (`jsonValueAncestor`):
+*    relational adapters cannot address it and nested-object adapters must
+*    not diverge from them;
+* 3. `notTimestamp` — not a `number.timestamp` leaf;
+* 4. `notFilterable` — the adapter cannot filter (so cannot group) the storage;
+* 5. `notDimension` — a strict table ({@link isStrictTable}) and the field
+*    is not a dimension;
+* 6. `noBuckets` — the adapter reports no `calendarBucketUnits()`.
+*
+* Whether the adapter supports the requested UNIT is a per-query rule, not
+* a field's (the core's `BUCKET_NOT_SUPPORTED`). Caller-specific policy
+* layers on top: moost-db rejects `@db.writeOnly` sources before asking.
+*/
+function bucketSourceVerdict(fd, table, adapter) {
+	if (fd.encrypted) return rejectSource("encrypted", ENCRYPTED_REASON);
+	const jsonAncestor = jsonValueAncestor(fd.path, table.jsonValueParents);
+	if (jsonAncestor !== void 0) return rejectSource("jsonDescendant", `inside JSON-stored column "${jsonAncestor}"`);
+	if (!isBucketableField(fd)) return rejectSource("notTimestamp", "not a timestamp field (declare it number.timestamp)");
+	if (!adapter.canFilterField(fd)) return rejectSource("notFilterable", ADAPTER_FILTER_REASON);
+	if (isStrictTable(table) && !table.dimensions.includes(fd.path)) return rejectSource("notDimension", "not a dimension");
+	if (adapter.calendarBucketUnits().size === 0) return rejectSource("noBuckets", "adapter has no calendar buckets");
+	return { ok: true };
+}
+function collectFilterKeys(filter, push, skip, refs) {
 	if (!filter || typeof filter !== "object" || Array.isArray(filter)) return;
 	for (const [key, value] of Object.entries(filter)) {
 		if (refs.unsupportedOperator) return;
 		if (key === "$and" || key === "$or") {
-			if (Array.isArray(value)) for (const child of value) collectFilterKeys(child, out, geo, skip, refs);
+			if (Array.isArray(value)) for (const child of value) collectFilterKeys(child, push, skip, refs);
 			continue;
 		}
 		if (key === "$not") {
-			collectFilterKeys(value, out, geo, skip, refs);
+			collectFilterKeys(value, push, skip, refs);
 			continue;
 		}
 		if (key.startsWith("$")) {
@@ -1330,7 +1616,7 @@ function collectFilterKeys(filter, out, geo, skip, refs) {
 			return;
 		}
 		if (skip?.has(key)) continue;
-		(geo !== void 0 && value !== null && typeof value === "object" && !Array.isArray(value) && "$geoWithin" in value ? geo : out).push(key);
+		push(key, value);
 	}
 }
 /**
@@ -1340,40 +1626,52 @@ function collectFilterKeys(filter, out, geo, skip, refs) {
 * 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`.
 */
 function collectQueryPaths(query, aggregate) {
 	const refs = {
 		filter: [],
-		geoFilter: [],
 		sort: [],
 		select: [],
 		groupBy: [],
 		having: [],
 		aggregate: [],
+		bucket: [],
 		aggregateMode: false
 	};
-	collectFilterKeys(query.filter, refs.filter, refs.geoFilter, void 0, refs);
+	collectFilterKeys(query.filter, (path, value) => refs.filter.push({
+		path,
+		predicate: filterPredicateOf(value)
+	}), void 0, refs);
 	const controls = query.controls ?? {};
 	const rawGroupBy = controls.$groupBy;
 	const groupBy = Array.isArray(rawGroupBy) ? rawGroupBy.filter((f) => typeof f === "string") : typeof rawGroupBy === "string" ? [rawGroupBy] : [];
 	refs.aggregateMode = aggregate ?? groupBy.length > 0;
-	refs.groupBy = groupBy;
 	const aliases = /* @__PURE__ */ new Set();
+	const bucketAliases = /* @__PURE__ */ new Set();
 	const select = controls.$select;
 	if (Array.isArray(select)) {
 		for (const item of select) if (typeof item === "string") refs.select.push(item);
-		else if (refs.aggregateMode && item && typeof item === "object" && "$field" in item) {
-			const expr = item;
-			aliases.add(resolveAlias(expr));
-			if (expr.$field !== "*") refs.aggregate.push(expr.$field);
+		else if (!refs.aggregateMode) continue;
+		else if (isAggregateExpr(item)) {
+			aliases.add(resolveAlias(item));
+			if (item.$field !== "*") refs.aggregate.push(item.$field);
+		} else if (isBucketExpr(item)) {
+			const alias = resolveAlias(item);
+			aliases.add(alias);
+			bucketAliases.add(alias);
+			refs.bucket.push(item.$field);
 		}
 	} else if (select && typeof select === "object") refs.select.push(...Object.keys(select));
+	refs.groupBy = bucketAliases.size > 0 ? groupBy.filter((name) => !bucketAliases.has(name)) : groupBy;
 	for (const name of sortFieldNames(controls.$sort)) if (!aliases.has(name)) refs.sort.push(name);
-	if (refs.aggregateMode) collectFilterKeys(controls.$having, refs.having, void 0, aliases, refs);
+	if (refs.aggregateMode) collectFilterKeys(controls.$having, (path) => refs.having.push(path), aliases, refs);
 	return refs;
 }
 /**
@@ -1424,21 +1722,22 @@ function pathSourceOf(meta) {
 * 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 pass `bucketSourceVerdict` (the rules
+*   moost-db's capability index applies too);
 * - 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.
 */
-function guardPath(meta, adapter, path, op, geoPredicate = false) {
+function guardPath(meta, adapter, path, op, predicate = "compare") {
 	const verb = OP_VERB[op];
 	const { kind, parent } = classifyQueryPath(pathSourceOf(meta), path);
 	switch (kind) {
@@ -1446,12 +1745,16 @@ function guardPath(meta, adapter, path, op, geoPredicate = false) {
 		case "leaf": {
 			if (op === "select") return;
 			const fd = meta.descriptorByPath.get(path);
+			if (op === "bucket") {
+				const verdict = bucketSourceVerdict(fd, meta, adapter);
+				if (!verdict.ok) throw pathError(path, `Cannot bucket "${path}" — ${verdict.reason}`, verdict.code === "noBuckets" ? "BUCKET_NOT_SUPPORTED" : "INVALID_QUERY");
+				return;
+			}
 			if (op === "sort") {
 				if (!adapter.canSortField(fd)) throw pathError(path, `Cannot sort by "${path}" — adapter cannot sort on this storage type`);
 				return;
 			}
-			if (geoPredicate) return;
-			if (!adapter.canFilterField(fd)) throw pathError(path, `Cannot ${verb} "${path}" — adapter cannot filter on this storage type`);
+			if (!canFilterLeaf(fd, predicate, adapter)) throw pathError(path, `Cannot ${verb} "${path}" — ${ADAPTER_FILTER_REASON}${op === "filter" ? acceptedOperatorsHint(narrowerFilterOps(fd, adapter)) : ""}`);
 			return;
 		}
 		case "objectParent":
@@ -1469,9 +1772,13 @@ function guardPath(meta, adapter, path, op, geoPredicate = false) {
 * {@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.
@@ -1480,27 +1787,32 @@ function guardPaths(meta, adapter, query, aggregate = false) {
 	if (!query) return;
 	const refs = collectQueryPaths(query, aggregate);
 	if (refs.unsupportedOperator !== void 0) throw pathError(refs.unsupportedOperator, unsupportedOperatorMessage(refs.unsupportedOperator));
-	for (const path of refs.filter) guardPath(meta, adapter, path, "filter");
-	for (const path of refs.geoFilter) guardPath(meta, adapter, path, "filter", true);
+	for (const ref of refs.filter) guardPath(meta, adapter, ref.path, "filter", ref.predicate);
 	for (const path of refs.sort) guardPath(meta, adapter, path, "sort");
 	for (const path of refs.select) guardPath(meta, adapter, path, "select");
 	for (const path of refs.aggregate) guardPath(meta, adapter, path, "aggregate");
+	for (const path of refs.bucket) guardPath(meta, adapter, path, "bucket");
 	for (const path of refs.groupBy) guardPath(meta, adapter, path, "groupBy");
 	for (const path of refs.having) guardPath(meta, adapter, path, "having");
 	return refs;
 }
-/** 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.
+*/
 function guardQuery(meta, adapter, query) {
 	if (!query) return;
 	guardFilter(meta, adapter, query.filter);
 	guardSort(meta, query.controls?.$sort);
+	resolveCalendarBuckets(query.controls, meta, false);
 	guardPaths(meta, adapter, query);
 }
 /**
-* `$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
@@ -1516,11 +1828,16 @@ function checkHavingKeys(refs) {
 }
 /**
 * 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).
 */
-function guardAggregate(meta, adapter, query) {
+function guardAggregate(meta, adapter, query, resolved) {
+	const buckets = resolved ?? resolveCalendarBuckets(query.controls, meta, true);
 	guardFilter(meta, adapter, query.filter);
 	const controls = query.controls;
 	if (meta.encryptedFields.size > 0) {
@@ -1533,9 +1850,24 @@ function guardAggregate(meta, adapter, query) {
 		guardSort(meta, controls.$sort);
 	}
 	const refs = guardPaths(meta, adapter, query, true);
+	guardBucketUnits(adapter, buckets);
 	const having = refs ? checkHavingKeys(refs) : void 0;
 	if (having) throw new DbError("INVALID_QUERY", [having]);
 }
+/**
+* Rejects a calendar bucket whose unit this adapter cannot group by
+* (`calendarBucketUnits()`; an adapter with none was already answered per
+* source by `bucketSourceVerdict`) with `BUCKET_NOT_SUPPORTED`,
+* before anything is translated — third-party adapters get a clean 400,
+* never an engine error or a silent fallback.
+*/
+function guardBucketUnits(adapter, buckets) {
+	const units = adapter.calendarBucketUnits();
+	for (const b of buckets) if (!units.has(b.unit)) throw new DbError("BUCKET_NOT_SUPPORTED", [{
+		path: "$select",
+		message: `Calendar bucket "${b.unit}" is not supported by this adapter`
+	}]);
+}
 //#endregion
 //#region src/table/db-readable.ts
 /**
@@ -2002,9 +2334,15 @@ var AtscriptDbReadable = class {
 	* Executes an aggregate query with GROUP BY and aggregate functions.
 	*
 	* Validates:
+	* - `$select` computed entries and calendar buckets (the shared normalizer,
+	*   `resolveCalendarBuckets`: shapes, unit, zone, alias, grouping)
 	* - Plain fields in $select are a subset of $groupBy
 	* - When dimensions/measures are defined (strict mode): $groupBy fields
 	*   must be dimensions, aggregate $field values must be measures (or '*')
+	* - the path guard (a bucket source must pass `bucketSourceVerdict` —
+	*   timestamp type, no JSON ancestor, a dimension in strict mode, an
+	*   adapter with calendar buckets) and the adapter's calendar-bucket units
+	*   (`BUCKET_NOT_SUPPORTED`)
 	*
 	* Translates field names, delegates to adapter.aggregate(),
 	* then reverse-maps and applies fromStorage formatters on results.
@@ -2012,6 +2350,7 @@ var AtscriptDbReadable = class {
 	async aggregate(query) {
 		this._ensureBuilt();
 		const { $groupBy, $select } = query.controls;
+		const buckets = resolveCalendarBuckets(query.controls, this._meta, true);
 		if ($select) {
 			const groupBySet = new Set($groupBy);
 			for (const item of $select) if (typeof item === "string" && !groupBySet.has(item)) throw new DbError("INVALID_QUERY", [{
@@ -2020,15 +2359,16 @@ var AtscriptDbReadable = class {
 			}]);
 		}
 		const { dimensions, measures } = this._meta;
-		if (dimensions.length > 0 || measures.length > 0) {
+		if (isStrictTable(this._meta)) {
 			const dimSet = new Set(dimensions);
 			const measSet = new Set(measures);
-			for (const field of $groupBy) if (!dimSet.has(field)) throw new DbError("INVALID_QUERY", [{
+			const bucketAliases = new Set(buckets.map((b) => b.alias));
+			for (const field of $groupBy) if (!dimSet.has(field) && !bucketAliases.has(field)) throw new DbError("INVALID_QUERY", [{
 				path: "$groupBy",
 				message: `Field "${field}" is not a dimension`
 			}]);
 			if ($select) {
-				for (const item of $select) if (typeof item !== "string" && item.$field !== "*" && !measSet.has(item.$field)) throw new DbError("INVALID_QUERY", [{
+				for (const item of $select) if (isAggregateExpr(item) && item.$field !== "*" && !measSet.has(item.$field)) throw new DbError("INVALID_QUERY", [{
 					path: "$select",
 					message: `Aggregate field "${item.$field}" is not a measure`
 				}]);
@@ -2038,8 +2378,7 @@ var AtscriptDbReadable = class {
 		if ($select && quantityRefByField.size > 0) {
 			const groupBySet = new Set($groupBy);
 			for (const item of $select) {
-				if (typeof item === "string") continue;
-				if (item.$field === "*") continue;
+				if (!isAggregateExpr(item) || item.$field === "*") continue;
 				const refField = quantityRefByField.get(item.$field);
 				if (refField && !groupBySet.has(refField)) throw new DbError("INVALID_QUERY", [{
 					path: "$select",
@@ -2052,8 +2391,8 @@ var AtscriptDbReadable = class {
 			this._ensureSearchable();
 			if (!searchTerm.trim()) return query.controls.$count ? [{ count: 0 }] : [];
 		}
-		guardAggregate(this._meta, this.adapter, query);
-		const dbQuery = this._fieldMapper.translateAggregateQuery(query, this._meta);
+		guardAggregate(this._meta, this.adapter, query, buckets);
+		const dbQuery = this._fieldMapper.translateAggregateQuery(query, this._meta, buckets);
 		return (await this.adapter.aggregate(dbQuery)).map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
 	}
 	/** Whether the underlying adapter supports text search. */
@@ -2064,6 +2403,10 @@ var AtscriptDbReadable = class {
 	canFilterField(fd) {
 		return this.adapter.canFilterField(fd);
 	}
+	/** Calendar-bucket units the adapter can group by (proxies adapter capability; empty = none). */
+	calendarBucketUnits() {
+		return this.adapter.calendarBucketUnits();
+	}
 	/** Whether the adapter can sort by a given field (proxies adapter capability). */
 	canSortField(fd) {
 		return this.adapter.canSortField(fd);
@@ -2350,7 +2693,7 @@ var AtscriptDbReadable = class {
 	* Public entry point for relation loading. Used by adapters for nested $with delegation.
 	*/
 	async loadRelations(rows, withRelations) {
-		const { loadRelationsImpl } = await import("./relation-loader-CUGcxJ18.mjs").then((n) => n.n);
+		const { loadRelationsImpl } = await import("./relation-loader-B68R1LET.mjs").then((n) => n.n);
 		return loadRelationsImpl(rows, withRelations, this);
 	}
 	/**
@@ -2415,6 +2758,9 @@ function createFailureCollector(what) {
 //#endregion
 //#region src/base-adapter.ts
 const EMPTY_DEFAULT_FNS = /* @__PURE__ */ new Set();
+const EMPTY_BUCKET_UNITS = /* @__PURE__ */ new Set();
+/** Every calendar-bucket unit — what an adapter that renders them all returns from `calendarBucketUnits()`. */
+const ALL_BUCKET_UNITS = new Set(BUCKET_UNITS);
 const txStorage = new AsyncLocalStorage();
 /** The innermost open transaction of `owner` in the current async chain. */
 function findTxContext(owner) {
@@ -2629,6 +2975,23 @@ var BaseDbAdapter = class {
 		return EMPTY_DEFAULT_FNS;
 	}
 	/**
+	* Calendar-bucket units (`{ $bucket, $field }` in an aggregate `$select`)
+	* this adapter can group by, over IANA time zones. Empty (the default) =
+	* calendar buckets unsupported: the core rejects them with
+	* `BUCKET_NOT_SUPPORTED` before dispatch, and moost-db's `/meta` advertises
+	* no bucketable field.
+	*
+	* A set rather than a boolean (like {@link nativeDefaultFns}) so a unit can
+	* be adopted adapter by adapter. An adapter that returns a unit must group
+	* by the bucket alias in `$groupBy` — see `controls.$select.buckets`
+	* (`TResolvedBucket`: physical `field`, source `fd`) — and return the
+	* `YYYY-MM-DD` label of the bucket's first local day (null for a null or
+	* out-of-range source, uniqu's `bucketLabel` semantics). Since 0.1.132.
+	*/
+	calendarBucketUnits() {
+		return EMPTY_BUCKET_UNITS;
+	}
+	/**
 	* Whether this adapter enforces foreign key constraints natively.
 	* When `true`, the generic layer skips application-level cascade/setNull
 	* on delete — the DB engine handles it (e.g. SQLite `ON DELETE CASCADE`).
@@ -2650,6 +3013,9 @@ var BaseDbAdapter = class {
 	* Used by `AsDbReadableController.buildMetaResponse()` to gate the
 	* `filterable` flag exposed to UIs — the adapter's answer is a hard gate
 	* even when the field carries `@db.column.filterable`.
+	*
+	* Vetoes value comparison only — a sole-`$exists` entry needs just a stored
+	* column (`canFilterLeaf`).
 	*/
 	canFilterField(fd) {
 		if (fd.encrypted) return false;
@@ -4345,4 +4711,4 @@ function isAtscriptDbView(readable) {
 	return readable.isView;
 }
 //#endregion
-export { isGeoIndexableType as A, unsupportedOperatorMessage as C, UniquSelect as D, FieldMappingStrategy as E, NoopLogger as M, TableMetadata as O, sortFieldNames as S, DocumentFieldMapper as T, guardAggregate as _, decomposePatch as a, guardPaths as b, createFailureCollector as c, AtscriptDbReadable as d, resolveDesignType as f, collectQueryPaths as g, classifyQueryPath as h, assertNoVersionWrites as i, isGeoPointType as j, findAncestorInSet as k, IntegrityStrategy as l, checkHavingKeys as m, isAtscriptDbView as n, ApplicationIntegrity as o, assertGeoPoint as p, AtscriptDbTable as r, BaseDbAdapter as s, AtscriptDbView as t, NativeIntegrity as u, guardFilter as v, RelationalFieldMapper as w, guardQuery as x, guardPath as y };
+export { unsupportedOperatorMessage as A, isJsonValueField as B, guardAggregate as C, guardQuery as D, guardPaths as E, TableMetadata as F, resolveCalendarBuckets as H, findAncestorInSet as I, isGeoIndexableType as L, DocumentFieldMapper as M, FieldMappingStrategy as N, narrowerFilterOps as O, UniquSelect as P, isGeoPointType as R, collectQueryPaths as S, guardPath as T, NoopLogger as U, jsonValueAncestor as V, assertGeoPoint as _, decomposePatch as a, checkHavingKeys as b, BaseDbAdapter as c, NativeIntegrity as d, AtscriptDbReadable as f, acceptedOperatorsHint as g, ENCRYPTED_REASON as h, assertNoVersionWrites as i, RelationalFieldMapper as j, sortFieldNames as k, createFailureCollector as l, ADAPTER_FILTER_REASON as m, isAtscriptDbView as n, ApplicationIntegrity as o, resolveDesignType as p, AtscriptDbTable as r, ALL_BUCKET_UNITS as s, AtscriptDbView as t, IntegrityStrategy as u, bucketSourceVerdict as v, guardFilter as w, classifyQueryPath as x, canFilterLeaf as y, isBucketableField as z };