@atscript/db 0.1.161 → 0.1.162

package/dist/plugin.mjs

@@ -1,10 +1,10 @@
-import { i as NULL_WHEN_EMPTY_AGGREGATE_FNS, o as SUPPORTED_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-B_sgl4mB.mjs";
-import { a as DERIVED_INCOMPATIBLE, i as DB_ENTITY_ANNOTATIONS, o as JSON_LEAF_TYPES, r as numericTypeProblem } from "./search-fields-CE8cmj9X.mjs";
+import { i as NULL_WHEN_EMPTY_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-DsS9UQVB.mjs";
+import { c as DERIVED_INCOMPATIBLE, l as JSON_LEAF_TYPES, o as numericTypeProblem, s as DB_ENTITY_ANNOTATIONS, t as ENCRYPTED_INCOMPATIBLE } from "./search-fields-0U0FAFGj.mjs";
 import "./consts-C_-5_pFq.mjs";
-import { C as validateExclusiveWith, S as searchFieldVerdict, T as validateSiblingStringField, _ as getParentTypeName, a as hasAnyViewAnnotation, b as primitiveBaseType, d as viewJoins, f as viewScopeTypes, g as getParentStruct, h as getNavTargetTypeName, i as forEachFieldRef, l as validateQueryScope, m as getDbTableOwner, n as findFKFieldsPointingTo, o as isAliasDecl, p as getAnnotationAlias, r as findViewCycle, s as isDbSourceDecl, t as earlierJoinTargets, u as validateRefArgument, v as integerMemberIndexProblem, w as validateFieldBaseType, x as refActionAnnotation, y as isNullableUnion } from "./validation-utils-BGjqc2jU.mjs";
+import { A as getParentTypeName, B as validateSiblingStringField, C as viewJoins, D as getDbTableOwner, E as getAnnotationAlias, F as refActionAnnotation, I as searchFieldVerdict, L as validateExclusiveWith, M as isNullableUnion, O as getNavTargetTypeName, P as primitiveBaseType, R as validateFieldBaseType, S as validateRefArgument, T as effectiveAnnotationNames, _ as hasAnyViewAnnotation, c as refuseCiphertext, d as viewFieldSeals, f as viewProps, g as forEachFieldRef, h as findViewCycle, i as encryptedTypeSearchProblem, j as integerMemberIndexProblem, k as getParentStruct, l as sealedSearchProblem, m as findFKFieldsPointingTo, o as isNavProp, p as earlierJoinTargets, s as jsonChainInfo, u as validateViewInterface, v as isAliasDecl, w as viewScopeTypes, x as validateQueryScope, y as isDbSourceDecl, z as validateIncompatible } from "./view-validation-QbqqXEAM.mjs";
+import { AnnotationSpec, DEFAULT_FORMAT, annotationExample, getFieldsForType, isArray, isInterface, isPrimitive, isProp, isQueryComparison, isQueryLogical, isRef, isStructure } from "@atscript/core";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { AnnotationSpec, DEFAULT_FORMAT, getFieldsForType, isArray, isInterface, isPrimitive, isProp, isQueryComparison, isQueryLogical, isRef, isStructure } from "@atscript/core";
 //#region src/plugin/manifest.ts
 /**
 * Renders the model-manifest module: an inventory of every exported
@@ -333,7 +333,7 @@ const VIEW_SOURCE_ARGUMENT = {
 * @since 0.1.141
 */
 const dbAliasAnnotations = { alias: new 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: 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: {
@@ -370,7 +370,7 @@ const dbAliasAnnotations = { alias: new AnnotationSpec({
 const CURRENCY_CODE_PATTERN = /^[A-Z0-9]{2,10}$/;
 const dbAmountAnnotations = { amount: { currency: {
 	$self: new 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: 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: {
@@ -384,7 +384,7 @@ const dbAmountAnnotations = { amount: { currency: {
 			errors.push(...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)`,
@@ -395,7 +395,7 @@ const dbAmountAnnotations = { amount: { currency: {
 		}
 	}),
 	ref: new 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: 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,
@@ -413,114 +413,14 @@ const dbAmountAnnotations = { amount: { currency: {
 			}, {
 				key: "db.unit.ref",
 				displayName: "@db.unit.ref"
-			}]));
+			}], doc));
 			errors.push(...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 = SUPPORTED_AGGREGATE_FNS.filter((fn) => !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 && 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 = isArray(step.def);
-		if (isArr) info.viaArray = true;
-		if (info.jsonRoot === void 0 && (isJsonProp || isArr)) info.jsonRoot = i;
-		if (i === chain.length) info.leafType = 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 (isInterface(owner)) return owner.props;
-	const def = owner.getDefinition();
-	return def && 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 && 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 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 || !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
@@ -540,7 +440,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 (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;
@@ -577,9 +477,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 = 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 = getParentStruct(token);
+	if (!struct?.ownerNode || !isInterface(struct.ownerNode)) fail(`${tag} must sit on a top-level field of the table, not inside a nested object`);
+	errors.push(...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 || !isRef(def)) return true;
+	const leaf = doc.unwindType(def.id, def.chain)?.def;
+	if (primitiveBaseType(leaf) !== "number") return true;
+	if (leaf.tags?.has("int")) return true;
+	return effectiveAnnotationNames(field, doc).has("expect.int");
+}
 const dbColumnAnnotations = {
 	patch: { strategy: new AnnotationSpec({
-		description: "Defines the **patching strategy** for updating nested objects.\n\n- **\"replace\"** → The field or object will be **fully replaced**.\n- **\"merge\"** → The field or object will be **merged recursively** (applies only to objects, not arrays).\n\n**Example:**\n```atscript\n@db.patch.strategy \"merge\"\nsettings: {\n  notifications: boolean\n  preferences: {\n    theme: string\n  }\n}\n```\n",
+		description: 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,
@@ -609,7 +551,7 @@ const dbColumnAnnotations = {
 	}) },
 	column: {
 		$self: new 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: 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: {
@@ -619,7 +561,7 @@ const dbColumnAnnotations = {
 			}
 		}),
 		renamed: new 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: 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: {
@@ -629,7 +571,7 @@ const dbColumnAnnotations = {
 			}
 		}),
 		collate: new 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: 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: {
@@ -647,7 +589,7 @@ const dbColumnAnnotations = {
 			}
 		}),
 		precision: new 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: 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: [{
@@ -664,7 +606,7 @@ const dbColumnAnnotations = {
 			}
 		}),
 		derived: new 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: 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,
@@ -739,11 +681,13 @@ const dbColumnAnnotations = {
 		filterable: columnCapability("filterable", "filtering"),
 		sortable: columnCapability("sortable", "sorting"),
 		searchable: new AnnotationSpec({
-			description: "Includes this column in the generic `$search` fallback: when the adapter reports no native search capability (no FTS / Atlas index configured), the readable controller matches the `$search` term as a case-insensitive substring across all `@db.column.searchable` fields (`$or`). Where adapter-native search IS available it wins and this annotation is not consulted. The term is escaped literally — no user-supplied regex. String 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: 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 sealed = sealedSearchProblem(token, doc, "@db.column.searchable");
+				if (sealed) return [sealed];
 				const verdict = searchFieldVerdict(token.parentNode, doc);
 				if (!("problem" in verdict)) return [];
 				return [{
@@ -755,7 +699,7 @@ const dbColumnAnnotations = {
 		}),
 		version: {
 			$self: new AnnotationSpec({
-				description: "Marks a numeric column as the row's version for optimistic concurrency control (OCC). The adapter auto-increments this column on every UPDATE, and callers may pass `$cas: { <col>: N }` in a write payload to make the update conditional on the current version. Direct writes to the version column (as plain SET, `$inc`, or `$mul`) are rejected. Fields marked `@db.column.version.exempt` do not bump it.\n\n**Constraints:**\n- At most one version column per table.\n- Must resolve to an integer type (`int`, `int32`, `int64`, etc.).\n- Default value on insert is `0`.\n\n**Example:**\n```atscript\n@db.column.version\nversion: int\n```\n",
+				description: 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) {
@@ -779,7 +723,7 @@ const dbColumnAnnotations = {
 				}
 			}),
 			exempt: new AnnotationSpec({
-				description: "Marks a field as **version-exempt**: a patch that writes ONLY exempt fields (`updateOne` / `bulkUpdate` without `$cas`, `updateMany`) leaves `@db.column.version` unchanged and adds no version check. A patch touching any other field bumps as usual; `$cas`, replace and `touchMany` always bump. Use it for derived/reporting columns refreshed in the background (scores, counters, caches) so they do not invalidate versions held by editors. On an object field it covers every nested field.\n\n**Example:**\n```atscript\n@db.column.version\nversion: number.int\n@db.column.version.exempt\nscore: number\n```\n",
+				description: 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,
@@ -791,7 +735,7 @@ const dbColumnAnnotations = {
 	},
 	default: {
 		$self: new 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: 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: {
@@ -801,7 +745,7 @@ const dbColumnAnnotations = {
 			}
 		}),
 		increment: new 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: 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: {
@@ -821,7 +765,7 @@ const dbColumnAnnotations = {
 			}
 		}),
 		uuid: new 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: 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) {
@@ -829,7 +773,7 @@ const dbColumnAnnotations = {
 			}
 		}),
 		now: new 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: 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) {
@@ -837,23 +781,34 @@ const dbColumnAnnotations = {
 			}
 		})
 	},
-	onUpdate: { now: new 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 = 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;
-		}
-	}) },
+	onUpdate: {
+		now: new AnnotationSpec({
+			description: 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 = 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 AnnotationSpec({
+			description: 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);
+			}
+		})
+	},
 	json: new 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: 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) {
@@ -862,7 +817,7 @@ const dbColumnAnnotations = {
 			if (definition && isRef(definition)) {
 				const unwound = doc.unwindType(definition.id, definition.chain);
 				if (unwound && 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
 				});
@@ -871,7 +826,7 @@ const dbColumnAnnotations = {
 		}
 	}),
 	ignore: new 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: 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) {
@@ -885,38 +840,18 @@ const dbColumnAnnotations = {
 		}
 	}),
 	encrypted: new 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: 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 = encryptedTypeSearchProblem(token, doc);
+			const errors = validateIncompatible(token, "@db.encrypted", ENCRYPTED_INCOMPATIBLE, doc);
+			return typeProblem ? [typeProblem, ...errors] : errors;
 		}
 	}),
 	writeOnly: new AnnotationSpec({
-		description: "Marks a field as write-only over HTTP: it may be set through insert/update/replace payloads but NEVER appears in read responses — the readable controller excludes it from every projection, rejects filtering/sorting/grouping on it, and `/meta` serves its TYPE (flagged `writeOnly`) so client preflight validation and generated forms still know its shape. The classic case is a sealed secret (pair with `@db.encrypted`): writable via generic forms, unreadable by anyone.\n\nServer-side code reading through `AtscriptDbTable` still sees the value — the seal is an HTTP-layer contract, not a storage one. 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: 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,
@@ -938,15 +873,9 @@ 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 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: 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,
@@ -1045,7 +974,7 @@ function validateCompute(token, args, doc) {
 		error("@db.compute is only valid on a field of a @db.view.for view");
 		return errors;
 	}
-	errors.push(...validateExclusiveWith(token, "@db.compute", EXCLUSIVE_WITH));
+	errors.push(...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;
@@ -1068,7 +997,7 @@ function validateCompute(token, args, doc) {
 	return errors;
 }
 const dbComputeAnnotations = { compute: new 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: 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: {
@@ -1083,7 +1012,7 @@ const dbComputeAnnotations = { compute: new AnnotationSpec({
 //#region src/plugin/annotations/index-ann.ts
 const dbIndexAnnotations = { index: {
 	plain: new 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: 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,
@@ -1102,7 +1031,7 @@ const dbIndexAnnotations = { index: {
 		}]
 	}),
 	unique: new 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: 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,
@@ -1115,9 +1044,11 @@ const dbIndexAnnotations = { index: {
 		}
 	}),
 	fulltext: new 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: 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 sealed = sealedSearchProblem(token, doc, "@db.index.fulltext");
+			if (sealed) return [sealed];
 			const verdict = searchFieldVerdict(field, doc);
 			if ("problem" in verdict) return [{
 				message: `@db.index.fulltext needs a string or an integer field — "${field.id}" ${verdict.problem}`,
@@ -1156,7 +1087,7 @@ const dbIndexAnnotations = { index: {
 		}]
 	}),
 	geo: new 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: 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,
@@ -1165,7 +1096,8 @@ const dbIndexAnnotations = { index: {
 			name: "name",
 			type: "string",
 			description: "Index name. Defaults to the field name."
-		}
+		},
+		validate: refuseCiphertext("@db.index.geo")
 	})
 } };
 //#endregion
@@ -1197,7 +1129,7 @@ function checkCompositeFkCoverage(token, alias, refTypeName, targetStruct, targe
 }
 const dbRelAnnotations = { rel: {
 	FK: new AnnotationSpec({
-		description: "Declares a foreign key reference on this field. The field must use a chain reference type (e.g., `User.id`) whose target is a primary key (`@meta.id`) or unique (`@db.index.unique`) field.\n\n**Dual role:**\n- On a `@db.table` interface, `@db.rel.FK` additionally drives DB-relation semantics —   relation loading with `@db.rel.to` / `@db.rel.from`, junction pairing with `@db.rel.via`, etc.\n- On any other interface (value-help sources, WF forms, plain interfaces), `@db.rel.FK`   acts purely as the value-help indicator: the client-side picker resolver uses it to   decide which fields render a value-help picker. The target's `@db.http.path` (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: 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: {
@@ -1287,7 +1219,7 @@ const dbRelAnnotations = { rel: {
 		}
 	}),
 	to: new 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: 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: {
@@ -1371,7 +1303,7 @@ const dbRelAnnotations = { rel: {
 		}
 	}),
 	from: new 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: 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: {
@@ -1460,7 +1392,7 @@ const dbRelAnnotations = { rel: {
 	onDelete: refActionAnnotation("onDelete"),
 	onUpdate: refActionAnnotation("onUpdate"),
 	via: new 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: 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: {
@@ -1524,7 +1456,7 @@ const dbRelAnnotations = { rel: {
 		}
 	}),
 	filterable: new 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: 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) {
@@ -1539,7 +1471,7 @@ const dbRelAnnotations = { rel: {
 		}
 	}),
 	filter: new 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: 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: {
@@ -1604,8 +1536,9 @@ function forEachComparison(expr, fn) {
 const dbSearchAnnotations = { search: {
 	vector: {
 		$self: new 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: 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: refuseCiphertext("@db.search.vector"),
 			passedWhenReferred: false,
 			multiple: false,
 			argument: [
@@ -1649,7 +1582,7 @@ const dbSearchAnnotations = { search: {
 			]
 		}),
 		threshold: new 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: 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,
@@ -1662,8 +1595,9 @@ const dbSearchAnnotations = { search: {
 		})
 	},
 	filter: new 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: 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: refuseCiphertext("@db.search.filter"),
 		passedWhenReferred: false,
 		multiple: true,
 		argument: {
@@ -1681,7 +1615,7 @@ const dbSearchAnnotations = { search: {
 * read sorts by it without a `$nulls` entry for it.
 */
 const dbSortAnnotations = { sort: { nulls: new 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: 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,
@@ -1707,6 +1641,10 @@ const dbSortAnnotations = { sort: { nulls: new AnnotationSpec({
 			fail("@db.sort.nulls on a @db.encrypted field — encrypted fields are not sortable");
 			return errors;
 		}
+		if (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 && isRef(def)) leaf = doc.unwindType(def.id, def.chain)?.def;
@@ -1727,7 +1665,7 @@ const dbTableAnnotations = {
 		filterable: tableCapability("filterable"),
 		sortable: tableCapability("sortable"),
 		$self: new 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: 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: {
@@ -1748,7 +1686,7 @@ const dbTableAnnotations = {
 			}
 		}),
 		renamed: new 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: 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: {
@@ -1767,7 +1705,7 @@ const dbTableAnnotations = {
 			}
 		}),
 		preferredId: { uniqueIndex: new 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: 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,
@@ -1815,7 +1753,7 @@ const dbTableAnnotations = {
 		}) }
 	},
 	schema: new 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: annotationExample("Assigns the entity to a database schema/namespace.", "@db.table \"users\"", "@db.schema \"auth\"", "export interface User { ... }"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		argument: {
@@ -1825,7 +1763,7 @@ const dbTableAnnotations = {
 		}
 	}),
 	space: new 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: 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: {
@@ -1835,7 +1773,7 @@ const dbTableAnnotations = {
 		}
 	}),
 	http: { path: new AnnotationSpec({
-		description: "HTTP endpoint path where this table is served. Used by the UI for value-help on FK fields. 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: 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: {
@@ -1845,7 +1783,7 @@ const dbTableAnnotations = {
 		}
 	}) },
 	sync: { method: new 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: 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: {
@@ -1856,7 +1794,7 @@ const dbTableAnnotations = {
 		}
 	}) },
 	depth: { limit: new 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: 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,
@@ -1910,19 +1848,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 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: 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,
@@ -1949,7 +1889,7 @@ function tableCapability(capability) {
 const UNIT_HOST_TYPES = ["decimal", "number"];
 const dbUnitAnnotations = { unit: {
 	$self: new 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: 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: {
@@ -1963,12 +1903,12 @@ const dbUnitAnnotations = { unit: {
 			errors.push(...validateExclusiveWith(token, "@db.unit", [{
 				key: "db.unit.ref",
 				displayName: "@db.unit.ref"
-			}]));
+			}], doc));
 			return errors;
 		}
 	}),
 	ref: new 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: 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,
@@ -1986,7 +1926,7 @@ const dbUnitAnnotations = { unit: {
 			}, {
 				key: "db.amount.currency.ref",
 				displayName: "@db.amount.currency.ref"
-			}]));
+			}], doc));
 			errors.push(...validateSiblingStringField(token, args, doc, "@db.unit.ref"));
 			return errors;
 		}
@@ -2051,7 +1991,7 @@ function orderKeyProblem(doc, target, path) {
 }
 const dbViewAnnotations = { view: {
 	$self: new 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: 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: {
@@ -2071,7 +2011,7 @@ const dbViewAnnotations = { view: {
 		}
 	}),
 	for: new 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: 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: {
@@ -2100,7 +2040,7 @@ const dbViewAnnotations = { view: {
 		}
 	}),
 	joins: new 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: 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,
@@ -2185,7 +2125,7 @@ const dbViewAnnotations = { view: {
 		}
 	}),
 	filter: new 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: 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: {
@@ -2220,7 +2160,7 @@ const dbViewAnnotations = { view: {
 		}
 	}),
 	materialized: new 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: 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) {
@@ -2235,7 +2175,7 @@ const dbViewAnnotations = { view: {
 		}
 	}),
 	renamed: new 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: 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: {
@@ -2255,7 +2195,7 @@ const dbViewAnnotations = { view: {
 		}
 	}),
 	having: new 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: 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: {
@@ -2323,18 +2263,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: 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: 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: 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)"