@atscript/db 0.1.140 → 0.1.142

package/dist/plugin.mjs

@@ -1,18 +1,11 @@
 import { i as SUPPORTED_AGGREGATE_FNS, r as NULL_WHEN_EMPTY_AGGREGATE_FNS } from "./aggregate-fns-CfsveE1w.mjs";
+import { n as DERIVED_INCOMPATIBLE, r as JSON_LEAF_TYPES, t as DB_ENTITY_ANNOTATIONS } from "./derived-rules-0sKn4f5C.mjs";
 import "./consts-C_-5_pFq.mjs";
-import { _ as validateSiblingStringField, a as validateRefArgument, c as getAnnotationAlias, d as getParentStruct, f as getParentTypeName, g as validateFieldBaseType, h as validateExclusiveWith, i as validateQueryScope, l as getDbTableOwner, m as refActionAnnotation, n as hasAnyViewAnnotation, o as viewJoins, p as primitiveBaseType, r as joinTargets, s as viewScopeTypes, t as findFKFieldsPointingTo, u as getNavTargetTypeName } from "./validation-utils-B4h-GW4d.mjs";
+import { S as validateSiblingStringField, _ as getParentTypeName, a as hasAnyViewAnnotation, b as validateExclusiveWith, d as viewJoins, f as viewScopeTypes, g as getParentStruct, h as getNavTargetTypeName, l as validateQueryScope, m as getDbTableOwner, n as findFKFieldsPointingTo, o as isAliasDecl, p as getAnnotationAlias, r as findViewCycle, s as isDbSourceDecl, t as earlierJoinTargets, u as validateRefArgument, v as primitiveBaseType, x as validateFieldBaseType, y as refActionAnnotation } from "./validation-utils-CMR4fe2M.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { AnnotationSpec, DEFAULT_FORMAT, isArray, isInterface, isPrimitive, isProp, isRef, isStructure } from "@atscript/core";
 //#region src/plugin/manifest.ts
-const DB_ENTITY_ANNOTATIONS = [
-	"db.table",
-	"db.view",
-	"db.view.for"
-];
-function isDbEntity(node) {
-	return DB_ENTITY_ANNOTATIONS.some((name) => node.countAnnotations(name) > 0);
-}
 /**
 * Renders the model-manifest module: an inventory of every exported
 * `@db.table` / `@db.view` entity in the project, grouped by `@db.space`.
@@ -41,7 +34,7 @@ async function generateModelManifest(options, output, format, repo) {
 		let specifier = path.relative(manifestDir, docPath).split(path.sep).join("/");
 		if (!specifier.startsWith(".")) specifier = `./${specifier}`;
 		for (const [exportName, node] of [...doc.exports.entries()].toSorted(([a], [b]) => a.localeCompare(b))) {
-			if (!isDbEntity(node)) continue;
+			if (!isDbSourceDecl(node)) continue;
 			let alias = exportName;
 			for (let n = 1; usedAliases.has(alias); n++) alias = `${exportName}_${n}`;
 			usedAliases.add(alias);
@@ -95,6 +88,113 @@ async function generateModelManifest(options, output, format, repo) {
 	});
 }
 //#endregion
+//#region src/plugin/lsp-scopes.ts
+/**
+* Editor scopes of the `@db.*` query / field-path arguments and the type
+* filters of the ref arguments — one function per rule. The validators in
+* `annotations/*` derive their in-scope types from these SAME functions, so a
+* diagnostic and what the editor completes, hovers and jumps to never diverge.
+* @since 0.1.141
+*/
+/** The `@db.view.for` entry name of a view node. */
+function viewEntry(view) {
+	return getAnnotationAlias(view, "db.view.for");
+}
+/**
+* `@db.view.filter` — and a conditional `@db.agg.*` of the same view: the
+* entry table and every `@db.view.joins` target (`@db.alias` names included),
+* in declaration order; an unqualified field belongs to the entry.
+*/
+function viewFilterScope(view) {
+	const entry = viewEntry(view);
+	return entry ? {
+		allowedTypes: viewScopeTypes(view),
+		unqualifiedTarget: entry
+	} : void 0;
+}
+/**
+* `@db.view.joins` condition: the join target, the entry table and the joins
+* declared before this one (chained joins — `earlier`, computed from the
+* view's {@link viewJoins} when the caller has not); an unqualified field
+* belongs to the entry.
+*/
+function viewJoinScope(view, join, earlier = earlierJoinTargets(viewJoins(view), join)) {
+	const entry = viewEntry(view);
+	const target = join.args[0]?.text;
+	if (!entry || !target) return;
+	return {
+		allowedTypes: [
+			target,
+			entry,
+			...earlier
+		],
+		unqualifiedTarget: entry
+	};
+}
+/** `@db.view.having`: the view's own fields, unqualified — no source type is in scope. */
+function viewHavingScope(view) {
+	return view.id ? {
+		allowedTypes: [],
+		unqualifiedTarget: view.id
+	} : void 0;
+}
+/** The condition of a `@db.agg.*` on a view field: the scope of the view's `@db.view.filter`. */
+function aggConditionScope(propToken) {
+	const view = getDbTableOwner(propToken);
+	return view ? viewFilterScope(view) : void 0;
+}
+/**
+* The field of a `@db.agg.*` (`'amount'`, `'settings.level'`): a field path
+* of the prop's chain-ref type, else of the view's `@db.view.for` entry —
+* where the runtime reads the aggregate's source column from.
+*/
+function aggFieldScope(propToken) {
+	const def = propToken.parentNode?.getDefinition();
+	const refType = def && isRef(def) && def.hasChain ? def.id : void 0;
+	const view = refType ? void 0 : getDbTableOwner(propToken);
+	const target = refType ?? (view ? viewEntry(view) : void 0);
+	return target ? {
+		allowedTypes: [],
+		unqualifiedTarget: target
+	} : void 0;
+}
+/**
+* `@db.rel.filter` on a navigational field: the related type (`Post` of
+* `posts: Post[]`) and, for `@db.rel.via`, the junction table; an
+* unqualified field belongs to the related type.
+*/
+function relFilterScope(field) {
+	const target = getNavTargetTypeName(field);
+	if (!target) return;
+	const junction = getAnnotationAlias(field, "db.rel.via");
+	return {
+		allowedTypes: junction ? [target, junction] : [target],
+		unqualifiedTarget: target
+	};
+}
+/** The `fieldScope` hooks (argument token → scope) the annotation specs declare. */
+const fieldScopes = {
+	viewFilter: (arg) => arg.parentNode ? viewFilterScope(arg.parentNode) : void 0,
+	viewJoin: (arg) => {
+		const view = arg.parentNode;
+		const joins = view ? viewJoins(view) : [];
+		const join = joins.find((a) => a.args.includes(arg));
+		return view && join ? viewJoinScope(view, join, earlierJoinTargets(joins, join)) : void 0;
+	},
+	viewHaving: (arg) => arg.parentNode ? viewHavingScope(arg.parentNode) : void 0,
+	aggCondition: aggConditionScope,
+	aggField: aggFieldScope,
+	relFilter: (arg) => arg.parentNode ? relFilterScope(arg.parentNode) : void 0
+};
+/** `refFilter` of the `@db.view.joins` target: a view source or a `@db.alias` of one. */
+function isJoinTarget(decl) {
+	return isDbSourceDecl(decl) || isAliasDecl(decl);
+}
+/** `refFilter` of `@db.rel.via`: a `@db.table`. */
+function isDbTable(decl) {
+	return decl.countAnnotations("db.table") > 0;
+}
+//#endregion
 //#region src/plugin/annotations/agg.ts
 /**
 * A conditional aggregate that is NULL when no row matches (so its field
@@ -109,7 +209,8 @@ const CONDITION_ARG = {
 	name: "condition",
 	type: "query",
 	optional: true,
-	description: "Row predicate of a conditional aggregate: only rows where it holds are aggregated (SQL `FN(CASE WHEN … THEN field END)`). May reference the entry table and every join; unqualified fields resolve to the entry table."
+	description: "Row predicate of a conditional aggregate: only rows where it holds are aggregated (SQL `FN(CASE WHEN … THEN field END)`). May reference the entry table and every join; unqualified fields resolve to the entry table.",
+	fieldScope: fieldScopes.aggCondition
 };
 /**
 * The rules every `@db.agg.*` shares: `'*'` is `count`'s only, and a
@@ -127,9 +228,8 @@ function validateAggArgs(name, token, args, doc) {
 	});
 	const condition = args[1];
 	if (!condition?.queryNode) return errors;
-	const owner = getDbTableOwner(token);
-	const entryTypeName = owner ? getAnnotationAlias(owner, "db.view.for") : void 0;
-	if (!owner || !entryTypeName) {
+	const scope = aggConditionScope(token);
+	if (!scope) {
 		errors.push({
 			message: `A conditional ${annotation} requires @db.view.for on the view`,
 			severity: 1,
@@ -137,7 +237,7 @@ function validateAggArgs(name, token, args, doc) {
 		});
 		return errors;
 	}
-	errors.push(...validateQueryScope(condition, viewScopeTypes(owner), entryTypeName, doc));
+	errors.push(...validateQueryScope(condition, scope, doc));
 	const prop = token.parentNode;
 	if (conditionalIsNullable(name) && prop && !prop.has("optional")) {
 		const field = prop.id ?? "field";
@@ -169,7 +269,8 @@ function aggSpec(name, description, field, types, extra = "") {
 			name: "field",
 			type: "string",
 			optional: field.optional,
-			description: field.description
+			description: field.description,
+			fieldScope: fieldScopes.aggField
 		}, CONDITION_ARG],
 		validate(token, args, doc) {
 			const errors = validateAggArgs(name, token, args, doc);
@@ -190,6 +291,51 @@ const dbAggAnnotations = { agg: {
 	max: aggSpec("max", "Declares a view field as MAX of a source column.", { description: "Source column name." })
 } };
 //#endregion
+//#region src/plugin/annotations/alias.ts
+/** The `accept` rule of a view-source ref argument (`@db.view.for`, `@db.alias`). */
+const VIEW_SOURCE_ARGUMENT = {
+	accept: isDbSourceDecl,
+	expected: "must be a @db.table or a @db.view."
+};
+/**
+* `@db.alias <Target>` — a named join scope over a table or view, so a view
+* can join the same table twice or join its own entry table (self-join).
+* @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",
+	nodeType: ["type"],
+	passedWhenReferred: false,
+	argument: {
+		name: "target",
+		type: "ref",
+		description: "The aliased table or view type (must have @db.table or @db.view).",
+		refFilter: isDbSourceDecl
+	},
+	validate(token, args, doc) {
+		const errors = [];
+		const owner = token.parentNode;
+		const target = args[0]?.text;
+		for (const name of DB_ENTITY_ANNOTATIONS) if (owner.countAnnotations(name) > 0) {
+			errors.push({
+				message: `A @db.alias type cannot carry @${name} — it names a join scope over "${target ?? "…"}", not a table or view`,
+				severity: 1,
+				range: token.range
+			});
+			break;
+		}
+		if (!target) return errors;
+		const def = owner.getDefinition();
+		if ((def && isRef(def) && !def.hasChain ? def.id : void 0) !== target) errors.push({
+			message: `@db.alias ${target} must be declared on 'export type ${owner.id ?? "X"} = ${target}' — the type must be a plain reference to the aliased ${target}`,
+			severity: 1,
+			range: token.range
+		});
+		errors.push(...validateRefArgument(args[0], doc, VIEW_SOURCE_ARGUMENT));
+		return errors;
+	}
+}) };
+//#endregion
 //#region src/plugin/annotations/amount.ts
 const CURRENCY_CODE_PATTERN = /^[A-Z0-9]{2,10}$/;
 const dbAmountAnnotations = { amount: { currency: {
@@ -244,6 +390,100 @@ const dbAmountAnnotations = { amount: { currency: {
 	})
 } } };
 //#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
 const dbColumnAnnotations = {
 	patch: { strategy: new AnnotationSpec({
@@ -331,6 +571,66 @@ const dbColumnAnnotations = {
 				return validateFieldBaseType(token, doc, "@db.column.precision", ["number", "decimal"]);
 			}
 		}),
+		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",
+			nodeType: ["prop"],
+			passedWhenReferred: false,
+			multiple: false,
+			validate(token, _args, doc) {
+				const errors = [];
+				const field = token.parentNode;
+				const fail = (message, severity = 1) => {
+					errors.push({
+						message,
+						severity,
+						range: token.range
+					});
+				};
+				const owner = getDbTableOwner(token);
+				if (!owner || !isInterface(owner) || owner.countAnnotations("db.table") === 0) {
+					fail("@db.column.derived is only valid on a top-level field of a @db.table interface");
+					return errors;
+				}
+				for (const [name, why] of DERIVED_INCOMPATIBLE) if (field.countAnnotations(name) > 0) fail(`@db.column.derived cannot coexist with @${name} — ${why}`);
+				const definition = field.getDefinition();
+				if (!definition || !isRef(definition) || !definition.hasChain) {
+					fail("@db.column.derived requires a chain reference into a @db.json field of the same table (e.g. `customerId: Order.payload.customer.id`)");
+					return errors;
+				}
+				const ref = definition;
+				const tableName = getParentTypeName(token);
+				if (ref.id !== tableName) {
+					fail(`@db.column.derived must reference the enclosing table '${tableName ?? ""}', not '${ref.id ?? ""}' — a derived column reads its own row`);
+					return errors;
+				}
+				const info = jsonChainInfo(ref, doc);
+				const path = `${info.typeName}.${info.chain.join(".")}`;
+				const notInsideJson = `@db.column.derived path '${path}' does not read inside a @db.json field — a flattened or scalar column needs no derived column`;
+				if (info.chain.length < 2) {
+					fail(notInsideJson);
+					return errors;
+				}
+				if (!info.resolved) return errors;
+				if (info.viaArray) {
+					fail(`@db.column.derived path '${path}' crosses an array — a derived column reads one scalar leaf`);
+					return errors;
+				}
+				if (info.jsonRoot === void 0 || info.jsonRoot >= info.chain.length) {
+					fail(notInsideJson);
+					return errors;
+				}
+				if (info.viaEncrypted) {
+					fail(`@db.column.derived path '${path}' reads inside a @db.encrypted field — ciphertext cannot be extracted`);
+					return errors;
+				}
+				if (info.leafType === void 0 || !JSON_LEAF_TYPES.has(info.leafType)) {
+					fail(`@db.column.derived path '${path}' must end at a string, number or boolean leaf` + (info.leafType ? ` (got '${info.leafType}')` : ""));
+					return errors;
+				}
+				if (info.optional && !field.has("optional")) fail(`@db.column.derived path '${path}' may be absent — declare the field optional (\`${field.id ?? ""}?:\`) so a missing leaf reads as null`, 2);
+				return errors;
+			}
+		}),
 		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"],
@@ -865,7 +1165,8 @@ const dbRelAnnotations = { rel: {
 		argument: {
 			name: "junction",
 			type: "ref",
-			description: "The junction table type (must have @db.table and @db.rel.FK fields pointing to both sides)."
+			description: "The junction table type (must have @db.table and @db.rel.FK fields pointing to both sides).",
+			refFilter: isDbTable
 		},
 		validate(token, args, doc) {
 			const errors = [];
@@ -882,7 +1183,10 @@ const dbRelAnnotations = { rel: {
 			});
 			if (!args[0]) return errors;
 			const junctionName = args[0].text;
-			errors.push(...validateRefArgument(args[0], doc, { requireDbTable: true }));
+			errors.push(...validateRefArgument(args[0], doc, {
+				accept: isDbTable,
+				expected: "must have @db.table annotation."
+			}));
 			if (errors.length > 0) return errors;
 			const junctionUnwound = doc.unwindType(junctionName);
 			if (!junctionUnwound) return errors;
@@ -925,7 +1229,8 @@ const dbRelAnnotations = { rel: {
 		argument: {
 			name: "condition",
 			type: "query",
-			description: "Filter expression restricting which related records are loaded."
+			description: "Filter expression restricting which related records are loaded — references the related type (and the @db.rel.via junction); unqualified fields belong to the related type.",
+			fieldScope: fieldScopes.relFilter
 		},
 		validate(token, args, doc) {
 			const errors = [];
@@ -942,14 +1247,8 @@ const dbRelAnnotations = { rel: {
 				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));
+			const scope = relFilterScope(field);
+			if (scope) errors.push(...validateQueryScope(args[0], scope, doc));
 			return errors;
 		}
 	})
@@ -1038,6 +1337,7 @@ const dbTableAnnotations = {
 		$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"],
+			passedWhenReferred: false,
 			argument: {
 				optional: true,
 				name: "name",
@@ -1058,6 +1358,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",
 			nodeType: ["interface"],
+			passedWhenReferred: false,
 			argument: {
 				name: "oldName",
 				type: "string",
@@ -1076,6 +1377,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",
 			nodeType: ["interface"],
+			passedWhenReferred: false,
 			multiple: false,
 			argument: {
 				optional: true,
@@ -1123,6 +1425,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",
 		nodeType: ["interface"],
+		passedWhenReferred: false,
 		argument: {
 			name: "name",
 			type: "string",
@@ -1132,6 +1435,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",
 		nodeType: ["interface"],
+		passedWhenReferred: false,
 		argument: {
 			name: "name",
 			type: "string",
@@ -1141,6 +1445,7 @@ const dbTableAnnotations = {
 	http: { path: new AnnotationSpec({
 		description: "HTTP endpoint path where this table is served. Used by the UI for value-help on FK fields. Gets overwritten by the final controller prefix at runtime.\n\n**Example:**\n```atscript\n@db.table \"authors\"\n@db.http.path \"/authors\"\nexport interface Author { ... }\n```\n",
 		nodeType: ["interface"],
+		passedWhenReferred: false,
 		argument: {
 			name: "path",
 			type: "string",
@@ -1150,6 +1455,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",
 		nodeType: ["interface"],
+		passedWhenReferred: false,
 		argument: {
 			name: "method",
 			type: "string",
@@ -1160,6 +1466,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",
 		nodeType: ["interface"],
+		passedWhenReferred: false,
 		multiple: false,
 		argument: {
 			name: "depth",
@@ -1225,6 +1532,7 @@ function tableCapability(capability) {
 @db.table.${capability} "manual"\nexport interface User {
 ` + example + "}\n```\n",
 		nodeType: ["interface"],
+		passedWhenReferred: false,
 		multiple: false,
 		argument: {
 			optional: true,
@@ -1293,91 +1601,12 @@ const dbUnitAnnotations = { unit: {
 	})
 } };
 //#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}`);
-/** Primitive leaf types a JSON-stored path may end at. */
-const JSON_LEAF_TYPES = new Set([
-	"string",
-	"number",
-	"boolean"
-]);
-/** 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 typeName = ref.id;
-	const chain = ref.chain.map((t) => t.text);
-	if (!typeName || chain.length < 2) return [];
-	let throughJson = false;
-	for (let i = 1; i < chain.length; i++) {
-		const step = doc.unwindType(typeName, chain.slice(0, i));
-		if (!step) return [];
-		const stepNode = step.node;
-		if (stepNode && isProp(stepNode) && stepNode.countAnnotations("db.json") > 0 || isArray(step.def)) {
-			throughJson = true;
-			break;
-		}
-	}
-	if (!throughJson) return [];
-	const leaf = doc.unwindType(typeName, chain)?.def;
-	const leafType = primitiveBaseType(leaf);
-	if (leafType !== void 0 && JSON_LEAF_TYPES.has(leafType)) return [];
-	return [{
-		message: `Field "${fieldName}" reads "${typeName}.${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/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"],
+		passedWhenReferred: false,
 		argument: {
 			optional: true,
 			name: "name",
@@ -1395,12 +1624,14 @@ const dbViewAnnotations = { view: {
 		}
 	}),
 	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",
+		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",
 		nodeType: ["interface"],
+		passedWhenReferred: false,
 		argument: {
 			name: "entry",
 			type: "ref",
-			description: "The primary/entry table type (must have @db.table)."
+			description: "The primary/entry table or view type (must have @db.table or @db.view).",
+			refFilter: isDbSourceDecl
 		},
 		validate(token, args, doc) {
 			const errors = [];
@@ -1410,26 +1641,35 @@ const dbViewAnnotations = { view: {
 				severity: 1,
 				range: token.range
 			});
-			if (args[0]) errors.push(...validateRefArgument(args[0], doc, { requireDbTable: true }));
+			if (args[0]) errors.push(...validateRefArgument(args[0], doc, VIEW_SOURCE_ARGUMENT));
+			const cycle = findViewCycle(owner, doc);
+			if (cycle) errors.push({
+				message: `View '${cycle[0]}' depends on itself: ${cycle.join(" → ")}`,
+				severity: 1,
+				range: args[0]?.range ?? token.range
+			});
 			errors.push(...validateViewInterface(owner, doc));
 			return errors;
 		}
 	}),
 	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); a table can be joined once (no aliases / self-joins).\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",
+		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",
 		nodeType: ["interface"],
+		passedWhenReferred: false,
 		multiple: true,
 		mergeStrategy: "append",
 		argument: [
 			{
 				name: "target",
 				type: "ref",
-				description: "The table type to join (must have @db.table)."
+				description: "The type to join: a @db.table, a @db.view, or a @db.alias of one (for a second join of the same table / a self-join).",
+				refFilter: isJoinTarget
 			},
 			{
 				name: "condition",
 				type: "query",
-				description: "Join condition expression."
+				description: "Join condition expression — may reference the join target, the entry table and the joins declared before this one.",
+				fieldScope: fieldScopes.viewJoin
 			},
 			{
 				name: "kind",
@@ -1450,7 +1690,10 @@ const dbViewAnnotations = { view: {
 				});
 				return errors;
 			}
-			if (args[0]) errors.push(...validateRefArgument(args[0], doc, { requireDbTable: true }));
+			if (args[0]) errors.push(...validateRefArgument(args[0], doc, {
+				accept: isJoinTarget,
+				expected: "must be a @db.table or a @db.view."
+			}));
 			const entryTypeName = getAnnotationAlias(owner, "db.view.for");
 			if (!entryTypeName) {
 				errors.push({
@@ -1460,40 +1703,40 @@ const dbViewAnnotations = { view: {
 				});
 				return errors;
 			}
-			const allJoins = viewJoins(owner);
-			const position = allJoins.findIndex((a) => a.token === token);
-			const earlier = joinTargets(position === -1 ? [] : allJoins.slice(0, position));
+			const joins = viewJoins(owner);
+			const join = joins.find((a) => a.token === token);
+			const earlier = join ? earlierJoinTargets(joins, join) : [];
 			if (args[0]) {
 				const target = args[0].text;
+				const aliasHint = (name) => {
+					const decl = doc.getDeclarationOwnerNode(target)?.node;
+					return decl && isAliasDecl(decl) ? "" : ` — declare a @db.alias type (\`@db.alias ${name}\` + \`export type Other = ${name}\`) to join it under another name`;
+				};
 				if (target === entryTypeName) errors.push({
-					message: `@db.view.joins cannot join the entry table '${target}' — no join aliases / self-joins yet`,
+					message: `@db.view.joins cannot join the entry table '${target}' directly${aliasHint(target)}`,
 					severity: 1,
 					range: args[0].range
 				});
 				else if (earlier.includes(target)) errors.push({
-					message: `'${target}' is joined more than once — no join aliases / self-joins yet`,
+					message: `'${target}' is joined more than once${aliasHint(target)}`,
 					severity: 1,
 					range: args[0].range
 				});
 			}
-			if (args[1]?.queryNode && args[0]) {
-				const joinTargetName = args[0].text;
-				errors.push(...validateQueryScope(args[1], [
-					joinTargetName,
-					entryTypeName,
-					...earlier
-				], entryTypeName, doc, "a join may reference the entry table and joins declared before it"));
-			}
+			const scope = join && viewJoinScope(owner, join, earlier);
+			if (args[1]?.queryNode && scope) errors.push(...validateQueryScope(args[1], scope, doc, "a join may reference the entry table and joins declared before it"));
 			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"],
+		passedWhenReferred: false,
 		argument: {
 			name: "condition",
 			type: "query",
-			description: "Filter expression for the view WHERE clause."
+			description: "Filter expression for the view WHERE clause — may reference the entry table and every join; unqualified fields belong to the entry.",
+			fieldScope: fieldScopes.viewFilter
 		},
 		validate(token, args, doc) {
 			const errors = [];
@@ -1507,8 +1750,8 @@ const dbViewAnnotations = { view: {
 				return errors;
 			}
 			if (!args[0]?.queryNode) return errors;
-			const entryTypeName = getAnnotationAlias(owner, "db.view.for");
-			if (!entryTypeName) {
+			const scope = viewFilterScope(owner);
+			if (!scope) {
 				errors.push({
 					message: "@db.view.filter requires @db.view.for to identify the entry table",
 					severity: 1,
@@ -1516,13 +1759,14 @@ const dbViewAnnotations = { view: {
 				});
 				return errors;
 			}
-			errors.push(...validateQueryScope(args[0], viewScopeTypes(owner), entryTypeName, doc));
+			errors.push(...validateQueryScope(args[0], scope, 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"],
+		passedWhenReferred: false,
 		validate(token, _args, _doc) {
 			const errors = [];
 			const owner = token.parentNode;
@@ -1537,6 +1781,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",
 		nodeType: ["interface"],
+		passedWhenReferred: false,
 		argument: {
 			name: "oldName",
 			type: "string",
@@ -1554,21 +1799,28 @@ const dbViewAnnotations = { view: {
 		}
 	}),
 	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",
+		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",
 		nodeType: ["interface"],
+		passedWhenReferred: false,
 		argument: {
 			name: "condition",
 			type: "query",
-			description: "HAVING condition referencing view aliases."
+			description: "HAVING condition — the view's own fields, unqualified.",
+			fieldScope: fieldScopes.viewHaving
 		},
-		validate(token, _args, _doc) {
+		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
-			});
+			if (!hasAnyViewAnnotation(owner)) {
+				errors.push({
+					message: "@db.view.having is only valid on @db.view interfaces",
+					severity: 1,
+					range: token.range
+				});
+				return errors;
+			}
+			const scope = viewHavingScope(owner);
+			if (args[0]?.queryNode && scope) errors.push(...validateQueryScope(args[0], scope, doc, "@db.view.having references the view's own fields unqualified"));
 			return errors;
 		}
 	})
@@ -1600,6 +1852,7 @@ const dbPlugin = (options) => ({
 				depth: dbTableAnnotations.depth,
 				rel: dbRelAnnotations.rel,
 				view: dbViewAnnotations.view,
+				alias: dbAliasAnnotations.alias,
 				agg: dbAggAnnotations.agg,
 				search: dbSearchAnnotations.search,
 				amount: dbAmountAnnotations.amount,