@atscript/db 0.1.148 → 0.1.150

package/dist/{column-diff-CUU4GvYg.cjs → column-diff-CKKBVDvx.cjs}

@@ -1,10 +1,9 @@
 const require_db_error = require("./db-error-DRQH4sLY.cjs");
 const require_aggregate_fns = require("./aggregate-fns-C-UJRobm.cjs");
 const require_nested_writer = require("./nested-writer-BUQvk6QT.cjs");
-const require_derived_rules = require("./derived-rules-YstgIxG-.cjs");
+const require_search_fields = require("./search-fields-DwrsJUC1.cjs");
 const require_object = require("./object-Djg28csK.cjs");
 require("./agg.cjs");
-const require_numeric_operand = require("./numeric-operand-DKfiRLYp.cjs");
 const require_aggregate_rules = require("./aggregate-rules-D_bsCpUI.cjs");
 const require_ops = require("./ops.cjs");
 const require_validator = require("./validator-UcuJxHNT.cjs");
@@ -396,6 +395,10 @@ function isGeoIndexableType(fieldType) {
 	}
 	return false;
 }
+/** Runtime mirror of the `@db.column.version.exempt` placement errors. */
+function rejectVersionExempt(path, why) {
+	throw new Error(`@db.column.version.exempt on "${path}": ${why}`);
+}
 /**
 * Computed metadata for a database table or view.
 *
@@ -443,6 +446,15 @@ var TableMetadata = class {
 	measures = [];
 	/** Logical field name annotated with `@db.column.version`, if any. */
 	versionField;
+	/** Paths annotated with `@db.column.version.exempt`, as declared (since 0.1.150). */
+	_versionExemptDeclared = /* @__PURE__ */ new Set();
+	/**
+	* Version-exempt paths (since 0.1.150): the declared ones plus every object
+	* whose direct children are all exempt (upward closure). A path is exempt
+	* when it, or an ancestor, is in this set — see {@link isVersionExemptPath}.
+	* Empty when the table declares no `@db.column.version`.
+	*/
+	versionExemptPaths = /* @__PURE__ */ new Set();
 	/** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
 	quantityRefByField = /* @__PURE__ */ new Map();
 	/** Logical paths annotated with `@db.encrypted` — stored as one opaque ciphertext column. */
@@ -599,6 +611,7 @@ var TableMetadata = class {
 			...this.originalMetaIdFields
 		]);
 		this._finalizeIndexes();
+		this._finalizeVersionExempt();
 		this._collateMap.clear();
 		this._columnFromMap.clear();
 		this.jsonFields.clear();
@@ -700,6 +713,15 @@ var TableMetadata = class {
 			const name = index === true ? fieldName : typeof index === "string" ? index : index?.name || fieldName;
 			this._addIndexField("unique", name, fieldName);
 		}
+		if (metadata.has("db.writeOnly") && (metadata.has("db.index.fulltext") || metadata.has("db.column.searchable"))) {
+			const which = metadata.has("db.index.fulltext") ? "@db.index.fulltext" : "@db.column.searchable";
+			throw new Error(`@db.writeOnly cannot coexist with ${which} on "${fieldName}" — search results would reveal the sealed value`);
+		}
+		const searchKind = require_search_fields.searchMemberKind(fieldType);
+		if (typeof searchKind === "object") {
+			if (metadata.has("db.index.fulltext")) throw new Error(`@db.index.fulltext on "${fieldName}" ${searchKind.problem} — a fulltext member must be a string or an integer`);
+			if (metadata.has("db.column.searchable")) throw new Error(`@db.column.searchable on "${fieldName}" ${searchKind.problem} — a searchable column must be a string or an integer`);
+		}
 		for (const index of metadata.get("db.index.fulltext") || []) {
 			const name = index === true ? fieldName : typeof index === "string" ? index : index?.name || fieldName;
 			const weight = index !== true && typeof index === "object" ? index?.weight : void 0;
@@ -727,6 +749,7 @@ var TableMetadata = class {
 			if (!hasExplicitIndex) this._addIndexField("plain", fieldName, fieldName);
 		}
 		if (metadata.has("db.column.measure")) this.measures.push(fieldName);
+		if (metadata.has("db.column.version.exempt")) this._versionExemptDeclared.add(fieldName);
 		if (metadata.has("db.column.version")) if (this.versionField !== void 0) logger.warn(`@db.column.version declared on multiple fields ("${this.versionField}" and "${fieldName}") — only one is allowed; using "${this.versionField}"`);
 		else {
 			this.versionField = fieldName;
@@ -737,6 +760,55 @@ var TableMetadata = class {
 		}
 	}
 	/**
+	* Validates the `@db.column.version.exempt` placements (E1–E5, the runtime
+	* mirror of the compile-time check, so pre-compiled models fail fast) and
+	* computes {@link versionExemptPaths} with its upward closure. Runs after
+	* `_applyOverrides` (the primary keys are final) and before `jsonFields` is
+	* released. A table without a version column ignores the annotation.
+	*/
+	_finalizeVersionExempt() {
+		if (this._versionExemptDeclared.size === 0) return;
+		for (const path of this._versionExemptDeclared) {
+			if (path === this.versionField) rejectVersionExempt(path, "cannot mark the version column itself");
+			if (this.primaryKeys.includes(path)) rejectVersionExempt(path, "a primary key identifies the row and is never patched");
+			if (this.navFields.has(path)) rejectVersionExempt(path, "a navigation field has no column here");
+			let pos = path.length;
+			while ((pos = path.lastIndexOf(".", pos - 1)) !== -1) {
+				const ancestor = path.slice(0, pos);
+				const node = this.flatMap.get(ancestor);
+				if (node?.metadata.has("db.json")) rejectVersionExempt(path, `mark the @db.json field "${ancestor}" itself — a JSON column is written as one value`);
+				if (node?.type.kind === "array") rejectVersionExempt(path, `mark the array field "${ancestor}" itself — array elements are not separate columns`);
+			}
+		}
+		if (this.versionField === void 0) return;
+		const exempt = new Set(this._versionExemptDeclared);
+		const objects = [...this.flatMap.keys()].filter((p) => {
+			const node = this.flatMap.get(p);
+			return node.type.kind === "object" && !node.metadata.has("db.json");
+		}).toSorted((a, b) => b.split(".").length - a.split(".").length);
+		for (const obj of objects) {
+			if (exempt.has(obj)) continue;
+			const prefix = `${obj}.`;
+			let children = 0;
+			let all = true;
+			for (const key of this.flatMap.keys()) {
+				if (!key.startsWith(prefix) || key.indexOf(".", prefix.length) !== -1) continue;
+				if (this.navFields.has(key) || this.ignoredFields.has(key)) continue;
+				children++;
+				if (!exempt.has(key)) {
+					all = false;
+					break;
+				}
+			}
+			if (children > 0 && all) exempt.add(obj);
+		}
+		this.versionExemptPaths = exempt;
+	}
+	/** Whether `path` — or an ancestor of it — is version-exempt (since 0.1.150). */
+	isVersionExemptPath(path) {
+		return require_object.selfOrAncestor(path, this.versionExemptPaths) !== void 0;
+	}
+	/**
 	* Build-time diagnostics for `@db.encrypted` (§6 of the field-encryption
 	* spec). Mirrors the compile-time AnnotationSpec validation so models built
 	* from pre-compiled types still fail fast.
@@ -766,7 +838,7 @@ var TableMetadata = class {
 			throw new Error(`@db.column.derived on "${fieldName}": ${why}`);
 		};
 		if (fieldName.includes(".")) reject("only a top-level field of a table can be derived");
-		for (const [name, why] of require_derived_rules.DERIVED_INCOMPATIBLE) if (metadata.has(name)) reject(`cannot coexist with @${name} — ${why}`);
+		for (const [name, why] of require_search_fields.DERIVED_INCOMPATIBLE) if (metadata.has(name)) reject(`cannot coexist with @${name} — ${why}`);
 		const ref = fieldType.ref;
 		if (!ref?.field) reject("requires a chain reference into a @db.json field of the same table (e.g. `customerId: Order.payload.customer.id`)");
 		const target = ref.type();
@@ -784,7 +856,7 @@ var TableMetadata = class {
 		}
 		if (jsonRoot === void 0 || jsonRoot === sourcePath) reject(`path "${sourcePath}" does not read inside a @db.json field — a flattened or scalar column needs no derived column`);
 		const leafType = resolveDesignType(this.flatMap.get(sourcePath));
-		if (!require_derived_rules.isJsonLeafType(leafType)) return reject(`path "${sourcePath}" must end at a string, number or boolean leaf (got "${leafType}")`);
+		if (!require_search_fields.isJsonLeafType(leafType)) return reject(`path "${sourcePath}" must end at a string, number or boolean leaf (got "${leafType}")`);
 		const source = resolveViewSource(rootType, sourcePath, false);
 		return {
 			sourcePath,
@@ -1070,8 +1142,28 @@ var TableMetadata = class {
 			};
 		}
 	}
+	/**
+	* Flags the integer members of fulltext indexes (matched by exact number,
+	* never part of the physical text index) and enforces that each is
+	* index-backed — the equality branch must not scan. Runs while index field
+	* names are still logical.
+	*/
+	_resolveIntegerFulltextMembers() {
+		for (const index of this.indexes.values()) {
+			if (index.type !== "fulltext") continue;
+			for (const field of index.fields) {
+				const ftype = this.flatMap.get(field.name);
+				if (!ftype || require_search_fields.searchMemberKind(ftype) !== "integer") continue;
+				const where = `@db.index.fulltext on the integer field "${field.name}"`;
+				if (require_object.findAncestorInSet(field.name, this.jsonFields) !== void 0) throw new Error(`${where} inside a JSON value is not supported`);
+				if (!(field.name === "_id" || this.originalMetaIdFields[0] === field.name || this.uniqueProps.has(field.name) || [...this.indexes.values()].some((other) => (other.type === "plain" || other.type === "unique") && other.fields[0]?.name === field.name))) throw new Error(`${where} needs an index for its exact-number match — make it the primary key (first @meta.id) or the first field of a @db.index.plain / @db.index.unique`);
+				field.integer = true;
+			}
+		}
+	}
 	_finalizeIndexes() {
 		for (const index of this.indexes.values()) if (index.type === "unique" && index.fields.length === 1) this.uniqueProps.add(index.fields[0].name);
+		this._resolveIntegerFulltextMembers();
 		for (const index of this.indexes.values()) for (const field of index.fields) {
 			const ftype = this.flatMap.get(field.name);
 			if (ftype) {
@@ -1154,6 +1246,334 @@ function computedMeta(rootType, path) {
 	} : void 0;
 }
 //#endregion
+//#region src/shared/search-term.ts
+/**
+* Internal filter operator (since 0.1.150): a regular expression over the
+* DECIMAL TEXT of an integer column. The core rewrites a caller's `$regex`
+* (or bare `RegExp`) on an integer field into it at translation time;
+* callers can never send it (the filter value guard refuses it).
+*/
+const INTEGER_REGEX_OP = "$integerRegex";
+const INTEGER_TERM_RE = /^-?(?:0|[1-9][0-9]*)$/;
+/**
+* The whole number a `$search` term denotes, or `undefined` (since 0.1.150).
+* The trimmed term must be a plain integer literal — ASCII digits with an
+* optional leading `-`, no `+`, no leading zeros (except `0` itself), no
+* `-0`, no separators / decimals / exponent — within the safe-integer range.
+* Only the whole term counts (`"invoice 2946"` has no number).
+*/
+function searchTermInteger(term) {
+	const t = term.trim();
+	if (!INTEGER_TERM_RE.test(t) || t === "-0") return void 0;
+	const n = Number(t);
+	return Number.isSafeInteger(n) ? n : void 0;
+}
+/**
+* Splits a fulltext index into the members that belong to the physical text
+* index and the integer members matched by exact number (since 0.1.150).
+*/
+function splitFulltextFields(index) {
+	const text = [];
+	const integer = [];
+	for (const f of index.fields) (f.integer ? integer : text).push(f);
+	return {
+		text,
+		integer
+	};
+}
+/**
+* `/meta` description of a fulltext index: the adapter's text-index label over
+* the text members, then the exact-number members (since 0.1.150).
+*/
+function describeFulltext(index, textLabel) {
+	const { text, integer } = splitFulltextFields(index);
+	return [text.length > 0 ? textLabel(text.map((f) => f.name).join(", ")) : "", integer.map((f) => `exact number on ${f.name}`).join(" + ")].filter(Boolean).join(" + ");
+}
+/**
+* The fulltext index that answers a search naming none (since 0.1.150): the
+* first one with at least one TEXT member, else the first one (an index of
+* integer members only answers exact-number terms).
+*/
+function defaultFulltextIndex(indexes) {
+	return indexes.find((i) => splitFulltextFields(i).text.length > 0) ?? indexes[0];
+}
+//#endregion
+//#region src/query/filter-values.ts
+const OPAQUE = {
+	kinds: new Set(["any"]),
+	timestamp: false
+};
+const NUMBER = {
+	kinds: new Set(["number"]),
+	timestamp: false
+};
+const INTEGER = {
+	kinds: new Set(["integer"]),
+	timestamp: false
+};
+const STRING = {
+	kinds: new Set(["string"]),
+	timestamp: false
+};
+function collectKinds(type, kinds, out, depth = 0) {
+	const def = type?.type;
+	const metadata = type?.metadata;
+	if (!def || depth > 8) {
+		kinds.add("any");
+		return;
+	}
+	switch (def.kind) {
+		case "": switch (def.designType) {
+			case "string":
+				kinds.add("string");
+				return;
+			case "number": {
+				const timestamp = def.tags?.has("timestamp") === true;
+				if (timestamp) out.timestamp = true;
+				const integer = timestamp || def.tags?.has("int") === true || metadata?.has?.("expect.int") === true;
+				kinds.add(integer ? "integer" : "number");
+				return;
+			}
+			case "decimal":
+				kinds.add("decimal");
+				return;
+			case "boolean":
+				kinds.add("boolean");
+				return;
+			case "null":
+			case "undefined":
+			case "never": return;
+			default:
+				kinds.add("any");
+				return;
+		}
+		case "union":
+			for (const item of def.items ?? []) collectKinds(item, kinds, out, depth + 1);
+			return;
+		case "array":
+			collectKinds(def.of, kinds, out, depth + 1);
+			return;
+		default: kinds.add("any");
+	}
+}
+const typeCache = /* @__PURE__ */ new WeakMap();
+/**
+* The value kinds a filter on `fd` accepts (cached per descriptor). A leaf
+* inside a JSON value (a `@db.json` object or an array, addressable on
+* nested-object adapters) is opaque: its contents are not schema-enforced.
+*/
+function valueTypeOf(meta, fd) {
+	let vt = typeCache.get(fd);
+	if (vt) return vt;
+	if (jsonValueAncestor(fd.path, meta.jsonValueParents) !== void 0 || fd.encrypted || fd.isGeoPoint || fd.designType === "json" || fd.designType === "object" || !fd.type) vt = OPAQUE;
+	else {
+		const kinds = /* @__PURE__ */ new Set();
+		const out = { timestamp: false };
+		collectKinds(fd.type, kinds, out);
+		const metadata = fd.type.metadata;
+		if ((fd.defaultValue?.kind === "fn" && fd.defaultValue.fn !== "uuid" || metadata?.has?.("db.agg.count") === true || metadata?.has?.("db.agg.countDistinct") === true) && kinds.delete("number")) kinds.add("integer");
+		vt = kinds.size === 0 ? OPAQUE : {
+			kinds,
+			timestamp: out.timestamp,
+			integerText: require_search_fields.searchMemberKind(fd.type) === "integer"
+		};
+	}
+	typeCache.set(fd, vt);
+	return vt;
+}
+/** Whether `$regex` on `fd` matches the decimal text of an integer (since 0.1.150). */
+function isIntegerTextField(meta, fd) {
+	return valueTypeOf(meta, fd).integerText === true;
+}
+/** A decimal literal (`5`, `-1.5`, `.5`, `1e3`), surrounding blanks allowed — no hex, no `Infinity`. */
+const NUMERIC_RE = /^\s*[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?\s*$/i;
+/** An integer literal (`5`, `-12`), surrounding blanks allowed. */
+const INTEGER_RE = /^\s*[+-]?\d+\s*$/;
+function acceptsScalar(kind, value) {
+	switch (kind) {
+		case "any": return true;
+		case "string": return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint";
+		case "number":
+		case "decimal": return typeof value === "number" && Number.isFinite(value) || typeof value === "bigint" || typeof value === "string" && NUMERIC_RE.test(value);
+		case "integer": return typeof value === "number" && Number.isInteger(value) || typeof value === "bigint" || typeof value === "string" && INTEGER_RE.test(value);
+		default: return typeof value === "boolean" || value === 0 || value === 1;
+	}
+}
+/** The first element of `value` (itself when not an array) `vt` rejects, or `undefined`. */
+function rejectedValue(vt, value) {
+	if (vt.kinds.has("any") || value === null || value === void 0) return void 0;
+	if (Array.isArray(value)) {
+		for (const item of value) {
+			const bad = rejectedValue(vt, item);
+			if (bad) return bad;
+		}
+		return;
+	}
+	if (typeof value === "object" && !require_object.isPlainObject(value)) return void 0;
+	for (const kind of vt.kinds) if (acceptsScalar(kind, value)) return void 0;
+	return { value };
+}
+const KIND_LABEL = {
+	string: "a string",
+	number: "a number",
+	integer: "an integer",
+	decimal: "a decimal (number or numeric string)",
+	boolean: "a boolean"
+};
+function expectedOf(vt) {
+	const labels = [];
+	for (const kind of vt.kinds) {
+		if (kind === "any") continue;
+		labels.push(kind === "integer" && vt.timestamp ? "an integer (epoch milliseconds)" : KIND_LABEL[kind]);
+	}
+	return labels.join(" or ");
+}
+function describeValue(value) {
+	if (typeof value === "string") return JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}…` : value);
+	if (require_object.isPlainObject(value)) return "an object";
+	return String(value);
+}
+function valueError(path, op, message) {
+	return new require_db_error.DbError("INVALID_QUERY", [{
+		path,
+		message: `Invalid filter value for "${path}"${op ? ` (${op})` : ""}: ${message}`
+	}]);
+}
+function holdsStrings(vt) {
+	return vt.kinds.has("string") || vt.kinds.has("any") || vt.integerText === true;
+}
+function checkRegex(path, vt, op, pattern) {
+	if (!holdsStrings(vt)) throw valueError(path, op, `a pattern match needs a string or integer field, "${path}" holds ${expectedOf(vt)}`);
+	if (typeof pattern !== "string" && !(pattern instanceof RegExp)) throw valueError(path, op, `expected a regular expression, got ${describeValue(pattern)}`);
+}
+function checkValue(path, vt, op, value) {
+	if (value instanceof RegExp) {
+		checkRegex(path, vt, op ?? "RegExp", value);
+		return;
+	}
+	const bad = rejectedValue(vt, value);
+	if (bad) throw valueError(path, op, `expected ${expectedOf(vt)}, got ${describeValue(bad.value)}`);
+}
+/** Operators whose operand is compared with the field's values. */
+const COMPARE_OPS = new Set([
+	"$eq",
+	"$ne",
+	"$gt",
+	"$gte",
+	"$lt",
+	"$lte",
+	"$in",
+	"$nin"
+]);
+/** Checks one filter entry's value (a bare value or an operator map) against `vt`. */
+function checkEntry(path, vt, value) {
+	if (vt.kinds.has("any")) return;
+	if (!require_object.isPlainObject(value)) {
+		checkValue(path, vt, void 0, value);
+		return;
+	}
+	for (const [op, operand] of Object.entries(value)) if (op === "$regex") checkRegex(path, vt, op, operand);
+	else if (COMPARE_OPS.has(op)) checkValue(path, vt, op, operand);
+}
+/**
+* Walks `filter` (through `$and` / `$or` / `$not`; relational predicates are
+* the related table's) and checks every entry whose key `typeOf` knows.
+*/
+function walkFilterValues(filter, typeOf) {
+	if (!require_object.isPlainObject(filter)) return;
+	for (const [key, value] of Object.entries(filter)) {
+		if (key === "$and" || key === "$or") {
+			if (Array.isArray(value)) for (const child of value) walkFilterValues(child, typeOf);
+			continue;
+		}
+		if (key === "$not") {
+			walkFilterValues(value, typeOf);
+			continue;
+		}
+		if (key.startsWith("$") || require_nested_writer.hasRelationOp(value)) continue;
+		if (require_object.isPlainObject(value) && "$integerRegex" in value) throw valueError(key, INTEGER_REGEX_OP, "is internal — use $regex");
+		const vt = typeOf(key);
+		if (vt) checkEntry(key, vt, value);
+	}
+}
+/**
+* Rejects (`INVALID_QUERY`, `path` = the field) a filter value that cannot
+* denote its field's declared type — see the module notes for the accepted
+* forms. Unknown paths are skipped (the path guard owns them).
+*/
+function guardFilterValues(meta, filter) {
+	if (!filter) return;
+	walkFilterValues(filter, (key) => {
+		const fd = meta.descriptorByPath.get(key);
+		return fd ? valueTypeOf(meta, fd) : void 0;
+	});
+}
+/**
+* `$having` values: an aggregate alias is a number (`count`,
+* `countDistinct`, `sum`, `avg`, an expression) or its source field's type
+* (`min` / `max`, `first` / `last`),
+* a calendar-bucket alias a string label, any other key a `$groupBy`
+* field's own type.
+*/
+function guardHavingValues(meta, controls) {
+	if (!controls?.$having) return;
+	const aliases = /* @__PURE__ */ new Map();
+	if (Array.isArray(controls.$select)) {
+		for (const item of controls.$select) if ((0, _uniqu_core.isAggregateOfExpr)(item) || (0, _uniqu_core.isSelectArithExpr)(item)) aliases.set(item.$as, NUMBER);
+		else if ((0, _uniqu_core.isAggregateExpr)(item)) {
+			const fd = require_aggregate_fns.SOURCE_VALUE_FNS.has(item.$fn) ? meta.descriptorByPath.get(item.$field) : void 0;
+			const counts = item.$fn === "count" || item.$fn === "countDistinct";
+			aliases.set((0, _uniqu_core.resolveAlias)(item), fd ? valueTypeOf(meta, fd) : counts ? INTEGER : NUMBER);
+		} else if ((0, _uniqu_core.isBucketExpr)(item)) aliases.set((0, _uniqu_core.resolveAlias)(item), STRING);
+	}
+	walkFilterValues(controls.$having, (key) => {
+		const alias = aliases.get(key);
+		if (alias) return alias;
+		const fd = meta.descriptorByPath.get(key);
+		return fd ? valueTypeOf(meta, fd) : void 0;
+	});
+}
+//#endregion
+//#region src/query/integer-regex.ts
+/** Rewrites one field entry; returns the same value when it has no pattern match. */
+function rewriteEntry(value) {
+	if (value instanceof RegExp) return { [INTEGER_REGEX_OP]: value };
+	if (require_object.isPlainObject(value) && "$regex" in value) {
+		const out = {};
+		for (const [op, operand] of Object.entries(value)) out[op === "$regex" ? INTEGER_REGEX_OP : op] = operand;
+		return out;
+	}
+	return value;
+}
+/**
+* `$regex` (and a bare `RegExp`) on integer search members →
+* {@link INTEGER_REGEX_OP}, on the LOGICAL filter. Copy-on-write: the very
+* same object comes back when nothing changed. Relational predicates are
+* rewritten by the related table when it translates them.
+*/
+function rewriteIntegerRegex(filter, meta) {
+	if (!require_object.isPlainObject(filter)) return filter;
+	let out;
+	for (const [key, value] of Object.entries(filter)) {
+		let next = value;
+		if (key === "$and" || key === "$or") {
+			if (Array.isArray(value)) {
+				const mapped = value.map((f) => rewriteIntegerRegex(f, meta));
+				if (mapped.some((m, i) => m !== value[i])) next = mapped;
+			}
+		} else if (key === "$not") next = rewriteIntegerRegex(value, meta);
+		else if (!key.startsWith("$") && !meta.navFields.has(key)) {
+			const fd = meta.descriptorByPath.get(key);
+			if (fd && isIntegerTextField(meta, fd)) next = rewriteEntry(value);
+		}
+		if (next !== value) {
+			out ??= { ...filter };
+			out[key] = next;
+		}
+	}
+	return out ?? filter;
+}
+//#endregion
 //#region src/query/aggregate-expr.ts
 /** Most nodes a group-level expression may have once the aliases it names are inlined (SQL repeats them). */
 const EXPANDED_MAX_NODES = 4 * _uniqu_core.ARITH_MAX_NODES;
@@ -1171,7 +1591,7 @@ const QUERY_EXPANDED_MAX_NODES = 1024;
 function numericOperandProblem(fd) {
 	if (fd.encrypted) return "is encrypted";
 	if (isJsonValueField(fd)) return "is not a scalar number";
-	return require_numeric_operand.numericTypeProblem({
+	return require_search_fields.numericTypeProblem({
 		base: fd.designType,
 		tags: (fd.type?.type)?.tags
 	});
@@ -1787,6 +2207,7 @@ var FieldMappingStrategy = class {
 	* translate predicate operands at deeper levels).
 	*/
 	translateFilter(filter, meta, depth = 0) {
+		filter = rewriteIntegerRegex(filter, meta);
 		const has = require_nested_writer.containsRelationFilter(filter);
 		const resolved = has ? require_nested_writer.resolveRelationFilterTree(filter, meta, depth) : filter;
 		return this.noteTranslated(filter, this.translateResolvedFilter(resolved, meta), has);
@@ -1921,7 +2342,8 @@ var FieldMappingStrategy = class {
 		if (!require_object.isPlainObject(value)) return fmt(value);
 		const ops = value;
 		const formatted = {};
-		for (const [op, opVal] of Object.entries(ops)) if ((op === "$in" || op === "$nin") && Array.isArray(opVal)) formatted[op] = opVal.map((v) => v === null || v === void 0 ? v : fmt(v));
+		for (const [op, opVal] of Object.entries(ops)) if (op === "$integerRegex") formatted[op] = opVal;
+		else if ((op === "$in" || op === "$nin") && Array.isArray(opVal)) formatted[op] = opVal.map((v) => v === null || v === void 0 ? v : fmt(v));
 		else if (op.startsWith("$") && opVal !== null && opVal !== void 0) formatted[op] = fmt(opVal);
 		else formatted[op] = opVal;
 		return formatted;
@@ -2118,7 +2540,7 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 		return result;
 	}
 	translateQuery(query, meta) {
-		const logical = query.filter;
+		const logical = rewriteIntegerRegex(query.filter, meta);
 		const has = require_nested_writer.containsRelationFilter(logical);
 		const filter = has ? require_nested_writer.resolveRelationFilterTree(logical, meta, 0) : logical;
 		if (!meta.requiresMappings) {
@@ -2192,337 +2614,107 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 			for (const key of Object.keys(update)) result[meta.leafByLogical.get(key)?.physicalName ?? key] = update[key];
 			return result;
 		}
-		const result = {};
-		const updateKeys = Object.keys(update);
-		for (const key of updateKeys) {
-			const value = update[key];
-			const operatorMatch = key.match(/^(.+?)(\.__\$.+)$/);
-			const basePath = operatorMatch ? operatorMatch[1] : key;
-			const suffix = operatorMatch ? operatorMatch[2] : "";
-			const fd = meta.leafByLogical.get(basePath);
-			const finalKey = (fd?.physicalName ?? basePath) + suffix;
-			if (fd?.storage === "json" && typeof value === "object" && value !== null && !suffix) result[finalKey] = JSON.stringify(value);
-			else result[finalKey] = value;
-		}
-		return this.formatWriteValues(result, meta);
-	}
-	/**
-	* Translates field names in sort and projection controls from
-	* logical dot-paths to physical column names.
-	*/
-	translateControls(controls, meta) {
-		if (!controls) return {};
-		const result = {
-			...controls,
-			$select: void 0,
-			$with: void 0
-		};
-		if (controls.$sort) {
-			const translated = {};
-			const sortObj = controls.$sort;
-			const sortKeys = Object.keys(sortObj);
-			for (const key of sortKeys) {
-				if (meta.flattenedParents.has(key)) continue;
-				const physical = meta.leafByLogical.get(key)?.physicalName ?? key;
-				translated[physical] = sortObj[key];
-			}
-			result.$sort = translated;
-		}
-		if (controls.$select) {
-			let translatedRaw;
-			if (Array.isArray(controls.$select)) {
-				const expanded = [];
-				for (const key of controls.$select) {
-					const expansion = meta.selectExpansion.get(key);
-					if (expansion) expanded.push(...expansion);
-					else expanded.push(meta.leafByLogical.get(key)?.physicalName ?? key);
-				}
-				translatedRaw = expanded;
-			} else {
-				const translated = {};
-				const selectObj = controls.$select;
-				const selectKeys = Object.keys(selectObj);
-				for (const key of selectKeys) {
-					const val = selectObj[key];
-					const expansion = meta.selectExpansion.get(key);
-					if (expansion) for (const leaf of expansion) translated[leaf] = val;
-					else {
-						const physical = meta.leafByLogical.get(key)?.physicalName ?? key;
-						translated[physical] = val;
-					}
-				}
-				translatedRaw = translated;
-			}
-			result.$select = new UniquSelect(translatedRaw, meta.allPhysicalFields);
-		}
-		return result;
-	}
-	/**
-	* Flattens nested object fields into __-separated keys and
-	* JSON-stringifies @db.json / array fields.
-	*/
-	flattenPayload(data, meta) {
-		const result = {};
-		for (const key of Object.keys(data)) this.writeFlattenedField(key, data[key], result, meta);
-		return result;
-	}
-	/**
-	* Classifies and writes a single field to the result object.
-	* Recurses into nested objects that should be flattened.
-	*/
-	writeFlattenedField(path, value, result, meta) {
-		if (meta.ignoredFields.has(path)) return;
-		if (meta.flattenedParents.has(path)) {
-			if (value === null || value === void 0) this.setFlattenedChildrenNull(path, result, meta);
-			else if (typeof value === "object" && !Array.isArray(value)) {
-				const obj = value;
-				for (const key of Object.keys(obj)) this.writeFlattenedField(`${path}.${key}`, obj[key], result, meta);
-			}
-		} else {
-			const fd = meta.leafByLogical.get(path);
-			const physical = fd?.physicalName ?? path.replace(/\./g, "__");
-			if (fd?.storage === "json") result[physical] = value !== void 0 && value !== null ? JSON.stringify(value) : value;
-			else result[physical] = value;
-		}
-	}
-	/**
-	* When a parent object is null/undefined, set all its flattened children to null.
-	*/
-	setFlattenedChildrenNull(parentPath, result, meta) {
-		const children = meta.childrenByParent.get(parentPath);
-		if (children) for (const physical of children) result[physical] = null;
-	}
-};
-//#endregion
-//#region src/query/filter-values.ts
-const OPAQUE = {
-	kinds: new Set(["any"]),
-	timestamp: false
-};
-const NUMBER = {
-	kinds: new Set(["number"]),
-	timestamp: false
-};
-const INTEGER = {
-	kinds: new Set(["integer"]),
-	timestamp: false
-};
-const STRING = {
-	kinds: new Set(["string"]),
-	timestamp: false
-};
-function collectKinds(type, kinds, out, depth = 0) {
-	const def = type?.type;
-	const metadata = type?.metadata;
-	if (!def || depth > 8) {
-		kinds.add("any");
-		return;
-	}
-	switch (def.kind) {
-		case "": switch (def.designType) {
-			case "string":
-				kinds.add("string");
-				return;
-			case "number": {
-				const timestamp = def.tags?.has("timestamp") === true;
-				if (timestamp) out.timestamp = true;
-				const integer = timestamp || def.tags?.has("int") === true || metadata?.has?.("expect.int") === true;
-				kinds.add(integer ? "integer" : "number");
-				return;
-			}
-			case "decimal":
-				kinds.add("decimal");
-				return;
-			case "boolean":
-				kinds.add("boolean");
-				return;
-			case "null":
-			case "undefined":
-			case "never": return;
-			default:
-				kinds.add("any");
-				return;
-		}
-		case "union":
-			for (const item of def.items ?? []) collectKinds(item, kinds, out, depth + 1);
-			return;
-		case "array":
-			collectKinds(def.of, kinds, out, depth + 1);
-			return;
-		default: kinds.add("any");
-	}
-}
-const typeCache = /* @__PURE__ */ new WeakMap();
-/**
-* The value kinds a filter on `fd` accepts (cached per descriptor). A leaf
-* inside a JSON value (a `@db.json` object or an array, addressable on
-* nested-object adapters) is opaque: its contents are not schema-enforced.
-*/
-function valueTypeOf(meta, fd) {
-	let vt = typeCache.get(fd);
-	if (vt) return vt;
-	if (jsonValueAncestor(fd.path, meta.jsonValueParents) !== void 0 || fd.encrypted || fd.isGeoPoint || fd.designType === "json" || fd.designType === "object" || !fd.type) vt = OPAQUE;
-	else {
-		const kinds = /* @__PURE__ */ new Set();
-		const out = { timestamp: false };
-		collectKinds(fd.type, kinds, out);
-		const metadata = fd.type.metadata;
-		if ((fd.defaultValue?.kind === "fn" && fd.defaultValue.fn !== "uuid" || metadata?.has?.("db.agg.count") === true || metadata?.has?.("db.agg.countDistinct") === true) && kinds.delete("number")) kinds.add("integer");
-		vt = kinds.size === 0 ? OPAQUE : {
-			kinds,
-			timestamp: out.timestamp
-		};
-	}
-	typeCache.set(fd, vt);
-	return vt;
-}
-/** A decimal literal (`5`, `-1.5`, `.5`, `1e3`), surrounding blanks allowed — no hex, no `Infinity`. */
-const NUMERIC_RE = /^\s*[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?\s*$/i;
-/** An integer literal (`5`, `-12`), surrounding blanks allowed. */
-const INTEGER_RE = /^\s*[+-]?\d+\s*$/;
-function acceptsScalar(kind, value) {
-	switch (kind) {
-		case "any": return true;
-		case "string": return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint";
-		case "number":
-		case "decimal": return typeof value === "number" && Number.isFinite(value) || typeof value === "bigint" || typeof value === "string" && NUMERIC_RE.test(value);
-		case "integer": return typeof value === "number" && Number.isInteger(value) || typeof value === "bigint" || typeof value === "string" && INTEGER_RE.test(value);
-		default: return typeof value === "boolean" || value === 0 || value === 1;
-	}
-}
-/** The first element of `value` (itself when not an array) `vt` rejects, or `undefined`. */
-function rejectedValue(vt, value) {
-	if (vt.kinds.has("any") || value === null || value === void 0) return void 0;
-	if (Array.isArray(value)) {
-		for (const item of value) {
-			const bad = rejectedValue(vt, item);
-			if (bad) return bad;
-		}
-		return;
-	}
-	if (typeof value === "object" && !require_object.isPlainObject(value)) return void 0;
-	for (const kind of vt.kinds) if (acceptsScalar(kind, value)) return void 0;
-	return { value };
-}
-const KIND_LABEL = {
-	string: "a string",
-	number: "a number",
-	integer: "an integer",
-	decimal: "a decimal (number or numeric string)",
-	boolean: "a boolean"
-};
-function expectedOf(vt) {
-	const labels = [];
-	for (const kind of vt.kinds) {
-		if (kind === "any") continue;
-		labels.push(kind === "integer" && vt.timestamp ? "an integer (epoch milliseconds)" : KIND_LABEL[kind]);
+		const result = {};
+		const updateKeys = Object.keys(update);
+		for (const key of updateKeys) {
+			const value = update[key];
+			const operatorMatch = key.match(/^(.+?)(\.__\$.+)$/);
+			const basePath = operatorMatch ? operatorMatch[1] : key;
+			const suffix = operatorMatch ? operatorMatch[2] : "";
+			const fd = meta.leafByLogical.get(basePath);
+			const finalKey = (fd?.physicalName ?? basePath) + suffix;
+			if (fd?.storage === "json" && typeof value === "object" && value !== null && !suffix) result[finalKey] = JSON.stringify(value);
+			else result[finalKey] = value;
+		}
+		return this.formatWriteValues(result, meta);
 	}
-	return labels.join(" or ");
-}
-function describeValue(value) {
-	if (typeof value === "string") return JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}…` : value);
-	if (require_object.isPlainObject(value)) return "an object";
-	return String(value);
-}
-function valueError(path, op, message) {
-	return new require_db_error.DbError("INVALID_QUERY", [{
-		path,
-		message: `Invalid filter value for "${path}"${op ? ` (${op})` : ""}: ${message}`
-	}]);
-}
-function holdsStrings(vt) {
-	return vt.kinds.has("string") || vt.kinds.has("any");
-}
-function checkRegex(path, vt, op, pattern) {
-	if (!holdsStrings(vt)) throw valueError(path, op, `a pattern match needs a string field, "${path}" holds ${expectedOf(vt)}`);
-	if (typeof pattern !== "string" && !(pattern instanceof RegExp)) throw valueError(path, op, `expected a regular expression, got ${describeValue(pattern)}`);
-}
-function checkValue(path, vt, op, value) {
-	if (value instanceof RegExp) {
-		checkRegex(path, vt, op ?? "RegExp", value);
-		return;
+	/**
+	* Translates field names in sort and projection controls from
+	* logical dot-paths to physical column names.
+	*/
+	translateControls(controls, meta) {
+		if (!controls) return {};
+		const result = {
+			...controls,
+			$select: void 0,
+			$with: void 0
+		};
+		if (controls.$sort) {
+			const translated = {};
+			const sortObj = controls.$sort;
+			const sortKeys = Object.keys(sortObj);
+			for (const key of sortKeys) {
+				if (meta.flattenedParents.has(key)) continue;
+				const physical = meta.leafByLogical.get(key)?.physicalName ?? key;
+				translated[physical] = sortObj[key];
+			}
+			result.$sort = translated;
+		}
+		if (controls.$select) {
+			let translatedRaw;
+			if (Array.isArray(controls.$select)) {
+				const expanded = [];
+				for (const key of controls.$select) {
+					const expansion = meta.selectExpansion.get(key);
+					if (expansion) expanded.push(...expansion);
+					else expanded.push(meta.leafByLogical.get(key)?.physicalName ?? key);
+				}
+				translatedRaw = expanded;
+			} else {
+				const translated = {};
+				const selectObj = controls.$select;
+				const selectKeys = Object.keys(selectObj);
+				for (const key of selectKeys) {
+					const val = selectObj[key];
+					const expansion = meta.selectExpansion.get(key);
+					if (expansion) for (const leaf of expansion) translated[leaf] = val;
+					else {
+						const physical = meta.leafByLogical.get(key)?.physicalName ?? key;
+						translated[physical] = val;
+					}
+				}
+				translatedRaw = translated;
+			}
+			result.$select = new UniquSelect(translatedRaw, meta.allPhysicalFields);
+		}
+		return result;
 	}
-	const bad = rejectedValue(vt, value);
-	if (bad) throw valueError(path, op, `expected ${expectedOf(vt)}, got ${describeValue(bad.value)}`);
-}
-/** Operators whose operand is compared with the field's values. */
-const COMPARE_OPS = new Set([
-	"$eq",
-	"$ne",
-	"$gt",
-	"$gte",
-	"$lt",
-	"$lte",
-	"$in",
-	"$nin"
-]);
-/** Checks one filter entry's value (a bare value or an operator map) against `vt`. */
-function checkEntry(path, vt, value) {
-	if (vt.kinds.has("any")) return;
-	if (!require_object.isPlainObject(value)) {
-		checkValue(path, vt, void 0, value);
-		return;
+	/**
+	* Flattens nested object fields into __-separated keys and
+	* JSON-stringifies @db.json / array fields.
+	*/
+	flattenPayload(data, meta) {
+		const result = {};
+		for (const key of Object.keys(data)) this.writeFlattenedField(key, data[key], result, meta);
+		return result;
 	}
-	for (const [op, operand] of Object.entries(value)) if (op === "$regex") checkRegex(path, vt, op, operand);
-	else if (COMPARE_OPS.has(op)) checkValue(path, vt, op, operand);
-}
-/**
-* Walks `filter` (through `$and` / `$or` / `$not`; relational predicates are
-* the related table's) and checks every entry whose key `typeOf` knows.
-*/
-function walkFilterValues(filter, typeOf) {
-	if (!require_object.isPlainObject(filter)) return;
-	for (const [key, value] of Object.entries(filter)) {
-		if (key === "$and" || key === "$or") {
-			if (Array.isArray(value)) for (const child of value) walkFilterValues(child, typeOf);
-			continue;
-		}
-		if (key === "$not") {
-			walkFilterValues(value, typeOf);
-			continue;
+	/**
+	* Classifies and writes a single field to the result object.
+	* Recurses into nested objects that should be flattened.
+	*/
+	writeFlattenedField(path, value, result, meta) {
+		if (meta.ignoredFields.has(path)) return;
+		if (meta.flattenedParents.has(path)) {
+			if (value === null || value === void 0) this.setFlattenedChildrenNull(path, result, meta);
+			else if (typeof value === "object" && !Array.isArray(value)) {
+				const obj = value;
+				for (const key of Object.keys(obj)) this.writeFlattenedField(`${path}.${key}`, obj[key], result, meta);
+			}
+		} else {
+			const fd = meta.leafByLogical.get(path);
+			const physical = fd?.physicalName ?? path.replace(/\./g, "__");
+			if (fd?.storage === "json") result[physical] = value !== void 0 && value !== null ? JSON.stringify(value) : value;
+			else result[physical] = value;
 		}
-		if (key.startsWith("$") || require_nested_writer.hasRelationOp(value)) continue;
-		const vt = typeOf(key);
-		if (vt) checkEntry(key, vt, value);
 	}
-}
-/**
-* Rejects (`INVALID_QUERY`, `path` = the field) a filter value that cannot
-* denote its field's declared type — see the module notes for the accepted
-* forms. Unknown paths are skipped (the path guard owns them).
-*/
-function guardFilterValues(meta, filter) {
-	if (!filter) return;
-	walkFilterValues(filter, (key) => {
-		const fd = meta.descriptorByPath.get(key);
-		return fd ? valueTypeOf(meta, fd) : void 0;
-	});
-}
-/**
-* `$having` values: an aggregate alias is a number (`count`,
-* `countDistinct`, `sum`, `avg`, an expression) or its source field's type
-* (`min` / `max`, `first` / `last`),
-* a calendar-bucket alias a string label, any other key a `$groupBy`
-* field's own type.
-*/
-function guardHavingValues(meta, controls) {
-	if (!controls?.$having) return;
-	const aliases = /* @__PURE__ */ new Map();
-	if (Array.isArray(controls.$select)) {
-		for (const item of controls.$select) if ((0, _uniqu_core.isAggregateOfExpr)(item) || (0, _uniqu_core.isSelectArithExpr)(item)) aliases.set(item.$as, NUMBER);
-		else if ((0, _uniqu_core.isAggregateExpr)(item)) {
-			const fd = require_aggregate_fns.SOURCE_VALUE_FNS.has(item.$fn) ? meta.descriptorByPath.get(item.$field) : void 0;
-			const counts = item.$fn === "count" || item.$fn === "countDistinct";
-			aliases.set((0, _uniqu_core.resolveAlias)(item), fd ? valueTypeOf(meta, fd) : counts ? INTEGER : NUMBER);
-		} else if ((0, _uniqu_core.isBucketExpr)(item)) aliases.set((0, _uniqu_core.resolveAlias)(item), STRING);
+	/**
+	* When a parent object is null/undefined, set all its flattened children to null.
+	*/
+	setFlattenedChildrenNull(parentPath, result, meta) {
+		const children = meta.childrenByParent.get(parentPath);
+		if (children) for (const physical of children) result[physical] = null;
 	}
-	walkFilterValues(controls.$having, (key) => {
-		const alias = aliases.get(key);
-		if (alias) return alias;
-		const fd = meta.descriptorByPath.get(key);
-		return fd ? valueTypeOf(meta, fd) : void 0;
-	});
-}
+};
 //#endregion
 //#region src/query/query-guards.ts
 /**
@@ -3595,6 +3787,17 @@ var AtscriptDbReadable = class {
 		if (field === void 0) return void 0;
 		return this._meta.columnMap.get(field) ?? field;
 	}
+	/**
+	* 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
+	* `@db.column.version`.
+	* @since 0.1.150
+	*/
+	get versionExemptFields() {
+		this._ensureBuilt();
+		return this._meta.versionExemptPaths;
+	}
 	/** Dimension fields from `@db.column.dimension`. */
 	get dimensions() {
 		this._ensureBuilt();
@@ -4661,6 +4864,16 @@ var BaseDbAdapter = class {
 		this._verbose = enabled;
 	}
 	/**
+	* Physical version column an UPDATE must bump, or `undefined` when it must
+	* not: no `@db.column.version`, or a version-exempt patch
+	* (`opts.keepVersion`, since 0.1.150 — the core never combines it with
+	* `expectedVersion`; a violation throws).
+	*/
+	_versionColumnFor(opts, expectedVersion) {
+		if (!opts?.keepVersion) return this._table.versionColumnPhysical;
+		if (expectedVersion !== void 0) throw new Error("keepVersion cannot combine with expectedVersion");
+	}
+	/**
 	* Logs a debug message if verbose mode is enabled.
 	* Adapters call this to log DB operations with zero overhead when disabled.
 	*/
@@ -5000,9 +5213,10 @@ var BaseDbAdapter = class {
 	*
 	* @param filter - Filter identifying the record to patch.
 	* @param patch - The patch payload with array operations.
+	* @param opts - `keepVersion`: skip the version bump (see {@link TDbUpdateOptions}).
 	* @returns Update result.
 	*/
-	async nativePatch(_filter, _patch, _ops, _expectedVersion) {
+	async nativePatch(_filter, _patch, _ops, _expectedVersion, _opts) {
 		throw new Error("Native patch not supported by this adapter");
 	}
 	/**
@@ -5047,6 +5261,7 @@ var BaseDbAdapter = class {
 				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));
@@ -5067,6 +5282,13 @@ var BaseDbAdapter = class {
 	/**
 	* Returns available search indexes for this adapter.
 	* UI uses this to show index picker. Override in adapters that support search.
+	*
+	* A fulltext index may carry integer members ({@link TDbIndexField.integer},
+	* since 0.1.150): list them in `fields`, keep them out of the physical text
+	* index, and OR `member = n` into the search predicate when
+	* `searchTermInteger(text)` is defined. An index of integer members only
+	* is still listed (it makes the table natively searchable); a term that is
+	* not a whole number then matches nothing.
 	*/
 	getSearchIndexes() {
 		return [];
@@ -5112,7 +5334,9 @@ var BaseDbAdapter = class {
 		return false;
 	}
 	/**
-	* Full-text search. Override in adapters that support search.
+	* Full-text search. Override in adapters that support search. The text
+	* match is OR'd with exact-number equality on the index's integer members
+	* when the whole term is a whole number (see `searchTermInteger`).
 	*
 	* @param text - Search text.
 	* @param query - Filter, sort, limit, etc.
@@ -5696,6 +5920,8 @@ function matchByKeys(a, b, keys) {
 }
 //#endregion
 //#region src/patch/patch-decomposer.ts
+/** Metadata tag the flattener puts on top-level array fields (shared with `isVersionExemptPatch`). */
+const TOP_LEVEL_ARRAY_TAG = "db.__topLevelArray";
 /**
 * Decomposes a patch payload into a flat update object for adapters
 * that don't support native patch operations.
@@ -5714,7 +5940,7 @@ function matchByKeys(a, b, keys) {
 */
 function decomposePatch(payload, table) {
 	const update = {};
-	flattenPatchPayload(payload, "", update, table, "db.__topLevelArray");
+	flattenPatchPayload(payload, "", update, table, TOP_LEVEL_ARRAY_TAG);
 	return update;
 }
 function flattenPatchPayload(payload, prefix, update, table, topLevelArrayTag) {
@@ -5796,6 +6022,44 @@ function assertNoVersionWrites(data, versionColumn) {
 	}]);
 }
 //#endregion
+//#region src/patch/version-exempt.ts
+/**
+* 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 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); anything else is a non-exempt write.
+* True iff at least one key is covered and none is not.
+* @since 0.1.150
+*/
+function isVersionExemptPatch(data, table) {
+	const meta = table.getMetadata();
+	if (meta.versionExemptPaths.size === 0) return false;
+	const walk = (obj, prefix) => {
+		let result = "none";
+		for (const [k, value] of Object.entries(obj)) {
+			const key = prefix ? `${prefix}.${k}` : k;
+			if (table.primaryKeys.includes(key)) continue;
+			if (meta.isVersionExemptPath(key)) {
+				result = "exempt";
+				continue;
+			}
+			const flatType = table.flatMap.get(key);
+			if (typeof value === "object" && value !== null && !Array.isArray(value) && !require_ops.isDbFieldOp(value) && !flatType?.metadata?.get("db.__topLevelArray") && !flatType?.metadata?.has("db.json") && flatType?.metadata?.get("db.patch.strategy") === "merge") {
+				const inner = walk(value, key);
+				if (inner === "versioned") return "versioned";
+				if (inner === "exempt") result = "exempt";
+				continue;
+			}
+			return "versioned";
+		}
+		return result;
+	};
+	return walk(data, "") === "exempt";
+}
+//#endregion
 //#region src/table/db-table.ts
 /** Returns true when `value` is a plain object carrying any `$`-prefixed key (an operator object). */
 function _hasOperatorKeys(value) {
@@ -6003,6 +6267,8 @@ function concurrentChange() {
 		message: "The record changed during the write — nothing was written, retry"
 	}]);
 }
+/** 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. */
@@ -6291,12 +6557,13 @@ 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] : [];
 				let result;
 				if (this.adapter.supportsNativePatch()) {
 					const ops = require_ops.separateFieldOps(data);
 					const translatedOps = ops ? this._fieldMapper.translateOpsKeys(ops, this._meta) : void 0;
 					const translatedData = this._fieldMapper.translatePatchKeys(data, this._meta);
-					result = await this.adapter.nativePatch(translatedFilter, translatedData, translatedOps, expectedVersion);
+					result = await this.adapter.nativePatch(translatedFilter, translatedData, translatedOps, expectedVersion, ...updateOpts);
 				} else {
 					const update = decomposePatch(data, this);
 					const ops = require_ops.separateFieldOps(update);
@@ -6307,8 +6574,8 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 							filter: translatedFilter,
 							controls: {}
 						}), this);
-						result = await this.adapter.updateOne(translatedFilter, resolved, translatedOps, expectedVersion);
-					} else result = await this.adapter.updateOne(translatedFilter, translatedUpdate, translatedOps, expectedVersion);
+						result = await this.adapter.updateOne(translatedFilter, resolved, translatedOps, expectedVersion, ...updateOpts);
+					} else result = await this.adapter.updateOne(translatedFilter, translatedUpdate, translatedOps, expectedVersion, ...updateOpts);
 				}
 				modifiedCount += result.modifiedCount;
 				matched[i] = result.matchedCount > 0;
@@ -6455,6 +6722,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			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] : [];
 		await this._encryptItems([dataCopy], "patch");
 		const update = decomposePatch(dataCopy, this);
 		const ops = require_ops.separateFieldOps(update);
@@ -6468,7 +6736,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			}),
 			modifiedCount: 0
 		};
-		return require_nested_writer.enrichFkViolation(this._meta, () => this.adapter.updateMany(translatedFilter, translatedUpdate, translatedOps));
+		return require_nested_writer.enrichFkViolation(this._meta, () => this.adapter.updateMany(translatedFilter, translatedUpdate, translatedOps, ...updateOpts));
 	}
 	async replaceMany(filter, data) {
 		this._ensureBuilt();
@@ -7400,7 +7668,7 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		};
 		if (joinNullable || source.optional || source.designType === "unknown") mapping.nullable = true;
 		if (source.jsonPath) {
-			if (!require_derived_rules.isJsonLeafType(source.designType)) throw new Error(`View "${this.tableName}" field "${viewPath}": JSON extraction supports string, number and boolean leaves only`);
+			if (!require_search_fields.isJsonLeafType(source.designType)) throw new Error(`View "${this.tableName}" field "${viewPath}": JSON extraction supports string, number and boolean leaves only`);
 			mapping.json = {
 				path: source.jsonPath,
 				type: source.designType
@@ -7540,7 +7808,8 @@ function computeTableSnapshot(readable, typeMapper, tableOptions) {
 		type: idx.type,
 		fields: idx.fields.map((f) => ({
 			name: f.name,
-			sort: f.sort
+			sort: f.sort,
+			...f.integer ? { integer: true } : {}
 		}))
 	})).toSorted((a, b) => a.key.localeCompare(b.key));
 	const foreignKeys = [...readable.foreignKeys.values()].map((fk) => ({
@@ -7913,6 +8182,12 @@ Object.defineProperty(exports, "FieldMappingStrategy", {
 		return FieldMappingStrategy;
 	}
 });
+Object.defineProperty(exports, "INTEGER_REGEX_OP", {
+	enumerable: true,
+	get: function() {
+		return INTEGER_REGEX_OP;
+	}
+});
 Object.defineProperty(exports, "IntegrityStrategy", {
 	enumerable: true,
 	get: function() {
@@ -8057,6 +8332,18 @@ Object.defineProperty(exports, "decomposePatch", {
 		return decomposePatch;
 	}
 });
+Object.defineProperty(exports, "defaultFulltextIndex", {
+	enumerable: true,
+	get: function() {
+		return defaultFulltextIndex;
+	}
+});
+Object.defineProperty(exports, "describeFulltext", {
+	enumerable: true,
+	get: function() {
+		return describeFulltext;
+	}
+});
 Object.defineProperty(exports, "fkColumns", {
 	enumerable: true,
 	get: function() {
@@ -8153,6 +8440,12 @@ Object.defineProperty(exports, "isJsonValueField", {
 		return isJsonValueField;
 	}
 });
+Object.defineProperty(exports, "isVersionExemptPatch", {
+	enumerable: true,
+	get: function() {
+		return isVersionExemptPatch;
+	}
+});
 Object.defineProperty(exports, "isViewType", {
 	enumerable: true,
 	get: function() {
@@ -8201,6 +8494,12 @@ Object.defineProperty(exports, "searchIndexNotFoundMessage", {
 		return searchIndexNotFoundMessage;
 	}
 });
+Object.defineProperty(exports, "searchTermInteger", {
+	enumerable: true,
+	get: function() {
+		return searchTermInteger;
+	}
+});
 Object.defineProperty(exports, "snapshotToExistingColumns", {
 	enumerable: true,
 	get: function() {
@@ -8219,6 +8518,12 @@ Object.defineProperty(exports, "sortFieldNames", {
 		return sortFieldNames;
 	}
 });
+Object.defineProperty(exports, "splitFulltextFields", {
+	enumerable: true,
+	get: function() {
+		return splitFulltextFields;
+	}
+});
 Object.defineProperty(exports, "unsupportedOperatorMessage", {
 	enumerable: true,
 	get: function() {