@atscript/db 0.1.132 → 0.1.134

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

@@ -32,10 +32,12 @@ const NoopLogger = {
 *   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
+* - **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).
 *
@@ -52,11 +54,14 @@ function resolveCalendarBuckets(controls, fields, aggregate) {
 	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).
+* 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;
@@ -207,6 +212,7 @@ var TableMetadata = class {
 	physicalNames = /* @__PURE__ */ new Set();
 	_built = false;
 	_identifications;
+	_alwaysAddressable;
 	_collateMap = /* @__PURE__ */ new Map();
 	_columnFromMap = /* @__PURE__ */ new Map();
 	constructor(nestedObjects) {
@@ -276,6 +282,11 @@ var TableMetadata = class {
 		if (!this.nestedObjects) this._buildLeafIndexes();
 		this._buildIdentifications();
 		this._resolvePreferredId(type);
+		this._alwaysAddressable = new Set([
+			...this.primaryKeys,
+			...this.preferredId,
+			...this.originalMetaIdFields
+		]);
 		this._finalizeIndexes();
 		this._collateMap.clear();
 		this._columnFromMap.clear();
@@ -734,6 +745,14 @@ var TableMetadata = class {
 	getIdentifications() {
 		return this._identifications ?? [];
 	}
+	/**
+	* Fields that always count as visible for row identification (since
+	* 0.1.134): primary key, `preferredId` and `@meta.id` fields — see
+	* `AtscriptDbReadable.identificationsVisibleTo`.
+	*/
+	getAlwaysAddressable() {
+		return this._alwaysAddressable ?? /* @__PURE__ */ new Set();
+	}
 	_resolvePreferredId(type) {
 		const preferred = type.metadata.get("db.table.preferredId.uniqueIndex");
 		if (preferred === void 0) {
@@ -1362,8 +1381,10 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 * - 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`
+* - 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
 *   capability its position (for a filter entry: its predicate class, see
@@ -1450,8 +1471,8 @@ const OP_VERB = {
 	aggregate: "aggregate over",
 	bucket: "bucket"
 };
-function pathError(path, message) {
-	return new require_db_error.DbError("INVALID_QUERY", [{
+function pathError(path, message, code = "INVALID_QUERY") {
+	return new require_db_error.DbError(code, [{
 		path,
 		message
 	}]);
@@ -1488,6 +1509,16 @@ function sortFieldNames(sort) {
 	if (typeof sort === "object") return Object.keys(sort);
 	return [];
 }
+/**
+* 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",
@@ -1536,6 +1567,52 @@ function narrowerFilterOps(fd, adapter) {
 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)) {
@@ -1662,8 +1739,8 @@ function pathSourceOf(meta) {
 * - 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 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.
@@ -1683,17 +1760,15 @@ function guardPath(meta, adapter, path, op, predicate = "compare") {
 			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`);
+				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 (!canFilterLeaf(fd, predicate, adapter)) throw pathError(path, `Cannot ${verb} "${path}" — adapter cannot filter on this storage type${op === "filter" ? acceptedOperatorsHint(narrowerFilterOps(fd, adapter)) : ""}`);
+			if (!canFilterLeaf(fd, predicate, adapter)) throw pathError(path, `Cannot ${verb} "${path}" — ${ADAPTER_FILTER_REASON}${op === "filter" ? acceptedOperatorsHint(narrowerFilterOps(fd, adapter)) : ""}`);
 			return;
 		}
 		case "objectParent":
@@ -1793,13 +1868,10 @@ function guardAggregate(meta, adapter, query, resolved) {
 	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`,
+* (`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.
 */
@@ -2058,6 +2130,19 @@ var AtscriptDbReadable = class {
 		return this._meta.getIdentifications();
 	}
 	/**
+	* The {@link identifications} an id may resolve through when fields are
+	* hidden per request (since 0.1.134): a unique index with a field that
+	* fails `isFieldVisible` is dropped, as if it did not exist. Primary-key,
+	* `preferredId` and `@meta.id` fields always count as visible. Without a
+	* predicate, every identification.
+	*/
+	identificationsVisibleTo(isFieldVisible) {
+		const all = this.identifications;
+		if (!isFieldVisible) return all;
+		const always = this._meta.getAlwaysAddressable();
+		return all.filter((ident) => ident.fields.every((f) => always.has(f) || isFieldVisible(f)));
+	}
+	/**
 	* Physical column name of the single `@meta.id` field, or `null` when the
 	* schema has zero or multiple `@meta.id` fields. Used by adapters to return
 	* the user's logical ID instead of the DB-generated one on insert.
@@ -2177,6 +2262,24 @@ var AtscriptDbReadable = class {
 		return this._meta.fieldDescriptors;
 	}
 	/**
+	* The target table of the navigation relation `navField` (since 0.1.134),
+	* resolved through the table resolver this readable was built with (the
+	* `DbSpace`'s). `undefined` when `navField` is not a relation of this table
+	* or no resolver is available (a table constructed without a `DbSpace`).
+	* Top-level relation names only — no dotted paths.
+	*
+	* ```typescript
+	* const users = posts.relatedTable('author')
+	* users?.primaryKeys // ['id']
+	* ```
+	*/
+	relatedTable(navField) {
+		this._ensureBuilt();
+		const targetType = this._meta.relations.get(navField)?.targetType();
+		if (!targetType || !this._tableResolver) return;
+		return this._tableResolver(targetType);
+	}
+	/**
 	* Resolves whether `path` references a real field — directly via `flatMap`
 	* or transitively through a nav relation by recursing into the target
 	* table. Defense-in-depth for query-path validation: `flattenAnnotatedType`
@@ -2192,12 +2295,7 @@ var AtscriptDbReadable = class {
 		if (dotIdx === -1) return false;
 		const head = path.slice(0, dotIdx);
 		const tail = path.slice(dotIdx + 1);
-		if (!this.navFields.has(head)) return false;
-		const relation = this._meta.relations.get(head);
-		if (!relation) return false;
-		const targetType = relation.targetType();
-		if (!targetType || !this._tableResolver) return false;
-		const targetTable = this._tableResolver(targetType);
+		const targetTable = this.relatedTable(head);
 		if (!targetTable || typeof targetTable.isValidFieldPath !== "function") return false;
 		const visited = _visited ?? /* @__PURE__ */ new Set();
 		const cycleKey = `${this.tableName}:${head}`;
@@ -2280,10 +2378,11 @@ var AtscriptDbReadable = class {
 	*   `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 (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`)
+	*   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.
@@ -2300,11 +2399,11 @@ 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);
-			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", [{
+			const bucketAliases = new Set(buckets.map((b) => b.alias));
+			for (const field of $groupBy) if (!dimSet.has(field) && !bucketAliases.has(field)) throw new require_db_error.DbError("INVALID_QUERY", [{
 				path: "$groupBy",
 				message: `Field "${field}" is not a dimension`
 			}]);
@@ -2562,9 +2661,11 @@ var AtscriptDbReadable = class {
 	* same identification resolution as {@link findById}. Public so callers can
 	* AND-combine the id-filter with a row-level read overlay before issuing
 	* `findOne` (avoiding the existence leak that `findById` would cause).
+	* `opts.isFieldVisible` (since 0.1.134) drops unique indexes over hidden
+	* fields — see {@link identificationsVisibleTo}.
 	*/
-	resolveIdFilter(id) {
-		return this._resolveIdFilter(id);
+	resolveIdFilter(id, opts) {
+		return this._resolveIdFilter(id, opts);
 	}
 	/**
 	* Resolve an id value into a filter expression.
@@ -2572,9 +2673,10 @@ var AtscriptDbReadable = class {
 	* When `preferredId` differs from the PK, scalar ids resolve only against
 	* the preferred field (deterministic addressing). Otherwise scalars try PK
 	* + every single-field unique index; objects try PK + compound unique
-	* indexes.
+	* indexes. With `opts.isFieldVisible`, only the identifications
+	* {@link identificationsVisibleTo} keeps are tried.
 	*/
-	_resolveIdFilter(id) {
+	_resolveIdFilter(id, opts) {
 		const pkFields = this.primaryKeys;
 		const preferredFields = this.preferredId;
 		const isExplicitPreferred = preferredFields.length !== pkFields.length || preferredFields.some((f, i) => f !== pkFields[i]);
@@ -2586,12 +2688,13 @@ var AtscriptDbReadable = class {
 		};
 		const orFilters = [];
 		const idObj = isScalar ? null : id;
-		for (const ident of this.identifications) {
+		const identifications = this.identificationsVisibleTo(opts?.isFieldVisible);
+		for (const ident of identifications) {
 			if (ident.fields.length !== 1) continue;
 			const filter = tryScalarOrField(ident.fields[0]);
 			if (filter) orFilters.push(filter);
 		}
-		if (idObj) for (const ident of this.identifications) {
+		if (idObj) for (const ident of identifications) {
 			if (ident.fields.length < 2) continue;
 			if (ident.source !== "primaryKey" && orFilters.length > 0) break;
 			const filter = this._tryCompoundFilter(ident.fields, idObj);
@@ -3993,7 +4096,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				const data = items[i];
 				for (const navField of this._meta.navFields) delete data[navField];
 				if (versionColumn !== void 0) assertNoVersionWrites(data, versionColumn);
-				const filter = this._extractRecordFilter(data);
+				const filter = this._extractRecordFilter(data, opts);
 				const prepared = this._fieldMapper.prepareForWrite(data, this._meta, this.adapter);
 				const result = await this.adapter.replaceOne(this._fieldMapper.translateFilter(filter, this._meta), prepared, expectedVersions[i]);
 				matchedCount += result.matchedCount;
@@ -4068,7 +4171,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				const expectedVersion = expectedVersions[i];
 				const data = { ...payload };
 				for (const navField of this._meta.navFields) delete data[navField];
-				const filter = this._extractRecordFilter(data);
+				const filter = this._extractRecordFilter(data, opts);
 				for (const key of Object.keys(filter)) delete data[key];
 				if (versionColumn !== void 0) assertNoVersionWrites(data, versionColumn);
 				const translatedFilter = this._fieldMapper.translateFilter(filter, this._meta);
@@ -4202,7 +4305,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	*/
 	async deleteOne(id, opts) {
 		this._ensureBuilt();
-		const filter = this._resolveIdFilter(id);
+		const filter = this._resolveIdFilter(id, opts);
 		if (!filter) return { deletedCount: 0 };
 		const guard = opts?.guard;
 		const needsCascade = this._integrity.needsCascade(this._cascadeResolver);
@@ -4376,9 +4479,11 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* 2. Single-field unique index — first `@db.index.unique` field found.
 	* 3. Compound unique index — first compound unique index whose fields are all present.
 	*
-	* Throws when no identifying fields can be found.
+	* Throws when no identifying fields can be found. With `isFieldVisible`
+	* (since 0.1.134), a unique index over a hidden field is skipped, as if it
+	* did not exist — see {@link identificationsVisibleTo}.
 	*/
-	_extractRecordFilter(payload) {
+	_extractRecordFilter(payload, opts) {
 		const pkFields = this.primaryKeys;
 		if (pkFields.length > 0) {
 			let allPresent = true;
@@ -4392,17 +4497,15 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				return filter;
 			}
 		}
-		for (const prop of this.uniqueProps) if (payload[prop] !== void 0) return { [prop]: this._prepareFilterValue(prop, payload[prop]) };
-		for (const index of this._meta.indexes.values()) {
-			if (index.type !== "unique" || index.fields.length < 2) continue;
-			let allPresent = true;
-			for (const indexField of index.fields) if (payload[indexField.name] === void 0) {
-				allPresent = false;
-				break;
-			}
-			if (allPresent) {
+		const identifications = this.identificationsVisibleTo(opts?.isFieldVisible);
+		const singleFields = /* @__PURE__ */ new Set();
+		for (const ident of identifications) if (ident.source !== "primaryKey" && ident.fields.length === 1) singleFields.add(ident.fields[0]);
+		for (const prop of this.uniqueProps) if (singleFields.has(prop) && payload[prop] !== void 0) return { [prop]: this._prepareFilterValue(prop, payload[prop]) };
+		for (const ident of identifications) {
+			if (ident.source === "primaryKey" || ident.fields.length < 2) continue;
+			if (ident.fields.every((field) => payload[field] !== void 0)) {
 				const filter = {};
-				for (const indexField of index.fields) filter[indexField.name] = this._prepareFilterValue(indexField.name, payload[indexField.name]);
+				for (const field of ident.fields) filter[field] = this._prepareFilterValue(field, payload[field]);
 				return filter;
 			}
 		}
@@ -4652,6 +4755,12 @@ function isAtscriptDbView(readable) {
 	return readable.isView;
 }
 //#endregion
+Object.defineProperty(exports, "ADAPTER_FILTER_REASON", {
+	enumerable: true,
+	get: function() {
+		return ADAPTER_FILTER_REASON;
+	}
+});
 Object.defineProperty(exports, "ALL_BUCKET_UNITS", {
 	enumerable: true,
 	get: function() {
@@ -4694,6 +4803,12 @@ Object.defineProperty(exports, "DocumentFieldMapper", {
 		return DocumentFieldMapper;
 	}
 });
+Object.defineProperty(exports, "ENCRYPTED_REASON", {
+	enumerable: true,
+	get: function() {
+		return ENCRYPTED_REASON;
+	}
+});
 Object.defineProperty(exports, "FieldMappingStrategy", {
 	enumerable: true,
 	get: function() {
@@ -4754,6 +4869,12 @@ Object.defineProperty(exports, "assertNoVersionWrites", {
 		return assertNoVersionWrites;
 	}
 });
+Object.defineProperty(exports, "bucketSourceVerdict", {
+	enumerable: true,
+	get: function() {
+		return bucketSourceVerdict;
+	}
+});
 Object.defineProperty(exports, "canFilterLeaf", {
 	enumerable: true,
 	get: function() {

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_db_error = require("./db-error-DTkkeu5b.cjs");
-const require_db_view = require("./db-view-CuFAhzwF.cjs");
+const require_db_view = require("./db-view-pgm2dHIo.cjs");
 const require_validator = require("./validator-BtZbcLN2.cjs");
 const require_consts = require("./consts-BzRfCcH2.cjs");
 const require_ops = require("./ops.cjs");
@@ -382,6 +382,7 @@ exports.$remove = require_ops.$remove;
 exports.$replace = require_ops.$replace;
 exports.$update = require_ops.$update;
 exports.$upsert = require_ops.$upsert;
+exports.ADAPTER_FILTER_REASON = require_db_view.ADAPTER_FILTER_REASON;
 exports.ALL_BUCKET_UNITS = require_db_view.ALL_BUCKET_UNITS;
 exports.ApplicationIntegrity = require_db_view.ApplicationIntegrity;
 exports.AtscriptDbReadable = require_db_view.AtscriptDbReadable;
@@ -395,6 +396,7 @@ exports.DbEncryption = DbEncryption;
 exports.DbError = require_db_error.DbError;
 exports.DbSpace = DbSpace;
 exports.DocumentFieldMapper = require_db_view.DocumentFieldMapper;
+exports.ENCRYPTED_REASON = require_db_view.ENCRYPTED_REASON;
 exports.FieldMappingStrategy = require_db_view.FieldMappingStrategy;
 exports.IntegrityStrategy = require_db_view.IntegrityStrategy;
 exports.NativeIntegrity = require_db_view.NativeIntegrity;
@@ -405,6 +407,7 @@ exports.UniquSelect = require_db_view.UniquSelect;
 exports.acceptedOperatorsHint = require_db_view.acceptedOperatorsHint;
 exports.assertGeoPoint = require_db_view.assertGeoPoint;
 exports.assertNoVersionWrites = require_db_view.assertNoVersionWrites;
+exports.bucketSourceVerdict = require_db_view.bucketSourceVerdict;
 exports.bucketTimeZoneUnavailable = require_db_error.bucketTimeZoneUnavailable;
 exports.buildDbValidator = require_validator.buildDbValidator;
 exports.buildValidationContext = require_validator.buildValidationContext;

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { $ as TDbWriteGuardContext, A as TDbActionIntent, At as isGeoPointType, B as TDbIndexField, Bt as NoopLogger, C as PrimaryKeyOf, Ct as TypedWithRelation, D as TCrudOp, Dt as TableMetadata, E as TColumnDiff, Et as WithRelation, F as TDbDefaultValue, Ft as resolveDesignType, G as TDbReferentialAction, H as TDbInsertManyResult, Ht as UniquSelect, I as TDbDeleteResult, It as DbEncryption, J as TDbRemoveGuardContext, K as TDbRelation, L as TDbFieldMeta, Lt as TDbEncryptionOptions, M as TDbActionProcessor, Mt as BaseDbAdapter, N as TDbCollation, Nt as AtscriptDbReadable, O as TCrudPermissions, Ot as findAncestorInSet, P as TDbDefaultFn, Pt as DbResponse, Q as TDbWriteGuard, R as TDbForeignKey, Rt as DocumentFieldMapper, S as OwnPropsOf, St as TWriteTableResolver, T as TCascadeTarget, Tt as UniqueryControls, U as TDbInsertResult, V as TDbIndexType, Vt as TGenericLogger, W as TDbObjectKind, X as TDbUpdateResult, Y as TDbStorageType, Z as TDbWriteAction, _ as FieldOpsFor, _t as TTableOptionDiff, a as jsonValueAncestor, at as TFieldMeta, b as NavPropsOf, bt as TValueFormatterPair, c as AggregateExpr, ct as TIdDescriptor, d as AggregateResult, dt as TMetadataOverrides, et as TDeleteOptions, f as AtscriptDbWritable, ft as TPrimaryKeyChange, g as DbRow, gt as TSyncColumnResult, h as DbQuery, ht as TSearchIndexInfo, i as isJsonValueField, it as TExistingTableOption, j as TDbActionLevel, jt as ALL_BUCKET_UNITS, k as TDbActionInfo, kt as isGeoIndexableType, l as AggregateFn, lt as TIdentification, m as DbPatch, mt as TRelationInfo, n as TResolvedBucket, nt as TExistingColumn, o as resolveCalendarBuckets, ot as TFkLookupResolver, p as DbControls, pt as TReferencingForeignKey, q as TDbRemoveGuard, r as isBucketableField, rt as TExistingForeignKey, s as AggregateControls, st as TFkLookupTarget, t as TBucketFieldSource, tt as TEnsureTableOptions, u as AggregateQuery, ut as TMetaResponse, v as FilterExpr, vt as TTableResolver, w as TCascadeResolver, wt as Uniquery, x as NullableOptional, xt as TWriteOptions, y as FlatOf, yt as TTouchManyOptions, z as TDbIndex, zt as FieldMappingStrategy } from "./buckets-BvoYYQ2Q.cjs";
+import { $ as TDbWriteGuardContext, A as TDbActionIntent, At as isGeoIndexableType, B as TDbIndexField, Bt as FieldMappingStrategy, C as PrimaryKeyOf, Ct as TWriteTableResolver, D as TCrudOp, Dt as WithRelation, E as TColumnDiff, Et as UniqueryControls, F as TDbDefaultValue, Ft as DbResponse, G as TDbReferentialAction, H as TDbInsertManyResult, Ht as TGenericLogger, I as TDbDeleteResult, It as resolveDesignType, J as TDbRemoveGuardContext, K as TDbRelation, L as TDbFieldMeta, Lt as DbEncryption, M as TDbActionProcessor, Mt as ALL_BUCKET_UNITS, N as TDbCollation, Nt as BaseDbAdapter, O as TCrudPermissions, Ot as TableMetadata, P as TDbDefaultFn, Pt as AtscriptDbReadable, Q as TDbWriteGuard, R as TDbForeignKey, Rt as TDbEncryptionOptions, S as OwnPropsOf, St as TWriteOptions, T as TCascadeTarget, Tt as Uniquery, U as TDbInsertResult, Ut as UniquSelect, V as TDbIndexType, Vt as NoopLogger, W as TDbObjectKind, X as TDbUpdateResult, Y as TDbStorageType, Z as TDbWriteAction, _ as FieldOpsFor, _t as TSyncColumnResult, a as jsonValueAncestor, at as TFieldMeta, b as NavPropsOf, bt as TTouchManyOptions, c as AggregateExpr, ct as TIdDescriptor, d as AggregateResult, dt as TMetaResponse, et as TDeleteOptions, f as AtscriptDbWritable, ft as TMetadataOverrides, g as DbRow, gt as TSearchIndexInfo, h as DbQuery, ht as TRelationInfo, i as isJsonValueField, it as TExistingTableOption, j as TDbActionLevel, jt as isGeoPointType, k as TDbActionInfo, kt as findAncestorInSet, l as AggregateFn, lt as TIdResolveOptions, m as DbPatch, mt as TReferencingForeignKey, n as TResolvedBucket, nt as TExistingColumn, o as resolveCalendarBuckets, ot as TFkLookupResolver, p as DbControls, pt as TPrimaryKeyChange, q as TDbRemoveGuard, r as isBucketableField, rt as TExistingForeignKey, s as AggregateControls, st as TFkLookupTarget, t as TBucketFieldSource, tt as TEnsureTableOptions, u as AggregateQuery, ut as TIdentification, v as FilterExpr, vt as TTableOptionDiff, w as TCascadeResolver, wt as TypedWithRelation, x as NullableOptional, xt as TValueFormatterPair, y as FlatOf, yt as TTableResolver, z as TDbIndex, zt as DocumentFieldMapper } from "./buckets-Bo2IcPZ_.cjs";
 import { _ as separateFieldOps, a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.cjs";
 import { BucketExpr, BucketUnit, CalendarBucketLabel, ComputedExpr, ResolvedBucket, WeekStart } from "./agg.cjs";
-import { a as TViewColumnMapping, c as AtscriptQueryFieldRef, d as TViewJoin, f as TViewPlan, g as NativeIntegrity, h as IntegrityStrategy, i as AtscriptDbView, l as AtscriptQueryNode, m as AtscriptDbTable, n as TAdapterFactory, o as isAtscriptDbView, p as translateQueryTree, r as TDbSpaceOptions, s as AtscriptQueryComparison, t as DbSpace, u as AtscriptRef } from "./db-space-Cslq5Dux.cjs";
+import { a as TViewColumnMapping, c as AtscriptQueryFieldRef, d as TViewJoin, f as TViewPlan, g as NativeIntegrity, h as IntegrityStrategy, i as AtscriptDbView, l as AtscriptQueryNode, m as AtscriptDbTable, n as TAdapterFactory, o as isAtscriptDbView, p as translateQueryTree, r as TDbSpaceOptions, s as AtscriptQueryComparison, t as DbSpace, u as AtscriptRef } from "./db-space-DtGx5HIC.cjs";
 import { _ as DbErrorCode, a as buildValidationContext, c as isNavRelation, d as TArrayPatch, f as TDbPatch, g as DbError, h as CasMismatchError, l as isEmptyObject, m as CasExhaustedError, n as ValidatorMode, p as getKeyProps, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as isPlainObject, v as bucketTimeZoneUnavailable } from "./validator-CewfnGZj.cjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
 import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, ResolvedBucket as ResolvedBucket$1, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
@@ -106,8 +106,10 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
  * - 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`
+ * - 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
  *   capability its position (for a filter entry: its predicate class, see
@@ -159,6 +161,16 @@ interface TFilterRef {
   path: string;
   predicate: TFilterPredicate;
 }
+/**
+ * The reason clause for a leaf the adapter cannot filter (value comparison).
+ * @internal Shared wording for moost-db's capability index — not consumer API.
+ */
+declare 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.
+ */
+declare const ENCRYPTED_REASON = "field is @db.encrypted (ciphertext cannot be compared or ordered)";
 /** The adapter-shaped capability {@link canFilterLeaf} consults (a `BaseDbAdapter` or a readable). */
 type TFilterCapabilitySource = Pick<BaseDbAdapter, "canFilterField" | "isGeoSearchable">;
 /** The operator each non-`compare` predicate class stands for, in `filterOps` order. */
@@ -184,6 +196,52 @@ declare function canFilterLeaf(fd: TDbFieldMeta, predicate: TFilterPredicate, ad
 declare function narrowerFilterOps(fd: TDbFieldMeta, adapter: TFilterCapabilitySource): string[];
 /** The rejection suffix naming {@link narrowerFilterOps} — `""` when there are none. */
 declare function acceptedOperatorsHint(ops: readonly string[]): string;
+/**
+ * The table side of a {@link bucketSourceVerdict}: `TableMetadata` itself,
+ * or moost-db's capability index assembling the same names from a readable.
+ */
+interface TBucketSourceTable {
+  /** Paths of the `isJsonValueField` descriptors — see `jsonValueAncestor`. */
+  jsonValueParents: ReadonlySet<string>;
+  /** Declared dimensions / measures — see {@link isStrictTable}. */
+  dimensions: readonly string[];
+  measures: readonly string[];
+}
+/**
+ * {@link bucketSourceVerdict}'s answer. `reason` is the shared clause (no
+ * trailing period) both layers put after the dash: the core's
+ * `Cannot bucket "P" — <reason>`, moost-db's
+ * `Bucketing field "P" is not permitted — <reason>.`
+ */
+type TBucketSourceVerdict = {
+  ok: true;
+} | {
+  ok: false;
+  code: "encrypted" | "jsonDescendant" | "notTimestamp" | "notFilterable" | "notDimension" | "noBuckets";
+  reason: string;
+};
+/**
+ * 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.
+ */
+declare function bucketSourceVerdict(fd: TDbFieldMeta, table: TBucketSourceTable, adapter: Pick<BaseDbAdapter, "canFilterField" | "calendarBucketUnits">): TBucketSourceVerdict;
 /** Every logical path a parsed query references, grouped by position (since 0.1.128). */
 interface TQueryPathRefs {
   /**
@@ -268,8 +326,8 @@ declare function classifyQueryPath(source: TQueryPathSource, path: string): {
  * - 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 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.
@@ -429,4 +487,4 @@ declare function createFailureCollector(what: string): {
   throwIfAny: () => void;
 };
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ALL_BUCKET_UNITS, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type ResolvedBucket, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TDbWriteAction, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGuardedQuery, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReferencingForeignKey, type TRelationInfo, type TResolvedBucket, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, assertGeoPoint, assertNoVersionWrites, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, findAncestorInSet, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, isAtscriptDbView, isBucketableField, isDbFieldOp, isEmptyObject, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, jsonValueAncestor, narrowerFilterOps, reconcileCas, resolveCalendarBuckets, resolveDesignType, separateCas, separateFieldOps, sortFieldNames, translateQueryTree, unsupportedOperatorMessage, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_BUCKET_UNITS, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type ResolvedBucket, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TBucketSourceTable, type TBucketSourceVerdict, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TDbWriteAction, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReferencingForeignKey, type TRelationInfo, type TResolvedBucket, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, findAncestorInSet, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, isAtscriptDbView, isBucketableField, isDbFieldOp, isEmptyObject, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, jsonValueAncestor, narrowerFilterOps, reconcileCas, resolveCalendarBuckets, resolveDesignType, separateCas, separateFieldOps, sortFieldNames, translateQueryTree, unsupportedOperatorMessage, walkFilter, withOptimisticRetry };