@atscript/db 0.1.161 → 0.1.163

package/dist/{column-diff-DR1glykD.mjs → column-diff-BfNIlMwX.mjs}

@@ -1,9 +1,9 @@
-import { a as aggregateExpressionsNotSupported, n as CasMismatchError, r as DbError, u as spaceClosedError } from "./db-error-eSsQX7rt.mjs";
-import { a as SOURCE_VALUE_FNS, c as isFirstLast, o as SUPPORTED_AGGREGATE_FNS, r as BASE_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-B_sgl4mB.mjs";
-import { A as hasRelationOp, D as containsRelationFilter, F as resolveRelationFilterTree, H as tableNameOf, I as compositeKey, J as viewExprNullable, K as isFieldRef, L as findFKEntryForRelation, M as noteRelationFilter, N as relGuardState, O as createRelationFilterHost, R as findFKForRelation, S as uniqueKeyTuple, U as computeOf, V as slicePerGroup, W as computedOperands, Y as walkViewExpr, _ as remapDeleteFkViolation, a as batchPatchNestedFrom, b as rowMatchesKey, c as batchReplaceNestedFrom, d as checkDepthOverflow, f as planNestedFromVia, g as enrichFkViolation, h as validateBatch, i as batchInsertNestedVia, l as batchReplaceNestedTo, m as preValidateNestedFrom, n as batchInsertNestedFrom, p as planPatchNestedTo, r as batchInsertNestedTo, s as batchPatchNestedVia, t as applyPatchNestedTo, u as batchReplaceNestedVia, v as findRowsByKeys, x as sameKey, y as pkTupleKey, z as findRemoteFK } from "./nested-writer-BOj_c_lI.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, d as soleUnionMember, f as unionValueMembers, i as dbPlugin, l as columnUnionBase, n as buildPatchPartial, t as buildDbValidator, u as pathPresence } from "./validator-B3fPJjS1.mjs";
-import { a as DERIVED_INCOMPATIBLE, n as searchMemberKind, r as numericTypeProblem, s as isJsonLeafType } from "./search-fields-CE8cmj9X.mjs";
-import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, t as deletePath } from "./object-TkiJQ-Dp.mjs";
+import { a as aggregateExpressionsNotSupported, c as invalidQuery, d as spaceClosedError, n as CasMismatchError, r as DbError } from "./db-error-hraC12B9.mjs";
+import { a as SOURCE_VALUE_FNS, c as isFirstLast, o as SUPPORTED_AGGREGATE_FNS, r as BASE_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-DsS9UQVB.mjs";
+import { A as hasRelationOp, D as containsRelationFilter, F as resolveRelationFilterTree, H as tableNameOf, I as compositeKey, J as viewExprNullable, K as isFieldRef, L as findFKEntryForRelation, M as noteRelationFilter, N as relGuardState, O as createRelationFilterHost, R as findFKForRelation, S as uniqueKeyTuple, U as computeOf, V as slicePerGroup, W as computedOperands, Y as walkViewExpr, _ as remapDeleteFkViolation, a as batchPatchNestedFrom, b as rowMatchesKey, c as batchReplaceNestedFrom, d as checkDepthOverflow, f as planNestedFromVia, g as enrichFkViolation, h as validateBatch, i as batchInsertNestedVia, l as batchReplaceNestedTo, m as preValidateNestedFrom, n as batchInsertNestedFrom, p as planPatchNestedTo, r as batchInsertNestedTo, s as batchPatchNestedVia, t as applyPatchNestedTo, u as batchReplaceNestedVia, v as findRowsByKeys, x as sameKey, y as pkTupleKey, z as findRemoteFK } from "./nested-writer-ClUX0DB0.mjs";
+import { a as forceNavNonOptional, c as getKeyProps, d as soleUnionMember, f as unionValueMembers, i as dbPlugin, l as columnUnionBase, n as buildPatchPartial, t as buildDbValidator, u as pathPresence } from "./validator-DuDWsIdQ.mjs";
+import { a as searchMemberKind, c as DERIVED_INCOMPATIBLE, n as ENCRYPTED_SEARCH_FEATURES, o as numericTypeProblem, t as ENCRYPTED_INCOMPATIBLE, u as isJsonLeafType } from "./search-fields-BPNsxrCk.mjs";
+import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, s as stableJson, t as deletePath } from "./object-PQ1J8jri.mjs";
 import { resolveAlias as resolveAlias$1 } from "./agg.mjs";
 import { t as NOT_DIMENSION_REASON } from "./aggregate-rules-jdPrxqWa.mjs";
 import { isDbFieldOp, separateCas, separateFieldOps } from "./ops.mjs";
@@ -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 (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 = ENCRYPTED_SEARCH_FEATURES.find((key) => entry.metadata.has(key));
+			if (!feature) continue;
+			const encrypted = 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 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) => isAggregateExpr(item) || 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 DbError("INVALID_QUERY", [{
-		path: "$groupBy",
-		message: "$groupBy must be an array of field names"
-	}]);
+	if (controls.$groupBy !== void 0 && controls.$groupBy !== null) throw 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 DbError("INVALID_QUERY", [{
-			path: "$search",
-			message: `Table "${this.tableName}" has no text search index` + (hasVectorIndex ? " — a @db.search.vector index only answers vectorSearch()" : "")
-		}]);
+		throw 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) => isAggregateExpr(item) || 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 invalidQuery("wait", "`wait` requires `lock`");
+			return;
+		}
+		if (mode !== "update" && mode !== "share") throw invalidQuery("lock", `Unknown lock mode "${String(mode)}" — use 'update' or 'share'`);
+		if (wait !== void 0 && !LOCK_WAITS.has(wait)) throw invalidQuery("wait", `Unknown lock wait "${String(wait)}" — use 'block', 'nowait' or 'skipLocked'`);
+		if (this.isView) throw invalidQuery("lock", `Locking reads run on tables only — "${this.tableName}" is a view`);
+		if (!isRowRead(query.controls)) throw invalidQuery("lock", "A locking read cannot group, aggregate or $count rows");
+		if (!this.adapter.supportsReadLocks()) throw new 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 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 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 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 DbError("INVALID_QUERY", [{
-					path: "$groupBy",
-					message: `Field "${field}" is not a dimension`
-				}]);
+				if (verdict ? !verdict.ok && verdict.code === "notDimension" : !dimSet.has(field)) throw invalidQuery("$groupBy", `Field "${field}" is not a dimension`);
 			}
 			if ($select) for (const item of $select) {
 				if (!isAggregateExpr(item) || item.$field === "*" || measSet.has(item.$field)) continue;
 				if (item.$fn === "countDistinct" || isFirstLast(item)) {
 					if (dimSet.has(item.$field)) continue;
-					throw new DbError("INVALID_QUERY", [{
-						path: "$select",
-						message: `Aggregate field "${item.$field}" is not a dimension or measure`
-					}]);
+					throw invalidQuery("$select", `Aggregate field "${item.$field}" is not a dimension or measure`);
 				}
-				throw new DbError("INVALID_QUERY", [{
-					path: "$select",
-					message: `Aggregate field "${item.$field}" is not a measure`
-				}]);
+				throw 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 (!isAggregateExpr(item) || item.$field === "*") continue;
 				const refField = quantityRefByField.get(item.$field);
-				if (refField && !groupBySet.has(refField)) throw new 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 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 DbError("INVALID_QUERY", [{
-			path: "$sort",
-			message: "geoSearch results are distance-ordered — $sort is not allowed on this path"
-		}]);
+		if (controls.$sort) throw 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 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 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 import("./relation-loader-CNBMPfRr.mjs").then((n) => n.n);
+		const { loadRelationsImpl } = await import("./relation-loader-Qv3LrQ42.mjs").then((n) => n.n);
 		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(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 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 AsyncLocalStorage();
@@ -5519,6 +5718,12 @@ const txStorage = new AsyncLocalStorage();
 function findTxContext(owner) {
 	for (let ctx = txStorage.getStore(); ctx; ctx = ctx.parent) if (ctx.owner === owner) return ctx;
 }
+/** Skip verdict of the deprecated `shouldSkipType` / `warnUnsupportedTypes` options. */
+function legacySkipReason(opts, index) {
+	const unsupported = opts.warnUnsupportedTypes;
+	if (unsupported?.types.includes(index.type)) return `[${unsupported.adapter}] ${index.type} index "${index.name}" declared but not supported by this adapter — skipped`;
+	return opts.shouldSkipType?.(index.type) ? null : void 0;
+}
 /**
 * Abstract base class for database adapters.
 *
@@ -5621,6 +5826,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 +5877,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 +5914,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 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 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 +6021,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 +6330,88 @@ 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;
+			let skipReason = opts.skipIndex?.(index);
+			if (skipReason === void 0) skipReason = legacySkipReason(opts, 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 +6630,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 +7206,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 +7220,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 +7452,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 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 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 +7552,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 DbError("INVALID_QUERY", [{
-			path: "onConflict",
-			message: `Unknown onConflict mode "${String(onConflict)}"`
-		}]);
+		if (onConflict !== void 0 && onConflict !== "error" && onConflict !== "ignore") throw invalidQuery("onConflict", `Unknown onConflict mode "${String(onConflict)}"`);
 		const ignore = onConflict === "ignore";
-		if (lockConflicts && !ignore) throw new DbError("INVALID_QUERY", [{
-			path: "lockConflicts",
-			message: "lockConflicts requires onConflict \"ignore\""
-		}]);
+		if (lockConflicts && !ignore) throw 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 +7645,9 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			const items = payloads.map((p, i) => {
 				const c = clone(p);
 				expectedVersions[i] = 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 +7781,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 = separateFieldOps(data);
@@ -7429,7 +7846,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 invalidQuery("", "touchMany requires @db.column.version");
 		if (keys.length === 0) return {
 			matchedCount: 0,
 			modifiedCount: 0
@@ -7440,14 +7857,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 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 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 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 invalidQuery(`[${i}]`, `touchMany: duplicate key ${identity}`);
 			seen.add(identity);
 			pair[versionField] = version;
 			pairs.push(pair);
@@ -7463,12 +7880,18 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			});
 			if (matched < keys.length) throw new CasMismatchError(matched, keys.length);
 		}
+		const stamps = {};
+		this._stampTopLevel(stamps, Date.now(), true);
+		const { update, ops } = 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 +7942,227 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		};
 		return 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 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);
+		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 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 = 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 && 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 && isEmptyObject(update)) {
+			const matchedCount = await this.adapter.count({
 				filter: translatedFilter,
 				controls: {}
-			}),
-			modifiedCount: 0
-		};
-		return enrichFkViolation(this._meta, () => this.adapter.updateMany(translatedFilter, translatedUpdate, translatedOps, ...updateOpts));
+			});
+			return {
+				matchedCount: bound ? Math.min(matchedCount, bound.writeLimit.limit) : matchedCount,
+				modifiedCount: 0
+			};
+		}
+		return 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);
+		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 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 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 remapDeleteFkViolation(this.tableName, () => this.adapter.deleteMany(this._fieldMapper.translateFilter(filter, this._meta)));
+		return 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 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 invalidQuery("limit", `limit must be a positive integer, got ${String(limit)}`);
+		const pk = this._meta.primaryKeys;
+		if (pk.length === 0) throw 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 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 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 = 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 +8393,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 && !sameKey(item[local], value)) throw new DbError("INVALID_QUERY", [{
-						path: navField,
-						message: `"${navField}" and "${local}" name different parents`
-					}]);
+					if (item[local] !== void 0 && item[local] !== null && !sameKey(item[local], value)) throw invalidQuery(navField, `"${navField}" and "${local}" name different parents`);
 					item[local] = value;
 				});
 				delete item[navField];
@@ -7823,10 +8404,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 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 invalidQuery(navField, "onConflict \"ignore\" cannot create a related parent record — insert it first or reference it by key");
 		}
 	}
 	/**
@@ -7852,10 +8430,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 DbError("INVALID_QUERY", [{
-			path: "",
-			message: "Adapter insertManyIgnore must return one slot per input row"
-		}]);
+		if (slots.length !== send.length) throw invalidQuery("", "Adapter insertManyIgnore must return one slot per input row");
 		const insertedIds = [];
 		const inserted = [];
 		send.forEach((rowIndex, k) => {
@@ -7880,20 +8455,14 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	*/
 	_insertedPkFilters(items, prepared, insertedIds) {
 		const pkFields = this.primaryKeys;
-		if (pkFields.length === 0 && items.length > 0) throw new DbError("INVALID_QUERY", [{
-			path: "",
-			message: "Write check requires a primary key on the table"
-		}]);
+		if (pkFields.length === 0 && items.length > 0) throw 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 DbError("INVALID_QUERY", [{
-					path: field,
-					message: `Write check: cannot resolve the primary key of inserted row [${i}]`
-				}]);
+				if (value === void 0 || value === null) throw invalidQuery(field, `Write check: cannot resolve the primary key of inserted row [${i}]`);
 				key[field] = value;
 			}
 			return this._pkFilterFrom(key);
@@ -7962,14 +8531,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 (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 && 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 +9427,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 +9465,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 +9479,10 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 				path: source.jsonPath,
 				type: source.designType
 			};
-		}
+		} else if (source.jsonColumn && !viewJson && isJsonLeafType(source.designType)) mapping.json = {
+			path: [],
+			type: source.designType
+		};
 		return mapping;
 	}
 };
@@ -8921,62 +9499,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 +9766,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 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 +9859,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 +9900,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 +9912,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
 				});
 			}
@@ -9350,4 +9953,4 @@ function computeColumnDiff(desired, existing, typeMapper, opts) {
 	return diff;
 }
 //#endregion
-export { RelationalFieldMapper as $, AtscriptDbReadable as A, canFilterLeaf as B, ApplicationIntegrity as C, createFailureCollector as D, BaseDbAdapter as E, ADAPTER_FILTER_REASON as F, guardAggregate as G, classifyQueryPath as H, ENCRYPTED_REASON as I, guardPaths as J, guardFilter as K, acceptedOperatorsHint as L, geoIndexNotFoundMessage as M, searchIndexNotFoundMessage as N, IntegrityStrategy as O, vectorIndexNotFoundMessage as P, unsupportedOperatorMessage as Q, assertGeoPoint as R, decomposePatch as S, ALL_VIEW_CAPABILITIES as T, collectQueryPaths as U, checkHavingKeys as V, groupSourceVerdict as W, narrowerFilterOps as X, guardQuery as Y, sortFieldNames as Z, isAtscriptDbView as _, normalizeComputedSelect as _t, computeTableHash as a, defaultFulltextIndex as at, isVersionExemptPatch as b, serializeDefaultValue as c, splitFulltextFields as ct, viewSnapshotSources as d, isGeoPointType as dt, DocumentFieldMapper as et, computeForeignKeyDiff as f, relationalColumnName as ft, AtscriptDbView as g, jsonValueAncestor as gt, hasForeignKeyChanges as h, isJsonValueField as ht, computeSchemaHash as i, INTEGER_REGEX_OP as it, resolveDesignType as j, NativeIntegrity as k, snapshotToExistingColumns as l, TableMetadata as lt, fkKey as m, isBucketableField as mt, isColumnTypeChanged as n, UniquSelect as nt, computeTableSnapshot as o, describeFulltext as ot, fkColumns as p, aliasTargetOf as pt, guardPath as q, canonicalizeQueryNode as r, numericOperandProblem as rt, computeViewSnapshot as s, searchTermInteger as st, computeColumnDiff as t, FieldMappingStrategy as tt, snapshotToExistingTableOptions as u, isGeoIndexableType as ut, isViewType as v, resolveCalendarBuckets as vt, ALL_BUCKET_UNITS as w, assertNoVersionWrites as x, AtscriptDbTable as y, NoopLogger as yt, bucketSourceVerdict as z };
+export { narrowerFilterOps as $, hasForeignKeyChanges as A, acceptedOperatorsHint as B, ALL_VIEW_CAPABILITIES as C, computeForeignKeyDiff as D, createFailureCollector as E, geoIndexNotFoundMessage as F, classifyQueryPath as G, bucketSourceVerdict as H, searchIndexNotFoundMessage as I, guardAggregate as J, collectQueryPaths as K, vectorIndexNotFoundMessage as L, NativeIntegrity as M, AtscriptDbReadable as N, fkColumns as O, resolveDesignType as P, guardQuery as Q, ADAPTER_FILTER_REASON as R, ALL_ISOLATION_LEVELS as S, NoopLogger as St, createChangeRecorder as T, canFilterLeaf as U, assertGeoPoint as V, checkHavingKeys as W, guardPath as X, guardFilter as Y, guardPaths as Z, isVersionExemptPatch as _, isBucketableField as _t, computeSchemaHash as a, UniquSelect as at, ApplicationIntegrity as b, normalizeComputedSelect as bt, computeViewSnapshot as c, defaultFulltextIndex as ct, snapshotToExistingTableOptions as d, splitFulltextFields as dt, sortFieldNames as et, viewSnapshotSources as f, TableMetadata as ft, AtscriptDbTable as g, aliasTargetOf as gt, isViewType as h, relationalColumnName as ht, canonicalizeQueryNode as i, FieldMappingStrategy as it, IntegrityStrategy as j, fkKey as k, serializeDefaultValue as l, describeFulltext as lt, isAtscriptDbView as m, isGeoPointType as mt, isColumnTypeChanged as n, RelationalFieldMapper as nt, computeTableHash as o, numericOperandProblem as ot, AtscriptDbView as p, isGeoIndexableType as pt, groupSourceVerdict as q, sameDefaultValue as r, DocumentFieldMapper as rt, computeTableSnapshot as s, INTEGER_REGEX_OP as st, computeColumnDiff as t, unsupportedOperatorMessage as tt, snapshotToExistingColumns as u, searchTermInteger as ut, assertNoVersionWrites as v, isJsonValueField as vt, BaseDbAdapter as w, ALL_BUCKET_UNITS as x, resolveCalendarBuckets as xt, decomposePatch as y, jsonValueAncestor as yt, ENCRYPTED_REASON as z };