@atscript/db 0.1.127 → 0.1.129

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 findAncestorInSet, B as TDbForeignKey, C as NullableOptional, Ct as TWriteOptions, D as TCascadeTarget, Dt as UniqueryControls, E as TCascadeResolver, Et as Uniquery, F as TDbCollation, Ft as UniquSelect, G as TDbInsertResult, H as TDbIndexField, I as TDbDefaultFn, J as TDbRelation, K as TDbObjectKind, L as TDbDefaultValue, M as TDbActionIntent, Mt as isGeoPointType, N as TDbActionLevel, Nt as NoopLogger, O as TColumnDiff, Ot as WithRelation, P as TDbActionProcessor, Pt as TGenericLogger, Q as TDbUpdateResult, R as TDbDeleteResult, S as NavPropsOf, St as TValueFormatterPair, T as PrimaryKeyOf, Tt as TypedWithRelation, 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 isGeoIndexableType, k as TCrudOp, kt as TableMetadata, 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 TWriteTableResolver, x as FlatOf, xt as TTouchManyOptions, y as FieldOpsFor, yt as TTableOptionDiff, z as TDbFieldMeta } from "./db-readable-Bn1bV_eC.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-DdIPYD0Q.mjs";
+import { _ as DbErrorCode, a as buildValidationContext, c as isNavRelation, d as TArrayPatch, f as TDbPatch, g as DbError, h as CasMismatchError, l as isEmptyObject, m as CasExhaustedError, n as ValidatorMode, p as getKeyProps, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as isPlainObject } from "./validator-wBARmD68.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, CasMismatchError, 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 TTouchManyOptions, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type 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.mjs

@@ -1,8 +1,8 @@
-import { n as DbError, t as CasExhaustedError } from "./db-error-BHPXOKzc.mjs";
-import { C as NoopLogger, S as isGeoPointType, _ as DocumentFieldMapper, a as ApplicationIntegrity, b as TableMetadata, c as IntegrityStrategy, d as resolveDesignType, f as assertGeoPoint, g as RelationalFieldMapper, h as guardQuery, i as decomposePatch, l as NativeIntegrity, m as guardFilter, n as AtscriptDbTable, o as BaseDbAdapter, p as guardAggregate, r as assertNoVersionWrites, s as createFailureCollector, t as AtscriptDbView, u as AtscriptDbReadable, v as FieldMappingStrategy, x as isGeoIndexableType, y as UniquSelect } from "./db-view-C8rZM5_N.mjs";
+import { n as CasMismatchError, r as DbError, t as CasExhaustedError } from "./db-error-COrO58t5.mjs";
+import { A as isGeoIndexableType, C as unsupportedOperatorMessage, D as UniquSelect, E as FieldMappingStrategy, M as NoopLogger, O as TableMetadata, S as sortFieldNames, T as DocumentFieldMapper, _ as guardAggregate, a as decomposePatch, b as guardPaths, c as createFailureCollector, d as AtscriptDbReadable, f as resolveDesignType, g as collectQueryPaths, h as classifyQueryPath, i as assertNoVersionWrites, j as isGeoPointType, k as findAncestorInSet, l as IntegrityStrategy, m as checkHavingKeys, n as isAtscriptDbView, o as ApplicationIntegrity, p as assertGeoPoint, r as AtscriptDbTable, s as BaseDbAdapter, t as AtscriptDbView, u as NativeIntegrity, v as guardFilter, w as RelationalFieldMapper, x as guardQuery, y as guardPath } from "./db-view-Dl0aDTiT.mjs";
+import { a as forceNavNonOptional, c as getKeyProps, l as isEmptyObject, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator, u as isPlainObject } from "./validator-CeD_fqyW.mjs";
 import { t as DEFAULT_DB_SPACE } from "./consts-C_-5_pFq.mjs";
-import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, separateCas, separateFieldOps } from "./ops.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-0vRXN51D.mjs";
+import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, reconcileCas, separateCas, separateFieldOps } from "./ops.mjs";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import { computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
 //#region src/encryption.ts
@@ -149,6 +149,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
@@ -178,6 +183,10 @@ async function withOptimisticRetry(table, filter, mutator, opts) {
 		}]);
 		lastSeenVersion = row[versionColumn];
 		const patch = await mutator(row);
+		if (patch === void 0 || isEmptyObject(patch)) return {
+			matchedCount: 1,
+			modifiedCount: 0
+		};
 		const result = await table.updateOne({
 			...filter,
 			...patch,
@@ -293,6 +302,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();
 	}
@@ -340,4 +372,4 @@ function translateQueryTree(node, resolveField) {
 	return { [leftField]: { [comp.op]: comp.right } };
 }
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, DEFAULT_DB_SPACE, DbEncryption, DbError, DbSpace, DocumentFieldMapper, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RelationalFieldMapper, TableMetadata, UniquSelect, 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, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, CasMismatchError, DEFAULT_DB_SPACE, DbEncryption, DbError, DbSpace, DocumentFieldMapper, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RelationalFieldMapper, TableMetadata, UniquSelect, 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/{nested-writer-DI-HeTky.mjs → nested-writer-CkDo-ZfH.mjs}

@@ -1,4 +1,4 @@
-import { n as DbError, r as DepthLimitExceededError } from "./db-error-BHPXOKzc.mjs";
+import { i as DepthLimitExceededError, r as DbError } from "./db-error-COrO58t5.mjs";
 import { ValidatorError } from "@atscript/typescript/utils";
 //#region src/rel/relation-helpers.ts
 /**

package/dist/{nested-writer-DoDhl3X3.cjs → nested-writer-DxPhmWFz.cjs}

@@ -1,4 +1,4 @@
-const require_db_error = require("./db-error-DXwEzmYJ.cjs");
+const require_db_error = require("./db-error-C4JuLcvb.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 //#region src/rel/relation-helpers.ts
 /**

package/dist/{ops-DJRnNTVo.d.cts → ops-AqhV7s9o.d.cts}

@@ -109,6 +109,29 @@ declare function separateFieldOps(data: Record<string, unknown>): TFieldOps | un
  *
  * Zero-allocation on the no-op (no `$cas`) path.
  */
+/**
+ * Reconciles the two spellings of one write item's expected version, in
+ * place (since 0.1.128): the SDK operator `$cas: { [versionColumn]: N }` and a
+ * top-level `[versionColumn]: N` (the HTTP wire shape, where a body's version
+ * column is a CAS predicate, not a SET). Shared by the moost-db controller
+ * (`target: "cas"` — normalises to `$cas` for the table) and the db-client
+ * (`target: "version"` — normalises to the wire shape).
+ *
+ * - neither present → no-op, returns `undefined`
+ * - one present → normalised to `target`, returns the expected version
+ * - both present and equal → normalised once
+ * - both present and different → `DbError("INVALID_QUERY")` at path `$cas`:
+ *   `Ambiguous version: "<col>" and "$cas.<col>" differ`
+ * - `$cas` malformed → {@link separateCas}'s own error (checked first, so a
+ *   malformed `$cas` is never reported as "ambiguous")
+ * - `$cas: undefined` counts as absent (the key is dropped)
+ * - `versionColumn === undefined` with a `$cas` → {@link separateCas}'s
+ *   "table has no @db.column.version" error
+ *
+ * Only a finite number counts as a present version column value — anything
+ * else is left untouched for the write validator to reject.
+ */
+declare function reconcileCas(data: Record<string, unknown>, versionColumn: string | undefined, target: "cas" | "version"): number | undefined;
 declare function separateCas(data: Record<string, unknown>, versionColumn?: string): number | undefined;
 //#endregion
-export { $mul as a, $update as c, TDbFieldOp as d, TFieldOps as f, separateFieldOps as g, separateCas as h, $insert as i, $upsert as l, isDbFieldOp as m, $dec as n, $remove as o, getDbFieldOp as p, $inc as r, $replace as s, $cas as t, TDbCas as u };
+export { separateFieldOps as _, $mul as a, $update as c, TDbFieldOp as d, TFieldOps as f, separateCas as g, reconcileCas as h, $insert as i, $upsert as l, isDbFieldOp as m, $dec as n, $remove as o, getDbFieldOp as p, $inc as r, $replace as s, $cas as t, TDbCas as u };

package/dist/{ops-DJRnNTVo.d.mts → ops-AqhV7s9o.d.mts}

@@ -109,6 +109,29 @@ declare function separateFieldOps(data: Record<string, unknown>): TFieldOps | un
  *
  * Zero-allocation on the no-op (no `$cas`) path.
  */
+/**
+ * Reconciles the two spellings of one write item's expected version, in
+ * place (since 0.1.128): the SDK operator `$cas: { [versionColumn]: N }` and a
+ * top-level `[versionColumn]: N` (the HTTP wire shape, where a body's version
+ * column is a CAS predicate, not a SET). Shared by the moost-db controller
+ * (`target: "cas"` — normalises to `$cas` for the table) and the db-client
+ * (`target: "version"` — normalises to the wire shape).
+ *
+ * - neither present → no-op, returns `undefined`
+ * - one present → normalised to `target`, returns the expected version
+ * - both present and equal → normalised once
+ * - both present and different → `DbError("INVALID_QUERY")` at path `$cas`:
+ *   `Ambiguous version: "<col>" and "$cas.<col>" differ`
+ * - `$cas` malformed → {@link separateCas}'s own error (checked first, so a
+ *   malformed `$cas` is never reported as "ambiguous")
+ * - `$cas: undefined` counts as absent (the key is dropped)
+ * - `versionColumn === undefined` with a `$cas` → {@link separateCas}'s
+ *   "table has no @db.column.version" error
+ *
+ * Only a finite number counts as a present version column value — anything
+ * else is left untouched for the write validator to reject.
+ */
+declare function reconcileCas(data: Record<string, unknown>, versionColumn: string | undefined, target: "cas" | "version"): number | undefined;
 declare function separateCas(data: Record<string, unknown>, versionColumn?: string): number | undefined;
 //#endregion
-export { $mul as a, $update as c, TDbFieldOp as d, TFieldOps as f, separateFieldOps as g, separateCas as h, $insert as i, $upsert as l, isDbFieldOp as m, $dec as n, $remove as o, getDbFieldOp as p, $inc as r, $replace as s, $cas as t, TDbCas as u };
+export { separateFieldOps as _, $mul as a, $update as c, TDbFieldOp as d, TFieldOps as f, separateCas as g, reconcileCas as h, $insert as i, $upsert as l, isDbFieldOp as m, $dec as n, $remove as o, getDbFieldOp as p, $inc as r, $replace as s, $cas as t, TDbCas as u };

package/dist/ops.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_error = require("./db-error-DXwEzmYJ.cjs");
+const require_db_error = require("./db-error-C4JuLcvb.cjs");
 //#region src/ops.ts
 /** Increment a numeric field by `value` (default 1). */
 function $inc(value = 1) {
@@ -144,6 +144,48 @@ function separateFieldOps(data) {
 *
 * Zero-allocation on the no-op (no `$cas`) path.
 */
+/**
+* Reconciles the two spellings of one write item's expected version, in
+* place (since 0.1.128): the SDK operator `$cas: { [versionColumn]: N }` and a
+* top-level `[versionColumn]: N` (the HTTP wire shape, where a body's version
+* column is a CAS predicate, not a SET). Shared by the moost-db controller
+* (`target: "cas"` — normalises to `$cas` for the table) and the db-client
+* (`target: "version"` — normalises to the wire shape).
+*
+* - neither present → no-op, returns `undefined`
+* - one present → normalised to `target`, returns the expected version
+* - both present and equal → normalised once
+* - both present and different → `DbError("INVALID_QUERY")` at path `$cas`:
+*   `Ambiguous version: "<col>" and "$cas.<col>" differ`
+* - `$cas` malformed → {@link separateCas}'s own error (checked first, so a
+*   malformed `$cas` is never reported as "ambiguous")
+* - `$cas: undefined` counts as absent (the key is dropped)
+* - `versionColumn === undefined` with a `$cas` → {@link separateCas}'s
+*   "table has no @db.column.version" error
+*
+* Only a finite number counts as a present version column value — anything
+* else is left untouched for the write validator to reject.
+*/
+function reconcileCas(data, versionColumn, target) {
+	if ("$cas" in data && data.$cas === void 0) delete data.$cas;
+	const versionValue = versionColumn === void 0 ? void 0 : data[versionColumn];
+	const hasVersion = typeof versionValue === "number" && Number.isFinite(versionValue);
+	const hasCas = "$cas" in data;
+	if (!hasCas && !hasVersion) return void 0;
+	let expected;
+	if (hasCas) {
+		expected = separateCas(data, versionColumn);
+		if (hasVersion && versionValue !== expected) throw new require_db_error.DbError("INVALID_QUERY", [{
+			path: "$cas",
+			message: `Ambiguous version: "${versionColumn}" and "$cas.${versionColumn}" differ`
+		}]);
+	} else expected = versionValue;
+	if (target === "cas") {
+		delete data[versionColumn];
+		data.$cas = { [versionColumn]: expected };
+	} else data[versionColumn] = expected;
+	return expected;
+}
 function separateCas(data, versionColumn) {
 	if (!("$cas" in data)) return void 0;
 	if (versionColumn === void 0) throw new require_db_error.DbError("INVALID_QUERY", [{
@@ -192,5 +234,6 @@ exports.$update = $update;
 exports.$upsert = $upsert;
 exports.getDbFieldOp = getDbFieldOp;
 exports.isDbFieldOp = isDbFieldOp;
+exports.reconcileCas = reconcileCas;
 exports.separateCas = separateCas;
 exports.separateFieldOps = separateFieldOps;

package/dist/ops.d.cts

@@ -1,2 +1,2 @@
-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";
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, TDbCas, TDbFieldOp, TFieldOps, getDbFieldOp, isDbFieldOp, separateCas, separateFieldOps };
+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";
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, TDbCas, TDbFieldOp, TFieldOps, getDbFieldOp, isDbFieldOp, reconcileCas, separateCas, separateFieldOps };

package/dist/ops.d.mts

@@ -1,2 +1,2 @@
-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";
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, TDbCas, TDbFieldOp, TFieldOps, getDbFieldOp, isDbFieldOp, separateCas, separateFieldOps };
+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";
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, TDbCas, TDbFieldOp, TFieldOps, getDbFieldOp, isDbFieldOp, reconcileCas, separateCas, separateFieldOps };

package/dist/ops.mjs

@@ -1,4 +1,4 @@
-import { n as DbError } from "./db-error-BHPXOKzc.mjs";
+import { r as DbError } from "./db-error-COrO58t5.mjs";
 //#region src/ops.ts
 /** Increment a numeric field by `value` (default 1). */
 function $inc(value = 1) {
@@ -143,6 +143,48 @@ function separateFieldOps(data) {
 *
 * Zero-allocation on the no-op (no `$cas`) path.
 */
+/**
+* Reconciles the two spellings of one write item's expected version, in
+* place (since 0.1.128): the SDK operator `$cas: { [versionColumn]: N }` and a
+* top-level `[versionColumn]: N` (the HTTP wire shape, where a body's version
+* column is a CAS predicate, not a SET). Shared by the moost-db controller
+* (`target: "cas"` — normalises to `$cas` for the table) and the db-client
+* (`target: "version"` — normalises to the wire shape).
+*
+* - neither present → no-op, returns `undefined`
+* - one present → normalised to `target`, returns the expected version
+* - both present and equal → normalised once
+* - both present and different → `DbError("INVALID_QUERY")` at path `$cas`:
+*   `Ambiguous version: "<col>" and "$cas.<col>" differ`
+* - `$cas` malformed → {@link separateCas}'s own error (checked first, so a
+*   malformed `$cas` is never reported as "ambiguous")
+* - `$cas: undefined` counts as absent (the key is dropped)
+* - `versionColumn === undefined` with a `$cas` → {@link separateCas}'s
+*   "table has no @db.column.version" error
+*
+* Only a finite number counts as a present version column value — anything
+* else is left untouched for the write validator to reject.
+*/
+function reconcileCas(data, versionColumn, target) {
+	if ("$cas" in data && data.$cas === void 0) delete data.$cas;
+	const versionValue = versionColumn === void 0 ? void 0 : data[versionColumn];
+	const hasVersion = typeof versionValue === "number" && Number.isFinite(versionValue);
+	const hasCas = "$cas" in data;
+	if (!hasCas && !hasVersion) return void 0;
+	let expected;
+	if (hasCas) {
+		expected = separateCas(data, versionColumn);
+		if (hasVersion && versionValue !== expected) throw new DbError("INVALID_QUERY", [{
+			path: "$cas",
+			message: `Ambiguous version: "${versionColumn}" and "$cas.${versionColumn}" differ`
+		}]);
+	} else expected = versionValue;
+	if (target === "cas") {
+		delete data[versionColumn];
+		data.$cas = { [versionColumn]: expected };
+	} else data[versionColumn] = expected;
+	return expected;
+}
 function separateCas(data, versionColumn) {
 	if (!("$cas" in data)) return void 0;
 	if (versionColumn === void 0) throw new DbError("INVALID_QUERY", [{
@@ -180,4 +222,4 @@ function separateCas(data, versionColumn) {
 	return foundValue;
 }
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, separateCas, separateFieldOps };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, reconcileCas, separateCas, separateFieldOps };

package/dist/plugin.cjs

@@ -405,7 +405,13 @@ const dbColumnAnnotations = {
 				description: "Starting value for the auto-increment sequence. Adapter-specific behavior; some adapters may ignore this."
 			},
 			validate(token, args, doc) {
-				return require_validation_utils.validateFieldBaseType(token, doc, "db.default.increment", "number");
+				const errors = require_validation_utils.validateFieldBaseType(token, doc, "db.default.increment", "number");
+				if (token.parentNode.countAnnotations("meta.id") === 0) errors.push({
+					message: `@db.default.increment on a field without @meta.id — auto-increment columns must be primary-key columns for schema sync to manage them`,
+					severity: 2,
+					range: token.range
+				});
+				return errors;
 			}
 		}),
 		uuid: new _atscript_core.AnnotationSpec({
@@ -506,7 +512,7 @@ const dbColumnAnnotations = {
 function columnCapability(capability, verb) {
 	const example = capability === "filterable" ? "  @db.column.filterable\n  email: string\n" : "  @db.column.sortable\n  createdAt: number.timestamp\n";
 	return new _atscript_core.AnnotationSpec({
-		description: `Marks a column as ${capability} in the readable controller's query/pages endpoints. Relevant only when the host \`@db.table\` interface opts into strict mode with \`@db.table.${capability} 'manual'\`; otherwise ${verb} is open on all columns (default-open, back-compat).
+		description: `Marks a column as ${capability} in the readable controller's query/pages endpoints. Relevant only when the host \`@db.table\` interface opts into strict mode with \`@db.table.${capability} 'manual'\`; otherwise ${verb} is open on every column the adapter can handle (default-open, back-compat) and the annotation is a no-op. Adapter capability always wins: \`@db.json\` / array columns stay non-sortable (and non-filterable on SQL adapters) even when annotated. \`/meta.fields\` advertises exactly what the gate accepts; index-backed columns additionally carry the advisory \`indexed\` flag.
 
 **Example:**
 \`\`\`atscript
@@ -598,7 +604,7 @@ const dbIndexAnnotations = { index: {
 //#region src/plugin/annotations/rel.ts
 const dbRelAnnotations = { rel: {
 	FK: new _atscript_core.AnnotationSpec({
-		description: "Declares a foreign key reference on this field. The field must use a chain reference type (e.g., `User.id`) whose target is a primary key (`@meta.id`) or unique (`@db.index.unique`) field.\n\n**Dual role:**\n- On a `@db.table` interface, `@db.rel.FK` additionally drives DB-relation semantics —   relation loading with `@db.rel.to` / `@db.rel.from`, junction pairing with `@db.rel.via`, etc.\n- On any other interface (value-help sources, WF forms, plain interfaces), `@db.rel.FK`   acts purely as the value-help indicator: the client-side picker resolver uses it to   decide which fields render a value-help picker. The target's `@db.http.path` (stamped   by its readable controller) supplies the picker URL.\n\n**Example:**\n```atscript\n@db.rel.FK\nauthorId: User.id\n\n// With alias (required when multiple FKs point to the same type)\n@db.rel.FK \"author\"\nauthorId: User.id\n```\n",
+		description: "Declares a foreign key reference on this field. The field must use a chain reference type (e.g., `User.id`) whose target is a primary key (`@meta.id`) or unique (`@db.index.unique`) field.\n\n**Dual role:**\n- On a `@db.table` interface, `@db.rel.FK` additionally drives DB-relation semantics —   relation loading with `@db.rel.to` / `@db.rel.from`, junction pairing with `@db.rel.via`, etc.\n- On any other interface (value-help sources, WF forms, plain interfaces), `@db.rel.FK`   acts purely as the value-help indicator: the client-side picker resolver uses it to   decide which fields render a value-help picker. The target's `@db.http.path` (stamped   by its readable controller) supplies the picker URL.\n- In `/meta` (and `/meta/form/:name`) the marker is inherited through reference chains:   a field declared as `code: Issue.code` where `Issue.code: Dict.code` carries `@db.rel.FK`   is served with `ref` pointing at the terminal field (`Dict.code`) and `db.rel.FK: true`,   so view fields get the dictionary picker. Runtime metadata is untouched.\n\n**Example:**\n```atscript\n@db.rel.FK\nauthorId: User.id\n\n// With alias (required when multiple FKs point to the same type)\n@db.rel.FK \"author\"\nauthorId: User.id\n```\n",
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		argument: {
@@ -1211,9 +1217,10 @@ function tableCapability(capability) {
 	const example = capability === "filterable" ? "  @db.column.filterable\n  email: string\n  // other fields not filterable via the controller\n" : "  @db.column.sortable\n  createdAt: number.timestamp\n  // other fields not sortable via the controller\n";
 	const verb = capability === "filterable" ? "filter" : "sort";
 	return new _atscript_core.AnnotationSpec({
-		description: `Controls ${verb}-gating on the readable controller's \`/query\` and \`/pages\` endpoints.\n\n- **\`'auto'\`** (default when the annotation is absent) — every column is ${capability}.\n- **\`'manual'\`** — only fields annotated \`@db.column.${capability}\` are ${capability};   all others are rejected with HTTP 400.
+		description: `Controls ${verb}-gating on the readable controller's \`/query\` and \`/pages\` endpoints.\n\n- **\`'auto'\`** (default when the annotation is absent) — every column the adapter can ${verb} is ${capability} (JSON / array columns are never sortable, and not filterable on SQL adapters).
+- **\`'manual'\`** — only fields annotated \`@db.column.${capability}\` are ${capability};   all others are rejected with HTTP 400.
 
-Writing the annotation explicitly as \`@db.table.${capability} 'auto'\` has the same runtime effect as omitting it; use it to document intent.
+\`/meta.fields[*].` + capability + "` advertises exactly what the gate accepts in either mode. The policy applies to " + (capability === "filterable" ? "filters only — `$groupBy`, `$having` keys and aggregate fields use the adapter's physical capability.\n\n" : "`$sort` only.\n\n") + `Writing the annotation explicitly as \`@db.table.${capability} 'auto'\` has the same runtime effect as omitting it; use it to document intent.
 
 **Example:**
 \`\`\`atscript