@atscript/db 0.1.82 → 0.1.84

package/dist/{db-error-D8tQhNgM.cjs → db-error-CrtPzaZ-.cjs}

@@ -25,7 +25,31 @@ var DepthLimitExceededError = class extends DbError {
 		this.actual = actual;
 	}
 };
+/**
+* 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.
+*/
+var CasExhaustedError = class extends DbError {
+	name = "CasExhaustedError";
+	constructor(attempts, lastSeenVersion) {
+		const message = `Optimistic concurrency: exhausted ${attempts} attempts; row kept changing under us (last seen version: ${lastSeenVersion ?? "unknown"})`;
+		super("CAS_EXHAUSTED", [{
+			path: "$cas",
+			message
+		}], message);
+		this.attempts = attempts;
+		this.lastSeenVersion = lastSeenVersion;
+	}
+};
 //#endregion
+Object.defineProperty(exports, "CasExhaustedError", {
+	enumerable: true,
+	get: function() {
+		return CasExhaustedError;
+	}
+});
 Object.defineProperty(exports, "DbError", {
 	enumerable: true,
 	get: function() {

package/dist/{db-error-Cepx-RsQ.mjs → db-error-yx2jdg8B.mjs}

@@ -25,5 +25,23 @@ var DepthLimitExceededError = class extends DbError {
 		this.actual = actual;
 	}
 };
+/**
+* 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.
+*/
+var CasExhaustedError = class extends DbError {
+	name = "CasExhaustedError";
+	constructor(attempts, lastSeenVersion) {
+		const message = `Optimistic concurrency: exhausted ${attempts} attempts; row kept changing under us (last seen version: ${lastSeenVersion ?? "unknown"})`;
+		super("CAS_EXHAUSTED", [{
+			path: "$cas",
+			message
+		}], message);
+		this.attempts = attempts;
+		this.lastSeenVersion = lastSeenVersion;
+	}
+};
 //#endregion
-export { DepthLimitExceededError as n, DbError as t };
+export { DbError as n, DepthLimitExceededError as r, CasExhaustedError as t };

package/dist/{db-readable-B2TRNZHv.d.mts → db-readable-BUUVDkLf.d.mts}

@@ -1,4 +1,4 @@
-import { u as TFieldOps } from "./ops-C61kelof.mjs";
+import { f as TFieldOps } from "./ops-Blqr0ipy.mjs";
 import { FlatOf, FlatOf as FlatOf$1, NavPropsOf, NavPropsOf as NavPropsOf$1, OwnPropsOf, OwnPropsOf as OwnPropsOf$1, PrimaryKeyOf, PrimaryKeyOf as PrimaryKeyOf$1, TAtscriptAnnotatedType, TAtscriptDataType, TAtscriptTypeObject, TMetadataMap, TSerializedAnnotatedType, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
 import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, AggregateFn, AggregateQuery, AggregateQuery as AggregateQuery$1, AggregateResult, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
 
@@ -83,6 +83,8 @@ declare class TableMetadata {
   columnMap: Map<string, string>;
   dimensions: string[];
   measures: string[];
+  /** Logical field name annotated with `@db.column.version`, if any. */
+  versionField?: string;
   /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
   quantityRefByField: Map<string, string>;
   pathToPhysical: Map<string, string>;
@@ -236,6 +238,12 @@ interface TMetaResponse {
   type: TSerializedAnnotatedType;
   actions: TDbActionInfo[];
   crud: TCrudPermissions;
+  /**
+   * Physical column name annotated with `@db.column.version`, when the table
+   * opts into optimistic concurrency control (OCC). Absent for tables without
+   * the annotation, i.e. last-write-wins (default) behavior.
+   */
+  versionColumn?: string;
 }
 /** Where the action applies on the UI. */
 type TDbActionLevel = "table" | "row" | "rows";
@@ -804,7 +812,7 @@ declare abstract class BaseDbAdapter {
    * @param patch - The patch payload with array operations.
    * @returns Update result.
    */
-  nativePatch(_filter: FilterExpr, _patch: unknown, _ops?: TFieldOps): Promise<TDbUpdateResult>;
+  nativePatch(_filter: FilterExpr, _patch: unknown, _ops?: TFieldOps, _expectedVersion?: number): Promise<TDbUpdateResult>;
   /**
    * Called before field flattening begins.
    * Use to extract table-level adapter-specific annotations.
@@ -951,8 +959,8 @@ declare abstract class BaseDbAdapter {
   aggregate(_query: DbQuery): Promise<Array<Record<string, unknown>>>;
   abstract insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   abstract insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
-  abstract replaceOne(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
-  abstract updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
+  abstract replaceOne(filter: FilterExpr, data: Record<string, unknown>, expectedVersion?: number): Promise<TDbUpdateResult>;
+  abstract updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number): Promise<TDbUpdateResult>;
   abstract deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
   abstract findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
   abstract findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
@@ -1277,6 +1285,12 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * @internal Adapter-facing surface; not part of the consumer API.
    */
   get metaIdPhysical(): string | null;
+  /**
+   * Physical column name of the field annotated with `@db.column.version`, or
+   * `undefined` when the table has no version column. Used by adapters and the
+   * REST integration to drive optimistic concurrency control (OCC).
+   */
+  get versionColumn(): string | undefined;
   /** Dimension fields from `@db.column.dimension`. */
   get dimensions(): readonly string[];
   /** Measure fields from `@db.column.measure`. */

package/dist/{db-readable-BSrIy08e.d.cts → db-readable-DgIxrEVQ.d.cts}

@@ -1,4 +1,4 @@
-import { u as TFieldOps } from "./ops-DXJ4Zw0P.cjs";
+import { f as TFieldOps } from "./ops-lzmfzuY9.cjs";
 import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, AggregateFn, AggregateQuery, AggregateQuery as AggregateQuery$1, AggregateResult, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
 import { FlatOf, FlatOf as FlatOf$1, NavPropsOf, NavPropsOf as NavPropsOf$1, OwnPropsOf, OwnPropsOf as OwnPropsOf$1, PrimaryKeyOf, PrimaryKeyOf as PrimaryKeyOf$1, TAtscriptAnnotatedType, TAtscriptDataType, TAtscriptTypeObject, TMetadataMap, TSerializedAnnotatedType, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
 
@@ -83,6 +83,8 @@ declare class TableMetadata {
   columnMap: Map<string, string>;
   dimensions: string[];
   measures: string[];
+  /** Logical field name annotated with `@db.column.version`, if any. */
+  versionField?: string;
   /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
   quantityRefByField: Map<string, string>;
   pathToPhysical: Map<string, string>;
@@ -236,6 +238,12 @@ interface TMetaResponse {
   type: TSerializedAnnotatedType;
   actions: TDbActionInfo[];
   crud: TCrudPermissions;
+  /**
+   * Physical column name annotated with `@db.column.version`, when the table
+   * opts into optimistic concurrency control (OCC). Absent for tables without
+   * the annotation, i.e. last-write-wins (default) behavior.
+   */
+  versionColumn?: string;
 }
 /** Where the action applies on the UI. */
 type TDbActionLevel = "table" | "row" | "rows";
@@ -804,7 +812,7 @@ declare abstract class BaseDbAdapter {
    * @param patch - The patch payload with array operations.
    * @returns Update result.
    */
-  nativePatch(_filter: FilterExpr, _patch: unknown, _ops?: TFieldOps): Promise<TDbUpdateResult>;
+  nativePatch(_filter: FilterExpr, _patch: unknown, _ops?: TFieldOps, _expectedVersion?: number): Promise<TDbUpdateResult>;
   /**
    * Called before field flattening begins.
    * Use to extract table-level adapter-specific annotations.
@@ -951,8 +959,8 @@ declare abstract class BaseDbAdapter {
   aggregate(_query: DbQuery): Promise<Array<Record<string, unknown>>>;
   abstract insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   abstract insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
-  abstract replaceOne(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
-  abstract updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
+  abstract replaceOne(filter: FilterExpr, data: Record<string, unknown>, expectedVersion?: number): Promise<TDbUpdateResult>;
+  abstract updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number): Promise<TDbUpdateResult>;
   abstract deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
   abstract findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
   abstract findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
@@ -1277,6 +1285,12 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * @internal Adapter-facing surface; not part of the consumer API.
    */
   get metaIdPhysical(): string | null;
+  /**
+   * Physical column name of the field annotated with `@db.column.version`, or
+   * `undefined` when the table has no version column. Used by adapters and the
+   * REST integration to drive optimistic concurrency control (OCC).
+   */
+  get versionColumn(): string | undefined;
   /** Dimension fields from `@db.column.dimension`. */
   get dimensions(): readonly string[];
   /** Measure fields from `@db.column.measure`. */

package/dist/{db-space-Dx8x-Ke1.d.cts → db-space-CZooARt_.d.mts}

@@ -1,6 +1,6 @@
-import { B as TDbInsertResult, J as TFkLookupResolver, N as TDbDeleteResult, W as TDbUpdateResult, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger, t as AtscriptDbReadable, x as TCascadeResolver, z as TDbInsertManyResult } from "./db-readable-BSrIy08e.cjs";
-import { FilterExpr } from "@uniqu/core";
+import { B as TDbInsertResult, J as TFkLookupResolver, N as TDbDeleteResult, W as TDbUpdateResult, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger, t as AtscriptDbReadable, x as TCascadeResolver, z as TDbInsertManyResult } from "./db-readable-BUUVDkLf.mjs";
 import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
+import { FilterExpr } from "@uniqu/core";
 
 //#region src/strategies/integrity.d.ts
 /**

package/dist/{db-space-SUFqMvKz.d.mts → db-space-DiErv7Q1.d.cts}

@@ -1,6 +1,6 @@
-import { B as TDbInsertResult, J as TFkLookupResolver, N as TDbDeleteResult, W as TDbUpdateResult, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger, t as AtscriptDbReadable, x as TCascadeResolver, z as TDbInsertManyResult } from "./db-readable-B2TRNZHv.mjs";
-import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
+import { B as TDbInsertResult, J as TFkLookupResolver, N as TDbDeleteResult, W as TDbUpdateResult, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger, t as AtscriptDbReadable, x as TCascadeResolver, z as TDbInsertManyResult } from "./db-readable-DgIxrEVQ.cjs";
 import { FilterExpr } from "@uniqu/core";
+import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
 
 //#region src/strategies/integrity.d.ts
 /**

package/dist/{db-view-CqEIhTFa.mjs → db-view-Dfw-FP5o.mjs}

@@ -1,9 +1,9 @@
-import { t as DbError } from "./db-error-Cepx-RsQ.mjs";
+import { n as DbError } from "./db-error-yx2jdg8B.mjs";
 import { resolveAlias } from "./agg.mjs";
 import { n as findRemoteFK, t as findFKForRelation } from "./relation-helpers-CLasawQq.mjs";
-import { separateFieldOps } from "./ops.mjs";
-import { i as forceNavNonOptional, r as dbPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-BB5h1Le3.mjs";
-import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, i as batchPatchNestedFrom, l as batchReplaceNestedVia, m as remapDeleteFkViolation, n as batchInsertNestedTo, o as batchPatchNestedVia, p as enrichFkViolation, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-CT2rLURx.mjs";
+import { separateCas, separateFieldOps } from "./ops.mjs";
+import { i as forceNavNonOptional, r as dbPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-DTDf9yWe.mjs";
+import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, i as batchPatchNestedFrom, l as batchReplaceNestedVia, m as remapDeleteFkViolation, n as batchInsertNestedTo, o as batchPatchNestedVia, p as enrichFkViolation, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-CVMRAPoF.mjs";
 import { flattenAnnotatedType, isAnnotatedType } from "@atscript/typescript/utils";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/logger.ts
@@ -64,6 +64,8 @@ var TableMetadata = class {
 	columnMap = /* @__PURE__ */ new Map();
 	dimensions = [];
 	measures = [];
+	/** Logical field name annotated with `@db.column.version`, if any. */
+	versionField;
 	/** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
 	quantityRefByField = /* @__PURE__ */ new Map();
 	pathToPhysical = /* @__PURE__ */ new Map();
@@ -258,6 +260,14 @@ var TableMetadata = class {
 			if (!hasExplicitIndex) this._addIndexField("plain", fieldName, fieldName);
 		}
 		if (metadata.has("db.column.measure")) this.measures.push(fieldName);
+		if (metadata.has("db.column.version")) if (this.versionField !== void 0) logger.warn(`@db.column.version declared on multiple fields ("${this.versionField}" and "${fieldName}") — only one is allowed; using "${this.versionField}"`);
+		else {
+			this.versionField = fieldName;
+			if (!this.defaults.has(fieldName)) this.defaults.set(fieldName, {
+				kind: "value",
+				value: "0"
+			});
+		}
 	}
 	_addIndexField(type, name, field, opts) {
 		const key = indexKey(type, name);
@@ -1249,6 +1259,17 @@ var AtscriptDbReadable = class {
 		}
 		return this._metaIdPhysical;
 	}
+	/**
+	* Physical column name of the field annotated with `@db.column.version`, or
+	* `undefined` when the table has no version column. Used by adapters and the
+	* REST integration to drive optimistic concurrency control (OCC).
+	*/
+	get versionColumn() {
+		this._ensureBuilt();
+		const field = this._meta.versionField;
+		if (field === void 0) return void 0;
+		return this._meta.columnMap.get(field) ?? field;
+	}
 	/** Dimension fields from `@db.column.dimension`. */
 	get dimensions() {
 		this._ensureBuilt();
@@ -1940,7 +1961,7 @@ var BaseDbAdapter = class {
 	* @param patch - The patch payload with array operations.
 	* @returns Update result.
 	*/
-	async nativePatch(_filter, _patch, _ops) {
+	async nativePatch(_filter, _patch, _ops, _expectedVersion) {
 		throw new Error("Native patch not supported by this adapter");
 	}
 	/**
@@ -2473,6 +2494,37 @@ function decomposeArrayPatch(key, value, fieldType, update, _table) {
 	if (value.$remove !== void 0) update[`${key}.__$remove`] = value.$remove;
 	if (keyProps.size > 0 && (value.$upsert !== void 0 || value.$update !== void 0 || value.$remove !== void 0)) update[`${key}.__$keys`] = [...keyProps];
 }
+/**
+* Throws if the payload attempts to write the version column directly.
+*
+* The version column is server-managed: the adapter auto-increments it
+* on every update. Direct writes (plain SET, `$inc`, `$mul`) would
+* either silently no-op (overwritten by the auto-bump) or corrupt the
+* OCC invariant. Reject them at the patch layer so the failure is
+* loud and adapter-agnostic.
+*
+* Inspects the payload AFTER `separateCas` has stripped `$cas` (so
+* that the legitimate `$cas` → expectedVersion path is not flagged).
+*
+* The check is intentionally narrow: only the physical column name at
+* the top level of the (already-decomposed) payload. Nested objects
+* cannot reach the version column through dot-paths because the
+* decomposer flattens those into top-level dot-keys; the version
+* column, being a scalar at the root, cannot be nested.
+*
+* Zero-allocation when the version column is not present.
+*
+* @throws {DbError} with code `VERSION_COLUMN_WRITE` when the version
+*   column appears as a top-level key in `data` or as the target of a
+*   `$inc`/`$mul` field op.
+*/
+function assertNoVersionWrites(data, versionColumn) {
+	if (!(versionColumn in data)) return;
+	throw new DbError("VERSION_COLUMN_WRITE", [{
+		path: versionColumn,
+		message: `Cannot write to version column "${versionColumn}" directly; omit it from the payload or use $cas for conflict detection`
+	}]);
+}
 //#endregion
 //#region src/table/db-table.ts
 /**
@@ -2619,7 +2671,13 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
 		if (!canNest && this._meta.navFields.size > 0) checkDepthOverflow(payloads, maxDepth, this._meta);
 		return enrichFkViolation(this._meta, () => this.adapter.withTransaction(async () => {
-			const items = payloads.map((p) => this._applyDefaults({ ...p }));
+			const versionColumn = this.versionColumn;
+			const expectedVersions = Array.from({ length: payloads.length });
+			const items = payloads.map((p, i) => {
+				const clone = { ...p };
+				expectedVersions[i] = separateCas(clone, versionColumn);
+				return this._applyDefaults(clone);
+			});
 			const originals = canNest ? payloads.map((p) => ({ ...p })) : [];
 			const validator = this.getValidator("bulkReplace");
 			const ctx = {
@@ -2634,11 +2692,13 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			if (canNest) await preValidateNestedFrom(host, originals);
 			let matchedCount = 0;
 			let modifiedCount = 0;
-			for (const data of items) {
+			for (let i = 0; i < items.length; i++) {
+				const data = items[i];
 				for (const navField of this._meta.navFields) delete data[navField];
+				if (versionColumn !== void 0) assertNoVersionWrites(data, versionColumn);
 				const filter = this._extractRecordFilter(data);
 				const prepared = this._fieldMapper.prepareForWrite(data, this._meta, this.adapter);
-				const result = await this.adapter.replaceOne(this._fieldMapper.translateFilter(filter, this._meta), prepared);
+				const result = await this.adapter.replaceOne(this._fieldMapper.translateFilter(filter, this._meta), prepared, expectedVersions[i]);
 				matchedCount += result.matchedCount;
 				modifiedCount += result.modifiedCount;
 			}
@@ -2671,6 +2731,13 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
 		if (!canNest && this._meta.navFields.size > 0) checkDepthOverflow(payloads, maxDepth, this._meta);
 		return enrichFkViolation(this._meta, () => this.adapter.withTransaction(async () => {
+			const versionColumn = this.versionColumn;
+			const expectedVersions = Array.from({ length: payloads.length });
+			const cloned = payloads.map((p, i) => {
+				const c = { ...p };
+				expectedVersions[i] = separateCas(c, versionColumn);
+				return c;
+			});
 			const validator = this.getValidator("bulkUpdate");
 			const ctx = {
 				mode: "patch",
@@ -2678,18 +2745,21 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				navFields: this._meta.navFields
 			};
 			this._applyDepthCtx(ctx, depth);
-			validateBatch(validator, payloads, ctx);
-			const originals = canNest ? payloads.map((p) => ({ ...p })) : [];
+			validateBatch(validator, cloned, ctx);
+			const originals = canNest ? cloned.map((p) => ({ ...p })) : [];
 			const host = this;
-			if (canNest) await batchPatchNestedTo(host, payloads, maxDepth, depth);
-			await this._integrity.validateForeignKeys(payloads, this._meta, this._fkLookupResolver, this._writeTableResolver, true);
+			if (canNest) await batchPatchNestedTo(host, cloned, maxDepth, depth);
+			await this._integrity.validateForeignKeys(cloned, this._meta, this._fkLookupResolver, this._writeTableResolver, true);
 			let matchedCount = 0;
 			let modifiedCount = 0;
-			for (const payload of payloads) {
+			for (let i = 0; i < cloned.length; i++) {
+				const payload = cloned[i];
+				const expectedVersion = expectedVersions[i];
 				const data = { ...payload };
 				for (const navField of this._meta.navFields) delete data[navField];
 				const filter = this._extractRecordFilter(data);
 				for (const key of Object.keys(filter)) delete data[key];
+				if (versionColumn !== void 0) assertNoVersionWrites(data, versionColumn);
 				if (_isEmptyObj(data)) {
 					matchedCount += 1;
 					modifiedCount += 0;
@@ -2701,7 +2771,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 					const ops = separateFieldOps(data);
 					const translatedOps = ops ? _translateOpsKeys(ops, this._meta) : void 0;
 					const translatedData = this._fieldMapper.translatePatchKeys(data, this._meta);
-					result = await this.adapter.nativePatch(translatedFilter, translatedData, translatedOps);
+					result = await this.adapter.nativePatch(translatedFilter, translatedData, translatedOps, expectedVersion);
 				} else {
 					const update = decomposePatch(data, this);
 					const ops = separateFieldOps(update);
@@ -2712,8 +2782,8 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 							filter: translatedFilter,
 							controls: {}
 						}), this);
-						result = await this.adapter.updateOne(translatedFilter, resolved, translatedOps);
-					} else result = await this.adapter.updateOne(translatedFilter, translatedUpdate, translatedOps);
+						result = await this.adapter.updateOne(translatedFilter, resolved, translatedOps, expectedVersion);
+					} else result = await this.adapter.updateOne(translatedFilter, translatedUpdate, translatedOps, expectedVersion);
 				}
 				matchedCount += result.matchedCount;
 				modifiedCount += result.modifiedCount;
@@ -2746,7 +2816,14 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	async updateMany(filter, data) {
 		this._ensureBuilt();
 		await this._integrity.validateForeignKeys([data], this._meta, this._fkLookupResolver, this._writeTableResolver, true);
-		const update = decomposePatch({ ...data }, this);
+		const dataCopy = { ...data };
+		const versionColumn = this.versionColumn;
+		if ("$cas" in dataCopy) throw new DbError("INVALID_QUERY", [{
+			path: "$cas",
+			message: "$cas is not supported on updateMany — use bulkUpdate with per-row $cas for version-locked batch updates"
+		}]);
+		if (versionColumn !== void 0) assertNoVersionWrites(dataCopy, versionColumn);
+		const update = decomposePatch(dataCopy, this);
 		const ops = separateFieldOps(update);
 		const translatedOps = ops ? _translateOpsKeys(ops, this._meta) : void 0;
 		const translatedUpdate = this._fieldMapper.translatePatchKeys(update, this._meta);
@@ -2787,17 +2864,21 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	_applyDefaults(data) {
 		const nativeValues = this.adapter.supportsNativeValueDefaults();
 		const nativeFns = this.adapter.nativeDefaultFns();
-		for (const [field, def] of this._meta.defaults.entries()) if (data[field] === void 0) {
-			if (def.kind === "value" && !nativeValues) {
-				const fieldType = this._meta.flatMap?.get(field);
-				data[field] = (fieldType?.type.kind === "" && fieldType.type.designType) === "string" ? def.value : JSON.parse(def.value);
-			} else if (def.kind === "fn" && !nativeFns.has(def.fn)) switch (def.fn) {
-				case "now":
-					data[field] = Date.now();
-					break;
-				case "uuid":
-					data[field] = crypto.randomUUID();
-					break;
+		const versionField = this._meta.versionField;
+		for (const [field, def] of this._meta.defaults.entries()) {
+			if (field === versionField) continue;
+			if (data[field] === void 0) {
+				if (def.kind === "value" && !nativeValues) {
+					const fieldType = this._meta.flatMap?.get(field);
+					data[field] = (fieldType?.type.kind === "" && fieldType.type.designType) === "string" ? def.value : JSON.parse(def.value);
+				} else if (def.kind === "fn" && !nativeFns.has(def.fn)) switch (def.fn) {
+					case "now":
+						data[field] = Date.now();
+						break;
+					case "uuid":
+						data[field] = crypto.randomUUID();
+						break;
+				}
 			}
 		}
 		return data;
@@ -2922,6 +3003,22 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		const adapterPlugins = this.adapter.getValidatorPlugins();
 		if (purpose === "insert" || purpose === "patch" || purpose === "bulkReplace") {
 			const mode = purpose === "bulkReplace" ? "replace" : purpose;
+			const versionField = this._meta.versionField;
+			if (versionField !== void 0) {
+				const plugins = adapterPlugins.length ? [...adapterPlugins, dbPlugin] : [dbPlugin];
+				return this.createValidator({
+					plugins,
+					partial: mode === "patch",
+					replace: (def, path) => {
+						const transformed = forceNavNonOptional(def);
+						if (path === versionField && !transformed.optional) return {
+							...transformed,
+							optional: true
+						};
+						return transformed;
+					}
+				});
+			}
 			return buildDbValidator(this.type, mode, adapterPlugins);
 		}
 		if (purpose === "bulkUpdate") {
@@ -3078,4 +3175,4 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 	}
 };
 //#endregion
-export { BaseDbAdapter as a, AtscriptDbReadable as c, DocumentFieldMapper as d, FieldMappingStrategy as f, NoopLogger as h, ApplicationIntegrity as i, resolveDesignType as l, TableMetadata as m, AtscriptDbTable as n, IntegrityStrategy as o, UniquSelect as p, decomposePatch as r, NativeIntegrity as s, AtscriptDbView as t, RelationalFieldMapper as u };
+export { ApplicationIntegrity as a, NativeIntegrity as c, RelationalFieldMapper as d, DocumentFieldMapper as f, NoopLogger as g, TableMetadata as h, decomposePatch as i, AtscriptDbReadable as l, UniquSelect as m, AtscriptDbTable as n, BaseDbAdapter as o, FieldMappingStrategy as p, assertNoVersionWrites as r, IntegrityStrategy as s, AtscriptDbView as t, resolveDesignType as u };