@atscript/db 0.1.161 → 0.1.162

package/dist/{column-diff-DpeUbhEI.cjs → column-diff-CZsMGQ_w.cjs}

@@ -1,9 +1,9 @@
-const require_db_error = require("./db-error-JcfJqqpk.cjs");
-const require_aggregate_fns = require("./aggregate-fns-DFtKAv7Q.cjs");
-const require_nested_writer = require("./nested-writer-Bl1SZS7x.cjs");
-const require_validator = require("./validator-B4YDLUkj.cjs");
-const require_search_fields = require("./search-fields-CT_UZ9fg.cjs");
-const require_object = require("./object-Djg28csK.cjs");
+const require_db_error = require("./db-error-DmF1_xrz.cjs");
+const require_aggregate_fns = require("./aggregate-fns-DupYzFD7.cjs");
+const require_nested_writer = require("./nested-writer-yCy6wGuN.cjs");
+const require_validator = require("./validator-DK9Ijpo7.cjs");
+const require_search_fields = require("./search-fields-Bi1n-pB1.cjs");
+const require_object = require("./object-GjsuPNqo.cjs");
 require("./agg.cjs");
 const require_aggregate_rules = require("./aggregate-rules-D_bsCpUI.cjs");
 const require_ops = require("./ops.cjs");
@@ -319,7 +319,8 @@ function resolveViewSource(sourceType, logicalPath, nestedObjects) {
 		return jsonRoot === logicalPath ? {
 			column,
 			designType,
-			optional
+			optional,
+			jsonColumn: true
 		} : {
 			column,
 			jsonPath: logicalPath.slice(jsonRoot.length + 1).split("."),
@@ -509,6 +510,12 @@ var TableMetadata = class {
 	* @since 0.1.156
 	*/
 	onUpdateNow = /* @__PURE__ */ new Set();
+	/**
+	* Top-level fields annotated with `@db.onUpdate.inc`: `0` on insert, `+1` in
+	* the same statement on every update and replace.
+	* @since 0.1.162
+	*/
+	onUpdateInc = /* @__PURE__ */ new Set();
 	/** Logical path → `@db.column` override (top-level keys only on document storage). */
 	columnMap = /* @__PURE__ */ new Map();
 	dimensions = [];
@@ -739,6 +746,13 @@ var TableMetadata = class {
 			adapter.onFieldScanned?.(entry.path, entry.type, entry.metadata);
 		}
 		for (const path of this.encryptedFields) if (require_object.findAncestorInSet(path, this.encryptedFields) !== void 0) this.encryptedFields.delete(path);
+		if (this.encryptedFields.size > 0) for (const entry of collected) {
+			if (entry.member || this.ignoredFields.has(entry.path)) continue;
+			const feature = require_search_fields.ENCRYPTED_SEARCH_FEATURES.find((key) => entry.metadata.has(key));
+			if (!feature) continue;
+			const encrypted = require_object.findAncestorInSet(entry.path, this.encryptedFields);
+			if (encrypted !== void 0) throw new Error(`@${feature} on "${entry.path}" — it is inside the @db.encrypted field "${encrypted}"; search over ciphertext is impossible`);
+		}
 		if (!this.nestedObjects) this._classifyFields();
 		const overrides = adapter.getMetadataOverrides?.(this);
 		if (overrides) this._applyOverrides(overrides);
@@ -834,6 +848,14 @@ var TableMetadata = class {
 		const resolvedDefault = resolveDefaultFromMetadata(metadata);
 		if (resolvedDefault) this.defaults.set(fieldName, resolvedDefault);
 		if (metadata.has("db.onUpdate.now")) this.onUpdateNow.add(fieldName);
+		if (metadata.has("db.onUpdate.inc")) {
+			if (fieldName.includes(".")) throw new Error(`@db.onUpdate.inc on "${fieldName}" must sit on a top-level field of the table`);
+			this.onUpdateInc.add(fieldName);
+			if (!this.defaults.has(fieldName)) this.defaults.set(fieldName, {
+				kind: "value",
+				value: "0"
+			});
+		}
 		if (metadata.has("db.ignore")) this.ignoredFields.add(fieldName);
 		if (isNavRelation(metadata)) {
 			this.navFields.add(fieldName);
@@ -997,14 +1019,7 @@ var TableMetadata = class {
 		const reject = (what, why) => {
 			throw new Error(`@db.encrypted on "${fieldName}" cannot coexist with ${what} — ${why}`);
 		};
-		if (metadata.has("meta.id")) reject("@meta.id", "the primary key must be addressable");
-		if (metadata.has("db.rel.FK")) reject("@db.rel.FK", "joins are impossible over ciphertext");
-		if (metadata.has("db.index.plain") || metadata.has("db.index.unique") || metadata.has("db.index.fulltext") || metadata.has("db.index.geo")) reject("@db.index.*", "indexes over ciphertext are meaningless");
-		if (metadata.has("db.search.vector") || metadata.has("db.search.filter")) reject("@db.search.*", "search over ciphertext is impossible");
-		if (metadata.has("db.mongo.search.text") || metadata.has("db.mongo.search.autocomplete")) reject("@db.mongo.search.*", "Atlas Search over ciphertext is impossible");
-		if (metadata.has("db.column.version")) reject("@db.column.version", "the OCC filter needs cleartext equality");
-		if (metadata.has("db.onUpdate.now")) reject("@db.onUpdate.now", "the update time is set after the encryption transform");
-		if (metadata.has("db.default.increment") || metadata.has("db.default.now")) reject("@db.default.increment / @db.default.now", "engine-side defaults bypass the encryption transform");
+		for (const [name, why] of require_search_fields.ENCRYPTED_INCOMPATIBLE) if (metadata.has(name)) reject(`@${name}`, why);
 		if (metadata.get("db.patch.strategy") === "merge") reject("@db.patch.strategy \"merge\"", "ciphertext is opaque — partial merges would silently drop omitted keys");
 	}
 	/**
@@ -4064,6 +4079,19 @@ function resolveDefaultFromMetadata(metadata) {
 		fn: "now"
 	};
 }
+const LOCK_WAITS = new Set([
+	"block",
+	"nowait",
+	"skipLocked"
+]);
+/** A plain row read — not grouped, aggregated or `$count`. */
+function isRowRead(controls) {
+	if (!controls) return true;
+	if (controls.$count) return false;
+	if (Array.isArray(controls.$groupBy) && controls.$groupBy.length > 0) return false;
+	const select = controls.$select;
+	return !(Array.isArray(select) && select.some((item) => (0, _uniqu_core.isAggregateExpr)(item) || (0, _uniqu_core.isAggregateOfExpr)(item)));
+}
 /**
 * `query` with `$groupBy` defaulted to `[]` — an aggregate without one is the
 * ungrouped query (one group), as `$groupBy: []` documents it.
@@ -4072,10 +4100,7 @@ function resolveDefaultFromMetadata(metadata) {
 function withGroupBy(query) {
 	const controls = query.controls ?? {};
 	if (Array.isArray(controls.$groupBy)) return query;
-	if (controls.$groupBy !== void 0 && controls.$groupBy !== null) throw new require_db_error.DbError("INVALID_QUERY", [{
-		path: "$groupBy",
-		message: "$groupBy must be an array of field names"
-	}]);
+	if (controls.$groupBy !== void 0 && controls.$groupBy !== null) throw require_db_error.invalidQuery("$groupBy", "$groupBy must be an array of field names");
 	return {
 		...query,
 		controls: {
@@ -4183,10 +4208,7 @@ var AtscriptDbReadable = class {
 	_ensureSearchable() {
 		if (this.adapter.isSearchable()) return;
 		const hasVectorIndex = this.adapter.getSearchIndexes().some((i) => i.type === "vector");
-		throw new require_db_error.DbError("INVALID_QUERY", [{
-			path: "$search",
-			message: `Table "${this.tableName}" has no text search index` + (hasVectorIndex ? " — a @db.search.vector index only answers vectorSearch()" : "")
-		}]);
+		throw require_db_error.invalidQuery("$search", `Table "${this.tableName}" has no text search index` + (hasVectorIndex ? " — a @db.search.vector index only answers vectorSearch()" : ""));
 	}
 	/** Engine-agnostic query-time guards (encrypted-field refs, $geoWithin shape). */
 	_guardQuery(query) {
@@ -4415,6 +4437,17 @@ var AtscriptDbReadable = class {
 		return this._meta.columnMap.get(field) ?? field;
 	}
 	/**
+	* Physical column names of the `@db.onUpdate.inc` fields (since 0.1.162):
+	* adapters add `col = col + 1` to every replace. Empty when there are none.
+	*
+	* @internal Adapter-facing surface; not part of the consumer API.
+	*/
+	get onUpdateIncPhysical() {
+		this._ensureBuilt();
+		return this._onUpdateIncPhysical ??= [...this._meta.onUpdateInc].map((field) => this._meta.columnMap.get(field) ?? field);
+	}
+	_onUpdateIncPhysical;
+	/**
 	* Logical paths of the `@db.column.version.exempt` fields, including objects
 	* whose direct children are all exempt. A patch that writes only these (and
 	* no `$cas`) does not bump the version column. Empty when the table has no
@@ -4663,10 +4696,7 @@ var AtscriptDbReadable = class {
 		const sort = controls?.$sort;
 		if (!sort || typeof sort !== "object") return void 0;
 		const keys = Object.keys(sort);
-		if (keys.length === 0 || controls.$count) return void 0;
-		if (Array.isArray(controls.$groupBy) && controls.$groupBy.length > 0) return void 0;
-		const select = controls.$select;
-		if (Array.isArray(select) && select.some((item) => (0, _uniqu_core.isAggregateExpr)(item) || (0, _uniqu_core.isAggregateOfExpr)(item))) return;
+		if (keys.length === 0 || !isRowRead(controls)) return void 0;
 		const pk = this._meta.primaryKeys;
 		if (pk.length === 0) return void 0;
 		const sorted = new Set(keys.map((key) => this._meta.physicalPath(key)));
@@ -4820,15 +4850,62 @@ var AtscriptDbReadable = class {
 		return this._type.validator(opts);
 	}
 	/**
+	* The row lock a `findOne` / `findMany` asked for (`opts.lock`, since
+	* 0.1.162), validated — `undefined` when none was asked for.
+	*
+	* @throws DbError `INVALID_QUERY` — bad `lock` / `wait` value, a view, a
+	*   grouped / aggregate / `$count` read, or no `withTransaction` scope of
+	*   this table's adapter; `LOCK_NOT_SUPPORTED` — the adapter cannot lock.
+	*/
+	_readLock(query, opts) {
+		const mode = opts?.lock;
+		const wait = opts?.wait;
+		if (mode === void 0) {
+			if (wait !== void 0) throw require_db_error.invalidQuery("wait", "`wait` requires `lock`");
+			return;
+		}
+		if (mode !== "update" && mode !== "share") throw require_db_error.invalidQuery("lock", `Unknown lock mode "${String(mode)}" — use 'update' or 'share'`);
+		if (wait !== void 0 && !LOCK_WAITS.has(wait)) throw require_db_error.invalidQuery("wait", `Unknown lock wait "${String(wait)}" — use 'block', 'nowait' or 'skipLocked'`);
+		if (this.isView) throw require_db_error.invalidQuery("lock", `Locking reads run on tables only — "${this.tableName}" is a view`);
+		if (!isRowRead(query.controls)) throw require_db_error.invalidQuery("lock", "A locking read cannot group, aggregate or $count rows");
+		if (!this.adapter.supportsReadLocks()) throw new require_db_error.DbError("LOCK_NOT_SUPPORTED", [{
+			path: "lock",
+			message: `The adapter behind "${this.tableName}" cannot lock rows on read — use $cas / withOptimisticRetry`
+		}]);
+		if (!this.adapter.inTransactionScope()) throw require_db_error.invalidQuery("lock", "A locking read requires a transaction — run it inside withTransaction() of this table's adapter");
+		return {
+			mode,
+			wait: wait ?? "block"
+		};
+	}
+	/**
 	* Finds a single record matching the query.
 	* The return type automatically excludes nav props unless they are
 	* explicitly requested via `$with`.
+	*
+	* `opts.lock` (since 0.1.162) makes it a locking read — see
+	* {@link TReadLockOptions}:
+	*
+	* ```typescript
+	* await adapter.withTransaction(async () => {
+	*   const order = await orders.findOne({ filter: { id }, controls: {} }, { lock: 'update' })
+	*   // … the row stays locked until the transaction ends
+	* })
+	* ```
 	*/
-	async findOne(query) {
+	async findOne(query, opts) {
 		this._ensureBuilt();
 		this._guardQuery(query);
+		const lock = this._readLock(query, opts);
+		return this._findOne(query, lock);
+	}
+	/** {@link findOne} of a guarded query with an already validated lock. */
+	async _findOne(query, lock) {
 		const read = this._translateRead(query);
-		const result = await this.adapter.findOne(read.translated);
+		const result = await this.adapter.findOne(lock ? {
+			...read.translated,
+			lock
+		} : read.translated);
 		if (!result) return null;
 		const [row] = await this._finishRead([result], read);
 		return row;
@@ -4837,12 +4914,20 @@ var AtscriptDbReadable = class {
 	* Finds all records matching the query.
 	* The return type automatically excludes nav props unless they are
 	* explicitly requested via `$with`.
+	*
+	* `opts.lock` (since 0.1.162) makes it a locking read — see
+	* {@link TReadLockOptions}. Sort by the primary key when locking several
+	* rows, so concurrent transactions take the locks in the same order.
 	*/
-	async findMany(query) {
+	async findMany(query, opts) {
 		this._ensureBuilt();
 		this._guardQuery(query);
+		const lock = this._readLock(query, opts);
 		const read = this._translateRead(query);
-		return await this._finishRead(await this.adapter.findMany(read.translated), read);
+		return await this._finishRead(await this.adapter.findMany(lock ? {
+			...read.translated,
+			lock
+		} : read.translated), read);
 	}
 	/**
 	* `findMany` for the generic `$with` loader. With `partitionBy` (logical
@@ -4912,10 +4997,7 @@ var AtscriptDbReadable = class {
 		const { buckets } = computed;
 		if ($select) {
 			const groupBySet = new Set($groupBy);
-			for (const item of $select) if (typeof item === "string" && !groupBySet.has(item)) throw new require_db_error.DbError("INVALID_QUERY", [{
-				path: "$select",
-				message: `Plain field "${item}" in $select must also appear in $groupBy`
-			}]);
+			for (const item of $select) if (typeof item === "string" && !groupBySet.has(item)) throw require_db_error.invalidQuery("$select", `Plain field "${item}" in $select must also appear in $groupBy`);
 		}
 		const { dimensions, measures } = this._meta;
 		if (isStrictTable(this._meta)) {
@@ -4927,24 +5009,15 @@ var AtscriptDbReadable = class {
 				if (bucketAliases.has(field)) continue;
 				const fd = descriptors.get(field);
 				const verdict = fd && groupSourceVerdict(fd, this._meta, this.adapter);
-				if (verdict ? !verdict.ok && verdict.code === "notDimension" : !dimSet.has(field)) throw new require_db_error.DbError("INVALID_QUERY", [{
-					path: "$groupBy",
-					message: `Field "${field}" is not a dimension`
-				}]);
+				if (verdict ? !verdict.ok && verdict.code === "notDimension" : !dimSet.has(field)) throw require_db_error.invalidQuery("$groupBy", `Field "${field}" is not a dimension`);
 			}
 			if ($select) for (const item of $select) {
 				if (!(0, _uniqu_core.isAggregateExpr)(item) || item.$field === "*" || measSet.has(item.$field)) continue;
 				if (item.$fn === "countDistinct" || require_aggregate_fns.isFirstLast(item)) {
 					if (dimSet.has(item.$field)) continue;
-					throw new require_db_error.DbError("INVALID_QUERY", [{
-						path: "$select",
-						message: `Aggregate field "${item.$field}" is not a dimension or measure`
-					}]);
+					throw require_db_error.invalidQuery("$select", `Aggregate field "${item.$field}" is not a dimension or measure`);
 				}
-				throw new require_db_error.DbError("INVALID_QUERY", [{
-					path: "$select",
-					message: `Aggregate field "${item.$field}" is not a measure`
-				}]);
+				throw require_db_error.invalidQuery("$select", `Aggregate field "${item.$field}" is not a measure`);
 			}
 		}
 		const { quantityRefByField } = this._meta;
@@ -4953,10 +5026,7 @@ var AtscriptDbReadable = class {
 			for (const item of $select) {
 				if (!(0, _uniqu_core.isAggregateExpr)(item) || item.$field === "*") continue;
 				const refField = quantityRefByField.get(item.$field);
-				if (refField && !groupBySet.has(refField)) throw new require_db_error.DbError("INVALID_QUERY", [{
-					path: "$select",
-					message: `Aggregate "${item.$fn}(${item.$field})" requires "${refField}" in $groupBy — quantity-ref-tagged fields must be grouped by their dimension`
-				}]);
+				if (refField && !groupBySet.has(refField)) throw require_db_error.invalidQuery("$select", `Aggregate "${item.$fn}(${item.$field})" requires "${refField}" in $groupBy — quantity-ref-tagged fields must be grouped by their dimension`);
 			}
 		}
 		const searchTerm = query.controls.$search;
@@ -5186,16 +5256,10 @@ var AtscriptDbReadable = class {
 		}]);
 		assertGeoPoint(point, "$center");
 		const controls = query?.controls ?? {};
-		if (controls.$sort) throw new require_db_error.DbError("INVALID_QUERY", [{
-			path: "$sort",
-			message: "geoSearch results are distance-ordered — $sort is not allowed on this path"
-		}]);
+		if (controls.$sort) throw require_db_error.invalidQuery("$sort", "geoSearch results are distance-ordered — $sort is not allowed on this path");
 		for (const key of ["$maxDistance", "$minDistance"]) {
 			const v = controls[key];
-			if (v !== void 0 && (typeof v !== "number" || !Number.isFinite(v) || v < 0)) throw new require_db_error.DbError("INVALID_QUERY", [{
-				path: key,
-				message: `${key} must be a non-negative number of meters`
-			}]);
+			if (v !== void 0 && (typeof v !== "number" || !Number.isFinite(v) || v < 0)) throw require_db_error.invalidQuery(key, `${key} must be a non-negative number of meters`);
 		}
 		this._guardQuery(query);
 		return this._translateRead(query);
@@ -5215,10 +5279,17 @@ var AtscriptDbReadable = class {
 	*
 	* // With relations — only requested nav props appear
 	* const user = await table.findById('123', { controls: { $with: [{ name: 'posts' }] } })
+	*
+	* // Locking read inside a transaction (since 0.1.162) — see TReadLockOptions
+	* const user = await table.findById('123', { lock: 'update' })
 	* ```
 	*/
 	async findById(id, query) {
-		return this.findOneByRow(id, { controls: query?.controls });
+		return this.findOneByRow(id, {
+			controls: query?.controls,
+			lock: query?.lock,
+			wait: query?.wait
+		});
 	}
 	/**
 	* Reads the ONE row an id addresses — resolved exactly like
@@ -5229,14 +5300,37 @@ var AtscriptDbReadable = class {
 	* must also match `opts.scope` (an out-of-scope row answers `null` like a
 	* missing one).
 	*
+	* `opts.lock` / `opts.wait` (since 0.1.162) lock the row found — see
+	* {@link TReadLockOptions}. The id is then resolved to its one row first
+	* (an unlocked read, exactly like {@link resolveRowFilter}) and that row is
+	* read with the lock: with `wait: 'skipLocked'` a row another transaction
+	* holds answers `null` — never a lower-precedence identification naming a
+	* different row.
+	*
 	* @since 0.1.143
 	*/
 	async findOneByRow(id, opts) {
 		this._ensureBuilt();
 		const controls = opts?.controls ?? {};
-		for (const candidate of this._idCandidates(id, opts)) {
+		const candidates = this._idCandidates(id, opts);
+		if (opts?.lock !== void 0 || opts?.wait !== void 0) {
+			const lock = this._readLock({
+				filter: {},
+				controls
+			}, opts);
+			const pinned = await this._pinIdCandidates(candidates, opts?.scope);
+			if (!pinned) return null;
+			const query = {
+				filter: this._andScope(pinned, opts?.scope),
+				controls
+			};
+			this._guardQuery(query);
+			return this._findOne(query, lock);
+		}
+		for (const candidate of candidates) {
+			const filter = this._andScope(candidate, opts?.scope);
 			const row = await this.findOne({
-				filter: this._andScope(candidate, opts?.scope),
+				filter,
 				controls
 			});
 			if (row) return row;
@@ -5440,7 +5534,7 @@ var AtscriptDbReadable = class {
 	* Public entry point for relation loading. Used by adapters for nested $with delegation.
 	*/
 	async loadRelations(rows, withRelations) {
-		const { loadRelationsImpl } = await Promise.resolve().then(() => require("./relation-loader-DeulLrAw.cjs")).then((n) => n.relation_loader_exports);
+		const { loadRelationsImpl } = await Promise.resolve().then(() => require("./relation-loader-DujL_Mh9.cjs")).then((n) => n.relation_loader_exports);
 		return loadRelationsImpl(rows, withRelations, this);
 	}
 	/**
@@ -5478,6 +5572,62 @@ var NativeIntegrity = class extends IntegrityStrategy {
 	}
 };
 //#endregion
+//#region src/schema/fk-diff.ts
+/** Canonical key for an FK: sorted local field names, comma-joined. */
+function fkKey(fields) {
+	return [...fields].toSorted().join(",");
+}
+/**
+* Physical local / target column names of a desired FK (`@db.column` renames
+* applied) — what DDL, constraint sync, the FK diff and the snapshot compare.
+*/
+function fkColumns(fk) {
+	return {
+		fields: fk.physicalFields ?? fk.fields,
+		targetFields: fk.physicalTargetFields ?? fk.targetFields
+	};
+}
+/**
+* Compares desired FK constraints against stored snapshot to detect
+* additions, removals, and property changes (target table, target fields,
+* onDelete, onUpdate).
+*/
+function computeForeignKeyDiff(desired, existingSnapshot) {
+	const added = [];
+	const removed = [];
+	const changed = [];
+	const existingByKey = /* @__PURE__ */ new Map();
+	for (const fk of existingSnapshot) existingByKey.set(fkKey(fk.fields), fk);
+	const desiredKeys = /* @__PURE__ */ new Set();
+	for (const fk of desired.values()) {
+		const key = fkKey(fkColumns(fk).fields);
+		desiredKeys.add(key);
+		const existing = existingByKey.get(key);
+		if (!existing) added.push(fk);
+		else if (fkPropertiesDiffer(fk, existing)) changed.push({
+			desired: fk,
+			existing
+		});
+	}
+	for (const [key, fk] of existingByKey) if (!desiredKeys.has(key)) removed.push(fk);
+	return {
+		added,
+		removed,
+		changed
+	};
+}
+/** Whether the FK diff contains any changes. */
+function hasForeignKeyChanges(diff) {
+	return diff.added.length > 0 || diff.removed.length > 0 || diff.changed.length > 0;
+}
+function fkPropertiesDiffer(desired, existing) {
+	if (desired.targetTable !== existing.targetTable) return true;
+	if (fkKey(fkColumns(desired).targetFields) !== fkKey(existing.targetFields)) return true;
+	if ((desired.onDelete ?? void 0) !== (existing.onDelete ?? void 0)) return true;
+	if ((desired.onUpdate ?? void 0) !== (existing.onUpdate ?? void 0)) return true;
+	return false;
+}
+//#endregion
 //#region src/shared/failure-collector.ts
 /**
 * Collects failures from a batch of independent operations so one failing
@@ -5493,8 +5643,10 @@ function createFailureCollector(what) {
 		attempt: async (label, op) => {
 			try {
 				await op();
+				return true;
 			} catch (error) {
 				failures.push(`${label}: ${error.message}`);
+				return false;
 			}
 		},
 		throwIfAny: () => {
@@ -5502,6 +5654,27 @@ function createFailureCollector(what) {
 		}
 	};
 }
+/**
+* Records the changes a sync pass makes — or, in a dry run, would make — so
+* planning and syncing share one code path. `apply(change, label, op)`
+* records `change` straight away in a dry run; otherwise it runs `op` first:
+* through `attempt` when given (a {@link createFailureCollector} collector —
+* a failure is collected and the change not recorded), else directly (a
+* failure throws).
+* @since 0.1.162
+*/
+function createChangeRecorder(dryRun, attempt) {
+	const changes = [];
+	return {
+		changes,
+		apply: async (change, label, op) => {
+			if (!dryRun) if (attempt) {
+				if (!await attempt(label, async () => op())) return;
+			} else await op();
+			changes.push(change);
+		}
+	};
+}
 //#endregion
 //#region src/base-adapter.ts
 const EMPTY_DEFAULT_FNS = /* @__PURE__ */ new Set();
@@ -5512,6 +5685,32 @@ const EMPTY_BUCKET_UNITS = /* @__PURE__ */ new Set();
 */
 const ALL_BUCKET_UNITS = new Set(_uniqu_core.BUCKET_UNITS);
 const NO_VIEW_CAPABILITIES = /* @__PURE__ */ new Set();
+/**
+* Every isolation level, weakest first — what an adapter that provides them
+* all returns from `isolationLevels()`. @since 0.1.162
+*/
+const ALL_ISOLATION_LEVELS = new Set([
+	"read committed",
+	"repeatable read",
+	"serializable"
+]);
+const NO_ISOLATION_LEVELS = /* @__PURE__ */ new Set();
+/** Strength of each isolation level (higher = stricter). */
+const ISOLATION_RANK = {
+	"read committed": 1,
+	"repeatable read": 2,
+	serializable: 3
+};
+/**
+* Validates `opts.isolation`: `undefined` when none is requested.
+* @throws DbError `INVALID_QUERY` for an unknown level.
+*/
+function requestedIsolation(opts) {
+	const level = opts?.isolation;
+	if (level === void 0) return void 0;
+	if (!ALL_ISOLATION_LEVELS.has(level)) throw require_db_error.invalidQuery("isolation", `Unknown isolation level "${String(level)}" — use 'read committed', 'repeatable read' or 'serializable'`);
+	return level;
+}
 /** Every view capability — what the bundled adapters return from `viewCapabilities()`. @since 0.1.147 */
 const ALL_VIEW_CAPABILITIES = new Set(["compute", "firstJoin"]);
 const txStorage = new node_async_hooks.AsyncLocalStorage();
@@ -5621,6 +5820,41 @@ var BaseDbAdapter = class {
 		if (expectedVersion !== void 0) throw new Error("keepVersion cannot combine with expectedVersion");
 	}
 	/**
+	* `@db.onUpdate.inc` columns (physical names, since 0.1.162) as a field-op
+	* increment by one, or `undefined` when the table declares none. A replace
+	* path renders it next to the replacement data (the core leaves these
+	* columns out of the payload); the patch paths get the `$inc` from the core.
+	*/
+	_onUpdateIncOps() {
+		const cols = this._table.onUpdateIncPhysical;
+		if (cols.length === 0) return void 0;
+		const inc = {};
+		for (const col of cols) inc[col] = 1;
+		return { inc };
+	}
+	/**
+	* Whether `updateMany` / `deleteMany` render a row bound
+	* ({@link TDbWriteLimit}) natively in one statement (since 0.1.162). When
+	* `false` (the default) the core emulates a bounded write: it reads the
+	* primary keys of the first `limit` matching rows in order, then writes the
+	* rows matching the filter AND those keys.
+	*/
+	supportsWriteLimit() {
+		return false;
+	}
+	/**
+	* Whether a native bounded write ({@link supportsWriteLimit}) picks and
+	* writes its rows atomically — a row a concurrent transaction deletes or
+	* moves out of the filter is passed over and the next match taken, so `0`
+	* affected rows always means nothing matched (MySQL's
+	* `UPDATE/DELETE … ORDER BY … LIMIT`). When `false` (the default) the core
+	* probes for a remaining match after a bounded write that affected no rows
+	* and retries it a few times (since 0.1.162).
+	*/
+	writeLimitIsAtomic() {
+		return false;
+	}
+	/**
 	* Logs a debug message if verbose mode is enabled.
 	* Adapters call this to log DB operations with zero overhead when disabled.
 	*/
@@ -5637,16 +5871,29 @@ var BaseDbAdapter = class {
 	* The generic layer handles nesting detection via `AsyncLocalStorage`.
 	* Adapters override `_beginTransaction`, `_commitTransaction`, and
 	* `_rollbackTransaction` to provide raw DB-specific transaction primitives.
-	*/
-	async withTransaction(fn) {
+	*
+	* `opts.isolation` (since 0.1.162) sets the isolation level of the
+	* transaction this call opens — "at least this level". An adapter whose
+	* {@link isolationLevels} lacks it throws `ISOLATION_NOT_SUPPORTED`. A
+	* nested call joins the open transaction; it may request a level only when
+	* that transaction was opened with the same or a stricter one, else it
+	* throws `INVALID_QUERY` (the level of a running transaction cannot change).
+	*/
+	async withTransaction(fn, opts) {
 		const owner = this._transactionOwner();
-		if (findTxContext(owner)) return fn();
+		const isolation = this._checkIsolation(opts);
+		const open = findTxContext(owner);
+		if (open) {
+			if (isolation) this._assertJoinIsolation(open.isolation, isolation);
+			return fn();
+		}
 		const ctx = {
 			owner,
 			state: void 0,
-			parent: txStorage.getStore()
+			parent: txStorage.getStore(),
+			isolation: this._inherentIsolation() ?? isolation
 		};
-		ctx.state = await this._beginTransaction();
+		ctx.state = await this._beginTransaction(isolation ? { isolation } : void 0);
 		return txStorage.run(ctx, async () => {
 			try {
 				const result = await fn();
@@ -5661,6 +5908,67 @@ var BaseDbAdapter = class {
 		});
 	}
 	/**
+	* The isolation levels {@link withTransaction} can open a transaction at
+	* (since 0.1.162). Default: none — a requested level throws
+	* `ISOLATION_NOT_SUPPORTED`. Override and apply the level in
+	* {@link _beginTransaction} (`opts.isolation`).
+	*/
+	isolationLevels() {
+		return NO_ISOLATION_LEVELS;
+	}
+	/**
+	* The level every transaction of this adapter runs at regardless of the
+	* request (since 0.1.162) — SQLite's `BEGIN IMMEDIATE` is always
+	* serializable. A nested `withTransaction` asking for any level then joins
+	* without error. Default `undefined` (the engine default / what was asked).
+	*/
+	_inherentIsolation() {}
+	/**
+	* Validates a `withTransaction` isolation request against
+	* {@link isolationLevels} — the requested level, or `undefined`.
+	* @throws DbError `INVALID_QUERY` (unknown level) / `ISOLATION_NOT_SUPPORTED`.
+	*/
+	_checkIsolation(opts) {
+		const level = requestedIsolation(opts);
+		if (level && !this.isolationLevels().has(level)) throw this._isolationNotSupported(`${this.constructor.name} cannot run a transaction at isolation level '${level}'`);
+		return level;
+	}
+	/** The `ISOLATION_NOT_SUPPORTED` error of a `withTransaction` isolation request. */
+	_isolationNotSupported(message) {
+		return new require_db_error.DbError("ISOLATION_NOT_SUPPORTED", [{
+			path: "isolation",
+			message
+		}]);
+	}
+	/**
+	* A nested `withTransaction` asked for `requested` while a transaction
+	* opened at `open` runs: fine when `open` is at least as strict.
+	* @throws DbError `INVALID_QUERY` otherwise.
+	*/
+	_assertJoinIsolation(open, requested) {
+		if (open && ISOLATION_RANK[open] >= ISOLATION_RANK[requested]) return;
+		throw require_db_error.invalidQuery("isolation", `A nested withTransaction cannot request isolation '${requested}': the open transaction runs at ${open ? `'${open}'` : "the engine default"} — set the level on the outermost call`);
+	}
+	/**
+	* Whether the readable layer may pass a row lock on `DbQuery.lock` to
+	* `findOne` / `findMany` (since 0.1.162). Default `false` — a locking read
+	* throws `LOCK_NOT_SUPPORTED`. An adapter whose transaction already
+	* serialises writers may return `true` and ignore the lock.
+	*/
+	supportsReadLocks() {
+		return false;
+	}
+	/**
+	* `true` inside a `withTransaction` scope of this adapter's owner — a real
+	* transaction or a pass-through one (adapters without transaction
+	* primitives, such as the in-memory one). Unlike {@link isInTransaction} a
+	* pass-through scope counts. Used to require a scope for locking reads.
+	* @since 0.1.162
+	*/
+	inTransactionScope() {
+		return findTxContext(this._transactionOwner()) !== void 0;
+	}
+	/**
 	* The object a transaction state is branded with (since 0.1.128). Every
 	* adapter instance that returns the same owner shares one transaction —
 	* override to return the driver / pool / client the adapter was constructed
@@ -5707,9 +6015,10 @@ var BaseDbAdapter = class {
 	}
 	/**
 	* Starts a raw transaction. Returns opaque state stored in the async context.
-	* Override in adapters that support transactions.
+	* Override in adapters that support transactions. `opts.isolation` (since
+	* 0.1.162) is set only to a level of {@link isolationLevels}.
 	*/
-	async _beginTransaction() {}
+	async _beginTransaction(_opts) {}
 	/** Commits the raw transaction. Override in adapters that support transactions. */
 	async _commitTransaction(_state) {}
 	/** Rolls back the raw transaction. Override in adapters that support transactions. */
@@ -6015,46 +6324,87 @@ var BaseDbAdapter = class {
 	*
 	* @example
 	* ```typescript
-	* async syncIndexes() {
-	*   await this.syncIndexesWithDiff({
+	* protected override _syncIndexes(dryRun: boolean) {
+	*   return this.syncIndexesWithDiff({
+	*     dryRun,
 	*     listExisting: async () => this.driver.all('PRAGMA index_list(...)'),
 	*     createIndex: async (index) => this.driver.exec('CREATE INDEX ...'),
 	*     dropIndex: async (name) => this.driver.exec('DROP INDEX ...'),
-	*     shouldSkipType: (type) => type === 'fulltext',
+	*     skipIndex: (index) => (index.type === 'fulltext' ? null : undefined),
 	*   })
 	* }
 	* ```
 	*/
 	async syncIndexesWithDiff(opts) {
 		const prefix = opts.prefix ?? "atscript__";
-		const managed = (await opts.listExisting()).filter((i) => i.name.startsWith(prefix));
+		const dryRun = opts.dryRun === true;
+		const managed = (await opts.listExisting()).filter((i) => i.name.startsWith(prefix) && !(opts.isUnmanaged?.(i.name) ?? false));
 		const existingNames = new Set(managed.map((i) => i.name));
 		const existingColumns = new Map(managed.filter((i) => i.columns).map((i) => [i.name, i.columns]));
 		const desiredNames = /* @__PURE__ */ new Set();
 		const { attempt, throwIfAny } = createFailureCollector("index sync");
+		const { changes, apply } = createChangeRecorder(dryRun, attempt);
 		for (const index of this._table.indexes.values()) {
-			if (opts.warnUnsupportedTypes?.types.includes(index.type)) {
-				this.logger.warn(`[${opts.warnUnsupportedTypes.adapter}] ${index.type} index "${index.name}" declared but not supported by this adapter — skipped`);
+			if (index.type === "fulltext" && !index.fields.some((f) => !f.integer)) continue;
+			const skipReason = opts.skipIndex?.(index);
+			if (skipReason !== void 0) {
+				if (skipReason !== null && !dryRun) this.logger.warn(skipReason);
 				continue;
 			}
-			if (opts.shouldSkipType?.(index.type)) continue;
-			if (index.type === "fulltext" && !index.fields.some((f) => !f.integer)) continue;
 			desiredNames.add(index.key);
 			if (!existingNames.has(index.key)) {
-				await attempt(`create index "${index.key}"`, () => opts.createIndex(index));
+				await apply({
+					name: index.key,
+					action: "add"
+				}, `create index "${index.key}"`, () => opts.createIndex(index));
 				continue;
 			}
 			if (index.type === "plain" || index.type === "unique") {
 				const liveColumns = existingColumns.get(index.key);
 				const desiredColumns = index.fields.map((f) => opts.renderDesiredColumn?.(index, f) ?? f.name);
-				if (liveColumns && (liveColumns.length !== desiredColumns.length || liveColumns.some((c, i) => c !== desiredColumns[i]))) await attempt(`rebuild index "${index.key}"`, async () => {
+				if (liveColumns && (liveColumns.length !== desiredColumns.length || liveColumns.some((c, i) => c !== desiredColumns[i]))) await apply({
+					name: index.key,
+					action: "rebuild"
+				}, `rebuild index "${index.key}"`, async () => {
 					await opts.dropIndex(index.key);
 					await opts.createIndex(index);
 				});
 			}
 		}
-		for (const name of existingNames) if (!desiredNames.has(name)) await attempt(`drop index "${name}"`, () => opts.dropIndex(name));
+		for (const name of existingNames) if (!desiredNames.has(name)) await apply({
+			name,
+			action: "drop"
+		}, `drop index "${name}"`, () => opts.dropIndex(name));
 		throwIfAny();
+		return changes;
+	}
+	/**
+	* Template method for foreign-key constraint synchronization: drops the
+	* live constraints the model does not declare and adds the declared ones
+	* the live table lacks — matched by their sorted local columns
+	* ({@link fkKey}). A failing statement throws. Returns the changes (made,
+	* or with `dryRun` only computed).
+	* @since 0.1.162
+	*/
+	async syncForeignKeysWithDiff(opts) {
+		const { changes, apply } = createChangeRecorder(opts.dryRun === true);
+		const existing = await opts.listExisting();
+		const desired = [...this._table.foreignKeys.values()];
+		const desiredKeys = new Set(desired.map((fk) => fkKey(fkColumns(fk).fields)));
+		for (const [name, columns] of existing) if (!desiredKeys.has(fkKey(columns))) await apply({
+			fields: columns,
+			action: "drop"
+		}, `drop foreign key "${name}"`, () => opts.dropConstraint(name));
+		const existingKeys = new Set([...existing.values()].map((columns) => fkKey(columns)));
+		for (const fk of desired) {
+			const { fields } = fkColumns(fk);
+			if (!existingKeys.has(fkKey(fields))) await apply({
+				fields,
+				targetTable: fk.targetTable,
+				action: "add"
+			}, `add foreign key (${fields.join(", ")})`, () => opts.addConstraint(fk));
+		}
+		return changes;
 	}
 	/**
 	* Returns available search indexes for this adapter.
@@ -6273,6 +6623,38 @@ var BaseDbAdapter = class {
 		return false;
 	}
 	/**
+	* Synchronizes indexes between the Atscript definitions and the database.
+	* Uses `this._table.indexes` for the full index definitions. Returns the
+	* changes it made (since 0.1.162) — schema sync reports them on the run
+	* entry; `void` reports none. Schema sync
+	* passes `opts` when safe mode skipped work the indexes depend on (see
+	* {@link TSyncIndexesOptions}); an adapter whose indexes do not depend on it
+	* ignores them. Default: {@link _syncIndexes} without `dryRun`.
+	*/
+	async syncIndexes(opts) {
+		return this._syncIndexes(false, opts);
+	}
+	/**
+	* The index changes {@link syncIndexes} would make now — no DDL. Schema
+	* sync's plan reports them (`entry.indexChanges`) and marks the entry
+	* `alter`; a run reports what `syncIndexes` returns.
+	* @since 0.1.162
+	*/
+	async planIndexes(opts) {
+		return this._syncIndexes(true, opts);
+	}
+	/**
+	* The one index pass behind {@link syncIndexes} (`dryRun: false`) and
+	* {@link planIndexes} (`dryRun: true` — compute the changes, no DDL).
+	* Adapters implement this (usually over {@link syncIndexesWithDiff}). An
+	* adapter that overrides `syncIndexes` instead plans no index work.
+	* @since 0.1.162
+	*/
+	async _syncIndexes(dryRun, _opts) {
+		if (dryRun) return [];
+		throw new Error(`${this.constructor.name} implements neither syncIndexes nor _syncIndexes`);
+	}
+	/**
 	* When true, the adapter can handle column type changes in-place
 	* (e.g. MySQL's ALTER TABLE MODIFY COLUMN) without requiring table recreation.
 	* The generic sync layer will delegate type changes to {@link syncColumns}
@@ -6817,7 +7199,7 @@ function assertNoVersionWrites(data, versionColumn) {
 * Whether a logical (pre-decomposition) patch writes ONLY version-exempt
 * fields (`@db.column.version.exempt`). `data` has nav fields, filter keys and
 * derived fields removed and `$cas` separated. Mirrors `flattenPatchPayload`
-* (keep the two side by side): PK keys and `@db.onUpdate.now` fields are
+* (keep the two side by side): PK keys and `@db.onUpdate.now` / `.inc` fields are
 * skipped; an exempt path (or one under an exempt ancestor) is covered
 * whatever its value (scalar, field op, array ops, object); a non-exempt
 * merge-strategy object recurses (only the supplied children are written);
@@ -6831,11 +7213,12 @@ function isVersionExemptPatch(data, table) {
 	const primaryKeys = meta.primaryKeys;
 	const flatMap = meta.flatMap;
 	const stamps = meta.onUpdateNow;
+	const counters = meta.onUpdateInc;
 	const walk = (obj, prefix) => {
 		let result = "none";
 		for (const [k, value] of Object.entries(obj)) {
 			const key = prefix ? `${prefix}.${k}` : k;
-			if (primaryKeys.includes(key) || stamps.has(key)) continue;
+			if (primaryKeys.includes(key) || stamps.has(key) || counters.has(key)) continue;
 			if (meta.isVersionExemptPath(key)) {
 				result = "exempt";
 				continue;
@@ -7062,15 +7445,47 @@ function concurrentChange() {
 }
 /** Hand-off for a version-exempt patch (since 0.1.150) — shared, never mutated. */
 const KEEP_VERSION = Object.freeze({ keepVersion: true });
-/** Upper bound of keys per `touchMany` UPDATE statement (parameter-count safety). */
-const TOUCH_MANY_CHUNK = 500;
-/** `touchMany` input rejection — always `INVALID_QUERY`, path names the key. */
-function invalidTouchKey(path, message) {
-	return new require_db_error.DbError("INVALID_QUERY", [{
-		path,
-		message
+/**
+* The trailing `TDbUpdateOptions` rest-arg of an adapter update: `[]` when
+* there is nothing to pass, so the common call shape stays unchanged.
+*/
+function updateOptsArg(keepVersion, limit) {
+	if (limit) return [keepVersion ? {
+		keepVersion,
+		limit
+	} : { limit }];
+	return keepVersion ? [KEEP_VERSION] : [];
+}
+/** Extra attempts of a bounded write that affected no rows while matches remain. */
+const BOUNDED_WRITE_RETRIES = 3;
+/**
+* A bounded write lost its picked rows to concurrent writers on every
+* attempt while rows still matched — retryable, like other row contention.
+*/
+function boundedWriteContention() {
+	return new require_db_error.DbError("SERIALIZATION_FAILURE", [{
+		path: "limit",
+		message: `Bounded write: concurrent writers took the picked rows on 4 attempts while rows still matched — retry`
 	}]);
 }
+const DELETE_RESULT = {
+	affected: (r) => r.deletedCount,
+	add: (a, b) => ({ deletedCount: a.deletedCount + b.deletedCount }),
+	none: () => ({ deletedCount: 0 })
+};
+const UPDATE_RESULT = {
+	affected: (r) => r.matchedCount,
+	add: (a, b) => ({
+		matchedCount: a.matchedCount + b.matchedCount,
+		modifiedCount: a.modifiedCount + b.modifiedCount
+	}),
+	none: () => ({
+		matchedCount: 0,
+		modifiedCount: 0
+	})
+};
+/** Upper bound of keys per `touchMany` UPDATE statement (parameter-count safety). */
+const TOUCH_MANY_CHUNK = 500;
 var AtscriptDbTable = class extends AtscriptDbReadable {
 	_cascadeResolver;
 	_fkLookupResolver;
@@ -7130,15 +7545,9 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	async _insertMany(payloads, opts) {
 		this._ensureBuilt();
 		const { _depth, _action, maxDepth: userMax, guard, check, onConflict, lockConflicts } = opts ?? {};
-		if (onConflict !== void 0 && onConflict !== "error" && onConflict !== "ignore") throw new require_db_error.DbError("INVALID_QUERY", [{
-			path: "onConflict",
-			message: `Unknown onConflict mode "${String(onConflict)}"`
-		}]);
+		if (onConflict !== void 0 && onConflict !== "error" && onConflict !== "ignore") throw require_db_error.invalidQuery("onConflict", `Unknown onConflict mode "${String(onConflict)}"`);
 		const ignore = onConflict === "ignore";
-		if (lockConflicts && !ignore) throw new require_db_error.DbError("INVALID_QUERY", [{
-			path: "lockConflicts",
-			message: "lockConflicts requires onConflict \"ignore\""
-		}]);
+		if (lockConflicts && !ignore) throw require_db_error.invalidQuery("lockConflicts", "lockConflicts requires onConflict \"ignore\"");
 		const ignoreOpts = ignore ? { inCallerTransaction: this.adapter.isInTransaction() } : void 0;
 		if (ignoreOpts?.inCallerTransaction && lockConflicts) ignoreOpts.lockConflicts = true;
 		const maxDepth = userMax ?? 3;
@@ -7229,8 +7638,9 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			const items = payloads.map((p, i) => {
 				const c = clone(p);
 				expectedVersions[i] = require_ops.separateCas(c, versionColumn);
-				this._stampOnUpdate(c, now, true);
-				return this._applyDefaults(c, now);
+				const d = this._applyDefaults(c, now);
+				this._stampOnUpdate(d, now, true);
+				return d;
 			});
 			const originals = canNest ? items.map((item) => ({ ...item })) : [];
 			const validator = this.getValidator("bulkReplace");
@@ -7364,8 +7774,8 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 					if (!matched[i] && _ownedBy?.strict?.[i]) throw concurrentChange();
 					continue;
 				}
-				const updateOpts = expectedVersion === void 0 && versionColumn !== void 0 && isVersionExemptPatch(data, this) ? [KEEP_VERSION] : [];
-				this._stampTopLevel(data, now);
+				const updateOpts = updateOptsArg(expectedVersion === void 0 && versionColumn !== void 0 && isVersionExemptPatch(data, this));
+				this._stampTopLevel(data, now, expectedVersion !== void 0);
 				let result;
 				if (this.adapter.supportsNativePatch()) {
 					const ops = require_ops.separateFieldOps(data);
@@ -7429,7 +7839,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	async touchMany(keys, opts) {
 		this._ensureBuilt();
 		const versionField = this._meta.versionField;
-		if (versionField === void 0) throw invalidTouchKey("", "touchMany requires @db.column.version");
+		if (versionField === void 0) throw require_db_error.invalidQuery("", "touchMany requires @db.column.version");
 		if (keys.length === 0) return {
 			matchedCount: 0,
 			modifiedCount: 0
@@ -7440,14 +7850,14 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		for (const [i, key] of keys.entries()) {
 			const pair = {};
 			for (const pk of pkFields) {
-				if (key[pk] === void 0) throw invalidTouchKey(`[${i}].${pk}`, `touchMany: each key must carry its "${pk}"`);
+				if (key[pk] === void 0) throw require_db_error.invalidQuery(`[${i}].${pk}`, `touchMany: each key must carry its "${pk}"`);
 				pair[pk] = key[pk];
 			}
 			const version = key[versionField];
-			if (typeof version !== "number" || !Number.isFinite(version)) throw invalidTouchKey(`[${i}].${versionField}`, `touchMany: each key must carry its expected "${versionField}" (number)`);
-			for (const [prop, value] of Object.entries(key)) if (value !== void 0 && prop !== versionField && !(prop in pair)) throw invalidTouchKey(`[${i}].${prop}`, `touchMany: a touch carries no payload — keys hold the primary key and "${versionField}" only, got "${prop}"`);
+			if (typeof version !== "number" || !Number.isFinite(version)) throw require_db_error.invalidQuery(`[${i}].${versionField}`, `touchMany: each key must carry its expected "${versionField}" (number)`);
+			for (const [prop, value] of Object.entries(key)) if (value !== void 0 && prop !== versionField && !(prop in pair)) throw require_db_error.invalidQuery(`[${i}].${prop}`, `touchMany: a touch carries no payload — keys hold the primary key and "${versionField}" only, got "${prop}"`);
 			const identity = JSON.stringify(pair);
-			if (seen.has(identity)) throw invalidTouchKey(`[${i}]`, `touchMany: duplicate key ${identity}`);
+			if (seen.has(identity)) throw require_db_error.invalidQuery(`[${i}]`, `touchMany: duplicate key ${identity}`);
 			seen.add(identity);
 			pair[versionField] = version;
 			pairs.push(pair);
@@ -7463,12 +7873,18 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			});
 			if (matched < keys.length) throw new require_db_error.CasMismatchError(matched, keys.length);
 		}
+		const stamps = {};
+		this._stampTopLevel(stamps, Date.now(), true);
+		const { update, ops } = require_object.isEmptyObject(stamps) ? {
+			update: stamps,
+			ops: void 0
+		} : this._translatePatch(stamps);
 		return this.adapter.withTransaction(async () => {
 			let matchedCount = 0;
 			let modifiedCount = 0;
 			for (let start = 0; start < translated.length; start += TOUCH_MANY_CHUNK) {
 				const chunk = translated.slice(start, start + TOUCH_MANY_CHUNK);
-				const result = await this.adapter.updateMany({ $or: chunk }, {}, void 0);
+				const result = await this.adapter.updateMany({ $or: chunk }, update, ops);
 				matchedCount += result.matchedCount;
 				modifiedCount += result.modifiedCount;
 			}
@@ -7519,66 +7935,227 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		};
 		return require_nested_writer.remapDeleteFkViolation(this.tableName, () => guard || needsCascade || candidates.length > 1 ? this.adapter.withTransaction(run) : run());
 	}
-	async updateMany(filter, data) {
+	/**
+	* Patches every row matching `filter` with `data` (own fields only — no
+	* relations, no `$cas`). Since 0.1.162 the payload is validated in `patch`
+	* mode, exactly like {@link updateOne}: a type mismatch, `null` on a
+	* non-nullable field, `@meta.required` or `@expect.*` failures throw a
+	* `ValidatorError` before any statement runs.
+	*
+	* `opts.limit` (since 0.1.162) bounds the write to the first `limit` matching
+	* rows in `opts.sort` order (default: primary key ascending; the primary key
+	* always breaks ties). Loop until `matchedCount === 0` to process every
+	* match in batches. Not exposed over HTTP.
+	*/
+	async updateMany(filter, data, opts) {
 		this._ensureBuilt();
 		this._guardMutationFilter(filter);
-		await this._integrity.validateForeignKeys([data], this._meta, this._fkLookupResolver, this._writeTableResolver, true);
+		const bound = this._writeBound(filter, opts);
 		const dataCopy = _cloneWritePayload(data);
-		this._meta.stripDerived(dataCopy);
+		if ("$cas" in dataCopy) throw require_db_error.invalidQuery("$cas", "$cas is not supported on updateMany — use bulkUpdate with per-row $cas for version-locked batch updates");
+		this._rejectNavWrite(dataCopy, "updateMany");
 		const now = Date.now();
 		this._stampOnUpdate(dataCopy, now, false);
+		require_nested_writer.validateBatch(this.getValidator("bulkUpdate"), [dataCopy], {
+			mode: "patch",
+			flatMap: this.flatMap,
+			navFields: this._meta.navFields
+		});
+		await this._integrity.validateForeignKeys([dataCopy], this._meta, this._fkLookupResolver, this._writeTableResolver, true);
+		this._meta.stripDerived(dataCopy);
 		const versionColumn = this.versionColumn;
-		if ("$cas" in dataCopy) throw new require_db_error.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 updateOpts = versionColumn !== void 0 && isVersionExemptPatch(dataCopy, this) ? [KEEP_VERSION] : [];
+		const keepVersion = versionColumn !== void 0 && isVersionExemptPatch(dataCopy, this);
 		this._stampTopLevel(dataCopy, now);
 		await this._encryptItems([dataCopy], "patch");
-		const update = decomposePatch(dataCopy, this);
-		const ops = require_ops.separateFieldOps(update);
-		const translatedOps = ops ? this._fieldMapper.translateOpsKeys(ops, this._meta) : void 0;
-		const translatedUpdate = this._fieldMapper.translatePatchKeys(update, this._meta);
-		const translatedFilter = this._fieldMapper.translateFilter(filter, this._meta);
-		if (translatedOps === void 0 && require_object.isEmptyObject(translatedUpdate)) return {
-			matchedCount: await this.adapter.count({
+		const { update, ops } = this._translatePatch(dataCopy);
+		const translatedFilter = bound?.query.filter ?? this._fieldMapper.translateFilter(filter, this._meta);
+		if (ops === void 0 && require_object.isEmptyObject(update)) {
+			const matchedCount = await this.adapter.count({
 				filter: translatedFilter,
 				controls: {}
-			}),
-			modifiedCount: 0
-		};
-		return require_nested_writer.enrichFkViolation(this._meta, () => this.adapter.updateMany(translatedFilter, translatedUpdate, translatedOps, ...updateOpts));
+			});
+			return {
+				matchedCount: bound ? Math.min(matchedCount, bound.writeLimit.limit) : matchedCount,
+				modifiedCount: 0
+			};
+		}
+		return require_nested_writer.enrichFkViolation(this._meta, () => {
+			if (!bound) return this.adapter.updateMany(translatedFilter, update, ops, ...updateOptsArg(keepVersion));
+			return this._runBounded(bound, UPDATE_RESULT, (f, limit) => this.adapter.updateMany(f, update, ops, ...updateOptsArg(keepVersion, limit)));
+		});
 	}
+	/**
+	* Replaces the own fields of every row matching `filter` with `data`. The
+	* payload is validated in `replace` mode (since 0.1.162) — every required
+	* field must be present — except the primary key, which the filter
+	* replaces as a row picker.
+	*/
 	async replaceMany(filter, data) {
 		this._ensureBuilt();
 		this._guardMutationFilter(filter);
-		await this._integrity.validateForeignKeys([data], this._meta, this._fkLookupResolver, this._writeTableResolver);
 		const dataCopy = _cloneWritePayload(data);
+		this._rejectNavWrite(dataCopy, "replaceMany");
 		this._stampOnUpdate(dataCopy, Date.now(), true);
+		require_nested_writer.validateBatch(this.getValidator("bulkReplace"), [dataCopy], {
+			mode: "replace",
+			navFields: this._meta.navFields,
+			keyless: true
+		});
+		await this._integrity.validateForeignKeys([dataCopy], this._meta, this._fkLookupResolver, this._writeTableResolver);
+		const versionColumn = this.versionColumn;
+		if (versionColumn !== void 0) assertNoVersionWrites(dataCopy, versionColumn);
 		await this._encryptItems([dataCopy], "write");
 		return require_nested_writer.enrichFkViolation(this._meta, () => this.adapter.replaceMany(this._fieldMapper.translateFilter(filter, this._meta), this._fieldMapper.prepareForWrite(dataCopy, this._meta, this.adapter)));
 	}
-	async deleteMany(filter) {
+	/**
+	* Deletes every row matching `filter` (application-level cascades run first
+	* where the adapter has no native foreign keys).
+	*
+	* `opts.limit` (since 0.1.162) bounds the delete to the first `limit`
+	* matching rows in `opts.sort` order (default: primary key ascending; the
+	* primary key always breaks ties) — for retention sweeps that keep each
+	* statement small. Loop until `deletedCount === 0`, not until it is below
+	* `limit`: a concurrent writer can make one round delete fewer rows while
+	* matches remain. Not exposed over HTTP.
+	*/
+	async deleteMany(filter, opts) {
 		this._ensureBuilt();
 		this._guardMutationFilter(filter);
+		const bound = this._writeBound(filter, opts);
+		const translate = (f) => this._fieldMapper.translateFilter(f, this._meta);
 		if (this._integrity.needsCascade(this._cascadeResolver, this.tableName)) return require_nested_writer.remapDeleteFkViolation(this.tableName, () => this.adapter.withTransaction(async () => {
-			const pin = await this._integrity.cascadeBeforeDelete(filter, this.tableName, this._meta, this._cascadeResolver, (f) => this._fieldMapper.translateFilter(f, this._meta), this.adapter);
-			if (pin) {
-				let deletedCount = 0;
-				for (const batch of pin) deletedCount += (await this.adapter.deleteMany(batch)).deletedCount;
-				return { deletedCount };
-			}
-			return this.adapter.deleteMany(this._fieldMapper.translateFilter(filter, this._meta));
+			if (!bound) return this._cascadeDelete(filter, translate);
+			return this._runBounded(bound, DELETE_RESULT, (f) => this._cascadeDelete(f, (pinned) => pinned), false);
 		}));
-		return require_nested_writer.remapDeleteFkViolation(this.tableName, () => this.adapter.deleteMany(this._fieldMapper.translateFilter(filter, this._meta)));
+		return require_nested_writer.remapDeleteFkViolation(this.tableName, () => bound ? this._runBounded(bound, DELETE_RESULT, (f, limit) => limit ? this.adapter.deleteMany(f, { limit }) : this.adapter.deleteMany(f)) : this.adapter.deleteMany(translate(filter)));
+	}
+	/**
+	* Runs a bounded write. `native` (default: `supportsWriteLimit()`) hands
+	* `write` the physical filter and the bound; otherwise the primary keys of
+	* the picked rows are read first and `write` gets `filter AND keys` per
+	* key batch (no bound) — a pick that finds nothing writes nothing.
+	*
+	* When the write affected no rows although a row still matches — a
+	* concurrent transaction deleted or changed the picked rows between the
+	* pick and the write — it runs again, at most
+	* {@link BOUNDED_WRITE_RETRIES} more times; an emulated write's next pick
+	* is that check. Rows still matching after the last attempt throw a
+	* retryable `SERIALIZATION_FAILURE`. So `0` means nothing matched (a loop
+	* until `0` cannot stop early); fewer than `limit` stays possible.
+	* A native write whose adapter reports `writeLimitIsAtomic()` is never
+	* re-checked.
+	*/
+	async _runBounded(bound, result, write, native = this.adapter.supportsWriteLimit()) {
+		const atomic = native && this.adapter.writeLimitIsAtomic();
+		const filter = bound.query.filter;
+		const pkColumns = this._meta.primaryKeys.map((field) => this._meta.physicalPath(field));
+		for (let attempt = 0;; attempt++) {
+			let out;
+			if (native) out = await write(filter, bound.writeLimit);
+			else {
+				const rows = await this.adapter.findMany(bound.query);
+				if (rows.length === 0) return result.none();
+				out = result.none();
+				for (const keys of pinByPrimaryKey(rows, pkColumns)) out = result.add(out, await write({ $and: [filter, keys] }));
+			}
+			if (atomic || result.affected(out) > 0) return out;
+			const last = attempt === BOUNDED_WRITE_RETRIES;
+			if (native || last) {
+				if (!await this._boundStillMatches(bound)) return out;
+				if (last) throw boundedWriteContention();
+			}
+		}
+	}
+	/** Whether any row still matches a bounded write's filter (a one-row key read). */
+	async _boundStillMatches(bound) {
+		const { $sort: _sort, $nulls: _nulls, ...controls } = bound.query.controls;
+		return (await this.adapter.findMany({
+			...bound.query,
+			controls: {
+				...controls,
+				$limit: 1
+			}
+		})).length > 0;
+	}
+	/**
+	* Application-level cascade, then the delete. `translate` maps `filter` to
+	* the adapter's physical filter (identity for an already-physical one).
+	*/
+	async _cascadeDelete(filter, translate) {
+		const pin = await this._integrity.cascadeBeforeDelete(filter, this.tableName, this._meta, this._cascadeResolver, translate, this.adapter);
+		if (pin) {
+			let deletedCount = 0;
+			for (const batch of pin) deletedCount += (await this.adapter.deleteMany(batch)).deletedCount;
+			return { deletedCount };
+		}
+		return this.adapter.deleteMany(translate(filter));
+	}
+	/**
+	* Validates `opts` of a bounded `updateMany` / `deleteMany` and returns the
+	* translated read of the rows it picks (filter, order with the primary-key
+	* tie-breaker, `limit`, primary-key projection), or `undefined` when the
+	* write is unbounded.
+	*/
+	_writeBound(filter, opts) {
+		if (opts?.limit === void 0) {
+			if (opts?.sort !== void 0) throw require_db_error.invalidQuery("sort", "sort applies to a bounded write only — set limit");
+			return;
+		}
+		const limit = opts.limit;
+		if (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 1) throw require_db_error.invalidQuery("limit", `limit must be a positive integer, got ${String(limit)}`);
+		const pk = this._meta.primaryKeys;
+		if (pk.length === 0) throw require_db_error.invalidQuery("limit", "a bounded write needs a primary key to order and pin its rows");
+		let sort;
+		if (opts.sort !== void 0 && Object.keys(opts.sort).length > 0) {
+			sort = {};
+			for (const [field, dir] of Object.entries(opts.sort)) {
+				if (dir !== 1 && dir !== -1) throw require_db_error.invalidQuery(`sort.${field}`, "sort direction must be 1 or -1");
+				sort[field] = dir;
+			}
+			guardPaths(this._meta, this.adapter, { controls: { $sort: sort } });
+		} else sort = Object.fromEntries(pk.map((field) => [field, 1]));
+		const query = this._fieldMapper.translateQuery(this._withStableSort({
+			filter,
+			controls: {
+				$sort: sort,
+				$limit: limit,
+				$select: [...pk]
+			}
+		}), this._meta);
+		const writeLimit = {
+			limit,
+			sort: query.controls.$sort
+		};
+		if (query.controls.$nulls) writeLimit.nulls = query.controls.$nulls;
+		return {
+			query,
+			writeLimit
+		};
+	}
+	/** `updateMany` / `replaceMany` write the table's own fields only. */
+	_rejectNavWrite(data, method) {
+		for (const navField of this._meta.navFields) if (data[navField] !== void 0) throw require_db_error.invalidQuery(navField, `${method} writes the table's own fields only — write relations through the keyed methods (updateOne / bulkUpdate / replaceOne / bulkReplace)`);
+	}
+	/**
+	* A logical patch → the adapter's physical `{ update, ops }`: nested
+	* merge-strategy objects decomposed into dot-paths (so nested field ops are
+	* caught), field ops separated, keys translated.
+	*/
+	_translatePatch(data) {
+		const decomposed = decomposePatch(data, this);
+		const ops = require_ops.separateFieldOps(decomposed);
+		return {
+			update: this._fieldMapper.translatePatchKeys(decomposed, this._meta),
+			ops: ops ? this._fieldMapper.translateOpsKeys(ops, this._meta) : void 0
+		};
 	}
 	/**
 	* Synchronizes indexes between Atscript definitions and the database.
 	*/
 	async syncIndexes() {
 		this._ensureBuilt();
-		return this.adapter.syncIndexes();
+		await this.adapter.syncIndexes();
 	}
 	/**
 	* Ensures the table/collection exists in the database.
@@ -7809,10 +8386,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				if (!(keys.length === fk.targetFields.length && fk.targetFields.every((f) => keys.includes(f) && target[f] != null))) continue;
 				fk.localFields.forEach((local, i) => {
 					const value = target[fk.targetFields[i]];
-					if (item[local] !== void 0 && item[local] !== null && !require_nested_writer.sameKey(item[local], value)) throw new require_db_error.DbError("INVALID_QUERY", [{
-						path: navField,
-						message: `"${navField}" and "${local}" name different parents`
-					}]);
+					if (item[local] !== void 0 && item[local] !== null && !require_nested_writer.sameKey(item[local], value)) throw require_db_error.invalidQuery(navField, `"${navField}" and "${local}" name different parents`);
 					item[local] = value;
 				});
 				delete item[navField];
@@ -7823,10 +8397,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	_rejectNestedToInIgnoreMode(items) {
 		for (const [navField, relation] of this._meta.relations) {
 			if (relation.direction !== "to") continue;
-			if (items.some((item) => item[navField] !== void 0 && item[navField] !== null)) throw new require_db_error.DbError("INVALID_QUERY", [{
-				path: navField,
-				message: "onConflict \"ignore\" cannot create a related parent record — insert it first or reference it by key"
-			}]);
+			if (items.some((item) => item[navField] !== void 0 && item[navField] !== null)) throw require_db_error.invalidQuery(navField, "onConflict \"ignore\" cannot create a related parent record — insert it first or reference it by key");
 		}
 	}
 	/**
@@ -7852,10 +8423,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			send.push(i);
 		}
 		const slots = send.length ? await this.adapter.insertManyIgnore(send.map((i) => prepared[i]), opts) : [];
-		if (slots.length !== send.length) throw new require_db_error.DbError("INVALID_QUERY", [{
-			path: "",
-			message: "Adapter insertManyIgnore must return one slot per input row"
-		}]);
+		if (slots.length !== send.length) throw require_db_error.invalidQuery("", "Adapter insertManyIgnore must return one slot per input row");
 		const insertedIds = [];
 		const inserted = [];
 		send.forEach((rowIndex, k) => {
@@ -7880,20 +8448,14 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	*/
 	_insertedPkFilters(items, prepared, insertedIds) {
 		const pkFields = this.primaryKeys;
-		if (pkFields.length === 0 && items.length > 0) throw new require_db_error.DbError("INVALID_QUERY", [{
-			path: "",
-			message: "Write check requires a primary key on the table"
-		}]);
+		if (pkFields.length === 0 && items.length > 0) throw require_db_error.invalidQuery("", "Write check requires a primary key on the table");
 		return items.map((item, i) => {
 			const key = {};
 			for (const field of pkFields) {
 				let value = item[field];
 				if (value === void 0) value = prepared[i]?.[this._meta.columnMap.get(field) ?? field];
 				if (value === void 0 && pkFields.length === 1) value = insertedIds[i];
-				if (value === void 0 || value === null) throw new require_db_error.DbError("INVALID_QUERY", [{
-					path: field,
-					message: `Write check: cannot resolve the primary key of inserted row [${i}]`
-				}]);
+				if (value === void 0 || value === null) throw require_db_error.invalidQuery(field, `Write check: cannot resolve the primary key of inserted row [${i}]`);
 				key[field] = value;
 			}
 			return this._pkFilterFrom(key);
@@ -7962,14 +8524,20 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* them once the patch is known to write something.
 	*/
 	_stampOnUpdate(data, now, topLevel) {
+		for (const field of this._meta.onUpdateInc) delete data[field];
 		for (const field of this._meta.onUpdateNow) if (!field.includes(".")) if (topLevel) data[field] = now;
 		else delete data[field];
 		else if (this._nestedDefaultFillable(field)) stampNested(data, field.split("."), 0, now);
 	}
-	/** Sets the top-level `@db.onUpdate.now` columns of a non-empty patch to `now`. */
-	_stampTopLevel(data, now) {
-		if (require_object.isEmptyObject(data)) return;
+	/**
+	* Sets the top-level `@db.onUpdate.now` columns of a non-empty patch to
+	* `now` and increments its `@db.onUpdate.inc` counters (`$inc: 1`).
+	* `force`: stamp an empty patch too (a touch writes the row).
+	*/
+	_stampTopLevel(data, now, force = false) {
+		if (!force && require_object.isEmptyObject(data)) return;
 		for (const field of this._meta.onUpdateNow) if (!field.includes(".")) data[field] = now;
+		for (const field of this._meta.onUpdateInc) data[field] = { $inc: 1 };
 	}
 	/** {@link _nestedDefaultFillable} per nested default path. */
 	_fillableDefaults;
@@ -8852,7 +9420,7 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 				continue;
 			}
 			if (source.flattened) fail(fieldName, "source is a flattened object — remove @db.json from the view field");
-			const mapping = this._leafMapping(fieldName, ownColumn ?? fieldName, sourceTable, source, joinNullable);
+			const mapping = this._leafMapping(fieldName, ownColumn ?? fieldName, sourceTable, source, joinNullable, fieldType.metadata.has("db.json"));
 			mappings.push(agg ? {
 				...mapping,
 				...agg
@@ -8890,7 +9458,7 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		for (const m of computed) visit(m, []);
 	}
 	/** One view column over one physical source (a column or a JSON leaf). */
-	_leafMapping(viewPath, viewColumn, sourceTable, source, joinNullable) {
+	_leafMapping(viewPath, viewColumn, sourceTable, source, joinNullable, viewJson = false) {
 		const mapping = {
 			viewColumn,
 			viewPath,
@@ -8904,7 +9472,10 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 				path: source.jsonPath,
 				type: source.designType
 			};
-		}
+		} else if (source.jsonColumn && !viewJson && require_search_fields.isJsonLeafType(source.designType)) mapping.json = {
+			path: [],
+			type: source.designType
+		};
 		return mapping;
 	}
 };
@@ -8921,62 +9492,6 @@ function isAtscriptDbView(readable) {
 	return readable.isView;
 }
 //#endregion
-//#region src/schema/fk-diff.ts
-/** Canonical key for an FK: sorted local field names, comma-joined. */
-function fkKey(fields) {
-	return [...fields].toSorted().join(",");
-}
-/**
-* Physical local / target column names of a desired FK (`@db.column` renames
-* applied) — what DDL, constraint sync, the FK diff and the snapshot compare.
-*/
-function fkColumns(fk) {
-	return {
-		fields: fk.physicalFields ?? fk.fields,
-		targetFields: fk.physicalTargetFields ?? fk.targetFields
-	};
-}
-/**
-* Compares desired FK constraints against stored snapshot to detect
-* additions, removals, and property changes (target table, target fields,
-* onDelete, onUpdate).
-*/
-function computeForeignKeyDiff(desired, existingSnapshot) {
-	const added = [];
-	const removed = [];
-	const changed = [];
-	const existingByKey = /* @__PURE__ */ new Map();
-	for (const fk of existingSnapshot) existingByKey.set(fkKey(fk.fields), fk);
-	const desiredKeys = /* @__PURE__ */ new Set();
-	for (const fk of desired.values()) {
-		const key = fkKey(fkColumns(fk).fields);
-		desiredKeys.add(key);
-		const existing = existingByKey.get(key);
-		if (!existing) added.push(fk);
-		else if (fkPropertiesDiffer(fk, existing)) changed.push({
-			desired: fk,
-			existing
-		});
-	}
-	for (const [key, fk] of existingByKey) if (!desiredKeys.has(key)) removed.push(fk);
-	return {
-		added,
-		removed,
-		changed
-	};
-}
-/** Whether the FK diff contains any changes. */
-function hasForeignKeyChanges(diff) {
-	return diff.added.length > 0 || diff.removed.length > 0 || diff.changed.length > 0;
-}
-function fkPropertiesDiffer(desired, existing) {
-	if (desired.targetTable !== existing.targetTable) return true;
-	if (fkKey(fkColumns(desired).targetFields) !== fkKey(existing.targetFields)) return true;
-	if ((desired.onDelete ?? void 0) !== (existing.onDelete ?? void 0)) return true;
-	if ((desired.onUpdate ?? void 0) !== (existing.onUpdate ?? void 0)) return true;
-	return false;
-}
-//#endregion
 //#region src/schema/schema-hash.ts
 /**
 * The physical sources a stored view snapshot reads: its entry table and the
@@ -9244,6 +9759,90 @@ function isColumnTypeChanged(existingType, expectedType) {
 	return existingType.toUpperCase() !== expectedType.toUpperCase();
 }
 /**
+* Whether a live column default (as the adapter's introspection normalized
+* it) and a model default (`serializeDefaultValue`) denote the same value for
+* `field` — compared in a canonical, type-aware form, because the DDL writes a
+* literal that differs from the annotation text and the engine reformats it
+* again: booleans as `1` / `0` (`true` / `1` → `1`), numbers numerically
+* (`1.0` = `1`, a DECIMAL's `0.00` = `0`), JSON-stored values as parsed,
+* key-sorted JSON (`{"a": 1}` = `{"a":1}`). With a column type `liveType`
+* of a fixed scale (`DECIMAL(10,2)`, `NUMERIC(8,3)`) — the type the column
+* has once synced, i.e. the model's — a model value is also the value the
+* column stores for it (`2.345` = `2.35`).
+* Function defaults (`fn:now`, `fn:uuid`, …) and every other value compare as
+* strings. Exported for adapters that must agree with schema sync.
+* @since 0.1.162
+*/
+function sameDefaultValue(field, live, desired, liveType) {
+	if (live === desired) return true;
+	if (live === void 0 || desired === void 0) return false;
+	if (live.startsWith("fn:") || desired.startsWith("fn:")) return false;
+	if (isJsonDefault(field)) {
+		const a = canonicalJson(live);
+		return a !== void 0 && a === canonicalJson(desired);
+	}
+	switch (field.designType) {
+		case "boolean": {
+			const a = canonicalBoolean(live);
+			return a !== void 0 && a === canonicalBoolean(desired);
+		}
+		case "number":
+		case "integer":
+		case "decimal": return sameNumber(live, desired, liveType);
+		default: return false;
+	}
+}
+function isJsonDefault(field) {
+	return field.storage === "json" || field.designType === "json" || field.designType === "array" || field.designType === "object";
+}
+function canonicalBoolean(value) {
+	const v = value.trim().toLowerCase();
+	if (v === "true" || v === "1") return "1";
+	if (v === "false" || v === "0") return "0";
+}
+/** Parsed JSON re-serialized with object keys sorted; `undefined` when not JSON. */
+function canonicalJson(value) {
+	try {
+		return require_object.stableJson(JSON.parse(value));
+	} catch {
+		return;
+	}
+}
+const DECIMAL_RE = /^([+-]?)(\d*)(?:\.(\d*))?$/;
+const SCALED_TYPE_RE = /^(?:DECIMAL|NUMERIC|DEC|FIXED)\s*\(\s*\d+\s*,\s*(\d+)\s*\)/i;
+/**
+* Numeric equality of two default literals — or, on a column of a fixed
+* scale (`liveType` `DECIMAL(p,s)` / `NUMERIC(p,s)`), of the live value and
+* the model value rounded half-up to that scale, as the engine stores it.
+*/
+function sameNumber(live, desired, liveType) {
+	const l = live.trim();
+	const d = desired.trim();
+	if (l === "" || d === "") return false;
+	const a = Number(l);
+	const b = Number(d);
+	if (!Number.isFinite(a) || !Number.isFinite(b)) return false;
+	if (a === b) return true;
+	const scale = liveType ? SCALED_TYPE_RE.exec(liveType.trim())?.[1] : void 0;
+	if (scale === void 0) return false;
+	const rounded = roundDecimal(d, Number(scale));
+	return rounded !== void 0 && Number(rounded) === a;
+}
+/** `value` (a plain decimal literal) rounded half-up to `scale` fraction digits, exactly. */
+function roundDecimal(value, scale) {
+	const m = DECIMAL_RE.exec(value);
+	if (!m) return;
+	const [, sign, int, frac = ""] = m;
+	if (frac.length <= scale) return value;
+	const digits = `${int || "0"}${frac.slice(0, scale)}`;
+	let n = BigInt(digits);
+	if (frac.charCodeAt(scale) >= 53) n += 1n;
+	const str = n.toString().padStart(scale + 1, "0");
+	const head = str.slice(0, str.length - scale);
+	const tail = str.slice(str.length - scale);
+	return `${sign}${head}${scale > 0 ? `.${tail}` : ""}`;
+}
+/**
 * Computes the difference between desired schema fields and existing database columns.
 *
 * @param desired - Field descriptors from the Atscript type (after flattening) —
@@ -9253,10 +9852,7 @@ function isColumnTypeChanged(existingType, expectedType) {
 *                     Receives the full field meta (design type, annotations, PK status, etc.)
 *                     so adapters can produce context-aware types (e.g., `VARCHAR(255)` from maxLength).
 *                     Required for type change detection.
-* @param opts.snapshot - The table's stored snapshot (since 0.1.141) — the baseline a
-*                        derived column's expression is compared with (the engine normalizes
-*                        the expression it stores, so the live column cannot be). Without
-*                        one, only a kind or type drift is seen.
+* @param opts - See {@link TColumnDiffOptions}.
 */
 function computeColumnDiff(desired, existing, typeMapper, opts) {
 	const existingByName = new Map(existing.map((c) => [c.name, c]));
@@ -9297,12 +9893,11 @@ function computeColumnDiff(desired, existing, typeMapper, opts) {
 				});
 				renamedOldNames.add(field.renamedFrom);
 			} else if (!checkDerived(field, existingCol, field.physicalName)) {
-				if (typeMapper) {
-					if (isColumnTypeChanged(existingCol.type, typeMapper(field))) typeChanged.push({
-						field,
-						existingType: existingCol.type
-					});
-				}
+				const mappedType = typeMapper?.(field);
+				if (mappedType !== void 0 && isColumnTypeChanged(existingCol.type, mappedType)) typeChanged.push({
+					field,
+					existingType: existingCol.type
+				});
 				if (!field.isPrimaryKey && !existingCol.pk) {
 					const desiredNotNull = !field.optional;
 					if (existingCol.notnull !== desiredNotNull) nullableChanged.push({
@@ -9310,12 +9905,13 @@ function computeColumnDiff(desired, existing, typeMapper, opts) {
 						wasNullable: !existingCol.notnull
 					});
 				}
+				const liveDefault = existingCol.dflt_value;
 				const desiredDefault = serializeDefaultValue(field.defaultValue);
 				const fn = field.defaultValue?.kind === "fn" ? field.defaultValue.fn : void 0;
 				const missingNative = fn !== void 0 && fn !== "increment" && opts?.nativeDefaultFns?.has(fn) === true;
-				if ((existingCol.dflt_value !== void 0 || missingNative) && existingCol.dflt_value !== desiredDefault) defaultChanged.push({
+				if ((liveDefault !== void 0 || missingNative) && liveDefault !== desiredDefault && !sameDefaultValue(field, liveDefault, desiredDefault, mappedType ?? existingCol.type) && !(liveDefault !== void 0 && desiredDefault !== void 0 && opts?.reportedDefault?.(desiredDefault, field) === liveDefault)) defaultChanged.push({
 					field,
-					oldDefault: existingCol.dflt_value,
+					oldDefault: liveDefault,
 					newDefault: desiredDefault
 				});
 			}
@@ -9362,6 +9958,12 @@ Object.defineProperty(exports, "ALL_BUCKET_UNITS", {
 		return ALL_BUCKET_UNITS;
 	}
 });
+Object.defineProperty(exports, "ALL_ISOLATION_LEVELS", {
+	enumerable: true,
+	get: function() {
+		return ALL_ISOLATION_LEVELS;
+	}
+});
 Object.defineProperty(exports, "ALL_VIEW_CAPABILITIES", {
 	enumerable: true,
 	get: function() {
@@ -9554,6 +10156,12 @@ Object.defineProperty(exports, "computeViewSnapshot", {
 		return computeViewSnapshot;
 	}
 });
+Object.defineProperty(exports, "createChangeRecorder", {
+	enumerable: true,
+	get: function() {
+		return createChangeRecorder;
+	}
+});
 Object.defineProperty(exports, "createFailureCollector", {
 	enumerable: true,
 	get: function() {
@@ -9728,6 +10336,12 @@ Object.defineProperty(exports, "resolveDesignType", {
 		return resolveDesignType;
 	}
 });
+Object.defineProperty(exports, "sameDefaultValue", {
+	enumerable: true,
+	get: function() {
+		return sameDefaultValue;
+	}
+});
 Object.defineProperty(exports, "searchIndexNotFoundMessage", {
 	enumerable: true,
 	get: function() {