@atscript/db 0.1.146 → 0.1.148

package/dist/index.d.cts

@@ -1,13 +1,13 @@
-import { $ as TDbUpdateResult, $t as AtscriptRef, A as TCrudPermissions, At as TViewJsonType, B as TDbFieldMeta, Bt as ALL_BUCKET_UNITS, C as NullableOptional, Ct as TRowResolveOptions, D as TCascadeTarget, Dt as TTableResolver, E as TCascadeResolver, Et as TTableOptionDiff, F as TDbAvailableActions, Ft as UniqueryControls, G as TDbInsertManyResult, Gt as AtscriptDbView, H as TDbIndex, Ht as DbSpace, I as TDbCollation, It as WithRelation, J as TDbReferentialAction, Jt as isViewType, K as TDbInsertResult, Kt as TViewColumnMapping, L as TDbDefaultFn, Lt as TableMetadata, M as TDbActionIntent, Mt as TWriteTableResolver, N as TDbActionLevel, Nt as TypedWithRelation, O as TColumnDiff, Ot as TTouchManyOptions, P as TDbActionProcessor, Pt as Uniquery, Q as TDbStorageType, Qt as AtscriptQueryNode, R as TDbDefaultValue, Rt as isGeoIndexableType, S as NavPropsOf, St as TRelationInfo, T as PrimaryKeyOf, Tt as TSyncColumnResult, U as TDbIndexField, Ut as TAdapterFactory, V as TDbForeignKey, Vt as BaseDbAdapter, W as TDbIndexType, Wt as TDbSpaceOptions, X as TDbRemoveGuard, Xt as AtscriptQueryComparison, Y as TDbRelation, Yt as aliasTargetOf, Z as TDbRemoveGuardContext, Zt as AtscriptQueryFieldRef, _ as DbQuery, _n as UniquSelect, _t as TIdentification, a as jsonValueAncestor, an as IntegrityStrategy, at as TDeleteOptions, b as FilterExpr, bt as TPrimaryKeyChange, c as AggregateControls, cn as DbResponse, ct as TEnsureTableOptions, d as AggregateQuery, dn as TDbEncryptionOptions, dt as TExistingTableOption, en as TViewJoin, et as TDbWriteAction, f as AggregateResult, fn as DocumentFieldMapper, ft as TFieldMeta, g as DbPatch, gn as TGenericLogger, gt as TIdResolveOptions, h as DbControls, hn as NoopLogger, ht as TIdDescriptor, i as isJsonValueField, in as AtscriptDbTable, it as TDbWriteGuardContext, j as TDbActionInfo, jt as TWriteOptions, k as TCrudOp, kt as TValueFormatterPair, l as AggregateExpr, ln as resolveDesignType, lt as TExistingColumn, m as AtscriptDbWritable, mn as TReadControls, mt as TFkLookupTarget, n as TResolvedBucket, nn as isFieldRef, nt as TDbWriteCheckContext, o as normalizeComputedSelect, on as NativeIntegrity, ot as TDerivedChangeReason, pn as FieldMappingStrategy, pt as TFkLookupResolver, q as TDbObjectKind, qt as isAtscriptDbView, r as isBucketableField, rn as translateQueryTree, rt as TDbWriteGuard, s as resolveCalendarBuckets, sn as AtscriptDbReadable, st as TDerivedColumn, t as TBucketFieldSource, tn as TViewPlan, tt as TDbWriteCheck, u as AggregateFn, un as DbEncryption, ut as TExistingForeignKey, v as DbRow, vt as TMetaResponse, w as OwnPropsOf, wt as TSearchIndexInfo, x as FlatOf, xt as TReferencingForeignKey, y as FieldOpsFor, yt as TMetadataOverrides, z as TDbDeleteResult, zt as isGeoPointType } from "./buckets-DYFu0eZ8.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-Bw6ks9Hy.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 { n as isColumnTypeChanged } from "./column-diff-w-Mym_3w.cjs";
-import { i as tableNameOf } from "./relation-helpers-BOMm_HUI.cjs";
-import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, ResolvedBucket as ResolvedBucket$1, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
-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
 /**
@@ -30,14 +30,16 @@ declare class RelationalFieldMapper extends FieldMappingStrategy {
   /** The flattened column of a logical path (`contact.email` → `contact__email`). */
   protected physicalPath(logical: string, meta: TableMetadata): string;
   /**
-   * Overrides the base `translateFilter` to use `leafByLogical` for key resolution
+   * Overrides the base `translateResolvedFilter` to use `leafByLogical` for key resolution
    * (handles flattened nested paths like `contact.email` → `contact__email`).
    */
-  translateFilter(filter: FilterExpr$1, meta: TableMetadata): FilterExpr$1;
+  protected translateResolvedFilter(filter: FilterExpr$1, meta: TableMetadata): FilterExpr$1;
   /**
    * Translates filter with key renaming from logical to physical names.
    * Used by the relational query path where field paths must be mapped
-   * to `__`-separated column names.
+   * to `__`-separated column names. Relational predicates must already be
+   * resolved (`translateFilter` / `translateQuery` do it); a resolved
+   * predicate passes through under its navigation-field key.
    */
   translateFilterWithRename(filter: FilterExpr$1, meta: TableMetadata): FilterExpr$1;
   prepareForWrite(payload: Record<string, unknown>, meta: TableMetadata, adapter: BaseDbAdapter): Record<string, unknown>;
@@ -83,8 +85,14 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
    * - `restrict`: throws if any children exist
    * - `cascade`: recursively deletes child records
    * - `setNull`: sets FK fields to null
+   *
+   * When `filter` holds a relational predicate, returns the matched rows
+   * PINNED by primary key (see {@link TCascadePin}): the caller deletes those
+   * rows, never re-evaluating `filter` on data the cascade just changed (a
+   * `$some` over a cascaded child relation would otherwise stop matching and
+   * leave the parent behind). Any other filter → `undefined`.
    */
-  cascadeBeforeDelete(filter: FilterExpr$1, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr$1) => FilterExpr$1, adapter: BaseDbAdapter): Promise<void>;
+  cascadeBeforeDelete(filter: FilterExpr$1, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr$1) => FilterExpr$1, adapter: BaseDbAdapter): Promise<TCascadePin>;
   needsCascade(cascadeResolver: TCascadeResolver | undefined): boolean;
   private recordKey;
   /**
@@ -119,6 +127,9 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
  *   {@link canFilterLeaf}) needs → `INVALID_QUERY` (see {@link guardPaths}).
  *   Runs after the checks above so `ENC_*` codes keep firing first for
  *   encrypted subtrees.
+ * - every filter / `$having` comparison value must be able to denote its
+ *   field's declared type (`?n='x'` on a number) → `INVALID_QUERY`, after
+ *   the path guard (see `guardFilterValues`, since 0.1.147).
  */
 /** Validates a `[lng, lat]` tuple (GeoJSON coordinate order). */
 declare function assertGeoPoint(point: unknown, path: string): asserts point is [number, number];
@@ -138,6 +149,7 @@ interface TGuardedQuery {
     $select?: unknown;
     $groupBy?: unknown;
     $having?: unknown;
+    $rowOrder?: unknown;
   };
 }
 /**
@@ -156,13 +168,23 @@ declare function sortFieldNames(sort: unknown): string[];
  * The operator class a filter entry needs from its field (since 0.1.132):
  * - `compare` — value comparison (bare values, `$eq`, `$gt`, `$in`, `$regex`, any mix);
  * - `geo` — a `$geoWithin` entry;
- * - `exists` — an entry whose sole operator is `$exists`.
+ * - `exists` — an entry whose sole operator is `$exists`;
+ * - `relation` — a relational predicate (`$some` / `$none` only) on a
+ *   navigation field (since 0.1.147).
  */
-type TFilterPredicate = "compare" | "geo" | "exists";
+type TFilterPredicate = "compare" | "geo" | "exists" | "relation";
 /** One filter entry, collected per occurrence: its key and the predicate class its operators need. */
 interface TFilterRef {
   path: string;
   predicate: TFilterPredicate;
+  /**
+   * `relation` entries: each operator with its operand (a filter on the
+   * related table, not walked here). @since 0.1.147
+   */
+  relation?: Array<{
+    op: RelationOp$1;
+    filter: FilterExpr$1;
+  }>;
 }
 /**
  * The reason clause for a leaf the adapter cannot filter (value comparison).
@@ -223,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
@@ -281,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.
  *
@@ -357,16 +402,20 @@ declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: st
  * `bucket`), `$groupBy` fields are checked, and computed aliases (`$as` or
  * the default) are exempt in `$sort` / `$having`.
  *
+ * Then every filter comparison value must be able to denote its field's
+ * declared type (`guardFilterValues`, since 0.1.147) — after the paths, so
+ * an unknown or unfilterable field keeps its own rejection.
+ *
  * 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;
+declare function guardPaths(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined, aggregate?: boolean, state?: TRelGuardState): TQueryPathRefs | undefined;
 /**
  * Shared read-path guard: filter + $sort encryption checks, the `$select`
  * normalizer (a calendar bucket is invalid outside a grouped query), then
  * the path guard.
  */
-declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined): void;
+declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined, state?: TRelGuardState): void;
 /**
  * `$having` is a post-aggregation filter, so a key is either a computed
  * alias (aggregate or calendar bucket — already exempt in
@@ -387,12 +436,13 @@ declare function checkHavingKeys(refs: TQueryPathRefs): {
  * (`AGG_FN_NOT_SUPPORTED`) and calendar-bucket units
  * (`BUCKET_NOT_SUPPORTED`), then the `$having` key rule
  * ({@link checkHavingKeys} — after the path guard so an unknown key still
- * reads `Unknown field`).
+ * 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 {
@@ -433,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
@@ -531,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, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type ResolvedBucket, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TBucketSourceTable, type TBucketSourceVerdict, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type 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 TRelationInfo, type TResolvedBucket, type TRowResolveOptions, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, 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, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, deletePath, findAncestorInSet, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, reconcileCas, 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 };

package/dist/index.d.mts

@@ -1,13 +1,13 @@
-import { $ as TDbUpdateResult, $t as AtscriptRef, A as TCrudPermissions, At as TViewJsonType, B as TDbFieldMeta, Bt as ALL_BUCKET_UNITS, C as NullableOptional, Ct as TRowResolveOptions, D as TCascadeTarget, Dt as TTableResolver, E as TCascadeResolver, Et as TTableOptionDiff, F as TDbAvailableActions, Ft as UniqueryControls, G as TDbInsertManyResult, Gt as AtscriptDbView, H as TDbIndex, Ht as DbSpace, I as TDbCollation, It as WithRelation, J as TDbReferentialAction, Jt as isViewType, K as TDbInsertResult, Kt as TViewColumnMapping, L as TDbDefaultFn, Lt as TableMetadata, M as TDbActionIntent, Mt as TWriteTableResolver, N as TDbActionLevel, Nt as TypedWithRelation, O as TColumnDiff, Ot as TTouchManyOptions, P as TDbActionProcessor, Pt as Uniquery, Q as TDbStorageType, Qt as AtscriptQueryNode, R as TDbDefaultValue, Rt as isGeoIndexableType, S as NavPropsOf, St as TRelationInfo, T as PrimaryKeyOf, Tt as TSyncColumnResult, U as TDbIndexField, Ut as TAdapterFactory, V as TDbForeignKey, Vt as BaseDbAdapter, W as TDbIndexType, Wt as TDbSpaceOptions, X as TDbRemoveGuard, Xt as AtscriptQueryComparison, Y as TDbRelation, Yt as aliasTargetOf, Z as TDbRemoveGuardContext, Zt as AtscriptQueryFieldRef, _ as DbQuery, _n as UniquSelect, _t as TIdentification, a as jsonValueAncestor, an as IntegrityStrategy, at as TDeleteOptions, b as FilterExpr, bt as TPrimaryKeyChange, c as AggregateControls, cn as DbResponse, ct as TEnsureTableOptions, d as AggregateQuery, dn as TDbEncryptionOptions, dt as TExistingTableOption, en as TViewJoin, et as TDbWriteAction, f as AggregateResult, fn as DocumentFieldMapper, ft as TFieldMeta, g as DbPatch, gn as TGenericLogger, gt as TIdResolveOptions, h as DbControls, hn as NoopLogger, ht as TIdDescriptor, i as isJsonValueField, in as AtscriptDbTable, it as TDbWriteGuardContext, j as TDbActionInfo, jt as TWriteOptions, k as TCrudOp, kt as TValueFormatterPair, l as AggregateExpr, ln as resolveDesignType, lt as TExistingColumn, m as AtscriptDbWritable, mn as TReadControls, mt as TFkLookupTarget, n as TResolvedBucket, nn as isFieldRef, nt as TDbWriteCheckContext, o as normalizeComputedSelect, on as NativeIntegrity, ot as TDerivedChangeReason, pn as FieldMappingStrategy, pt as TFkLookupResolver, q as TDbObjectKind, qt as isAtscriptDbView, r as isBucketableField, rn as translateQueryTree, rt as TDbWriteGuard, s as resolveCalendarBuckets, sn as AtscriptDbReadable, st as TDerivedColumn, t as TBucketFieldSource, tn as TViewPlan, tt as TDbWriteCheck, u as AggregateFn, un as DbEncryption, ut as TExistingForeignKey, v as DbRow, vt as TMetaResponse, w as OwnPropsOf, wt as TSearchIndexInfo, x as FlatOf, xt as TReferencingForeignKey, y as FieldOpsFor, yt as TMetadataOverrides, z as TDbDeleteResult, zt as isGeoPointType } from "./buckets-DRycmhOW.mjs";
+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-CNdTOnei.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 isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, t as deletePath } from "./object-CtPYTIvy.mjs";
-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-D5DHsAby.mjs";
-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-Bw6ks9Hy.mjs";
+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-Wo-smrYV.mjs";
+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.mjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
-import { n as isColumnTypeChanged } from "./column-diff-Q9UmWn5x.mjs";
-import { i as tableNameOf } from "./relation-helpers-B-0NRKat.mjs";
-import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
-import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, ResolvedBucket as ResolvedBucket$1, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
+import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-DsaIijVX.mjs";
+import { i as tableNameOf } from "./relation-helpers-Ba0v49sn.mjs";
+import { AtscriptExprNode as AtscriptExprNode$1, TAtscriptAnnotatedType } from "@atscript/typescript/utils";
+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";
 
 //#region src/shared/consts.d.ts
 /**
@@ -30,14 +30,16 @@ declare class RelationalFieldMapper extends FieldMappingStrategy {
   /** The flattened column of a logical path (`contact.email` → `contact__email`). */
   protected physicalPath(logical: string, meta: TableMetadata): string;
   /**
-   * Overrides the base `translateFilter` to use `leafByLogical` for key resolution
+   * Overrides the base `translateResolvedFilter` to use `leafByLogical` for key resolution
    * (handles flattened nested paths like `contact.email` → `contact__email`).
    */
-  translateFilter(filter: FilterExpr$1, meta: TableMetadata): FilterExpr$1;
+  protected translateResolvedFilter(filter: FilterExpr$1, meta: TableMetadata): FilterExpr$1;
   /**
    * Translates filter with key renaming from logical to physical names.
    * Used by the relational query path where field paths must be mapped
-   * to `__`-separated column names.
+   * to `__`-separated column names. Relational predicates must already be
+   * resolved (`translateFilter` / `translateQuery` do it); a resolved
+   * predicate passes through under its navigation-field key.
    */
   translateFilterWithRename(filter: FilterExpr$1, meta: TableMetadata): FilterExpr$1;
   prepareForWrite(payload: Record<string, unknown>, meta: TableMetadata, adapter: BaseDbAdapter): Record<string, unknown>;
@@ -83,8 +85,14 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
    * - `restrict`: throws if any children exist
    * - `cascade`: recursively deletes child records
    * - `setNull`: sets FK fields to null
+   *
+   * When `filter` holds a relational predicate, returns the matched rows
+   * PINNED by primary key (see {@link TCascadePin}): the caller deletes those
+   * rows, never re-evaluating `filter` on data the cascade just changed (a
+   * `$some` over a cascaded child relation would otherwise stop matching and
+   * leave the parent behind). Any other filter → `undefined`.
    */
-  cascadeBeforeDelete(filter: FilterExpr$1, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr$1) => FilterExpr$1, adapter: BaseDbAdapter): Promise<void>;
+  cascadeBeforeDelete(filter: FilterExpr$1, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr$1) => FilterExpr$1, adapter: BaseDbAdapter): Promise<TCascadePin>;
   needsCascade(cascadeResolver: TCascadeResolver | undefined): boolean;
   private recordKey;
   /**
@@ -119,6 +127,9 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
  *   {@link canFilterLeaf}) needs → `INVALID_QUERY` (see {@link guardPaths}).
  *   Runs after the checks above so `ENC_*` codes keep firing first for
  *   encrypted subtrees.
+ * - every filter / `$having` comparison value must be able to denote its
+ *   field's declared type (`?n='x'` on a number) → `INVALID_QUERY`, after
+ *   the path guard (see `guardFilterValues`, since 0.1.147).
  */
 /** Validates a `[lng, lat]` tuple (GeoJSON coordinate order). */
 declare function assertGeoPoint(point: unknown, path: string): asserts point is [number, number];
@@ -138,6 +149,7 @@ interface TGuardedQuery {
     $select?: unknown;
     $groupBy?: unknown;
     $having?: unknown;
+    $rowOrder?: unknown;
   };
 }
 /**
@@ -156,13 +168,23 @@ declare function sortFieldNames(sort: unknown): string[];
  * The operator class a filter entry needs from its field (since 0.1.132):
  * - `compare` — value comparison (bare values, `$eq`, `$gt`, `$in`, `$regex`, any mix);
  * - `geo` — a `$geoWithin` entry;
- * - `exists` — an entry whose sole operator is `$exists`.
+ * - `exists` — an entry whose sole operator is `$exists`;
+ * - `relation` — a relational predicate (`$some` / `$none` only) on a
+ *   navigation field (since 0.1.147).
  */
-type TFilterPredicate = "compare" | "geo" | "exists";
+type TFilterPredicate = "compare" | "geo" | "exists" | "relation";
 /** One filter entry, collected per occurrence: its key and the predicate class its operators need. */
 interface TFilterRef {
   path: string;
   predicate: TFilterPredicate;
+  /**
+   * `relation` entries: each operator with its operand (a filter on the
+   * related table, not walked here). @since 0.1.147
+   */
+  relation?: Array<{
+    op: RelationOp$1;
+    filter: FilterExpr$1;
+  }>;
 }
 /**
  * The reason clause for a leaf the adapter cannot filter (value comparison).
@@ -223,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
@@ -281,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.
  *
@@ -357,16 +402,20 @@ declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: st
  * `bucket`), `$groupBy` fields are checked, and computed aliases (`$as` or
  * the default) are exempt in `$sort` / `$having`.
  *
+ * Then every filter comparison value must be able to denote its field's
+ * declared type (`guardFilterValues`, since 0.1.147) — after the paths, so
+ * an unknown or unfilterable field keeps its own rejection.
+ *
  * 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;
+declare function guardPaths(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined, aggregate?: boolean, state?: TRelGuardState): TQueryPathRefs | undefined;
 /**
  * Shared read-path guard: filter + $sort encryption checks, the `$select`
  * normalizer (a calendar bucket is invalid outside a grouped query), then
  * the path guard.
  */
-declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined): void;
+declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined, state?: TRelGuardState): void;
 /**
  * `$having` is a post-aggregation filter, so a key is either a computed
  * alias (aggregate or calendar bucket — already exempt in
@@ -387,12 +436,13 @@ declare function checkHavingKeys(refs: TQueryPathRefs): {
  * (`AGG_FN_NOT_SUPPORTED`) and calendar-bucket units
  * (`BUCKET_NOT_SUPPORTED`), then the `$having` key rule
  * ({@link checkHavingKeys} — after the path guard so an unknown key still
- * reads `Unknown field`).
+ * 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 {
@@ -433,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
@@ -531,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, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type ResolvedBucket, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TBucketSourceTable, type TBucketSourceVerdict, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type 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 TRelationInfo, type TResolvedBucket, type TRowResolveOptions, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, 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, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, deletePath, findAncestorInSet, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, reconcileCas, 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 };