@atscript/db 0.1.135 → 0.1.136

package/dist/sync.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_view = require("./db-view-Dm7MpUGB.cjs");
+const require_db_view = require("./db-view-BAzhEUxB.cjs");
 //#region src/schema/schema-hash.ts
 /** Extracts sorted field snapshots from a readable's field descriptors. */
 function extractFieldSnapshots(fields, typeMapper) {
@@ -66,20 +66,43 @@ function computeViewSnapshot(view) {
 	};
 	const plan = view.viewPlan;
 	const qualify = (ref) => view.resolveFieldRef(ref, (n) => n);
+	const canonical = (node) => JSON.stringify(canonicalizeQueryNode(node, qualify));
+	const columns = view.getViewColumnMappings().map((m) => {
+		const col = {
+			column: m.viewColumn,
+			sourceTable: m.sourceTable,
+			sourceColumn: m.sourceColumn
+		};
+		if (m.json) {
+			col.jsonPath = JSON.stringify(m.json.path);
+			col.jsonType = m.json.type;
+		}
+		if (m.aggFn) col.aggFn = m.aggFn;
+		if (m.aggField) col.aggField = m.aggField;
+		if (m.aggFilter) col.aggFilter = canonical(m.aggFilter);
+		return col;
+	}).toSorted((a, b) => a.column < b.column ? -1 : a.column > b.column ? 1 : 0);
 	const result = {
 		tableName: view.tableName,
 		viewType: plan.materialized ? "M" : "V",
 		entryTable: plan.entryTable,
-		joinTables: plan.joins.map((j) => ({
-			targetTable: j.targetTable,
-			condition: JSON.stringify(canonicalizeQueryNode(j.condition, qualify))
-		})),
-		materialized: plan.materialized || void 0,
+		joinTables: plan.joins.map((j) => {
+			const join = {
+				targetTable: j.targetTable,
+				condition: canonical(j.condition)
+			};
+			if (j.kind === "left") join.kind = "left";
+			return join;
+		}),
+		columns
+	};
+	if (plan.filter) result.filterHash = fnv1a(canonical(plan.filter));
+	if (plan.having) result.havingHash = fnv1a(canonical(plan.having));
+	if (plan.materialized) result.materialized = true;
+	return {
+		...result,
 		fields
 	};
-	if (plan.filter) result.filterHash = fnv1a(JSON.stringify(canonicalizeQueryNode(plan.filter, qualify)));
-	if (plan.having) result.havingHash = fnv1a(JSON.stringify(canonicalizeQueryNode(plan.having, qualify)));
-	return result;
 }
 /**
 * Converts a view predicate (join condition, `@db.view.filter`,
@@ -1747,7 +1770,11 @@ var SchemaSync = class {
 				if (d.externalTargets.get(fk.targetTable) === false) addRefusal(refusals, t.name, `FK ${t.name}.${fk.fields.join(",")} references "${fk.targetTable}" which is neither in the sync inventory nor present in the database`);
 			}
 		}
-		for (const view of d.views) if (d.viewObjectKinds.get(view.tableName) === "table") addRefusal(refusals, view.tableName, `A physical table "${view.tableName}" exists where managed view "${view.tableName}" is declared — drop or rename it`);
+		for (const view of d.views) {
+			if (d.viewObjectKinds.get(view.tableName) === "table") addRefusal(refusals, view.tableName, `A physical table "${view.tableName}" exists where managed view "${view.tableName}" is declared — drop or rename it`);
+			const fns = view.dbAdapter.aggregateFns();
+			for (const col of view.getViewColumnMappings()) if (col.aggFn && !fns.has(col.aggFn)) addRefusal(refusals, view.tableName, `View "${view.tableName}" field "${col.viewPath}": aggregate "${col.aggFn}" is not supported by this adapter (aggregateFns())`);
+		}
 		if (!safe) for (const r of d.removed) {
 			if (r.isView) continue;
 			const referencers = [];

package/dist/sync.d.cts

@@ -1,5 +1,5 @@
-import { E as TColumnDiff, F as TDbDefaultValue, Ht as TGenericLogger, L as TDbFieldMeta, Pt as AtscriptDbReadable, R as TDbForeignKey, W as TDbObjectKind, Y as TDbStorageType, it as TExistingTableOption, mt as TReferencingForeignKey, nt as TExistingColumn, pt as TPrimaryKeyChange, rt as TExistingForeignKey, tt as TEnsureTableOptions, vt as TTableOptionDiff } from "./buckets-D6PBXKRJ.cjs";
-import { c as AtscriptQueryFieldRef$1, i as AtscriptDbView, l as AtscriptQueryNode$1, t as DbSpace } from "./db-space-BdtBNTeH.cjs";
+import { D as TColumnDiff, Ft as AtscriptDbReadable, G as TDbObjectKind, I as TDbDefaultValue, R as TDbFieldMeta, Ut as TGenericLogger, X as TDbStorageType, at as TExistingTableOption, ht as TReferencingForeignKey, it as TExistingForeignKey, mt as TPrimaryKeyChange, nt as TEnsureTableOptions, rt as TExistingColumn, yt as TTableOptionDiff, z as TDbForeignKey } from "./buckets-kKY0RKYN.cjs";
+import { i as AtscriptDbView, l as AtscriptQueryFieldRef$1, t as DbSpace, u as AtscriptQueryNode$1 } from "./db-space-ClG41vJh.cjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts
@@ -269,9 +269,27 @@ interface TViewJoinSnapshot {
   targetTable: string;
   /** Canonical JSON of the join condition (see {@link canonicalizeQueryNode}). */
   condition: string;
-  /** Reserved for optional joins; absent today so it does not perturb the hash. */
+  /** Emitted only for `"left"` — an inner join (the default) carries no key. @since 0.1.136 */
   kind?: "inner" | "left";
 }
+/**
+ * One column of a managed view as stored in its snapshot — the PHYSICAL
+ * source it reads, so a source rename (`@db.column`, flattening, a moved
+ * JSON leaf) or an aggregate change recreates the view.
+ * @since 0.1.136
+ */
+interface TViewColumnSnapshot {
+  column: string;
+  sourceTable: string;
+  sourceColumn: string;
+  /** JSON array of the path segments inside a JSON source column. */
+  jsonPath?: string;
+  jsonType?: string;
+  aggFn?: string;
+  aggField?: string;
+  /** Canonical JSON of a conditional aggregate's predicate. */
+  aggFilter?: string;
+}
 interface TViewSnapshot {
   tableName: string;
   viewType: "V" | "M" | "E";
@@ -281,6 +299,8 @@ interface TViewSnapshot {
    * join-less view (`[]`) serializes byte-identically to older snapshots.
    */
   joinTables?: TViewJoinSnapshot[];
+  /** @since 0.1.136 — view columns and their physical sources, sorted by `column`. */
+  columns?: TViewColumnSnapshot[];
   filterHash?: string;
   /** @since 0.1.128 — hash of the canonical `@db.view.having` predicate. */
   havingHash?: string;
@@ -649,4 +669,4 @@ declare function syncSchema(space: DbSpace, types: readonly TAtscriptAnnotatedTy
  */
 declare function planSchema(space: DbSpace, types: readonly TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe">): Promise<TSyncPlan>;
 //#endregion
-export { SchemaSync, SyncEntry, type TDbObjectKind, type TDependencyEdge, type TEnsureTableOptions, type TExistingForeignKey, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TPrimaryKeyChange, type TReferencingForeignKey, type TSyncColors, type TSyncEntryInit, type TSyncEntryStatus, type TSyncOptions, type TSyncPlan, type TSyncResult, type TSyncSkippedWork, type TTableSnapshot, type TViewJoinSnapshot, type TViewSnapshot, canonicalizeQueryNode, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };
+export { SchemaSync, SyncEntry, type TDbObjectKind, type TDependencyEdge, type TEnsureTableOptions, type TExistingForeignKey, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TPrimaryKeyChange, type TReferencingForeignKey, type TSyncColors, type TSyncEntryInit, type TSyncEntryStatus, type TSyncOptions, type TSyncPlan, type TSyncResult, type TSyncSkippedWork, type TTableSnapshot, type TViewColumnSnapshot, type TViewJoinSnapshot, type TViewSnapshot, canonicalizeQueryNode, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };

package/dist/sync.d.mts

@@ -1,5 +1,5 @@
-import { E as TColumnDiff, F as TDbDefaultValue, Ht as TGenericLogger, L as TDbFieldMeta, Pt as AtscriptDbReadable, R as TDbForeignKey, W as TDbObjectKind, Y as TDbStorageType, it as TExistingTableOption, mt as TReferencingForeignKey, nt as TExistingColumn, pt as TPrimaryKeyChange, rt as TExistingForeignKey, tt as TEnsureTableOptions, vt as TTableOptionDiff } from "./buckets-GruoVxH5.mjs";
-import { c as AtscriptQueryFieldRef$1, i as AtscriptDbView, l as AtscriptQueryNode$1, t as DbSpace } from "./db-space-9CH5neN7.mjs";
+import { D as TColumnDiff, Ft as AtscriptDbReadable, G as TDbObjectKind, I as TDbDefaultValue, R as TDbFieldMeta, Ut as TGenericLogger, X as TDbStorageType, at as TExistingTableOption, ht as TReferencingForeignKey, it as TExistingForeignKey, mt as TPrimaryKeyChange, nt as TEnsureTableOptions, rt as TExistingColumn, yt as TTableOptionDiff, z as TDbForeignKey } from "./buckets-y4EzoX7D.mjs";
+import { i as AtscriptDbView, l as AtscriptQueryFieldRef$1, t as DbSpace, u as AtscriptQueryNode$1 } from "./db-space-BX4K3vb6.mjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts
@@ -269,9 +269,27 @@ interface TViewJoinSnapshot {
   targetTable: string;
   /** Canonical JSON of the join condition (see {@link canonicalizeQueryNode}). */
   condition: string;
-  /** Reserved for optional joins; absent today so it does not perturb the hash. */
+  /** Emitted only for `"left"` — an inner join (the default) carries no key. @since 0.1.136 */
   kind?: "inner" | "left";
 }
+/**
+ * One column of a managed view as stored in its snapshot — the PHYSICAL
+ * source it reads, so a source rename (`@db.column`, flattening, a moved
+ * JSON leaf) or an aggregate change recreates the view.
+ * @since 0.1.136
+ */
+interface TViewColumnSnapshot {
+  column: string;
+  sourceTable: string;
+  sourceColumn: string;
+  /** JSON array of the path segments inside a JSON source column. */
+  jsonPath?: string;
+  jsonType?: string;
+  aggFn?: string;
+  aggField?: string;
+  /** Canonical JSON of a conditional aggregate's predicate. */
+  aggFilter?: string;
+}
 interface TViewSnapshot {
   tableName: string;
   viewType: "V" | "M" | "E";
@@ -281,6 +299,8 @@ interface TViewSnapshot {
    * join-less view (`[]`) serializes byte-identically to older snapshots.
    */
   joinTables?: TViewJoinSnapshot[];
+  /** @since 0.1.136 — view columns and their physical sources, sorted by `column`. */
+  columns?: TViewColumnSnapshot[];
   filterHash?: string;
   /** @since 0.1.128 — hash of the canonical `@db.view.having` predicate. */
   havingHash?: string;
@@ -649,4 +669,4 @@ declare function syncSchema(space: DbSpace, types: readonly TAtscriptAnnotatedTy
  */
 declare function planSchema(space: DbSpace, types: readonly TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe">): Promise<TSyncPlan>;
 //#endregion
-export { SchemaSync, SyncEntry, type TDbObjectKind, type TDependencyEdge, type TEnsureTableOptions, type TExistingForeignKey, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TPrimaryKeyChange, type TReferencingForeignKey, type TSyncColors, type TSyncEntryInit, type TSyncEntryStatus, type TSyncOptions, type TSyncPlan, type TSyncResult, type TSyncSkippedWork, type TTableSnapshot, type TViewJoinSnapshot, type TViewSnapshot, canonicalizeQueryNode, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };
+export { SchemaSync, SyncEntry, type TDbObjectKind, type TDependencyEdge, type TEnsureTableOptions, type TExistingForeignKey, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TPrimaryKeyChange, type TReferencingForeignKey, type TSyncColors, type TSyncEntryInit, type TSyncEntryStatus, type TSyncOptions, type TSyncPlan, type TSyncResult, type TSyncSkippedWork, type TTableSnapshot, type TViewColumnSnapshot, type TViewJoinSnapshot, type TViewSnapshot, canonicalizeQueryNode, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };

package/dist/sync.mjs

@@ -1,4 +1,4 @@
-import { U as NoopLogger } from "./db-view-Doh8vPg3.mjs";
+import { W as NoopLogger } from "./db-view-BrAtbaOx.mjs";
 //#region src/schema/schema-hash.ts
 /** Extracts sorted field snapshots from a readable's field descriptors. */
 function extractFieldSnapshots(fields, typeMapper) {
@@ -65,20 +65,43 @@ function computeViewSnapshot(view) {
 	};
 	const plan = view.viewPlan;
 	const qualify = (ref) => view.resolveFieldRef(ref, (n) => n);
+	const canonical = (node) => JSON.stringify(canonicalizeQueryNode(node, qualify));
+	const columns = view.getViewColumnMappings().map((m) => {
+		const col = {
+			column: m.viewColumn,
+			sourceTable: m.sourceTable,
+			sourceColumn: m.sourceColumn
+		};
+		if (m.json) {
+			col.jsonPath = JSON.stringify(m.json.path);
+			col.jsonType = m.json.type;
+		}
+		if (m.aggFn) col.aggFn = m.aggFn;
+		if (m.aggField) col.aggField = m.aggField;
+		if (m.aggFilter) col.aggFilter = canonical(m.aggFilter);
+		return col;
+	}).toSorted((a, b) => a.column < b.column ? -1 : a.column > b.column ? 1 : 0);
 	const result = {
 		tableName: view.tableName,
 		viewType: plan.materialized ? "M" : "V",
 		entryTable: plan.entryTable,
-		joinTables: plan.joins.map((j) => ({
-			targetTable: j.targetTable,
-			condition: JSON.stringify(canonicalizeQueryNode(j.condition, qualify))
-		})),
-		materialized: plan.materialized || void 0,
+		joinTables: plan.joins.map((j) => {
+			const join = {
+				targetTable: j.targetTable,
+				condition: canonical(j.condition)
+			};
+			if (j.kind === "left") join.kind = "left";
+			return join;
+		}),
+		columns
+	};
+	if (plan.filter) result.filterHash = fnv1a(canonical(plan.filter));
+	if (plan.having) result.havingHash = fnv1a(canonical(plan.having));
+	if (plan.materialized) result.materialized = true;
+	return {
+		...result,
 		fields
 	};
-	if (plan.filter) result.filterHash = fnv1a(JSON.stringify(canonicalizeQueryNode(plan.filter, qualify)));
-	if (plan.having) result.havingHash = fnv1a(JSON.stringify(canonicalizeQueryNode(plan.having, qualify)));
-	return result;
 }
 /**
 * Converts a view predicate (join condition, `@db.view.filter`,
@@ -1746,7 +1769,11 @@ var SchemaSync = class {
 				if (d.externalTargets.get(fk.targetTable) === false) addRefusal(refusals, t.name, `FK ${t.name}.${fk.fields.join(",")} references "${fk.targetTable}" which is neither in the sync inventory nor present in the database`);
 			}
 		}
-		for (const view of d.views) if (d.viewObjectKinds.get(view.tableName) === "table") addRefusal(refusals, view.tableName, `A physical table "${view.tableName}" exists where managed view "${view.tableName}" is declared — drop or rename it`);
+		for (const view of d.views) {
+			if (d.viewObjectKinds.get(view.tableName) === "table") addRefusal(refusals, view.tableName, `A physical table "${view.tableName}" exists where managed view "${view.tableName}" is declared — drop or rename it`);
+			const fns = view.dbAdapter.aggregateFns();
+			for (const col of view.getViewColumnMappings()) if (col.aggFn && !fns.has(col.aggFn)) addRefusal(refusals, view.tableName, `View "${view.tableName}" field "${col.viewPath}": aggregate "${col.aggFn}" is not supported by this adapter (aggregateFns())`);
+		}
 		if (!safe) for (const r of d.removed) {
 			if (r.isView) continue;
 			const referencers = [];

package/dist/{validation-utils-MWOP1Ts4.mjs → validation-utils-B4h-GW4d.mjs}

@@ -11,14 +11,17 @@ function validateExclusiveWith(token, selfName, others) {
 	});
 	return errors;
 }
+/** Primitive base type (`string`, `number`, `decimal`, …) of a resolved definition, if it is a primitive. */
+function primitiveBaseType(def) {
+	if (!def || !isPrimitive(def)) return void 0;
+	const ct = def.config.type;
+	return typeof ct === "object" ? ct.kind === "final" ? ct.value : ct.kind : ct;
+}
 /** Resolves a field/prop's primitive base type, or `undefined` if it isn't a ref-to-primitive. */
 function getPrimitiveBaseType(node, doc) {
 	const def = node.getDefinition();
 	if (!def || !isRef(def)) return void 0;
-	const unwound = doc.unwindType(def.id, def.chain);
-	if (!unwound || !isPrimitive(unwound.def)) return void 0;
-	const ct = unwound.def.config.type;
-	return typeof ct === "object" ? ct.kind === "final" ? ct.value : ct.kind : ct;
+	return primitiveBaseType(doc.unwindType(def.id, def.chain)?.def);
 }
 /** Asserts `args[0]` names a sibling property whose primitive base type is `string`. */
 function validateSiblingStringField(token, args, doc, selfName) {
@@ -253,6 +256,24 @@ const viewAnnotationNames = [
 	"db.view.filter",
 	"db.view.materialized"
 ];
+/** The `@db.view.joins` annotations of a view interface, in declaration order. */
+function viewJoins(owner) {
+	return owner.annotations?.filter((a) => a.name === "db.view.joins") ?? [];
+}
+/** The target type names of `@db.view.joins` annotations. */
+function joinTargets(joins) {
+	return joins.map((a) => a.args[0]?.text).filter((t) => !!t);
+}
+/**
+* The type names a view predicate (`@db.view.filter`, a conditional
+* `@db.agg.*`) may reference: the `@db.view.for` entry table, then every
+* `@db.view.joins` target.
+*/
+function viewScopeTypes(owner) {
+	const entry = getAnnotationAlias(owner, "db.view.for");
+	const targets = joinTargets(viewJoins(owner));
+	return entry ? [entry, ...targets] : targets;
+}
 /**
 * Check if a node has any @db.view.* annotation.
 */
@@ -266,8 +287,9 @@ function hasAnyViewAnnotation(node) {
 * @param allowedTypes - Type names allowed as qualified refs
 * @param unqualifiedTarget - Type name for resolving unqualified refs, or null to disallow them
 * @param doc - The document for type lookups
+* @param scopeHint - Replaces the default "expected 'A' or 'B'" tail of the out-of-scope message
 */
-function validateQueryScope(queryToken, allowedTypes, unqualifiedTarget, doc) {
+function validateQueryScope(queryToken, allowedTypes, unqualifiedTarget, doc, scopeHint) {
 	const errors = [];
 	const queryNode = queryToken.queryNode;
 	if (!queryNode) return errors;
@@ -275,7 +297,7 @@ function validateQueryScope(queryToken, allowedTypes, unqualifiedTarget, doc) {
 		if (ref.typeRef) {
 			const typeName = ref.typeRef.text;
 			if (!allowedTypes.includes(typeName)) errors.push({
-				message: `Query references '${typeName}' which is not in scope — expected ${allowedTypes.map((t) => `'${t}'`).join(" or ")}`,
+				message: `Query references '${typeName}' which is not in scope — ${scopeHint ?? `expected ${allowedTypes.map((t) => `'${t}'`).join(" or ")}`}`,
 				severity: 1,
 				range: ref.typeRef.range
 			});
@@ -310,4 +332,4 @@ function validateQueryScope(queryToken, allowedTypes, unqualifiedTarget, doc) {
 	return errors;
 }
 //#endregion
-export { getAnnotationAlias as a, getParentStruct as c, validateExclusiveWith as d, validateFieldBaseType as f, validateRefArgument as i, getParentTypeName as l, hasAnyViewAnnotation as n, getDbTableOwner as o, validateSiblingStringField as p, validateQueryScope as r, getNavTargetTypeName as s, findFKFieldsPointingTo as t, refActionAnnotation as u };
+export { validateSiblingStringField as _, validateRefArgument as a, getAnnotationAlias as c, getParentStruct as d, getParentTypeName as f, validateFieldBaseType as g, validateExclusiveWith as h, validateQueryScope as i, getDbTableOwner as l, refActionAnnotation as m, hasAnyViewAnnotation as n, viewJoins as o, primitiveBaseType as p, joinTargets as r, viewScopeTypes as s, findFKFieldsPointingTo as t, getNavTargetTypeName as u };

package/dist/{validation-utils-B7SXPkm7.cjs → validation-utils-Dg0hW6dn.cjs}

@@ -11,14 +11,17 @@ function validateExclusiveWith(token, selfName, others) {
 	});
 	return errors;
 }
+/** Primitive base type (`string`, `number`, `decimal`, …) of a resolved definition, if it is a primitive. */
+function primitiveBaseType(def) {
+	if (!def || !(0, _atscript_core.isPrimitive)(def)) return void 0;
+	const ct = def.config.type;
+	return typeof ct === "object" ? ct.kind === "final" ? ct.value : ct.kind : ct;
+}
 /** Resolves a field/prop's primitive base type, or `undefined` if it isn't a ref-to-primitive. */
 function getPrimitiveBaseType(node, doc) {
 	const def = node.getDefinition();
 	if (!def || !(0, _atscript_core.isRef)(def)) return void 0;
-	const unwound = doc.unwindType(def.id, def.chain);
-	if (!unwound || !(0, _atscript_core.isPrimitive)(unwound.def)) return void 0;
-	const ct = unwound.def.config.type;
-	return typeof ct === "object" ? ct.kind === "final" ? ct.value : ct.kind : ct;
+	return primitiveBaseType(doc.unwindType(def.id, def.chain)?.def);
 }
 /** Asserts `args[0]` names a sibling property whose primitive base type is `string`. */
 function validateSiblingStringField(token, args, doc, selfName) {
@@ -253,6 +256,24 @@ const viewAnnotationNames = [
 	"db.view.filter",
 	"db.view.materialized"
 ];
+/** The `@db.view.joins` annotations of a view interface, in declaration order. */
+function viewJoins(owner) {
+	return owner.annotations?.filter((a) => a.name === "db.view.joins") ?? [];
+}
+/** The target type names of `@db.view.joins` annotations. */
+function joinTargets(joins) {
+	return joins.map((a) => a.args[0]?.text).filter((t) => !!t);
+}
+/**
+* The type names a view predicate (`@db.view.filter`, a conditional
+* `@db.agg.*`) may reference: the `@db.view.for` entry table, then every
+* `@db.view.joins` target.
+*/
+function viewScopeTypes(owner) {
+	const entry = getAnnotationAlias(owner, "db.view.for");
+	const targets = joinTargets(viewJoins(owner));
+	return entry ? [entry, ...targets] : targets;
+}
 /**
 * Check if a node has any @db.view.* annotation.
 */
@@ -266,8 +287,9 @@ function hasAnyViewAnnotation(node) {
 * @param allowedTypes - Type names allowed as qualified refs
 * @param unqualifiedTarget - Type name for resolving unqualified refs, or null to disallow them
 * @param doc - The document for type lookups
+* @param scopeHint - Replaces the default "expected 'A' or 'B'" tail of the out-of-scope message
 */
-function validateQueryScope(queryToken, allowedTypes, unqualifiedTarget, doc) {
+function validateQueryScope(queryToken, allowedTypes, unqualifiedTarget, doc, scopeHint) {
 	const errors = [];
 	const queryNode = queryToken.queryNode;
 	if (!queryNode) return errors;
@@ -275,7 +297,7 @@ function validateQueryScope(queryToken, allowedTypes, unqualifiedTarget, doc) {
 		if (ref.typeRef) {
 			const typeName = ref.typeRef.text;
 			if (!allowedTypes.includes(typeName)) errors.push({
-				message: `Query references '${typeName}' which is not in scope — expected ${allowedTypes.map((t) => `'${t}'`).join(" or ")}`,
+				message: `Query references '${typeName}' which is not in scope — ${scopeHint ?? `expected ${allowedTypes.map((t) => `'${t}'`).join(" or ")}`}`,
 				severity: 1,
 				range: ref.typeRef.range
 			});
@@ -352,6 +374,18 @@ Object.defineProperty(exports, "hasAnyViewAnnotation", {
 		return hasAnyViewAnnotation;
 	}
 });
+Object.defineProperty(exports, "joinTargets", {
+	enumerable: true,
+	get: function() {
+		return joinTargets;
+	}
+});
+Object.defineProperty(exports, "primitiveBaseType", {
+	enumerable: true,
+	get: function() {
+		return primitiveBaseType;
+	}
+});
 Object.defineProperty(exports, "refActionAnnotation", {
 	enumerable: true,
 	get: function() {
@@ -388,3 +422,15 @@ Object.defineProperty(exports, "validateSiblingStringField", {
 		return validateSiblingStringField;
 	}
 });
+Object.defineProperty(exports, "viewJoins", {
+	enumerable: true,
+	get: function() {
+		return viewJoins;
+	}
+});
+Object.defineProperty(exports, "viewScopeTypes", {
+	enumerable: true,
+	get: function() {
+		return viewScopeTypes;
+	}
+});

package/dist/{validator-CewfnGZj.d.mts → validator-Drb2N-YL.d.cts}

@@ -1,7 +1,7 @@
 import { TAtscriptAnnotatedType, TAtscriptTypeArray, TAtscriptTypeObject, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
 
 //#region src/db-error.d.ts
-type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY" | "DEPTH_EXCEEDED" | "VERSION_COLUMN_WRITE" | "CAS_EXHAUSTED" | "CAS_MISMATCH" | "ENC_CONFIG_MISSING" | "ENC_KEY_INVALID" | "ENC_NOT_ENCRYPTED" | "ENC_DECRYPT_FAILED" | "ENC_FIELD_FILTER" | "ENC_FIELD_SORT" | "ENC_FIELD_AGG" | "ENC_FIELD_PATCH_OP" | "GEO_INDEX_MISSING" | "GEO_NOT_SUPPORTED" | "FILTER_TYPE_MISMATCH" /** The adapter's `calendarBucketUnits()` lacks the requested unit (moost-db: 400). */ | "BUCKET_NOT_SUPPORTED" /** The engine cannot resolve the bucket's time zone — a store-configuration condition (moost-db: 501). */ | "BUCKET_TZ_UNAVAILABLE" | "TX_WAIT_TIMEOUT";
+type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY" | "DEPTH_EXCEEDED" | "VERSION_COLUMN_WRITE" | "CAS_EXHAUSTED" | "CAS_MISMATCH" | "ENC_CONFIG_MISSING" | "ENC_KEY_INVALID" | "ENC_NOT_ENCRYPTED" | "ENC_DECRYPT_FAILED" | "ENC_FIELD_FILTER" | "ENC_FIELD_SORT" | "ENC_FIELD_AGG" | "ENC_FIELD_PATCH_OP" | "GEO_INDEX_MISSING" | "GEO_NOT_SUPPORTED" | "FILTER_TYPE_MISMATCH" /** The adapter's `calendarBucketUnits()` lacks the requested unit (moost-db: 400). */ | "BUCKET_NOT_SUPPORTED" /** The engine cannot resolve the bucket's time zone — a store-configuration condition (moost-db: 501). */ | "BUCKET_TZ_UNAVAILABLE" /** A known aggregate function the adapter's `aggregateFns()` lacks (moost-db: 400). @since 0.1.136 */ | "AGG_FN_NOT_SUPPORTED" | "TX_WAIT_TIMEOUT";
 declare class DbError extends Error {
   readonly code: DbErrorCode;
   readonly errors: Array<{

package/dist/{validator-CewfnGZj.d.cts → validator-Drb2N-YL.d.mts}

@@ -1,7 +1,7 @@
 import { TAtscriptAnnotatedType, TAtscriptTypeArray, TAtscriptTypeObject, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
 
 //#region src/db-error.d.ts
-type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY" | "DEPTH_EXCEEDED" | "VERSION_COLUMN_WRITE" | "CAS_EXHAUSTED" | "CAS_MISMATCH" | "ENC_CONFIG_MISSING" | "ENC_KEY_INVALID" | "ENC_NOT_ENCRYPTED" | "ENC_DECRYPT_FAILED" | "ENC_FIELD_FILTER" | "ENC_FIELD_SORT" | "ENC_FIELD_AGG" | "ENC_FIELD_PATCH_OP" | "GEO_INDEX_MISSING" | "GEO_NOT_SUPPORTED" | "FILTER_TYPE_MISMATCH" /** The adapter's `calendarBucketUnits()` lacks the requested unit (moost-db: 400). */ | "BUCKET_NOT_SUPPORTED" /** The engine cannot resolve the bucket's time zone — a store-configuration condition (moost-db: 501). */ | "BUCKET_TZ_UNAVAILABLE" | "TX_WAIT_TIMEOUT";
+type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY" | "DEPTH_EXCEEDED" | "VERSION_COLUMN_WRITE" | "CAS_EXHAUSTED" | "CAS_MISMATCH" | "ENC_CONFIG_MISSING" | "ENC_KEY_INVALID" | "ENC_NOT_ENCRYPTED" | "ENC_DECRYPT_FAILED" | "ENC_FIELD_FILTER" | "ENC_FIELD_SORT" | "ENC_FIELD_AGG" | "ENC_FIELD_PATCH_OP" | "GEO_INDEX_MISSING" | "GEO_NOT_SUPPORTED" | "FILTER_TYPE_MISMATCH" /** The adapter's `calendarBucketUnits()` lacks the requested unit (moost-db: 400). */ | "BUCKET_NOT_SUPPORTED" /** The engine cannot resolve the bucket's time zone — a store-configuration condition (moost-db: 501). */ | "BUCKET_TZ_UNAVAILABLE" /** A known aggregate function the adapter's `aggregateFns()` lacks (moost-db: 400). @since 0.1.136 */ | "AGG_FN_NOT_SUPPORTED" | "TX_WAIT_TIMEOUT";
 declare class DbError extends Error {
   readonly code: DbErrorCode;
   readonly errors: Array<{

package/dist/validator.d.cts

@@ -1,4 +1,4 @@
 import { a as $mul, c as $update, d as TDbFieldOp, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.cjs";
-import { a as buildValidationContext, c as isNavRelation, d as TArrayPatch, f as TDbPatch, g as DbError, i as buildPatchPartial, l as isEmptyObject, n as ValidatorMode, o as dbPlugin, p as getKeyProps, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as isPlainObject } from "./validator-CewfnGZj.cjs";
+import { a as buildValidationContext, c as isNavRelation, d as TArrayPatch, f as TDbPatch, g as DbError, i as buildPatchPartial, l as isEmptyObject, n as ValidatorMode, o as dbPlugin, p as getKeyProps, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as isPlainObject } from "./validator-Drb2N-YL.cjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
 export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, DbError, type DbValidationContext, type TArrayPatch, type TDbCas, type TDbFieldOp, type TDbPatch, ValidationContext, ValidatorMode, buildDbValidator, buildPatchPartial, buildValidationContext, createDbValidatorPlugin, dbPlugin, forceNavNonOptional, getKeyProps, isDbFieldOp, isEmptyObject, isNavRelation, isPlainObject, reconcileCas, separateCas };

package/dist/validator.d.mts

@@ -1,4 +1,4 @@
 import { a as $mul, c as $update, d as TDbFieldOp, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.mjs";
-import { a as buildValidationContext, c as isNavRelation, d as TArrayPatch, f as TDbPatch, g as DbError, i as buildPatchPartial, l as isEmptyObject, n as ValidatorMode, o as dbPlugin, p as getKeyProps, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as isPlainObject } from "./validator-CewfnGZj.mjs";
+import { a as buildValidationContext, c as isNavRelation, d as TArrayPatch, f as TDbPatch, g as DbError, i as buildPatchPartial, l as isEmptyObject, n as ValidatorMode, o as dbPlugin, p as getKeyProps, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as isPlainObject } from "./validator-Drb2N-YL.mjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
 export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, DbError, type DbValidationContext, type TArrayPatch, type TDbCas, type TDbFieldOp, type TDbPatch, ValidationContext, ValidatorMode, buildDbValidator, buildPatchPartial, buildValidationContext, createDbValidatorPlugin, dbPlugin, forceNavNonOptional, getKeyProps, isDbFieldOp, isEmptyObject, isNavRelation, isPlainObject, reconcileCas, separateCas };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db",
-  "version": "0.1.135",
+  "version": "0.1.136",
   "description": "Database adapter utilities for atscript.",
   "keywords": [
     "atscript",

package/dist/agg-CvXDGnKi.mjs

@@ -1,61 +0,0 @@
-import { r as DbError } from "./db-error-D5uilS_A.mjs";
-import { isAggregateExpr as isAggregateExpr$1, isBucketExpr as isBucketExpr$1, resolveAlias } from "@uniqu/core";
-//#region src/query/aggregate-fns.ts
-/**
-* The only `$fn` names a `$select` aggregate may use (since 0.1.135). Any
-* other name is rejected with `INVALID_QUERY` (HTTP 400 through moost-db)
-* before a query reaches an adapter, so no adapter ever renders an unchecked
-* function name into SQL or a pipeline.
-*/
-const SUPPORTED_AGGREGATE_FNS = [
-	"sum",
-	"count",
-	"avg",
-	"min",
-	"max"
-];
-const SUPPORTED_LIST = `${SUPPORTED_AGGREGATE_FNS.slice(0, -1).join(", ")} or ${SUPPORTED_AGGREGATE_FNS.at(-1)}`;
-/**
-* Throws `DbError` `INVALID_QUERY` (uniqu's wording) unless `fn` is in
-* `SUPPORTED_AGGREGATE_FNS` — for adapters to re-assert before rendering.
-*/
-function assertAggregateFn(fn, path = "$select") {
-	if (!SUPPORTED_AGGREGATE_FNS.includes(fn)) throw new DbError("INVALID_QUERY", [{
-		path,
-		message: `Unknown aggregate function "${String(fn)}" — use ${SUPPORTED_LIST}`
-	}]);
-}
-//#endregion
-//#region src/agg.ts
-/**
-* Reads the `$search` / `$index` controls of an aggregate query.
-*
-* Search and grouping are orthogonal: `$search` narrows the ROWS, `$groupBy`
-* shapes what is left. Every adapter must therefore apply the search predicate
-* BEFORE grouping, so the groups — and `$count`, which counts them — only ever
-* describe rows that matched. An adapter that silently ignored the term would
-* report totals for rows the same search excludes from the leaf list.
-*
-* Two rules the leaf search path applies and the grouped path must NOT:
-* - **No implicit relevance ordering.** Relevance is a property of a row, not
-*   of a group; after `$group` there is no per-row score left to sort on.
-*   Grouped results order by `$sort` or not at all.
-* - **No implicit row cap.** The leaf runners cap an unbounded search at 1000
-*   rows; applying that before `$group` would silently truncate group counts.
-*
-* Returns `undefined` when there is nothing to search for, so callers fall
-* straight through to the plain grouped path.
-*/
-function resolveAggregateSearch(controls) {
-	const raw = controls?.$search;
-	if (typeof raw !== "string") return;
-	const text = raw.trim();
-	if (!text) return;
-	const index = controls?.$index;
-	return {
-		text,
-		indexName: typeof index === "string" && index ? index : void 0
-	};
-}
-//#endregion
-export { SUPPORTED_AGGREGATE_FNS as a, resolveAlias as i, isBucketExpr$1 as n, assertAggregateFn as o, resolveAggregateSearch as r, isAggregateExpr$1 as t };

package/dist/agg-EcIbAFnJ.cjs

@@ -1,78 +0,0 @@
-const require_db_error = require("./db-error-DTkkeu5b.cjs");
-require("@uniqu/core");
-//#region src/query/aggregate-fns.ts
-/**
-* The only `$fn` names a `$select` aggregate may use (since 0.1.135). Any
-* other name is rejected with `INVALID_QUERY` (HTTP 400 through moost-db)
-* before a query reaches an adapter, so no adapter ever renders an unchecked
-* function name into SQL or a pipeline.
-*/
-const SUPPORTED_AGGREGATE_FNS = [
-	"sum",
-	"count",
-	"avg",
-	"min",
-	"max"
-];
-const SUPPORTED_LIST = `${SUPPORTED_AGGREGATE_FNS.slice(0, -1).join(", ")} or ${SUPPORTED_AGGREGATE_FNS.at(-1)}`;
-/**
-* Throws `DbError` `INVALID_QUERY` (uniqu's wording) unless `fn` is in
-* `SUPPORTED_AGGREGATE_FNS` — for adapters to re-assert before rendering.
-*/
-function assertAggregateFn(fn, path = "$select") {
-	if (!SUPPORTED_AGGREGATE_FNS.includes(fn)) throw new require_db_error.DbError("INVALID_QUERY", [{
-		path,
-		message: `Unknown aggregate function "${String(fn)}" — use ${SUPPORTED_LIST}`
-	}]);
-}
-//#endregion
-//#region src/agg.ts
-/**
-* Reads the `$search` / `$index` controls of an aggregate query.
-*
-* Search and grouping are orthogonal: `$search` narrows the ROWS, `$groupBy`
-* shapes what is left. Every adapter must therefore apply the search predicate
-* BEFORE grouping, so the groups — and `$count`, which counts them — only ever
-* describe rows that matched. An adapter that silently ignored the term would
-* report totals for rows the same search excludes from the leaf list.
-*
-* Two rules the leaf search path applies and the grouped path must NOT:
-* - **No implicit relevance ordering.** Relevance is a property of a row, not
-*   of a group; after `$group` there is no per-row score left to sort on.
-*   Grouped results order by `$sort` or not at all.
-* - **No implicit row cap.** The leaf runners cap an unbounded search at 1000
-*   rows; applying that before `$group` would silently truncate group counts.
-*
-* Returns `undefined` when there is nothing to search for, so callers fall
-* straight through to the plain grouped path.
-*/
-function resolveAggregateSearch(controls) {
-	const raw = controls?.$search;
-	if (typeof raw !== "string") return;
-	const text = raw.trim();
-	if (!text) return;
-	const index = controls?.$index;
-	return {
-		text,
-		indexName: typeof index === "string" && index ? index : void 0
-	};
-}
-//#endregion
-Object.defineProperty(exports, "SUPPORTED_AGGREGATE_FNS", {
-	enumerable: true,
-	get: function() {
-		return SUPPORTED_AGGREGATE_FNS;
-	}
-});
-Object.defineProperty(exports, "assertAggregateFn", {
-	enumerable: true,
-	get: function() {
-		return assertAggregateFn;
-	}
-});
-Object.defineProperty(exports, "resolveAggregateSearch", {
-	enumerable: true,
-	get: function() {
-		return resolveAggregateSearch;
-	}
-});