@atscript/db 0.1.131 → 0.1.132

package/dist/{db-view-DUDnyQ3b.cjs → db-view-CuFAhzwF.cjs}

@@ -1,9 +1,10 @@
-const require_db_error = require("./db-error-C4JuLcvb.cjs");
-const require_validator = require("./validator-lkCJKuoo.cjs");
-const require_agg = require("./agg.cjs");
-const require_nested_writer = require("./nested-writer-DxPhmWFz.cjs");
+const require_db_error = require("./db-error-DTkkeu5b.cjs");
+require("./agg.cjs");
+const require_validator = require("./validator-BtZbcLN2.cjs");
+const require_nested_writer = require("./nested-writer-wk1EFUNY.cjs");
 const require_ops = require("./ops.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
+let _uniqu_core = require("@uniqu/core");
 let node_async_hooks = require("node:async_hooks");
 //#region src/logger.ts
 const NoopLogger = {
@@ -14,6 +15,78 @@ 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.
+* - **Schema** (timestamp-typed source, JSON ancestor, encryption, physical
+*   filterability) is the path guard's (`guardPath` op `bucket`), mirrored by
+*   moost-db's capability index; dimensions are the aggregate rules'.
+* - **Adapter capability** (`calendarBucketUnits()`) 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 = (0, _uniqu_core.resolveBuckets)(controls, {
+		aggregate,
+		isField: (name) => fields.flatMap.has(name) || fields.navFields.has(name) || fields.physicalNames.has(name)
+	});
+	if (!res.ok) throw new require_db_error.DbError("INVALID_QUERY", res.issues);
+	return res.buckets;
+}
+/**
+* Whether a field can 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. Physical filterability is the
+* caller's (the core path guard and moost-db's capability index both add it).
+*/
+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 +197,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 +216,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 +283,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 +515,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 +755,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 +768,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 +845,7 @@ var UniquSelect = class UniquSelect {
 			this._aggregates = void 0;
 			return;
 		}
-		const aggs = this._raw.filter((v) => UniquSelect._isAggregateExpr(v));
+		const aggs = this._raw.filter(_uniqu_core.isAggregateExpr);
 		this._aggregates = aggs.length > 0 ? aggs : void 0;
 		return this._aggregates;
 	}
@@ -734,6 +853,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 +877,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 ((0, _uniqu_core.isAggregateExpr)(item) || (0, _uniqu_core.isBucketExpr)(item)) aliases.add((0, _uniqu_core.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 ((0, _uniqu_core.isAggregateExpr)(item) || (0, _uniqu_core.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 +966,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 +1095,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 +1194,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(require_agg.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 +1358,18 @@ 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 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). */
 function assertGeoPoint(point, path) {
@@ -1241,7 +1410,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 +1427,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 (!(0, _uniqu_core.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 require_db_error.DbError("INVALID_QUERY", [{
+				path: key,
+				message: `$exists on "${key}" expects true or false`
+			}]);
 		}
 	}
 }
@@ -1273,7 +1447,8 @@ 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 require_db_error.DbError("INVALID_QUERY", [{
@@ -1313,16 +1488,64 @@ function sortFieldNames(sort) {
 	if (typeof sort === "object") return Object.keys(sort);
 	return [];
 }
-function collectFilterKeys(filter, out, geo, skip, refs) {
+/** 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 ((0, _uniqu_core.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(", ")})` : "";
+}
+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 +1553,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 +1563,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(require_agg.resolveAlias(expr));
-			if (expr.$field !== "*") refs.aggregate.push(expr.$field);
+		else if (!refs.aggregateMode) continue;
+		else if ((0, _uniqu_core.isAggregateExpr)(item)) {
+			aliases.add((0, _uniqu_core.resolveAlias)(item));
+			if (item.$field !== "*") refs.aggregate.push(item.$field);
+		} else if ((0, _uniqu_core.isBucketExpr)(item)) {
+			const alias = (0, _uniqu_core.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 +1659,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 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.
 */
-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 +1682,18 @@ function guardPath(meta, adapter, path, op, geoPredicate = false) {
 		case "leaf": {
 			if (op === "select") return;
 			const fd = meta.descriptorByPath.get(path);
+			if (op === "bucket") {
+				const jsonAncestor = jsonValueAncestor(path, meta.jsonValueParents);
+				if (jsonAncestor !== void 0) throw pathError(path, `Cannot bucket "${path}" — inside JSON-stored column "${jsonAncestor}"`);
+				if (!isBucketableField(fd)) throw pathError(path, notTimestampMessage(path));
+				if (!adapter.canFilterField(fd)) throw pathError(path, `Cannot bucket "${path}" — adapter cannot filter on this storage type`);
+				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 cannot filter on this storage type${op === "filter" ? acceptedOperatorsHint(narrowerFilterOps(fd, adapter)) : ""}`);
 			return;
 		}
 		case "objectParent":
@@ -1469,9 +1711,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 +1726,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 +1767,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 +1789,27 @@ 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 require_db_error.DbError("INVALID_QUERY", [having]);
 }
+/** The core wording for a bucket over a field that is not `number.timestamp`. */
+function notTimestampMessage(path) {
+	return `Cannot bucket "${path}" — not a timestamp field (declare it number.timestamp)`;
+}
+/**
+* Rejects a calendar bucket whose unit this adapter cannot group by
+* (`calendarBucketUnits()`; empty by default) 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 require_db_error.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 +2276,14 @@ 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 '*')
+	*   must be dimensions (a calendar bucket's source field included),
+	*   aggregate $field values must be measures (or '*')
+	* - the path guard (a bucket source must be a timestamp field) 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 +2291,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 require_db_error.DbError("INVALID_QUERY", [{
@@ -2023,12 +2303,13 @@ var AtscriptDbReadable = class {
 		if (dimensions.length > 0 || measures.length > 0) {
 			const dimSet = new Set(dimensions);
 			const measSet = new Set(measures);
-			for (const field of $groupBy) if (!dimSet.has(field)) throw new require_db_error.DbError("INVALID_QUERY", [{
+			const bucketSource = new Map(buckets.map((b) => [b.alias, b.field]));
+			for (const field of $groupBy.map((key) => bucketSource.get(key) ?? key)) if (!dimSet.has(field)) throw new require_db_error.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 require_db_error.DbError("INVALID_QUERY", [{
+				for (const item of $select) if ((0, _uniqu_core.isAggregateExpr)(item) && item.$field !== "*" && !measSet.has(item.$field)) throw new require_db_error.DbError("INVALID_QUERY", [{
 					path: "$select",
 					message: `Aggregate field "${item.$field}" is not a measure`
 				}]);
@@ -2038,8 +2319,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 (!(0, _uniqu_core.isAggregateExpr)(item) || item.$field === "*") continue;
 				const refField = quantityRefByField.get(item.$field);
 				if (refField && !groupBySet.has(refField)) throw new require_db_error.DbError("INVALID_QUERY", [{
 					path: "$select",
@@ -2052,8 +2332,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 +2344,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 +2634,7 @@ var AtscriptDbReadable = class {
 	* Public entry point for relation loading. Used by adapters for nested $with delegation.
 	*/
 	async loadRelations(rows, withRelations) {
-		const { loadRelationsImpl } = await Promise.resolve().then(() => require("./relation-loader-C8GOpNYJ.cjs")).then((n) => n.relation_loader_exports);
+		const { loadRelationsImpl } = await Promise.resolve().then(() => require("./relation-loader-BD4xANQJ.cjs")).then((n) => n.relation_loader_exports);
 		return loadRelationsImpl(rows, withRelations, this);
 	}
 	/**
@@ -2415,6 +2699,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(_uniqu_core.BUCKET_UNITS);
 const txStorage = new node_async_hooks.AsyncLocalStorage();
 /** The innermost open transaction of `owner` in the current async chain. */
 function findTxContext(owner) {
@@ -2629,6 +2916,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 +2954,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,6 +4652,12 @@ function isAtscriptDbView(readable) {
 	return readable.isView;
 }
 //#endregion
+Object.defineProperty(exports, "ALL_BUCKET_UNITS", {
+	enumerable: true,
+	get: function() {
+		return ALL_BUCKET_UNITS;
+	}
+});
 Object.defineProperty(exports, "ApplicationIntegrity", {
 	enumerable: true,
 	get: function() {
@@ -4423,6 +4736,12 @@ Object.defineProperty(exports, "UniquSelect", {
 		return UniquSelect;
 	}
 });
+Object.defineProperty(exports, "acceptedOperatorsHint", {
+	enumerable: true,
+	get: function() {
+		return acceptedOperatorsHint;
+	}
+});
 Object.defineProperty(exports, "assertGeoPoint", {
 	enumerable: true,
 	get: function() {
@@ -4435,6 +4754,12 @@ Object.defineProperty(exports, "assertNoVersionWrites", {
 		return assertNoVersionWrites;
 	}
 });
+Object.defineProperty(exports, "canFilterLeaf", {
+	enumerable: true,
+	get: function() {
+		return canFilterLeaf;
+	}
+});
 Object.defineProperty(exports, "checkHavingKeys", {
 	enumerable: true,
 	get: function() {
@@ -4507,6 +4832,12 @@ Object.defineProperty(exports, "isAtscriptDbView", {
 		return isAtscriptDbView;
 	}
 });
+Object.defineProperty(exports, "isBucketableField", {
+	enumerable: true,
+	get: function() {
+		return isBucketableField;
+	}
+});
 Object.defineProperty(exports, "isGeoIndexableType", {
 	enumerable: true,
 	get: function() {
@@ -4519,6 +4850,30 @@ Object.defineProperty(exports, "isGeoPointType", {
 		return isGeoPointType;
 	}
 });
+Object.defineProperty(exports, "isJsonValueField", {
+	enumerable: true,
+	get: function() {
+		return isJsonValueField;
+	}
+});
+Object.defineProperty(exports, "jsonValueAncestor", {
+	enumerable: true,
+	get: function() {
+		return jsonValueAncestor;
+	}
+});
+Object.defineProperty(exports, "narrowerFilterOps", {
+	enumerable: true,
+	get: function() {
+		return narrowerFilterOps;
+	}
+});
+Object.defineProperty(exports, "resolveCalendarBuckets", {
+	enumerable: true,
+	get: function() {
+		return resolveCalendarBuckets;
+	}
+});
 Object.defineProperty(exports, "resolveDesignType", {
 	enumerable: true,
 	get: function() {