@atscript/db 0.1.83 → 0.1.84

package/dist/index.mjs

@@ -1,8 +1,57 @@
-import { t as DbError } from "./db-error-Cepx-RsQ.mjs";
-import { a as BaseDbAdapter, c as AtscriptDbReadable, d as DocumentFieldMapper, f as FieldMappingStrategy, h as NoopLogger, i as ApplicationIntegrity, l as resolveDesignType, m as TableMetadata, n as AtscriptDbTable, o as IntegrityStrategy, p as UniquSelect, r as decomposePatch, s as NativeIntegrity, t as AtscriptDbView, u as RelationalFieldMapper } from "./db-view-CqEIhTFa.mjs";
-import { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, separateFieldOps } from "./ops.mjs";
-import { a as isNavRelation, i as forceNavNonOptional, n as buildValidationContext, o as createDbValidatorPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-BB5h1Le3.mjs";
+import { n as DbError, t as CasExhaustedError } from "./db-error-yx2jdg8B.mjs";
+import { a as ApplicationIntegrity, c as NativeIntegrity, d as RelationalFieldMapper, f as DocumentFieldMapper, g as NoopLogger, h as TableMetadata, i as decomposePatch, l as AtscriptDbReadable, m as UniquSelect, n as AtscriptDbTable, o as BaseDbAdapter, p as FieldMappingStrategy, r as assertNoVersionWrites, s as IntegrityStrategy, t as AtscriptDbView, u as resolveDesignType } from "./db-view-Dfw-FP5o.mjs";
+import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, separateCas, separateFieldOps } from "./ops.mjs";
+import { a as isNavRelation, i as forceNavNonOptional, n as buildValidationContext, o as createDbValidatorPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-DTDf9yWe.mjs";
 import { computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
+//#region src/with-optimistic-retry.ts
+/**
+* Runs a read-modify-write loop under optimistic concurrency control (OCC).
+*
+* Reads the row via `findOne({ filter })`, hands it to `mutator`, then applies
+* the returned patch with `$cas: { [versionColumn]: row[versionColumn] }`. On
+* a version conflict (`matchedCount === 0`) it re-reads the row, calls the
+* mutator with the fresh state, and retries — up to `maxAttempts` times.
+*
+* 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
+* inside a single object spread).
+*
+* @throws {DbError} with code `INVALID_QUERY` if `table` has no
+*   `@db.column.version` column — the helper would have no version to thread
+*   into `$cas` and would silently degrade to last-write-wins.
+* @throws {DbError} with code `NOT_FOUND` if the initial `findOne` returns
+*   `null`. The mutator is not invoked with a fabricated row.
+* @throws {CasExhaustedError} if `maxAttempts` is reached without a
+*   successful commit.
+*/
+async function withOptimisticRetry(table, filter, mutator, opts) {
+	const versionColumn = table.versionColumn;
+	if (versionColumn === void 0) throw new DbError("INVALID_QUERY", [{
+		path: "$cas",
+		message: `withOptimisticRetry: table "${table.tableName}" has no @db.column.version column — CAS cannot be applied`
+	}]);
+	const maxAttempts = opts?.maxAttempts ?? 5;
+	let lastSeenVersion;
+	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+		const row = await table.findOne({ filter });
+		if (row === null) throw new DbError("NOT_FOUND", [{
+			path: "$cas",
+			message: `withOptimisticRetry: row not found in "${table.tableName}" for filter ${JSON.stringify(filter)}`
+		}]);
+		lastSeenVersion = row[versionColumn];
+		const patch = await mutator(row);
+		const result = await table.updateOne({
+			...filter,
+			...patch,
+			$cas: { [versionColumn]: lastSeenVersion }
+		});
+		if (result.matchedCount > 0) return result;
+		if (attempt < maxAttempts && opts?.delay !== void 0) await opts.delay(attempt);
+	}
+	throw new CasExhaustedError(maxAttempts, lastSeenVersion);
+}
+//#endregion
 //#region src/table/db-space.ts
 /**
 * A database space — a registry of tables and views sharing the same adapter type and driver.
@@ -138,4 +187,4 @@ function translateQueryTree(node, resolveField) {
 	return { [leftField]: { [comp.op]: comp.right } };
 }
 //#endregion
-export { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, DbError, DbSpace, DocumentFieldMapper, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RelationalFieldMapper, TableMetadata, UniquSelect, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, isDbFieldOp, isNavRelation, isPrimitive, resolveDesignType, separateFieldOps, translateQueryTree, walkFilter };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, DbError, DbSpace, DocumentFieldMapper, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RelationalFieldMapper, TableMetadata, UniquSelect, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, isDbFieldOp, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };

package/dist/{nested-writer-CT2rLURx.mjs → nested-writer-CVMRAPoF.mjs}

@@ -1,4 +1,4 @@
-import { n as DepthLimitExceededError, t as DbError } from "./db-error-Cepx-RsQ.mjs";
+import { n as DbError, r as DepthLimitExceededError } from "./db-error-yx2jdg8B.mjs";
 import { r as resolveRelationTargetTable } from "./relation-helpers-CLasawQq.mjs";
 import { ValidatorError } from "@atscript/typescript/utils";
 //#region src/table/error-utils.ts

package/dist/{nested-writer-v_LPR1yJ.cjs → nested-writer-Chl_zySG.cjs}

@@ -1,4 +1,4 @@
-const require_db_error = require("./db-error-D8tQhNgM.cjs");
+const require_db_error = require("./db-error-CrtPzaZ-.cjs");
 const require_relation_helpers = require("./relation-helpers-BYvsE1tR.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 //#region src/table/error-utils.ts

package/dist/{ops-C61kelof.d.mts → ops-Blqr0ipy.d.mts}

@@ -5,12 +5,37 @@ interface TDbFieldOp {
   $dec?: number;
   $mul?: number;
 }
+/**
+ * A compare-and-set assertion: the update applies only if the version
+ * column currently equals `value`. Used inline in update payloads:
+ *
+ *   { ...patch, $cas: { version: 4 } }
+ *
+ * The map shape is forward-compatible with multi-field CAS; v1 has
+ * exactly one entry keyed by the table's version column name.
+ */
+interface TDbCas {
+  [versionColumn: string]: number;
+}
 /** Increment a numeric field by `value` (default 1). */
 declare function $inc(value?: number): TDbFieldOp;
 /** Decrement a numeric field by `value` (default 1). */
 declare function $dec(value?: number): TDbFieldOp;
 /** Multiply a numeric field by `value`. */
 declare function $mul(value: number): TDbFieldOp;
+/**
+ * Build a CAS marker for an inline payload.
+ *
+ * Use as a sibling to plain SET fields in an update payload:
+ *
+ *   await users.updateOne({ id, status: 'active', ...$cas('version', 4) })
+ *
+ * The wrapped object can be spread directly so the marker stays a
+ * single, type-safe top-level entry.
+ */
+declare function $cas(versionColumn: string, value: number): {
+  $cas: TDbCas;
+};
 /** Replace the entire array. */
 declare function $replace<T>(items: T[]): {
   $replace: T[];
@@ -63,5 +88,27 @@ declare function getDbFieldOp(value: unknown): {
  * avoid intermediate `{ op, value }` objects, and short-circuits on typeof.
  */
 declare function separateFieldOps(data: Record<string, unknown>): TFieldOps | undefined;
+/**
+ * Strips the top-level `$cas` operator from a write payload.
+ *
+ * Mutates `data` (deletes `$cas`) and returns the extracted expected
+ * version, or `undefined` if no `$cas` was present.
+ *
+ * The caller is expected to know the table's version column name and
+ * either trust the lookup or pass it explicitly for validation. v1
+ * accepts a single-entry `$cas` map; the returned number is the value
+ * of that entry.
+ *
+ * Errors (all thrown as {@link DbError}):
+ * - `$cas` is not a plain object → `"$cas operator: ..."`
+ * - `$cas` map is empty
+ * - `$cas` value is non-numeric / non-integer
+ * - `$cas` has more than one entry (v1 single-column constraint)
+ * - `$cas` key does not match `versionColumn` (when provided)
+ * - `$cas` is present on a non-versioned table (`versionColumn === undefined`)
+ *
+ * Zero-allocation on the no-op (no `$cas`) path.
+ */
+declare function separateCas(data: Record<string, unknown>, versionColumn?: string): number | undefined;
 //#endregion
-export { $remove as a, $upsert as c, getDbFieldOp as d, isDbFieldOp as f, $mul as i, TDbFieldOp as l, $inc as n, $replace as o, separateFieldOps as p, $insert as r, $update as s, $dec as t, TFieldOps as u };
+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 };

package/dist/{ops-DXJ4Zw0P.d.cts → ops-lzmfzuY9.d.cts}

@@ -5,12 +5,37 @@ interface TDbFieldOp {
   $dec?: number;
   $mul?: number;
 }
+/**
+ * A compare-and-set assertion: the update applies only if the version
+ * column currently equals `value`. Used inline in update payloads:
+ *
+ *   { ...patch, $cas: { version: 4 } }
+ *
+ * The map shape is forward-compatible with multi-field CAS; v1 has
+ * exactly one entry keyed by the table's version column name.
+ */
+interface TDbCas {
+  [versionColumn: string]: number;
+}
 /** Increment a numeric field by `value` (default 1). */
 declare function $inc(value?: number): TDbFieldOp;
 /** Decrement a numeric field by `value` (default 1). */
 declare function $dec(value?: number): TDbFieldOp;
 /** Multiply a numeric field by `value`. */
 declare function $mul(value: number): TDbFieldOp;
+/**
+ * Build a CAS marker for an inline payload.
+ *
+ * Use as a sibling to plain SET fields in an update payload:
+ *
+ *   await users.updateOne({ id, status: 'active', ...$cas('version', 4) })
+ *
+ * The wrapped object can be spread directly so the marker stays a
+ * single, type-safe top-level entry.
+ */
+declare function $cas(versionColumn: string, value: number): {
+  $cas: TDbCas;
+};
 /** Replace the entire array. */
 declare function $replace<T>(items: T[]): {
   $replace: T[];
@@ -63,5 +88,27 @@ declare function getDbFieldOp(value: unknown): {
  * avoid intermediate `{ op, value }` objects, and short-circuits on typeof.
  */
 declare function separateFieldOps(data: Record<string, unknown>): TFieldOps | undefined;
+/**
+ * Strips the top-level `$cas` operator from a write payload.
+ *
+ * Mutates `data` (deletes `$cas`) and returns the extracted expected
+ * version, or `undefined` if no `$cas` was present.
+ *
+ * The caller is expected to know the table's version column name and
+ * either trust the lookup or pass it explicitly for validation. v1
+ * accepts a single-entry `$cas` map; the returned number is the value
+ * of that entry.
+ *
+ * Errors (all thrown as {@link DbError}):
+ * - `$cas` is not a plain object → `"$cas operator: ..."`
+ * - `$cas` map is empty
+ * - `$cas` value is non-numeric / non-integer
+ * - `$cas` has more than one entry (v1 single-column constraint)
+ * - `$cas` key does not match `versionColumn` (when provided)
+ * - `$cas` is present on a non-versioned table (`versionColumn === undefined`)
+ *
+ * Zero-allocation on the no-op (no `$cas`) path.
+ */
+declare function separateCas(data: Record<string, unknown>, versionColumn?: string): number | undefined;
 //#endregion
-export { $remove as a, $upsert as c, getDbFieldOp as d, isDbFieldOp as f, $mul as i, TDbFieldOp as l, $inc as n, $replace as o, separateFieldOps as p, $insert as r, $update as s, $dec as t, TFieldOps as u };
+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 };

package/dist/ops.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_db_error = require("./db-error-CrtPzaZ-.cjs");
 //#region src/ops.ts
 /** Increment a numeric field by `value` (default 1). */
 function $inc(value = 1) {
@@ -12,6 +13,19 @@ function $dec(value = 1) {
 function $mul(value) {
 	return { $mul: value };
 }
+/**
+* Build a CAS marker for an inline payload.
+*
+* Use as a sibling to plain SET fields in an update payload:
+*
+*   await users.updateOne({ id, status: 'active', ...$cas('version', 4) })
+*
+* The wrapped object can be spread directly so the marker stays a
+* single, type-safe top-level entry.
+*/
+function $cas(versionColumn, value) {
+	return { $cas: { [versionColumn]: value } };
+}
 /** Replace the entire array. */
 function $replace(items) {
 	return { $replace: items };
@@ -109,7 +123,65 @@ function separateFieldOps(data) {
 	}
 	return ops;
 }
+/**
+* Strips the top-level `$cas` operator from a write payload.
+*
+* Mutates `data` (deletes `$cas`) and returns the extracted expected
+* version, or `undefined` if no `$cas` was present.
+*
+* The caller is expected to know the table's version column name and
+* either trust the lookup or pass it explicitly for validation. v1
+* accepts a single-entry `$cas` map; the returned number is the value
+* of that entry.
+*
+* Errors (all thrown as {@link DbError}):
+* - `$cas` is not a plain object → `"$cas operator: ..."`
+* - `$cas` map is empty
+* - `$cas` value is non-numeric / non-integer
+* - `$cas` has more than one entry (v1 single-column constraint)
+* - `$cas` key does not match `versionColumn` (when provided)
+* - `$cas` is present on a non-versioned table (`versionColumn === undefined`)
+*
+* Zero-allocation on the no-op (no `$cas`) path.
+*/
+function separateCas(data, versionColumn) {
+	if (!("$cas" in data)) return void 0;
+	if (versionColumn === void 0) throw new require_db_error.DbError("INVALID_QUERY", [{
+		path: "$cas",
+		message: "$cas operator: table has no @db.column.version; cannot use $cas"
+	}]);
+	const raw = data.$cas;
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new require_db_error.DbError("INVALID_QUERY", [{
+		path: "$cas",
+		message: "$cas operator: must be a plain object"
+	}]);
+	const map = raw;
+	let foundKey;
+	for (const k in map) {
+		if (foundKey !== void 0) throw new require_db_error.DbError("INVALID_QUERY", [{
+			path: "$cas",
+			message: "$cas operator: expected exactly one entry (v1 single-column CAS)"
+		}]);
+		foundKey = k;
+	}
+	if (foundKey === void 0) throw new require_db_error.DbError("INVALID_QUERY", [{
+		path: "$cas",
+		message: "$cas operator: must contain a single version entry"
+	}]);
+	if (versionColumn !== void 0 && foundKey !== versionColumn) throw new require_db_error.DbError("INVALID_QUERY", [{
+		path: `$cas.${foundKey}`,
+		message: `$cas operator: key "${foundKey}" does not match version column "${versionColumn}"`
+	}]);
+	const foundValue = map[foundKey];
+	if (typeof foundValue !== "number" || !Number.isInteger(foundValue)) throw new require_db_error.DbError("INVALID_QUERY", [{
+		path: `$cas.${foundKey}`,
+		message: `$cas operator: value for "${foundKey}" must be an integer`
+	}]);
+	delete data.$cas;
+	return foundValue;
+}
 //#endregion
+exports.$cas = $cas;
 exports.$dec = $dec;
 exports.$inc = $inc;
 exports.$insert = $insert;
@@ -120,4 +192,5 @@ exports.$update = $update;
 exports.$upsert = $upsert;
 exports.getDbFieldOp = getDbFieldOp;
 exports.isDbFieldOp = isDbFieldOp;
+exports.separateCas = separateCas;
 exports.separateFieldOps = separateFieldOps;

package/dist/ops.d.cts

@@ -1,2 +1,2 @@
-import { a as $remove, c as $upsert, d as getDbFieldOp, f as isDbFieldOp, i as $mul, l as TDbFieldOp, n as $inc, o as $replace, p as separateFieldOps, r as $insert, s as $update, t as $dec, u as TFieldOps } from "./ops-DXJ4Zw0P.cjs";
-export { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, TDbFieldOp, TFieldOps, getDbFieldOp, isDbFieldOp, separateFieldOps };
+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-lzmfzuY9.cjs";
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, TDbCas, TDbFieldOp, TFieldOps, getDbFieldOp, isDbFieldOp, separateCas, separateFieldOps };

package/dist/ops.d.mts

@@ -1,2 +1,2 @@
-import { a as $remove, c as $upsert, d as getDbFieldOp, f as isDbFieldOp, i as $mul, l as TDbFieldOp, n as $inc, o as $replace, p as separateFieldOps, r as $insert, s as $update, t as $dec, u as TFieldOps } from "./ops-C61kelof.mjs";
-export { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, TDbFieldOp, TFieldOps, getDbFieldOp, isDbFieldOp, separateFieldOps };
+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-Blqr0ipy.mjs";
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, TDbCas, TDbFieldOp, TFieldOps, getDbFieldOp, isDbFieldOp, separateCas, separateFieldOps };

package/dist/ops.mjs

@@ -1,3 +1,4 @@
+import { n as DbError } from "./db-error-yx2jdg8B.mjs";
 //#region src/ops.ts
 /** Increment a numeric field by `value` (default 1). */
 function $inc(value = 1) {
@@ -11,6 +12,19 @@ function $dec(value = 1) {
 function $mul(value) {
 	return { $mul: value };
 }
+/**
+* Build a CAS marker for an inline payload.
+*
+* Use as a sibling to plain SET fields in an update payload:
+*
+*   await users.updateOne({ id, status: 'active', ...$cas('version', 4) })
+*
+* The wrapped object can be spread directly so the marker stays a
+* single, type-safe top-level entry.
+*/
+function $cas(versionColumn, value) {
+	return { $cas: { [versionColumn]: value } };
+}
 /** Replace the entire array. */
 function $replace(items) {
 	return { $replace: items };
@@ -108,5 +122,62 @@ function separateFieldOps(data) {
 	}
 	return ops;
 }
+/**
+* Strips the top-level `$cas` operator from a write payload.
+*
+* Mutates `data` (deletes `$cas`) and returns the extracted expected
+* version, or `undefined` if no `$cas` was present.
+*
+* The caller is expected to know the table's version column name and
+* either trust the lookup or pass it explicitly for validation. v1
+* accepts a single-entry `$cas` map; the returned number is the value
+* of that entry.
+*
+* Errors (all thrown as {@link DbError}):
+* - `$cas` is not a plain object → `"$cas operator: ..."`
+* - `$cas` map is empty
+* - `$cas` value is non-numeric / non-integer
+* - `$cas` has more than one entry (v1 single-column constraint)
+* - `$cas` key does not match `versionColumn` (when provided)
+* - `$cas` is present on a non-versioned table (`versionColumn === undefined`)
+*
+* Zero-allocation on the no-op (no `$cas`) path.
+*/
+function separateCas(data, versionColumn) {
+	if (!("$cas" in data)) return void 0;
+	if (versionColumn === void 0) throw new DbError("INVALID_QUERY", [{
+		path: "$cas",
+		message: "$cas operator: table has no @db.column.version; cannot use $cas"
+	}]);
+	const raw = data.$cas;
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new DbError("INVALID_QUERY", [{
+		path: "$cas",
+		message: "$cas operator: must be a plain object"
+	}]);
+	const map = raw;
+	let foundKey;
+	for (const k in map) {
+		if (foundKey !== void 0) throw new DbError("INVALID_QUERY", [{
+			path: "$cas",
+			message: "$cas operator: expected exactly one entry (v1 single-column CAS)"
+		}]);
+		foundKey = k;
+	}
+	if (foundKey === void 0) throw new DbError("INVALID_QUERY", [{
+		path: "$cas",
+		message: "$cas operator: must contain a single version entry"
+	}]);
+	if (versionColumn !== void 0 && foundKey !== versionColumn) throw new DbError("INVALID_QUERY", [{
+		path: `$cas.${foundKey}`,
+		message: `$cas operator: key "${foundKey}" does not match version column "${versionColumn}"`
+	}]);
+	const foundValue = map[foundKey];
+	if (typeof foundValue !== "number" || !Number.isInteger(foundValue)) throw new DbError("INVALID_QUERY", [{
+		path: `$cas.${foundKey}`,
+		message: `$cas operator: value for "${foundKey}" must be an integer`
+	}]);
+	delete data.$cas;
+	return foundValue;
+}
 //#endregion
-export { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, separateFieldOps };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, separateCas, separateFieldOps };

package/dist/plugin.cjs

@@ -210,7 +210,30 @@ const dbColumnAnnotations = {
 			}
 		}),
 		filterable: columnCapability("filterable", "filtering"),
-		sortable: columnCapability("sortable", "sorting")
+		sortable: columnCapability("sortable", "sorting"),
+		version: new _atscript_core.AnnotationSpec({
+			description: "Marks a numeric column as the row's version for optimistic concurrency control (OCC). The adapter auto-increments this column on every UPDATE, and callers may pass `$cas: { <col>: N }` in a write payload to make the update conditional on the current version. Direct writes to the version column (as plain SET, `$inc`, or `$mul`) are rejected.\n\n**Constraints:**\n- At most one version column per table.\n- Must resolve to an integer type (`int`, `int32`, `int64`, etc.).\n- Default value on insert is `0`.\n\n**Example:**\n```atscript\n@db.column.version\nversion: int\n```\n",
+			nodeType: ["prop"],
+			validate(token, _args, doc) {
+				const errors = require_validation_utils.validateFieldBaseType(token, doc, "@db.column.version", "number");
+				if (token.parentNode.has("optional")) errors.push({
+					message: "@db.column.version requires a non-optional field — version columns are always populated (default 0)",
+					severity: 1,
+					range: token.range
+				});
+				const struct = require_validation_utils.getParentStruct(token);
+				if (struct) {
+					let count = 0;
+					for (const [, prop] of struct.props) if (prop.countAnnotations("db.column.version") > 0) count++;
+					if (count > 1) errors.push({
+						message: "At most one @db.column.version per table",
+						severity: 1,
+						range: token.range
+					});
+				}
+				return errors;
+			}
+		})
 	},
 	default: {
 		$self: new _atscript_core.AnnotationSpec({

package/dist/plugin.mjs

@@ -206,7 +206,30 @@ const dbColumnAnnotations = {
 			}
 		}),
 		filterable: columnCapability("filterable", "filtering"),
-		sortable: columnCapability("sortable", "sorting")
+		sortable: columnCapability("sortable", "sorting"),
+		version: new AnnotationSpec({
+			description: "Marks a numeric column as the row's version for optimistic concurrency control (OCC). The adapter auto-increments this column on every UPDATE, and callers may pass `$cas: { <col>: N }` in a write payload to make the update conditional on the current version. Direct writes to the version column (as plain SET, `$inc`, or `$mul`) are rejected.\n\n**Constraints:**\n- At most one version column per table.\n- Must resolve to an integer type (`int`, `int32`, `int64`, etc.).\n- Default value on insert is `0`.\n\n**Example:**\n```atscript\n@db.column.version\nversion: int\n```\n",
+			nodeType: ["prop"],
+			validate(token, _args, doc) {
+				const errors = validateFieldBaseType(token, doc, "@db.column.version", "number");
+				if (token.parentNode.has("optional")) errors.push({
+					message: "@db.column.version requires a non-optional field — version columns are always populated (default 0)",
+					severity: 1,
+					range: token.range
+				});
+				const struct = getParentStruct(token);
+				if (struct) {
+					let count = 0;
+					for (const [, prop] of struct.props) if (prop.countAnnotations("db.column.version") > 0) count++;
+					if (count > 1) errors.push({
+						message: "At most one @db.column.version per table",
+						severity: 1,
+						range: token.range
+					});
+				}
+				return errors;
+			}
+		})
 	},
 	default: {
 		$self: new AnnotationSpec({

package/dist/rel.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_relation_loader = require("./relation-loader-CRC5LcqM.cjs");
 const require_relation_helpers = require("./relation-helpers-BYvsE1tR.cjs");
-const require_nested_writer = require("./nested-writer-v_LPR1yJ.cjs");
+const require_nested_writer = require("./nested-writer-Chl_zySG.cjs");
 exports.batchInsertNestedFrom = require_nested_writer.batchInsertNestedFrom;
 exports.batchInsertNestedTo = require_nested_writer.batchInsertNestedTo;
 exports.batchInsertNestedVia = require_nested_writer.batchInsertNestedVia;

package/dist/rel.d.cts

@@ -1,4 +1,4 @@
-import { F as TDbForeignKey, H as TDbRelation, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger } from "./db-readable-BSrIy08e.cjs";
+import { F as TDbForeignKey, H as TDbRelation, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger } from "./db-readable-DgIxrEVQ.cjs";
 import { t as DbValidationContext } from "./db-validator-plugin-DRGMCEn3.cjs";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 import { Validator } from "@atscript/typescript/utils";

package/dist/rel.d.mts

@@ -1,4 +1,4 @@
-import { F as TDbForeignKey, H as TDbRelation, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger } from "./db-readable-B2TRNZHv.mjs";
+import { F as TDbForeignKey, H as TDbRelation, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger } from "./db-readable-BUUVDkLf.mjs";
 import { t as DbValidationContext } from "./db-validator-plugin-DDvYyv5t.mjs";
 import { Validator } from "@atscript/typescript/utils";
 import { FilterExpr, WithRelation } from "@uniqu/core";

package/dist/rel.mjs

@@ -1,4 +1,4 @@
 import { t as loadRelationsImpl } from "./relation-loader-BEOTXNcq.mjs";
 import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-CLasawQq.mjs";
-import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, i as batchPatchNestedFrom, l as batchReplaceNestedVia, n as batchInsertNestedTo, o as batchPatchNestedVia, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-CT2rLURx.mjs";
+import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, i as batchPatchNestedFrom, l as batchReplaceNestedVia, n as batchInsertNestedTo, o as batchPatchNestedVia, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-CVMRAPoF.mjs";
 export { batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, findFKForRelation, findRemoteFK, loadRelationsImpl, preValidateNestedFrom, resolveRelationTargetTable, validateBatch };

package/dist/sync.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_view = require("./db-view-Bf5P3_7k.cjs");
+const require_db_view = require("./db-view-da5OTSRH.cjs");
 //#region src/schema/schema-hash.ts
 /** Extracts sorted field snapshots from a readable's field descriptors. */
 function extractFieldSnapshots(fields, typeMapper) {

package/dist/sync.d.cts

@@ -1,5 +1,5 @@
-import { C as TColumnDiff, F as TDbForeignKey, G as TExistingColumn, K as TExistingTableOption, M as TDbDefaultValue, P as TDbFieldMeta, U as TDbStorageType, pt as TGenericLogger, rt as TTableOptionDiff, t as AtscriptDbReadable } from "./db-readable-BSrIy08e.cjs";
-import { r as AtscriptDbView, t as DbSpace } from "./db-space-Dx8x-Ke1.cjs";
+import { C as TColumnDiff, F as TDbForeignKey, G as TExistingColumn, K as TExistingTableOption, M as TDbDefaultValue, P as TDbFieldMeta, U as TDbStorageType, pt as TGenericLogger, rt as TTableOptionDiff, t as AtscriptDbReadable } from "./db-readable-DgIxrEVQ.cjs";
+import { r as AtscriptDbView, t as DbSpace } from "./db-space-DiErv7Q1.cjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts

package/dist/sync.d.mts

@@ -1,5 +1,5 @@
-import { C as TColumnDiff, F as TDbForeignKey, G as TExistingColumn, K as TExistingTableOption, M as TDbDefaultValue, P as TDbFieldMeta, U as TDbStorageType, pt as TGenericLogger, rt as TTableOptionDiff, t as AtscriptDbReadable } from "./db-readable-B2TRNZHv.mjs";
-import { r as AtscriptDbView, t as DbSpace } from "./db-space-SUFqMvKz.mjs";
+import { C as TColumnDiff, F as TDbForeignKey, G as TExistingColumn, K as TExistingTableOption, M as TDbDefaultValue, P as TDbFieldMeta, U as TDbStorageType, pt as TGenericLogger, rt as TTableOptionDiff, t as AtscriptDbReadable } from "./db-readable-BUUVDkLf.mjs";
+import { r as AtscriptDbView, t as DbSpace } from "./db-space-CZooARt_.mjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts

package/dist/sync.mjs

@@ -1,4 +1,4 @@
-import { h as NoopLogger } from "./db-view-CqEIhTFa.mjs";
+import { g as NoopLogger } from "./db-view-Dfw-FP5o.mjs";
 //#region src/schema/schema-hash.ts
 /** Extracts sorted field snapshots from a readable's field descriptors. */
 function extractFieldSnapshots(fields, typeMapper) {

package/dist/{validator-BB5h1Le3.mjs → validator-DTDf9yWe.mjs}

@@ -1,4 +1,4 @@
-import { n as DepthLimitExceededError } from "./db-error-Cepx-RsQ.mjs";
+import { r as DepthLimitExceededError } from "./db-error-yx2jdg8B.mjs";
 import { isDbFieldOp } from "./ops.mjs";
 import { flattenAnnotatedType } from "@atscript/typescript/utils";
 //#region src/patch/patch-types.ts

package/dist/{validator-BIuw_T0k.cjs → validator-DrmUaZA3.cjs}

@@ -1,4 +1,4 @@
-const require_db_error = require("./db-error-D8tQhNgM.cjs");
+const require_db_error = require("./db-error-CrtPzaZ-.cjs");
 const require_ops = require("./ops.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 //#region src/patch/patch-types.ts

package/dist/validator.cjs

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_ops = require("./ops.cjs");
-const require_validator = require("./validator-BIuw_T0k.cjs");
+const require_validator = require("./validator-DrmUaZA3.cjs");
+exports.$cas = require_ops.$cas;
 exports.$dec = require_ops.$dec;
 exports.$inc = require_ops.$inc;
 exports.$insert = require_ops.$insert;

package/dist/validator.d.cts

@@ -1,4 +1,4 @@
-import { a as $remove, c as $upsert, f as isDbFieldOp, i as $mul, l as TDbFieldOp, n as $inc, o as $replace, r as $insert, s as $update, t as $dec } from "./ops-DXJ4Zw0P.cjs";
+import { a as $mul, c as $update, d as TDbFieldOp, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-lzmfzuY9.cjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-DRGMCEn3.cjs";
 import { a as dbPlugin, c as TArrayPatch, i as buildValidationContext, l as TDbPatch, n as ValidatorMode, o as forceNavNonOptional, r as buildDbValidator, s as isNavRelation, t as ValidationContext, u as getKeyProps } from "./validator-_z_A3cKa.cjs";
-export { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, DbValidationContext, TArrayPatch, TDbFieldOp, TDbPatch, ValidationContext, ValidatorMode, buildDbValidator, buildValidationContext, createDbValidatorPlugin, dbPlugin, forceNavNonOptional, getKeyProps, isDbFieldOp, isNavRelation };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, DbValidationContext, TArrayPatch, TDbCas, TDbFieldOp, TDbPatch, ValidationContext, ValidatorMode, buildDbValidator, buildValidationContext, createDbValidatorPlugin, dbPlugin, forceNavNonOptional, getKeyProps, isDbFieldOp, isNavRelation };

package/dist/validator.d.mts

@@ -1,4 +1,4 @@
-import { a as $remove, c as $upsert, f as isDbFieldOp, i as $mul, l as TDbFieldOp, n as $inc, o as $replace, r as $insert, s as $update, t as $dec } from "./ops-C61kelof.mjs";
+import { a as $mul, c as $update, d as TDbFieldOp, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-Blqr0ipy.mjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-DDvYyv5t.mjs";
 import { a as dbPlugin, c as TArrayPatch, i as buildValidationContext, l as TDbPatch, n as ValidatorMode, o as forceNavNonOptional, r as buildDbValidator, s as isNavRelation, t as ValidationContext, u as getKeyProps } from "./validator-DttN2e5_.mjs";
-export { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, DbValidationContext, TArrayPatch, TDbFieldOp, TDbPatch, ValidationContext, ValidatorMode, buildDbValidator, buildValidationContext, createDbValidatorPlugin, dbPlugin, forceNavNonOptional, getKeyProps, isDbFieldOp, isNavRelation };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, DbValidationContext, TArrayPatch, TDbCas, TDbFieldOp, TDbPatch, ValidationContext, ValidatorMode, buildDbValidator, buildValidationContext, createDbValidatorPlugin, dbPlugin, forceNavNonOptional, getKeyProps, isDbFieldOp, isNavRelation };

package/dist/validator.mjs

@@ -1,3 +1,3 @@
-import { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, isDbFieldOp } from "./ops.mjs";
-import { a as isNavRelation, i as forceNavNonOptional, n as buildValidationContext, o as createDbValidatorPlugin, r as dbPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-BB5h1Le3.mjs";
-export { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, buildDbValidator, buildValidationContext, createDbValidatorPlugin, dbPlugin, forceNavNonOptional, getKeyProps, isDbFieldOp, isNavRelation };
+import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, isDbFieldOp } from "./ops.mjs";
+import { a as isNavRelation, i as forceNavNonOptional, n as buildValidationContext, o as createDbValidatorPlugin, r as dbPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-DTDf9yWe.mjs";
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, buildDbValidator, buildValidationContext, createDbValidatorPlugin, dbPlugin, forceNavNonOptional, getKeyProps, isDbFieldOp, isNavRelation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db",
-  "version": "0.1.83",
+  "version": "0.1.84",
   "description": "Database adapter utilities for atscript.",
   "keywords": [
     "atscript",