@atscript/db 0.1.127 → 0.1.128

package/dist/index.cjs

@@ -1,9 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_db_error = require("./db-error-DXwEzmYJ.cjs");
-const require_db_view = require("./db-view-BP0Qbeux.cjs");
+const require_db_view = require("./db-view-C8-MsjND.cjs");
+const require_validator = require("./validator-BNUHCXIE.cjs");
 const require_consts = require("./consts-BzRfCcH2.cjs");
 const require_ops = require("./ops.cjs");
-const require_validator = require("./validator-CSGug4vg.cjs");
 let node_crypto = require("node:crypto");
 let _uniqu_core = require("@uniqu/core");
 //#region src/encryption.ts
@@ -150,6 +150,11 @@ var DbEncryption = class {
 * a version conflict (`matchedCount === 0`) it re-reads the row, calls the
 * mutator with the fresh state, and retries — up to `maxAttempts` times.
 *
+* A mutator that returns `undefined` or an empty object `{}` aborts without
+* writing: the helper resolves `{ matchedCount: 1, modifiedCount: 0 }` and the
+* version does not move (since 0.1.128 — previously `{}` reported a fabricated
+* match as well, but through the empty-patch short-circuit).
+*
 * The filter (typically the primary key) is threaded into the update payload
 * so the table layer can extract the row identity. If `mutator` returns
 * fields that overlap with the filter, the patch wins (last-write semantics
@@ -179,6 +184,10 @@ async function withOptimisticRetry(table, filter, mutator, opts) {
 		}]);
 		lastSeenVersion = row[versionColumn];
 		const patch = await mutator(row);
+		if (patch === void 0 || require_validator.isEmptyObject(patch)) return {
+			matchedCount: 1,
+			modifiedCount: 0
+		};
 		const result = await table.updateOne({
 			...filter,
 			...patch,
@@ -294,6 +303,29 @@ var DbSpace = class {
 		const adapter = this._getAdminAdapter();
 		if (adapter.dropViewByName) await adapter.dropViewByName(viewName);
 	}
+	/**
+	* Drops a group of mutually referencing tables as one operation.
+	* Used by schema sync to remove a foreign-key cycle no longer in the schema.
+	* @since 0.1.128
+	*/
+	async dropTablesByName(tableNames) {
+		await this._getAdminAdapter().dropTablesByName(tableNames);
+	}
+	/**
+	* Live foreign keys referencing `tableName`, or `undefined` when the
+	* adapter cannot introspect them. Used by schema sync for drop ordering
+	* and surviving-reference checks of tables without a registered readable.
+	* @since 0.1.128
+	*/
+	async getReferencingForeignKeys(tableName) {
+		return this._getAdminAdapter().getReferencingForeignKeys?.(tableName);
+	}
+	/**
+	* A factory-fresh adapter with NO registered readable. Only the name-taking
+	* primitives may run on it (`dropTableByName`, `dropViewByName`,
+	* `dropTablesByName`, `getReferencingForeignKeys`) — adapters derive the
+	* schema for those from the driver/connection, not from a bound table.
+	*/
 	_getAdminAdapter() {
 		return this._adminAdapter ??= this.adapterFactory();
 	}
@@ -372,6 +404,9 @@ exports.assertGeoPoint = require_db_view.assertGeoPoint;
 exports.assertNoVersionWrites = require_db_view.assertNoVersionWrites;
 exports.buildDbValidator = require_validator.buildDbValidator;
 exports.buildValidationContext = require_validator.buildValidationContext;
+exports.checkHavingKeys = require_db_view.checkHavingKeys;
+exports.classifyQueryPath = require_db_view.classifyQueryPath;
+exports.collectQueryPaths = require_db_view.collectQueryPaths;
 Object.defineProperty(exports, "computeInsights", {
 	enumerable: true,
 	get: function() {
@@ -381,26 +416,35 @@ Object.defineProperty(exports, "computeInsights", {
 exports.createDbValidatorPlugin = require_validator.createDbValidatorPlugin;
 exports.createFailureCollector = require_db_view.createFailureCollector;
 exports.decomposePatch = require_db_view.decomposePatch;
+exports.findAncestorInSet = require_db_view.findAncestorInSet;
 exports.forceNavNonOptional = require_validator.forceNavNonOptional;
 exports.getDbFieldOp = require_ops.getDbFieldOp;
 exports.getKeyProps = require_validator.getKeyProps;
 exports.guardAggregate = require_db_view.guardAggregate;
 exports.guardFilter = require_db_view.guardFilter;
+exports.guardPath = require_db_view.guardPath;
+exports.guardPaths = require_db_view.guardPaths;
 exports.guardQuery = require_db_view.guardQuery;
+exports.isAtscriptDbView = require_db_view.isAtscriptDbView;
 exports.isDbFieldOp = require_ops.isDbFieldOp;
+exports.isEmptyObject = require_validator.isEmptyObject;
 exports.isGeoIndexableType = require_db_view.isGeoIndexableType;
 exports.isGeoPointType = require_db_view.isGeoPointType;
 exports.isNavRelation = require_validator.isNavRelation;
+exports.isPlainObject = require_validator.isPlainObject;
 Object.defineProperty(exports, "isPrimitive", {
 	enumerable: true,
 	get: function() {
 		return _uniqu_core.isPrimitive;
 	}
 });
+exports.reconcileCas = require_ops.reconcileCas;
 exports.resolveDesignType = require_db_view.resolveDesignType;
 exports.separateCas = require_ops.separateCas;
 exports.separateFieldOps = require_ops.separateFieldOps;
+exports.sortFieldNames = require_db_view.sortFieldNames;
 exports.translateQueryTree = translateQueryTree;
+exports.unsupportedOperatorMessage = require_db_view.unsupportedOperatorMessage;
 Object.defineProperty(exports, "walkFilter", {
 	enumerable: true,
 	get: function() {

package/dist/index.d.cts

@@ -1,8 +1,8 @@
-import { $ as TIdentification, A as TDbActionLevel, B as TDbIndexType, C as TCascadeResolver, D as TCrudPermissions, E as TCrudOp, F as TDbDeleteResult, G as TDbStorageType, H as TDbInsertResult, I as TDbFieldMeta, J as TExistingTableOption, K as TDbUpdateResult, L as TDbForeignKey, M as TDbCollation, N as TDbDefaultFn, O as TDbActionInfo, P as TDbDefaultValue, Q as TIdDescriptor, R as TDbIndex, S as PrimaryKeyOf, T as TColumnDiff, U as TDbReferentialAction, V as TDbInsertManyResult, W as TDbRelation, X as TFkLookupResolver, Y as TFieldMeta, Z as TFkLookupTarget, _ as FieldOpsFor, _t as TGenericLogger, a as TDbEncryptionOptions, at as TTableOptionDiff, b as NavPropsOf, c as BaseDbAdapter, ct as TWriteTableResolver, d as AggregateFn, dt as UniqueryControls, et as TMetaResponse, f as AggregateQuery, ft as WithRelation, g as DbQuery, gt as NoopLogger, h as DbControls, ht as isGeoPointType, i as DbEncryption, it as TSyncColumnResult, j as TDbActionProcessor, k as TDbActionIntent, l as AggregateControls, lt as TypedWithRelation, m as AtscriptDbWritable, mt as isGeoIndexableType, n as DbResponse, nt as TRelationInfo, o as DocumentFieldMapper, ot as TTableResolver, p as AggregateResult, pt as TableMetadata, q as TExistingColumn, r as resolveDesignType, rt as TSearchIndexInfo, s as FieldMappingStrategy, st as TValueFormatterPair, t as AtscriptDbReadable, tt as TMetadataOverrides, u as AggregateExpr, ut as Uniquery, v as FilterExpr, vt as UniquSelect, w as TCascadeTarget, x as OwnPropsOf, y as FlatOf, z as TDbIndexField } from "./db-readable-C0nDKX8A.cjs";
-import { a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateFieldOps, h as separateCas, 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-DJRnNTVo.cjs";
-import { a as TViewColumnMapping, c as AtscriptQueryNode, d as TViewPlan, f as translateQueryTree, h as NativeIntegrity, i as AtscriptDbView, l as AtscriptRef, m as IntegrityStrategy, n as TAdapterFactory, o as AtscriptQueryComparison, p as AtscriptDbTable, r as TDbSpaceOptions, s as AtscriptQueryFieldRef, t as DbSpace, u as TViewJoin } from "./db-space-CSntT6yS.cjs";
+import { $ as TDbWriteAction, A as TCrudPermissions, At as isGeoIndexableType, B as TDbForeignKey, C as NullableOptional, Ct as TWriteTableResolver, D as TCascadeTarget, Dt as WithRelation, E as TCascadeResolver, Et as UniqueryControls, F as TDbCollation, G as TDbInsertResult, H as TDbIndexField, I as TDbDefaultFn, J as TDbRelation, K as TDbObjectKind, L as TDbDefaultValue, M as TDbActionIntent, Mt as NoopLogger, N as TDbActionLevel, Nt as TGenericLogger, O as TColumnDiff, Ot as TableMetadata, P as TDbActionProcessor, Pt as UniquSelect, Q as TDbUpdateResult, R as TDbDeleteResult, S as NavPropsOf, St as TWriteOptions, T as PrimaryKeyOf, Tt as Uniquery, U as TDbIndexType, V as TDbIndex, W as TDbInsertManyResult, X as TDbRemoveGuardContext, Y as TDbRemoveGuard, Z as TDbStorageType, _ as DbQuery, _t as TSearchIndexInfo, a as TDbEncryptionOptions, at as TExistingForeignKey, b as FilterExpr, bt as TTableResolver, c as BaseDbAdapter, ct as TFkLookupResolver, d as AggregateFn, dt as TIdentification, et as TDbWriteGuard, f as AggregateQuery, ft as TMetaResponse, g as DbPatch, gt as TRelationInfo, h as DbControls, ht as TReferencingForeignKey, i as DbEncryption, it as TExistingColumn, j as TDbActionInfo, jt as isGeoPointType, k as TCrudOp, kt as findAncestorInSet, l as AggregateControls, lt as TFkLookupTarget, m as AtscriptDbWritable, mt as TPrimaryKeyChange, n as DbResponse, nt as TDeleteOptions, o as DocumentFieldMapper, ot as TExistingTableOption, p as AggregateResult, pt as TMetadataOverrides, q as TDbReferentialAction, r as resolveDesignType, rt as TEnsureTableOptions, s as FieldMappingStrategy, st as TFieldMeta, t as AtscriptDbReadable, tt as TDbWriteGuardContext, u as AggregateExpr, ut as TIdDescriptor, v as DbRow, vt as TSyncColumnResult, w as OwnPropsOf, wt as TypedWithRelation, x as FlatOf, xt as TValueFormatterPair, y as FieldOpsFor, yt as TTableOptionDiff, z as TDbFieldMeta } from "./db-readable-CkbZn_z-.cjs";
+import { _ as separateFieldOps, a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.cjs";
+import { a as TViewColumnMapping, c as AtscriptQueryFieldRef, d as TViewJoin, f as TViewPlan, g as NativeIntegrity, h as IntegrityStrategy, i as AtscriptDbView, l as AtscriptQueryNode, m as AtscriptDbTable, n as TAdapterFactory, o as isAtscriptDbView, p as translateQueryTree, r as TDbSpaceOptions, s as AtscriptQueryComparison, t as DbSpace, u as AtscriptRef } from "./db-space-BevOyVrC.cjs";
+import { a as buildValidationContext, c as isNavRelation, d as TArrayPatch, f as TDbPatch, g as DbErrorCode, h as DbError, l as isEmptyObject, m as CasExhaustedError, n as ValidatorMode, p as getKeyProps, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as isPlainObject } from "./validator-DuAmWc8L.cjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
-import { a as buildValidationContext, c as isNavRelation, d as getKeyProps, l as TArrayPatch, n as ValidatorMode, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch } from "./validator-BcBtg8yW.cjs";
 import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
 
 //#region src/shared/consts.d.ts
@@ -88,33 +88,6 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
   private buildCascadeChildFilter;
 }
 //#endregion
-//#region src/db-error.d.ts
-type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY" | "DEPTH_EXCEEDED" | "VERSION_COLUMN_WRITE" | "CAS_EXHAUSTED" | "ENC_CONFIG_MISSING" | "ENC_KEY_INVALID" | "ENC_NOT_ENCRYPTED" | "ENC_DECRYPT_FAILED" | "ENC_FIELD_FILTER" | "ENC_FIELD_SORT" | "ENC_FIELD_AGG" | "ENC_FIELD_PATCH_OP" | "GEO_INDEX_MISSING" | "GEO_NOT_SUPPORTED" | "FILTER_TYPE_MISMATCH";
-declare class DbError extends Error {
-  readonly code: DbErrorCode;
-  readonly errors: Array<{
-    path: string;
-    message: string;
-  }>;
-  name: string;
-  constructor(code: DbErrorCode, errors: Array<{
-    path: string;
-    message: string;
-  }>, message?: string);
-}
-/**
- * Thrown by {@link withOptimisticRetry} when `maxAttempts` is reached
- * without a successful CAS commit — the target row kept changing under
- * the read-modify-write loop. Surfaces the attempt count and the
- * last-observed version so callers can log/report the contention.
- */
-declare class CasExhaustedError extends DbError {
-  readonly attempts: number;
-  readonly lastSeenVersion: number | undefined;
-  name: string;
-  constructor(attempts: number, lastSeenVersion: number | undefined);
-}
-//#endregion
 //#region src/query/query-guards.d.ts
 /**
  * Engine-agnostic query-time guards, applied in the core layer BEFORE filter
@@ -127,6 +100,11 @@ declare class CasExhaustedError extends DbError {
  * - `$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`
+ * - 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.
  */
 /** Validates a `[lng, lat]` tuple (GeoJSON coordinate order). */
 declare function assertGeoPoint(point: unknown, path: string): asserts point is [number, number];
@@ -135,14 +113,156 @@ declare function assertGeoPoint(point: unknown, path: string): asserts point is
  * validating `$geoWithin` operator nodes.
  */
 declare function guardFilter(meta: TableMetadata, adapter: BaseDbAdapter, filter: FilterExpr$1 | undefined, encCode?: "ENC_FIELD_FILTER" | "ENC_FIELD_AGG"): void;
-/** Shared read-path guard: filter + $sort. */
-declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: {
+/** The query positions a field path can appear in. */
+type TQueryPathOp = "filter" | "sort" | "select" | "groupBy" | "having" | "aggregate";
+/** Query shape accepted by {@link guardPaths} / {@link collectQueryPaths} — the raw (pre-translation) uniqu controls. */
+interface TGuardedQuery {
   filter?: FilterExpr$1;
   controls?: {
     $sort?: unknown;
+    $select?: unknown;
+    $groupBy?: unknown;
+    $having?: unknown;
+  };
+}
+/**
+ * The one wording for a filter-node `$`-key that is not `$and` / `$or` /
+ * `$not` (uniqu's walker would treat it as a field named `$…`). The core
+ * guard and the HTTP gate both answer with it; `path` is the operator itself.
+ */
+declare function unsupportedOperatorMessage(op: string): string;
+/**
+ * Normalizes every accepted `$sort` form (`"a,-b"`, `["a", "-b"]`,
+ * `[{ a: 1 }]`, `{ a: 1 }`) into its field names. Mirrors the HTTP layer's
+ * walker so programmatic callers get the same acceptance set.
+ */
+declare function sortFieldNames(sort: unknown): string[];
+/** Every logical path a parsed query references, grouped by position (since 0.1.128). */
+interface TQueryPathRefs {
+  /** Filter keys (recursing through `$and` / `$or` / `$not`), minus the geo predicates below. */
+  filter: string[];
+  /**
+   * Filter keys whose predicate is `$geoWithin`. Their shape and index support
+   * are validated by `guardFilter`, so the core path guard skips the adapter's
+   * scalar filter veto for them; the HTTP gate checks them like any filter path.
+   */
+  geoFilter: string[];
+  sort: string[];
+  select: string[];
+  groupBy: string[];
+  having: string[];
+  /** Aggregate `$field`s (`*` excluded). Only populated in aggregate mode. */
+  aggregate: string[];
+  /** `true` in aggregate mode: `$select` entries are aggregate expressions, aliases are exempt in `$sort` / `$having`. */
+  aggregateMode: boolean;
+  /**
+   * First filter-node `$`-key that is not `$and` / `$or` / `$not`. uniqu's
+   * walker would treat it as a field named `$…` — reject instead of 500.
+   */
+  unsupportedOperator?: string;
+}
+/**
+ * Walks the PARSED query structure (not the flattened insights map, which
+ * cannot tell `$select=assignee.name` from `$with=assignee($select=name)`)
+ * and returns the root paths per position. `$with` sub-trees are not
+ * 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).
+ */
+declare function collectQueryPaths(query: TGuardedQuery, aggregate?: boolean): TQueryPathRefs;
+/** What a logical path is on THIS readable / adapter (since 0.1.128). */
+type TQueryPathKind = /** A navigation relation or anything under one — never a column of this table. */"nav" /** A stored leaf (a non-ignored, non-nav descriptor). */ | "leaf" /** A nested-object parent: flattened away on relational adapters, an unlisted descriptor on nested-object ones. */ | "objectParent" /** A descendant of a JSON-stored column that this adapter cannot address (relational adapters). */ | "jsonDescendant" /** A descendant of an `@db.encrypted` field (the ciphertext column covers the subtree). */ | "encryptedDescendant" /** Unknown to this table. */ | "unknown";
+/** The lookups {@link classifyQueryPath} needs — `TableMetadata` and moost-db's `FieldCapabilityIndex` both provide them. */
+interface TQueryPathSource {
+  navFields: ReadonlySet<string>;
+  /** Stored leaves by logical path. */
+  leaves: {
+    has(path: string): boolean;
+  };
+  /** Nested-object parents by logical path. */
+  objectParents: {
+    has(path: string): boolean;
   };
-} | undefined): void;
-/** Aggregate-path guard: $groupBy / $select / $having refs + filter + $sort. */
+  jsonParents: ReadonlySet<string>;
+  encryptedFields: ReadonlySet<string>;
+}
+/**
+ * Classifies one logical path. The rules exist once, in this order, for the
+ * core backstop ({@link guardPath}) and the HTTP capability gate alike:
+ *
+ * 1. navigation relations (and anything under them) — `parent` is the nav
+ *    head when the path is a descendant;
+ * 2. a stored leaf;
+ * 3. a nested-object parent;
+ * 4. a descendant of a JSON-stored column — `parent` names the column;
+ * 5. a descendant of an `@db.encrypted` field — `parent` names the field;
+ * 6. unknown.
+ */
+declare function classifyQueryPath(source: TQueryPathSource, path: string): {
+  kind: TQueryPathKind;
+  parent?: string;
+};
+/**
+ * Validates ONE logical path for ONE query position against this table's
+ * 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 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.
+ *
+ * Messages are the short programmatic forms; the HTTP wording (moost-db's
+ * `FieldCapabilityIndex`, with `$with` hints and leaf lists) is what clients
+ * see and is authoritative — the HTTP gate always answers first.
+ */
+declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: string, op: TQueryPathOp, geoPredicate?: boolean): void;
+/**
+ * Core backstop for every read / aggregate / mutation-filter entry point:
+ * each referenced path (see {@link collectQueryPaths}) must exist on THIS
+ * adapter with the physical capability the position needs (see
+ * {@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`.
+ *
+ * Returns the collected refs so callers can run further structural rules
+ * (see {@link checkHavingKeys}) without walking the query again.
+ */
+declare function guardPaths(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined, aggregate?: boolean): TQueryPathRefs | undefined;
+/** Shared read-path guard: filter + $sort encryption checks, then the path guard. */
+declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined): void;
+/**
+ * `$having` is a post-aggregation filter, so a key is either an aggregate
+ * alias (`$as`, else `fn_field` — already exempt in {@link collectQueryPaths})
+ * or a `$groupBy` field (exact logical-path match: `metadata.clicks` grouped
+ * stays valid). Any other key — a real but non-grouped column included — is
+ * 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
+ * `Unknown field` rejection uses); `undefined` when every key is valid.
+ */
+declare function checkHavingKeys(refs: TQueryPathRefs): {
+  path: string;
+  message: string;
+} | undefined;
+/**
+ * Aggregate-path guard: $groupBy / $select / $having encryption refs + filter
+ * + $sort, then the path guard, then the `$having` key rule
+ * ({@link checkHavingKeys} — after the path guard so an unknown key still
+ * reads `Unknown field`).
+ */
 declare function guardAggregate(meta: TableMetadata, adapter: BaseDbAdapter, query: AggregateQuery$1): void;
 //#endregion
 //#region src/with-optimistic-retry.d.ts
@@ -164,6 +284,11 @@ interface WithOptimisticRetryOptions {
  * a version conflict (`matchedCount === 0`) it re-reads the row, calls the
  * mutator with the fresh state, and retries — up to `maxAttempts` times.
  *
+ * A mutator that returns `undefined` or an empty object `{}` aborts without
+ * writing: the helper resolves `{ matchedCount: 1, modifiedCount: 0 }` and the
+ * version does not move (since 0.1.128 — previously `{}` reported a fabricated
+ * match as well, but through the empty-patch short-circuit).
+ *
  * The filter (typically the primary key) is threaded into the update payload
  * so the table layer can extract the row identity. If `mutator` returns
  * fields that overlap with the filter, the patch wins (last-write semantics
@@ -177,7 +302,7 @@ interface WithOptimisticRetryOptions {
  * @throws {CasExhaustedError} if `maxAttempts` is reached without a
  *   successful commit.
  */
-declare function withOptimisticRetry<TRow extends Record<string, unknown>>(table: AtscriptDbTable, filter: Record<string, unknown>, mutator: (row: TRow) => Promise<Record<string, unknown>> | Record<string, unknown>, opts?: WithOptimisticRetryOptions): Promise<TDbUpdateResult>;
+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/patch/patch-decomposer.d.ts
 /**
@@ -237,4 +362,4 @@ declare function createFailureCollector(what: string): {
   throwIfAny: () => void;
 };
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardQuery, isDbFieldOp, isGeoIndexableType, isGeoPointType, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TDbWriteAction, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGuardedQuery, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReferencingForeignKey, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, findAncestorInSet, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, isAtscriptDbView, isDbFieldOp, isEmptyObject, isGeoIndexableType, isGeoPointType, isNavRelation, isPlainObject, isPrimitive, reconcileCas, resolveDesignType, separateCas, separateFieldOps, sortFieldNames, translateQueryTree, unsupportedOperatorMessage, walkFilter, withOptimisticRetry };

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { $ as TIdentification, A as TDbActionLevel, B as TDbIndexType, C as TCascadeResolver, D as TCrudPermissions, E as TCrudOp, F as TDbDeleteResult, G as TDbStorageType, H as TDbInsertResult, I as TDbFieldMeta, J as TExistingTableOption, K as TDbUpdateResult, L as TDbForeignKey, M as TDbCollation, N as TDbDefaultFn, O as TDbActionInfo, P as TDbDefaultValue, Q as TIdDescriptor, R as TDbIndex, S as PrimaryKeyOf, T as TColumnDiff, U as TDbReferentialAction, V as TDbInsertManyResult, W as TDbRelation, X as TFkLookupResolver, Y as TFieldMeta, Z as TFkLookupTarget, _ as FieldOpsFor, _t as TGenericLogger, a as TDbEncryptionOptions, at as TTableOptionDiff, b as NavPropsOf, c as BaseDbAdapter, ct as TWriteTableResolver, d as AggregateFn, dt as UniqueryControls, et as TMetaResponse, f as AggregateQuery, ft as WithRelation, g as DbQuery, gt as NoopLogger, h as DbControls, ht as isGeoPointType, i as DbEncryption, it as TSyncColumnResult, j as TDbActionProcessor, k as TDbActionIntent, l as AggregateControls, lt as TypedWithRelation, m as AtscriptDbWritable, mt as isGeoIndexableType, n as DbResponse, nt as TRelationInfo, o as DocumentFieldMapper, ot as TTableResolver, p as AggregateResult, pt as TableMetadata, q as TExistingColumn, r as resolveDesignType, rt as TSearchIndexInfo, s as FieldMappingStrategy, st as TValueFormatterPair, t as AtscriptDbReadable, tt as TMetadataOverrides, u as AggregateExpr, ut as Uniquery, v as FilterExpr, vt as UniquSelect, w as TCascadeTarget, x as OwnPropsOf, y as FlatOf, z as TDbIndexField } from "./db-readable-BkAGccv9.mjs";
-import { a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateFieldOps, h as separateCas, 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-DJRnNTVo.mjs";
-import { a as TViewColumnMapping, c as AtscriptQueryNode, d as TViewPlan, f as translateQueryTree, h as NativeIntegrity, i as AtscriptDbView, l as AtscriptRef, m as IntegrityStrategy, n as TAdapterFactory, o as AtscriptQueryComparison, p as AtscriptDbTable, r as TDbSpaceOptions, s as AtscriptQueryFieldRef, t as DbSpace, u as TViewJoin } from "./db-space-B_ASuDaR.mjs";
+import { $ as TDbWriteAction, A as TCrudPermissions, At as isGeoIndexableType, B as TDbForeignKey, C as NullableOptional, Ct as TWriteTableResolver, D as TCascadeTarget, Dt as WithRelation, E as TCascadeResolver, Et as UniqueryControls, F as TDbCollation, G as TDbInsertResult, H as TDbIndexField, I as TDbDefaultFn, J as TDbRelation, K as TDbObjectKind, L as TDbDefaultValue, M as TDbActionIntent, Mt as NoopLogger, N as TDbActionLevel, Nt as TGenericLogger, O as TColumnDiff, Ot as TableMetadata, P as TDbActionProcessor, Pt as UniquSelect, Q as TDbUpdateResult, R as TDbDeleteResult, S as NavPropsOf, St as TWriteOptions, T as PrimaryKeyOf, Tt as Uniquery, U as TDbIndexType, V as TDbIndex, W as TDbInsertManyResult, X as TDbRemoveGuardContext, Y as TDbRemoveGuard, Z as TDbStorageType, _ as DbQuery, _t as TSearchIndexInfo, a as TDbEncryptionOptions, at as TExistingForeignKey, b as FilterExpr, bt as TTableResolver, c as BaseDbAdapter, ct as TFkLookupResolver, d as AggregateFn, dt as TIdentification, et as TDbWriteGuard, f as AggregateQuery, ft as TMetaResponse, g as DbPatch, gt as TRelationInfo, h as DbControls, ht as TReferencingForeignKey, i as DbEncryption, it as TExistingColumn, j as TDbActionInfo, jt as isGeoPointType, k as TCrudOp, kt as findAncestorInSet, l as AggregateControls, lt as TFkLookupTarget, m as AtscriptDbWritable, mt as TPrimaryKeyChange, n as DbResponse, nt as TDeleteOptions, o as DocumentFieldMapper, ot as TExistingTableOption, p as AggregateResult, pt as TMetadataOverrides, q as TDbReferentialAction, r as resolveDesignType, rt as TEnsureTableOptions, s as FieldMappingStrategy, st as TFieldMeta, t as AtscriptDbReadable, tt as TDbWriteGuardContext, u as AggregateExpr, ut as TIdDescriptor, v as DbRow, vt as TSyncColumnResult, w as OwnPropsOf, wt as TypedWithRelation, x as FlatOf, xt as TValueFormatterPair, y as FieldOpsFor, yt as TTableOptionDiff, z as TDbFieldMeta } from "./db-readable-BTl4NzNN.mjs";
+import { _ as separateFieldOps, a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.mjs";
+import { a as TViewColumnMapping, c as AtscriptQueryFieldRef, d as TViewJoin, f as TViewPlan, g as NativeIntegrity, h as IntegrityStrategy, i as AtscriptDbView, l as AtscriptQueryNode, m as AtscriptDbTable, n as TAdapterFactory, o as isAtscriptDbView, p as translateQueryTree, r as TDbSpaceOptions, s as AtscriptQueryComparison, t as DbSpace, u as AtscriptRef } from "./db-space-BEB5Jl8M.mjs";
+import { a as buildValidationContext, c as isNavRelation, d as TArrayPatch, f as TDbPatch, g as DbErrorCode, h as DbError, l as isEmptyObject, m as CasExhaustedError, n as ValidatorMode, p as getKeyProps, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as isPlainObject } from "./validator-DuAmWc8L.mjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
-import { a as buildValidationContext, c as isNavRelation, d as getKeyProps, l as TArrayPatch, n as ValidatorMode, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch } from "./validator-BcBtg8yW.mjs";
 import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
 
 //#region src/shared/consts.d.ts
@@ -88,33 +88,6 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
   private buildCascadeChildFilter;
 }
 //#endregion
-//#region src/db-error.d.ts
-type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY" | "DEPTH_EXCEEDED" | "VERSION_COLUMN_WRITE" | "CAS_EXHAUSTED" | "ENC_CONFIG_MISSING" | "ENC_KEY_INVALID" | "ENC_NOT_ENCRYPTED" | "ENC_DECRYPT_FAILED" | "ENC_FIELD_FILTER" | "ENC_FIELD_SORT" | "ENC_FIELD_AGG" | "ENC_FIELD_PATCH_OP" | "GEO_INDEX_MISSING" | "GEO_NOT_SUPPORTED" | "FILTER_TYPE_MISMATCH";
-declare class DbError extends Error {
-  readonly code: DbErrorCode;
-  readonly errors: Array<{
-    path: string;
-    message: string;
-  }>;
-  name: string;
-  constructor(code: DbErrorCode, errors: Array<{
-    path: string;
-    message: string;
-  }>, message?: string);
-}
-/**
- * Thrown by {@link withOptimisticRetry} when `maxAttempts` is reached
- * without a successful CAS commit — the target row kept changing under
- * the read-modify-write loop. Surfaces the attempt count and the
- * last-observed version so callers can log/report the contention.
- */
-declare class CasExhaustedError extends DbError {
-  readonly attempts: number;
-  readonly lastSeenVersion: number | undefined;
-  name: string;
-  constructor(attempts: number, lastSeenVersion: number | undefined);
-}
-//#endregion
 //#region src/query/query-guards.d.ts
 /**
  * Engine-agnostic query-time guards, applied in the core layer BEFORE filter
@@ -127,6 +100,11 @@ declare class CasExhaustedError extends DbError {
  * - `$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`
+ * - 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.
  */
 /** Validates a `[lng, lat]` tuple (GeoJSON coordinate order). */
 declare function assertGeoPoint(point: unknown, path: string): asserts point is [number, number];
@@ -135,14 +113,156 @@ declare function assertGeoPoint(point: unknown, path: string): asserts point is
  * validating `$geoWithin` operator nodes.
  */
 declare function guardFilter(meta: TableMetadata, adapter: BaseDbAdapter, filter: FilterExpr$1 | undefined, encCode?: "ENC_FIELD_FILTER" | "ENC_FIELD_AGG"): void;
-/** Shared read-path guard: filter + $sort. */
-declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: {
+/** The query positions a field path can appear in. */
+type TQueryPathOp = "filter" | "sort" | "select" | "groupBy" | "having" | "aggregate";
+/** Query shape accepted by {@link guardPaths} / {@link collectQueryPaths} — the raw (pre-translation) uniqu controls. */
+interface TGuardedQuery {
   filter?: FilterExpr$1;
   controls?: {
     $sort?: unknown;
+    $select?: unknown;
+    $groupBy?: unknown;
+    $having?: unknown;
+  };
+}
+/**
+ * The one wording for a filter-node `$`-key that is not `$and` / `$or` /
+ * `$not` (uniqu's walker would treat it as a field named `$…`). The core
+ * guard and the HTTP gate both answer with it; `path` is the operator itself.
+ */
+declare function unsupportedOperatorMessage(op: string): string;
+/**
+ * Normalizes every accepted `$sort` form (`"a,-b"`, `["a", "-b"]`,
+ * `[{ a: 1 }]`, `{ a: 1 }`) into its field names. Mirrors the HTTP layer's
+ * walker so programmatic callers get the same acceptance set.
+ */
+declare function sortFieldNames(sort: unknown): string[];
+/** Every logical path a parsed query references, grouped by position (since 0.1.128). */
+interface TQueryPathRefs {
+  /** Filter keys (recursing through `$and` / `$or` / `$not`), minus the geo predicates below. */
+  filter: string[];
+  /**
+   * Filter keys whose predicate is `$geoWithin`. Their shape and index support
+   * are validated by `guardFilter`, so the core path guard skips the adapter's
+   * scalar filter veto for them; the HTTP gate checks them like any filter path.
+   */
+  geoFilter: string[];
+  sort: string[];
+  select: string[];
+  groupBy: string[];
+  having: string[];
+  /** Aggregate `$field`s (`*` excluded). Only populated in aggregate mode. */
+  aggregate: string[];
+  /** `true` in aggregate mode: `$select` entries are aggregate expressions, aliases are exempt in `$sort` / `$having`. */
+  aggregateMode: boolean;
+  /**
+   * First filter-node `$`-key that is not `$and` / `$or` / `$not`. uniqu's
+   * walker would treat it as a field named `$…` — reject instead of 500.
+   */
+  unsupportedOperator?: string;
+}
+/**
+ * Walks the PARSED query structure (not the flattened insights map, which
+ * cannot tell `$select=assignee.name` from `$with=assignee($select=name)`)
+ * and returns the root paths per position. `$with` sub-trees are not
+ * 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).
+ */
+declare function collectQueryPaths(query: TGuardedQuery, aggregate?: boolean): TQueryPathRefs;
+/** What a logical path is on THIS readable / adapter (since 0.1.128). */
+type TQueryPathKind = /** A navigation relation or anything under one — never a column of this table. */"nav" /** A stored leaf (a non-ignored, non-nav descriptor). */ | "leaf" /** A nested-object parent: flattened away on relational adapters, an unlisted descriptor on nested-object ones. */ | "objectParent" /** A descendant of a JSON-stored column that this adapter cannot address (relational adapters). */ | "jsonDescendant" /** A descendant of an `@db.encrypted` field (the ciphertext column covers the subtree). */ | "encryptedDescendant" /** Unknown to this table. */ | "unknown";
+/** The lookups {@link classifyQueryPath} needs — `TableMetadata` and moost-db's `FieldCapabilityIndex` both provide them. */
+interface TQueryPathSource {
+  navFields: ReadonlySet<string>;
+  /** Stored leaves by logical path. */
+  leaves: {
+    has(path: string): boolean;
+  };
+  /** Nested-object parents by logical path. */
+  objectParents: {
+    has(path: string): boolean;
   };
-} | undefined): void;
-/** Aggregate-path guard: $groupBy / $select / $having refs + filter + $sort. */
+  jsonParents: ReadonlySet<string>;
+  encryptedFields: ReadonlySet<string>;
+}
+/**
+ * Classifies one logical path. The rules exist once, in this order, for the
+ * core backstop ({@link guardPath}) and the HTTP capability gate alike:
+ *
+ * 1. navigation relations (and anything under them) — `parent` is the nav
+ *    head when the path is a descendant;
+ * 2. a stored leaf;
+ * 3. a nested-object parent;
+ * 4. a descendant of a JSON-stored column — `parent` names the column;
+ * 5. a descendant of an `@db.encrypted` field — `parent` names the field;
+ * 6. unknown.
+ */
+declare function classifyQueryPath(source: TQueryPathSource, path: string): {
+  kind: TQueryPathKind;
+  parent?: string;
+};
+/**
+ * Validates ONE logical path for ONE query position against this table's
+ * 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 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.
+ *
+ * Messages are the short programmatic forms; the HTTP wording (moost-db's
+ * `FieldCapabilityIndex`, with `$with` hints and leaf lists) is what clients
+ * see and is authoritative — the HTTP gate always answers first.
+ */
+declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: string, op: TQueryPathOp, geoPredicate?: boolean): void;
+/**
+ * Core backstop for every read / aggregate / mutation-filter entry point:
+ * each referenced path (see {@link collectQueryPaths}) must exist on THIS
+ * adapter with the physical capability the position needs (see
+ * {@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`.
+ *
+ * Returns the collected refs so callers can run further structural rules
+ * (see {@link checkHavingKeys}) without walking the query again.
+ */
+declare function guardPaths(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined, aggregate?: boolean): TQueryPathRefs | undefined;
+/** Shared read-path guard: filter + $sort encryption checks, then the path guard. */
+declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined): void;
+/**
+ * `$having` is a post-aggregation filter, so a key is either an aggregate
+ * alias (`$as`, else `fn_field` — already exempt in {@link collectQueryPaths})
+ * or a `$groupBy` field (exact logical-path match: `metadata.clicks` grouped
+ * stays valid). Any other key — a real but non-grouped column included — is
+ * 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
+ * `Unknown field` rejection uses); `undefined` when every key is valid.
+ */
+declare function checkHavingKeys(refs: TQueryPathRefs): {
+  path: string;
+  message: string;
+} | undefined;
+/**
+ * Aggregate-path guard: $groupBy / $select / $having encryption refs + filter
+ * + $sort, then the path guard, then the `$having` key rule
+ * ({@link checkHavingKeys} — after the path guard so an unknown key still
+ * reads `Unknown field`).
+ */
 declare function guardAggregate(meta: TableMetadata, adapter: BaseDbAdapter, query: AggregateQuery$1): void;
 //#endregion
 //#region src/with-optimistic-retry.d.ts
@@ -164,6 +284,11 @@ interface WithOptimisticRetryOptions {
  * a version conflict (`matchedCount === 0`) it re-reads the row, calls the
  * mutator with the fresh state, and retries — up to `maxAttempts` times.
  *
+ * A mutator that returns `undefined` or an empty object `{}` aborts without
+ * writing: the helper resolves `{ matchedCount: 1, modifiedCount: 0 }` and the
+ * version does not move (since 0.1.128 — previously `{}` reported a fabricated
+ * match as well, but through the empty-patch short-circuit).
+ *
  * The filter (typically the primary key) is threaded into the update payload
  * so the table layer can extract the row identity. If `mutator` returns
  * fields that overlap with the filter, the patch wins (last-write semantics
@@ -177,7 +302,7 @@ interface WithOptimisticRetryOptions {
  * @throws {CasExhaustedError} if `maxAttempts` is reached without a
  *   successful commit.
  */
-declare function withOptimisticRetry<TRow extends Record<string, unknown>>(table: AtscriptDbTable, filter: Record<string, unknown>, mutator: (row: TRow) => Promise<Record<string, unknown>> | Record<string, unknown>, opts?: WithOptimisticRetryOptions): Promise<TDbUpdateResult>;
+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/patch/patch-decomposer.d.ts
 /**
@@ -237,4 +362,4 @@ declare function createFailureCollector(what: string): {
   throwIfAny: () => void;
 };
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardQuery, isDbFieldOp, isGeoIndexableType, isGeoPointType, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TDbWriteAction, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGuardedQuery, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReferencingForeignKey, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, findAncestorInSet, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, isAtscriptDbView, isDbFieldOp, isEmptyObject, isGeoIndexableType, isGeoPointType, isNavRelation, isPlainObject, isPrimitive, reconcileCas, resolveDesignType, separateCas, separateFieldOps, sortFieldNames, translateQueryTree, unsupportedOperatorMessage, walkFilter, withOptimisticRetry };