@atscript/db 0.1.147 → 0.1.149

package/dist/{db-error-D5uilS_A.mjs → db-error-Az85UhTX.mjs}

@@ -10,6 +10,25 @@ var DbError = class extends Error {
 		this.stack = void 0;
 	}
 };
+/** Whether `error` is a `DbError` with code `CONFLICT` (unique / primary-key violation). */
+function isConflict(error) {
+	return error instanceof DbError && error.code === "CONFLICT";
+}
+/** @internal The error every handle of a closed `DbSpace` throws. */
+function spaceClosedError() {
+	return new DbError("SPACE_CLOSED", [{
+		path: "",
+		message: "The DbSpace is closed; table and view handles can no longer be used"
+	}]);
+}
+/**
+* Collapses the failures of a multi-step shutdown into one `AggregateError`
+* (message lists every failure).
+* @internal
+*/
+function aggregateFailure(label, errors) {
+	return new AggregateError(errors, `${label}: ${errors.map((e) => e instanceof Error ? e.message : String(e)).join("; ")}`);
+}
 /**
 * Thrown when a write payload nests deeper than the table's
 * declared `@db.depth.limit N`. Surfaced as HTTP 400 in moost-db.
@@ -83,5 +102,17 @@ function bucketTimeZoneUnavailable(message) {
 		message
 	}]);
 }
+/**
+* The adapter's `supportsAggregateExpressions()` is false (or its SQL dialect
+* cannot cast to a double) and the query uses arithmetic in an aggregate
+* `$select` (`AGG_EXPR_NOT_SUPPORTED`, `path` `$select`; moost-db: 400).
+* @since 0.1.148
+*/
+function aggregateExpressionsNotSupported() {
+	return new DbError("AGG_EXPR_NOT_SUPPORTED", [{
+		path: "$select",
+		message: "Aggregate expressions are not supported by this adapter"
+	}]);
+}
 //#endregion
-export { bucketTimeZoneUnavailable as a, DepthLimitExceededError as i, CasMismatchError as n, DbError as r, CasExhaustedError as t };
+export { aggregateExpressionsNotSupported as a, isConflict as c, DepthLimitExceededError as i, spaceClosedError as l, CasMismatchError as n, aggregateFailure as o, DbError as r, bucketTimeZoneUnavailable as s, CasExhaustedError as t };

package/dist/{db-error-DTkkeu5b.cjs → db-error-DRQH4sLY.cjs}

@@ -10,6 +10,25 @@ var DbError = class extends Error {
 		this.stack = void 0;
 	}
 };
+/** Whether `error` is a `DbError` with code `CONFLICT` (unique / primary-key violation). */
+function isConflict(error) {
+	return error instanceof DbError && error.code === "CONFLICT";
+}
+/** @internal The error every handle of a closed `DbSpace` throws. */
+function spaceClosedError() {
+	return new DbError("SPACE_CLOSED", [{
+		path: "",
+		message: "The DbSpace is closed; table and view handles can no longer be used"
+	}]);
+}
+/**
+* Collapses the failures of a multi-step shutdown into one `AggregateError`
+* (message lists every failure).
+* @internal
+*/
+function aggregateFailure(label, errors) {
+	return new AggregateError(errors, `${label}: ${errors.map((e) => e instanceof Error ? e.message : String(e)).join("; ")}`);
+}
 /**
 * Thrown when a write payload nests deeper than the table's
 * declared `@db.depth.limit N`. Surfaced as HTTP 400 in moost-db.
@@ -83,6 +102,18 @@ function bucketTimeZoneUnavailable(message) {
 		message
 	}]);
 }
+/**
+* The adapter's `supportsAggregateExpressions()` is false (or its SQL dialect
+* cannot cast to a double) and the query uses arithmetic in an aggregate
+* `$select` (`AGG_EXPR_NOT_SUPPORTED`, `path` `$select`; moost-db: 400).
+* @since 0.1.148
+*/
+function aggregateExpressionsNotSupported() {
+	return new DbError("AGG_EXPR_NOT_SUPPORTED", [{
+		path: "$select",
+		message: "Aggregate expressions are not supported by this adapter"
+	}]);
+}
 //#endregion
 Object.defineProperty(exports, "CasExhaustedError", {
 	enumerable: true,
@@ -108,9 +139,33 @@ Object.defineProperty(exports, "DepthLimitExceededError", {
 		return DepthLimitExceededError;
 	}
 });
+Object.defineProperty(exports, "aggregateExpressionsNotSupported", {
+	enumerable: true,
+	get: function() {
+		return aggregateExpressionsNotSupported;
+	}
+});
+Object.defineProperty(exports, "aggregateFailure", {
+	enumerable: true,
+	get: function() {
+		return aggregateFailure;
+	}
+});
 Object.defineProperty(exports, "bucketTimeZoneUnavailable", {
 	enumerable: true,
 	get: function() {
 		return bucketTimeZoneUnavailable;
 	}
 });
+Object.defineProperty(exports, "isConflict", {
+	enumerable: true,
+	get: function() {
+		return isConflict;
+	}
+});
+Object.defineProperty(exports, "spaceClosedError", {
+	enumerable: true,
+	get: function() {
+		return spaceClosedError;
+	}
+});

package/dist/{fk-diff-BtOmL4OW.d.mts → fk-diff-BQ4krij8.d.cts}

@@ -1,4 +1,4 @@
-import { $ as TDbStorageType, H as TDbForeignKey, Jt as AtscriptDbView, O as TColumnDiff, V as TDbFieldMeta, ct as TDerivedColumn, ft as TExistingTableOption, nn as AtscriptQueryFieldRef, pn as AtscriptDbReadable, rn as AtscriptQueryNode, ut as TExistingColumn, z as TDbDefaultValue } from "./buckets-DYopfd2Y.mjs";
+import { $t as AtscriptDbView, B as TDbDefaultValue, H as TDbFieldMeta, U as TDbForeignKey, cn as AtscriptQueryNode, ft as TDerivedColumn, gt as TExistingTableOption, k as TColumnDiff, mt as TExistingColumn, rt as TDbStorageType, sn as AtscriptQueryFieldRef, yn as AtscriptDbReadable } from "./buckets-DJiYlMXc.cjs";
 
 //#region src/schema/schema-hash.d.ts
 interface TFieldSnapshot {

package/dist/{fk-diff-DLqwVkKG.d.cts → fk-diff-DsaIijVX.d.mts}

@@ -1,4 +1,4 @@
-import { $ as TDbStorageType, H as TDbForeignKey, Jt as AtscriptDbView, O as TColumnDiff, V as TDbFieldMeta, ct as TDerivedColumn, ft as TExistingTableOption, nn as AtscriptQueryFieldRef, pn as AtscriptDbReadable, rn as AtscriptQueryNode, ut as TExistingColumn, z as TDbDefaultValue } from "./buckets-CjdPipCC.cjs";
+import { $t as AtscriptDbView, B as TDbDefaultValue, H as TDbFieldMeta, U as TDbForeignKey, cn as AtscriptQueryNode, ft as TDerivedColumn, gt as TExistingTableOption, k as TColumnDiff, mt as TExistingColumn, rt as TDbStorageType, sn as AtscriptQueryFieldRef, yn as AtscriptDbReadable } from "./buckets-CNdTOnei.mjs";
 
 //#region src/schema/schema-hash.d.ts
 interface TFieldSnapshot {

package/dist/index.cjs

@@ -1,13 +1,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_error = require("./db-error-DTkkeu5b.cjs");
-const require_column_diff = require("./column-diff-Dt7EDJsA.cjs");
-const require_aggregate_fns = require("./aggregate-fns-CtsRbZn9.cjs");
-const require_nested_writer = require("./nested-writer-SqtYJHF0.cjs");
+const require_db_error = require("./db-error-DRQH4sLY.cjs");
+const require_column_diff = require("./column-diff-CUU4GvYg.cjs");
+const require_aggregate_fns = require("./aggregate-fns-C-UJRobm.cjs");
+const require_nested_writer = require("./nested-writer-BUQvk6QT.cjs");
 const require_derived_rules = require("./derived-rules-YstgIxG-.cjs");
 const require_object = require("./object-Djg28csK.cjs");
 const require_consts = require("./consts-BzRfCcH2.cjs");
 const require_ops = require("./ops.cjs");
-const require_validator = require("./validator-CVS-onRg.cjs");
+const require_validator = require("./validator-UcuJxHNT.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _uniqu_core = require("@uniqu/core");
 let node_crypto = require("node:crypto");
@@ -236,8 +236,14 @@ var DbSpace = class {
 	_readables = /* @__PURE__ */ new WeakMap();
 	/** All tables created in this space — used for reverse FK lookup during cascade. */
 	_allTables = /* @__PURE__ */ new Set();
+	/** Every table / view handle the space created — flagged closed on {@link close}. */
+	_handles = /* @__PURE__ */ new Set();
 	/** Lazily created adapter for administrative ops (drop table/view) that don't need a registered readable. */
 	_adminAdapter;
+	/** Every adapter this space created (tables, views, admin) — disposed on close. */
+	_adapters = /* @__PURE__ */ new Set();
+	_onClose;
+	_closing;
 	logger;
 	/** Encryption service for `@db.encrypted` fields — validated eagerly at construction. */
 	_encryption;
@@ -252,6 +258,7 @@ var DbSpace = class {
 		else {
 			const options = loggerOrOptions ?? {};
 			this.logger = options.logger ?? require_column_diff.NoopLogger;
+			this._onClose = options.onClose;
 			if (options.encryption) this._encryption = new DbEncryption(options.encryption);
 		}
 	}
@@ -260,6 +267,7 @@ var DbSpace = class {
 	* appropriate instance. Uses `@db.view` or `@db.view.for` presence to distinguish.
 	*/
 	get(type, logger) {
+		this._assertOpen();
 		if (require_column_diff.isViewType(type)) return this.getView(type, logger);
 		return this.getTable(type, logger);
 	}
@@ -268,6 +276,7 @@ var DbSpace = class {
 	* Creates the table + adapter on first access, caches for subsequent calls.
 	*/
 	getTable(type, logger) {
+		this._assertOpen();
 		let readable = this._readables.get(type);
 		if (!readable) {
 			assertNotAlias(type);
@@ -280,6 +289,7 @@ var DbSpace = class {
 			readable.setFkLookupResolver((tableName) => this._getFkLookupTarget(tableName));
 			readable.setEncryption(this._encryption);
 			this._readables.set(type, readable);
+			this._handles.add(readable);
 		}
 		return readable;
 	}
@@ -288,12 +298,14 @@ var DbSpace = class {
 	* Creates the view + adapter on first access, caches for subsequent calls.
 	*/
 	getView(type, logger) {
+		this._assertOpen();
 		let readable = this._readables.get(type);
 		if (!readable) {
 			assertNotAlias(type);
 			readable = new require_column_diff.AtscriptDbView(type, this._createAdapter(), logger || this.logger, (t) => this.get(t));
 			readable.setEncryption(this._encryption);
 			this._readables.set(type, readable);
+			this._handles.add(readable);
 		}
 		return readable;
 	}
@@ -302,6 +314,7 @@ var DbSpace = class {
 	* Creates the table/view + adapter on first access if needed.
 	*/
 	getAdapter(type) {
+		this._assertOpen();
 		return this.get(type).dbAdapter;
 	}
 	/**
@@ -309,6 +322,7 @@ var DbSpace = class {
 	* See `BaseDbAdapter.dropTableByName` for an adapter that does not support it.
 	*/
 	async dropTableByName(tableName) {
+		this._assertOpen();
 		await this._getAdminAdapter().dropTableByName(tableName);
 	}
 	/**
@@ -316,6 +330,7 @@ var DbSpace = class {
 	* See `BaseDbAdapter.dropViewByName` for an adapter that does not support it.
 	*/
 	async dropViewByName(viewName) {
+		this._assertOpen();
 		await this._getAdminAdapter().dropViewByName(viewName);
 	}
 	/**
@@ -324,6 +339,7 @@ var DbSpace = class {
 	* @since 0.1.128
 	*/
 	async dropTablesByName(tableNames) {
+		this._assertOpen();
 		await this._getAdminAdapter().dropTablesByName(tableNames);
 	}
 	/**
@@ -333,6 +349,7 @@ var DbSpace = class {
 	* @since 0.1.128
 	*/
 	async getReferencingForeignKeys(tableName) {
+		this._assertOpen();
 		return this._getAdminAdapter().getReferencingForeignKeys?.(tableName);
 	}
 	/**
@@ -351,8 +368,46 @@ var DbSpace = class {
 	_createAdapter() {
 		const adapter = this.adapterFactory();
 		adapter.registerSpace?.(this);
+		this._adapters.add(adapter);
 		return adapter;
 	}
+	/** `true` once {@link close} was called. @since 0.1.148 */
+	get closed() {
+		return this._closing !== void 0;
+	}
+	/** Throws `SPACE_CLOSED` once the space is closed. */
+	_assertOpen() {
+		if (this._closing) throw require_db_error.spaceClosedError();
+	}
+	/**
+	* Closes the space: marks it closed, disposes every adapter it created, then
+	* runs the `onClose` hook (the `createAdapter` helpers close their driver
+	* there). Idempotent — every call returns the first call's promise. Every
+	* step is attempted; failures are collected into an `AggregateError`.
+	*
+	* It does not cancel or drain in-flight queries: call it after the server
+	* stopped accepting requests. After close, `get*` and operations on existing
+	* table/view handles throw `DbError("SPACE_CLOSED")`.
+	* @since 0.1.148
+	*/
+	close() {
+		return this._closing ??= this._doClose();
+	}
+	async _doClose() {
+		for (const readable of this._handles) readable._spaceClosed = true;
+		const errors = [];
+		for (const adapter of this._adapters) try {
+			await adapter.dispose?.();
+		} catch (error) {
+			errors.push(error);
+		}
+		try {
+			await this._onClose?.();
+		} catch (error) {
+			errors.push(error);
+		}
+		if (errors.length > 0) throw require_db_error.aggregateFailure("DbSpace close failed", errors);
+	}
 	/**
 	* Finds all child tables with FKs pointing to the given parent table name.
 	* Accesses `table.foreignKeys` which triggers `_flatten()` if needed.
@@ -376,6 +431,9 @@ var DbSpace = class {
 		for (const table of this._allTables) if (table.tableName === tableName) return { count: (filter) => table.count({ filter }) };
 	}
 };
+if (typeof Symbol.asyncDispose === "symbol") DbSpace.prototype[Symbol.asyncDispose] = function() {
+	return this.close();
+};
 //#endregion
 //#region src/table/db-entity.ts
 /**
@@ -438,6 +496,8 @@ exports.ResolvedRelationFilter = require_nested_writer.ResolvedRelationFilter;
 exports.TableMetadata = require_column_diff.TableMetadata;
 exports.UniquSelect = require_column_diff.UniquSelect;
 exports.acceptedOperatorsHint = require_column_diff.acceptedOperatorsHint;
+exports.aggregateExpressionsNotSupported = require_db_error.aggregateExpressionsNotSupported;
+exports.aggregateFailure = require_db_error.aggregateFailure;
 exports.aliasTargetOf = require_column_diff.aliasTargetOf;
 exports.andFilters = require_nested_writer.andFilters;
 exports.assertGeoPoint = require_column_diff.assertGeoPoint;
@@ -461,6 +521,7 @@ exports.createDbValidatorPlugin = require_validator.createDbValidatorPlugin;
 exports.createFailureCollector = require_column_diff.createFailureCollector;
 exports.decomposePatch = require_column_diff.decomposePatch;
 exports.deletePath = require_object.deletePath;
+exports.evaluateExpr = require_nested_writer.evaluateExpr;
 exports.findAncestorInSet = require_object.findAncestorInSet;
 exports.fkColumns = require_column_diff.fkColumns;
 exports.forEachResolvedRelation = require_nested_writer.forEachResolvedRelation;
@@ -469,6 +530,7 @@ exports.geoIndexNotFoundMessage = require_column_diff.geoIndexNotFoundMessage;
 exports.getDbFieldOp = require_ops.getDbFieldOp;
 exports.getKeyProps = require_validator.getKeyProps;
 exports.getPath = require_object.getPath;
+exports.groupSourceVerdict = require_column_diff.groupSourceVerdict;
 exports.guardAggregate = require_column_diff.guardAggregate;
 exports.guardFilter = require_column_diff.guardFilter;
 exports.guardPath = require_column_diff.guardPath;
@@ -478,6 +540,7 @@ exports.hasRelationOp = require_nested_writer.hasRelationOp;
 exports.isAtscriptDbView = require_column_diff.isAtscriptDbView;
 exports.isBucketableField = require_column_diff.isBucketableField;
 exports.isColumnTypeChanged = require_column_diff.isColumnTypeChanged;
+exports.isConflict = require_db_error.isConflict;
 exports.isDbEntityType = isDbEntityType;
 exports.isDbFieldOp = require_ops.isDbFieldOp;
 exports.isEmptyObject = require_object.isEmptyObject;
@@ -504,6 +567,7 @@ exports.isViewType = require_column_diff.isViewType;
 exports.jsonValueAncestor = require_column_diff.jsonValueAncestor;
 exports.narrowerFilterOps = require_column_diff.narrowerFilterOps;
 exports.normalizeComputedSelect = require_column_diff.normalizeComputedSelect;
+exports.numericOperandProblem = require_column_diff.numericOperandProblem;
 exports.reconcileCas = require_ops.reconcileCas;
 exports.relationStaticFilter = require_nested_writer.relationStaticFilter;
 exports.resolveCalendarBuckets = require_column_diff.resolveCalendarBuckets;
@@ -515,6 +579,7 @@ exports.separateFieldOps = require_ops.separateFieldOps;
 exports.sortFieldNames = require_column_diff.sortFieldNames;
 exports.tableNameOf = require_nested_writer.tableNameOf;
 exports.translateQueryTree = require_nested_writer.translateQueryTree;
+exports.uniqueKeyTuple = require_nested_writer.uniqueKeyTuple;
 exports.unsupportedOperatorMessage = require_column_diff.unsupportedOperatorMessage;
 exports.vectorIndexNotFoundMessage = require_column_diff.vectorIndexNotFoundMessage;
 Object.defineProperty(exports, "walkFilter", {

package/dist/index.d.cts

@@ -1,13 +1,13 @@
-import { $ as TDbStorageType, $t as AtscriptExprNode, A as TCrudPermissions, An as TDbEncryptionOptions, At as TValueFormatterPair, B as TDbDeleteResult, Bt as isGeoPointType, C as NullableOptional, Cn as andFilters, Ct as TRelationInfo, D as TCascadeTarget, Dn as isResolvedRelationFilter, Dt as TTableOptionDiff, E as TCascadeResolver, En as hasRelationOp, Et as TSyncColumnResult, F as TDbActionTargetSummary, Fn as TGenericLogger, Ft as Uniquery, G as TDbIndexType, Gt as DbSpace, H as TDbForeignKey, Ht as ALL_VIEW_CAPABILITIES, I as TDbAvailableActions, In as UniquSelect, It as UniqueryControls, J as TDbObjectKind, Jt as AtscriptDbView, K as TDbInsertManyResult, Kt as TAdapterFactory, L as TDbCollation, Lt as WithRelation, M as TDbActionIntent, Mn as FieldMappingStrategy, Mt as TWriteOptions, N as TDbActionLevel, Nn as TReadControls, Nt as TWriteTableResolver, O as TColumnDiff, On as relationStaticFilter, Ot as TTableResolver, P as TDbActionProcessor, Pn as NoopLogger, Pt as TypedWithRelation, Q as TDbRemoveGuardContext, Qt as aliasTargetOf, R as TDbDefaultFn, Rt as TableMetadata, S as NavPropsOf, Sn as TRelationStaticFilter, St as TReferencingForeignKey, T as PrimaryKeyOf, Tn as forEachResolvedRelation, Tt as TSearchIndexInfo, U as TDbIndex, Ut as BaseDbAdapter, V as TDbFieldMeta, Vt as ALL_BUCKET_UNITS, W as TDbIndexField, Wt as TViewCapability, X as TDbRelation, Xt as isAtscriptDbView, Y as TDbReferentialAction, Yt as TViewColumnMapping, Z as TDbRemoveGuard, Zt as isViewType, _ as DbQuery, _n as REL_FILTER_MAX_NODES, _t as TIdResolveOptions, a as jsonValueAncestor, an as TViewJoin, at as TDbWriteGuardContext, b as FilterExpr, bn as TRelationFilterJunction, bt as TMetadataOverrides, c as AggregateControls, cn as translateQueryTree, ct as TDerivedColumn, d as AggregateQuery, dn as NativeIntegrity, dt as TExistingForeignKey, en as AtscriptOrderItem, et as TDbUpdateResult, f as AggregateResult, fn as TCascadePin, ft as TExistingTableOption, g as DbPatch, gn as REL_FILTER_MAX_DEPTH, gt as TIdDescriptor, h as DbControls, hn as resolveDesignType, ht as TFkLookupTarget, i as isJsonValueField, in as AtscriptRef, it as TDbWriteGuard, j as TDbActionInfo, jn as DocumentFieldMapper, jt as TViewJsonType, k as TCrudOp, kn as DbEncryption, kt as TTouchManyOptions, l as AggregateExpr, ln as AtscriptDbTable, lt as TEnsureTableOptions, m as AtscriptDbWritable, mn as DbResponse, mt as TFkLookupResolver, n as TResolvedBucket, nn as AtscriptQueryFieldRef, nt as TDbWriteCheck, o as normalizeComputedSelect, on as TViewPlan, ot as TDeleteOptions, pn as AtscriptDbReadable, pt as TFieldMeta, q as TDbInsertResult, qt as TDbSpaceOptions, r as isBucketableField, rn as AtscriptQueryNode, rt as TDbWriteCheckContext, s as resolveCalendarBuckets, sn as isFieldRef, st as TDerivedChangeReason, t as TBucketFieldSource, tn as AtscriptQueryComparison, tt as TDbWriteAction, u as AggregateFn, un as IntegrityStrategy, ut as TExistingColumn, v as DbRow, vn as ResolvedRelationFilter, vt as TIdentification, w as OwnPropsOf, wn as containsRelationFilter, wt as TRowResolveOptions, x as FlatOf, xn as TRelationFilterTable, xt as TPrimaryKeyChange, y as FieldOpsFor, yn as TRelGuardState, yt as TMetaResponse, z as TDbDefaultValue, zt as isGeoIndexableType } from "./buckets-CjdPipCC.cjs";
+import { $ as TDbReferentialAction, $t as AtscriptDbView, A as TCrudOp, An as containsRelationFilter, At as TSearchIndexInfo, B as TDbDefaultValue, Bn as NoopLogger, Bt as Uniquery, C as NavPropsOf, Cn as REL_FILTER_MAX_NODES, Ct as TInsertOptions, D as TCascadeResolver, Dn as TRelationFilterTable, Dt as TReferencingForeignKey, E as PrimaryKeyOf, En as TRelationFilterJunction, Et as TPrimaryKeyChange, F as TDbActionProcessor, Fn as DbEncryption, Ft as TValueFormatterPair, G as TDbIndexField, Gn as UniquSelect, Gt as isGeoPointType, H as TDbFieldMeta, Hn as TExprAggregate, Ht as WithRelation, I as TDbActionTargetSummary, In as TDbEncryptionOptions, It as TViewJsonType, J as TDbInsertIgnoreSlot, Jt as BaseDbAdapter, K as TDbIndexType, Kt as ALL_BUCKET_UNITS, L as TDbAvailableActions, Ln as DocumentFieldMapper, Lt as TWriteOptions, M as TDbActionInfo, Mn as hasRelationOp, Mt as TTableOptionDiff, N as TDbActionIntent, Nn as isResolvedRelationFilter, Nt as TTableResolver, O as TCascadeTarget, On as TRelationStaticFilter, Ot as TRelationInfo, P as TDbActionLevel, Pn as relationStaticFilter, Pt as TTouchManyOptions, Q as TDbObjectKind, Qt as TDbSpaceOptions, R as TDbCollation, Rn as FieldMappingStrategy, Rt as TWriteTableResolver, S as FlatOf, Sn as REL_FILTER_MAX_DEPTH, St as TIdentification, T as OwnPropsOf, Tn as TRelGuardState, Tt as TMetadataOverrides, U as TDbForeignKey, Un as TFirstLast, Ut as TableMetadata, V as TDbDeleteResult, Vn as TGenericLogger, Vt as UniqueryControls, W as TDbIndex, Wn as TRowOrderKey, Wt as isGeoIndexableType, X as TDbInsertManyResult, Xt as DbSpace, Y as TDbInsertManyIgnoreResult, Yt as TViewCapability, Z as TDbInsertResult, Zt as TAdapterFactory, _ as DbPatch, _n as NativeIntegrity, _t as TFieldMeta, a as isJsonValueField, an as AtscriptOrderItem, at as TDbWriteAction, b as FieldOpsFor, bn as DbResponse, bt as TIdDescriptor, c as resolveCalendarBuckets, cn as AtscriptQueryNode, ct as TDbWriteGuard, d as AggregateFn, dn as TViewPlan, dt as TDerivedChangeReason, en as TViewColumnMapping, et as TDbRelation, f as AggregateQuery, fn as evaluateExpr, ft as TDerivedColumn, g as DbControls, gn as IntegrityStrategy, gt as TExistingTableOption, h as AtscriptDbWritable, hn as AtscriptDbTable, ht as TExistingForeignKey, i as isBucketableField, in as AtscriptExprNode, it as TDbUpdateResult, j as TCrudPermissions, jn as forEachResolvedRelation, jt as TSyncColumnResult, k as TColumnDiff, kn as andFilters, kt as TRowResolveOptions, l as AggregateControls, ln as AtscriptRef, lt as TDbWriteGuardContext, mn as translateQueryTree, mt as TExistingColumn, n as TComputedSelect, nn as isViewType, nt as TDbRemoveGuardContext, o as jsonValueAncestor, on as AtscriptQueryComparison, ot as TDbWriteCheck, p as AggregateResult, pn as isFieldRef, pt as TEnsureTableOptions, q as TDbInsertIgnoreResult, qt as ALL_VIEW_CAPABILITIES, r as TResolvedBucket, rn as aliasTargetOf, rt as TDbStorageType, s as normalizeComputedSelect, sn as AtscriptQueryFieldRef, st as TDbWriteCheckContext, t as TBucketFieldSource, tn as isAtscriptDbView, tt as TDbRemoveGuard, u as AggregateExpr, un as TViewJoin, ut as TDeleteOptions, v as DbQuery, vn as TCascadePin, vt as TFkLookupResolver, w as NullableOptional, wn as ResolvedRelationFilter, wt as TMetaResponse, x as FilterExpr, xn as resolveDesignType, xt as TIdResolveOptions, y as DbRow, yn as AtscriptDbReadable, yt as TFkLookupTarget, z as TDbDefaultFn, zn as TReadControls, zt as TypedWithRelation } from "./buckets-DJiYlMXc.cjs";
 import { _ as separateFieldOps, a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.cjs";
 import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, t as deletePath } from "./object-CtPYTIvy.cjs";
-import { c as CalendarBucketLabel, d as WeekStart, g as ALL_AGGREGATE_FNS, l as ComputedExpr, o as BucketExpr, s as BucketUnit, u as ResolvedBucket } from "./agg-CV7y8nC6.cjs";
-import { a as buildValidationContext, c as isNavRelation, d as getKeyProps, f as CasExhaustedError, g as bucketTimeZoneUnavailable, h as DbErrorCode, l as TArrayPatch, m as DbError, n as ValidatorMode, p as CasMismatchError, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch } from "./validator-CMnTI6r7.cjs";
+import { c as CalendarBucketLabel, d as WeekStart, g as ALL_AGGREGATE_FNS, l as ComputedExpr, o as BucketExpr, s as BucketUnit, u as ResolvedBucket } from "./agg-42CSpGDR.cjs";
+import { _ as aggregateFailure, a as buildValidationContext, c as isNavRelation, d as getKeyProps, f as CasExhaustedError, g as aggregateExpressionsNotSupported, h as DbErrorCode, l as TArrayPatch, m as DbError, n as ValidatorMode, p as CasMismatchError, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch, v as bucketTimeZoneUnavailable, y as isConflict } from "./validator-tBNvM1qc.cjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
-import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-DLqwVkKG.cjs";
-import { i as tableNameOf } from "./relation-helpers-DH3LvwLV.cjs";
-import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, RELATION_OPS, RelationOp, RelationOp as RelationOp$1, ResolvedBucket as ResolvedBucket$1, Uniquery as Uniquery$1, computeInsights, isPrimitive, isRelationOp, walkFilter } from "@uniqu/core";
-import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
+import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-BQ4krij8.cjs";
+import { i as tableNameOf } from "./relation-helpers-kX7jjgME.cjs";
+import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, RELATION_OPS, RelationOp, RelationOp as RelationOp$1, ResolvedRowOrderKey, ResolvedSelectExpr, Uniquery as Uniquery$1, computeInsights, isPrimitive, isRelationOp, walkFilter } from "@uniqu/core";
+import { AtscriptExprNode as AtscriptExprNode$1, TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/shared/consts.d.ts
 /**
@@ -149,6 +149,7 @@ interface TGuardedQuery {
     $select?: unknown;
     $groupBy?: unknown;
     $having?: unknown;
+    $rowOrder?: unknown;
   };
 }
 /**
@@ -244,6 +245,28 @@ type TBucketSourceVerdict = {
   code: "encrypted" | "jsonDescendant" | "notTimestamp" | "notFilterable" | "notDimension" | "noBuckets";
   reason: string;
 };
+/** {@link groupSourceVerdict}'s answer — the `reason` clause has no trailing period. */
+type TGroupSourceVerdict = {
+  ok: true;
+} | {
+  ok: false;
+  code: "encrypted" | "notFilterable" | "notDimension";
+  reason: string;
+};
+/**
+ * Whether the stored leaf `fd` may be a `$groupBy` key (since 0.1.148) — the
+ * one rule for the core's strict-table check and moost-db's capability index
+ * (`/meta.fields[P].groupable` and the HTTP gate). First failing rule wins:
+ *
+ * 1. `encrypted` — `@db.encrypted`;
+ * 2. `notFilterable` — the adapter cannot filter (so cannot group) the storage;
+ * 3. `notDimension` — a strict table ({@link isStrictTable}) and the field is
+ *    not a dimension.
+ *
+ * A calendar-bucket alias is not a field: it groups by its source, whose
+ * dimension rule is {@link bucketSourceVerdict}'s (callers skip aliases).
+ */
+declare function groupSourceVerdict(fd: TDbFieldMeta, table: Pick<TBucketSourceTable, "dimensions" | "measures">, adapter: Pick<BaseDbAdapter, "canFilterField">): TGroupSourceVerdict;
 /**
  * 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
@@ -302,8 +325,9 @@ interface TQueryPathRefs {
  *
  * Aggregate mode is `aggregate` when given, else the presence of `$groupBy`.
  * 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
+ * aggregate's `$field` (a row-level expression's names, a `first` / `last`
+ * field) into `aggregate`, a calendar bucket's into `bucket`, a `$rowOrder`
+ * key into `sort` — 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.
  *
@@ -414,10 +438,11 @@ declare function checkHavingKeys(refs: TQueryPathRefs): {
  * ({@link checkHavingKeys} — after the path guard so an unknown key still
  * reads `Unknown field`), then the `$having` values (`guardHavingValues`).
  *
- * `buckets` are the query's resolved calendar buckets when the caller already
- * ran `normalizeComputedSelect` (resolved here otherwise).
+ * `resolved` is the query's normalized computed `$select`
+ * (`resolveComputedSelect`) when the caller already ran it (resolved here
+ * otherwise).
  */
-declare function guardAggregate(meta: TableMetadata, adapter: BaseDbAdapter, query: AggregateQuery$1, resolved?: readonly ResolvedBucket$1[]): void;
+declare function guardAggregate(meta: TableMetadata, adapter: BaseDbAdapter, query: AggregateQuery$1, resolved?: TComputedSelect): void;
 //#endregion
 //#region src/with-optimistic-retry.d.ts
 interface WithOptimisticRetryOptions {
@@ -458,6 +483,14 @@ interface WithOptimisticRetryOptions {
  */
 declare function withOptimisticRetry<TRow extends Record<string, unknown>>(table: AtscriptDbTable, filter: Record<string, unknown>, mutator: (row: TRow) => Promise<Record<string, unknown> | undefined> | Record<string, unknown> | undefined, opts?: WithOptimisticRetryOptions): Promise<TDbUpdateResult>;
 //#endregion
+//#region src/shared/keys.d.ts
+/**
+ * Identity of the key tuple `fields` of `row` for uniqueness checks, or
+ * `undefined` when any component is null / missing (a NULL never collides).
+ * Equal across driver representations (see {@link keyString}).
+ */
+declare function uniqueKeyTuple(row: Record<string, unknown>, fields: readonly string[]): string | undefined;
+//#endregion
 //#region src/shared/index-messages.d.ts
 /**
  * Wording of the "index not found" errors — one source for the core, every
@@ -556,4 +589,16 @@ declare function createFailureCollector(what: string): {
   throwIfAny: () => void;
 };
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptExprNode, type AtscriptOrderItem, 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, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, type RelationOp, RelationalFieldMapper, type ResolvedBucket, ResolvedRelationFilter, 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 TDbActionTargetSummary, type TDbAvailableActions, 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 TDbWriteCheck, type TDbWriteCheckContext, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TDerivedChangeReason, type TDerivedColumn, 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 TReadControls, type TReferencingForeignKey, type TRelationFilterJunction, type TRelationFilterTable, type TRelationInfo, type TRelationStaticFilter, type TResolvedBucket, type TRowResolveOptions, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewCapability, type TViewColumnMapping, type TViewJoin, type TViewJsonType, 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, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, deletePath, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, tableNameOf, translateQueryTree, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };
+//#region src/query/aggregate-expr.d.ts
+/**
+ * Why a field cannot be an arithmetic operand, or `undefined` when it can: it
+ * must be a `number` (not a decimal — those are exact, an expression is IEEE
+ * double — and not a timestamp-tagged number) with plain column storage. The
+ * runtime twin of `@db.compute`'s operand rule, so declared and query-time
+ * arithmetic accept the same fields.
+ *
+ * @since 0.1.148
+ */
+declare function numericOperandProblem(fd: TDbFieldMeta): string | undefined;
+//#endregion
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptExprNode, type AtscriptOrderItem, 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, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, type RelationOp, RelationalFieldMapper, type ResolvedBucket, ResolvedRelationFilter, 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 TDbActionTargetSummary, type TDbAvailableActions, 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 TDbInsertIgnoreResult, type TDbInsertIgnoreSlot, type TDbInsertManyIgnoreResult, 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 TDbWriteCheck, type TDbWriteCheckContext, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TDerivedChangeReason, type TDerivedColumn, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TExprAggregate, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFirstLast, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGroupSourceVerdict, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TInsertOptions, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadControls, type TReferencingForeignKey, type TRelationFilterJunction, type TRelationFilterTable, type TRelationInfo, type TRelationStaticFilter, type TResolvedBucket, type TRowOrderKey, type TRowResolveOptions, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewCapability, type TViewColumnMapping, type TViewJoin, type TViewJsonType, 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, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, deletePath, evaluateExpr, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, tableNameOf, translateQueryTree, uniqueKeyTuple, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };