@atscript/db 0.1.161 → 0.1.163

package/dist/plugin.cjs

@@ -33,14 +33,14 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_aggregate_fns = require("./aggregate-fns-DFtKAv7Q.cjs");
-const require_search_fields = require("./search-fields-CT_UZ9fg.cjs");
+const require_aggregate_fns = require("./aggregate-fns-DupYzFD7.cjs");
+const require_search_fields = require("./search-fields-B49-RCWd.cjs");
 require("./consts-BzRfCcH2.cjs");
-const require_validation_utils = require("./validation-utils-CtLNlBtB.cjs");
+const require_view_validation = require("./view-validation-BiDLCYMw.cjs");
+let _atscript_core = require("@atscript/core");
 let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
 let node_url = require("node:url");
-let _atscript_core = require("@atscript/core");
 //#region src/plugin/manifest.ts
 /**
 * Renders the model-manifest module: an inventory of every exported
@@ -70,7 +70,7 @@ async function generateModelManifest(options, output, format, repo) {
 		let specifier = node_path.default.relative(manifestDir, docPath).split(node_path.default.sep).join("/");
 		if (!specifier.startsWith(".")) specifier = `./${specifier}`;
 		for (const [exportName, node] of [...doc.exports.entries()].toSorted(([a], [b]) => a.localeCompare(b))) {
-			if (!require_validation_utils.isDbSourceDecl(node)) continue;
+			if (!require_view_validation.isDbSourceDecl(node)) continue;
 			let alias = exportName;
 			for (let n = 1; usedAliases.has(alias); n++) alias = `${exportName}_${n}`;
 			usedAliases.add(alias);
@@ -79,7 +79,7 @@ async function generateModelManifest(options, output, format, repo) {
 				exportName,
 				specifier,
 				isView: node.countAnnotations("db.view") > 0 || node.countAnnotations("db.view.for") > 0,
-				space: require_validation_utils.getAnnotationAlias(node, "db.space") || "default"
+				space: require_view_validation.getAnnotationAlias(node, "db.space") || "default"
 			});
 		}
 	}
@@ -134,7 +134,7 @@ async function generateModelManifest(options, output, format, repo) {
 */
 /** The `@db.view.for` entry name of a view node. */
 function viewEntry(view) {
-	return require_validation_utils.getAnnotationAlias(view, "db.view.for");
+	return require_view_validation.getAnnotationAlias(view, "db.view.for");
 }
 /**
 * `@db.view.filter` — and a conditional `@db.agg.*` of the same view: the
@@ -144,7 +144,7 @@ function viewEntry(view) {
 function viewFilterScope(view) {
 	const entry = viewEntry(view);
 	return entry ? {
-		allowedTypes: require_validation_utils.viewScopeTypes(view),
+		allowedTypes: require_view_validation.viewScopeTypes(view),
 		unqualifiedTarget: entry
 	} : void 0;
 }
@@ -154,7 +154,7 @@ function viewFilterScope(view) {
 * view's {@link viewJoins} when the caller has not); an unqualified field
 * belongs to the entry.
 */
-function viewJoinScope(view, join, earlier = require_validation_utils.earlierJoinTargets(require_validation_utils.viewJoins(view), join)) {
+function viewJoinScope(view, join, earlier = require_view_validation.earlierJoinTargets(require_view_validation.viewJoins(view), join)) {
 	const entry = viewEntry(view);
 	const target = join.args[0]?.text;
 	if (!entry || !target) return;
@@ -192,12 +192,12 @@ function joinOrderScope(join) {
 * @since 0.1.147
 */
 function computeScope(propToken) {
-	const view = require_validation_utils.getDbTableOwner(propToken);
+	const view = require_view_validation.getDbTableOwner(propToken);
 	return view ? viewHavingScope(view) : void 0;
 }
 /** The condition of a `@db.agg.*` on a view field: the scope of the view's `@db.view.filter`. */
 function aggConditionScope(propToken) {
-	const view = require_validation_utils.getDbTableOwner(propToken);
+	const view = require_view_validation.getDbTableOwner(propToken);
 	return view ? viewFilterScope(view) : void 0;
 }
 /**
@@ -208,7 +208,7 @@ function aggConditionScope(propToken) {
 function aggFieldScope(propToken) {
 	const def = propToken.parentNode?.getDefinition();
 	const refType = def && (0, _atscript_core.isRef)(def) && def.hasChain ? def.id : void 0;
-	const view = refType ? void 0 : require_validation_utils.getDbTableOwner(propToken);
+	const view = refType ? void 0 : require_view_validation.getDbTableOwner(propToken);
 	const target = refType ?? (view ? viewEntry(view) : void 0);
 	return target ? {
 		allowedTypes: [],
@@ -221,9 +221,9 @@ function aggFieldScope(propToken) {
 * unqualified field belongs to the related type.
 */
 function relFilterScope(field) {
-	const target = require_validation_utils.getNavTargetTypeName(field);
+	const target = require_view_validation.getNavTargetTypeName(field);
 	if (!target) return;
-	const junction = require_validation_utils.getAnnotationAlias(field, "db.rel.via");
+	const junction = require_view_validation.getAnnotationAlias(field, "db.rel.via");
 	return {
 		allowedTypes: junction ? [target, junction] : [target],
 		unqualifiedTarget: target
@@ -238,12 +238,12 @@ const fieldScopes = {
 	viewFilter: (arg) => arg.parentNode ? viewFilterScope(arg.parentNode) : void 0,
 	viewJoin: (arg) => {
 		const view = arg.parentNode;
-		const joins = view ? require_validation_utils.viewJoins(view) : [];
+		const joins = view ? require_view_validation.viewJoins(view) : [];
 		const join = joinOfArg(joins, arg);
-		return view && join ? viewJoinScope(view, join, require_validation_utils.earlierJoinTargets(joins, join)) : void 0;
+		return view && join ? viewJoinScope(view, join, require_view_validation.earlierJoinTargets(joins, join)) : void 0;
 	},
 	joinOrder: (arg) => {
-		const join = arg.parentNode ? joinOfArg(require_validation_utils.viewJoins(arg.parentNode), arg) : void 0;
+		const join = arg.parentNode ? joinOfArg(require_view_validation.viewJoins(arg.parentNode), arg) : void 0;
 		return join ? joinOrderScope(join) : void 0;
 	},
 	viewHaving: (arg) => arg.parentNode ? viewHavingScope(arg.parentNode) : void 0,
@@ -254,7 +254,7 @@ const fieldScopes = {
 };
 /** `refFilter` of the `@db.view.joins` target: a view source or a `@db.alias` of one. */
 function isJoinTarget(decl) {
-	return require_validation_utils.isDbSourceDecl(decl) || require_validation_utils.isAliasDecl(decl);
+	return require_view_validation.isDbSourceDecl(decl) || require_view_validation.isAliasDecl(decl);
 }
 /** `refFilter` of `@db.rel.via`: a `@db.table`. */
 function isDbTable(decl) {
@@ -303,7 +303,7 @@ function validateAggArgs(name, token, args, doc) {
 		});
 		return errors;
 	}
-	errors.push(...require_validation_utils.validateQueryScope(condition, scope, doc));
+	errors.push(...require_view_validation.validateQueryScope(condition, scope, doc));
 	const prop = token.parentNode;
 	if (conditionalIsNullable(name) && prop && !prop.has("optional")) {
 		const field = prop.id ?? "field";
@@ -340,7 +340,7 @@ function aggSpec(name, description, field, types, extra = "") {
 		}, CONDITION_ARG],
 		validate(token, args, doc) {
 			const errors = validateAggArgs(name, token, args, doc);
-			if (types) errors.push(...require_validation_utils.validateFieldBaseType(token, doc, `@db.agg.${name}`, types));
+			if (types) errors.push(...require_view_validation.validateFieldBaseType(token, doc, `@db.agg.${name}`, types));
 			return errors;
 		}
 	});
@@ -360,7 +360,7 @@ const dbAggAnnotations = { agg: {
 //#region src/plugin/annotations/alias.ts
 /** The `accept` rule of a view-source ref argument (`@db.view.for`, `@db.alias`). */
 const VIEW_SOURCE_ARGUMENT = {
-	accept: require_validation_utils.isDbSourceDecl,
+	accept: require_view_validation.isDbSourceDecl,
 	expected: "must be a @db.table or a @db.view."
 };
 /**
@@ -369,14 +369,14 @@ const VIEW_SOURCE_ARGUMENT = {
 * @since 0.1.141
 */
 const dbAliasAnnotations = { alias: new _atscript_core.AnnotationSpec({
-	description: "Declares a **join alias**: a type alias of a `@db.table` or `@db.view` that a view can join under its own name — to join the same table twice or to self-join the entry table. Only valid on `export type X = Target`, where `Target` is the argument. The alias is a scope name inside view definitions, not a table: it is never synced or registered on a `DbSpace`, and it cannot be the `@db.view.for` entry.\n\n**Example:**\n```atscript\n@db.alias Employee\nexport type Manager = Employee\n\n@db.view.for Employee\n@db.view.joins Manager, `Manager.id = Employee.managerId`, 'left'\nexport interface Staff {\n    id: Employee.id\n    managerName?: Manager.name\n}\n```\n",
+	description: (0, _atscript_core.annotationExample)("Declares a **join alias**: a type alias of a `@db.table` or `@db.view` that a view can join under its own name — to join the same table twice or to self-join the entry table. Only valid on `export type X = Target`, where `Target` is the argument. The alias is a scope name inside view definitions, not a table: it is never synced or registered on a `DbSpace`, and it cannot be the `@db.view.for` entry.", "@db.alias Employee", "export type Manager = Employee", "", "@db.view.for Employee", "@db.view.joins Manager, `Manager.id = Employee.managerId`, 'left'", "export interface Staff {", "    id: Employee.id", "    managerName?: Manager.name", "}"),
 	nodeType: ["type"],
 	passedWhenReferred: false,
 	argument: {
 		name: "target",
 		type: "ref",
 		description: "The aliased table or view type (must have @db.table or @db.view).",
-		refFilter: require_validation_utils.isDbSourceDecl
+		refFilter: require_view_validation.isDbSourceDecl
 	},
 	validate(token, args, doc) {
 		const errors = [];
@@ -397,7 +397,7 @@ const dbAliasAnnotations = { alias: new _atscript_core.AnnotationSpec({
 			severity: 1,
 			range: token.range
 		});
-		errors.push(...require_validation_utils.validateRefArgument(args[0], doc, VIEW_SOURCE_ARGUMENT));
+		errors.push(...require_view_validation.validateRefArgument(args[0], doc, VIEW_SOURCE_ARGUMENT));
 		return errors;
 	}
 }) };
@@ -406,7 +406,7 @@ const dbAliasAnnotations = { alias: new _atscript_core.AnnotationSpec({
 const CURRENCY_CODE_PATTERN = /^[A-Z0-9]{2,10}$/;
 const dbAmountAnnotations = { amount: { currency: {
 	$self: new _atscript_core.AnnotationSpec({
-		description: "Hard-coded **currency code** for this amount field. Use when a table stores amounts in a single, fixed currency.\n\nFor per-row currency, use `@db.amount.currency.ref 'fieldName'` instead.\n\nOnly valid on `decimal` fields — money in floating-point is wrong.\n\n**Example:**\n```atscript\n@db.amount.currency 'EUR'\namount: decimal\n```\n",
+		description: (0, _atscript_core.annotationExample)("Hard-coded **currency code** for this amount field. Use when a table stores amounts in a single, fixed currency.\n\nFor per-row currency, use `@db.amount.currency.ref 'fieldName'` instead.\n\nOnly valid on `decimal` fields — money in floating-point is wrong.", "@db.amount.currency 'EUR'", "amount: decimal"),
 		nodeType: ["prop"],
 		multiple: false,
 		argument: {
@@ -416,11 +416,11 @@ const dbAmountAnnotations = { amount: { currency: {
 		},
 		validate(token, args, doc) {
 			const errors = [];
-			errors.push(...require_validation_utils.validateFieldBaseType(token, doc, "@db.amount.currency", "decimal"));
-			errors.push(...require_validation_utils.validateExclusiveWith(token, "@db.amount.currency", [{
+			errors.push(...require_view_validation.validateFieldBaseType(token, doc, "@db.amount.currency", "decimal"));
+			errors.push(...require_view_validation.validateExclusiveWith(token, "@db.amount.currency", [{
 				key: "db.amount.currency.ref",
 				displayName: "@db.amount.currency.ref"
-			}]));
+			}], doc));
 			const code = args[0]?.text;
 			if (code && !CURRENCY_CODE_PATTERN.test(code)) errors.push({
 				message: `@db.amount.currency '${code}': invalid currency code (expected 2–10 uppercase letters or digits)`,
@@ -431,7 +431,7 @@ const dbAmountAnnotations = { amount: { currency: {
 		}
 	}),
 	ref: new _atscript_core.AnnotationSpec({
-		description: "Binds this amount to a **sibling field** that holds its currency code. Use when each row may have a different currency.\n\nThe referenced field should be of type `db.currencyCode` (or at least a `string`).\n\nOnly valid on `decimal` fields.\n\n**Example:**\n```atscript\ncurrency: db.currencyCode\n@db.amount.currency.ref 'currency'\namount: decimal\n```\n",
+		description: (0, _atscript_core.annotationExample)("Binds this amount to a **sibling field** that holds its currency code. Use when each row may have a different currency.\n\nThe referenced field should be of type `db.currencyCode` (or at least a `string`).\n\nOnly valid on `decimal` fields.", "currency: db.currencyCode", "@db.amount.currency.ref 'currency'", "amount: decimal"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		multiple: false,
@@ -442,121 +442,21 @@ const dbAmountAnnotations = { amount: { currency: {
 		},
 		validate(token, args, doc) {
 			const errors = [];
-			errors.push(...require_validation_utils.validateFieldBaseType(token, doc, "@db.amount.currency.ref", "decimal"));
-			errors.push(...require_validation_utils.validateExclusiveWith(token, "@db.amount.currency.ref", [{
+			errors.push(...require_view_validation.validateFieldBaseType(token, doc, "@db.amount.currency.ref", "decimal"));
+			errors.push(...require_view_validation.validateExclusiveWith(token, "@db.amount.currency.ref", [{
 				key: "db.amount.currency",
 				displayName: "@db.amount.currency"
 			}, {
 				key: "db.unit.ref",
 				displayName: "@db.unit.ref"
-			}]));
-			errors.push(...require_validation_utils.validateSiblingStringField(token, args, doc, "@db.amount.currency.ref"));
+			}], doc));
+			errors.push(...require_view_validation.validateSiblingStringField(token, args, doc, "@db.amount.currency.ref"));
 			return errors;
 		}
 	})
 } } };
 //#endregion
-//#region src/shared/view-validation.ts
-/** `@db.agg.*` annotations that are never NULL (the counts: 0 over no value). */
-const NULL_SAFE_AGG_ANNOTATIONS = require_aggregate_fns.SUPPORTED_AGGREGATE_FNS.filter((fn) => !require_aggregate_fns.NULL_WHEN_EMPTY_AGGREGATE_FNS.has(fn)).map((fn) => `db.agg.${fn}`);
-/**
-* Walks a chain ref step by step (`Order.payload`, `Order.payload.customer`, …)
-* and reports the JSON root, arrays, encryption, optionality and the leaf type.
-* A chain shorter than 2 is not a field path (`resolved: false`).
-* @since 0.1.141
-*/
-function jsonChainInfo(ref, doc) {
-	const typeName = ref.id ?? "";
-	const chain = ref.chain.map((t) => t.text);
-	const info = {
-		typeName,
-		chain,
-		resolved: false,
-		viaArray: false,
-		viaEncrypted: false,
-		optional: false
-	};
-	if (!typeName || chain.length < 2) return info;
-	for (let i = 1; i <= chain.length; i++) {
-		const step = doc.unwindType(typeName, chain.slice(0, i));
-		if (!step) return info;
-		const node = step.node;
-		const prop = node && (0, _atscript_core.isProp)(node) ? node : void 0;
-		if (prop?.has("optional")) info.optional = true;
-		if (prop && prop.countAnnotations("db.encrypted") > 0) info.viaEncrypted = true;
-		const isJsonProp = prop !== void 0 && prop.countAnnotations("db.json") > 0;
-		const isArr = (0, _atscript_core.isArray)(step.def);
-		if (isArr) info.viaArray = true;
-		if (info.jsonRoot === void 0 && (isJsonProp || isArr)) info.jsonRoot = i;
-		if (i === chain.length) info.leafType = require_validation_utils.primitiveBaseType(step.def);
-	}
-	info.resolved = true;
-	return info;
-}
-/** Props of a view interface (its own structure; views don't use `extends`). */
-function viewProps(owner) {
-	if ((0, _atscript_core.isInterface)(owner)) return owner.props;
-	const def = owner.getDefinition();
-	return def && (0, _atscript_core.isStructure)(def) ? def.props : void 0;
-}
-/**
-* VW8: a chain ref that passes through a `@db.json` or array node reads a
-* JSON leaf, which views can only extract as a string / number / boolean.
-* Intermediate nodes that `unwindType` can't reach are skipped (sync-time
-* resolution reports them).
-*/
-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_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,
-		range
-	}];
-}
-/**
-* Whole-view checks, run once per `@db.view.for` interface:
-*
-* - VW7 — a field reading from a left-joined table must be optional (the
-*   join yields NULL for unmatched rows); `@db.agg.count` / `countDistinct`
-*   fields are exempt (they count 0, never NULL).
-* - VW8 — a chain ref through a `@db.json` or array node must end at a
-*   primitive string / number / boolean leaf.
-* @since 0.1.136
-*/
-function validateViewInterface(owner, doc) {
-	const errors = [];
-	const props = viewProps(owner);
-	if (!props) return errors;
-	const leftJoined = /* @__PURE__ */ new Set();
-	for (const join of require_validation_utils.viewJoins(owner)) {
-		const target = join.args[0]?.text;
-		if (target && join.args[2]?.text === "left") leftJoined.add(target);
-	}
-	for (const [fieldName, prop] of props) {
-		const def = prop.getDefinition();
-		if (!def || !(0, _atscript_core.isRef)(def)) continue;
-		const ref = def;
-		const range = (prop.token("identifier") ?? ref.token("identifier"))?.range;
-		if (!range) continue;
-		if (ref.id && leftJoined.has(ref.id) && !prop.has("optional") && !NULL_SAFE_AGG_ANNOTATIONS.some((name) => prop.countAnnotations(name) > 0)) errors.push({
-			message: `Field "${fieldName}" reads from left-joined "${ref.id}" and must be optional (${fieldName}?: …)`,
-			severity: 1,
-			range
-		});
-		errors.push(...validateJsonChain(fieldName, ref, doc, range));
-	}
-	return errors;
-}
-//#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
@@ -576,7 +476,7 @@ function validateVersionExempt(token) {
 	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 (require_view_validation.isNavProp(field)) 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;
@@ -613,9 +513,51 @@ function validateVersionExempt(token) {
 	}
 	return errors;
 }
+/** Annotations a `@db.onUpdate.inc` field cannot carry, with the reason. */
+const ON_UPDATE_INC_INCOMPATIBLE = [
+	["meta.id", "the primary key identifies the row and is never updated"],
+	["db.column.version", "the version column is already bumped on every update"],
+	["db.onUpdate.now", "a field is either a time stamp or a counter"],
+	["db.default", "the counter starts at 0"],
+	["db.default.increment", "the counter starts at 0"],
+	["db.default.uuid", "the counter starts at 0"],
+	["db.default.now", "the counter starts at 0"],
+	["db.json", "a JSON column is written as one value"]
+];
+/**
+* Compile-time rules of `@db.onUpdate.inc` (since 0.1.162). The runtime
+* mirror (top level, encryption) is in `TableMetadata`.
+*/
+function validateOnUpdateInc(token, doc) {
+	const tag = "@db.onUpdate.inc";
+	const errors = require_view_validation.validateFieldBaseType(token, doc, tag, "number");
+	const field = token.parentNode;
+	const fail = (message) => {
+		errors.push({
+			message,
+			severity: 1,
+			range: token.range
+		});
+	};
+	if (errors.length === 0 && !isIntegerField(field, doc)) fail(`${tag} requires an integer field — use number.int (or @expect.int)`);
+	if (field.has("optional")) fail(`${tag} requires a non-optional field — the counter is always populated (default 0)`);
+	const struct = require_view_validation.getParentStruct(token);
+	if (!struct?.ownerNode || !(0, _atscript_core.isInterface)(struct.ownerNode)) fail(`${tag} must sit on a top-level field of the table, not inside a nested object`);
+	errors.push(...require_view_validation.validateIncompatible(token, tag, ON_UPDATE_INC_INCOMPATIBLE, doc));
+	return errors;
+}
+/** Whether a numeric field is an integer: `number.int`, an `integer` base or `@expect.int`. */
+function isIntegerField(field, doc) {
+	const def = field.getDefinition();
+	if (!def || !(0, _atscript_core.isRef)(def)) return true;
+	const leaf = doc.unwindType(def.id, def.chain)?.def;
+	if (require_view_validation.primitiveBaseType(leaf) !== "number") return true;
+	if (leaf.tags?.has("int")) return true;
+	return require_view_validation.effectiveAnnotationNames(field, doc).has("expect.int");
+}
 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",
+		description: (0, _atscript_core.annotationExample)("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).", "@db.patch.strategy \"merge\"", "settings: {", "  notifications: boolean", "  preferences: {", "    theme: string", "  }", "}"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		multiple: false,
@@ -645,7 +587,7 @@ const dbColumnAnnotations = {
 	}) },
 	column: {
 		$self: new _atscript_core.AnnotationSpec({
-			description: "Overrides the physical column name in the database. For nested (flattened) fields, the parent prefix is still prepended automatically. Document storage (MongoDB) renames top-level fields only — a nested field keeps its name there.\n\n**Example:**\n```atscript\n@db.column \"first_name\"\nfirstName: string\n// → physical column: first_name\n\n// Nested:\naddress: {\n  @db.column \"zip_code\"\n  zip: string\n}\n// → physical column: address__zip_code\n```\n",
+			description: (0, _atscript_core.annotationExample)("Overrides the physical column name in the database. For nested (flattened) fields, the parent prefix is still prepended automatically. Document storage (MongoDB) renames top-level fields only — a nested field keeps its name there.", "@db.column \"first_name\"", "firstName: string", "// → physical column: first_name", "", "// Nested:", "address: {", "  @db.column \"zip_code\"", "  zip: string", "}", "// → physical column: address__zip_code"),
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			argument: {
@@ -655,7 +597,7 @@ const dbColumnAnnotations = {
 			}
 		}),
 		renamed: new _atscript_core.AnnotationSpec({
-			description: "Specifies the previous local field name for column rename migration. The sync engine generates ALTER TABLE RENAME COLUMN instead of drop+add (on document storage, top-level fields only).\n\n**Example:**\n```atscript\n@db.column.renamed \"zip\"\npostalCode: string\n// Renames address__zip → address__postalCode\n```\n",
+			description: (0, _atscript_core.annotationExample)("Specifies the previous local field name for column rename migration. The sync engine generates ALTER TABLE RENAME COLUMN instead of drop+add (on document storage, top-level fields only).", "@db.column.renamed \"zip\"", "postalCode: string", "// Renames address__zip → address__postalCode"),
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			argument: {
@@ -665,7 +607,7 @@ const dbColumnAnnotations = {
 			}
 		}),
 		collate: new _atscript_core.AnnotationSpec({
-			description: "Portable collation for string comparison and sorting. Adapters map the generic value to their native collation.\n\n- **\"binary\"** — exact byte comparison (case-sensitive)\n- **\"nocase\"** — case-insensitive comparison\n- **\"unicode\"** — full Unicode-aware sorting\n\nFor adapter-specific collations, use `@db.<engine>.collate` instead.\n\n**Example:**\n```atscript\n@db.column.collate \"nocase\"\nusername: string\n```\n",
+			description: (0, _atscript_core.annotationExample)("Portable collation for string comparison and sorting. Adapters map the generic value to their native collation.\n\n- **\"binary\"** — exact byte comparison (case-sensitive)\n- **\"nocase\"** — case-insensitive comparison\n- **\"unicode\"** — full Unicode-aware sorting\n\nFor adapter-specific collations, use `@db.<engine>.collate` instead.", "@db.column.collate \"nocase\"", "username: string"),
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			argument: {
@@ -679,11 +621,11 @@ const dbColumnAnnotations = {
 				description: "Portable collation mode: \"binary\", \"nocase\", or \"unicode\"."
 			},
 			validate(token, args, doc) {
-				return require_validation_utils.validateFieldBaseType(token, doc, "@db.column.collate", "string");
+				return require_view_validation.validateFieldBaseType(token, doc, "@db.column.collate", "string");
 			}
 		}),
 		precision: new _atscript_core.AnnotationSpec({
-			description: "Sets decimal precision and scale for database storage. Adapters map this to their native decimal type (e.g., `DECIMAL(10,2)` in SQL, ignored in MongoDB).\n\nFor `decimal` fields the runtime value is a string; for `number` fields this is a DB storage hint only.\n\n**Example:**\n```atscript\n@db.column.precision 10, 2\nprice: decimal\n```\n",
+			description: (0, _atscript_core.annotationExample)("Sets decimal precision and scale for database storage. Adapters map this to their native decimal type (e.g., `DECIMAL(10,2)` in SQL, ignored in MongoDB).\n\nFor `decimal` fields the runtime value is a string; for `number` fields this is a DB storage hint only.", "@db.column.precision 10, 2", "price: decimal"),
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			argument: [{
@@ -696,11 +638,11 @@ const dbColumnAnnotations = {
 				description: "Number of digits after the decimal point."
 			}],
 			validate(token, args, doc) {
-				return require_validation_utils.validateFieldBaseType(token, doc, "@db.column.precision", ["number", "decimal"]);
+				return require_view_validation.validateFieldBaseType(token, doc, "@db.column.precision", ["number", "decimal"]);
 			}
 		}),
 		derived: new _atscript_core.AnnotationSpec({
-			description: "Declares a **derived column**: a read-only column computed from one `string`, `number` or `boolean` leaf inside a `@db.json` field of the **same table**, so the leaf can be filtered, sorted, grouped and indexed like a real column. The field's type is a chain reference into that field (`customerId: Order.payload.customer.id`); the path may not cross an array or a `@db.encrypted` field. Declare the field optional when the path can be absent (a missing leaf reads as `null`). A value written to it is dropped; `$inc` / `$dec` / `$mul` on it are rejected.\n\nStorage per adapter, schema sync and the compatible annotations: https://atscript.dev/db/api/storage#derived-columns\n\n**Example:**\n```atscript\n@db.table 'orders'\nexport interface Order {\n  @meta.id\n  id: number\n\n  @db.json\n  payload: {\n    customer: { id: string, vip: boolean }\n    total: number\n  }\n\n  @db.column.derived\n  @db.index.plain\n  customerId: Order.payload.customer.id\n\n  @db.column.derived\n  vip?: Order.payload.customer.vip\n}\n```\n",
+			description: (0, _atscript_core.annotationExample)("Declares a **derived column**: a read-only column computed from one `string`, `number` or `boolean` leaf inside a `@db.json` field of the **same table**, so the leaf can be filtered, sorted, grouped and indexed like a real column. The field's type is a chain reference into that field (`customerId: Order.payload.customer.id`); the path may not cross an array or a `@db.encrypted` field. Declare the field optional when the path can be absent (a missing leaf reads as `null`). A value written to it is dropped; `$inc` / `$dec` / `$mul` on it are rejected.\n\nStorage per adapter, schema sync and the compatible annotations: https://atscript.dev/db/api/storage#derived-columns", "@db.table 'orders'", "export interface Order {", "  @meta.id", "  id: number", "", "  @db.json", "  payload: {", "    customer: { id: string, vip: boolean }", "    total: number", "  }", "", "  @db.column.derived", "  @db.index.plain", "  customerId: Order.payload.customer.id", "", "  @db.column.derived", "  vip?: Order.payload.customer.vip", "}"),
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			multiple: false,
@@ -714,7 +656,7 @@ const dbColumnAnnotations = {
 						range: token.range
 					});
 				};
-				const owner = require_validation_utils.getDbTableOwner(token);
+				const owner = require_view_validation.getDbTableOwner(token);
 				if (!owner || !(0, _atscript_core.isInterface)(owner) || owner.countAnnotations("db.table") === 0) {
 					fail("@db.column.derived is only valid on a top-level field of a @db.table interface");
 					return errors;
@@ -726,12 +668,12 @@ const dbColumnAnnotations = {
 					return errors;
 				}
 				const ref = definition;
-				const tableName = require_validation_utils.getParentTypeName(token);
+				const tableName = require_view_validation.getParentTypeName(token);
 				if (ref.id !== tableName) {
 					fail(`@db.column.derived must reference the enclosing table '${tableName ?? ""}', not '${ref.id ?? ""}' — a derived column reads its own row`);
 					return errors;
 				}
-				const info = jsonChainInfo(ref, doc);
+				const info = require_view_validation.jsonChainInfo(ref, doc);
 				const path = `${info.typeName}.${info.chain.join(".")}`;
 				const notInsideJson = `@db.column.derived path '${path}' does not read inside a @db.json field — a flattened or scalar column needs no derived column`;
 				if (info.chain.length < 2) {
@@ -769,18 +711,20 @@ const dbColumnAnnotations = {
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			validate(token, _args, doc) {
-				return require_validation_utils.validateFieldBaseType(token, doc, "@db.column.measure", ["number", "decimal"]);
+				return require_view_validation.validateFieldBaseType(token, doc, "@db.column.measure", ["number", "decimal"]);
 			}
 		}),
 		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 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",
+			description: (0, _atscript_core.annotationExample)("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.", "@db.table \"jobs\"", "export interface Job {", "  @db.column.searchable", "  jobName: string", "  @db.column.searchable", "  description: string", "  @db.column.searchable", "  refNo: number.int", "}"),
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			multiple: false,
 			validate(token, _args, doc) {
-				const verdict = require_validation_utils.searchFieldVerdict(token.parentNode, doc);
+				const sealed = require_view_validation.sealedSearchProblem(token, doc, "@db.column.searchable");
+				if (sealed) return [sealed];
+				const verdict = require_view_validation.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}`,
@@ -791,17 +735,17 @@ const dbColumnAnnotations = {
 		}),
 		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",
+				description: (0, _atscript_core.annotationExample)("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`.", "@db.column.version", "version: int"),
 				nodeType: ["prop"],
 				passedWhenReferred: false,
 				validate(token, _args, doc) {
-					const errors = require_validation_utils.validateFieldBaseType(token, doc, "@db.column.version", "number");
+					const errors = require_view_validation.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);
+					const struct = require_view_validation.getParentStruct(token);
 					if (struct) {
 						let count = 0;
 						for (const [, prop] of struct.props) if (prop.countAnnotations("db.column.version") > 0) count++;
@@ -815,7 +759,7 @@ const dbColumnAnnotations = {
 				}
 			}),
 			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",
+				description: (0, _atscript_core.annotationExample)("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.", "@db.column.version", "version: number.int", "@db.column.version.exempt", "score: number"),
 				nodeType: ["prop"],
 				passedWhenReferred: false,
 				multiple: false,
@@ -827,7 +771,7 @@ const dbColumnAnnotations = {
 	},
 	default: {
 		$self: new _atscript_core.AnnotationSpec({
-			description: "Sets a static DB-level default value (used in DDL DEFAULT clause). For string fields the value is used as-is; for other types it is parsed as JSON.\n\n**Example:**\n```atscript\n@db.default \"active\"\nstatus: string\n```\n",
+			description: (0, _atscript_core.annotationExample)("Sets a static DB-level default value (used in DDL DEFAULT clause). For string fields the value is used as-is; for other types it is parsed as JSON.", "@db.default \"active\"", "status: string"),
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			argument: {
@@ -837,7 +781,7 @@ const dbColumnAnnotations = {
 			}
 		}),
 		increment: new _atscript_core.AnnotationSpec({
-			description: "Auto-incrementing integer default. Each adapter maps this to its native mechanism (e.g., `AUTO_INCREMENT` in MySQL, `INTEGER PRIMARY KEY` in SQLite, counter collection in MongoDB).\n\n**Example:**\n```atscript\n@db.default.increment\nid: number.int\n\n// With optional start value:\n@db.default.increment 1000\nid: number.int\n```\n",
+			description: (0, _atscript_core.annotationExample)("Auto-incrementing integer default. Each adapter maps this to its native mechanism (e.g., `AUTO_INCREMENT` in MySQL, `INTEGER PRIMARY KEY` in SQLite, counter collection in MongoDB).", "@db.default.increment", "id: number.int", "", "// With optional start value:", "@db.default.increment 1000", "id: number.int"),
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			argument: {
@@ -847,7 +791,7 @@ const dbColumnAnnotations = {
 				description: "Starting value for the auto-increment sequence. Adapter-specific behavior; some adapters may ignore this."
 			},
 			validate(token, args, doc) {
-				const errors = require_validation_utils.validateFieldBaseType(token, doc, "db.default.increment", "number");
+				const errors = require_view_validation.validateFieldBaseType(token, doc, "db.default.increment", "number");
 				if (token.parentNode.countAnnotations("meta.id") === 0) errors.push({
 					message: `@db.default.increment on a field without @meta.id — auto-increment columns must be primary-key columns for schema sync to manage them`,
 					severity: 2,
@@ -857,39 +801,50 @@ const dbColumnAnnotations = {
 			}
 		}),
 		uuid: new _atscript_core.AnnotationSpec({
-			description: "UUID generation default. Each adapter maps this to its native mechanism (e.g., `DEFAULT (UUID())` in MySQL, `gen_random_uuid()` in PostgreSQL, app-level in SQLite).\n\n**Example:**\n```atscript\n@db.default.uuid\nid: string.uuid\n```\n",
+			description: (0, _atscript_core.annotationExample)("UUID generation default. Each adapter maps this to its native mechanism (e.g., `DEFAULT (UUID())` in MySQL, `gen_random_uuid()` in PostgreSQL, app-level in SQLite).", "@db.default.uuid", "id: string.uuid"),
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			validate(token, args, doc) {
-				return require_validation_utils.validateFieldBaseType(token, doc, "db.default.uuid", "string");
+				return require_view_validation.validateFieldBaseType(token, doc, "db.default.uuid", "string");
 			}
 		}),
 		now: new _atscript_core.AnnotationSpec({
-			description: "Current timestamp default. Each adapter maps this to its native mechanism (e.g., `DEFAULT CURRENT_TIMESTAMP` in MySQL, `DEFAULT now()` in PostgreSQL).\n\n**Example:**\n```atscript\n@db.default.now\ncreatedAt: number.timestamp\n```\n",
+			description: (0, _atscript_core.annotationExample)("Current timestamp default. Each adapter maps this to its native mechanism (e.g., `DEFAULT CURRENT_TIMESTAMP` in MySQL, `DEFAULT now()` in PostgreSQL).", "@db.default.now", "createdAt: number.timestamp"),
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			validate(token, args, doc) {
-				return require_validation_utils.validateFieldBaseType(token, doc, "db.default.now", ["number", "string"]);
+				return require_view_validation.validateFieldBaseType(token, doc, "db.default.now", ["number", "string"]);
+			}
+		})
+	},
+	onUpdate: {
+		now: new _atscript_core.AnnotationSpec({
+			description: (0, _atscript_core.annotationExample)("Sets the field to the current time (epoch ms) on every update: patches (`updateOne`, `bulkUpdate`, `updateMany`, HTTP `PATCH`) and replaces (`replaceOne`, `bulkReplace`, `replaceMany`, HTTP `PUT`). The value is written by the SDK in the same statement on every adapter and overrides a value the payload carries. Inserts are not affected — combine with `@db.default.now` (`number.timestamp.updated` applies both). Writes outside the SDK (raw SQL) do not set it.", "@db.default.now", "@db.onUpdate.now", "updatedAt: number.timestamp"),
+			nodeType: ["prop"],
+			passedWhenReferred: false,
+			validate(token, args, doc) {
+				const errors = require_view_validation.validateFieldBaseType(token, doc, "@db.onUpdate.now", "number");
+				const field = token.parentNode;
+				for (const [name, why] of [["meta.id", "the primary key identifies the row and is never updated"], ["db.column.version", "the version column is adapter-managed"]]) if (field.countAnnotations(name) > 0) errors.push({
+					message: `@db.onUpdate.now cannot coexist with @${name} — ${why}`,
+					severity: 1,
+					range: token.range
+				});
+				return errors;
+			}
+		}),
+		inc: new _atscript_core.AnnotationSpec({
+			description: (0, _atscript_core.annotationExample)("A per-row **change counter**: `0` on insert (unless the insert supplies a value), then `+1` in the same statement on every SDK update of the row — patches (`updateOne`, `bulkUpdate`, `updateMany`, HTTP `PATCH`, including patches that write only `@db.column.version.exempt` fields), replaces (`replaceOne`, `bulkReplace`, `replaceMany`, HTTP `PUT`) and `touchMany`. A value the payload carries is ignored, so clients cannot set it. An empty patch writes nothing and leaves it unchanged. It has no compare-and-set and does not affect `@db.column.version`. Writes outside the SDK (raw SQL, native `ON DELETE SET NULL` actions) do not move it.\n\n**Constraints:** a non-optional integer field at the top level of the table; not the primary key, the version column, a `@db.onUpdate.now`, `@db.default*`, `@db.json` or `@db.encrypted` field.", "@db.onUpdate.inc", "revision: number.int"),
+			nodeType: ["prop"],
+			passedWhenReferred: false,
+			multiple: false,
+			validate(token, _args, doc) {
+				return validateOnUpdateInc(token, doc);
 			}
 		})
 	},
-	onUpdate: { now: new _atscript_core.AnnotationSpec({
-		description: "Sets the field to the current time (epoch ms) on every update: patches (`updateOne`, `bulkUpdate`, `updateMany`, HTTP `PATCH`) and replaces (`replaceOne`, `bulkReplace`, `replaceMany`, HTTP `PUT`). The value is written by the SDK in the same statement on every adapter and overrides a value the payload carries. Inserts are not affected — combine with `@db.default.now` (`number.timestamp.updated` applies both). Writes outside the SDK (raw SQL) do not set it.\n\n**Example:**\n```atscript\n@db.default.now\n@db.onUpdate.now\nupdatedAt: number.timestamp\n```\n",
-		nodeType: ["prop"],
-		passedWhenReferred: false,
-		validate(token, args, doc) {
-			const errors = require_validation_utils.validateFieldBaseType(token, doc, "@db.onUpdate.now", "number");
-			const field = token.parentNode;
-			for (const [name, why] of [["meta.id", "the primary key identifies the row and is never updated"], ["db.column.version", "the version column is adapter-managed"]]) if (field.countAnnotations(name) > 0) errors.push({
-				message: `@db.onUpdate.now cannot coexist with @${name} — ${why}`,
-				severity: 1,
-				range: token.range
-			});
-			return errors;
-		}
-	}) },
 	json: new _atscript_core.AnnotationSpec({
-		description: "Forces a field to be stored as a single JSON column instead of being flattened into separate columns. Use on nested object fields that should remain as JSON in the database.\n\n**Example:**\n```atscript\n@db.json\nmetadata: { key: string, value: string }\n```\n",
+		description: (0, _atscript_core.annotationExample)("Forces a field to be stored as a single JSON column instead of being flattened into separate columns. Use on nested object fields that should remain as JSON in the database. On a primitive field (string / number / boolean) it stores the value as JSON too: SQL adapters filter the column only with `$exists` and never sort it — drop `@db.json` to get a typed, sortable scalar column.", "@db.json", "metadata: { key: string, value: string }"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		validate(token, _args, doc) {
@@ -898,7 +853,7 @@ const dbColumnAnnotations = {
 			if (definition && (0, _atscript_core.isRef)(definition)) {
 				const unwound = doc.unwindType(definition.id, definition.chain);
 				if (unwound && (0, _atscript_core.isPrimitive)(unwound.def)) errors.push({
-					message: "@db.json on a primitive field has no effect — primitive fields are already stored as scalar columns",
+					message: "@db.json on a primitive field stores it as one JSON column — filterable only with $exists and never sortable; drop @db.json for a typed scalar column",
 					severity: 2,
 					range: token.range
 				});
@@ -907,7 +862,7 @@ const dbColumnAnnotations = {
 		}
 	}),
 	ignore: new _atscript_core.AnnotationSpec({
-		description: "Excludes a field from the database schema. The field exists in the Atscript type but has no column in the DB.\n\n**Example:**\n```atscript\n@db.ignore\ndisplayName: string\n```\n",
+		description: (0, _atscript_core.annotationExample)("Excludes a field from the database schema. The field exists in the Atscript type but has no column in the DB.", "@db.ignore", "displayName: string"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		validate(token, _args, _doc) {
@@ -921,38 +876,18 @@ const dbColumnAnnotations = {
 		}
 	}),
 	encrypted: new _atscript_core.AnnotationSpec({
-		description: "Encrypts this field at rest. Values are AES-256-GCM encrypted by the core layer before reaching the database and decrypted on read — transparent to application code.\n\nConstraints: the field cannot be filtered, sorted, indexed, used as PK/FK, patched with arithmetic ops, or referenced by search/vector/geo features.\n\n**Example:**\n```atscript\n@db.encrypted\napiToken?: string\n```\n",
+		description: (0, _atscript_core.annotationExample)("Encrypts this field at rest. Values are AES-256-GCM encrypted by the core layer before reaching the database and decrypted on read — transparent to application code.\n\nConstraints: the field cannot be filtered, sorted, indexed, used as PK/FK, patched with arithmetic ops, or referenced by search/vector/geo features.", "@db.encrypted", "apiToken?: string"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		multiple: false,
-		validate(token, _args, _doc) {
-			const errors = [];
-			const field = token.parentNode;
-			for (const [name, why] of [
-				["meta.id", "the primary key must be addressable"],
-				["db.rel.FK", "joins are impossible over ciphertext"],
-				["db.index.plain", "indexes over ciphertext are meaningless"],
-				["db.index.unique", "indexes over ciphertext are meaningless"],
-				["db.index.fulltext", "indexes over ciphertext are meaningless"],
-				["db.index.geo", "geo indexes over ciphertext are meaningless"],
-				["db.search.vector", "vector search over ciphertext is impossible"],
-				["db.search.filter", "search filters need cleartext equality"],
-				["db.column.version", "the OCC filter needs cleartext equality"],
-				["db.default.increment", "engine-side defaults bypass the encryption transform"],
-				["db.default.now", "engine-side defaults bypass the encryption transform"],
-				["db.onUpdate.now", "the update time is set after the encryption transform"],
-				["db.mongo.search.text", "Atlas Search over ciphertext is impossible"],
-				["db.mongo.search.autocomplete", "Atlas Search over ciphertext is impossible"]
-			]) if (field.countAnnotations(name) > 0) errors.push({
-				message: `@db.encrypted cannot coexist with @${name} — ${why}`,
-				severity: 1,
-				range: token.range
-			});
-			return errors;
+		validate(token, _args, doc) {
+			const typeProblem = require_view_validation.encryptedTypeSearchProblem(token, doc);
+			const errors = require_view_validation.validateIncompatible(token, "@db.encrypted", require_search_fields.ENCRYPTED_INCOMPATIBLE, doc);
+			return typeProblem ? [typeProblem, ...errors] : errors;
 		}
 	}),
 	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. 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",
+		description: (0, _atscript_core.annotationExample)("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.", "@db.writeOnly", "@db.encrypted", "credentials?: string"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		multiple: false,
@@ -974,21 +909,15 @@ const dbColumnAnnotations = {
 	})
 };
 function columnCapability(capability, verb) {
-	const example = capability === "filterable" ? "  @db.column.filterable\n  email: string\n" : "  @db.column.sortable\n  createdAt: number.timestamp\n";
+	const example = capability === "filterable" ? ["  @db.column.filterable", "  email: string"] : ["  @db.column.sortable", "  createdAt: number.timestamp"];
 	return new _atscript_core.AnnotationSpec({
-		description: `Marks a column as ${capability} in the readable controller's query/pages endpoints. Relevant only when the host \`@db.table\` interface opts into strict mode with \`@db.table.${capability} 'manual'\`; otherwise ${verb} is open on every column the adapter can handle (default-open, back-compat) and the annotation is a no-op. Adapter capability always wins: \`@db.json\` / array columns stay non-sortable (and non-filterable on SQL adapters) even when annotated. \`/meta.fields\` advertises exactly what the gate accepts; index-backed columns additionally carry the advisory \`indexed\` flag.
-
-**Example:**
-\`\`\`atscript
-@db.table "users"
-@db.table.${capability} "manual"\nexport interface User {
-` + example + "}\n```\n",
+		description: (0, _atscript_core.annotationExample)(`Marks a column as ${capability} in the readable controller's query/pages endpoints. Relevant only when the host \`@db.table\` interface opts into strict mode with \`@db.table.${capability} 'manual'\`; otherwise ${verb} is open on every column the adapter can handle (default-open, back-compat) and the annotation is a no-op. Adapter capability always wins: \`@db.json\` / array columns stay non-sortable (and non-filterable on SQL adapters) even when annotated. \`/meta.fields\` advertises exactly what the gate accepts; index-backed columns additionally carry the advisory \`indexed\` flag.`, "@db.table \"users\"", `@db.table.${capability} "manual"`, "export interface User {", ...example, "}"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		multiple: false,
 		validate(token, _args, _doc) {
 			const errors = [];
-			const owner = require_validation_utils.getDbTableOwner(token);
+			const owner = require_view_validation.getDbTableOwner(token);
 			if (!owner || owner.countAnnotations("db.table") === 0) errors.push({
 				message: `@db.column.${capability} is only valid on fields of a @db.table interface`,
 				severity: 1,
@@ -1029,7 +958,7 @@ function operandProblem(prop, doc) {
 	if (computeArg(prop)) return void 0;
 	const def = prop.getDefinition();
 	const leaf = def && (0, _atscript_core.isRef)(def) ? doc.unwindType(def.id, def.chain)?.def : def;
-	const base = require_validation_utils.primitiveBaseType(leaf);
+	const base = require_view_validation.primitiveBaseType(leaf);
 	if (base === void 0) return void 0;
 	return require_search_fields.numericTypeProblem({
 		base,
@@ -1071,7 +1000,7 @@ function validateCompute(token, args, doc) {
 	const errors = [];
 	const prop = token.parentNode;
 	const field = prop.id ?? "field";
-	const view = require_validation_utils.getDbTableOwner(token);
+	const view = require_view_validation.getDbTableOwner(token);
 	const error = (message, range = token.range) => errors.push({
 		message,
 		severity: 1,
@@ -1081,15 +1010,15 @@ function validateCompute(token, args, doc) {
 		error("@db.compute is only valid on a field of a @db.view.for view");
 		return errors;
 	}
-	errors.push(...require_validation_utils.validateExclusiveWith(token, "@db.compute", EXCLUSIVE_WITH));
+	errors.push(...require_view_validation.validateExclusiveWith(token, "@db.compute", EXCLUSIVE_WITH, doc));
 	if (!isPlainNumber(prop, doc)) error(`Field "${field}" has a @db.compute and must be typed \`number\``);
 	const expr = args[0]?.exprNode;
 	if (!expr) return errors;
 	const refs = expr.fieldRefs();
-	const props = viewProps(view) ?? /* @__PURE__ */ new Map();
+	const props = require_view_validation.viewProps(view) ?? /* @__PURE__ */ new Map();
 	if (refs.length === 0) error("@db.compute needs at least one view field — a constant column is not supported", args[0].range);
 	const scope = viewHavingScope(view);
-	if (scope) errors.push(...require_validation_utils.validateQueryScope(args[0], scope, doc, "@db.compute references the view's own fields — declare it on the view first (`field: Type.field`)"));
+	if (scope) errors.push(...require_view_validation.validateQueryScope(args[0], scope, doc, "@db.compute references the view's own fields — declare it on the view first (`field: Type.field`)"));
 	for (const ref of refs) {
 		if (ref.typeRef) continue;
 		const operand = props.get(ref.fieldRef.text);
@@ -1104,7 +1033,7 @@ function validateCompute(token, args, doc) {
 	return errors;
 }
 const dbComputeAnnotations = { compute: new _atscript_core.AnnotationSpec({
-	description: "Declares a **computed view column** (since 0.1.147): closed arithmetic over the view's own fields — dimensions, aggregates, first-row-join fields and other computed fields — evaluated by the database, so the column sorts, filters and pages like any other.\n\nGrammar: `+ - * /`, unary `-`, parentheses, numeric literals, `coalesce(a, b, …)`. Every value is a double (`7 / 2 = 3.5`); a NULL operand yields NULL; division by zero yields NULL — so an expression with `/` or an optional operand needs an optional field.\n\n**Example:**\n```atscript\n@db.agg.count 'id', `Issue.status = 'open'`\nopenCount: Issue.id\n\n@db.compute `openCount * 10 + coalesce(oldestSeverity, 0)`\nrank: number\n```\n",
+	description: (0, _atscript_core.annotationExample)("Declares a **computed view column** (since 0.1.147): closed arithmetic over the view's own fields — dimensions, aggregates, first-row-join fields and other computed fields — evaluated by the database, so the column sorts, filters and pages like any other.\n\nGrammar: `+ - * /`, unary `-`, parentheses, numeric literals, `coalesce(a, b, …)`. Every value is a double (`7 / 2 = 3.5`); a NULL operand yields NULL; division by zero yields NULL — so an expression with `/` or an optional operand needs an optional field.", "@db.agg.count 'id', `Issue.status = 'open'`", "openCount: Issue.id", "", "@db.compute `openCount * 10 + coalesce(oldestSeverity, 0)`", "rank: number"),
 	nodeType: ["prop"],
 	passedWhenReferred: false,
 	argument: {
@@ -1119,7 +1048,7 @@ const dbComputeAnnotations = { compute: new _atscript_core.AnnotationSpec({
 //#region src/plugin/annotations/index-ann.ts
 const dbIndexAnnotations = { index: {
 	plain: new _atscript_core.AnnotationSpec({
-		description: "Standard (non-unique) index for query performance. Fields sharing the same index name form a composite index.\n\n**Example:**\n```atscript\n@db.index.plain \"idx_timeline\", \"desc\"\ncreatedAt: number.timestamp\n```\n",
+		description: (0, _atscript_core.annotationExample)("Standard (non-unique) index for query performance. Fields sharing the same index name form a composite index.", "@db.index.plain \"idx_timeline\", \"desc\"", "createdAt: number.timestamp"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		multiple: true,
@@ -1138,7 +1067,7 @@ const dbIndexAnnotations = { index: {
 		}]
 	}),
 	unique: new _atscript_core.AnnotationSpec({
-		description: "Unique index — ensures no two rows/documents have the same value(s). Fields sharing the same index name form a composite unique constraint.\n\n**Example:**\n```atscript\n@db.index.unique \"tenant_email\"\nemail: string.email\n```\n",
+		description: (0, _atscript_core.annotationExample)("Unique index — ensures no two rows/documents have the same value(s). Fields sharing the same index name form a composite unique constraint.", "@db.index.unique \"tenant_email\"", "email: string.email"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		multiple: true,
@@ -1151,10 +1080,12 @@ 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. 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",
+		description: (0, _atscript_core.annotationExample)("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.", "@db.index.fulltext \"ft_content\"", "title: string", "", "@db.index.fulltext \"ft_content\", 5", "bio: string", "", "@db.index.fulltext \"ft_content\"", "@db.index.unique", "refNo: number.int"),
 		validate(token, args, doc) {
 			const field = token.parentNode;
-			const verdict = require_validation_utils.searchFieldVerdict(field, doc);
+			const sealed = require_view_validation.sealedSearchProblem(token, doc, "@db.index.fulltext");
+			if (sealed) return [sealed];
+			const verdict = require_view_validation.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,
@@ -1162,7 +1093,7 @@ const dbIndexAnnotations = { index: {
 			}];
 			if (verdict.kind !== "integer") return [];
 			const errors = [];
-			const missing = require_validation_utils.integerMemberIndexProblem(token);
+			const missing = require_view_validation.integerMemberIndexProblem(token);
 			if (missing) errors.push({
 				message: missing,
 				severity: 1,
@@ -1192,7 +1123,7 @@ const dbIndexAnnotations = { index: {
 		}]
 	}),
 	geo: new _atscript_core.AnnotationSpec({
-		description: "Geospatial index on a `db.geoPoint` field. Enables `geoSearch()` (distance-ranked) and accelerates `$geoWithin` filters.\n\n**Example:**\n```atscript\n@db.index.geo\ngeo: db.geoPoint\n```\n",
+		description: (0, _atscript_core.annotationExample)("Geospatial index on a `db.geoPoint` field. Enables `geoSearch()` (distance-ranked) and accelerates `$geoWithin` filters.", "@db.index.geo", "geo: db.geoPoint"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		multiple: false,
@@ -1201,7 +1132,8 @@ const dbIndexAnnotations = { index: {
 			name: "name",
 			type: "string",
 			description: "Index name. Defaults to the field name."
-		}
+		},
+		validate: require_view_validation.refuseCiphertext("@db.index.geo")
 	})
 } };
 //#endregion
@@ -1217,13 +1149,13 @@ function checkCompositeFkCoverage(token, alias, refTypeName, targetStruct, targe
 	if (targetProp.countAnnotations("db.index.unique") > 0) return true;
 	const pk = [...targetStruct.props.entries()].filter(([, p]) => p.countAnnotations("meta.id") > 0).map(([name]) => name);
 	if (pk.length <= 1) return true;
-	const hostStruct = require_validation_utils.getParentStruct(token);
-	const owner = require_validation_utils.getDbTableOwner(token);
+	const hostStruct = require_view_validation.getParentStruct(token);
+	const owner = require_view_validation.getDbTableOwner(token);
 	if (!hostStruct || owner === void 0 || !isDbTable(owner)) return true;
 	const covered = /* @__PURE__ */ new Set();
 	for (const [, sibling] of hostStruct.props) {
 		if (sibling.countAnnotations("db.rel.FK") === 0) continue;
-		if (require_validation_utils.getAnnotationAlias(sibling, "db.rel.FK") !== alias) continue;
+		if (require_view_validation.getAnnotationAlias(sibling, "db.rel.FK") !== alias) continue;
 		const siblingDef = sibling.getDefinition();
 		if (siblingDef && (0, _atscript_core.isRef)(siblingDef) && siblingDef.id === refTypeName) {
 			if (siblingDef.chain.length === 1) covered.add(siblingDef.chain[0].text);
@@ -1233,7 +1165,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` (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",
+		description: (0, _atscript_core.annotationExample)("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.", "@db.rel.FK", "authorId: User.id", "", "// With alias (required when multiple FKs point to the same type)", "@db.rel.FK \"author\"", "authorId: User.id"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		argument: {
@@ -1299,7 +1231,7 @@ const dbRelAnnotations = { rel: {
 				}
 			}
 			if (!alias) {
-				const struct = require_validation_utils.getParentStruct(token);
+				const struct = require_view_validation.getParentStruct(token);
 				if (struct) {
 					let sameTargetCount = 0;
 					for (const [, prop] of struct.props) {
@@ -1309,7 +1241,7 @@ const dbRelAnnotations = { rel: {
 						const r = def;
 						if (!r.hasChain) continue;
 						if (r.id === refTypeName) {
-							if (!require_validation_utils.getAnnotationAlias(prop, "db.rel.FK")) sameTargetCount++;
+							if (!require_view_validation.getAnnotationAlias(prop, "db.rel.FK")) sameTargetCount++;
 						}
 					}
 					if (sameTargetCount > 1) errors.push({
@@ -1323,7 +1255,7 @@ const dbRelAnnotations = { rel: {
 		}
 	}),
 	to: new _atscript_core.AnnotationSpec({
-		description: "Forward navigational property — the FK is on **this** interface. The compiler resolves the matching @db.rel.FK by target type or alias.\n\n**Example:**\n```atscript\n@db.rel.to\nauthor?: User\n\n// With alias\n@db.rel.to \"author\"\nauthor?: User\n```\n",
+		description: (0, _atscript_core.annotationExample)("Forward navigational property — the FK is on **this** interface. The compiler resolves the matching @db.rel.FK by target type or alias.", "@db.rel.to", "author?: User", "", "// With alias", "@db.rel.to \"author\"", "author?: User"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		argument: {
@@ -1336,7 +1268,7 @@ const dbRelAnnotations = { rel: {
 			const errors = [];
 			const field = token.parentNode;
 			const alias = args[0]?.text;
-			const owner = require_validation_utils.getDbTableOwner(token);
+			const owner = require_view_validation.getDbTableOwner(token);
 			if (!owner || owner.countAnnotations("db.table") === 0) errors.push({
 				message: "@db.rel.to is only valid on fields of a @db.table interface",
 				severity: 1,
@@ -1347,7 +1279,7 @@ const dbRelAnnotations = { rel: {
 				severity: 1,
 				range: token.range
 			});
-			const targetTypeName = require_validation_utils.getNavTargetTypeName(field);
+			const targetTypeName = require_view_validation.getNavTargetTypeName(field);
 			if (!targetTypeName) return errors;
 			const unwound = doc.unwindType(targetTypeName);
 			if (unwound) {
@@ -1365,15 +1297,15 @@ const dbRelAnnotations = { rel: {
 				severity: 1,
 				range: token.range
 			});
-			const struct = require_validation_utils.getParentStruct(token);
+			const struct = require_view_validation.getParentStruct(token);
 			if (struct) {
 				const fieldName = field.id;
 				for (const [name, prop] of struct.props) {
 					if (name === fieldName) continue;
 					if (prop.countAnnotations("db.rel.to") === 0) continue;
-					const propAlias = require_validation_utils.getAnnotationAlias(prop, "db.rel.to");
+					const propAlias = require_view_validation.getAnnotationAlias(prop, "db.rel.to");
 					if ((alias || void 0) === (propAlias || void 0)) {
-						if (require_validation_utils.getNavTargetTypeName(prop) === targetTypeName) {
+						if (require_view_validation.getNavTargetTypeName(prop) === targetTypeName) {
 							errors.push({
 								message: `Duplicate @db.rel.to '${alias || targetTypeName}' — only one forward navigational property per alias`,
 								severity: 1,
@@ -1384,13 +1316,13 @@ const dbRelAnnotations = { rel: {
 					}
 				}
 				if (alias) {
-					if (require_validation_utils.findFKFieldsPointingTo(doc, struct, targetTypeName, alias).length === 0) errors.push({
+					if (require_view_validation.findFKFieldsPointingTo(doc, struct, targetTypeName, alias).length === 0) errors.push({
 						message: `No @db.rel.FK '${alias}' found on this interface`,
 						severity: 1,
 						range: token.range
 					});
 				} else {
-					const matches = require_validation_utils.findFKFieldsPointingTo(doc, struct, targetTypeName);
+					const matches = require_view_validation.findFKFieldsPointingTo(doc, struct, targetTypeName);
 					if (matches.length === 0) errors.push({
 						message: `No @db.rel.FK on this interface points to '${targetTypeName}' — did you mean @db.rel.from?`,
 						severity: 1,
@@ -1407,7 +1339,7 @@ const dbRelAnnotations = { rel: {
 		}
 	}),
 	from: new _atscript_core.AnnotationSpec({
-		description: "Inverse navigational property — the FK is on the **target** interface, pointing back to this one.\n\n**Example:**\n```atscript\n@db.rel.from\nposts: Post[]\n\n// With alias\n@db.rel.from \"original\"\ncomments: Comment[]\n```\n",
+		description: (0, _atscript_core.annotationExample)("Inverse navigational property — the FK is on the **target** interface, pointing back to this one.", "@db.rel.from", "posts: Post[]", "", "// With alias", "@db.rel.from \"original\"", "comments: Comment[]"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		argument: {
@@ -1420,7 +1352,7 @@ const dbRelAnnotations = { rel: {
 			const errors = [];
 			const field = token.parentNode;
 			const alias = args[0]?.text;
-			const owner = require_validation_utils.getDbTableOwner(token);
+			const owner = require_view_validation.getDbTableOwner(token);
 			if (!owner || owner.countAnnotations("db.table") === 0) errors.push({
 				message: "@db.rel.from is only valid on fields of a @db.table interface",
 				severity: 1,
@@ -1431,7 +1363,7 @@ const dbRelAnnotations = { rel: {
 				severity: 1,
 				range: token.range
 			});
-			const targetTypeName = require_validation_utils.getNavTargetTypeName(field);
+			const targetTypeName = require_view_validation.getNavTargetTypeName(field);
 			if (!targetTypeName) return errors;
 			const unwound = doc.unwindType(targetTypeName);
 			if (!unwound) return errors;
@@ -1445,15 +1377,15 @@ const dbRelAnnotations = { rel: {
 				});
 				return errors;
 			}
-			const struct = require_validation_utils.getParentStruct(token);
+			const struct = require_view_validation.getParentStruct(token);
 			if (struct) {
 				const fieldName = field.id;
 				for (const [name, prop] of struct.props) {
 					if (name === fieldName) continue;
 					if (prop.countAnnotations("db.rel.from") === 0) continue;
-					const propAlias = require_validation_utils.getAnnotationAlias(prop, "db.rel.from");
+					const propAlias = require_view_validation.getAnnotationAlias(prop, "db.rel.from");
 					if ((alias || void 0) === (propAlias || void 0)) {
-						if (require_validation_utils.getNavTargetTypeName(prop) === targetTypeName) {
+						if (require_view_validation.getNavTargetTypeName(prop) === targetTypeName) {
 							errors.push({
 								message: `Duplicate @db.rel.from '${alias || targetTypeName}' — only one inverse navigational property per alias`,
 								severity: 1,
@@ -1464,9 +1396,9 @@ const dbRelAnnotations = { rel: {
 					}
 				}
 			}
-			const thisTypeName = require_validation_utils.getParentTypeName(token);
+			const thisTypeName = require_view_validation.getParentTypeName(token);
 			if (!thisTypeName) return errors;
-			const matches = require_validation_utils.findFKFieldsPointingTo(targetDoc, targetDef, thisTypeName, alias);
+			const matches = require_view_validation.findFKFieldsPointingTo(targetDoc, targetDef, thisTypeName, alias);
 			if (alias) {
 				if (matches.length === 0) errors.push({
 					message: `No @db.rel.FK '${alias}' found on '${targetTypeName}'`,
@@ -1493,10 +1425,10 @@ const dbRelAnnotations = { rel: {
 			return errors;
 		}
 	}),
-	onDelete: require_validation_utils.refActionAnnotation("onDelete"),
-	onUpdate: require_validation_utils.refActionAnnotation("onUpdate"),
+	onDelete: require_view_validation.refActionAnnotation("onDelete"),
+	onUpdate: require_view_validation.refActionAnnotation("onUpdate"),
 	via: new _atscript_core.AnnotationSpec({
-		description: "Declares a many-to-many navigational property through an explicit junction table. `@db.rel.via` is self-sufficient — no `@db.rel.from` pairing is needed.\n\n**Example:**\n```atscript\n@db.rel.via PostTag\ntags: Tag[]\n```\n",
+		description: (0, _atscript_core.annotationExample)("Declares a many-to-many navigational property through an explicit junction table. `@db.rel.via` is self-sufficient — no `@db.rel.from` pairing is needed.", "@db.rel.via PostTag", "tags: Tag[]"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		argument: {
@@ -1520,7 +1452,7 @@ const dbRelAnnotations = { rel: {
 			});
 			if (!args[0]) return errors;
 			const junctionName = args[0].text;
-			errors.push(...require_validation_utils.validateRefArgument(args[0], doc, {
+			errors.push(...require_view_validation.validateRefArgument(args[0], doc, {
 				accept: isDbTable,
 				expected: "must have @db.table annotation."
 			}));
@@ -1529,10 +1461,10 @@ const dbRelAnnotations = { rel: {
 			if (!junctionUnwound) return errors;
 			const junctionDef = junctionUnwound.def;
 			if (!(0, _atscript_core.isInterface)(junctionDef)) return errors;
-			const thisTypeName = require_validation_utils.getParentTypeName(token);
-			const targetTypeName = require_validation_utils.getNavTargetTypeName(field);
+			const thisTypeName = require_view_validation.getParentTypeName(token);
+			const targetTypeName = require_view_validation.getNavTargetTypeName(field);
 			if (!thisTypeName || !targetTypeName) return errors;
-			const fksToThis = require_validation_utils.findFKFieldsPointingTo(junctionUnwound.doc, junctionDef, thisTypeName);
+			const fksToThis = require_view_validation.findFKFieldsPointingTo(junctionUnwound.doc, junctionDef, thisTypeName);
 			if (fksToThis.length === 0) errors.push({
 				message: `Junction '${junctionName}' has no @db.rel.FK pointing to '${thisTypeName}'`,
 				severity: 1,
@@ -1544,7 +1476,7 @@ const dbRelAnnotations = { rel: {
 				range: args[0].range
 			});
 			if (targetTypeName !== thisTypeName) {
-				const fksToTarget = require_validation_utils.findFKFieldsPointingTo(junctionUnwound.doc, junctionDef, targetTypeName);
+				const fksToTarget = require_view_validation.findFKFieldsPointingTo(junctionUnwound.doc, junctionDef, targetTypeName);
 				if (fksToTarget.length === 0) errors.push({
 					message: `Junction '${junctionName}' has no @db.rel.FK pointing to '${targetTypeName}'`,
 					severity: 1,
@@ -1560,7 +1492,7 @@ const dbRelAnnotations = { rel: {
 		}
 	}),
 	filterable: new _atscript_core.AnnotationSpec({
-		description: "Lets HTTP clients filter the parent rows by this relation's related rows — `ticket=$some(status=open)` / `ticket=$none(...)` in a moost-db query (`{ ticket: { $some: { status: 'open' } } }`). Off by default: a client predicate filters the PARENT set and runs a correlated subquery. Server-side code (`transformFilter`, `actionRowScope`, direct table calls) never needs it. The related table's own field rules (visibility, encryption, write-only) apply inside the predicate.\n\n**Example:**\n```atscript\n@db.rel.to\n@db.rel.filterable\nticket?: Ticket\n```\n",
+		description: (0, _atscript_core.annotationExample)("Lets HTTP clients filter the parent rows by this relation's related rows — `ticket=$some(status=open)` / `ticket=$none(...)` in a moost-db query (`{ ticket: { $some: { status: 'open' } } }`). Off by default: a client predicate filters the PARENT set and runs a correlated subquery. Server-side code (`transformFilter`, `actionRowScope`, direct table calls) never needs it. The related table's own field rules (visibility, encryption, write-only) apply inside the predicate.", "@db.rel.to", "@db.rel.filterable", "ticket?: Ticket"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		validate(token) {
@@ -1575,7 +1507,7 @@ const dbRelAnnotations = { rel: {
 		}
 	}),
 	filter: new _atscript_core.AnnotationSpec({
-		description: "Applies a filter to a navigational property, restricting which related records are loaded (`$with`) and which count in relational predicates (`$some` / `$none`).\n\n**Example:**\n```atscript\n@db.rel.from\n@db.rel.filter `Post.published = true`\npublishedPosts: Post[]\n```\n",
+		description: (0, _atscript_core.annotationExample)("Applies a filter to a navigational property, restricting which related records are loaded (`$with`) and which count in relational predicates (`$some` / `$none`).", "@db.rel.from", "@db.rel.filter `Post.published = true`", "publishedPosts: Post[]"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		argument: {
@@ -1600,7 +1532,7 @@ const dbRelAnnotations = { rel: {
 			}
 			if (!args[0]?.queryNode) return errors;
 			const scope = relFilterScope(field);
-			if (scope) errors.push(...require_validation_utils.validateQueryScope(args[0], scope, doc));
+			if (scope) errors.push(...require_view_validation.validateQueryScope(args[0], scope, doc));
 			const expression = args[0].queryNode.expression;
 			forEachComparison(expression, (cmp) => {
 				if (cmp.right && "fieldRef" in cmp.right) errors.push({
@@ -1609,13 +1541,13 @@ const dbRelAnnotations = { rel: {
 					range: cmp.right.fieldRef.range
 				});
 			});
-			const junction = hasVia ? require_validation_utils.getAnnotationAlias(field, "db.rel.via") : void 0;
+			const junction = hasVia ? require_view_validation.getAnnotationAlias(field, "db.rel.via") : void 0;
 			if (junction) {
 				const conjuncts = (0, _atscript_core.isQueryLogical)(expression) && expression.operator === "and" ? expression.operands : [expression];
 				for (const conjunct of conjuncts) {
 					let junctionRef;
 					let targetRef = false;
-					require_validation_utils.forEachFieldRef(conjunct, (ref) => {
+					require_view_validation.forEachFieldRef(conjunct, (ref) => {
 						if (ref.typeRef?.text === junction) junctionRef ??= ref.typeRef.range;
 						else targetRef = true;
 					});
@@ -1640,8 +1572,9 @@ function forEachComparison(expr, fn) {
 const dbSearchAnnotations = { search: {
 	vector: {
 		$self: new _atscript_core.AnnotationSpec({
-			description: "Marks a field as a **vector embedding** for **similarity search**.\n\n- Each adapter maps this to its native vector type and index:\n  - **MongoDB** → Atlas `$vectorSearch` index\n  - **MySQL 9+** → `VECTOR(N)` column + `VEC_DISTANCE_*` functions\n  - **PostgreSQL** → pgvector `vector(N)` column + distance operators\n  - **SQLite** → `BLOB` column + `vec0` virtual index (requires the `sqlite-vec` extension; falls back to JSON `TEXT` when unavailable)\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\nembedding: db.vector\n```\n",
+			description: (0, _atscript_core.annotationExample)("Marks a field as a **vector embedding** for **similarity search**.\n\n- Each adapter maps this to its native vector type and index:\n  - **MongoDB** → Atlas `$vectorSearch` index\n  - **MySQL 9+** → `VECTOR(N)` column + `VEC_DISTANCE_*` functions\n  - **PostgreSQL** → pgvector `vector(N)` column + distance operators\n  - **SQLite** → `BLOB` column + `vec0` virtual index (requires the `sqlite-vec` extension; falls back to JSON `TEXT` when unavailable)", "@db.search.vector 1536, \"cosine\"", "embedding: db.vector"),
 			nodeType: ["prop"],
+			validate: require_view_validation.refuseCiphertext("@db.search.vector"),
 			passedWhenReferred: false,
 			multiple: false,
 			argument: [
@@ -1685,7 +1618,7 @@ const dbSearchAnnotations = { search: {
 			]
 		}),
 		threshold: new _atscript_core.AnnotationSpec({
-			description: "Sets a **default minimum similarity threshold** for vector search queries on this field.\n\n- Results with a similarity score below this threshold are excluded.\n- Query-time `$threshold` control overrides this default.\n- Value range: `0` to `1` (where `1` means exact match).\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\n@db.search.vector.threshold 0.7\nembedding: db.vector\n```\n",
+			description: (0, _atscript_core.annotationExample)("Sets a **default minimum similarity threshold** for vector search queries on this field.\n\n- Results with a similarity score below this threshold are excluded.\n- Query-time `$threshold` control overrides this default.\n- Value range: `0` to `1` (where `1` means exact match).", "@db.search.vector 1536, \"cosine\"", "@db.search.vector.threshold 0.7", "embedding: db.vector"),
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			multiple: false,
@@ -1698,8 +1631,9 @@ const dbSearchAnnotations = { search: {
 		})
 	},
 	filter: new _atscript_core.AnnotationSpec({
-		description: "Assigns a field as a **pre-filter** for a **vector search index**.\n\n- Filters allow vector search queries to return results only within a specific subset.\n- The referenced index must be defined using `@db.search.vector`.\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\nembedding: db.vector\n\n@db.search.filter \"embedding\"\ncategory: string\n```\n",
+		description: (0, _atscript_core.annotationExample)("Assigns a field as a **pre-filter** for a **vector search index**.\n\n- Filters allow vector search queries to return results only within a specific subset.\n- The referenced index must be defined using `@db.search.vector`.", "@db.search.vector 1536, \"cosine\"", "embedding: db.vector", "", "@db.search.filter \"embedding\"", "category: string"),
 		nodeType: ["prop"],
+		validate: require_view_validation.refuseCiphertext("@db.search.filter"),
 		passedWhenReferred: false,
 		multiple: true,
 		argument: {
@@ -1717,7 +1651,7 @@ const dbSearchAnnotations = { search: {
 * read sorts by it without a `$nulls` entry for it.
 */
 const dbSortAnnotations = { sort: { nulls: new _atscript_core.AnnotationSpec({
-	description: "Default **NULL placement** when a read sorts by this field and the request names none (`$nulls` control, URL suffix `$sort=-closedAt:last`).\n\n- **`'first'`** — rows where the field is NULL (or missing) come before every value, in both sort directions\n- **`'last'`** — they come after every value, in both directions\n\nWithout it (and without `$nulls`) NULL placement is the database's own: first in ascending order on SQLite, MySQL, MongoDB and the in-memory adapter, last on PostgreSQL. Applies to `$sort` and to the `$rowOrder` of `first()` / `last()`. Only optional and `| null` fields can be NULL — on another required table field it has no effect. On PostgreSQL, MySQL and MongoDB a placement the engine does not produce natively costs the index its ORDER BY (a sort step instead).\n\n**Example:**\n```atscript\n@db.sort.nulls 'last'\nclosedAt?: number.timestamp\n```\n",
+	description: (0, _atscript_core.annotationExample)("Default **NULL placement** when a read sorts by this field and the request names none (`$nulls` control, URL suffix `$sort=-closedAt:last`).\n\n- **`'first'`** — rows where the field is NULL (or missing) come before every value, in both sort directions\n- **`'last'`** — they come after every value, in both directions\n\nWithout it (and without `$nulls`) NULL placement is the database's own: first in ascending order on SQLite, MySQL, MongoDB and the in-memory adapter, last on PostgreSQL. Applies to `$sort` and to the `$rowOrder` of `first()` / `last()`. Only optional and `| null` fields can be NULL — on another required table field it has no effect. On PostgreSQL, MySQL and MongoDB a placement the engine does not produce natively costs the index its ORDER BY (a sort step instead).", "@db.sort.nulls 'last'", "closedAt?: number.timestamp"),
 	nodeType: ["prop"],
 	passedWhenReferred: false,
 	multiple: false,
@@ -1743,16 +1677,20 @@ const dbSortAnnotations = { sort: { nulls: new _atscript_core.AnnotationSpec({
 			fail("@db.sort.nulls on a @db.encrypted field — encrypted fields are not sortable");
 			return errors;
 		}
+		if (require_view_validation.viewFieldSeals(field, doc).encrypted) {
+			fail("@db.sort.nulls on a view field over a @db.encrypted source field — encrypted fields are not sortable");
+			return errors;
+		}
 		const def = field.getDefinition();
 		let leaf = def;
 		if (def && (0, _atscript_core.isRef)(def)) leaf = doc.unwindType(def.id, def.chain)?.def;
-		const base = require_validation_utils.primitiveBaseType(leaf);
+		const base = require_view_validation.primitiveBaseType(leaf);
 		if (def && ((0, _atscript_core.isArray)(def) || (0, _atscript_core.isStructure)(def)) || leaf && ((0, _atscript_core.isArray)(leaf) || (0, _atscript_core.isStructure)(leaf) || (0, _atscript_core.isInterface)(leaf)) || leaf && (0, _atscript_core.isPrimitive)(leaf) && (base === "array" || base === "object")) {
 			fail("@db.sort.nulls needs a sortable scalar field — not an object or an array");
 			return errors;
 		}
-		const owner = require_validation_utils.getDbTableOwner(token);
-		if (!field.has("optional") && !require_validation_utils.isNullableUnion(def, doc) && owner && owner.countAnnotations("db.table") > 0 && field.ownerNode?.ownerNode === owner) fail("@db.sort.nulls on a required field has no effect — the field is never NULL; make it optional (field?: …) or remove the annotation", 2);
+		const owner = require_view_validation.getDbTableOwner(token);
+		if (!field.has("optional") && !require_view_validation.isNullableUnion(def, doc) && owner && owner.countAnnotations("db.table") > 0 && field.ownerNode?.ownerNode === owner) fail("@db.sort.nulls on a required field has no effect — the field is never NULL; make it optional (field?: …) or remove the annotation", 2);
 		return errors;
 	}
 }) } };
@@ -1763,7 +1701,7 @@ const dbTableAnnotations = {
 		filterable: tableCapability("filterable"),
 		sortable: tableCapability("sortable"),
 		$self: new _atscript_core.AnnotationSpec({
-			description: "Marks an interface as a database-persisted entity (table in SQL, collection in MongoDB). If the name argument is omitted, the adapter derives the table name from the interface name.\n\n**Example:**\n```atscript\n@db.table \"users\"\nexport interface User { ... }\n```\n",
+			description: (0, _atscript_core.annotationExample)("Marks an interface as a database-persisted entity (table in SQL, collection in MongoDB). If the name argument is omitted, the adapter derives the table name from the interface name.", "@db.table \"users\"", "export interface User { ... }"),
 			nodeType: ["interface"],
 			passedWhenReferred: false,
 			argument: {
@@ -1775,7 +1713,7 @@ const dbTableAnnotations = {
 			validate(token, _args, _doc) {
 				const errors = [];
 				const owner = token.parentNode;
-				if (require_validation_utils.hasAnyViewAnnotation(owner)) errors.push({
+				if (require_view_validation.hasAnyViewAnnotation(owner)) errors.push({
 					message: "An interface cannot be both a @db.table and a @db.view",
 					severity: 1,
 					range: token.range
@@ -1784,7 +1722,7 @@ const dbTableAnnotations = {
 			}
 		}),
 		renamed: new _atscript_core.AnnotationSpec({
-			description: "Specifies the previous table name for table rename migration. The sync engine generates ALTER TABLE RENAME instead of drop+create.\n\n**Example:**\n```atscript\n@db.table \"app_users\"\n@db.table.renamed \"users\"\nexport interface User { ... }\n```\n",
+			description: (0, _atscript_core.annotationExample)("Specifies the previous table name for table rename migration. The sync engine generates ALTER TABLE RENAME instead of drop+create.", "@db.table \"app_users\"", "@db.table.renamed \"users\"", "export interface User { ... }"),
 			nodeType: ["interface"],
 			passedWhenReferred: false,
 			argument: {
@@ -1803,7 +1741,7 @@ const dbTableAnnotations = {
 			}
 		}),
 		preferredId: { uniqueIndex: new _atscript_core.AnnotationSpec({
-			description: "Selects a unique index as the table's preferred row identifier. When the unique-index name is omitted, the first declared unique-index group wins.\n\n**Example:**\n```atscript\n@db.table\n@db.table.preferredId.uniqueIndex \"by_slug\"\nexport interface Post {\n  @db.index.unique \"by_slug\"\n  slug: string\n}\n```\n",
+			description: (0, _atscript_core.annotationExample)("Selects a unique index as the table's preferred row identifier. When the unique-index name is omitted, the first declared unique-index group wins.", "@db.table", "@db.table.preferredId.uniqueIndex \"by_slug\"", "export interface Post {", "  @db.index.unique \"by_slug\"", "  slug: string", "}"),
 			nodeType: ["interface"],
 			passedWhenReferred: false,
 			multiple: false,
@@ -1816,7 +1754,7 @@ const dbTableAnnotations = {
 			validate(token, args, _doc) {
 				const errors = [];
 				const owner = token.parentNode;
-				if (require_validation_utils.hasAnyViewAnnotation(owner)) errors.push({
+				if (require_view_validation.hasAnyViewAnnotation(owner)) errors.push({
 					message: "@db.table.preferredId.uniqueIndex is not supported on @db.view interfaces (views have no unique-index declarations).",
 					severity: 1,
 					range: token.range
@@ -1851,7 +1789,7 @@ const dbTableAnnotations = {
 		}) }
 	},
 	schema: new _atscript_core.AnnotationSpec({
-		description: "Assigns the entity to a database schema/namespace.\n\n**Example:**\n```atscript\n@db.table \"users\"\n@db.schema \"auth\"\nexport interface User { ... }\n```\n",
+		description: (0, _atscript_core.annotationExample)("Assigns the entity to a database schema/namespace.", "@db.table \"users\"", "@db.schema \"auth\"", "export interface User { ... }"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		argument: {
@@ -1861,7 +1799,7 @@ const dbTableAnnotations = {
 		}
 	}),
 	space: new _atscript_core.AnnotationSpec({
-		description: "Binds the entity to a named database space (a `DbSpace` — one per physical database) for apps running more than one database at once (e.g. MongoDB + PostgreSQL). Absent means the default space.\n\nConsumed by the generated model manifest (grouping in `modelsBySpace`) and by `@TableController(Model)` token binding, which resolves the space registered under this name via `provideDbSpace(space, name)`.\n\n**Example:**\n```atscript\n@db.table \"feed_runs\"\n@db.space \"analytics\"\nexport interface FeedRun { ... }\n```\n",
+		description: (0, _atscript_core.annotationExample)("Binds the entity to a named database space (a `DbSpace` — one per physical database) for apps running more than one database at once (e.g. MongoDB + PostgreSQL). Absent means the default space.\n\nConsumed by the generated model manifest (grouping in `modelsBySpace`) and by `@TableController(Model)` token binding, which resolves the space registered under this name via `provideDbSpace(space, name)`.", "@db.table \"feed_runs\"", "@db.space \"analytics\"", "export interface FeedRun { ... }"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		argument: {
@@ -1871,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. 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",
+		description: (0, _atscript_core.annotationExample)("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).", "@db.table \"authors\"", "@db.http.path \"/authors\"", "export interface Author { ... }"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		argument: {
@@ -1881,7 +1819,7 @@ const dbTableAnnotations = {
 		}
 	}) },
 	sync: { method: new _atscript_core.AnnotationSpec({
-		description: "Controls how the sync engine handles structural changes that cannot be applied via ALTER TABLE.\n\n- `\"recreate\"` — lossless: create temp table, copy data, drop old, rename.\n- `\"drop\"` — lossy: drop table entirely and create from scratch.\n\nWithout this annotation, structural changes fail with an error requiring manual intervention.\n\n**Example:**\n```atscript\n@db.sync.method \"drop\"\ninterface Logs { ... }\n```\n",
+		description: (0, _atscript_core.annotationExample)("Controls how the sync engine handles structural changes that cannot be applied via ALTER TABLE.\n\n- `\"recreate\"` — lossless: create temp table, copy data, drop old, rename.\n- `\"drop\"` — lossy: drop table entirely and create from scratch.\n\nWithout this annotation, structural changes fail with an error requiring manual intervention.", "@db.sync.method \"drop\"", "interface Logs { ... }"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		argument: {
@@ -1892,7 +1830,7 @@ const dbTableAnnotations = {
 		}
 	}) },
 	depth: { limit: new _atscript_core.AnnotationSpec({
-		description: "Security guard on nested-write payloads. `N` is a non-negative integer declaring the maximum depth a client may nest `@db.rel.from` children in insert, replace, or patch payloads. Writes deeper than `N` are rejected at the server boundary with HTTP 400 before any DB access.\n\n**Default when absent:** `0` — any nested-write payload is rejected. Authors opt in explicitly to `N >= 1` when they want the server to accept deep writes. This is a security / blast-radius control, not a performance knob.\n\n**Scope:** affects only write acceptance. Has no effect on `/meta` serialization, read/query paths, or wire shape — the meta endpoint always ships FK refs as the shallow `{ id, metadata }` shape regardless of this annotation.\n\n**Example:**\n```atscript\n@db.table \"authors\"\n@db.depth.limit 2\nexport interface Author { ... }\n```\n",
+		description: (0, _atscript_core.annotationExample)("Security guard on nested-write payloads. `N` is a non-negative integer declaring the maximum depth a client may nest `@db.rel.from` children in insert, replace, or patch payloads. Writes deeper than `N` are rejected at the server boundary with HTTP 400 before any DB access.\n\n**Default when absent:** `0` — any nested-write payload is rejected. Authors opt in explicitly to `N >= 1` when they want the server to accept deep writes. This is a security / blast-radius control, not a performance knob.\n\n**Scope:** affects only write acceptance. Has no effect on `/meta` serialization, read/query paths, or wire shape — the meta endpoint always ships FK refs as the shallow `{ id, metadata }` shape regardless of this annotation.", "@db.table \"authors\"", "@db.depth.limit 2", "export interface Author { ... }"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		multiple: false,
@@ -1946,19 +1884,21 @@ function collectUniqueIndexGroups(owner) {
 	return groups;
 }
 function tableCapability(capability) {
-	const example = capability === "filterable" ? "  @db.column.filterable\n  email: string\n  // other fields not filterable via the controller\n" : "  @db.column.sortable\n  createdAt: number.timestamp\n  // other fields not sortable via the controller\n";
+	const example = capability === "filterable" ? [
+		"  @db.column.filterable",
+		"  email: string",
+		"  // other fields not filterable via the controller"
+	] : [
+		"  @db.column.sortable",
+		"  createdAt: number.timestamp",
+		"  // other fields not sortable via the controller"
+	];
 	const verb = capability === "filterable" ? "filter" : "sort";
 	return new _atscript_core.AnnotationSpec({
-		description: `Controls ${verb}-gating on the readable controller's \`/query\` and \`/pages\` endpoints.\n\n- **\`'auto'\`** (default when the annotation is absent) — every column the adapter can ${verb} is ${capability} (JSON / array columns are never sortable, and not filterable on SQL adapters).
+		description: (0, _atscript_core.annotationExample)(`Controls ${verb}-gating on the readable controller's \`/query\` and \`/pages\` endpoints.\n\n- **\`'auto'\`** (default when the annotation is absent) — every column the adapter can ${verb} is ${capability} (JSON / array columns are never sortable, and not filterable on SQL adapters).
 - **\`'manual'\`** — only fields annotated \`@db.column.${capability}\` are ${capability};   all others are rejected with HTTP 400.
 
-\`/meta.fields[*].` + capability + "` advertises exactly what the gate accepts in either mode. The policy applies to " + (capability === "filterable" ? "filters only — `$groupBy`, `$having` keys and aggregate fields use the adapter's physical capability.\n\n" : "`$sort` only.\n\n") + `Writing the annotation explicitly as \`@db.table.${capability} 'auto'\` has the same runtime effect as omitting it; use it to document intent.
-
-**Example:**
-\`\`\`atscript
-@db.table "users"
-@db.table.${capability} "manual"\nexport interface User {
-` + example + "}\n```\n",
+\`/meta.fields[*].` + capability + "` advertises exactly what the gate accepts in either mode. The policy applies to " + (capability === "filterable" ? "filters only — `$groupBy`, `$having` keys and aggregate fields use the adapter's physical capability.\n\n" : "`$sort` only.\n\n") + `Writing the annotation explicitly as \`@db.table.${capability} 'auto'\` has the same runtime effect as omitting it; use it to document intent.`, "@db.table \"users\"", `@db.table.${capability} "manual"`, "export interface User {", ...example, "}"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		multiple: false,
@@ -1985,7 +1925,7 @@ function tableCapability(capability) {
 const UNIT_HOST_TYPES = ["decimal", "number"];
 const dbUnitAnnotations = { unit: {
 	$self: new _atscript_core.AnnotationSpec({
-		description: "Hard-coded **unit of measure** for this quantity field. Use when a table stores all values for this field in a single, fixed unit.\n\nFor per-row units, use `@db.unit.ref 'fieldName'` instead.\n\nValid on `decimal` and `number` fields. Unlike `@db.amount.currency`, the unit code is free-form (`'kg'`, `'rpm'`, `'qps'`, …) — no ISO-style validation.\n\nAggregations on a unit-tagged field do not need grouping when the unit is a fixed literal — the constraint is satisfied schema-wide.\n\n**Example:**\n```atscript\n@db.unit 'kg'\nweight: decimal\n```\n",
+		description: (0, _atscript_core.annotationExample)("Hard-coded **unit of measure** for this quantity field. Use when a table stores all values for this field in a single, fixed unit.\n\nFor per-row units, use `@db.unit.ref 'fieldName'` instead.\n\nValid on `decimal` and `number` fields. Unlike `@db.amount.currency`, the unit code is free-form (`'kg'`, `'rpm'`, `'qps'`, …) — no ISO-style validation.\n\nAggregations on a unit-tagged field do not need grouping when the unit is a fixed literal — the constraint is satisfied schema-wide.", "@db.unit 'kg'", "weight: decimal"),
 		nodeType: ["prop"],
 		multiple: false,
 		argument: {
@@ -1995,16 +1935,16 @@ const dbUnitAnnotations = { unit: {
 		},
 		validate(token, _args, doc) {
 			const errors = [];
-			errors.push(...require_validation_utils.validateFieldBaseType(token, doc, "@db.unit", UNIT_HOST_TYPES));
-			errors.push(...require_validation_utils.validateExclusiveWith(token, "@db.unit", [{
+			errors.push(...require_view_validation.validateFieldBaseType(token, doc, "@db.unit", UNIT_HOST_TYPES));
+			errors.push(...require_view_validation.validateExclusiveWith(token, "@db.unit", [{
 				key: "db.unit.ref",
 				displayName: "@db.unit.ref"
-			}]));
+			}], doc));
 			return errors;
 		}
 	}),
 	ref: new _atscript_core.AnnotationSpec({
-		description: "Binds this quantity to a **sibling field** that holds its unit. Use when different rows may carry different units (e.g. mixed kg/lb measurements).\n\nThe referenced field must be a `string`.\n\nValid on `decimal` and `number` fields. Aggregating this field forces the referenced unit field into `$groupBy` at runtime — summing rows with different units is rejected.\n\n**Example:**\n```atscript\nunit: string\n@db.unit.ref 'unit'\nweight: decimal\n```\n",
+		description: (0, _atscript_core.annotationExample)("Binds this quantity to a **sibling field** that holds its unit. Use when different rows may carry different units (e.g. mixed kg/lb measurements).\n\nThe referenced field must be a `string`.\n\nValid on `decimal` and `number` fields. Aggregating this field forces the referenced unit field into `$groupBy` at runtime — summing rows with different units is rejected.", "unit: string", "@db.unit.ref 'unit'", "weight: decimal"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		multiple: false,
@@ -2015,15 +1955,15 @@ const dbUnitAnnotations = { unit: {
 		},
 		validate(token, args, doc) {
 			const errors = [];
-			errors.push(...require_validation_utils.validateFieldBaseType(token, doc, "@db.unit.ref", UNIT_HOST_TYPES));
-			errors.push(...require_validation_utils.validateExclusiveWith(token, "@db.unit.ref", [{
+			errors.push(...require_view_validation.validateFieldBaseType(token, doc, "@db.unit.ref", UNIT_HOST_TYPES));
+			errors.push(...require_view_validation.validateExclusiveWith(token, "@db.unit.ref", [{
 				key: "db.unit",
 				displayName: "@db.unit"
 			}, {
 				key: "db.amount.currency.ref",
 				displayName: "@db.amount.currency.ref"
-			}]));
-			errors.push(...require_validation_utils.validateSiblingStringField(token, args, doc, "@db.unit.ref"));
+			}], doc));
+			errors.push(...require_view_validation.validateSiblingStringField(token, args, doc, "@db.unit.ref"));
 			return errors;
 		}
 	})
@@ -2039,7 +1979,7 @@ const dbUnitAnnotations = { unit: {
 */
 function validateJoinOrder(orderToken, scope, doc) {
 	const target = scope.unqualifiedTarget;
-	const errors = require_validation_utils.validateQueryScope(orderToken, scope, doc, `a first-row join orders by fields of its target '${target}'`);
+	const errors = require_view_validation.validateQueryScope(orderToken, scope, doc, `a first-row join orders by fields of its target '${target}'`);
 	const seen = /* @__PURE__ */ new Set();
 	for (const item of orderToken.orderNode.items) {
 		const { ref } = item;
@@ -2087,7 +2027,7 @@ function orderKeyProblem(doc, target, path) {
 }
 const dbViewAnnotations = { view: {
 	$self: new _atscript_core.AnnotationSpec({
-		description: "Marks an interface as a **database view**. Optionally takes a view name argument.\n\n**Example:**\n```atscript\n@db.view \"active_premium_users\"\n@db.view.for User\nexport interface ActivePremiumUser { ... }\n```\n",
+		description: (0, _atscript_core.annotationExample)("Marks an interface as a **database view**. Optionally takes a view name argument.", "@db.view \"active_premium_users\"", "@db.view.for User", "export interface ActivePremiumUser { ... }"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		argument: {
@@ -2107,14 +2047,14 @@ const dbViewAnnotations = { view: {
 		}
 	}),
 	for: new _atscript_core.AnnotationSpec({
-		description: "Specifies the entry/primary source for a computed view — a `@db.table`, or another `@db.view` (views over views, since 0.1.141). Required for views that map fields via chain refs. A `@db.alias` type cannot be the entry.\n\n**Example:**\n```atscript\n@db.view.for Order\n@db.view.filter `Order.status = 'active'`\nexport interface ActiveOrderDetails { ... }\n```\n",
+		description: (0, _atscript_core.annotationExample)("Specifies the entry/primary source for a computed view — a `@db.table`, or another `@db.view` (views over views, since 0.1.141). Required for views that map fields via chain refs. A `@db.alias` type cannot be the entry.", "@db.view.for Order", "@db.view.filter `Order.status = 'active'`", "export interface ActiveOrderDetails { ... }"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		argument: {
 			name: "entry",
 			type: "ref",
 			description: "The primary/entry table or view type (must have @db.table or @db.view).",
-			refFilter: require_validation_utils.isDbSourceDecl
+			refFilter: require_view_validation.isDbSourceDecl
 		},
 		validate(token, args, doc) {
 			const errors = [];
@@ -2124,19 +2064,19 @@ const dbViewAnnotations = { view: {
 				severity: 1,
 				range: token.range
 			});
-			if (args[0]) errors.push(...require_validation_utils.validateRefArgument(args[0], doc, VIEW_SOURCE_ARGUMENT));
-			const cycle = require_validation_utils.findViewCycle(owner, doc);
+			if (args[0]) errors.push(...require_view_validation.validateRefArgument(args[0], doc, VIEW_SOURCE_ARGUMENT));
+			const cycle = require_view_validation.findViewCycle(owner, doc);
 			if (cycle) errors.push({
 				message: `View '${cycle[0]}' depends on itself: ${cycle.join(" → ")}`,
 				severity: 1,
 				range: args[0]?.range ?? token.range
 			});
-			errors.push(...validateViewInterface(owner, doc));
+			errors.push(...require_view_validation.validateViewInterface(owner, doc));
 			return errors;
 		}
 	}),
 	joins: new _atscript_core.AnnotationSpec({
-		description: "Declares an explicit join for a view. Joins are INNER by default — pass `'left'` as the third argument to keep entry rows without a match (fields read from a left-joined table must be optional). A join condition may reference the entry table and joins declared before it (chained joins). The target is a `@db.table`, a `@db.view` (since 0.1.141), or a `@db.alias` type — the way to join one table twice or to self-join the entry table: every scope name (entry + joins) must be unique.\n\n**Example:**\n```atscript\n@db.view.for Order\n@db.view.joins Customer, `Customer.id = Order.customerId`\n@db.view.joins Region, `Region.id = Customer.regionId`, 'left'\nexport interface OrderRegion { ... }\n```\n\n**First-row join** (since 0.1.147): a 4th argument — an ordering of the target's fields (`` `raisedAt, id` ``, `` `severity desc` ``) — joins only the FIRST matching target row by that ordering (the target's primary key is appended as the final tie-break), so every field read through the join comes from that one row. NULL sorts first in `asc`.\n```atscript\n@db.view.joins OldestOpenIssue, `OldestOpenIssue.ticketId = Ticket.id and OldestOpenIssue.status = 'open'`, 'left', `raisedAt`\n```\n",
+		description: (0, _atscript_core.annotationExample)("Declares an explicit join for a view. Joins are INNER by default — pass `'left'` as the third argument to keep entry rows without a match (fields read from a left-joined table must be optional). A join condition may reference the entry table and joins declared before it (chained joins). The target is a `@db.table`, a `@db.view` (since 0.1.141), or a `@db.alias` type — the way to join one table twice or to self-join the entry table: every scope name (entry + joins) must be unique.", "@db.view.for Order", "@db.view.joins Customer, `Customer.id = Order.customerId`", "@db.view.joins Region, `Region.id = Customer.regionId`, 'left'", "export interface OrderRegion { ... }", "```", "", "**First-row join** (since 0.1.147): a 4th argument — an ordering of the target's fields (`` `raisedAt, id` ``, `` `severity desc` ``) — joins only the FIRST matching target row by that ordering (the target's primary key is appended as the final tie-break), so every field read through the join comes from that one row. NULL sorts first in `asc`.", "```atscript", "@db.view.joins OldestOpenIssue, `OldestOpenIssue.ticketId = Ticket.id and OldestOpenIssue.status = 'open'`, 'left', `raisedAt`"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		multiple: true,
@@ -2172,7 +2112,7 @@ const dbViewAnnotations = { view: {
 		validate(token, args, doc) {
 			const errors = [];
 			const owner = token.parentNode;
-			if (!require_validation_utils.hasAnyViewAnnotation(owner) && !args[0]) {
+			if (!require_view_validation.hasAnyViewAnnotation(owner) && !args[0]) {
 				errors.push({
 					message: "@db.view.joins is only valid on @db.view interfaces",
 					severity: 1,
@@ -2180,11 +2120,11 @@ const dbViewAnnotations = { view: {
 				});
 				return errors;
 			}
-			if (args[0]) errors.push(...require_validation_utils.validateRefArgument(args[0], doc, {
+			if (args[0]) errors.push(...require_view_validation.validateRefArgument(args[0], doc, {
 				accept: isJoinTarget,
 				expected: "must be a @db.table or a @db.view."
 			}));
-			const entryTypeName = require_validation_utils.getAnnotationAlias(owner, "db.view.for");
+			const entryTypeName = require_view_validation.getAnnotationAlias(owner, "db.view.for");
 			if (!entryTypeName) {
 				errors.push({
 					message: "@db.view.joins requires @db.view.for to identify the entry table",
@@ -2193,14 +2133,14 @@ const dbViewAnnotations = { view: {
 				});
 				return errors;
 			}
-			const joins = require_validation_utils.viewJoins(owner);
+			const joins = require_view_validation.viewJoins(owner);
 			const join = joins.find((a) => a.token === token);
-			const earlier = join ? require_validation_utils.earlierJoinTargets(joins, join) : [];
+			const earlier = join ? require_view_validation.earlierJoinTargets(joins, join) : [];
 			if (args[0]) {
 				const target = args[0].text;
 				const aliasHint = (name) => {
 					const decl = doc.getDeclarationOwnerNode(target)?.node;
-					return decl && require_validation_utils.isAliasDecl(decl) ? "" : ` — declare a @db.alias type (\`@db.alias ${name}\` + \`export type Other = ${name}\`) to join it under another name`;
+					return decl && require_view_validation.isAliasDecl(decl) ? "" : ` — declare a @db.alias type (\`@db.alias ${name}\` + \`export type Other = ${name}\`) to join it under another name`;
 				};
 				if (target === entryTypeName) errors.push({
 					message: `@db.view.joins cannot join the entry table '${target}' directly${aliasHint(target)}`,
@@ -2214,14 +2154,14 @@ const dbViewAnnotations = { view: {
 				});
 			}
 			const scope = join && viewJoinScope(owner, join, earlier);
-			if (args[1]?.queryNode && scope) errors.push(...require_validation_utils.validateQueryScope(args[1], scope, doc, "a join may reference the entry table and joins declared before it"));
+			if (args[1]?.queryNode && scope) errors.push(...require_view_validation.validateQueryScope(args[1], scope, doc, "a join may reference the entry table and joins declared before it"));
 			const order = join && args[3]?.orderNode ? joinOrderScope(join) : void 0;
 			if (order) errors.push(...validateJoinOrder(args[3], order, doc));
 			return errors;
 		}
 	}),
 	filter: new _atscript_core.AnnotationSpec({
-		description: "WHERE clause for a view, filtering which rows are included.\n\n**Example:**\n```atscript\n@db.view.for User\n@db.view.filter `User.status = 'active' and User.age >= 18`\nexport interface ActiveUser { ... }\n```\n",
+		description: (0, _atscript_core.annotationExample)("WHERE clause for a view, filtering which rows are included.", "@db.view.for User", "@db.view.filter `User.status = 'active' and User.age >= 18`", "export interface ActiveUser { ... }"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		argument: {
@@ -2233,7 +2173,7 @@ const dbViewAnnotations = { view: {
 		validate(token, args, doc) {
 			const errors = [];
 			const owner = token.parentNode;
-			if (!require_validation_utils.hasAnyViewAnnotation(owner) && !args[0]) {
+			if (!require_view_validation.hasAnyViewAnnotation(owner) && !args[0]) {
 				errors.push({
 					message: "@db.view.filter is only valid on @db.view interfaces",
 					severity: 1,
@@ -2251,18 +2191,18 @@ const dbViewAnnotations = { view: {
 				});
 				return errors;
 			}
-			errors.push(...require_validation_utils.validateQueryScope(args[0], scope, doc));
+			errors.push(...require_view_validation.validateQueryScope(args[0], scope, doc));
 			return errors;
 		}
 	}),
 	materialized: new _atscript_core.AnnotationSpec({
-		description: "Marks a view as materialized (precomputed, stored on disk). Supported by PostgreSQL, CockroachDB, Oracle, SQL Server (indexed views), Snowflake. MongoDB supports on-demand materialized views via $merge/$out. Not applicable to MySQL or SQLite.\n\n**Example:**\n```atscript\n@db.view.materialized\n@db.view.for User\n@db.view.filter `User.status = 'active'`\nexport interface ActiveUsers { ... }\n```\n",
+		description: (0, _atscript_core.annotationExample)("Marks a view as materialized (precomputed, stored on disk). Supported by PostgreSQL, CockroachDB, Oracle, SQL Server (indexed views), Snowflake. MongoDB supports on-demand materialized views via $merge/$out. Not applicable to MySQL or SQLite.", "@db.view.materialized", "@db.view.for User", "@db.view.filter `User.status = 'active'`", "export interface ActiveUsers { ... }"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		validate(token, _args, _doc) {
 			const errors = [];
 			const owner = token.parentNode;
-			if (!require_validation_utils.hasAnyViewAnnotation(owner)) errors.push({
+			if (!require_view_validation.hasAnyViewAnnotation(owner)) errors.push({
 				message: "@db.view.materialized is only valid on @db.view interfaces",
 				severity: 1,
 				range: token.range
@@ -2271,7 +2211,7 @@ const dbViewAnnotations = { view: {
 		}
 	}),
 	renamed: new _atscript_core.AnnotationSpec({
-		description: "Specifies the previous view name for view rename migration. The sync engine drops the old view and creates the new one.\n\n**Example:**\n```atscript\n@db.view \"active_premium_users\"\n@db.view.renamed \"active_users\"\n@db.view.for User\nexport interface ActivePremiumUser { ... }\n```\n",
+		description: (0, _atscript_core.annotationExample)("Specifies the previous view name for view rename migration. The sync engine drops the old view and creates the new one.", "@db.view \"active_premium_users\"", "@db.view.renamed \"active_users\"", "@db.view.for User", "export interface ActivePremiumUser { ... }"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		argument: {
@@ -2282,7 +2222,7 @@ const dbViewAnnotations = { view: {
 		validate(token, _args, _doc) {
 			const errors = [];
 			const owner = token.parentNode;
-			if (!require_validation_utils.hasAnyViewAnnotation(owner)) errors.push({
+			if (!require_view_validation.hasAnyViewAnnotation(owner)) errors.push({
 				message: "@db.view.renamed requires @db.view on the same interface",
 				severity: 1,
 				range: token.range
@@ -2291,7 +2231,7 @@ const dbViewAnnotations = { view: {
 		}
 	}),
 	having: new _atscript_core.AnnotationSpec({
-		description: "Post-aggregation filter (HAVING clause) for analytical views. References the view's own fields, unqualified (`totalRevenue > 100`) — aggregate fields by their alias, plain fields as GROUP BY dimensions; source-table refs are not in scope.\n\n**Example:**\n```atscript\n@db.view\n@db.view.for Order\n@db.view.having `totalRevenue > 100`\nexport interface TopCategories { ... }\n```\n",
+		description: (0, _atscript_core.annotationExample)("Post-aggregation filter (HAVING clause) for analytical views. References the view's own fields, unqualified (`totalRevenue > 100`) — aggregate fields by their alias, plain fields as GROUP BY dimensions; source-table refs are not in scope.", "@db.view", "@db.view.for Order", "@db.view.having `totalRevenue > 100`", "export interface TopCategories { ... }"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		argument: {
@@ -2303,7 +2243,7 @@ const dbViewAnnotations = { view: {
 		validate(token, args, doc) {
 			const errors = [];
 			const owner = token.parentNode;
-			if (!require_validation_utils.hasAnyViewAnnotation(owner)) {
+			if (!require_view_validation.hasAnyViewAnnotation(owner)) {
 				errors.push({
 					message: "@db.view.having is only valid on @db.view interfaces",
 					severity: 1,
@@ -2312,7 +2252,7 @@ const dbViewAnnotations = { view: {
 				return errors;
 			}
 			const scope = viewHavingScope(owner);
-			if (args[0]?.queryNode && scope) errors.push(...require_validation_utils.validateQueryScope(args[0], scope, doc, "@db.view.having references the view's own fields unqualified"));
+			if (args[0]?.queryNode && scope) errors.push(...require_view_validation.validateQueryScope(args[0], scope, doc, "@db.view.having references the view's own fields unqualified"));
 			return errors;
 		}
 	})
@@ -2359,18 +2299,18 @@ const dbPlugin = (options) => ({
 						kind: "array",
 						of: "number"
 					},
-					documentation: "Represents a **vector embedding** (array of numbers) for **similarity search**.\n\n- Equivalent to `number[]` but explicitly marks the field as a vector embedding.\n- Each adapter maps this to its native vector type:\n  - **MongoDB** → BSON array\n  - **MySQL 9+** → `VECTOR(N)`\n  - **PostgreSQL** → pgvector `vector(N)`\n  - **SQLite** → JSON\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\nembedding: db.vector\n```\n"
+					documentation: (0, _atscript_core.annotationExample)("Represents a **vector embedding** (array of numbers) for **similarity search**.\n\n- Equivalent to `number[]` but explicitly marks the field as a vector embedding.\n- Each adapter maps this to its native vector type:\n  - **MongoDB** → BSON array\n  - **MySQL 9+** → `VECTOR(N)`\n  - **PostgreSQL** → pgvector `vector(N)`\n  - **SQLite** → JSON", "@db.search.vector 1536, \"cosine\"", "embedding: db.vector")
 				},
 				geoPoint: {
 					type: {
 						kind: "array",
 						of: "number"
 					},
-					documentation: "Represents a **geographic point** as a `[longitude, latitude]` tuple (GeoJSON coordinate order).\n\n- Equivalent to `number[]` of length 2, but explicitly marks the field as a geo point.\n- **Coordinate order is GeoJSON order: longitude first.**\n- Each adapter maps this to its native storage:\n  - **MongoDB** → GeoJSON `{ type: 'Point', coordinates: [lng, lat] }`\n  - **PostgreSQL** → PostGIS `geography(Point,4326)` (JSONB without PostGIS)\n  - **MySQL** → `POINT SRID 4326`\n  - **SQLite** → JSON `TEXT` (haversine-based search)\n\n**Example:**\n```atscript\n@db.index.geo\ngeo: db.geoPoint\n```\n"
+					documentation: (0, _atscript_core.annotationExample)("Represents a **geographic point** as a `[longitude, latitude]` tuple (GeoJSON coordinate order).\n\n- Equivalent to `number[]` of length 2, but explicitly marks the field as a geo point.\n- **Coordinate order is GeoJSON order: longitude first.**\n- Each adapter maps this to its native storage:\n  - **MongoDB** → GeoJSON `{ type: 'Point', coordinates: [lng, lat] }`\n  - **PostgreSQL** → PostGIS `geography(Point,4326)` (JSONB without PostGIS)\n  - **MySQL** → `POINT SRID 4326`\n  - **SQLite** → JSON `TEXT` (haversine-based search)", "@db.index.geo", "geo: db.geoPoint")
 				},
 				currencyCode: {
 					type: "string",
-					documentation: "Represents a **currency code** — typically ISO 4217 (`'USD'`, `'EUR'`, `'JPY'`) but accepts any uppercase alphanumeric code 2–10 chars long, so crypto and custom codes (`'BTC'`, `'USDC'`, `'POINTS'`) fit too.\n\nPair with `@db.amount.currency.ref 'fieldName'` on a `decimal` field to bind the amount to its row-level currency. The validator checks that the ref target resolves to this type (or a plain `string`).\n\n**Example:**\n```atscript\ncurrency: db.currencyCode\n@db.amount.currency.ref 'currency'\namount: decimal\n```\n",
+					documentation: (0, _atscript_core.annotationExample)("Represents a **currency code** — typically ISO 4217 (`'USD'`, `'EUR'`, `'JPY'`) but accepts any uppercase alphanumeric code 2–10 chars long, so crypto and custom codes (`'BTC'`, `'USDC'`, `'POINTS'`) fit too.\n\nPair with `@db.amount.currency.ref 'fieldName'` on a `decimal` field to bind the amount to its row-level currency. The validator checks that the ref target resolves to this type (or a plain `string`).", "currency: db.currencyCode", "@db.amount.currency.ref 'currency'", "amount: decimal"),
 					annotations: { "expect.pattern": [{
 						pattern: "^[A-Z0-9]{2,10}$",
 						message: "Invalid currency code (expected 2–10 uppercase letters or digits)"