@atscript/db 0.1.148 → 0.1.150

package/dist/plugin.cjs

@@ -34,10 +34,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 //#endregion
 const require_aggregate_fns = require("./aggregate-fns-C-UJRobm.cjs");
-const require_derived_rules = require("./derived-rules-YstgIxG-.cjs");
-const require_numeric_operand = require("./numeric-operand-DKfiRLYp.cjs");
+const require_search_fields = require("./search-fields-DwrsJUC1.cjs");
 require("./consts-BzRfCcH2.cjs");
-const require_validation_utils = require("./validation-utils-Da2GjobR.cjs");
+const require_validation_utils = require("./validation-utils-debIYpq0.cjs");
 let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
 let node_url = require("node:url");
@@ -383,7 +382,7 @@ const dbAliasAnnotations = { alias: new _atscript_core.AnnotationSpec({
 		const errors = [];
 		const owner = token.parentNode;
 		const target = args[0]?.text;
-		for (const name of require_derived_rules.DB_ENTITY_ANNOTATIONS) if (owner.countAnnotations(name) > 0) {
+		for (const name of require_search_fields.DB_ENTITY_ANNOTATIONS) if (owner.countAnnotations(name) > 0) {
 			errors.push({
 				message: `A @db.alias type cannot carry @${name} — it names a join scope over "${target ?? "…"}", not a table or view`,
 				severity: 1,
@@ -509,7 +508,7 @@ function viewProps(owner) {
 function validateJsonChain(fieldName, ref, doc, range) {
 	const info = jsonChainInfo(ref, doc);
 	if (!info.resolved || info.jsonRoot === void 0 || info.jsonRoot >= info.chain.length) return [];
-	if (info.leafType !== void 0 && require_derived_rules.JSON_LEAF_TYPES.has(info.leafType)) return [];
+	if (info.leafType !== void 0 && require_search_fields.JSON_LEAF_TYPES.has(info.leafType)) return [];
 	return [{
 		message: `Field "${fieldName}" reads "${info.typeName}.${info.chain.join(".")}" inside a JSON-stored field — it must end at a string, number or boolean leaf`,
 		severity: 1,
@@ -552,6 +551,68 @@ function validateViewInterface(owner, doc) {
 }
 //#endregion
 //#region src/plugin/annotations/column.ts
+/** Nav-field annotations: a navigation field has no column on this table. */
+const NAV_ANNOTATIONS = [
+	"db.rel.to",
+	"db.rel.from",
+	"db.rel.via"
+];
+/**
+* Compile-time placement rules of `@db.column.version.exempt` (E1–E5, W1, W2).
+* E6 (derived) lives in `DERIVED_INCOMPATIBLE`. The runtime mirror is
+* `TableMetadata._finalizeVersionExempt`.
+* @since 0.1.150
+*/
+function validateVersionExempt(token) {
+	const errors = [];
+	const field = token.parentNode;
+	const fail = (message, severity = 1) => {
+		errors.push({
+			message,
+			severity,
+			range: token.range
+		});
+	};
+	const tag = "@db.column.version.exempt";
+	if (field.countAnnotations("db.column.version") > 0) fail(`${tag} cannot mark the version column itself`);
+	if (field.countAnnotations("meta.id") > 0) fail(`${tag} cannot mark a primary key — it identifies the row and is never patched`);
+	if (NAV_ANNOTATIONS.some((n) => field.countAnnotations(n) > 0)) fail(`${tag} cannot mark a navigation field — related rows follow their own table's versioning`);
+	if (field.countAnnotations("db.ignore") > 0) fail(`${tag} has no effect on an ignored field`, 2);
+	let node = field;
+	let tableOwner;
+	let reported = false;
+	while (node.ownerNode && (0, _atscript_core.isStructure)(node.ownerNode)) {
+		let up = node.ownerNode.ownerNode;
+		let viaArray = false;
+		while (up && (0, _atscript_core.isArray)(up)) {
+			viaArray = true;
+			up = up.ownerNode;
+		}
+		if (!up) break;
+		if ((0, _atscript_core.isInterface)(up)) {
+			tableOwner = up;
+			break;
+		}
+		if (!(0, _atscript_core.isProp)(up)) break;
+		if (!reported && viaArray) {
+			fail(`${tag} cannot sit inside an array — mark the array field '${up.id ?? ""}' itself; array elements are not separate columns`);
+			reported = true;
+		} else if (!reported && up.countAnnotations("db.json") > 0) {
+			fail(`${tag} cannot sit inside a @db.json field — mark the @db.json field '${up.id ?? ""}' itself; a JSON column is written as one value`);
+			reported = true;
+		}
+		node = up;
+	}
+	if (tableOwner && (0, _atscript_core.isInterface)(tableOwner) && tableOwner.countAnnotations("db.table") > 0) {
+		const struct = tableOwner.getDefinition();
+		let hasVersion = false;
+		if (struct && (0, _atscript_core.isStructure)(struct)) {
+			for (const [, prop] of struct.props) if (prop.countAnnotations("db.column.version") > 0) hasVersion = true;
+		}
+		if (!hasVersion) fail(`${tag} has no effect — table '${tableOwner.id ?? ""}' declares no @db.column.version`, 2);
+	}
+	return errors;
+}
 const dbColumnAnnotations = {
 	patch: { strategy: new _atscript_core.AnnotationSpec({
 		description: "Defines the **patching strategy** for updating nested objects.\n\n- **\"replace\"** → The field or object will be **fully replaced**.\n- **\"merge\"** → The field or object will be **merged recursively** (applies only to objects, not arrays).\n\n**Example:**\n```atscript\n@db.patch.strategy \"merge\"\nsettings: {\n  notifications: boolean\n  preferences: {\n    theme: string\n  }\n}\n```\n",
@@ -658,7 +719,7 @@ const dbColumnAnnotations = {
 					fail("@db.column.derived is only valid on a top-level field of a @db.table interface");
 					return errors;
 				}
-				for (const [name, why] of require_derived_rules.DERIVED_INCOMPATIBLE) if (field.countAnnotations(name) > 0) fail(`@db.column.derived cannot coexist with @${name} — ${why}`);
+				for (const [name, why] of require_search_fields.DERIVED_INCOMPATIBLE) if (field.countAnnotations(name) > 0) fail(`@db.column.derived cannot coexist with @${name} — ${why}`);
 				const definition = field.getDefinition();
 				if (!definition || !(0, _atscript_core.isRef)(definition) || !definition.hasChain) {
 					fail("@db.column.derived requires a chain reference into a @db.json field of the same table (e.g. `customerId: Order.payload.customer.id`)");
@@ -690,7 +751,7 @@ const dbColumnAnnotations = {
 					fail(`@db.column.derived path '${path}' reads inside a @db.encrypted field — ciphertext cannot be extracted`);
 					return errors;
 				}
-				if (info.leafType === void 0 || !require_derived_rules.JSON_LEAF_TYPES.has(info.leafType)) {
+				if (info.leafType === void 0 || !require_search_fields.JSON_LEAF_TYPES.has(info.leafType)) {
 					fail(`@db.column.derived path '${path}' must end at a string, number or boolean leaf` + (info.leafType ? ` (got '${info.leafType}')` : ""));
 					return errors;
 				}
@@ -714,38 +775,55 @@ const dbColumnAnnotations = {
 		filterable: columnCapability("filterable", "filtering"),
 		sortable: columnCapability("sortable", "sorting"),
 		searchable: new _atscript_core.AnnotationSpec({
-			description: "Includes this column in the generic `$search` fallback: when the adapter reports no native search capability (no FTS / Atlas index configured), the readable controller matches the `$search` term as a case-insensitive substring across all `@db.column.searchable` fields (`$or`). Where adapter-native search IS available it wins and this annotation is not consulted. The term is escaped literally — no user-supplied regex. String-typed columns only.\n\n**Example:**\n```atscript\n@db.table \"jobs\"\nexport interface Job {\n  @db.column.searchable\n  jobName: string\n  @db.column.searchable\n  description: string\n}\n```\n",
+			description: "Includes this column in the generic `$search` fallback: when the adapter reports no native search capability (no FTS / Atlas index configured), the readable controller matches the `$search` term as a case-insensitive substring across all `@db.column.searchable` fields (`$or`). Where adapter-native search IS available it wins and this annotation is not consulted. The term is escaped literally — no user-supplied regex. String and integer columns only: an integer column (`number.int` and its sizes, `@expect.int`, `@db.default.increment`) matches when the term is a substring of the number's decimal text (`2946` finds `29461277`). Floats, decimals and timestamps are refused.\n\n**Example:**\n```atscript\n@db.table \"jobs\"\nexport interface Job {\n  @db.column.searchable\n  jobName: string\n  @db.column.searchable\n  description: string\n  @db.column.searchable\n  refNo: number.int\n}\n```\n",
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			multiple: false,
 			validate(token, _args, doc) {
-				return require_validation_utils.validateFieldBaseType(token, doc, "@db.column.searchable", ["string"]);
-			}
-		}),
-		version: new _atscript_core.AnnotationSpec({
-			description: "Marks a numeric column as the row's version for optimistic concurrency control (OCC). The adapter auto-increments this column on every UPDATE, and callers may pass `$cas: { <col>: N }` in a write payload to make the update conditional on the current version. Direct writes to the version column (as plain SET, `$inc`, or `$mul`) are rejected.\n\n**Constraints:**\n- At most one version column per table.\n- Must resolve to an integer type (`int`, `int32`, `int64`, etc.).\n- Default value on insert is `0`.\n\n**Example:**\n```atscript\n@db.column.version\nversion: int\n```\n",
-			nodeType: ["prop"],
-			passedWhenReferred: false,
-			validate(token, _args, doc) {
-				const errors = require_validation_utils.validateFieldBaseType(token, doc, "@db.column.version", "number");
-				if (token.parentNode.has("optional")) errors.push({
-					message: "@db.column.version requires a non-optional field — version columns are always populated (default 0)",
+				const verdict = require_validation_utils.searchFieldVerdict(token.parentNode, doc);
+				if (!("problem" in verdict)) return [];
+				return [{
+					message: `@db.column.searchable needs a string or an integer field — "${token.parentNode.id}" ${verdict.problem}`,
 					severity: 1,
 					range: token.range
-				});
-				const struct = require_validation_utils.getParentStruct(token);
-				if (struct) {
-					let count = 0;
-					for (const [, prop] of struct.props) if (prop.countAnnotations("db.column.version") > 0) count++;
-					if (count > 1) errors.push({
-						message: "At most one @db.column.version per table",
+				}];
+			}
+		}),
+		version: {
+			$self: new _atscript_core.AnnotationSpec({
+				description: "Marks a numeric column as the row's version for optimistic concurrency control (OCC). The adapter auto-increments this column on every UPDATE, and callers may pass `$cas: { <col>: N }` in a write payload to make the update conditional on the current version. Direct writes to the version column (as plain SET, `$inc`, or `$mul`) are rejected. Fields marked `@db.column.version.exempt` do not bump it.\n\n**Constraints:**\n- At most one version column per table.\n- Must resolve to an integer type (`int`, `int32`, `int64`, etc.).\n- Default value on insert is `0`.\n\n**Example:**\n```atscript\n@db.column.version\nversion: int\n```\n",
+				nodeType: ["prop"],
+				passedWhenReferred: false,
+				validate(token, _args, doc) {
+					const errors = require_validation_utils.validateFieldBaseType(token, doc, "@db.column.version", "number");
+					if (token.parentNode.has("optional")) errors.push({
+						message: "@db.column.version requires a non-optional field — version columns are always populated (default 0)",
 						severity: 1,
 						range: token.range
 					});
+					const struct = require_validation_utils.getParentStruct(token);
+					if (struct) {
+						let count = 0;
+						for (const [, prop] of struct.props) if (prop.countAnnotations("db.column.version") > 0) count++;
+						if (count > 1) errors.push({
+							message: "At most one @db.column.version per table",
+							severity: 1,
+							range: token.range
+						});
+					}
+					return errors;
 				}
-				return errors;
-			}
-		})
+			}),
+			exempt: new _atscript_core.AnnotationSpec({
+				description: "Marks a field as **version-exempt**: a patch that writes ONLY exempt fields (`updateOne` / `bulkUpdate` without `$cas`, `updateMany`) leaves `@db.column.version` unchanged and adds no version check. A patch touching any other field bumps as usual; `$cas`, replace and `touchMany` always bump. Use it for derived/reporting columns refreshed in the background (scores, counters, caches) so they do not invalidate versions held by editors. On an object field it covers every nested field.\n\n**Example:**\n```atscript\n@db.column.version\nversion: number.int\n@db.column.version.exempt\nscore: number\n```\n",
+				nodeType: ["prop"],
+				passedWhenReferred: false,
+				multiple: false,
+				validate(token) {
+					return validateVersionExempt(token);
+				}
+			})
+		}
 	},
 	default: {
 		$self: new _atscript_core.AnnotationSpec({
@@ -858,17 +936,23 @@ const dbColumnAnnotations = {
 		}
 	}),
 	writeOnly: new _atscript_core.AnnotationSpec({
-		description: "Marks a field as write-only over HTTP: it may be set through insert/update/replace payloads but NEVER appears in read responses — the readable controller excludes it from every projection, rejects filtering/sorting/grouping on it, and `/meta` serves its TYPE (flagged `writeOnly`) so client preflight validation and generated forms still know its shape. The classic case is a sealed secret (pair with `@db.encrypted`): writable via generic forms, unreadable by anyone.\n\nServer-side code reading through `AtscriptDbTable` still sees the value — the seal is an HTTP-layer contract, not a storage one.\n\n**Example:**\n```atscript\n@db.writeOnly\n@db.encrypted\ncredentials?: string\n```\n",
+		description: "Marks a field as write-only over HTTP: it may be set through insert/update/replace payloads but NEVER appears in read responses — the readable controller excludes it from every projection, rejects filtering/sorting/grouping on it, and `/meta` serves its TYPE (flagged `writeOnly`) so client preflight validation and generated forms still know its shape. The classic case is a sealed secret (pair with `@db.encrypted`): writable via generic forms, unreadable by anyone.\n\nServer-side code reading through `AtscriptDbTable` still sees the value — the seal is an HTTP-layer contract, not a storage one. It cannot be combined with `@db.index.fulltext` or `@db.column.searchable`: a search hit would reveal the sealed value.\n\n**Example:**\n```atscript\n@db.writeOnly\n@db.encrypted\ncredentials?: string\n```\n",
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		multiple: false,
 		validate(token, _args, _doc) {
 			const errors = [];
-			if (token.parentNode.countAnnotations("meta.id") > 0) errors.push({
+			const field = token.parentNode;
+			if (field.countAnnotations("meta.id") > 0) errors.push({
 				message: `@db.writeOnly cannot coexist with @meta.id — the primary key must be readable`,
 				severity: 1,
 				range: token.range
 			});
+			for (const name of ["db.index.fulltext", "db.column.searchable"]) if (field.countAnnotations(name) > 0) errors.push({
+				message: `@db.writeOnly cannot coexist with @${name} — search results would reveal the sealed value`,
+				severity: 1,
+				range: token.range
+			});
 			return errors;
 		}
 	})
@@ -931,7 +1015,7 @@ function operandProblem(prop, doc) {
 	const leaf = def && (0, _atscript_core.isRef)(def) ? doc.unwindType(def.id, def.chain)?.def : def;
 	const base = require_validation_utils.primitiveBaseType(leaf);
 	if (base === void 0) return void 0;
-	return require_numeric_operand.numericTypeProblem({
+	return require_search_fields.numericTypeProblem({
 		base,
 		tags: (0, _atscript_core.isPrimitive)(leaf) ? leaf.tags : void 0
 	});
@@ -1051,7 +1135,30 @@ const dbIndexAnnotations = { index: {
 		}
 	}),
 	fulltext: new _atscript_core.AnnotationSpec({
-		description: "Full-text search index. Fields sharing the same index name form a composite full-text index.\n\n**Example:**\n```atscript\n@db.index.fulltext \"ft_content\"\ntitle: string\n\n@db.index.fulltext \"ft_content\", 5\nbio: string\n```\n",
+		description: "Full-text search index. Fields sharing the same index name form a composite full-text index. A string member is part of the engine's text index. An integer member (`number.int` and its sizes, `@expect.int`, `@db.default.increment`) is never part of the physical text index: when the whole search term is a whole number (`2946`, `-12`; no leading zeros), rows whose member equals it exactly also match (OR'd with the text match). An integer member must be index-backed — the primary key (first `@meta.id`) or the first field of a `@db.index.plain` / `@db.index.unique`. Floats, decimals and timestamps are refused.\n\n**Example:**\n```atscript\n@db.index.fulltext \"ft_content\"\ntitle: string\n\n@db.index.fulltext \"ft_content\", 5\nbio: string\n\n@db.index.fulltext \"ft_content\"\n@db.index.unique\nrefNo: number.int\n```\n",
+		validate(token, args, doc) {
+			const field = token.parentNode;
+			const verdict = require_validation_utils.searchFieldVerdict(field, doc);
+			if ("problem" in verdict) return [{
+				message: `@db.index.fulltext needs a string or an integer field — "${field.id}" ${verdict.problem}`,
+				severity: 1,
+				range: token.range
+			}];
+			if (verdict.kind !== "integer") return [];
+			const errors = [];
+			const missing = require_validation_utils.integerMemberIndexProblem(token);
+			if (missing) errors.push({
+				message: missing,
+				severity: 1,
+				range: token.range
+			});
+			if (args[1]) errors.push({
+				message: "the weight is ignored on an integer member (it is matched by exact number, not by text)",
+				severity: 2,
+				range: args[1].range
+			});
+			return errors;
+		},
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		multiple: true,
@@ -1065,7 +1172,7 @@ const dbIndexAnnotations = { index: {
 			optional: true,
 			name: "weight",
 			type: "number",
-			description: "Field importance in search results (higher = more relevant). Defaults to `1`. Supported by databases with weighted fulltext (e.g., MongoDB, PostgreSQL)."
+			description: "Field importance in search results (higher = more relevant). Defaults to `1`. Supported by databases with weighted fulltext (e.g., MongoDB, PostgreSQL). Ignored on integer members."
 		}]
 	}),
 	geo: new _atscript_core.AnnotationSpec({
@@ -1110,7 +1217,7 @@ function checkCompositeFkCoverage(token, alias, refTypeName, targetStruct, targe
 }
 const dbRelAnnotations = { rel: {
 	FK: new _atscript_core.AnnotationSpec({
-		description: "Declares a foreign key reference on this field. The field must use a chain reference type (e.g., `User.id`) whose target is a primary key (`@meta.id`) or unique (`@db.index.unique`) field.\n\n**Dual role:**\n- On a `@db.table` interface, `@db.rel.FK` additionally drives DB-relation semantics —   relation loading with `@db.rel.to` / `@db.rel.from`, junction pairing with `@db.rel.via`, etc.\n- On any other interface (value-help sources, WF forms, plain interfaces), `@db.rel.FK`   acts purely as the value-help indicator: the client-side picker resolver uses it to   decide which fields render a value-help picker. The target's `@db.http.path` (stamped   by its readable controller) supplies the picker URL.\n- In `/meta` (and `/meta/form/:name`) the marker is inherited through reference chains:   a field declared as `code: Issue.code` where `Issue.code: Dict.code` carries `@db.rel.FK`   is served with `ref` pointing at the terminal field (`Dict.code`) and `db.rel.FK: true`,   so view fields get the dictionary picker. Runtime metadata is untouched.\n\n**Example:**\n```atscript\n@db.rel.FK\nauthorId: User.id\n\n// With alias (required when multiple FKs point to the same type)\n@db.rel.FK \"author\"\nauthorId: User.id\n```\n",
+		description: "Declares a foreign key reference on this field. The field must use a chain reference type (e.g., `User.id`) whose target is a primary key (`@meta.id`) or unique (`@db.index.unique`) field.\n\n**Dual role:**\n- On a `@db.table` interface, `@db.rel.FK` additionally drives DB-relation semantics —   relation loading with `@db.rel.to` / `@db.rel.from`, junction pairing with `@db.rel.via`, etc.\n- On any other interface (value-help sources, WF forms, plain interfaces), `@db.rel.FK`   acts purely as the value-help indicator: the client-side picker resolver uses it to   decide which fields render a value-help picker. The target's `@db.http.path` (published   by its canonical readable controller) supplies the picker URL.\n- In `/meta` (and `/meta/form/:name`) the marker is inherited through reference chains:   a field declared as `code: Issue.code` where `Issue.code: Dict.code` carries `@db.rel.FK`   is served with `ref` pointing at the terminal field (`Dict.code`) and `db.rel.FK: true`,   so view fields get the dictionary picker. Runtime metadata is untouched.\n\n**Example:**\n```atscript\n@db.rel.FK\nauthorId: User.id\n\n// With alias (required when multiple FKs point to the same type)\n@db.rel.FK \"author\"\nauthorId: User.id\n```\n",
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		argument: {
@@ -1702,7 +1809,7 @@ const dbTableAnnotations = {
 		}
 	}),
 	http: { path: new _atscript_core.AnnotationSpec({
-		description: "HTTP endpoint path where this table is served. Used by the UI for value-help on FK fields. Gets overwritten by the final controller prefix at runtime.\n\n**Example:**\n```atscript\n@db.table \"authors\"\n@db.http.path \"/authors\"\nexport interface Author { ... }\n```\n",
+		description: "HTTP endpoint path where this table is served. Used by the UI for value-help on FK fields. After app.init() the app publishes the canonical controller route here at runtime; a model mounted on several routes needs `canonical: true` on one of its controllers (or declare this annotation and mount that controller without an explicit prefix).\n\n**Example:**\n```atscript\n@db.table \"authors\"\n@db.http.path \"/authors\"\nexport interface Author { ... }\n```\n",
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		argument: {

package/dist/plugin.mjs

@@ -1,8 +1,7 @@
 import { i as NULL_WHEN_EMPTY_AGGREGATE_FNS, o as SUPPORTED_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-CyaZyb9I.mjs";
-import { n as DERIVED_INCOMPATIBLE, r as JSON_LEAF_TYPES, t as DB_ENTITY_ANNOTATIONS } from "./derived-rules-0sKn4f5C.mjs";
-import { t as numericTypeProblem } from "./numeric-operand-B1jKH7x5.mjs";
+import { a as DERIVED_INCOMPATIBLE, i as DB_ENTITY_ANNOTATIONS, o as JSON_LEAF_TYPES, r as numericTypeProblem } from "./search-fields-DBIZKwyb.mjs";
 import "./consts-C_-5_pFq.mjs";
-import { S as validateSiblingStringField, _ as getParentTypeName, a as hasAnyViewAnnotation, b as validateExclusiveWith, d as viewJoins, f as viewScopeTypes, g as getParentStruct, h as getNavTargetTypeName, i as forEachFieldRef, l as validateQueryScope, m as getDbTableOwner, n as findFKFieldsPointingTo, o as isAliasDecl, p as getAnnotationAlias, r as findViewCycle, s as isDbSourceDecl, t as earlierJoinTargets, u as validateRefArgument, v as primitiveBaseType, x as validateFieldBaseType, y as refActionAnnotation } from "./validation-utils-Dq0uZ7ef.mjs";
+import { C as validateFieldBaseType, S as validateExclusiveWith, _ as getParentTypeName, a as hasAnyViewAnnotation, b as refActionAnnotation, d as viewJoins, f as viewScopeTypes, g as getParentStruct, h as getNavTargetTypeName, i as forEachFieldRef, l as validateQueryScope, m as getDbTableOwner, n as findFKFieldsPointingTo, o as isAliasDecl, p as getAnnotationAlias, r as findViewCycle, s as isDbSourceDecl, t as earlierJoinTargets, u as validateRefArgument, v as integerMemberIndexProblem, w as validateSiblingStringField, x as searchFieldVerdict, y as primitiveBaseType } from "./validation-utils-DqZAH6aT.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { AnnotationSpec, DEFAULT_FORMAT, getFieldsForType, isArray, isInterface, isPrimitive, isProp, isQueryComparison, isQueryLogical, isRef, isStructure } from "@atscript/core";
@@ -516,6 +515,68 @@ function validateViewInterface(owner, doc) {
 }
 //#endregion
 //#region src/plugin/annotations/column.ts
+/** Nav-field annotations: a navigation field has no column on this table. */
+const NAV_ANNOTATIONS = [
+	"db.rel.to",
+	"db.rel.from",
+	"db.rel.via"
+];
+/**
+* Compile-time placement rules of `@db.column.version.exempt` (E1–E5, W1, W2).
+* E6 (derived) lives in `DERIVED_INCOMPATIBLE`. The runtime mirror is
+* `TableMetadata._finalizeVersionExempt`.
+* @since 0.1.150
+*/
+function validateVersionExempt(token) {
+	const errors = [];
+	const field = token.parentNode;
+	const fail = (message, severity = 1) => {
+		errors.push({
+			message,
+			severity,
+			range: token.range
+		});
+	};
+	const tag = "@db.column.version.exempt";
+	if (field.countAnnotations("db.column.version") > 0) fail(`${tag} cannot mark the version column itself`);
+	if (field.countAnnotations("meta.id") > 0) fail(`${tag} cannot mark a primary key — it identifies the row and is never patched`);
+	if (NAV_ANNOTATIONS.some((n) => field.countAnnotations(n) > 0)) fail(`${tag} cannot mark a navigation field — related rows follow their own table's versioning`);
+	if (field.countAnnotations("db.ignore") > 0) fail(`${tag} has no effect on an ignored field`, 2);
+	let node = field;
+	let tableOwner;
+	let reported = false;
+	while (node.ownerNode && isStructure(node.ownerNode)) {
+		let up = node.ownerNode.ownerNode;
+		let viaArray = false;
+		while (up && isArray(up)) {
+			viaArray = true;
+			up = up.ownerNode;
+		}
+		if (!up) break;
+		if (isInterface(up)) {
+			tableOwner = up;
+			break;
+		}
+		if (!isProp(up)) break;
+		if (!reported && viaArray) {
+			fail(`${tag} cannot sit inside an array — mark the array field '${up.id ?? ""}' itself; array elements are not separate columns`);
+			reported = true;
+		} else if (!reported && up.countAnnotations("db.json") > 0) {
+			fail(`${tag} cannot sit inside a @db.json field — mark the @db.json field '${up.id ?? ""}' itself; a JSON column is written as one value`);
+			reported = true;
+		}
+		node = up;
+	}
+	if (tableOwner && isInterface(tableOwner) && tableOwner.countAnnotations("db.table") > 0) {
+		const struct = tableOwner.getDefinition();
+		let hasVersion = false;
+		if (struct && isStructure(struct)) {
+			for (const [, prop] of struct.props) if (prop.countAnnotations("db.column.version") > 0) hasVersion = true;
+		}
+		if (!hasVersion) fail(`${tag} has no effect — table '${tableOwner.id ?? ""}' declares no @db.column.version`, 2);
+	}
+	return errors;
+}
 const dbColumnAnnotations = {
 	patch: { strategy: new AnnotationSpec({
 		description: "Defines the **patching strategy** for updating nested objects.\n\n- **\"replace\"** → The field or object will be **fully replaced**.\n- **\"merge\"** → The field or object will be **merged recursively** (applies only to objects, not arrays).\n\n**Example:**\n```atscript\n@db.patch.strategy \"merge\"\nsettings: {\n  notifications: boolean\n  preferences: {\n    theme: string\n  }\n}\n```\n",
@@ -678,38 +739,55 @@ const dbColumnAnnotations = {
 		filterable: columnCapability("filterable", "filtering"),
 		sortable: columnCapability("sortable", "sorting"),
 		searchable: new AnnotationSpec({
-			description: "Includes this column in the generic `$search` fallback: when the adapter reports no native search capability (no FTS / Atlas index configured), the readable controller matches the `$search` term as a case-insensitive substring across all `@db.column.searchable` fields (`$or`). Where adapter-native search IS available it wins and this annotation is not consulted. The term is escaped literally — no user-supplied regex. String-typed columns only.\n\n**Example:**\n```atscript\n@db.table \"jobs\"\nexport interface Job {\n  @db.column.searchable\n  jobName: string\n  @db.column.searchable\n  description: string\n}\n```\n",
+			description: "Includes this column in the generic `$search` fallback: when the adapter reports no native search capability (no FTS / Atlas index configured), the readable controller matches the `$search` term as a case-insensitive substring across all `@db.column.searchable` fields (`$or`). Where adapter-native search IS available it wins and this annotation is not consulted. The term is escaped literally — no user-supplied regex. String and integer columns only: an integer column (`number.int` and its sizes, `@expect.int`, `@db.default.increment`) matches when the term is a substring of the number's decimal text (`2946` finds `29461277`). Floats, decimals and timestamps are refused.\n\n**Example:**\n```atscript\n@db.table \"jobs\"\nexport interface Job {\n  @db.column.searchable\n  jobName: string\n  @db.column.searchable\n  description: string\n  @db.column.searchable\n  refNo: number.int\n}\n```\n",
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			multiple: false,
 			validate(token, _args, doc) {
-				return validateFieldBaseType(token, doc, "@db.column.searchable", ["string"]);
-			}
-		}),
-		version: new AnnotationSpec({
-			description: "Marks a numeric column as the row's version for optimistic concurrency control (OCC). The adapter auto-increments this column on every UPDATE, and callers may pass `$cas: { <col>: N }` in a write payload to make the update conditional on the current version. Direct writes to the version column (as plain SET, `$inc`, or `$mul`) are rejected.\n\n**Constraints:**\n- At most one version column per table.\n- Must resolve to an integer type (`int`, `int32`, `int64`, etc.).\n- Default value on insert is `0`.\n\n**Example:**\n```atscript\n@db.column.version\nversion: int\n```\n",
-			nodeType: ["prop"],
-			passedWhenReferred: false,
-			validate(token, _args, doc) {
-				const errors = validateFieldBaseType(token, doc, "@db.column.version", "number");
-				if (token.parentNode.has("optional")) errors.push({
-					message: "@db.column.version requires a non-optional field — version columns are always populated (default 0)",
+				const verdict = searchFieldVerdict(token.parentNode, doc);
+				if (!("problem" in verdict)) return [];
+				return [{
+					message: `@db.column.searchable needs a string or an integer field — "${token.parentNode.id}" ${verdict.problem}`,
 					severity: 1,
 					range: token.range
-				});
-				const struct = getParentStruct(token);
-				if (struct) {
-					let count = 0;
-					for (const [, prop] of struct.props) if (prop.countAnnotations("db.column.version") > 0) count++;
-					if (count > 1) errors.push({
-						message: "At most one @db.column.version per table",
+				}];
+			}
+		}),
+		version: {
+			$self: new AnnotationSpec({
+				description: "Marks a numeric column as the row's version for optimistic concurrency control (OCC). The adapter auto-increments this column on every UPDATE, and callers may pass `$cas: { <col>: N }` in a write payload to make the update conditional on the current version. Direct writes to the version column (as plain SET, `$inc`, or `$mul`) are rejected. Fields marked `@db.column.version.exempt` do not bump it.\n\n**Constraints:**\n- At most one version column per table.\n- Must resolve to an integer type (`int`, `int32`, `int64`, etc.).\n- Default value on insert is `0`.\n\n**Example:**\n```atscript\n@db.column.version\nversion: int\n```\n",
+				nodeType: ["prop"],
+				passedWhenReferred: false,
+				validate(token, _args, doc) {
+					const errors = validateFieldBaseType(token, doc, "@db.column.version", "number");
+					if (token.parentNode.has("optional")) errors.push({
+						message: "@db.column.version requires a non-optional field — version columns are always populated (default 0)",
 						severity: 1,
 						range: token.range
 					});
+					const struct = getParentStruct(token);
+					if (struct) {
+						let count = 0;
+						for (const [, prop] of struct.props) if (prop.countAnnotations("db.column.version") > 0) count++;
+						if (count > 1) errors.push({
+							message: "At most one @db.column.version per table",
+							severity: 1,
+							range: token.range
+						});
+					}
+					return errors;
 				}
-				return errors;
-			}
-		})
+			}),
+			exempt: new AnnotationSpec({
+				description: "Marks a field as **version-exempt**: a patch that writes ONLY exempt fields (`updateOne` / `bulkUpdate` without `$cas`, `updateMany`) leaves `@db.column.version` unchanged and adds no version check. A patch touching any other field bumps as usual; `$cas`, replace and `touchMany` always bump. Use it for derived/reporting columns refreshed in the background (scores, counters, caches) so they do not invalidate versions held by editors. On an object field it covers every nested field.\n\n**Example:**\n```atscript\n@db.column.version\nversion: number.int\n@db.column.version.exempt\nscore: number\n```\n",
+				nodeType: ["prop"],
+				passedWhenReferred: false,
+				multiple: false,
+				validate(token) {
+					return validateVersionExempt(token);
+				}
+			})
+		}
 	},
 	default: {
 		$self: new AnnotationSpec({
@@ -822,17 +900,23 @@ const dbColumnAnnotations = {
 		}
 	}),
 	writeOnly: new AnnotationSpec({
-		description: "Marks a field as write-only over HTTP: it may be set through insert/update/replace payloads but NEVER appears in read responses — the readable controller excludes it from every projection, rejects filtering/sorting/grouping on it, and `/meta` serves its TYPE (flagged `writeOnly`) so client preflight validation and generated forms still know its shape. The classic case is a sealed secret (pair with `@db.encrypted`): writable via generic forms, unreadable by anyone.\n\nServer-side code reading through `AtscriptDbTable` still sees the value — the seal is an HTTP-layer contract, not a storage one.\n\n**Example:**\n```atscript\n@db.writeOnly\n@db.encrypted\ncredentials?: string\n```\n",
+		description: "Marks a field as write-only over HTTP: it may be set through insert/update/replace payloads but NEVER appears in read responses — the readable controller excludes it from every projection, rejects filtering/sorting/grouping on it, and `/meta` serves its TYPE (flagged `writeOnly`) so client preflight validation and generated forms still know its shape. The classic case is a sealed secret (pair with `@db.encrypted`): writable via generic forms, unreadable by anyone.\n\nServer-side code reading through `AtscriptDbTable` still sees the value — the seal is an HTTP-layer contract, not a storage one. It cannot be combined with `@db.index.fulltext` or `@db.column.searchable`: a search hit would reveal the sealed value.\n\n**Example:**\n```atscript\n@db.writeOnly\n@db.encrypted\ncredentials?: string\n```\n",
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		multiple: false,
 		validate(token, _args, _doc) {
 			const errors = [];
-			if (token.parentNode.countAnnotations("meta.id") > 0) errors.push({
+			const field = token.parentNode;
+			if (field.countAnnotations("meta.id") > 0) errors.push({
 				message: `@db.writeOnly cannot coexist with @meta.id — the primary key must be readable`,
 				severity: 1,
 				range: token.range
 			});
+			for (const name of ["db.index.fulltext", "db.column.searchable"]) if (field.countAnnotations(name) > 0) errors.push({
+				message: `@db.writeOnly cannot coexist with @${name} — search results would reveal the sealed value`,
+				severity: 1,
+				range: token.range
+			});
 			return errors;
 		}
 	})
@@ -1015,7 +1099,30 @@ const dbIndexAnnotations = { index: {
 		}
 	}),
 	fulltext: new AnnotationSpec({
-		description: "Full-text search index. Fields sharing the same index name form a composite full-text index.\n\n**Example:**\n```atscript\n@db.index.fulltext \"ft_content\"\ntitle: string\n\n@db.index.fulltext \"ft_content\", 5\nbio: string\n```\n",
+		description: "Full-text search index. Fields sharing the same index name form a composite full-text index. A string member is part of the engine's text index. An integer member (`number.int` and its sizes, `@expect.int`, `@db.default.increment`) is never part of the physical text index: when the whole search term is a whole number (`2946`, `-12`; no leading zeros), rows whose member equals it exactly also match (OR'd with the text match). An integer member must be index-backed — the primary key (first `@meta.id`) or the first field of a `@db.index.plain` / `@db.index.unique`. Floats, decimals and timestamps are refused.\n\n**Example:**\n```atscript\n@db.index.fulltext \"ft_content\"\ntitle: string\n\n@db.index.fulltext \"ft_content\", 5\nbio: string\n\n@db.index.fulltext \"ft_content\"\n@db.index.unique\nrefNo: number.int\n```\n",
+		validate(token, args, doc) {
+			const field = token.parentNode;
+			const verdict = searchFieldVerdict(field, doc);
+			if ("problem" in verdict) return [{
+				message: `@db.index.fulltext needs a string or an integer field — "${field.id}" ${verdict.problem}`,
+				severity: 1,
+				range: token.range
+			}];
+			if (verdict.kind !== "integer") return [];
+			const errors = [];
+			const missing = integerMemberIndexProblem(token);
+			if (missing) errors.push({
+				message: missing,
+				severity: 1,
+				range: token.range
+			});
+			if (args[1]) errors.push({
+				message: "the weight is ignored on an integer member (it is matched by exact number, not by text)",
+				severity: 2,
+				range: args[1].range
+			});
+			return errors;
+		},
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		multiple: true,
@@ -1029,7 +1136,7 @@ const dbIndexAnnotations = { index: {
 			optional: true,
 			name: "weight",
 			type: "number",
-			description: "Field importance in search results (higher = more relevant). Defaults to `1`. Supported by databases with weighted fulltext (e.g., MongoDB, PostgreSQL)."
+			description: "Field importance in search results (higher = more relevant). Defaults to `1`. Supported by databases with weighted fulltext (e.g., MongoDB, PostgreSQL). Ignored on integer members."
 		}]
 	}),
 	geo: new AnnotationSpec({
@@ -1074,7 +1181,7 @@ function checkCompositeFkCoverage(token, alias, refTypeName, targetStruct, targe
 }
 const dbRelAnnotations = { rel: {
 	FK: new AnnotationSpec({
-		description: "Declares a foreign key reference on this field. The field must use a chain reference type (e.g., `User.id`) whose target is a primary key (`@meta.id`) or unique (`@db.index.unique`) field.\n\n**Dual role:**\n- On a `@db.table` interface, `@db.rel.FK` additionally drives DB-relation semantics —   relation loading with `@db.rel.to` / `@db.rel.from`, junction pairing with `@db.rel.via`, etc.\n- On any other interface (value-help sources, WF forms, plain interfaces), `@db.rel.FK`   acts purely as the value-help indicator: the client-side picker resolver uses it to   decide which fields render a value-help picker. The target's `@db.http.path` (stamped   by its readable controller) supplies the picker URL.\n- In `/meta` (and `/meta/form/:name`) the marker is inherited through reference chains:   a field declared as `code: Issue.code` where `Issue.code: Dict.code` carries `@db.rel.FK`   is served with `ref` pointing at the terminal field (`Dict.code`) and `db.rel.FK: true`,   so view fields get the dictionary picker. Runtime metadata is untouched.\n\n**Example:**\n```atscript\n@db.rel.FK\nauthorId: User.id\n\n// With alias (required when multiple FKs point to the same type)\n@db.rel.FK \"author\"\nauthorId: User.id\n```\n",
+		description: "Declares a foreign key reference on this field. The field must use a chain reference type (e.g., `User.id`) whose target is a primary key (`@meta.id`) or unique (`@db.index.unique`) field.\n\n**Dual role:**\n- On a `@db.table` interface, `@db.rel.FK` additionally drives DB-relation semantics —   relation loading with `@db.rel.to` / `@db.rel.from`, junction pairing with `@db.rel.via`, etc.\n- On any other interface (value-help sources, WF forms, plain interfaces), `@db.rel.FK`   acts purely as the value-help indicator: the client-side picker resolver uses it to   decide which fields render a value-help picker. The target's `@db.http.path` (published   by its canonical readable controller) supplies the picker URL.\n- In `/meta` (and `/meta/form/:name`) the marker is inherited through reference chains:   a field declared as `code: Issue.code` where `Issue.code: Dict.code` carries `@db.rel.FK`   is served with `ref` pointing at the terminal field (`Dict.code`) and `db.rel.FK: true`,   so view fields get the dictionary picker. Runtime metadata is untouched.\n\n**Example:**\n```atscript\n@db.rel.FK\nauthorId: User.id\n\n// With alias (required when multiple FKs point to the same type)\n@db.rel.FK \"author\"\nauthorId: User.id\n```\n",
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		argument: {
@@ -1666,7 +1773,7 @@ const dbTableAnnotations = {
 		}
 	}),
 	http: { path: new AnnotationSpec({
-		description: "HTTP endpoint path where this table is served. Used by the UI for value-help on FK fields. Gets overwritten by the final controller prefix at runtime.\n\n**Example:**\n```atscript\n@db.table \"authors\"\n@db.http.path \"/authors\"\nexport interface Author { ... }\n```\n",
+		description: "HTTP endpoint path where this table is served. Used by the UI for value-help on FK fields. After app.init() the app publishes the canonical controller route here at runtime; a model mounted on several routes needs `canonical: true` on one of its controllers (or declare this annotation and mount that controller without an explicit prefix).\n\n**Example:**\n```atscript\n@db.table \"authors\"\n@db.http.path \"/authors\"\nexport interface Author { ... }\n```\n",
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		argument: {

package/dist/rel.d.cts

@@ -1,6 +1,6 @@
-import { Jt as BaseDbAdapter, Nt as TTableResolver, Rt as TWriteTableResolver, U as TDbForeignKey, Ut as TableMetadata, Vn as TGenericLogger, et as TDbRelation, h as AtscriptDbWritable, m as AtscriptDbTableLike } from "./buckets-DJiYlMXc.cjs";
+import { Hn as TGenericLogger, Pt as TTableResolver, U as TDbForeignKey, Wt as TableMetadata, Yt as BaseDbAdapter, et as TDbRelation, h as AtscriptDbWritable, m as AtscriptDbTableLike, zt as TWriteTableResolver } from "./buckets-24Ac4sIS.cjs";
 import { t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
-import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-kX7jjgME.cjs";
+import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-DjVJN2ng.cjs";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 import { Validator } from "@atscript/typescript/utils";
 

package/dist/rel.d.mts

@@ -1,6 +1,6 @@
-import { Jt as BaseDbAdapter, Nt as TTableResolver, Rt as TWriteTableResolver, U as TDbForeignKey, Ut as TableMetadata, Vn as TGenericLogger, et as TDbRelation, h as AtscriptDbWritable, m as AtscriptDbTableLike } from "./buckets-CNdTOnei.mjs";
+import { Hn as TGenericLogger, Pt as TTableResolver, U as TDbForeignKey, Wt as TableMetadata, Yt as BaseDbAdapter, et as TDbRelation, h as AtscriptDbWritable, m as AtscriptDbTableLike, zt as TWriteTableResolver } from "./buckets-XOz0Bw5x.mjs";
 import { t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
-import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-Ba0v49sn.mjs";
+import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-H7UEVkHs.mjs";
 import { Validator } from "@atscript/typescript/utils";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 

package/dist/{relation-helpers-kX7jjgME.d.cts → relation-helpers-DjVJN2ng.d.cts}

@@ -1,4 +1,4 @@
-import { U as TDbForeignKey, et as TDbRelation } from "./buckets-DJiYlMXc.cjs";
+import { U as TDbForeignKey, et as TDbRelation } from "./buckets-24Ac4sIS.cjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/rel/relation-helpers.d.ts

package/dist/{relation-helpers-Ba0v49sn.d.mts → relation-helpers-H7UEVkHs.d.mts}

@@ -1,4 +1,4 @@
-import { U as TDbForeignKey, et as TDbRelation } from "./buckets-CNdTOnei.mjs";
+import { U as TDbForeignKey, et as TDbRelation } from "./buckets-XOz0Bw5x.mjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/rel/relation-helpers.d.ts