@atscript/db 0.1.38

package/dist/plugin.mjs

@@ -0,0 +1,989 @@
+import { findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, refActionAnnotation, validateFieldBaseType, validateQueryScope, validateRefArgument } from "./validation-utils-DhR_mtKa.mjs";
+import { AnnotationSpec, isArray, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
+
+//#region packages/db/src/plugin/annotations/agg.ts
+const dbAggAnnotations = { agg: {
+	sum: new AnnotationSpec({
+		description: "Declares a view field as SUM of a source column.",
+		nodeType: ["prop"],
+		argument: {
+			name: "field",
+			type: "string",
+			description: "Source column name to sum."
+		},
+		validate(token, _args, doc) {
+			return validateFieldBaseType(token, doc, "@db.agg.sum", ["number", "decimal"]);
+		}
+	}),
+	avg: new AnnotationSpec({
+		description: "Declares a view field as AVG of a source column.",
+		nodeType: ["prop"],
+		argument: {
+			name: "field",
+			type: "string",
+			description: "Source column name to average."
+		},
+		validate(token, _args, doc) {
+			return validateFieldBaseType(token, doc, "@db.agg.avg", ["number", "decimal"]);
+		}
+	}),
+	count: new AnnotationSpec({
+		description: "Declares a view field as COUNT. Without argument: COUNT(*). With field name argument: COUNT(field) (non-null count).",
+		nodeType: ["prop"],
+		argument: {
+			name: "field",
+			type: "string",
+			optional: true,
+			description: "Source column name to count non-null values. Omit for COUNT(*)."
+		},
+		validate(token, _args, doc) {
+			return validateFieldBaseType(token, doc, "@db.agg.count", ["number"]);
+		}
+	}),
+	min: new AnnotationSpec({
+		description: "Declares a view field as MIN of a source column.",
+		nodeType: ["prop"],
+		argument: {
+			name: "field",
+			type: "string",
+			description: "Source column name."
+		}
+	}),
+	max: new AnnotationSpec({
+		description: "Declares a view field as MAX of a source column.",
+		nodeType: ["prop"],
+		argument: {
+			name: "field",
+			type: "string",
+			description: "Source column name."
+		}
+	})
+} };
+
+//#endregion
+//#region packages/db/src/plugin/annotations/column.ts
+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",
+		nodeType: ["prop"],
+		multiple: false,
+		argument: {
+			name: "strategy",
+			type: "string",
+			description: "The **patch strategy** for this field: `\"replace\"` (default) or `\"merge\"`.",
+			values: ["replace", "merge"]
+		},
+		validate(token, args, doc) {
+			const field = token.parentNode;
+			const errors = [];
+			const definition = field.getDefinition();
+			if (!definition) return errors;
+			let wrongType = false;
+			if (isRef(definition)) {
+				const def = doc.unwindType(definition.id, definition.chain)?.def;
+				if (!isStructure(def) && !isInterface(def) && !isArray(def)) wrongType = true;
+			} else if (!isStructure(definition) && !isInterface(definition) && !isArray(definition)) wrongType = true;
+			if (wrongType) errors.push({
+				message: `@db.patch.strategy requires a field of type object or array`,
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	}) },
+	column: {
+		$self: new AnnotationSpec({
+			description: "Overrides the physical column name in the database. For nested (flattened) fields, the parent prefix is still prepended automatically.\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",
+			nodeType: ["prop"],
+			argument: {
+				name: "name",
+				type: "string",
+				description: "The column/field name (without parent prefix for nested fields)."
+			}
+		}),
+		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.\n\n**Example:**\n```atscript\n@db.column.renamed \"zip\"\npostalCode: string\n// Renames address__zip → address__postalCode\n```\n",
+			nodeType: ["prop"],
+			argument: {
+				name: "oldName",
+				type: "string",
+				description: "The old local field name (parent prefix is reconstructed automatically)."
+			}
+		}),
+		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",
+			nodeType: ["prop"],
+			argument: {
+				name: "collation",
+				type: "string",
+				values: [
+					"binary",
+					"nocase",
+					"unicode"
+				],
+				description: "Portable collation mode: \"binary\", \"nocase\", or \"unicode\"."
+			},
+			validate(token, args, doc) {
+				return validateFieldBaseType(token, doc, "@db.column.collate", "string");
+			}
+		}),
+		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",
+			nodeType: ["prop"],
+			argument: [{
+				name: "precision",
+				type: "number",
+				description: "Total number of significant digits."
+			}, {
+				name: "scale",
+				type: "number",
+				description: "Number of digits after the decimal point."
+			}],
+			validate(token, args, doc) {
+				return validateFieldBaseType(token, doc, "@db.column.precision", ["number", "decimal"]);
+			}
+		}),
+		dimension: new AnnotationSpec({
+			description: "Marks a field as a dimension — groupable in aggregate queries ($groupBy). Dimension fields automatically receive a database index during schema sync.",
+			nodeType: ["prop"]
+		}),
+		measure: new AnnotationSpec({
+			description: "Marks a field as a measure — aggregatable in aggregate queries (sum, avg, count, min, max). Only valid on numeric or decimal fields.",
+			nodeType: ["prop"],
+			validate(token, _args, doc) {
+				return validateFieldBaseType(token, doc, "@db.column.measure", ["number", "decimal"]);
+			}
+		})
+	},
+	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",
+			nodeType: ["prop"],
+			argument: {
+				name: "value",
+				type: "string",
+				description: "Static default value. Strings used as-is; other types parsed via JSON.parse()."
+			}
+		}),
+		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",
+			nodeType: ["prop"],
+			argument: {
+				optional: true,
+				name: "start",
+				type: "number",
+				description: "Starting value for the auto-increment sequence. Adapter-specific behavior; some adapters may ignore this."
+			},
+			validate(token, args, doc) {
+				return validateFieldBaseType(token, doc, "db.default.increment", "number");
+			}
+		}),
+		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",
+			nodeType: ["prop"],
+			validate(token, args, doc) {
+				return validateFieldBaseType(token, doc, "db.default.uuid", "string");
+			}
+		}),
+		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",
+			nodeType: ["prop"],
+			validate(token, args, doc) {
+				return validateFieldBaseType(token, doc, "db.default.now", ["number", "string"]);
+			}
+		})
+	},
+	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",
+		nodeType: ["prop"],
+		validate(token, _args, doc) {
+			const errors = [];
+			const field = token.parentNode;
+			const definition = field.getDefinition();
+			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",
+					severity: 2,
+					range: token.range
+				});
+			}
+			return errors;
+		}
+	}),
+	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",
+		nodeType: ["prop"],
+		validate(token, args, doc) {
+			const errors = [];
+			const field = token.parentNode;
+			if (field.countAnnotations("meta.id") > 0) errors.push({
+				message: `@db.ignore cannot coexist with @meta.id — a field cannot be both a primary key and excluded from the database`,
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	})
+};
+
+//#endregion
+//#region packages/db/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",
+		nodeType: ["prop"],
+		multiple: true,
+		mergeStrategy: "append",
+		argument: [{
+			optional: true,
+			name: "name",
+			type: "string",
+			description: "Index name / composite group name."
+		}, {
+			optional: true,
+			name: "sort",
+			type: "string",
+			values: ["asc", "desc"],
+			description: "Sort direction. Defaults to \"asc\"."
+		}]
+	}),
+	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",
+		nodeType: ["prop"],
+		multiple: true,
+		mergeStrategy: "append",
+		argument: {
+			optional: true,
+			name: "name",
+			type: "string",
+			description: "Index name / composite group name."
+		}
+	}),
+	fulltext: new AnnotationSpec({
+		description: "Full-text search index. Fields sharing the same index name form a composite full-text index.\n\n**Example:**\n```atscript\n@db.index.fulltext \"ft_content\"\ntitle: string\n\n@db.index.fulltext \"ft_content\", 5\nbio: string\n```\n",
+		nodeType: ["prop"],
+		multiple: true,
+		mergeStrategy: "append",
+		argument: [{
+			optional: true,
+			name: "name",
+			type: "string",
+			description: "Index name / composite group name."
+		}, {
+			optional: true,
+			name: "weight",
+			type: "number",
+			description: "Field importance in search results (higher = more relevant). Defaults to `1`. Supported by databases with weighted fulltext (e.g., MongoDB, PostgreSQL)."
+		}]
+	})
+} };
+
+//#endregion
+//#region packages/db/src/plugin/annotations/rel.ts
+const dbRelAnnotations = { rel: {
+	FK: new AnnotationSpec({
+		description: "Declares a foreign key constraint on this field. The field must use a chain reference type (e.g., `User.id`) to specify the FK target.\n\n**Example:**\n```atscript\n@db.rel.FK\nauthorId: User.id\n\n// With alias (required when multiple FKs point to the same type)\n@db.rel.FK \"author\"\nauthorId: User.id\n```\n",
+		nodeType: ["prop"],
+		argument: {
+			optional: true,
+			name: "alias",
+			type: "string",
+			description: "Alias for pairing with @db.rel.to. Required when multiple FKs point to the same target type."
+		},
+		validate(token, args, doc) {
+			const errors = [];
+			const field = token.parentNode;
+			const alias = args[0]?.text;
+			const owner = getDbTableOwner(token);
+			if (!owner || owner.countAnnotations("db.table") === 0) errors.push({
+				message: "@db.rel.FK is only valid on fields of a @db.table interface",
+				severity: 1,
+				range: token.range
+			});
+			if (field.countAnnotations("db.rel.to") > 0 || field.countAnnotations("db.rel.from") > 0) errors.push({
+				message: "A field cannot be both a foreign key and a navigational property",
+				severity: 1,
+				range: token.range
+			});
+			const definition = field.getDefinition();
+			if (!definition || !isRef(definition) || !definition.hasChain) {
+				errors.push({
+					message: `@db.rel.FK requires a chain reference type (e.g. User.id), got scalar type`,
+					severity: 1,
+					range: token.range
+				});
+				return errors;
+			}
+			const ref = definition;
+			const refTypeName = ref.id;
+			const chainFields = ref.chain.map((c) => c.text);
+			const targetUnwound = doc.unwindType(refTypeName);
+			if (targetUnwound) {
+				const targetDef = targetUnwound.def;
+				if (isInterface(targetDef) || isStructure(targetDef)) {
+					const struct = isInterface(targetDef) ? targetDef.getDefinition() : targetDef;
+					if (struct && isStructure(struct) && chainFields.length > 0) {
+						const targetProp = struct.props.get(chainFields[0]);
+						if (targetProp) {
+							if (targetProp.countAnnotations("meta.id") === 0 && targetProp.countAnnotations("db.index.unique") === 0) errors.push({
+								message: `@db.rel.FK target '${refTypeName}.${chainFields.join(".")}' is not a primary key (@meta.id) or unique (@db.index.unique) field`,
+								severity: 1,
+								range: token.range
+							});
+							const propDef = targetProp.getDefinition();
+							if (propDef && isRef(propDef)) {
+								const propUnwound = targetUnwound.doc.unwindType(propDef.id, propDef.chain);
+								if (propUnwound && !isPrimitive(propUnwound.def)) errors.push({
+									message: `Foreign key field must resolve to a scalar type (number, string, etc.), got '${propDef.id}'`,
+									severity: 1,
+									range: token.range
+								});
+							} else if (propDef && !isPrimitive(propDef)) errors.push({
+								message: `Foreign key field must resolve to a scalar type (number, string, etc.)`,
+								severity: 1,
+								range: token.range
+							});
+						}
+					}
+				}
+			}
+			if (!alias) {
+				const struct = getParentStruct(token);
+				if (struct) {
+					let sameTargetCount = 0;
+					for (const [, prop] of struct.props) {
+						if (prop.countAnnotations("db.rel.FK") === 0) continue;
+						const def = prop.getDefinition();
+						if (!def || !isRef(def)) continue;
+						const r = def;
+						if (!r.hasChain) continue;
+						if (r.id === refTypeName) {
+							if (!getAnnotationAlias(prop, "db.rel.FK")) sameTargetCount++;
+						}
+					}
+					if (sameTargetCount > 1) errors.push({
+						message: `Multiple @db.rel.FK fields resolve to type '${refTypeName}' — add alias to disambiguate`,
+						severity: 1,
+						range: token.range
+					});
+				}
+			}
+			return errors;
+		}
+	}),
+	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",
+		nodeType: ["prop"],
+		argument: {
+			optional: true,
+			name: "alias",
+			type: "string",
+			description: "Match a local @db.rel.FK by alias."
+		},
+		validate(token, args, doc) {
+			const errors = [];
+			const field = token.parentNode;
+			const alias = args[0]?.text;
+			const owner = 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,
+				range: token.range
+			});
+			if (field.countAnnotations("db.rel.FK") > 0) errors.push({
+				message: "A field cannot be both a foreign key and a navigational property",
+				severity: 1,
+				range: token.range
+			});
+			const targetTypeName = getNavTargetTypeName(field);
+			if (!targetTypeName) return errors;
+			const unwound = doc.unwindType(targetTypeName);
+			if (unwound) {
+				const targetDef = unwound.def;
+				const targetNode = isInterface(targetDef) ? targetDef : undefined;
+				if (!targetNode || targetNode.countAnnotations("db.table") === 0) errors.push({
+					message: `@db.rel.to target '${targetTypeName}' is not a @db.table entity`,
+					severity: 1,
+					range: token.range
+				});
+			}
+			const fieldDef = field.getDefinition();
+			if (fieldDef && fieldDef.entity === "group" && fieldDef.op === "|") errors.push({
+				message: "@db.rel.to does not support union types — use separate relations",
+				severity: 1,
+				range: token.range
+			});
+			const struct = 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 = getAnnotationAlias(prop, "db.rel.to");
+					if ((alias || undefined) === (propAlias || undefined)) {
+						const otherTarget = getNavTargetTypeName(prop);
+						if (otherTarget === targetTypeName) {
+							errors.push({
+								message: `Duplicate @db.rel.to '${alias || targetTypeName}' — only one forward navigational property per alias`,
+								severity: 1,
+								range: token.range
+							});
+							break;
+						}
+					}
+				}
+				if (alias) {
+					const matches = findFKFieldsPointingTo(doc, struct, targetTypeName, alias);
+					if (matches.length === 0) errors.push({
+						message: `No @db.rel.FK '${alias}' found on this interface`,
+						severity: 1,
+						range: token.range
+					});
+				} else {
+					const matches = 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,
+						range: token.range
+					});
+else if (matches.length > 1) errors.push({
+						message: `Multiple @db.rel.FK fields point to '${targetTypeName}' — add alias to disambiguate`,
+						severity: 1,
+						range: token.range
+					});
+				}
+			}
+			return errors;
+		}
+	}),
+	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",
+		nodeType: ["prop"],
+		argument: {
+			optional: true,
+			name: "alias",
+			type: "string",
+			description: "Match a @db.rel.FK on the target interface by alias."
+		},
+		validate(token, args, doc) {
+			const errors = [];
+			const field = token.parentNode;
+			const alias = args[0]?.text;
+			const owner = 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,
+				range: token.range
+			});
+			if (field.countAnnotations("db.rel.FK") > 0) errors.push({
+				message: "A field cannot be both a foreign key and a navigational property",
+				severity: 1,
+				range: token.range
+			});
+			const targetTypeName = getNavTargetTypeName(field);
+			if (!targetTypeName) return errors;
+			const unwound = doc.unwindType(targetTypeName);
+			if (!unwound) return errors;
+			const targetDef = unwound.def;
+			const targetDoc = unwound.doc;
+			if (!isInterface(targetDef) || targetDef.countAnnotations("db.table") === 0) {
+				errors.push({
+					message: `@db.rel.from target '${targetTypeName}' is not a @db.table entity`,
+					severity: 1,
+					range: token.range
+				});
+				return errors;
+			}
+			const struct = 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 = getAnnotationAlias(prop, "db.rel.from");
+					if ((alias || undefined) === (propAlias || undefined)) {
+						const otherTarget = getNavTargetTypeName(prop);
+						if (otherTarget === targetTypeName) {
+							errors.push({
+								message: `Duplicate @db.rel.from '${alias || targetTypeName}' — only one inverse navigational property per alias`,
+								severity: 1,
+								range: token.range
+							});
+							break;
+						}
+					}
+				}
+			}
+			const thisTypeName = getParentTypeName(token);
+			if (!thisTypeName) return errors;
+			const matches = findFKFieldsPointingTo(targetDoc, targetDef, thisTypeName, alias);
+			if (alias) {
+				if (matches.length === 0) errors.push({
+					message: `No @db.rel.FK '${alias}' found on '${targetTypeName}'`,
+					severity: 1,
+					range: token.range
+				});
+			} else if (matches.length === 0) errors.push({
+				message: `No @db.rel.FK on '${targetTypeName}' points to '${thisTypeName}'`,
+				severity: 1,
+				range: token.range
+			});
+else if (matches.length > 1) errors.push({
+				message: `'${targetTypeName}' has multiple @db.rel.FK fields pointing to '${thisTypeName}' — add alias`,
+				severity: 1,
+				range: token.range
+			});
+			const fieldDef = field.getDefinition();
+			if (!isArray(fieldDef) && matches.length === 1) {
+				const fkProp = matches[0].prop;
+				if (fkProp.countAnnotations("db.index.unique") === 0) errors.push({
+					message: `@db.rel.from '${field.id}' has singular type '${targetTypeName}' (1:1) but the FK on '${targetTypeName}' is not @db.index.unique — did you mean '${targetTypeName}[]' (1:N)?`,
+					severity: 2,
+					range: token.range
+				});
+			}
+			return errors;
+		}
+	}),
+	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",
+		nodeType: ["prop"],
+		argument: {
+			name: "junction",
+			type: "ref",
+			description: "The junction table type (must have @db.table and @db.rel.FK fields pointing to both sides)."
+		},
+		validate(token, args, doc) {
+			const errors = [];
+			const field = token.parentNode;
+			if (field.countAnnotations("db.rel.to") > 0 || field.countAnnotations("db.rel.from") > 0) errors.push({
+				message: "@db.rel.via is self-sufficient — cannot be combined with @db.rel.to or @db.rel.from",
+				severity: 1,
+				range: token.range
+			});
+			const definition = field.getDefinition();
+			if (!isArray(definition)) errors.push({
+				message: "@db.rel.via requires an array type (e.g. Tag[])",
+				severity: 1,
+				range: token.range
+			});
+			if (!args[0]) return errors;
+			const junctionName = args[0].text;
+			errors.push(...validateRefArgument(args[0], doc, { requireDbTable: true }));
+			if (errors.length > 0) return errors;
+			const junctionUnwound = doc.unwindType(junctionName);
+			if (!junctionUnwound) return errors;
+			const junctionDef = junctionUnwound.def;
+			if (!isInterface(junctionDef)) return errors;
+			const thisTypeName = getParentTypeName(token);
+			const targetTypeName = getNavTargetTypeName(field);
+			if (!thisTypeName || !targetTypeName) return errors;
+			const fksToThis = findFKFieldsPointingTo(junctionUnwound.doc, junctionDef, thisTypeName);
+			if (fksToThis.length === 0) errors.push({
+				message: `Junction '${junctionName}' has no @db.rel.FK pointing to '${thisTypeName}'`,
+				severity: 1,
+				range: args[0].range
+			});
+else if (fksToThis.length > 1) errors.push({
+				message: `Junction '${junctionName}' has multiple @db.rel.FK pointing to '${thisTypeName}' — not supported`,
+				severity: 1,
+				range: args[0].range
+			});
+			if (targetTypeName !== thisTypeName) {
+				const fksToTarget = findFKFieldsPointingTo(junctionUnwound.doc, junctionDef, targetTypeName);
+				if (fksToTarget.length === 0) errors.push({
+					message: `Junction '${junctionName}' has no @db.rel.FK pointing to '${targetTypeName}'`,
+					severity: 1,
+					range: args[0].range
+				});
+else if (fksToTarget.length > 1) errors.push({
+					message: `Junction '${junctionName}' has multiple @db.rel.FK pointing to '${targetTypeName}' — not supported`,
+					severity: 1,
+					range: args[0].range
+				});
+			}
+			return errors;
+		}
+	}),
+	filter: new AnnotationSpec({
+		description: "Applies a filter to a navigational property, restricting which related records are loaded.\n\n**Example:**\n```atscript\n@db.rel.from\n@db.rel.filter `Post.published = true`\npublishedPosts: Post[]\n```\n",
+		nodeType: ["prop"],
+		argument: {
+			name: "condition",
+			type: "query",
+			description: "Filter expression restricting which related records are loaded."
+		},
+		validate(token, args, doc) {
+			const errors = [];
+			const field = token.parentNode;
+			const hasTo = field.countAnnotations("db.rel.to") > 0;
+			const hasFrom = field.countAnnotations("db.rel.from") > 0;
+			const hasVia = field.countAnnotations("db.rel.via") > 0;
+			if (!hasTo && !hasFrom && !hasVia) {
+				errors.push({
+					message: "@db.rel.filter is only valid on navigational fields (@db.rel.to, @db.rel.from, or @db.rel.via)",
+					severity: 1,
+					range: token.range
+				});
+				return errors;
+			}
+			if (!args[0]?.queryNode) return errors;
+			const targetTypeName = getNavTargetTypeName(field);
+			if (!targetTypeName) return errors;
+			const allowedTypes = [targetTypeName];
+			if (hasVia) {
+				const junctionType = getAnnotationAlias(field, "db.rel.via");
+				if (junctionType) allowedTypes.push(junctionType);
+			}
+			errors.push(...validateQueryScope(args[0], allowedTypes, targetTypeName, doc));
+			return errors;
+		}
+	})
+} };
+
+//#endregion
+//#region packages/db/src/plugin/annotations/search.ts
+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** → JSON storage (no native vector support)\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\nembedding: db.vector\n```\n",
+			nodeType: ["prop"],
+			multiple: false,
+			argument: [
+				{
+					optional: false,
+					name: "dimensions",
+					type: "number",
+					description: "The **number of dimensions in the vector** (must match your embedding model output).",
+					values: [
+						"512",
+						"768",
+						"1024",
+						"1536",
+						"3072",
+						"4096"
+					]
+				},
+				{
+					optional: true,
+					name: "similarity",
+					type: "string",
+					description: "The **similarity metric** for vector search. Defaults to `\"cosine\"`.\n\n**Available options:** `\"cosine\"`, `\"euclidean\"`, `\"dotProduct\"`.",
+					values: [
+						"cosine",
+						"euclidean",
+						"dotProduct"
+					]
+				},
+				{
+					optional: true,
+					name: "indexName",
+					type: "string",
+					description: "The **name of the vector search index** (optional, defaults to the field name)."
+				}
+			]
+		}),
+		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",
+			nodeType: ["prop"],
+			multiple: false,
+			argument: {
+				optional: false,
+				name: "value",
+				type: "number",
+				description: "Minimum similarity score (`0`–`1`). Results below this threshold are excluded."
+			}
+		})
+	},
+	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",
+		nodeType: ["prop"],
+		multiple: true,
+		argument: {
+			optional: false,
+			name: "indexName",
+			type: "string",
+			description: "The **name of the vector search index** (field name or explicit indexName from `@db.search.vector`) this field filters."
+		}
+	})
+} };
+
+//#endregion
+//#region packages/db/src/plugin/annotations/table.ts
+const dbTableAnnotations = {
+	table: {
+		$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",
+			nodeType: ["interface"],
+			argument: {
+				optional: true,
+				name: "name",
+				type: "string",
+				description: "Table/collection name. If omitted, derived from interface name."
+			},
+			validate(token, _args, _doc) {
+				const errors = [];
+				const owner = token.parentNode;
+				if (hasAnyViewAnnotation(owner)) errors.push({
+					message: "An interface cannot be both a @db.table and a @db.view",
+					severity: 1,
+					range: token.range
+				});
+				return errors;
+			}
+		}),
+		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",
+			nodeType: ["interface"],
+			argument: {
+				name: "oldName",
+				type: "string",
+				description: "The previous table/collection name."
+			},
+			validate(token, _args, _doc) {
+				const errors = [];
+				const owner = token.parentNode;
+				if (owner.countAnnotations("db.table") === 0) errors.push({
+					message: "@db.table.renamed requires @db.table on the same interface",
+					severity: 1,
+					range: token.range
+				});
+				return errors;
+			}
+		})
+	},
+	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",
+		nodeType: ["interface"],
+		argument: {
+			name: "name",
+			type: "string",
+			description: "Schema/namespace name."
+		}
+	}),
+	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",
+		nodeType: ["interface"],
+		argument: {
+			name: "method",
+			type: "string",
+			description: "Sync method: \"drop\" (lossy) or \"recreate\" (lossless with data copy).",
+			values: ["drop", "recreate"]
+		}
+	}) }
+};
+
+//#endregion
+//#region packages/db/src/plugin/annotations/view.ts
+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",
+		nodeType: ["interface"],
+		argument: {
+			optional: true,
+			name: "name",
+			type: "string",
+			description: "The view name in the database. If omitted, derived from the interface name."
+		},
+		validate(token, _args, _doc) {
+			const errors = [];
+			const owner = token.parentNode;
+			if (owner.countAnnotations("db.table") > 0) errors.push({
+				message: "An interface cannot be both a @db.table and a @db.view",
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	}),
+	for: new AnnotationSpec({
+		description: "Specifies the entry/primary table for a computed view. Required for views that map fields via chain refs.\n\n**Example:**\n```atscript\n@db.view.for Order\n@db.view.filter `Order.status = 'active'`\nexport interface ActiveOrderDetails { ... }\n```\n",
+		nodeType: ["interface"],
+		argument: {
+			name: "entry",
+			type: "ref",
+			description: "The primary/entry table type (must have @db.table)."
+		},
+		validate(token, args, doc) {
+			const errors = [];
+			const owner = token.parentNode;
+			if (owner.countAnnotations("db.table") > 0) errors.push({
+				message: "An interface cannot be both a @db.table and a @db.view",
+				severity: 1,
+				range: token.range
+			});
+			if (args[0]) errors.push(...validateRefArgument(args[0], doc, { requireDbTable: true }));
+			return errors;
+		}
+	}),
+	joins: new AnnotationSpec({
+		description: "Declares an explicit join for a view. Use when no `@db.rel.*` path exists between the entry table and the target.\n\n**Example:**\n```atscript\n@db.view.for Order\n@db.view.joins Warehouse, `Warehouse.regionId = Order.regionId`\nexport interface OrderWarehouse { ... }\n```\n",
+		nodeType: ["interface"],
+		multiple: true,
+		mergeStrategy: "append",
+		argument: [{
+			name: "target",
+			type: "ref",
+			description: "The table type to join (must have @db.table)."
+		}, {
+			name: "condition",
+			type: "query",
+			description: "Join condition expression."
+		}],
+		validate(token, args, doc) {
+			const errors = [];
+			const owner = token.parentNode;
+			if (!hasAnyViewAnnotation(owner) && !args[0]) {
+				errors.push({
+					message: "@db.view.joins is only valid on @db.view interfaces",
+					severity: 1,
+					range: token.range
+				});
+				return errors;
+			}
+			if (args[0]) errors.push(...validateRefArgument(args[0], doc, { requireDbTable: true }));
+			const entryTypeName = getAnnotationAlias(owner, "db.view.for");
+			if (!entryTypeName) {
+				errors.push({
+					message: "@db.view.joins requires @db.view.for to identify the entry table",
+					severity: 1,
+					range: token.range
+				});
+				return errors;
+			}
+			if (args[1]?.queryNode && args[0]) {
+				const joinTargetName = args[0].text;
+				errors.push(...validateQueryScope(args[1], [joinTargetName, entryTypeName], entryTypeName, doc));
+			}
+			return errors;
+		}
+	}),
+	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",
+		nodeType: ["interface"],
+		argument: {
+			name: "condition",
+			type: "query",
+			description: "Filter expression for the view WHERE clause."
+		},
+		validate(token, args, doc) {
+			const errors = [];
+			const owner = token.parentNode;
+			if (!hasAnyViewAnnotation(owner) && !args[0]) {
+				errors.push({
+					message: "@db.view.filter is only valid on @db.view interfaces",
+					severity: 1,
+					range: token.range
+				});
+				return errors;
+			}
+			if (!args[0]?.queryNode) return errors;
+			const entryTypeName = getAnnotationAlias(owner, "db.view.for");
+			if (!entryTypeName) {
+				errors.push({
+					message: "@db.view.filter requires @db.view.for to identify the entry table",
+					severity: 1,
+					range: token.range
+				});
+				return errors;
+			}
+			const allowedTypes = [entryTypeName];
+			const joinsAnnotations = owner.annotations?.filter((a) => a.name === "db.view.joins");
+			if (joinsAnnotations) {
+				for (const join of joinsAnnotations) if (join.args[0]) allowedTypes.push(join.args[0].text);
+			}
+			errors.push(...validateQueryScope(args[0], allowedTypes, entryTypeName, doc));
+			return errors;
+		}
+	}),
+	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",
+		nodeType: ["interface"],
+		validate(token, _args, _doc) {
+			const errors = [];
+			const owner = token.parentNode;
+			if (!hasAnyViewAnnotation(owner)) errors.push({
+				message: "@db.view.materialized is only valid on @db.view interfaces",
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	}),
+	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",
+		nodeType: ["interface"],
+		argument: {
+			name: "oldName",
+			type: "string",
+			description: "The previous view name."
+		},
+		validate(token, _args, _doc) {
+			const errors = [];
+			const owner = token.parentNode;
+			if (!hasAnyViewAnnotation(owner)) errors.push({
+				message: "@db.view.renamed requires @db.view on the same interface",
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	}),
+	having: new AnnotationSpec({
+		description: "Post-aggregation filter (HAVING clause) for analytical views. References view field aliases with applied aggregate functions.\n\n**Example:**\n```atscript\n@db.view\n@db.view.for Order\n@db.view.having `totalRevenue > 100`\nexport interface TopCategories { ... }\n```\n",
+		nodeType: ["interface"],
+		argument: {
+			name: "condition",
+			type: "query",
+			description: "HAVING condition referencing view aliases."
+		},
+		validate(token, _args, _doc) {
+			const errors = [];
+			const owner = token.parentNode;
+			if (!hasAnyViewAnnotation(owner)) errors.push({
+				message: "@db.view.having is only valid on @db.view interfaces",
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	})
+} };
+
+//#endregion
+//#region packages/db/src/plugin/index.ts
+const dbPlugin = () => ({
+	name: "db",
+	config() {
+		return {
+			annotations: { db: {
+				patch: dbColumnAnnotations.patch,
+				table: dbTableAnnotations.table,
+				schema: dbTableAnnotations.schema,
+				index: dbIndexAnnotations.index,
+				column: dbColumnAnnotations.column,
+				default: dbColumnAnnotations.default,
+				json: dbColumnAnnotations.json,
+				ignore: dbColumnAnnotations.ignore,
+				sync: dbTableAnnotations.sync,
+				rel: dbRelAnnotations.rel,
+				view: dbViewAnnotations.view,
+				agg: dbAggAnnotations.agg,
+				search: dbSearchAnnotations.search
+			} },
+			primitives: { db: { extensions: { vector: {
+				type: {
+					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"
+			} } } }
+		};
+	}
+});
+
+//#endregion
+export { dbPlugin, dbPlugin as default };