@trilogy-data/trilogy-studio-components 0.1.25 → 0.1.26

package/dist/{editorRefinementToolExecutor-mX8ClQ63.js → editorRefinementToolExecutor-CVY3FA7k.js}

@@ -299,7 +299,7 @@ var c = class e {
 	size() {
 		return this.cache.size;
 	}
-}, y = class {
+}, y = class e {
 	settingStore;
 	validateCache;
 	formatCache;
@@ -338,17 +338,28 @@ var c = class e {
 	buildResolverUrl(e) {
 		return `${this.settingStore.settings.trilogyResolver.replace(/\/+$/, "")}/${e}`;
 	}
-	async fetchWithErrorHandling(e, t) {
+	static RETRY_STATUSES = /* @__PURE__ */ new Set([503]);
+	static MAX_RETRIES = 3;
+	static MAX_RETRY_DELAY_MS = 5e3;
+	delay(e) {
+		return new Promise((t) => setTimeout(t, e));
+	}
+	retryDelayMs(t, n) {
+		let r = Number(t.headers?.get?.("retry-after")), i = Number.isFinite(r) && r > 0 ? r * 1e3 : 500 * 2 ** n;
+		return Math.min(i, e.MAX_RETRY_DELAY_MS) * (.75 + Math.random() * .5);
+	}
+	async fetchWithErrorHandling(t, n) {
 		try {
-			let n = await fetch(e, t);
-			if (!n.ok) {
-				let e = await n.json().catch(() => ({}));
+			let r = await fetch(t, n);
+			for (let i = 0; !r.ok && e.RETRY_STATUSES.has(r.status) && i < e.MAX_RETRIES; i++) await this.delay(this.retryDelayMs(r, i)), r = await fetch(t, n);
+			if (!r.ok) {
+				let e = await r.json().catch(() => ({}));
 				throw {
-					message: `HTTP error ${n.status}`,
+					message: `HTTP error ${r.status}`,
 					response: { data: e }
 				};
 			}
-			return { data: await n.json() };
+			return { data: await r.json() };
 		} catch (e) {
 			throw console.log(e), Error(this.getErrorMessage(e));
 		}
@@ -926,9 +937,9 @@ function De(e) {
 			Object.entries(e).forEach(([e, n]) => {
 				t[e] || (t[e] = []), t[e].push(n);
 			});
-		}), Object.entries(t).map(([e, t]) => t.length > 1 ? `(${t.map((t) => ke(e, t)).join(" OR ")})` : ke(e, t[0])).join(" AND ");
+		}), Object.entries(t).map(([e, t]) => t.length > 1 ? `(${t.map((t) => C(e, t)).join(" OR ")})` : C(e, t[0])).join(" AND ");
 	}
-	return Object.keys(e).length === 0 ? "" : Object.entries(e).map(([e, t]) => ke(e, t)).join(" AND ");
+	return Object.keys(e).length === 0 ? "" : Object.entries(e).map(([e, t]) => C(e, t)).join(" AND ");
 }
 function Oe(e) {
 	if (e instanceof Date) return `'${e.getFullYear()}-${String(e.getMonth() + 1).padStart(2, "0")}-${String(e.getDate()).padStart(2, "0")}'::date`;
@@ -937,23 +948,23 @@ function Oe(e) {
 	if (typeof e == "boolean") return e ? "TRUE" : "FALSE";
 	if (typeof e == "number") return e.toString();
 }
-function ke(e, t) {
+function C(e, t) {
 	return t === null ? `${e} IS NULL` : typeof t == "string" ? `${e}='''${t.replace(/'/g, "!`")}'''` : Array.isArray(t) ? `${e} between ${Oe(t[0])} and ${Oe(t[t.length - 1])}` : typeof t == "number" || typeof t == "boolean" ? `${e}=${t}` : t === void 0 ? `${e} IS NULL` : `${e}='${JSON.stringify(t).replace(/'/g, "!`")}'`;
 }
 //#endregion
 //#region dashboards/crossFilters.ts
-function Ae(e = []) {
+function ke(e = []) {
 	let t = /* @__PURE__ */ new Set();
 	for (let n of e) n?.label && t.add(n.label);
 	return Array.from(t);
 }
-function C(e) {
+function w(e) {
 	return { ...e };
 }
-function w(e) {
+function T(e) {
 	return { ...e };
 }
-function je(e, t) {
+function Ae(e, t) {
 	if (e.op !== t.op) return !1;
 	switch (e.op) {
 		case "is_null": return !0;
@@ -968,31 +979,31 @@ function je(e, t) {
 		}
 	}
 }
-function T(e, t) {
+function E(e, t) {
 	let n = Object.keys(e).sort(), r = Object.keys(t).sort();
-	return n.length === r.length && n.every((n, i) => n === r[i] && je(e[n], t[n]));
+	return n.length === r.length && n.every((n, i) => n === r[i] && Ae(e[n], t[n]));
 }
-function Me(e, t) {
+function je(e, t) {
 	return Array.isArray(e) && Array.isArray(t) ? e.length === t.length && e.every((e, n) => e === t[n]) : e === t;
 }
-function Ne(e, t) {
+function Me(e, t) {
 	let n = Object.keys(e).sort(), r = Object.keys(t).sort();
-	return n.length === r.length && n.every((n, i) => n === r[i] && Me(e[n], t[n]));
+	return n.length === r.length && n.every((n, i) => n === r[i] && je(e[n], t[n]));
 }
-function Pe(e, t, n, r) {
+function Ne(e, t, n, r) {
 	let i = e.filter((e) => e.source !== t), a = e.filter((e) => e.source === t);
 	if (r === "remove") return i;
 	if (r === "add") return [...i, {
 		source: t,
-		value: w(n)
+		value: T(n)
 	}];
-	let o = a.some((e) => Ne(e.value, n)) ? a.filter((e) => !Ne(e.value, n)) : [...a, {
+	let o = a.some((e) => Me(e.value, n)) ? a.filter((e) => !Me(e.value, n)) : [...a, {
 		source: t,
-		value: w(n)
+		value: T(n)
 	}];
 	return [...i, ...o];
 }
-function Fe(e, t, n) {
+function Pe(e, t, n) {
 	if (t.size === 0) return n && e.startsWith("local.") ? e.replace(/^local\./, "") : e;
 	if (t.has(e)) return e;
 	if (e.startsWith("local.")) {
@@ -1001,7 +1012,7 @@ function Fe(e, t, n) {
 	}
 	return null;
 }
-function Ie(e, t = [], n = {}) {
+function Fe(e, t = [], n = {}) {
 	let r = new Set(t), i = n.normalizeLocalFields ?? !1;
 	return Object.entries(e).reduce((e, [t, n]) => {
 		if (typeof n != "object" || !n || ![
@@ -1010,11 +1021,11 @@ function Ie(e, t = [], n = {}) {
 			"in",
 			"is_null"
 		].includes(n.op)) return e;
-		let a = Fe(t, r, i);
+		let a = Pe(t, r, i);
 		return a && (e[a] = n), e;
 	}, {});
 }
-function E(e) {
+function D(e) {
 	if (!e.length) return {
 		filterStrings: [],
 		parameters: {}
@@ -1044,8 +1055,8 @@ function E(e) {
 		parameters: r
 	};
 }
-function D(e) {
-	let t = e.conceptFilters || [], n = (e.filters || []).filter((e) => e.source !== "cross"), { filterStrings: r, parameters: i } = E(t), a = r.join(" AND ");
+function O(e) {
+	let t = e.conceptFilters || [], n = (e.filters || []).filter((e) => e.source !== "cross"), { filterStrings: r, parameters: i } = D(t), a = r.join(" AND ");
 	a && n.push({
 		source: "cross",
 		value: a,
@@ -1054,43 +1065,43 @@ function D(e) {
 	let o = JSON.stringify(n) !== JSON.stringify(e.filters || []);
 	return e.filters = n, o;
 }
-function Le(e, t, n, r) {
+function Ie(e, t, n, r) {
 	let i = e.filter((e) => e.source !== t), a = e.filter((e) => e.source === t);
 	if (r === "remove") return i;
 	if (r === "add") return [...i, {
 		source: t,
-		value: C(n)
+		value: w(n)
 	}];
-	let o = a.some((e) => T(e.value, n)) ? a.filter((e) => !T(e.value, n)) : [...a, {
+	let o = a.some((e) => E(e.value, n)) ? a.filter((e) => !E(e.value, n)) : [...a, {
 		source: t,
-		value: C(n)
+		value: w(n)
 	}];
 	return [...i, ...o];
 }
-function Re(e, t, n, r, i) {
+function Le(e, t, n, r, i) {
 	let a = [];
 	return Object.entries(e).forEach(([e, o]) => {
 		if (e === t) {
-			let e = Pe(o.chartFilters || [], t, r, i);
+			let e = Ne(o.chartFilters || [], t, r, i);
 			JSON.stringify(e) !== JSON.stringify(o.chartFilters || []) && (o.chartFilters = e);
 			return;
 		}
 		if (!o.allowCrossFilter) return;
-		let s = Le(o.conceptFilters || [], t, n, i), c = JSON.stringify(s) !== JSON.stringify(o.conceptFilters || []);
+		let s = Ie(o.conceptFilters || [], t, n, i), c = JSON.stringify(s) !== JSON.stringify(o.conceptFilters || []);
 		c && (o.conceptFilters = s);
-		let l = D(o);
+		let l = O(o);
 		(c || l) && a.push(e);
 	}), a;
 }
-function ze(e, t, n) {
+function Re(e, t, n) {
 	let r = e[t];
 	if (!r) return !1;
 	let i = (r.conceptFilters || []).filter((e) => e.source !== n), a = JSON.stringify(i) !== JSON.stringify(r.conceptFilters || []);
 	a && (r.conceptFilters = i);
-	let o = D(r);
+	let o = O(r);
 	return a || o;
 }
-function Be(e, t) {
+function ze(e, t) {
 	let n = [];
 	return Object.entries(e).forEach(([e, r]) => {
 		if (e === t) {
@@ -1099,27 +1110,27 @@ function Be(e, t) {
 		}
 		let i = (r.conceptFilters || []).filter((e) => e.source !== t), a = JSON.stringify(i) !== JSON.stringify(r.conceptFilters || []);
 		a && (r.conceptFilters = i);
-		let o = D(r);
+		let o = O(r);
 		(a || o) && n.push(e);
 	}), n;
 }
-function Ve(e) {
+function Be(e) {
 	let t = [];
 	return Object.entries(e).forEach(([e, n]) => {
 		let r = !!n.conceptFilters?.length || !!n.chartFilters?.length || !!n.filters?.length;
 		n.conceptFilters = [], n.chartFilters = [], n.filters = [], r && t.push(e);
 	}), t;
 }
-function He(e = {}) {
+function Ve(e = {}) {
 	let t = /* @__PURE__ */ new Map(), n = () => {
 		let t = e.validFields ? o(e.validFields) : [];
 		return new Set(t);
 	}, r = (t) => {
-		let r = Ie(t.filters, n(), { normalizeLocalFields: e.normalizeLocalFields ?? !0 });
+		let r = Fe(t.filters, n(), { normalizeLocalFields: e.normalizeLocalFields ?? !0 });
 		return {
 			source: t.source,
 			filters: r,
-			chart: w(t.chart || {}),
+			chart: T(t.chart || {}),
 			append: t.append
 		};
 	};
@@ -1127,8 +1138,8 @@ function He(e = {}) {
 		getSelections() {
 			return Array.from(t.values()).flat().map((e) => ({
 				source: e.source,
-				filters: C(e.filters),
-				chart: w(e.chart || {}),
+				filters: w(e.filters),
+				chart: T(e.chart || {}),
 				append: e.append
 			}));
 		},
@@ -1141,7 +1152,7 @@ function He(e = {}) {
 			let o = t.get(e.source) || [];
 			if (a === "remove") return t.delete(e.source), i.filters;
 			if (a === "add") return t.set(e.source, [i]), i.filters;
-			let s = o.some((e) => T(e.filters, i.filters)) ? o.filter((e) => !T(e.filters, i.filters)) : [...o, i];
+			let s = o.some((e) => E(e.filters, i.filters)) ? o.filter((e) => !E(e.filters, i.filters)) : [...o, i];
 			return s.length === 0 ? t.delete(e.source) : t.set(e.source, s), i.filters;
 		},
 		clearSource(e) {
@@ -1156,14 +1167,14 @@ function He(e = {}) {
 		getSqlFilterInputsFor(e) {
 			return Array.from(t.entries()).filter(([t]) => t !== e).flatMap(([e, t]) => t.map((t) => ({
 				source: e,
-				value: C(t.filters)
+				value: w(t.filters)
 			})));
 		},
 		getChartSelectionsFor(e) {
-			return (t.get(e) || []).map((e) => w(e.chart || {}));
+			return (t.get(e) || []).map((e) => T(e.chart || {}));
 		},
 		getFilterExpressionFor(e) {
-			let { filterStrings: t } = E(this.getSqlFilterInputsFor(e));
+			let { filterStrings: t } = D(this.getSqlFilterInputsFor(e));
 			return t.join(" AND ");
 		},
 		getSqlFiltersFor(e, t = []) {
@@ -1174,7 +1185,7 @@ function He(e = {}) {
 			let n = t.map((e) => ({
 				source: "base",
 				value: e
-			})), { filterStrings: r, parameters: i } = E(this.getSqlFilterInputsFor(e)), a = r.join(" AND ");
+			})), { filterStrings: r, parameters: i } = D(this.getSqlFilterInputsFor(e)), a = r.join(" AND ");
 			return a && n.push({
 				source: "cross",
 				value: a,
@@ -1182,13 +1193,13 @@ function He(e = {}) {
 			}), n;
 		},
 		getSqlParametersFor(e) {
-			let { parameters: t } = E(this.getSqlFilterInputsFor(e));
+			let { parameters: t } = D(this.getSqlFilterInputsFor(e));
 			return t;
 		}
 	};
 }
-function Ue(e = {}) {
-	let t = a(0), n = He(o(e)), r = () => {
+function He(e = {}) {
+	let t = a(0), n = Ve(o(e)), r = () => {
 		t.value += 1;
 	};
 	return {
@@ -1234,7 +1245,7 @@ function Ue(e = {}) {
 }
 //#endregion
 //#region dashboards/base.ts
-var O = {
+var k = {
 	CHART: "chart",
 	MARKDOWN: "markdown",
 	TABLE: "table",
@@ -1245,24 +1256,24 @@ var O = {
 	APPENDIX_HEADER: "appendix-header",
 	FREEFORM: "freeform"
 };
-function We(e) {
+function Ue(e) {
 	return !!e && typeof e == "object" && "markdown" in e;
 }
-function Ge(e) {
+function We(e) {
 	return !!e && typeof e == "object" && "headline" in e && "verdict" in e && "confidence" in e;
 }
-function Ke(e) {
+function Ge(e) {
 	return !!e && typeof e == "object" && "claim" in e && !("headline" in e);
 }
-function qe(e) {
+function Ke(e) {
 	return !!e && typeof e == "object" && typeof e.html == "string";
 }
-function Je(e) {
+function qe(e) {
 	let t = e.content;
-	if (typeof t == "string") return e.type === O.CHART || e.type === O.TABLE ? t : void 0;
-	if (qe(t) || Ge(t) || Ke(t) || We(t)) return t.query || void 0;
+	if (typeof t == "string") return e.type === k.CHART || e.type === k.TABLE ? t : void 0;
+	if (Ke(t) || We(t) || Ge(t) || Ue(t)) return t.query || void 0;
 }
-var Ye = class t {
+var Je = class t {
 	id;
 	name;
 	storage;
@@ -1305,7 +1316,7 @@ var Ye = class t {
 	}
 	addItem(e, t = 0, n = 0, r = 4, i = null, a = null, o) {
 		let s = this.nextId.toString(), c = 10, l = r;
-		e === O.MARKDOWN ? c = 3 : e === O.SECTION_HEADER || e === O.APPENDIX_HEADER ? c = 1 : e === O.MEMO ? (c = 8, l = 20) : e === O.CLAIM ? (c = 4, l = 20) : e === O.FREEFORM && (c = 10);
+		e === k.MARKDOWN ? c = 3 : e === k.SECTION_HEADER || e === k.APPENDIX_HEADER ? c = 1 : e === k.MEMO ? (c = 8, l = 20) : e === k.CLAIM ? (c = 4, l = 20) : e === k.FREEFORM && (c = 10);
 		let u = n;
 		u = this.layout.reduce((e, t) => Math.max(e, t.y + t.h), 0), this.layout.push({
 			x: t,
@@ -1316,16 +1327,16 @@ var Ye = class t {
 			static: !1
 		});
 		let d = `Note ${s}`;
-		e === O.CHART ? d = `Chart ${s}` : e === O.TABLE ? d = `Table ${s}` : e === O.SECTION_HEADER ? d = "### Section Header" : e === O.MEMO ? d = "Executive Memo" : e === O.CLAIM ? d = `Claim ${s}` : e === O.APPENDIX_HEADER ? d = "### Appendix" : e === O.FREEFORM && (d = `Widget ${s}`);
+		e === k.CHART ? d = `Chart ${s}` : e === k.TABLE ? d = `Table ${s}` : e === k.SECTION_HEADER ? d = "### Section Header" : e === k.MEMO ? d = "Executive Memo" : e === k.CLAIM ? d = `Claim ${s}` : e === k.APPENDIX_HEADER ? d = "### Appendix" : e === k.FREEFORM && (d = `Widget ${s}`);
 		let f = o || d, p = "# Markdown Cell\nEnter your markdown content here.";
-		e === O.CHART ? p = "SELECT unnest([1,2,3,4]) as value, 'example' as dim" : e === O.TABLE ? p = "SELECT [1,2,3,4] as value, 'example' as dim" : e === O.SECTION_HEADER || e === O.APPENDIX_HEADER ? p = "" : e === O.MEMO ? p = {
+		e === k.CHART ? p = "SELECT unnest([1,2,3,4]) as value, 'example' as dim" : e === k.TABLE ? p = "SELECT [1,2,3,4] as value, 'example' as dim" : e === k.SECTION_HEADER || e === k.APPENDIX_HEADER ? p = "" : e === k.MEMO ? p = {
 			headline: "",
 			verdict: "inconclusive",
 			magnitude: "",
 			cause: "",
 			action: "",
 			confidence: "medium"
-		} : e === O.CLAIM ? p = { claim: "" } : e === O.FREEFORM && (p = {
+		} : e === k.CLAIM ? p = { claim: "" } : e === k.FREEFORM && (p = {
 			html: ee,
 			query: "SELECT unnest(['alpha','beta','gamma']) as dim, random() * 100 as value"
 		});
@@ -1336,7 +1347,7 @@ var Ye = class t {
 			name: f,
 			width: 0,
 			height: 0,
-			allowCrossFilter: !(e === O.SECTION_HEADER || e === O.APPENDIX_HEADER || e === O.MEMO)
+			allowCrossFilter: !(e === k.SECTION_HEADER || e === k.APPENDIX_HEADER || e === k.MEMO)
 		}, this.nextId++, this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0, s;
 	}
 	setLayoutType(e) {
@@ -1427,22 +1438,22 @@ var Ye = class t {
 	}
 	updateItemFilters(e) {
 		let t = this.gridItems[e];
-		t && D(t) && (this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0);
+		t && O(t) && (this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0);
 	}
 	removeItemCrossFilter(e, t) {
-		ze(this.gridItems, e, t) && (this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0);
+		Re(this.gridItems, e, t) && (this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0);
 	}
 	removeItemCrossFilterSource(e) {
-		let t = !!this.gridItems[e]?.chartFilters?.length, n = Be(this.gridItems, e);
+		let t = !!this.gridItems[e]?.chartFilters?.length, n = ze(this.gridItems, e);
 		return (n.length > 0 || t) && (this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0), n;
 	}
 	removeAllFilters() {
-		let e = Ve(this.gridItems);
+		let e = Be(this.gridItems);
 		for (let e in this.gridItems) this.gridItems[e].parameters = {};
 		return e.length > 0 && (this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0), e;
 	}
 	updateItemCrossFilters(e, t, n, r) {
-		let i = Re(this.gridItems, e, t, n, r);
+		let i = Le(this.gridItems, e, t, n, r);
 		return this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0, i;
 	}
 	updateItemName(e, t) {
@@ -1547,7 +1558,7 @@ var Ye = class t {
 			children: n.children || []
 		});
 	}
-}, Xe = .5, Ze = 1e4, Qe = 2e5, $e = [
+}, Ye = .5, Xe = 1e4, Ze = 2e5, Qe = [
 	{
 		value: "demo",
 		label: "Demo (limited messages)"
@@ -1572,13 +1583,13 @@ var Ye = class t {
 		value: "deepseek",
 		label: "DeepSeek"
 	}
-], et = Object.fromEntries($e.map((e) => [e.value, e.label])), tt = {
+], $e = Object.fromEntries(Qe.map((e) => [e.value, e.label])), et = {
 	anthropic: "sk-ant-...",
 	openai: "sk-...",
 	google: "AIza...",
 	openrouter: "sk-or-...",
 	deepseek: "sk-..."
-}, k = "# Trilogy Syntax\n\nTrilogy statements define a semantic model or a query; collections of statements\nare written as `.preql` files. A statement returns data (SELECT) or defines\nconcepts (key | property | auto | metric), datasources, or parameters.\n\nimport <model> as <alias>; makes a model's fields available. <model> is a DOT-SEPARATED MODULE PATH relative to the project root (where trilogy.toml lives), never a file path: the file `raw/store_sales.preql` is imported as `import raw.store_sales as ss;` — replace each `/` with `.`, drop the `.preql`, keep the folder segment. When an imported model imports others (a fact with imported dimensions), those are dot paths: `enroll.student.name`. Typical usage imports ONE fact and reaches dimensions through it; nested dimensions carry ALL values (order.customers includes customers without orders).\n\nkey | property | auto | metric; define new concepts. `auto x <- ...` is a DEFINITION, not a precomputed value: each reference expands and re-evaluates in the consuming query's scope.\n\nparameter NAME TYPE [default <literal>]; — a runtime value supplied via `--param NAME=VALUE` (repeatable); append `?` to the type to allow null.\n\n## Combining models\n\n| Goal | Use |\n|---|---|\n| Typical query | no merge, no join: access all fields through dot-paths |\n| Blend two models on shared keys inside one query | scoped `subset\\|union join` |\n| Make a connection universal to a whole file | `merge` |\n| Stack subsets/channels as rows | `union(...)` |\n| Rows in A but never in B (set difference) | `except(...)` |\n| Rows present in every source (set intersection) | `intersect(...)` |\n\n### Query-scoped join\n\nA typical fact already has its dimensions merged in, so no join is needed. Blending fact models or rowset outputs takes a scoped join, placed right after the select list, which DECLARES how the key domains relate: `subset join a = b` (a's values are contained in b's, a ⊆ b; b authoritative for the key) or `union join a = b` (neither contains the other; the key is the coalesce of both sides and unmatched rows from BOTH sides are kept).\n\nTwo rules decide whether the numbers are right, so apply them before reaching for the example:\n\n- Joins NEVER drop a row and NULL keys match null-safely; there is NO inner join. An intersection is an explicit `where <optional-side attr> is not null`.\n- JOIN ON THE FULL GRAIN: `explore` prints each fact's grain as @<k1, k2>; write one clause PER key. Matching only one key of a multi-key grain causes duplication.\n\nChaining, expression keys, union/subset mixing, multi-key and self-pair shapes: trilogy agent-info syntax example scoped-join.\n\nmerge <a> into ~<b>; is the persistent (whole-file) equivalent of `subset join a = b`; plain `merge a into b;` declares EXACT domain equivalence. Standalone statements; prefer a scoped join unless the connection is universal.\n\n### union / except / intersect (row set operations)\n\n`union(...)` row-stacks self-contained select arms positionally (SQL UNION ALL) into one named rowset (`with combined as union((armA), (armB), ...) -> (out1, out2, ...)`); `except(...)` / `intersect(...)` share that arm shape but are SQL SET operators (DISTINCT rows, null-safe whole-row compare, and except subtracts later arms from the FIRST, so arm order matters). Prefer except over a multi-column `not in` for \"in A but never in B\". Each arm dedups to its own output grain BEFORE stacking, so aggregate INSIDE each arm or the total silently undersums. Examples: trilogy agent-info syntax example union-stack-channels / except-intersect-setops.\n\n## Query structure\n\nTop-level statements first (each `;`-terminated), then a query with clauses in this EXACT order — all optional except select:\n\n```\n<top-level statements>;            # import / key / auto / rowset / merge / def / parameter\nwith <name> as                     # optional: name the select as a reusable rowset (CTE)\nwhere   <row condition>            # 1. filters INPUT rows, BEFORE aggregation\nselect  <col>, <agg> as name,      # 2. projection — grouping is AUTOMATIC by the\n                                   #    non-aggregated columns; never write GROUP BY\n  subset|union join a = b (= c)?   # 3. blend models; one clause per key, right after the select list\nby rollup|cube|grouping sets (...) # 4. optional multi-level grouping for the whole select\nhaving  <result condition>         # 5. filters aggregated/joined RESULTS\norder by <col> asc|desc            # 6. sort\nlimit   <n>;                       # 7. cap rows\n```\n\nA rowset (`with <name> as where ... select ...;`) is a standalone statement, evaluated in isolation — it does NOT respond to the consuming query's context. All its outputs are namespaced: output `abc.def` of rowset `foo` is referenced as `foo.abc.def`, and joined back like any concept (`subset join foo.key = other.key`). Alias every reused expression with `as`.\n\nFull annotated example: trilogy agent-info syntax example query-structure.\n\n### Not SQL — what to never write\n\n- **No FROM, GROUP BY, DISTINCT, SELECT \\*, or SQL-style set operators between selects.** Stack rows with `union(...)`; set difference/intersection with `except(...)`/`intersect(...)`; blend fact models with a scoped join.\n- **Grouping is automatic** by the non-aggregated fields in the SELECT — never write GROUP BY. Aggregates inherit the select's grain wherever they appear (where/select/having). Override per-aggregate with `agg(x) by <dims>`; `by *` aggregates across all data (single row). To weight a related dimension property once per fact row, project it to the fact grain first: `auto row_birth_year <- group(enroll.student.birth_year) by enroll.student_id, enroll.course_id;` then aggregate that.\n- **Output rows are deduplicated to the select grain.** To preserve legitimate duplicates (one row per matching fact), include the fact's grain keys in the select — hidden with the PREFIX `--` if they shouldn't appear in the output.\n- **Never write `distinct`.** `count(<key>)` is already distinct because keys are unique; `count_distinct(<property>)` counts distinct values of a non-key property.\n- **Count a COMPOSITE grain with `grain(...)`.** `count(grain(order_id, item.id))` counts order+item combinations; `grain(...)` is NEVER NULL. Never count one column of a multi-key grain — a coarser key counts its own distinct values and undercounts. `count_distinct(a, b)` is accepted as sugar for `count(grain(a, b))` (distinct combinations, NULL members included).\n- **An aggregate over a group with no qualifying rows is NULL, never 0.** `sum(x ? cond) by k` yields NULL for groups where nothing matches, so `= 0` matches nothing. Test emptiness with `count(key ? cond) by k = 0` or wrap: `coalesce(sum(x ? cond), 0)`.\n- **`count(1)` is invalid** — a constant does not identify rows. Use the row key, `count(grain(...))`, or `sum(1) by <grain>`.\n- **One-column expression subqueries only.** `(select ...)` is allowed where a scalar or membership set is expected (exactly one projected column) — never as a SQL-style FROM-subquery. For related-entity filters prefer the dot-path: `where enrollments.student.state = 'TN'`, not a subselect.\n- **`--` is a HIDDEN-field prefix, not a comment** (it still changes query structure). Comments use `#` only.\n- **Aliases**: always use the full dot-path (`enroll.student.id`); alias every new expression with `as`; a select alias is usable in `having`/`order by` but NOT inside other select expressions or `where`, and must not rename a field back to an existing concept name.\n\n## Filtering\n\n`where` filters input rows before aggregation; `having` filters results after aggregation/windows. The inline filter `x ? cond` filters the immediate prior expression: `sum(credits ? enrolled = true)`.\n\nAggregates/windows in WHERE do not filter each other's inputs. Use inline filters, or a staged `then where` chain: each `then where` stage's aggregates compute over only the rows passing earlier stages (`where x = 5 then where sum(y) > 10` ≡ `where x = 5 and sum(y ? x = 5) > 10`). One rule: the SAME cross-row expression cannot gate two different stages — give one an inline filter.\n\nWindows need all rows in their range: filter AFTER the window (in `having`) rather than in `where` when the window must see the full set.\n\n## Membership (semijoins)\n\n`in` / `not in` cross models without any declared relationship — the semijoin IS a scoped intersection. The right side is a concept or expression (never a subselect); build computed sets with an inline filter: `auto big_zip <- student.zip ? (count(student.id ? student.honors = true) by student.zip) > 10; ... where school.zip in big_zip`.\n\nMembership is IDENTITY matching, not SQL three-valued logic: NULL matches NULL; the result is always TRUE or FALSE (safe as a projected flag); `not in` is the exact complement (a NULL in the set never empties the result). For strict SQL behavior, add `x is not null`.\n\nA fact model contains ALL dimensional members, so `where students.id not in enroll.student_id` is typically a tautology — use `where enroll.id is null` instead. Tuple membership `(a, b) in (m.a, m.b)` requires both right-side concepts to resolve to ONE source (model or rowset); to test against a cross-model pair, stage it through a rowset first. Examples: existence-anti-join, staged-membership.\n\n## Aggregation\n\nAn aggregate without an explicit `by` is RESPONSIVE — its grain is set where it is consumed, not where it is declared (`auto avg_credits <- avg(enroll.credits);` becomes per-department when selected with `enroll.department`). Pin a grain inline: `sum(metric) by dim1, dim2 as name`; `by` accepts bare identifiers or parenthesized expressions: `avg(price) by (substring(phone, 1, 2))`.\n\nMulti-level grouping (`by rollup|cube|grouping sets (...)`) is a clause of the WHOLE select, placed before `having`: it computes every no-explicit-grain aggregate at every level in one pass (`by rollup (d1, d2)` → leaf, per-d1 subtotal, grand total). `grouping(<field>)` = 1 on rolled-up rows — use it to label levels rather than testing for NULL. Full detail: trilogy agent-info syntax example rollup.\n\n## Window functions\n\nDefault to windows for self-referential queries (period-over-period, running totals, rank, share of group). SQL-style syntax: `rank(<key>) over (partition by <g> order by <expr> desc)` (`dense_rank`/`row_number` same shape; multi-key `rank(a, b)`); `sum(x) over (partition by g order by t)` for running totals; `lag(<field>, <offset>) over (...)` / `lead(...)` for offsets (default 1). `partition by` is optional and accepts expressions.\n\n## Data types\n\nScalars: `string`, `bytes`, `bool`, `int`, `bigint`, `float`, `double`, `number`, `numeric(p,s)` (alias `decimal`; use for exact money), `date`, `datetime`, `timestamp`, `geography`, `any`. Composites: `array<T>`, `map<K, V>`, `struct<name: T, ...>`, `enum<T>[v1, v2, ...]`. Cast with `::type` or `cast(x as type)`: `\"2020-01-01\"::date`.\n\n`?` after a type marks it nullable (`property user.middle_name string?;`). `~` prefixing a concept marks the reference as a PARTIAL subset of the concept's domain — on a select item (`~customer.id`) or in `merge a into ~b` (a ⊆ b); it tells the planner this side is not authoritative.\n\n## Expression gotchas\n\n- `x ? cond` binds to a primary — wrap arithmetic: `(a - b) ? cond`, NOT `a - b ? cond`.\n- `a || b` is NULL if either side is NULL; `concat(...)` skips NULL arguments; `concat_ws(sep, ...)` joins with sep, skipping NULLs.\n- Date parts are unquoted: `date_part(d, year)`, never `'year'`; prefer `year(d)`. `date_diff(start, end, unit)` = end − start (a shipping lag is `date_diff(sold_date, ship_date, day)`).\n- Zero-argument functions still take parentheses: `current_date()`.\n- Factor repeated calculations into a `def` macro (invoked `@name(...)`) or reusable `auto` concepts.\n\n\nFunctions (the `aggregate` family doubles as the Aggregate Functions list):\naggregate: count|count_distinct|sum|max|min|avg|stddev|variance|array_agg|bool_or|bool_and|any|grouping(<arg1>) ; grouping_id(<arg1>, <arg2>, ..., <argN>)\nstring: concat|concat_strict|concat_ws(<arg1>, <arg2>, ..., <argN>) ; split|strpos|contains|trim|regexp_contains|format_time|parse_time(<arg1>, <arg2>) ; len|lower|upper|ltrim|rtrim|hex(<arg1>) ; substring|replace|regexp_extract|regexp_replace(<arg1>, <arg2>, <arg3>)\ndate/time: date|datetime|timestamp|second|minute|hour|day|day_of_week|week|month|quarter|year|month_name|day_name|unix_to_timestamp(<arg1>) ; date_spine(<arg1>, <arg2>) ; current_date|current_datetime()\n  date_part(<arg1>, <arg2>) e.g. date_part('2020-01-01'::date, year)\n  date_truncate(<arg1>, <arg2>) e.g. date_trunc('2020-01-01'::date, month)\n  date_add(<arg1>, <arg2>, <arg3>) e.g. date_add('2020-01-01'::date, month, 1)\n  date_sub(<arg1>, <arg2>, <arg3>) e.g. date_sub('2020-01-01'::date, day, 1)\n  date_diff(<arg1>, <arg2>, <arg3>) e.g. date_diff('2020-01-01'::date, '2020-01-02'::date, day)\n  current_timestamp() e.g. now()\narray/map/struct: unnest|array_distinct|array_sum|map_keys|map_values(<arg1>) ; struct|array(<arg1>, <arg2>, ..., <argN>) ; array_sort|array_to_string(<arg1>, <arg2>) ; array_transform|array_filter|generate_array(<arg1>, <arg2>, <arg3>)\nmath: mod|round|log|power|hash(<arg1>, <arg2>) ; abs|sqrt|random|floor|ceil(<arg1>)\nconditional/cast: case|simple_case|coalesce|greatest|least(<arg1>, <arg2>, ..., <argN>) ; cast|nullif(<arg1>, <arg2>) ; isnull(<arg1>)\ngeo: geo_from_text|geo_x|geo_y|geo_centroid(<arg1>) ; geo_point|geo_distance(<arg1>, <arg2>) ; geo_transform(<arg1>, <arg2>, <arg3>)\nother: is_not_distinct(<arg1>, <arg2>)\n\nSome types carry trait metadata that adds meaning: 'latitude', 'longitude' and 'currency' are all 'float' with extra semantics.\n\nAdditional syntax examples:\nThese less-common patterns have complete, copy-pasteable examples. Do NOT guess\nthe syntax — print the full example on demand with\n`trilogy agent-info syntax example <name>`:\n- `python-datasource` - run a local Python script as a datasource: wrap a function in `trilogy.io.run`, which writes the Arrow IPC stream to stdout for you from a table, dataframe, or list of dicts; declare concepts, map script columns in `datasource (...)`, use `grain (...) file `path.py`;`, then reference locally declared concepts WITHOUT the datasource name as a prefix\n- `query-structure` - the exact clause order of a query, and how to define a rowset\n- `chart` - drawing a result rather than tabulating it: `chart layer <type> ( <role> <- <expr> as <name>, ... )` is a STATEMENT that wraps its own query - the bindings ARE the select; layers, roles, scales, reference lines and `from <select>`\n- `filtered-aggregate` - aggregating only the rows matching a condition, and counting rows correctly\n- `row-level-where-vs-having` - choosing between WHERE and HAVING for a threshold condition\n- `nested-aggregate-group-average` - the \"above 1.2x the group norm\" ask: inner `sum(x) by entity, group`, outer `avg(inner) by group`; use WHERE for the comparison when a separate output-only filter must not narrow the benchmark\n- `pivot-columns` - turn distinct values of a dimension into columns with a reusable `def` macro + filtered aggregate\n- `case-when` - `case when <cond> then <val> ... else <val> end` to relabel codes or bucket a measure into a derived value, then group by it\n- `window-period-over-period` - `lead`/`lag` over (order by ...) to compare a row to an offset period; build a scoped set with `<col> ? <cond>` and filter with `in`\n- `union-stack-channels` - stacking several sources/channels together as rows\n- `except-intersect-setops` - set difference or co-occurrence across sources\n- `scoped-join` - blending a second fact model or rowset into one query\n- `existence-anti-join` - keeping or excluding rows by whether a key matches another model\n- `set-intersect-difference` - count tuples present in / absent from other groups via per-group presence flags - the multi-column INTERSECT/EXCEPT idiom\n- `dedup-before-aggregate` - a `rowset <- select <cols>` collapses identical tuples to one row (SELECT-grain group by) before a downstream sum - the `distinct`/UNION substitute\n- `rollup` - subtotals and a grand total in one pass, and labeling the levels\n- `rank-over-rollup` - rank rollup subtotals/leaves with a SINGLE `rank(a,b) over (partition by level, parent ...)` - not separate ranks per level\n- `staged-membership` - filtering a fine-grain query by a set computed at a coarser grain\n- `correlated-exists-via-grouped-counts` - translate `EXISTS other` / `NOT EXISTS other matching` over the same model into two `count(...) by <grain>` compared in `where` (`> 1` = another exists, `= 1` = no other matches) - pin the correlation grain with `by`", nt = "# Trilogy Syntax\n\nTrilogy statements define a semantic model or a query; collections of statements\nare written as `.preql` files. A statement returns data (SELECT) or defines\nconcepts (key | property | auto | metric), datasources, or parameters.\n\nimport <model> as <alias>; makes a model's fields available. <model> is a DOT-SEPARATED MODULE PATH relative to the project root (where trilogy.toml lives), never a file path: the file `raw/store_sales.preql` is imported as `import raw.store_sales as ss;` — replace each `/` with `.`, drop the `.preql`, keep the folder segment. When an imported model imports others (a fact with imported dimensions), those are dot paths: `enroll.student.name`. Typical usage imports ONE fact and reaches dimensions through it; nested dimensions carry ALL values (order.customers includes customers without orders).\n\nkey | property | auto | metric; define new concepts. `auto x <- ...` is a DEFINITION, not a precomputed value: each reference expands and re-evaluates in the consuming query's scope.\n\nparameter NAME TYPE [default <literal>]; — a runtime value supplied via `--param NAME=VALUE` (repeatable); append `?` to the type to allow null.\n\n## Combining models\n\n| Goal | Use |\n|---|---|\n| Typical query | no merge, no join: access all fields through dot-paths |\n| Blend two models on shared keys inside one query | scoped `subset\\|union join` |\n| Make a connection universal to a whole file | `merge` |\n| Stack subsets/channels as rows | `union(...)` |\n| Rows in A but never in B (set difference) | `except(...)` |\n| Rows present in every source (set intersection) | `intersect(...)` |\n\n### Query-scoped join\n\nA typical fact already has its dimensions merged in, so no join is needed. Blending fact models or rowset outputs takes a scoped join, placed right after the select list, which DECLARES how the key domains relate: `subset join a = b` (a's values are contained in b's, a ⊆ b; b authoritative for the key) or `union join a = b` (neither contains the other; the key is the coalesce of both sides and unmatched rows from BOTH sides are kept).\n\nTwo rules decide whether the numbers are right, so apply them before reaching for the example:\n\n- Joins NEVER drop a row and NULL keys match null-safely; there is NO inner join. An intersection is an explicit `where <optional-side attr> is not null`.\n- JOIN ON THE FULL GRAIN: `explore` prints each fact's grain as @<k1, k2>; write one clause PER key. Matching only one key of a multi-key grain causes duplication.\n\nChaining, expression keys, union/subset mixing, multi-key and self-pair shapes: trilogy agent-info syntax example scoped-join.\n\nmerge <a> into ~<b>; is the persistent (whole-file) equivalent of `subset join a = b`; plain `merge a into b;` declares EXACT domain equivalence. Standalone statements; prefer a scoped join unless the connection is universal.\n\n### union / except / intersect (row set operations)\n\n`union(...)` row-stacks self-contained select arms positionally (SQL UNION ALL) into one named rowset (`with combined as union((armA), (armB), ...) -> (out1, out2, ...)`); `except(...)` / `intersect(...)` share that arm shape but are SQL SET operators (DISTINCT rows, null-safe whole-row compare, and except subtracts later arms from the FIRST, so arm order matters). Prefer except over a multi-column `not in` for \"in A but never in B\". Each arm dedups to its own output grain BEFORE stacking, so aggregate INSIDE each arm or the total silently undersums. Examples: trilogy agent-info syntax example union-stack-channels / except-intersect-setops.\n\n## Query structure\n\nTop-level statements first (each `;`-terminated), then a query with clauses in this EXACT order — all optional except select:\n\n```\n<top-level statements>;            # import / key / auto / rowset / merge / def / parameter\nwith <name> as                     # optional: name the select as a reusable rowset (CTE)\nwhere   <row condition>            # 1. filters INPUT rows, BEFORE aggregation\nselect  <col>, <agg> as name,      # 2. projection — grouping is AUTOMATIC by the\n                                   #    non-aggregated columns; never write GROUP BY\n  subset|union join a = b (= c)?   # 3. blend models; one clause per key, right after the select list\nby rollup|cube|grouping sets (...) # 4. optional multi-level grouping for the whole select\nhaving  <result condition>         # 5. filters aggregated/joined RESULTS\norder by <col> asc|desc            # 6. sort\nlimit   <n>;                       # 7. cap rows\n```\n\nA rowset (`with <name> as where ... select ...;`) is a standalone statement, evaluated in isolation — it does NOT respond to the consuming query's context. All its outputs are namespaced: output `abc.def` of rowset `foo` is referenced as `foo.abc.def`, and joined back like any concept (`subset join foo.key = other.key`). Alias every reused expression with `as`.\n\nFull annotated example: trilogy agent-info syntax example query-structure.\n\n### Not SQL — what to never write\n\n- **No FROM, GROUP BY, DISTINCT, SELECT \\*, or SQL-style set operators between selects.** Stack rows with `union(...)`; set difference/intersection with `except(...)`/`intersect(...)`; blend fact models with a scoped join.\n- **Grouping is automatic** by the non-aggregated fields in the SELECT — never write GROUP BY. Aggregates inherit the select's grain wherever they appear (where/select/having). Override per-aggregate with `agg(x) by <dims>`; `by *` aggregates across all data (single row). To weight a related dimension property once per fact row, project it to the fact grain first: `auto row_birth_year <- group(enroll.student.birth_year) by enroll.student_id, enroll.course_id;` then aggregate that.\n- **Output rows are deduplicated to the select grain.** To preserve legitimate duplicates (one row per matching fact), include the fact's grain keys in the select — hidden with the PREFIX `--` if they shouldn't appear in the output.\n- **Never write `distinct`.** `count(<key>)` is already distinct because keys are unique; `count_distinct(<property>)` counts distinct values of a non-key property.\n- **Count a COMPOSITE grain with `grain(...)`.** `count(grain(order_id, item.id))` counts order+item combinations; `grain(...)` is NEVER NULL. Never count one column of a multi-key grain — a coarser key counts its own distinct values and undercounts. `count_distinct(a, b)` is accepted as sugar for `count(grain(a, b))` (distinct combinations, NULL members included).\n- **An aggregate over a group with no qualifying rows is NULL, never 0.** `sum(x ? cond) by k` yields NULL for groups where nothing matches, so `= 0` matches nothing. Test emptiness with `count(key ? cond) by k = 0` or wrap: `coalesce(sum(x ? cond), 0)`.\n- **`count(1)` is invalid** — a constant does not identify rows. Use the row key, `count(grain(...))`, or `sum(1) by <grain>`.\n- **One-column expression subqueries only.** `(select ...)` is allowed where a scalar or membership set is expected (exactly one projected column) — never as a SQL-style FROM-subquery. For related-entity filters prefer the dot-path: `where enrollments.student.state = 'TN'`, not a subselect.\n- **`--` is a HIDDEN-field prefix, not a comment** (it still changes query structure). Comments use `#` only.\n- **Aliases**: always use the full dot-path (`enroll.student.id`); alias every new expression with `as`; a select alias is usable in `having`/`order by` but NOT inside other select expressions or `where`, and must not rename a field back to an existing concept name.\n\n## Filtering\n\n`where` filters input rows before aggregation; `having` filters results after aggregation/windows. The inline filter `x ? cond` filters the immediate prior expression: `sum(credits ? enrolled = true)`.\n\nAggregates/windows in WHERE do not filter each other's inputs. Use inline filters, or a staged `then where` chain: each `then where` stage's aggregates compute over only the rows passing earlier stages (`where x = 5 then where sum(y) > 10` ≡ `where x = 5 and sum(y ? x = 5) > 10`). One rule: the SAME cross-row expression cannot gate two different stages — give one an inline filter.\n\nWindows need all rows in their range: filter AFTER the window (in `having`) rather than in `where` when the window must see the full set.\n\n## Membership (semijoins)\n\n`in` / `not in` cross models without any declared relationship — the semijoin IS a scoped intersection. The right side is a concept or expression (never a subselect); build computed sets with an inline filter: `auto big_zip <- student.zip ? (count(student.id ? student.honors = true) by student.zip) > 10; ... where school.zip in big_zip`.\n\nMembership is IDENTITY matching, not SQL three-valued logic: NULL matches NULL; the result is always TRUE or FALSE (safe as a projected flag); `not in` is the exact complement (a NULL in the set never empties the result). For strict SQL behavior, add `x is not null`.\n\nA fact model contains ALL dimensional members, so `where students.id not in enroll.student_id` is typically a tautology — use `where enroll.id is null` instead. Tuple membership `(a, b) in (m.a, m.b)` requires both right-side concepts to resolve to ONE source (model or rowset); to test against a cross-model pair, stage it through a rowset first. Examples: existence-anti-join, staged-membership.\n\n## Aggregation\n\nAn aggregate without an explicit `by` is RESPONSIVE — its grain is set where it is consumed, not where it is declared (`auto avg_credits <- avg(enroll.credits);` becomes per-department when selected with `enroll.department`). Pin a grain inline: `sum(metric) by dim1, dim2 as name`; `by` accepts bare identifiers or parenthesized expressions: `avg(price) by (substring(phone, 1, 2))`.\n\nMulti-level grouping (`by rollup|cube|grouping sets (...)`) is a clause of the WHOLE select, placed before `having`: it computes every no-explicit-grain aggregate at every level in one pass (`by rollup (d1, d2)` → leaf, per-d1 subtotal, grand total). `grouping(<field>)` = 1 on rolled-up rows — use it to label levels rather than testing for NULL. Full detail: trilogy agent-info syntax example rollup.\n\n## Window functions\n\nDefault to windows for self-referential queries (period-over-period, running totals, rank, share of group). SQL-style syntax: `rank(<key>) over (partition by <g> order by <expr> desc)` (`dense_rank`/`row_number` same shape; multi-key `rank(a, b)`); `sum(x) over (partition by g order by t)` for running totals; `lag(<field>, <offset>) over (...)` / `lead(...)` for offsets (default 1). `partition by` is optional and accepts expressions.\n\n## Data types\n\nScalars: `string`, `bytes`, `bool`, `int`, `bigint`, `float`, `double`, `number`, `numeric(p,s)` (alias `decimal`; use for exact money), `date`, `datetime`, `timestamp`, `geography`, `any`. Composites: `array<T>`, `map<K, V>`, `struct<name: T, ...>`, `enum<T>[v1, v2, ...]`. Cast with `::type` or `cast(x as type)`: `\"2020-01-01\"::date`.\n\n`?` after a type marks it nullable (`property user.middle_name string?;`). `~` prefixing a concept marks the reference as a PARTIAL subset of the concept's domain — on a select item (`~customer.id`) or in `merge a into ~b` (a ⊆ b); it tells the planner this side is not authoritative.\n\n## Expression gotchas\n\n- `x ? cond` binds to a primary — wrap arithmetic: `(a - b) ? cond`, NOT `a - b ? cond`.\n- `a || b` is NULL if either side is NULL; `concat(...)` skips NULL arguments; `concat_ws(sep, ...)` joins with sep, skipping NULLs.\n- Date parts are unquoted: `date_part(d, year)`, never `'year'`; prefer `year(d)`. `date_diff(start, end, unit)` = end − start (a shipping lag is `date_diff(sold_date, ship_date, day)`).\n- Zero-argument functions still take parentheses: `current_date()`.\n- Factor repeated calculations into a `def` macro (invoked `@name(...)`) or reusable `auto` concepts.", rt = ["aggregate: count|count_distinct|sum|max|min|avg|stddev|variance|array_agg|bool_or|bool_and|any|grouping(<arg1>) ; grouping_id(<arg1>, <arg2>, ..., <argN>)"], it = [
+}, A = "# Trilogy Syntax\n\nTrilogy statements define a semantic model or a query; collections of statements\nare written as `.preql` files. A statement returns data (SELECT) or defines\nconcepts (key | property | auto | metric), datasources, or parameters.\n\nimport <model> as <alias>; makes a model's fields available. <model> is a DOT-SEPARATED MODULE PATH relative to the project root (where trilogy.toml lives), never a file path: the file `raw/store_sales.preql` is imported as `import raw.store_sales as ss;` — replace each `/` with `.`, drop the `.preql`, keep the folder segment. When an imported model imports others (a fact with imported dimensions), those are dot paths: `enroll.student.name`. Typical usage imports ONE fact and reaches dimensions through it; nested dimensions carry ALL values (order.customers includes customers without orders).\n\nkey | property | auto | metric; define new concepts. `auto x <- ...` is a DEFINITION, not a precomputed value: each reference expands and re-evaluates in the consuming query's scope.\n\nparameter NAME TYPE [default <literal>]; — a runtime value supplied via `--param NAME=VALUE` (repeatable); append `?` to the type to allow null.\n\n## Combining models\n\n| Goal | Use |\n|---|---|\n| Typical query | no merge, no join: access all fields through dot-paths |\n| Blend two models on shared keys inside one query | scoped `subset\\|union join` |\n| Make a connection universal to a whole file | `merge` |\n| Stack subsets/channels as rows | `union(...)` |\n| Rows in A but never in B (set difference) | `except(...)` |\n| Rows present in every source (set intersection) | `intersect(...)` |\n\n### Query-scoped join\n\nA typical fact already has its dimensions merged in, so no join is needed. Blending fact models or rowset outputs takes a scoped join, placed right after the select list, which DECLARES how the key domains relate: `subset join a = b` (a's values are contained in b's, a ⊆ b; b authoritative for the key) or `union join a = b` (neither contains the other; the key is the coalesce of both sides and unmatched rows from BOTH sides are kept).\n\nTwo rules decide whether the numbers are right, so apply them before reaching for the example:\n\n- Joins NEVER drop a row and NULL keys match null-safely; there is NO inner join. An intersection is an explicit `where <optional-side attr> is not null`.\n- JOIN ON THE FULL GRAIN: `explore` prints each fact's grain as @<k1, k2>; write one clause PER key. Matching only one key of a multi-key grain causes duplication.\n\nChaining, expression keys, union/subset mixing, multi-key and self-pair shapes: trilogy agent-info syntax example scoped-join.\n\nmerge <a> into ~<b>; is the persistent (whole-file) equivalent of `subset join a = b`; plain `merge a into b;` declares EXACT domain equivalence. Standalone statements; prefer a scoped join unless the connection is universal.\n\n### union / except / intersect (row set operations)\n\n`union(...)` row-stacks self-contained select arms positionally (SQL UNION ALL) into one named rowset (`with combined as union((armA), (armB), ...) -> (out1, out2, ...)`); `except(...)` / `intersect(...)` share that arm shape but are SQL SET operators (DISTINCT rows, null-safe whole-row compare, and except subtracts later arms from the FIRST, so arm order matters). Prefer except over a multi-column `not in` for \"in A but never in B\". Each arm dedups to its own output grain BEFORE stacking, so aggregate INSIDE each arm or the total silently undersums. Examples: trilogy agent-info syntax example union-stack-channels / except-intersect-setops.\n\n## Query structure\n\nTop-level statements first (each `;`-terminated), then a query with clauses in this EXACT order — all optional except select:\n\n```\n<top-level statements>;            # import / key / auto / rowset / merge / def / parameter\nwith <name> as                     # optional: name the select as a reusable rowset (CTE)\nwhere   <row condition>            # 1. filters INPUT rows, BEFORE aggregation\nselect  <col>, <agg> as name,      # 2. projection — grouping is AUTOMATIC by the\n                                   #    non-aggregated columns; never write GROUP BY\n  subset|union join a = b (= c)?   # 3. blend models; one clause per key, right after the select list\nby rollup|cube|grouping sets (...) # 4. optional multi-level grouping for the whole select\nhaving  <result condition>         # 5. filters aggregated/joined RESULTS\norder by <col> asc|desc            # 6. sort\nlimit   <n>;                       # 7. cap rows\n```\n\nA rowset (`with <name> as where ... select ...;`) is a standalone statement, evaluated in isolation — it does NOT respond to the consuming query's context. All its outputs are namespaced: output `abc.def` of rowset `foo` is referenced as `foo.abc.def`, and joined back like any concept (`subset join foo.key = other.key`). Alias every reused expression with `as`.\n\nFull annotated example: trilogy agent-info syntax example query-structure.\n\n### Not SQL — what to never write\n\n- **No FROM, GROUP BY, DISTINCT, SELECT \\*, or SQL-style set operators between selects.** Stack rows with `union(...)`; set difference/intersection with `except(...)`/`intersect(...)`; blend fact models with a scoped join.\n- **Grouping is automatic** by the non-aggregated fields in the SELECT — never write GROUP BY. Aggregates inherit the select's grain wherever they appear (where/select/having). Override per-aggregate with `agg(x) by <dims>`; `by *` aggregates across all data (single row). To weight a related dimension property once per fact row, project it to the fact grain first: `auto row_birth_year <- group(enroll.student.birth_year) by enroll.student_id, enroll.course_id;` then aggregate that.\n- **Output rows are deduplicated to the select grain.** To preserve legitimate duplicates (one row per matching fact), include the fact's grain keys in the select — hidden with the PREFIX `--` if they shouldn't appear in the output.\n- **Never write `distinct`.** `count(<key>)` is already distinct because keys are unique; `count_distinct(<property>)` counts distinct values of a non-key property.\n- **Count a COMPOSITE grain with `grain(...)`.** `count(grain(order_id, item.id))` counts order+item combinations; `grain(...)` is NEVER NULL. Never count one column of a multi-key grain — a coarser key counts its own distinct values and undercounts. `count_distinct(a, b)` is accepted as sugar for `count(grain(a, b))` (distinct combinations, NULL members included).\n- **An aggregate over a group with no qualifying rows is NULL, never 0.** `sum(x ? cond) by k` yields NULL for groups where nothing matches, so `= 0` matches nothing. Test emptiness with `count(key ? cond) by k = 0` or wrap: `coalesce(sum(x ? cond), 0)`.\n- **`count(1)` is invalid** — a constant does not identify rows. Use the row key, `count(grain(...))`, or `sum(1) by <grain>`.\n- **One-column expression subqueries only.** `(select ...)` is allowed where a scalar or membership set is expected (exactly one projected column) — never as a SQL-style FROM-subquery. For related-entity filters prefer the dot-path: `where enrollments.student.state = 'TN'`, not a subselect.\n- **`--` is a HIDDEN-field prefix, not a comment** (it still changes query structure). Comments use `#` only.\n- **Aliases**: always use the full dot-path (`enroll.student.id`); alias every new expression with `as`; a select alias is usable in `having`/`order by` but NOT inside other select expressions or `where`, and must not rename a field back to an existing concept name.\n\n## Filtering\n\n`where` filters input rows before aggregation; `having` filters results after aggregation/windows. The inline filter `x ? cond` filters the immediate prior expression: `sum(credits ? enrolled = true)`.\n\nAggregates/windows in WHERE do not filter each other's inputs. Use inline filters, or a staged `then where` chain: each `then where` stage's aggregates compute over only the rows passing earlier stages (`where x = 5 then where sum(y) > 10` ≡ `where x = 5 and sum(y ? x = 5) > 10`). One rule: the SAME cross-row expression cannot gate two different stages — give one an inline filter.\n\nWindows need all rows in their range: filter AFTER the window (in `having`) rather than in `where` when the window must see the full set.\n\n## Membership (semijoins)\n\n`in` / `not in` cross models without any declared relationship — the semijoin IS a scoped intersection. The right side is a concept or expression (never a subselect); build computed sets with an inline filter: `auto big_zip <- student.zip ? (count(student.id ? student.honors = true) by student.zip) > 10; ... where school.zip in big_zip`.\n\nMembership is IDENTITY matching, not SQL three-valued logic: NULL matches NULL; the result is always TRUE or FALSE (safe as a projected flag); `not in` is the exact complement (a NULL in the set never empties the result). For strict SQL behavior, add `x is not null`.\n\nA fact model contains ALL dimensional members, so `where students.id not in enroll.student_id` is typically a tautology — use `where enroll.id is null` instead. Tuple membership `(a, b) in (m.a, m.b)` requires both right-side concepts to resolve to ONE source (model or rowset); to test against a cross-model pair, stage it through a rowset first. Examples: existence-anti-join, staged-membership.\n\n## Aggregation\n\nAn aggregate without an explicit `by` is RESPONSIVE — its grain is set where it is consumed, not where it is declared (`auto avg_credits <- avg(enroll.credits);` becomes per-department when selected with `enroll.department`). Pin a grain inline: `sum(metric) by dim1, dim2 as name`; `by` accepts bare identifiers or parenthesized expressions: `avg(price) by (substring(phone, 1, 2))`.\n\nMulti-level grouping (`by rollup|cube|grouping sets (...)`) is a clause of the WHOLE select, placed before `having`: it computes every no-explicit-grain aggregate at every level in one pass (`by rollup (d1, d2)` → leaf, per-d1 subtotal, grand total). `grouping(<field>)` = 1 on rolled-up rows — use it to label levels rather than testing for NULL. Full detail: trilogy agent-info syntax example rollup.\n\n## Window functions\n\nDefault to windows for self-referential queries (period-over-period, running totals, rank, share of group). SQL-style syntax: `rank(<key>) over (partition by <g> order by <expr> desc)` (`dense_rank`/`row_number` same shape; multi-key `rank(a, b)`); `sum(x) over (partition by g order by t)` for running totals; `lag(<field>, <offset>) over (...)` / `lead(...)` for offsets (default 1). `partition by` is optional and accepts expressions.\n\n## Data types\n\nScalars: `string`, `bytes`, `bool`, `int`, `bigint`, `float`, `double`, `number`, `numeric(p,s)` (alias `decimal`; use for exact money), `date`, `datetime`, `timestamp`, `geography`, `any`. Composites: `array<T>`, `map<K, V>`, `struct<name: T, ...>`, `enum<T>[v1, v2, ...]`. Cast with `::type` or `cast(x as type)`: `\"2020-01-01\"::date`.\n\n`?` after a type marks it nullable (`property user.middle_name string?;`). `~` prefixing a concept marks the reference as a PARTIAL subset of the concept's domain — on a select item (`~customer.id`) or in `merge a into ~b` (a ⊆ b); it tells the planner this side is not authoritative.\n\n## Expression gotchas\n\n- `x ? cond` binds to a primary — wrap arithmetic: `(a - b) ? cond`, NOT `a - b ? cond`.\n- `a || b` is NULL if either side is NULL; `concat(...)` skips NULL arguments; `concat_ws(sep, ...)` joins with sep, skipping NULLs.\n- Date parts are unquoted: `date_part(d, year)`, never `'year'`; prefer `year(d)`. `date_diff(start, end, unit)` = end − start (a shipping lag is `date_diff(sold_date, ship_date, day)`).\n- Zero-argument functions still take parentheses: `current_date()`.\n- Factor repeated calculations into a `def` macro (invoked `@name(...)`) or reusable `auto` concepts.\n\n\nFunctions (the `aggregate` family doubles as the Aggregate Functions list):\naggregate: count|count_distinct|sum|max|min|avg|stddev|variance|array_agg|bool_or|bool_and|any|grouping(<arg1>) ; grouping_id(<arg1>, <arg2>, ..., <argN>)\nstring: concat|concat_strict|concat_ws(<arg1>, <arg2>, ..., <argN>) ; split|strpos|contains|trim|regexp_contains|format_time|parse_time(<arg1>, <arg2>) ; len|lower|upper|ltrim|rtrim|hex(<arg1>) ; substring|replace|regexp_extract|regexp_replace(<arg1>, <arg2>, <arg3>)\ndate/time: date|datetime|timestamp|second|minute|hour|day|day_of_week|week|month|quarter|year|month_name|day_name|unix_to_timestamp(<arg1>) ; date_spine(<arg1>, <arg2>) ; current_date|current_datetime()\n  date_part(<arg1>, <arg2>) e.g. date_part('2020-01-01'::date, year)\n  date_truncate(<arg1>, <arg2>) e.g. date_trunc('2020-01-01'::date, month)\n  date_add(<arg1>, <arg2>, <arg3>) e.g. date_add('2020-01-01'::date, month, 1)\n  date_sub(<arg1>, <arg2>, <arg3>) e.g. date_sub('2020-01-01'::date, day, 1)\n  date_diff(<arg1>, <arg2>, <arg3>) e.g. date_diff('2020-01-01'::date, '2020-01-02'::date, day)\n  current_timestamp() e.g. now()\narray/map/struct: unnest|array_distinct|array_sum|map_keys|map_values(<arg1>) ; struct|array(<arg1>, <arg2>, ..., <argN>) ; array_sort|array_to_string(<arg1>, <arg2>) ; array_transform|array_filter|generate_array(<arg1>, <arg2>, <arg3>)\nmath: mod|round|log|power|hash(<arg1>, <arg2>) ; abs|sqrt|random|floor|ceil(<arg1>)\nconditional/cast: case|simple_case|coalesce|greatest|least(<arg1>, <arg2>, ..., <argN>) ; cast|nullif(<arg1>, <arg2>) ; isnull(<arg1>)\ngeo: geo_from_text|geo_x|geo_y|geo_centroid(<arg1>) ; geo_point|geo_distance(<arg1>, <arg2>) ; geo_transform(<arg1>, <arg2>, <arg3>)\nother: is_not_distinct(<arg1>, <arg2>)\n\nSome types carry trait metadata that adds meaning: 'latitude', 'longitude' and 'currency' are all 'float' with extra semantics.\n\nAdditional syntax examples:\nThese less-common patterns have complete, copy-pasteable examples. Do NOT guess\nthe syntax — print the full example on demand with\n`trilogy agent-info syntax example <name>`:\n- `python-datasource` - run a local Python script as a datasource: wrap a function in `trilogy.io.run`, which writes the Arrow IPC stream to stdout for you from a table, dataframe, or list of dicts; declare concepts, map script columns in `datasource (...)`, use `grain (...) file `path.py`;`, then reference locally declared concepts WITHOUT the datasource name as a prefix\n- `query-structure` - the exact clause order of a query, and how to define a rowset\n- `chart` - drawing a result rather than tabulating it: `chart layer <type> ( <role> <- <expr> as <name>, ... )` is a STATEMENT that wraps its own query - the bindings ARE the select; layers, roles, scales, reference lines and `from <select>`\n- `filtered-aggregate` - aggregating only the rows matching a condition, and counting rows correctly\n- `row-level-where-vs-having` - choosing between WHERE and HAVING for a threshold condition\n- `nested-aggregate-group-average` - the \"above 1.2x the group norm\" ask: inner `sum(x) by entity, group`, outer `avg(inner) by group`; use WHERE for the comparison when a separate output-only filter must not narrow the benchmark\n- `pivot-columns` - turn distinct values of a dimension into columns with a reusable `def` macro + filtered aggregate\n- `case-when` - `case when <cond> then <val> ... else <val> end` to relabel codes or bucket a measure into a derived value, then group by it\n- `window-period-over-period` - `lead`/`lag` over (order by ...) to compare a row to an offset period; build a scoped set with `<col> ? <cond>` and filter with `in`\n- `union-stack-channels` - stacking several sources/channels together as rows\n- `except-intersect-setops` - set difference or co-occurrence across sources\n- `scoped-join` - blending a second fact model or rowset into one query\n- `existence-anti-join` - keeping or excluding rows by whether a key matches another model\n- `set-intersect-difference` - count tuples present in / absent from other groups via per-group presence flags - the multi-column INTERSECT/EXCEPT idiom\n- `dedup-before-aggregate` - a `rowset <- select <cols>` collapses identical tuples to one row (SELECT-grain group by) before a downstream sum - the `distinct`/UNION substitute\n- `rollup` - subtotals and a grand total in one pass, and labeling the levels\n- `rank-over-rollup` - rank rollup subtotals/leaves with a SINGLE `rank(a,b) over (partition by level, parent ...)` - not separate ranks per level\n- `staged-membership` - filtering a fine-grain query by a set computed at a coarser grain\n- `correlated-exists-via-grouped-counts` - translate `EXISTS other` / `NOT EXISTS other matching` over the same model into two `count(...) by <grain>` compared in `where` (`> 1` = another exists, `= 1` = no other matches) - pin the correlation grain with `by`", tt = "# Trilogy Syntax\n\nTrilogy statements define a semantic model or a query; collections of statements\nare written as `.preql` files. A statement returns data (SELECT) or defines\nconcepts (key | property | auto | metric), datasources, or parameters.\n\nimport <model> as <alias>; makes a model's fields available. <model> is a DOT-SEPARATED MODULE PATH relative to the project root (where trilogy.toml lives), never a file path: the file `raw/store_sales.preql` is imported as `import raw.store_sales as ss;` — replace each `/` with `.`, drop the `.preql`, keep the folder segment. When an imported model imports others (a fact with imported dimensions), those are dot paths: `enroll.student.name`. Typical usage imports ONE fact and reaches dimensions through it; nested dimensions carry ALL values (order.customers includes customers without orders).\n\nkey | property | auto | metric; define new concepts. `auto x <- ...` is a DEFINITION, not a precomputed value: each reference expands and re-evaluates in the consuming query's scope.\n\nparameter NAME TYPE [default <literal>]; — a runtime value supplied via `--param NAME=VALUE` (repeatable); append `?` to the type to allow null.\n\n## Combining models\n\n| Goal | Use |\n|---|---|\n| Typical query | no merge, no join: access all fields through dot-paths |\n| Blend two models on shared keys inside one query | scoped `subset\\|union join` |\n| Make a connection universal to a whole file | `merge` |\n| Stack subsets/channels as rows | `union(...)` |\n| Rows in A but never in B (set difference) | `except(...)` |\n| Rows present in every source (set intersection) | `intersect(...)` |\n\n### Query-scoped join\n\nA typical fact already has its dimensions merged in, so no join is needed. Blending fact models or rowset outputs takes a scoped join, placed right after the select list, which DECLARES how the key domains relate: `subset join a = b` (a's values are contained in b's, a ⊆ b; b authoritative for the key) or `union join a = b` (neither contains the other; the key is the coalesce of both sides and unmatched rows from BOTH sides are kept).\n\nTwo rules decide whether the numbers are right, so apply them before reaching for the example:\n\n- Joins NEVER drop a row and NULL keys match null-safely; there is NO inner join. An intersection is an explicit `where <optional-side attr> is not null`.\n- JOIN ON THE FULL GRAIN: `explore` prints each fact's grain as @<k1, k2>; write one clause PER key. Matching only one key of a multi-key grain causes duplication.\n\nChaining, expression keys, union/subset mixing, multi-key and self-pair shapes: trilogy agent-info syntax example scoped-join.\n\nmerge <a> into ~<b>; is the persistent (whole-file) equivalent of `subset join a = b`; plain `merge a into b;` declares EXACT domain equivalence. Standalone statements; prefer a scoped join unless the connection is universal.\n\n### union / except / intersect (row set operations)\n\n`union(...)` row-stacks self-contained select arms positionally (SQL UNION ALL) into one named rowset (`with combined as union((armA), (armB), ...) -> (out1, out2, ...)`); `except(...)` / `intersect(...)` share that arm shape but are SQL SET operators (DISTINCT rows, null-safe whole-row compare, and except subtracts later arms from the FIRST, so arm order matters). Prefer except over a multi-column `not in` for \"in A but never in B\". Each arm dedups to its own output grain BEFORE stacking, so aggregate INSIDE each arm or the total silently undersums. Examples: trilogy agent-info syntax example union-stack-channels / except-intersect-setops.\n\n## Query structure\n\nTop-level statements first (each `;`-terminated), then a query with clauses in this EXACT order — all optional except select:\n\n```\n<top-level statements>;            # import / key / auto / rowset / merge / def / parameter\nwith <name> as                     # optional: name the select as a reusable rowset (CTE)\nwhere   <row condition>            # 1. filters INPUT rows, BEFORE aggregation\nselect  <col>, <agg> as name,      # 2. projection — grouping is AUTOMATIC by the\n                                   #    non-aggregated columns; never write GROUP BY\n  subset|union join a = b (= c)?   # 3. blend models; one clause per key, right after the select list\nby rollup|cube|grouping sets (...) # 4. optional multi-level grouping for the whole select\nhaving  <result condition>         # 5. filters aggregated/joined RESULTS\norder by <col> asc|desc            # 6. sort\nlimit   <n>;                       # 7. cap rows\n```\n\nA rowset (`with <name> as where ... select ...;`) is a standalone statement, evaluated in isolation — it does NOT respond to the consuming query's context. All its outputs are namespaced: output `abc.def` of rowset `foo` is referenced as `foo.abc.def`, and joined back like any concept (`subset join foo.key = other.key`). Alias every reused expression with `as`.\n\nFull annotated example: trilogy agent-info syntax example query-structure.\n\n### Not SQL — what to never write\n\n- **No FROM, GROUP BY, DISTINCT, SELECT \\*, or SQL-style set operators between selects.** Stack rows with `union(...)`; set difference/intersection with `except(...)`/`intersect(...)`; blend fact models with a scoped join.\n- **Grouping is automatic** by the non-aggregated fields in the SELECT — never write GROUP BY. Aggregates inherit the select's grain wherever they appear (where/select/having). Override per-aggregate with `agg(x) by <dims>`; `by *` aggregates across all data (single row). To weight a related dimension property once per fact row, project it to the fact grain first: `auto row_birth_year <- group(enroll.student.birth_year) by enroll.student_id, enroll.course_id;` then aggregate that.\n- **Output rows are deduplicated to the select grain.** To preserve legitimate duplicates (one row per matching fact), include the fact's grain keys in the select — hidden with the PREFIX `--` if they shouldn't appear in the output.\n- **Never write `distinct`.** `count(<key>)` is already distinct because keys are unique; `count_distinct(<property>)` counts distinct values of a non-key property.\n- **Count a COMPOSITE grain with `grain(...)`.** `count(grain(order_id, item.id))` counts order+item combinations; `grain(...)` is NEVER NULL. Never count one column of a multi-key grain — a coarser key counts its own distinct values and undercounts. `count_distinct(a, b)` is accepted as sugar for `count(grain(a, b))` (distinct combinations, NULL members included).\n- **An aggregate over a group with no qualifying rows is NULL, never 0.** `sum(x ? cond) by k` yields NULL for groups where nothing matches, so `= 0` matches nothing. Test emptiness with `count(key ? cond) by k = 0` or wrap: `coalesce(sum(x ? cond), 0)`.\n- **`count(1)` is invalid** — a constant does not identify rows. Use the row key, `count(grain(...))`, or `sum(1) by <grain>`.\n- **One-column expression subqueries only.** `(select ...)` is allowed where a scalar or membership set is expected (exactly one projected column) — never as a SQL-style FROM-subquery. For related-entity filters prefer the dot-path: `where enrollments.student.state = 'TN'`, not a subselect.\n- **`--` is a HIDDEN-field prefix, not a comment** (it still changes query structure). Comments use `#` only.\n- **Aliases**: always use the full dot-path (`enroll.student.id`); alias every new expression with `as`; a select alias is usable in `having`/`order by` but NOT inside other select expressions or `where`, and must not rename a field back to an existing concept name.\n\n## Filtering\n\n`where` filters input rows before aggregation; `having` filters results after aggregation/windows. The inline filter `x ? cond` filters the immediate prior expression: `sum(credits ? enrolled = true)`.\n\nAggregates/windows in WHERE do not filter each other's inputs. Use inline filters, or a staged `then where` chain: each `then where` stage's aggregates compute over only the rows passing earlier stages (`where x = 5 then where sum(y) > 10` ≡ `where x = 5 and sum(y ? x = 5) > 10`). One rule: the SAME cross-row expression cannot gate two different stages — give one an inline filter.\n\nWindows need all rows in their range: filter AFTER the window (in `having`) rather than in `where` when the window must see the full set.\n\n## Membership (semijoins)\n\n`in` / `not in` cross models without any declared relationship — the semijoin IS a scoped intersection. The right side is a concept or expression (never a subselect); build computed sets with an inline filter: `auto big_zip <- student.zip ? (count(student.id ? student.honors = true) by student.zip) > 10; ... where school.zip in big_zip`.\n\nMembership is IDENTITY matching, not SQL three-valued logic: NULL matches NULL; the result is always TRUE or FALSE (safe as a projected flag); `not in` is the exact complement (a NULL in the set never empties the result). For strict SQL behavior, add `x is not null`.\n\nA fact model contains ALL dimensional members, so `where students.id not in enroll.student_id` is typically a tautology — use `where enroll.id is null` instead. Tuple membership `(a, b) in (m.a, m.b)` requires both right-side concepts to resolve to ONE source (model or rowset); to test against a cross-model pair, stage it through a rowset first. Examples: existence-anti-join, staged-membership.\n\n## Aggregation\n\nAn aggregate without an explicit `by` is RESPONSIVE — its grain is set where it is consumed, not where it is declared (`auto avg_credits <- avg(enroll.credits);` becomes per-department when selected with `enroll.department`). Pin a grain inline: `sum(metric) by dim1, dim2 as name`; `by` accepts bare identifiers or parenthesized expressions: `avg(price) by (substring(phone, 1, 2))`.\n\nMulti-level grouping (`by rollup|cube|grouping sets (...)`) is a clause of the WHOLE select, placed before `having`: it computes every no-explicit-grain aggregate at every level in one pass (`by rollup (d1, d2)` → leaf, per-d1 subtotal, grand total). `grouping(<field>)` = 1 on rolled-up rows — use it to label levels rather than testing for NULL. Full detail: trilogy agent-info syntax example rollup.\n\n## Window functions\n\nDefault to windows for self-referential queries (period-over-period, running totals, rank, share of group). SQL-style syntax: `rank(<key>) over (partition by <g> order by <expr> desc)` (`dense_rank`/`row_number` same shape; multi-key `rank(a, b)`); `sum(x) over (partition by g order by t)` for running totals; `lag(<field>, <offset>) over (...)` / `lead(...)` for offsets (default 1). `partition by` is optional and accepts expressions.\n\n## Data types\n\nScalars: `string`, `bytes`, `bool`, `int`, `bigint`, `float`, `double`, `number`, `numeric(p,s)` (alias `decimal`; use for exact money), `date`, `datetime`, `timestamp`, `geography`, `any`. Composites: `array<T>`, `map<K, V>`, `struct<name: T, ...>`, `enum<T>[v1, v2, ...]`. Cast with `::type` or `cast(x as type)`: `\"2020-01-01\"::date`.\n\n`?` after a type marks it nullable (`property user.middle_name string?;`). `~` prefixing a concept marks the reference as a PARTIAL subset of the concept's domain — on a select item (`~customer.id`) or in `merge a into ~b` (a ⊆ b); it tells the planner this side is not authoritative.\n\n## Expression gotchas\n\n- `x ? cond` binds to a primary — wrap arithmetic: `(a - b) ? cond`, NOT `a - b ? cond`.\n- `a || b` is NULL if either side is NULL; `concat(...)` skips NULL arguments; `concat_ws(sep, ...)` joins with sep, skipping NULLs.\n- Date parts are unquoted: `date_part(d, year)`, never `'year'`; prefer `year(d)`. `date_diff(start, end, unit)` = end − start (a shipping lag is `date_diff(sold_date, ship_date, day)`).\n- Zero-argument functions still take parentheses: `current_date()`.\n- Factor repeated calculations into a `def` macro (invoked `@name(...)`) or reusable `auto` concepts.", nt = ["aggregate: count|count_distinct|sum|max|min|avg|stddev|variance|array_agg|bool_or|bool_and|any|grouping(<arg1>) ; grouping_id(<arg1>, <arg2>, ..., <argN>)"], rt = [
 	"aggregate: count|count_distinct|sum|max|min|avg|stddev|variance|array_agg|bool_or|bool_and|any|grouping(<arg1>) ; grouping_id(<arg1>, <arg2>, ..., <argN>)",
 	"string: concat|concat_strict|concat_ws(<arg1>, <arg2>, ..., <argN>) ; split|strpos|contains|trim|regexp_contains|format_time|parse_time(<arg1>, <arg2>) ; len|lower|upper|ltrim|rtrim|hex(<arg1>) ; substring|replace|regexp_extract|regexp_replace(<arg1>, <arg2>, <arg3>)",
 	"date/time: date|datetime|timestamp|second|minute|hour|day|day_of_week|week|month|quarter|year|month_name|day_name|unix_to_timestamp(<arg1>) ; date_spine(<arg1>, <arg2>) ; current_date|current_datetime()",
@@ -1593,7 +1604,7 @@ var Ye = class t {
 	"conditional/cast: case|simple_case|coalesce|greatest|least(<arg1>, <arg2>, ..., <argN>) ; cast|nullif(<arg1>, <arg2>) ; isnull(<arg1>)",
 	"geo: geo_from_text|geo_x|geo_y|geo_centroid(<arg1>) ; geo_point|geo_distance(<arg1>, <arg2>) ; geo_transform(<arg1>, <arg2>, <arg3>)",
 	"other: is_not_distinct(<arg1>, <arg2>)"
-], at = [
+], it = [
 	"string",
 	"bytes",
 	"bool",
@@ -1615,6 +1626,121 @@ var Ye = class t {
 	"unix_seconds",
 	"unknown",
 	"any"
+], at = [
+	{
+		name: "case-when",
+		title: "Conditional values with case (relabel codes / bucket a measure)",
+		summary: "`case when <cond> then <val> ... else <val> end` to relabel codes or bucket a measure into a derived value, then group by it",
+		body: "# `case when <cond> then <val> ... else <val> end` builds a derived value.\n# Assign it to an `auto` concept, then group/filter by it like any other.\n# Use `else null` when unmatched rows should drop out of downstream grouping.\nimport iris as iris;\n\nauto petal_size <- case\n    when iris.petal_length < 2.0 then 'small'\n    when iris.petal_length < 5.0 then 'medium'\n    else 'large'\nend;\n\nselect\n    petal_size,\n    count(iris.petal_length) as flower_count,\n    avg(iris.petal_width) as avg_petal_width,\norder by flower_count desc;\n"
+	},
+	{
+		name: "chart",
+		title: "Chart statement - layers, roles, settings and reference lines",
+		summary: "drawing a result rather than tabulating it: `chart layer <type> ( <role> <- <expr> as <name>, ... )` is a STATEMENT that wraps its own query - the bindings ARE the select; layers, roles, scales, reference lines and `from <select>`",
+		body: "# `chart` is a top-level statement, like `select` - it wraps a query AND says\n# how to draw it. It renders wherever results render: a trilogy code block in a\n# `trilogy render` report, a studio cell, terminal output, and\n# `copy into png|svg|html|pdf '<path>' from chart ...` for a standalone image.\nimport enrollments as enroll;\n\n# --- 1. Minimal form --------------------------------------------------------\n# `layer <type> ( <role> <- <expr> [as <name>], ... )`. The bindings ARE the\n# select: grouping is automatic by the non-aggregated ones, exactly as in a\n# query. NEVER write a separate `select` for a chart.\nchart layer bar ( x_axis <- enroll.department, y_axis <- sum(enroll.credits) as credits );\n\n# A COMPUTED binding must be aliased: `y_axis <- sum(enroll.credits) as credits`.\n# A bare concept reference needs no alias (`x_axis <- enroll.department`) but may\n# take one as a display label. `y_axis <- sum(...)` with no `as` is a parse error.\n#\n# GRAIN: every binding is a select column, so binding a FINER concept to any\n# role (color, group, annotation, ...) refines the grain and splits the marks -\n# exactly as adding that column to a select would. Aggregate annotations at the\n# mark's own grain (`count(enroll.id) as ...`) instead of binding a detail field.\n\n# --- 2. Every part of the statement -----------------------------------------\n# Components may appear in any order after `chart`; at least one `layer` is\n# required, and multiple `layer`s compose into one overlaid chart.\nchart\n  set show_title                            # title from the value-axis label\n  set hide_legend\n  set scale_y: log                          # scale_x | scale_y : linear | log | sqrt\n  layer bar (\n    x_axis <- enroll.department,\n    y_axis <- sum(enroll.credits) as credits,\n    color <- enroll.completed,              # one legend series per value\n    annotation <- count(enroll.id) as enrollments   # text label on each mark\n  )\n  order by credits desc                     # category order follows ORDER BY\n  limit 10                                  # (ascending when there is no ORDER BY)\n  place hline at 5 as target;               # reference rule; `place vline at ...`\n                                            # too. `at` takes a literal; `as <label>`\n                                            # is optional\n\n# --- 3. `from <select>` - when the bindings cannot express the query ---------\n# Bindings alone have no `where` / `having` / hidden columns. Add `from` plus a\n# COMPLETE select, which carries its own clauses in the usual order:\nchart layer line (\n    x_axis <- enroll.year,\n    y_axis <- completions,\n    color <- enroll.department\n  )\n  from\n  where enroll.year >= 2016\n  select\n    enroll.year,\n    enroll.department,\n    count(enroll.id ? enroll.completed = true) as completions\n  order by enroll.year asc;\n# With `from select`, EVERY binding must be a bare reference to one of the\n# select's outputs - put transformations inside the select - and layer-level\n# `order by` / `limit` are rejected: they belong to the select.\n\n# --- 4. Types ---------------------------------------------------------------\n#   bar       vertical bars: x_axis = category, y_axis = measure\n#   barh      horizontal bars: x_axis = MEASURE, y_axis = category (roles swap)\n#   line      x_axis = the ordered axis (date/year), y_axis = measure\n#   point     scatter; `size <- <measure>` scales the marks\n#   area      line, filled\n#   headline  big KPI number - needs only `x_axis <- <measure> as <name>`\n#   donut     the numeric binding sizes the slices; the other positional one -\n#             or `color` - names them. No annotations.\n#   heatmap   x_axis and y_axis are BOTH categories, `color` is the measure\n#   boxplot   x_axis = category, y_axis = the distribution being summarized\n# `treemap` parses but no renderer implements it; the error names what does.\nchart layer barh ( x_axis <- sum(enroll.credits) as credits, y_axis <- enroll.department );\nchart layer headline ( x_axis <- count(enroll.student_id) as students );\nchart layer donut ( x_axis <- enroll.department, y_axis <- sum(enroll.credits) as credits );\nchart layer heatmap (\n    x_axis <- enroll.year,\n    y_axis <- enroll.department,\n    color <- sum(enroll.credits) as credits\n);\n# A boxplot summarizes RAW rows, so its select has to carry the fact's row grain\n# - hidden with `--` - or output dedup collapses the distribution to the set of\n# distinct values.\nchart layer boxplot ( x_axis <- enroll.department, y_axis <- enroll.credits )\n  from select --enroll.id, enroll.department, enroll.credits;\n\n# --- 5. Roles ---------------------------------------------------------------\n#   x_axis, y_axis          position\n#   color                   one series per value, WITH a legend\n#   size                    mark size (point)\n#   group                   side-by-side bars, or a per-series split on\n#                           line/point/area - no legend\n#   x_trellis / y_trellis   small multiples (columns / rows)\n#   annotation              per-mark text label\n#   geo                     reserved - parses, then raises\n# Each role may be bound at most once per layer; an unknown role name is a parse\n# error. Trellis roles cannot combine with multiple layers, placements, or\n# annotations (Vega-Lite forbids facets inside layered charts).\nchart layer bar (\n    x_axis <- enroll.year,\n    y_axis <- sum(enroll.credits) as credits,\n    group <- enroll.department              # side-by-side bars, no legend\n);\n\n# EXPLICIT SERIES COLORS: select a `string::hex` column (the trait comes from\n# `import std.color;`) alongside a `color` binding and each color value takes the\n# hex code found on its rows (missing -> gray); bind the hex column itself to\n# `color` to use the codes directly.\n"
+	},
+	{
+		name: "correlated-exists-via-grouped-counts",
+		title: "Correlated EXISTS / NOT-EXISTS over rows of the SAME model",
+		summary: "translate `EXISTS other` / `NOT EXISTS other matching` over the same model into two `count(...) by <grain>` compared in `where` (`> 1` = another exists, `= 1` = no other matches) - pin the correlation grain with `by`",
+		body: "# A self-referential EXISTS / NOT-EXISTS (e.g. \"the ONLY enrollee who completed\n# a course that had more than one enrollee\") becomes TWO filtered counts pinned\n# to the correlation grain, compared in `where`:\n#   count(k) by <grain> > 1            # EXISTS another row in the group\n#   count(k ? cond) by <grain> = 1     # NOT EXISTS another row matching cond\n#                                         (exactly one matches: the row itself)\n# An aggregate condition in `where` groups by the SELECT grain unless pinned.\n# When the correlation grain DIFFERS from the select grain - as here\n# (correlate by course, select per student) - you MUST pin it with `by <grain>`;\n# a bare `count(...) > 0` would group by the select grain and give wrong rows.\n# SCOPE: the pin fixes only the GROUPS. A `where` aggregate always computes\n# over ALL rows of the model; the other `where` predicates never narrow its\n# input rows - exactly right for whole-table EXISTS checks like this one. If\n# the aggregate should see only already-filtered rows, use `having` or stage\n# it with `then where` (a stage's aggregates see only rows passing earlier\n# stages).\nimport enrollments as enroll;\n\nauto enrollees_per_course <- count(enroll.student_id) by enroll.course;\nauto completers_per_course <- count(enroll.student_id ? enroll.completed = true) by enroll.course;\n\nwhere\n    enroll.completed = true\n    and enrollees_per_course > 1     # the course had at least one OTHER enrollee\n    and completers_per_course = 1    # and no OTHER enrollee completed it\nselect\n    enroll.student_id,\n    count(enroll.course) as sole_completions\norder by sole_completions desc\nlimit 100;\n"
+	},
+	{
+		name: "dedup-before-aggregate",
+		title: "Deduplicate identical rows before aggregating (UNION DISTINCT)",
+		summary: "a `rowset <- select <cols>` collapses identical tuples to one row (SELECT-grain group by) before a downstream sum - the `distinct`/UNION substitute",
+		body: "# `distinct` and UNION are not available. To collapse identical tuples to one\n# row BEFORE aggregating (so duplicates don't double-count), materialize the\n# tuple in a `rowset <- select <cols>`: a rowset select groups at its own grain,\n# emitting one row per distinct tuple. Then aggregate over the rowset's columns.\n#  - ALIAS every rowset column you reference downstream with `as`. Without `as`,\n#    the column keeps its FULL source path under the rowset name - `select\n#    sales.item.brand_id` is reachable as `rs.sales.item.brand_id`, NOT\n#    `rs.brand_id`. `as brand_id` makes it `rs.brand_id`.\nimport enrollments as enroll;\n\n# Collapse repeat (student, course) enrollments to one row each (a student who\n# took a course in multiple years counts once).\nrowset unique_sc <- select\n    enroll.student_id as sid,\n    enroll.course as course,\n;\n\n# Count over the deduplicated rows - identical (student, course) pairs counted once.\nselect\n    unique_sc.course,\n    count(unique_sc.sid) as distinct_students,\norder by unique_sc.course asc;\n"
+	},
+	{
+		name: "except-intersect-setops",
+		title: "Set difference / co-occurrence across sources with except(...) / intersect(...)",
+		summary: "set difference or co-occurrence across sources",
+		body: "# `except(...)` and `intersect(...)` are relational table-valued functions with the\n# SAME shape as `union(...)`: TWO OR MORE inline self-contained select arms, matched\n# by COLUMN POSITION to the trailing `-> (...)` output list. They are SQL SET\n# operators, which differ from the union stack in three ways:\n#   - the output is DEDUPLICATED (distinct rows);\n#   - whole rows are compared with NULL-SAFE equality (NULL matches NULL - the\n#     same identity semantics as `in` / `not in` membership);\n#   - for `except(...)` ARM ORDER MATTERS: the FIRST arm is the base population and\n#     every later arm is subtracted from it, left to right.\n# Use `except` for \"combinations in A that never appear in B (or C)\" and\n# `intersect` for \"combinations present in every source\".\nimport enrollments as enroll;\n\n# Distinct (course, year) combinations Biology offered that Chemistry did not.\nwith bio_only as except(\n    (where enroll.department = 'Biology'\n     select enroll.course as course, enroll.year as year),\n    (where enroll.department = 'Chemistry'\n     select enroll.course as course, enroll.year as year)\n) -> (course, year);\n\nselect\n    bio_only.course,\n    bio_only.year,\norder by bio_only.course asc nulls first, bio_only.year asc nulls first\nlimit 100;\n\n# Counting the surviving combinations is the idiomatic anti-membership count\n# (e.g. \"customers who bought in store but never online\"):\n#     from except((...store combos...), (...web combos...)) -> (last, first, day)\n#     select count(day) as combos;\n# ---------------------------------------------------------------------------\n# NOTES:\n#  - Same arm rules as `union(...)`: inline arms only, positional binding, equal\n#    column count/order/types per arm; reference outputs as `<rowset>.<output>`.\n#  - `except((a), (b), (c))` means (a EXCEPT b) EXCEPT c - subtract left to right.\n#    `intersect(...)` keeps rows present in EVERY arm (order does not matter).\n#  - Outputs are DISTINCT rows: aggregate them directly (`count(x)`) for \"how many\n#    unique combinations\" - no extra dedup step needed.\n"
+	},
+	{
+		name: "existence-anti-join",
+		title: "Existence / anti-join across models",
+		summary: "keeping or excluding rows by whether a key matches another model",
+		body: "# `in` / `not in` against another model's key is the semi-join / anti-join\n# idiom - no manual JOIN. Use it instead of `count(...) is null` hacks.\n# Membership is IDENTITY matching and total: NULL matches NULL, the result is\n# never NULL, and `not in` is the EXACT complement of `in` - a NULL in the set\n# does not empty an anti-join (no SQL NOT-IN footgun), and NULL-keyed rows land\n# in exactly one of the two sides. For strict SQL parity, filter NULLs\n# explicitly (`where key is not null and key in other.key`).\nimport students as students;\nimport enrollments as enroll;\n\n# semi-join: majors with at least one student enrolled in 'Biology 101'\nauto bio_students <- enroll.student_id ? enroll.course = 'Biology 101';\nwhere students.id in bio_students\nselect students.major, count(students.id) as enrolled_students;\n\n# anti-join: students who never enrolled in ANY course\nwhere students.id not in enroll.student_id\nselect students.major, count(students.id) as never_enrolled;\n\n# NULLABLE FLAG: a flag that is true only when a match exists and NULL otherwise\n# (e.g. `enroll.completed` set only for graded rows) needs `is null` for the\n# \"never matched\" case - `not flag` evaluates NULL→dropped, losing those rows.\nwhere enroll.completed is null\nselect enroll.student_id;\n\n# COMPOSITE (multi-column) membership: to test a MULTI-PART key against a set,\n# wrap both sides in matching tuples - `(a, b) in (set.a, set.b)`. This matches\n# ROW-WISE (the whole tuple must appear as one row of the set), so it is NOT the\n# same as `a in set.a and b in set.b`, which matches the parts independently and\n# lets unrelated cross-pairs through. Build the set as a `rowset` selecting the\n# key columns, then test the tuple with `in` / `not in`. Prefer this over\n# concatenating the parts into a single string key.\nrowset multi_course_pairs <- select\n    enroll.department as dept,\n    enroll.course as course,\nhaving count_distinct(enroll.year) > 1;      # (dept, course) offered in >1 year\n\nwhere (enroll.department, enroll.course)\n    in (multi_course_pairs.dept, multi_course_pairs.course)\nselect enroll.student_id, count(enroll.id) as enrollments;\n"
+	},
+	{
+		name: "filtered-aggregate",
+		title: "Filtered aggregate - aggregate only the rows matching a condition",
+		summary: "aggregating only the rows matching a condition, and counting rows correctly",
+		body: "# `?` is a local filter - a filter that applies only to the prior expression-\n# several differently-filtered measures can share one select. Add `by <grain>`\n# to pin an aggregate to a grain other than the select's.\nimport iris as iris;\n\nselect\n    iris.species,\n    avg(iris.petal_length) as avg_petal,\n    avg(iris.petal_length ? iris.petal_width > 1.5) as avg_petal_wide_only,\n    count(iris.petal_length ? iris.sepal_length > 6.0) as long_sepal_count,\norder by iris.species asc;\n\n# COUNTING ROWS: `count(k ? cond)` counts DISTINCT values of k - `count` is\n# distinct-by-argument. To count matching ROWS, count the model's unique grain /\n# row key (often named `row_key`), NOT a non-unique sub-key. e.g. counting line\n# items by `count(line_number ? cond)` collapses to the number of distinct line\n# numbers (1..7) and undercounts - use `count(row_key ? cond)`.\n\n# COMPOSITE GRAIN: when SEVERAL keys together identify the thing you are counting,\n# name them with `grain(...)` instead of picking one:\n#   count(grain(sales.order_id, sales.item_id))                 # order+item lines\n#   count_distinct(grain(cust.first_name, cust.last_name, sales.date))\n# `grain(...)` is NEVER NULL, so a combination with a missing member (a customer\n# with no last name) still counts - whereas `count(last_name)` silently drops it.\n# It composes with `?` like any expression: count(grain(a, b) ? cond).\n"
+	},
+	{
+		name: "nested-aggregate-group-average",
+		title: "Compare a per-entity total to the group average of those totals",
+		summary: "the \"above 1.2x the group norm\" ask: inner `sum(x) by entity, group`, outer `avg(inner) by group`; use WHERE for the comparison when a separate output-only filter must not narrow the benchmark",
+		body: "# Compare each entity's total to the GROUP AVERAGE of those per-entity totals\n# (the \"above 1.2x the group norm\" pattern). Give EACH grain its own `by`: the\n# inner total is per (entity, group); the outer average re-aggregates those\n# totals up to the group. \n# since the aggregates are in the having, both are aggregates *after* the id filter is applied\nimport enrollments as enroll;\n\nauto student_dept_credits <- sum(enroll.credits) by enroll.student_id, enroll.department;\nauto dept_avg_credits <- avg(student_dept_credits) by enroll.department;\n\nwhere enroll.student_id > 103\nselect\n    enroll.student_id,\nhaving student_dept_credits > 1.2 * dept_avg_credits;\n\n# BENCHMARK OVER FULL POPULATION + FILTERED OUTPUT: if the department average must span\n# EVERY student but the output should contain only target students (id > 103), put the aggregate\n# comparison in WHERE alongside the output-only filter. Aggregate conditions in WHERE do\n# not filter one another's inputs, so `student_id > 103` does not narrow the department\n# benchmark. Do NOT put the comparison in HAVING after the output filter; that computes a\n# target-students-only department average.\nwhere\n    student_dept_credits > 1.2 * dept_avg_credits\n    and enroll.student_id > 103\nselect\n    enroll.student_id,\n    enroll.department,\n    student_dept_credits,\n;\n\n# SCOPED INPUT POPULATION: when the totals and their group average must use only\n# rows from a specific period, bind that condition inside the inner aggregate.\n# A separate output-only filter still belongs in the final WHERE and does not\n# narrow the rows feeding either aggregate.\nauto student_dept_credits_2024 <- sum(enroll.credits ? enroll.year = 2024)\n    by enroll.student_id, enroll.department;\nauto dept_avg_credits_2024 <- avg(student_dept_credits_2024) by enroll.department;\n\nwhere\n    student_dept_credits_2024 > 1.2 * dept_avg_credits_2024\n    and enroll.student_id > 103\nselect\n    enroll.student_id,\n    enroll.department,\n    student_dept_credits_2024,\n;\n\n# HIDDEN GROUP KEY: if the requested output is one row per (student, department)\n# but displays only student_id, keep department in the select with the `--`\n# PREFIX. Otherwise identical displayed student rows are deduplicated and the\n# required per-department row grain is lost.\nwhere student_dept_credits_2024 > 1.2 * dept_avg_credits_2024\nselect\n    enroll.student_id,\n    --enroll.department,\n;\n\n# For more complex boundaries, compute the full-population benchmark in a separate rowset\n# with no output filter, then apply the subset filter only in the final selection.\n"
+	},
+	{
+		name: "pivot-columns",
+		title: "Pivot dimension values into columns",
+		summary: "turn distinct values of a dimension into columns with a reusable `def` macro + filtered aggregate",
+		body: "# A `def` macro expands inline at each `@call`. Pair it with a filtered\n# aggregate to project one column per category value (a pivot). With no row\n# dimension in the select this yields a single summary row.\nimport iris as iris;\n\ndef species_avg(s) -> avg(iris.petal_length ? iris.species = s);\n\nselect\n    @species_avg('setosa') as setosa_avg_petal,\n    @species_avg('versicolor') as versicolor_avg_petal,\n    @species_avg('virginica') as virginica_avg_petal,\n;\n"
+	},
+	{
+		name: "python-datasource",
+		title: "Python script datasource - Arrow IPC producer plus Trilogy model",
+		summary: "run a local Python script as a datasource: wrap a function in `trilogy.io.run`, which writes the Arrow IPC stream to stdout for you from a table, dataframe, or list of dicts; declare concepts, map script columns in `datasource (...)`, use `grain (...) file `path.py`;`, then reference locally declared concepts WITHOUT the datasource name as a prefix",
+		body: "# Python datasources require `enable_python_datasources = true` under\n# `[engine.config]` in trilogy.toml. Create these TWO files side by side.\n#\n# File 1: fibonacci.py\n# ---------------------------------------------------------------------------\n# #!/usr/bin/env -S uv run\n# # /// script\n# # requires-python = \">=3.11\"\n# # dependencies = [\"pyarrow>=16\", \"pytrilogy\"]\n# # ///\n#\n# from trilogy.io import run\n#\n#\n# def fibonacci():\n#     values = [0, 1]\n#     while len(values) < 20:\n#         values.append(values[-1] + values[-2])\n#     return [{\"index\": i, \"value\": v} for i, v in enumerate(values)]\n#\n#\n# if __name__ == \"__main__\":\n#     raise SystemExit(run(fibonacci))\n#\n# `run` converts whatever you return -- a pyarrow table, a pandas/polars frame,\n# a list of dicts, or an iterator of those -- and gives the script a CLI\n# (`--limit`, `--filter`, `--columns`, `--describe`). Run\n# `trilogy source describe ./fibonacci.py` to print the datasource block below\n# instead of writing it against a guessed schema.\n#\n# IMPORTANT: stdout must contain ONLY the Arrow IPC stream. Send diagnostics\n# to stderr. A PEP 723 block lets `uv run` install script dependencies.\n#\n# File 2: query.preql\n# ---------------------------------------------------------------------------\nkey index int;\nproperty index.value int;\n\n# The left side is the physical Arrow column; the right side is the Trilogy\n# concept declared above. The file suffix identifies this as a Python source.\ndatasource fibonacci_numbers (\n    index: index,\n    value: value,\n)\ngrain (index)\nfile `./fibonacci.py`;\n\n# A datasource declaration does NOT create a namespace. Use local concepts as\n# `index` and `value`, NOT `fibonacci_numbers.index` / `.value`.\nselect\n    index,\n    value,\norder by index;\n"
+	},
+	{
+		name: "query-structure",
+		title: "Full query structure - every clause and where it goes (+ rowsets)",
+		summary: "the exact clause order of a query, and how to define a rowset",
+		body: "# Every Trilogy query has the SAME fixed skeleton. Top-level statements come\n# first (each ends with `;`), then ONE query whose clauses appear in this exact\n# order - each clause is OPTIONAL except `select`:\n#\n#   <top-level statements>;        # import / key / property / auto / metric /\n#                                  #   rowset / merge / def / datasource / parameter\n#   where   <row condition>        # 1. filter INPUT rows (BEFORE aggregation)\n#   select  <col>, <agg> as name,  # 2. the projection - grouping is AUTOMATIC by the\n#                                  #      non-aggregated columns (never write GROUP BY)\n#   <subset|union join a = b (=c)?>* # 3. blend models (zero or more joins; one per concept RIGHT AFTER the\n#                                  #      select list - the SQL-like spot)\n#   having  <result condition>     # 4. filter on an AGGREGATED / joined RESULT\n#   order by <col> asc|desc        # 5. sort\n#   limit   <n>                    # 6. cap rows\nimport enrollments as enroll;\nimport students as students;\n\n# --- TOP-LEVEL DEFINITIONS (reusable; all live ABOVE the query) -------------\n# An `auto`/`metric`/`property`/`key` defines a field. It expands inline wherever\n# referenced (a macro), re-evaluated in the referencing query's scope.\nauto completed_credits <- sum(enroll.credits ? enroll.completed = true);\n\n# A ROWSET is a NAMED select: `rowset <name> <- <a full select>;`. It runs as its\n# own scoped query (its own where/select/having) and exposes its outputs as\n# `<name>.<col>`. ALIAS every column you reuse downstream with `as`.\nrowset dept_totals <- select\n    enroll.department as department,\n    sum(enroll.credits) as total_credits,\n;\n\n# --- THE QUERY - clauses in the fixed order above ---------------------------\nwhere enroll.year >= 2015                   # 1. WHERE: per-row filter, before aggregation\nselect                                      # 2. SELECT: grouped automatically by students.major\n    students.major,\n    count(enroll.id) as enrollments,\n    --completed_credits,                    #    a leading `--` HIDES a column from the output\nsubset join enroll.student_id = students.id  # 3. JOIN: blend students onto enrollments (after the select list)\nhaving completed_credits > 0                # 4. HAVING: condition on an aggregated RESULT\norder by enrollments desc nulls first       # 5. ORDER BY\nlimit 100;                                  # 6. LIMIT\n\n# Reference a rowset's outputs as `<rowset>.<output>` in a later query.\nselect\n    dept_totals.department,\n    dept_totals.total_credits,\norder by dept_totals.total_credits desc nulls first\nlimit 100;\n\n# ---------------------------------------------------------------------------\n# NOTES:\n#  - Joins sit RIGHT AFTER the select list (the SQL-like, preferred spot). They\n#    may also appear before `select` - both parse - but keep them after the\n#    select list for consistency.\n#  - `where` filters INPUT rows (before aggregation). To filter on something only\n#    known AFTER the join / aggregation (e.g. comparing two joined rowsets'\n#    counts), select that value (hide it with `--`) and test it in `having` -\n#    `having` is the post-aggregation/output filter. There is only ONE `where`.\n#  - Output rows dedupe to the select grain. To keep legitimate duplicates (one\n#    row per matching fact), select the fact's grain keys - hide with `--` if\n#    they shouldn't appear in the output.\n#  - No FROM, GROUP BY, DISTINCT, SELECT *, subqueries, or SQL-style set/JOIN\n#    operators. Grouping is automatic; blend with the scoped `join` above.\n"
+	},
+	{
+		name: "rank-over-rollup",
+		title: "Rank within each rollup level (one window over the rollup)",
+		summary: "rank rollup subtotals/leaves with a SINGLE `rank(a,b) over (partition by level, parent ...)` - not separate ranks per level",
+		body: "# When ranking the rows of a ROLLUP within each hierarchy level, use ONE\n# multi-key window over the rollup output. `grouping()` gives the level; the\n# window partitions by (level, parent) so leaves rank within their parent and\n# subtotals rank among themselves - all in one pass. Do NOT write separate rank\n# concepts per level (they mis-rank across the wrong row set). The aggregates and\n# grouping() level concepts are plain - the select's `by rollup (…)` clause stamps\n# the grouping onto all of them.\nimport enrollments as enroll;\n\nauto total <- count(enroll.id);\nauto g_course <- grouping(enroll.course);\nauto g_year <- grouping(enroll.year);\nauto level <- g_course + g_year;   # 0 = leaf, 1 = course subtotal, 2 = grand total\nauto parent <- case when g_year = 0 then enroll.course else null end;\nauto rnk <- rank(enroll.course, enroll.year)\n    over (partition by level, parent order by total desc);\n\nselect\n    enroll.course,\n    enroll.year,\n    total,\n    level,\n    --parent,\n    rnk,\nby rollup (enroll.course, enroll.year)\norder by level desc nulls first, parent asc nulls first, rnk asc nulls first\nlimit 100;\n\n# ---------------------------------------------------------------------------\n# NOTE - a composite aggregate over a rollup (a difference/ratio of sums) needs\n# NO special handling: `sum(profit) - sum(loss) as net` rolls up both operands\n# to the same levels, because `by rollup (…)` is a property of the whole select,\n# not of one aggregate.\n"
+	},
+	{
+		name: "rollup",
+		title: "Subtotals + grand total in one pass with `by rollup (…)`",
+		summary: "subtotals and a grand total in one pass, and labeling the levels",
+		body: "# A `by rollup (d1, d2)` clause AFTER the select list (before having/order by)\n# computes the whole select at MULTIPLE grain levels in one pass - the grouping\n# sets (d1, d2), (d1), () - i.e. per-(d1,d2) leaf rows, a subtotal per d1, and a\n# grand total. (`by cube (d1, d2)` = every combination; `by rollup ()` over the\n# select's own grain.) It applies to EVERY aggregate in the select, so all\n# measures share one consistent grouping.\nimport enrollments as enroll;\n\n# `grouping(d)` = 1 when d is ROLLED UP on a row (a subtotal/grand-total row), 0 on\n# a leaf - use it to LABEL those rows: the rolled-up dimension is otherwise NULL\n# and would collide with any genuine NULL in the data.\nselect\n    case when grouping(enroll.department) = 1 then 'ALL DEPARTMENTS'\n         else enroll.department end as department,\n    case when grouping(enroll.course) = 1 then 'all courses'\n         else enroll.course end as course,\n    sum(enroll.credits) as total_credits\nby rollup (enroll.department, enroll.course)\nhaving total_credits > 0\norder by department asc nulls first, course asc nulls first\nlimit 100;\n\n# ---------------------------------------------------------------------------\n# NOTES:\n#  - CLAUSE ORDER matches SQL: the `by rollup (…)` grouping clause comes BEFORE\n#    `having` (select list -> by rollup -> having -> order by -> limit). The\n#    HAVING filters EVERY grouping level - subtotal and grand-total rows too.\n#  - SORT: use EXACTLY the sort the question asks for. Rollup rows are ordinary rows\n#    and sort with everything else (their rolled-up dimensions are NULL, hence\n#    `nulls first`/`nulls last` decides where they land). Sorting by LEVEL is OPTIONAL\n#    and only when you actually want leaves/subtotals/totals grouped together: ORDER BY\n#    cannot compute a fresh aggregate, so PROJECT the level (`grouping(a) + grouping(b)`)\n#    as a HIDDEN (`--`) column and sort by its alias:\n#        --grouping(enroll.department) + grouping(enroll.course) as _level\n#        order by _level asc, department asc nulls first\n#    Do NOT add `_level` to a sort the question already specified - a leading sort key\n#    changes WHICH rows survive a `limit`, so it can silently drop the totals.\n#  - COMPOSITE measures just work: `sum(a) - sum(b) as net` rolls up BOTH operands\n#    to the same levels because the `by rollup (…)` clause covers the whole select.\n#    To zero-fill a measure, wrap it: `coalesce(sum(a), 0) as a`.\n#  - FILTER-BEFORE-ROLLUP vs `having`: `by rollup (…) having x > t` filters EVERY level AFTER\n#    the rollup, so the subtotal/total rows still AGGREGATE the below-threshold leaves (they\n#    just aren't displayed). To keep only leaf groups meeting a threshold and roll up JUST\n#    those survivors, filter the leaves in a rowset FIRST (`rowset kept <- select … having x >\n#    t`), then `by rollup ()` over `kept`. `having` on the rollup itself is the wrong tool when\n#    subtotals must exclude the filtered-out leaves.\n"
+	},
+	{
+		name: "row-level-where-vs-having",
+		title: "Row-level filter (WHERE) vs aggregate filter (HAVING) - don't wrap a per-row threshold in max()/min()",
+		summary: "choosing between WHERE and HAVING for a threshold condition",
+		body: "# A non-aggregate, per-ROW condition belongs in WHERE - it filters the rows that\n# feed every aggregate, BEFORE grouping. HAVING is ONLY for filtering on an\n# aggregate RESULT. These are different operations; do not substitute one for the\n# other.\nimport iris as iris;\n\n# RIGHT - keep only large-sepal FLOWERS, then average their petals.\n# `sepal_length > 6.0` is a per-row test on a column -> WHERE.\nwhere iris.sepal_length > 6.0\nselect\n    iris.species,\n    avg(iris.petal_length) as avg_petal,\norder by iris.species asc;\n\n# WRONG - `having max(iris.sepal_length) by iris.species > 6.0` does NOT keep\n# large-sepal rows. It keeps whole SPECIES whose single largest flower exceeds\n# 6.0, then averages ALL of that species' flowers (small ones included). Wrapping\n# a per-row threshold in max()/min() in HAVING silently changes the meaning, and\n# AND-ing it with another filter (e.g. a rank cutoff) often yields 0 rows because\n# the two now select disjoint populations.\n#\n# Pick by what the condition is ABOUT:\n#   per-row value of a column   -> WHERE     `where x.amount > 10000`\n#   an aggregate's result       -> HAVING    `having total_amount > 10000`\n#                                             (select it, hide with `--`)\n#   aggregate just SOME rows    -> inline `?` `sum(x.amount ? x.amount > 10000)`\n#\n# An aggregate condition CAN go in WHERE as a pre-filter (`where count(x) > 0`);\n# it groups by the SELECT grain unless pinned with `by <grain>` (`by *` = a\n# whole-table total). SCOPE: a WHERE aggregate computes over ALL rows of the\n# model - the other WHERE predicates never narrow its input (HAVING, selected,\n# and inline-`?` aggregates DO see the filtered rows). `by` pins the groups,\n# never the input rows; for an aggregate over the filtered rows use `having`\n# or a `then where` stage.\n"
+	},
+	{
+		name: "scoped-join",
+		title: "Blend two models in one query with a scoped subset/union join",
+		summary: "blending a second fact model or rowset into one query",
+		body: "# A query-scoped `join` blends a second model into ONE select without editing the\n# model files (the query-local equivalent of `merge`). A join DECLARES how the\n# two keys' value domains relate - it never drops rows (rendering is always\n# row-preserving; restrict rows with explicit `is not null` filters):\n#   subset join a = b  -> declares a's values are contained in b's (a is the\n#                         narrow side, b superset, all values in a in b)\n#   union  join a = b  -> neither domain contains the other; the key coalesces\n#                         and unmatched rows from EITHER side are kept\n# Place the clause(s) RIGHT AFTER the `select` list (the SQL-like spot).\nimport enrollments as enroll;\nimport students as students;\n\n# (1) SINGLE-KEY blend: bring students onto enrollments by the shared student\n# key. Enrollment student ids are a SUBSET of all student ids, so declare that;\n# majors with no enrollments are preserved with a NULL count.\nselect\n    students.major,\n    count(enroll.id) as enrollments,\nsubset join enroll.student_id = students.id\norder by enrollments desc nulls first\nlimit 100;\n\n# The select plus its join clause(s) is ONE statement, so it must end with `;`\n# even when no `order by`/`limit` follows the join - a quick probe that stops\n# right after the join clause still needs the terminator:\nselect\n    students.major,\n    count(enroll.id) as enrollments,\nsubset join enroll.student_id = students.id;\n\n# ---------------------------------------------------------------------------\n# (2) MULTI-KEY blend - JOIN ON THE FULL GRAIN. When facts share a COMPOSITE\n# grain, write ONE join clause per key. `trilogy explore` shows each fact's grain\n# as `@<k1, k2>` (e.g. a sales/returns fact keyed `@<department, course>`);\n# matching only ONE key fans out and DOUBLE-COUNTS. Two rowsets, joined on both\n# of their shared keys:\nrowset completed_by <- where enroll.completed = true\n    select enroll.department as dept, enroll.course as course, count(enroll.id) as completed_cnt;\nrowset incomplete_by <- where enroll.completed = false\n    select enroll.department as dept, enroll.course as course, count(enroll.id) as incomplete_cnt;\nrowset null_completed <- where enroll.completed is null\n    select enroll.department as dept, enroll.course as course, count(enroll.id) as null_completed_cnt;\n\nselect\n    completed_by.dept,\n    completed_by.course,\n    completed_by.completed_cnt,\n    incomplete_by.incomplete_cnt,\n    null_completed.null_completed_cnt,\nunion join completed_by.dept = incomplete_by.dept = null_completed.dept\nunion join completed_by.course = incomplete_by.course = null_completed.course\norder by completed_by.dept asc nulls first\nlimit 100;\n\n# ---------------------------------------------------------------------------\n# (3) SELF-PAIR across two periods/sets (period-over-period) - a useful shape\n# for \"this year vs last year\": build one rowset per period (each aggregated to\n# the SAME keys), filter to restrict to output to one side or the other\n# in having clause.\n\nrowset y2020 <- where enroll.year = 2020 select enroll.department as dept, count(enroll.id) as cnt;\nrowset y2021 <- where enroll.year = 2021 select enroll.department as dept, count(enroll.id) as cnt;\n\nselect\n    y2020.dept,\n    y2020.cnt as cnt_2020,\n    y2021.cnt as cnt_2021,\n    y2021.cnt - y2020.cnt as yoy_diff,\nunion join y2020.dept = y2021.dept\nhaving y2021.cnt is not null\norder by yoy_diff desc nulls first\nlimit 100;\n\n# ---------------------------------------------------------------------------\n# (4) EXPRESSION join keys - a key may be ANY expression (arithmetic, an\n# aggregate, a window), not just a bare field. Here each year is matched to the\n# PRIOR year by joining on an OFFSET key (`prev_year.yr + 1`), so the prior\n# year's count lands on the current row without a self-merge. Only `=` equality\n# is supported (a key below comparison level - wrap a comparison in parens).\nrowset cur_year  <- select enroll.year as yr, count(enroll.id) as cnt;\nrowset prev_year <- select enroll.year as yr, count(enroll.id) as cnt;\n\nselect\n    cur_year.yr,\n    cur_year.cnt as this_year,\n    prev_year.cnt as prior_year,\nunion join cur_year.yr = prev_year.yr + 1\norder by cur_year.yr asc\nlimit 100;\n\n# NOTES:\n#  - JOIN ON THE FULL GRAIN: one `join` clause per key in the two facts' shared\n#    `@<...>` grain. Under-joining (one key of a multi-key grain) can cause\n#    duplication. Chain `= c` to also pull a base key into the join\n#    group so its properties stay reachable (`union join a.k = b.k = base.k`).\n#  - Stacked clauses of the SAME type can share one prefix via `and`:\n#    `union join a.k1 = b.k1 and a.k2 = b.k2` == two stacked `union join` clauses.\n#    `and` joins distinct KEY-EQUALITY groups (not filters); `= c` chains keys into\n#    ONE group - both compose: `union join a.k = b.k = base.k and a.k2 = b.k2`.\n#    A COMMA never separates join groups (it is a select-list separator only):\n#    `union join a.k1 = b.k1, a.k2 = b.k2` is an error - use `and`.\n#  - Terminate the statement with `;` after the LAST clause, whatever that clause\n#    is (join, `having`, `order by`, `limit`).\n#  - A join key may be ANY expression (a computed/offset key, an aggregate, a\n#    window), not only a bare field - see (4). Only `=` equality is supported.\n#  - Joins NEVER drop rows: for an intersection (rows present in BOTH sides),\n#    add explicit conditions - `where <side_a attr> is not null and <side_b\n#    attr> is not null`. A one-sided `is not null` keeps the other side's\n#    exclusive rows. Either spelling reads as \"did this side match?\": the\n#    side's own JOIN KEY (`where a.k is not null`, tested per side even though\n#    the projected key is the coalesced group axis) or any of its measures /\n#    attributes (`where a.cnt is not null`). Same in `having`.\n#  - `left`/`full`/`inner`/`right`/`cross join` are NOT valid query-scoped joins\n#    (they error) - only `subset`/`union`. Map an old `left join a = b` to\n#    `subset join b = a` (swap operands) and `full join a = b` to\n#    `union join a = b`. A union key-group must be ALL union (can't mix with\n#    subset on the SAME key; `union join a = b = c` chains one union group);\n"
+	},
+	{
+		name: "set-intersect-difference",
+		title: "Set intersection / difference on a multi-column key (presence per group)",
+		summary: "count tuples present in / absent from other groups via per-group presence flags - the multi-column INTERSECT/EXCEPT idiom",
+		body: "# To intersect or difference rows on a MULTI-COLUMN key (the SQL INTERSECT /\n# EXCEPT of several columns), group by the full key tuple and build a presence\n# flag per set with `sum(case when <set> then 1 else 0 end)`. Grouping keeps\n# NULL key parts as their own group (correct INTERSECT/EXCEPT semantics).\n# (Avoid concatenating nullable fields into a single key: `||` over a NULL\n# yields NULL, and `concat()`/`concat_ws()` skip NULLs, which conflates\n# distinct tuples - tuple grouping handles NULL parts correctly.)\nimport enrollments as enroll;\n\n# Presence of each (student_id, course) tuple among completed vs open enrollments.\nauto in_completed <- sum(case when enroll.completed = true then 1 else 0 end)\n    by enroll.student_id, enroll.course;\nauto in_open <- sum(case when enroll.completed = false then 1 else 0 end)\n    by enroll.student_id, enroll.course;\n\nselect\n    # intersection: tuples appearing in BOTH sets\n    sum(case when in_completed > 0 and in_open > 0 then 1 else 0 end) as in_both,\n    # difference: tuples completed but never open (completed EXCEPT open)\n    sum(case when in_completed > 0 and in_open = 0 then 1 else 0 end) as completed_only,\n;\n"
+	},
+	{
+		name: "staged-membership",
+		title: "Stage a coarse-grain membership set, then filter a fine-grain query",
+		summary: "filtering a fine-grain query by a set computed at a coarser grain",
+		body: "# When a query filters on a condition computed at a COARSER grain (e.g. \"items\n# sold in all 3 channels\", \"courses offered in more than one year\"), compute that\n# membership set in its own `rowset` and filter the fine-grain query with `in`.\n# Staging keeps the coarse aggregate from entangling with the fine-grain\n# aggregates (which otherwise re-aggregate / over-count).\nimport enrollments as enroll;\n\n# Coarse stage: courses offered in more than one year.\nrowset multi_year <- select\n    enroll.course as course,\n    --count_distinct(enroll.year) as year_count,\nhaving year_count > 1\n;\n\n# Fine stage: enrollments per course, only for those courses.\nwhere enroll.course in multi_year.course\nselect\n    enroll.course,\n    count(enroll.id) as enrollments,\norder by enrollments desc\nlimit 100;\n"
+	},
+	{
+		name: "union-stack-channels",
+		title: "Stack rows from several sources/channels with the union(...) TVF",
+		summary: "stacking several sources/channels together as rows",
+		body: "# `union(...)` is a relational table-valued function: it STACKS the rows of TWO OR\n# MORE self-contained `select` arms, positionally (like SQL `UNION ALL`), into one\n# named result. Use it to combine CHANNELS / SOURCES / labeled populations - ONE\n# ARM PER SOURCE, to any amount. It\n# is a row STACK, NOT a key-join: arms are matched by COLUMN POSITION, so every arm\n# must project the same number of columns, in the same order and types, as the\n# trailing `-> (...)` output list.\nimport enrollments as enroll;\n\n# IMPORTANT: each arm is an INLINE, self-contained select written directly inside\n# the `union(...)` - you CANNOT pass the name of a previously-defined rowset as an\n# arm; put the full select logic (its own `where`, its own aggregation) in the arm.\n# The arms' i-th column maps to the i-th name in the `-> (...)` output list; the\n# surface names inside each arm need not match - only POSITION does. Each arm may\n# group by its own dims (here `course`), so an arm can emit MANY rows.\nwith by_channel as union(\n    (where enroll.department = 'Biology'\n     select\n        'Biology' as channel,\n        enroll.course as course,\n        count(enroll.id) as enrollments,\n    ),\n    (where enroll.department = 'Chemistry'\n     select\n        'Chemistry' as channel,\n        enroll.course as course,\n        count(enroll.id) as enrollments,\n    ),\n    (where enroll.department = 'Physics'\n     select\n        'Physics' as channel,\n        enroll.course as course,\n        count(enroll.id) as enrollments,\n    )\n) -> (channel, course, enrollments);\n\n# Reference the stacked outputs as `<rowset>.<output>`.\nselect\n    by_channel.channel,\n    by_channel.course,\n    by_channel.enrollments,\norder by by_channel.channel, by_channel.enrollments desc nulls first\nlimit 100;\n\n# ---------------------------------------------------------------------------\n# NOTES:\n#  - Pass TWO OR MORE arms - add a fourth/fifth the same way; one arm per source.\n#  - The trailing `-> (channel, course, enrollments)` NAMES the positional outputs;\n#    column order / count / type must line up across every arm.\n#  - Every union output is treated as a KEY (grain component). To RE-AGGREGATE the\n#    stack (e.g. a grand total across channels), wrap it in an outer aggregate:\n#        select sum(by_channel.enrollments) by rollup by_channel.channel as total;\n#  - An arm may carry its OWN query-scoped join (`select ... subset join b = a`\n#    after its select list) - localize each source's join to the arm that needs it.\n#  - This is NOT the forbidden SQL `UNION` keyword between two selects; it is the\n#    `union(...)` function form - the cleanest way to stack rows from several\n#    sources.\n#  - AGGREGATING across a union/set-op: an arm's `select` dedups to its own output\n#    grain BEFORE stacking (all selects are select distinct), \n#    so stacking raw per-row values (a measure, a `1` flag)\n#    and summing/counting OUTSIDE the union silently undercounts whenever two source\n#    rows in one arm project the same tuple (e.g. two same-priced sales in a week).\n#    Pre-aggregate INSIDE each arm (`sum(sales) as v`, `sum(1) as cnt` - as this\n#    example's `count(enroll.id)` does), or pull the arm's grain key through as an\n#    extra output column so every fact row stays distinct (downstream selects can\n#    just ignore it). And count a GUARANTEED-non-null key, never a nullable display\n#    column: `except`/`intersect` keep all-null rows (NULL-safe), which\n#    `count(nullable_col)` then silently skips.\n"
+	},
+	{
+		name: "window-period-over-period",
+		title: "Period-over-period ratio with a window function",
+		summary: "`lead`/`lag` over (order by ...) to compare a row to an offset period; build a scoped set with `<col> ? <cond>` and filter with `in`",
+		body: "# `<col> ? <cond>` builds a filtered set of values you can match with `in`.\n# lead()/lag() over (order by ...) compares each row to an offset row - here\n# each year's enrollment count divided by the PRIOR year's.\nimport enrollments as enroll;\n\nauto recent_years <- enroll.year ? enroll.year >= 2015;\n\ndef vs_prior_year(amt) -> round(amt / (lag(amt, 1) over (order by enroll.year asc)), 2);\n\nwhere enroll.year in recent_years\nselect\n    enroll.year,\n    @vs_prior_year(count(enroll.id)) as enrollment_growth,\nhaving\n    enrollment_growth is not null\norder by enroll.year asc nulls first;\n"
+	}
 ];
 //#endregion
 //#region dashboards/prompts.ts
@@ -1688,25 +1814,25 @@ function ft(e) {
 }
 var pt = `You are a world-class assistant for generating queries in Trilogy, a SQL inspired language with similar syntax, Use the the syntax description below and field information to answer the user request. Return your answer with a short reasoning and a valid Trilogy query in triple double quotes.
 
-${k}
+${A}
 
 For any response to the user, use this format -> put your actual response within triple double quotes with thinking and justification before it, in this format (replace placeholders with relevant content): Reasoning: {{reasoning}} """{{ response }}"""
 `;
-function A(e) {
+function j(e) {
 	return ft(e).map((e) => `[name: ${e.name} | type:${e.type}${e.calculation ? " | alias_for:" + e.calculation : ""}${e.description ? " | description:" + e.description : ""}]`).join(", ");
 }
 function mt(e, t) {
-	return `${pt}. Using these base and aliased calculations, derivations thereof created with valid Trilogy, and any extra context you have: ${A(t)}, create the best valid Trilogy query to answer the following user input: "${e}" Return the query within triple double quotes with your thinking and justification before it, so of this form as a jinja template: Reasoning: {{reasoning_placeholder}} """{{ trilogy }}""". Example: Because the user asked for sales by year, and revenue is the best sales related field available, we can aggregate revenue by year: """SELECT order.year, sum(revenue) as year_revenue order by order.year asc;"""`;
+	return `${pt}. Using these base and aliased calculations, derivations thereof created with valid Trilogy, and any extra context you have: ${j(t)}, create the best valid Trilogy query to answer the following user input: "${e}" Return the query within triple double quotes with your thinking and justification before it, so of this form as a jinja template: Reasoning: {{reasoning_placeholder}} """{{ trilogy }}""". Example: Because the user asked for sales by year, and revenue is the best sales related field available, we can aggregate revenue by year: """SELECT order.year, sum(revenue) as year_revenue order by order.year asc;"""`;
 }
 function ht(e, t) {
-	return `${pt}. Using these base and aliased calculations, derivations thereof created with valid Trilogy, and any extra context you have: ${A(t)}, create the closest matching syntactically valid WHERE CLAUSE to filter a dashboard from this request """${e}""".  Return only the portion of a SQL query representing the where clause, excluding any ordering. Do not include comments. After you generate the code, review it carefully to make sure it is only the partial where clause of a select, starting with WHERE (imagine if you put a "select 1 ..." in front of it.), with no semicolon at the end. Return your generated code within triple double quotes with thinking and justification before it in the form (as a jinja example) Reasoning: {{reasoning}} """{{ trilogy }}""". Example: Reasoning: Because the user asked for rainbow colors, we can filter to where the color is a primary color """where color in ('red', 'blue', 'violet')"""`;
+	return `${pt}. Using these base and aliased calculations, derivations thereof created with valid Trilogy, and any extra context you have: ${j(t)}, create the closest matching syntactically valid WHERE CLAUSE to filter a dashboard from this request """${e}""".  Return only the portion of a SQL query representing the where clause, excluding any ordering. Do not include comments. After you generate the code, review it carefully to make sure it is only the partial where clause of a select, starting with WHERE (imagine if you put a "select 1 ..." in front of it.), with no semicolon at the end. Return your generated code within triple double quotes with thinking and justification before it in the form (as a jinja example) Reasoning: {{reasoning}} """{{ trilogy }}""". Example: Reasoning: Because the user asked for rainbow colors, we can filter to where the color is a primary color """where color in ('red', 'blue', 'violet')"""`;
 }
 function gt(e, t) {
-	return ct(e, A(t));
+	return ct(e, j(t));
 }
 //#endregion
 //#region llm/sharedToolSchemas.ts
-var _t = [
+var M = [
 	"line",
 	"bar",
 	"barh",
@@ -1720,7 +1846,7 @@ var _t = [
 	"boxplot",
 	"treemap",
 	"beeswarm"
-], vt = {
+], _t = {
 	chartType: "bar",
 	xField: "category",
 	yField: "revenue",
@@ -1737,13 +1863,13 @@ var _t = [
 	scaleX: "linear",
 	scaleY: "linear",
 	linkY2: !1
-}, yt = {
+}, vt = {
 	type: "object",
 	description: "One layer of a layered chart, drawn over the same result set.",
 	properties: {
 		chartType: {
 			type: "string",
-			enum: _t,
+			enum: M,
 			description: "Type of chart to render"
 		},
 		xField: {
@@ -1776,7 +1902,7 @@ var _t = [
 			description: "Which side to draw this layer value axis on (optional)"
 		}
 	}
-}, bt = {
+}, yt = {
 	chartType: "bar",
 	showTitle: !0,
 	layers: [{
@@ -1793,13 +1919,13 @@ var _t = [
 		value: 1e3,
 		label: "target"
 	}]
-}, j = {
+}, N = {
 	type: "object",
 	description: "Chart configuration object",
 	properties: {
 		chartType: {
 			type: "string",
-			enum: _t,
+			enum: M,
 			description: "Type of chart to render"
 		},
 		xField: {
@@ -1874,7 +2000,7 @@ var _t = [
 		},
 		layers: {
 			type: "array",
-			items: yt,
+			items: vt,
 			description: "Draw several marks over one result set, e.g. bars for a total with a line for an average. When set, the chart type and field bindings above are ignored and each layer supplies its own; the settings above (title, legend, scales) still apply to the chart as a whole. Only line, bar, barh, area, point, boxplot, donut and heatmap can be layers. Cannot be combined with trellisField/trellisRowField. Leave unset for an ordinary single-mark chart."
 		},
 		placements: {
@@ -1904,7 +2030,7 @@ var _t = [
 			description: "Force layers to share one y-axis (true) or get independent ones (false). Omit to let the chart decide from the layers value formats (optional)"
 		}
 	}
-}, xt = _t.map((e) => `'${e}'`).join(", "), M = `Chart type is auto-detected based on data shape unless you specify a chartConfig. Only provide chartConfig if the user specifically requests a chart type or configuration; otherwise let auto-detection handle it.
+}, bt = M.map((e) => `'${e}'`).join(", "), P = `Chart type is auto-detected based on data shape unless you specify a chartConfig. Only provide chartConfig if the user specifically requests a chart type or configuration; otherwise let auto-detection handle it.
 
 [Important!] Hiding fields used only for filtering/query structure from output - such as ranks - with the "--" trilogy select syntax may be useful to get the right auto-formatting. 
 
@@ -1913,12 +2039,12 @@ You DO NOT need to specify colorField as the hexField if it is included; it will
 You can also add a default available Trilogy import "import std.color;" at the top of a query and cast a string case statement of hex values to ::string::hex to create mappings yourself.
 Do this if the user asks for specific coloring.
 
-Example chartConfig: ${JSON.stringify(vt)}
+Example chartConfig: ${JSON.stringify(_t)}
 
 To draw more than one mark over the same results — bars for a total with a line for an average, say — set 'layers' instead of the top-level chart type and fields. Each layer names its own chartType and fields; title, legend and scale settings stay on the parent. Add 'placements' for constant reference lines.
-Example layered chartConfig: ${JSON.stringify(bt)}
+Example layered chartConfig: ${JSON.stringify(yt)}
 
-Available chartTypes: ${xt}`, N = {
+Available chartTypes: ${bt}`, F = {
 	name: "connect_data_connection",
 	description: "Connect or reconnect a data connection that is not currently active. Use this when a query fails because the connection is not active, or when you need to establish a connection before running queries.",
 	input_schema: {
@@ -1932,16 +2058,16 @@ Available chartTypes: ${xt}`, N = {
 };
 //#endregion
 //#region llm/chatAgentPrompt.ts
-function St(e) {
+function xt(e) {
 	return e({
-		trilogySyntaxReference: k,
-		rulesInput: nt,
-		aggFunctions: rt,
-		functions: it,
-		datatypes: at
+		trilogySyntaxReference: A,
+		rulesInput: tt,
+		aggFunctions: nt,
+		functions: rt,
+		datatypes: it
 	});
 }
-var Ct = {
+var I = {
 	name: "return_to_user",
 	description: "Signal that you are done and return control to the user. You MUST call this tool when you have completed all requested tasks and are ready for the user's next input. Provide a brief summary of what was accomplished. Never end a turn with plain text — always call this tool when finished.",
 	input_schema: {
@@ -1952,7 +2078,7 @@ var Ct = {
 		} },
 		required: ["message"]
 	}
-}, wt = [
+}, St = [
 	{
 		name: "run_trilogy_query",
 		description: "Execute a Trilogy query and return tabular results. Use this for data exploration, aggregations, and when the user wants to see raw data in a table format.",
@@ -1973,7 +2099,7 @@ var Ct = {
 	},
 	{
 		name: "chart_trilogy_query",
-		description: `Execute a Trilogy query and display results as a chart. ${M}`,
+		description: `Execute a Trilogy query and display results as a chart. ${P}`,
 		input_schema: {
 			type: "object",
 			properties: {
@@ -1986,7 +2112,7 @@ var Ct = {
 					description: "Data connection name to run the query against"
 				},
 				chartConfig: {
-					...j,
+					...N,
 					description: "Optional chart configuration. Only provide if user specifically requests a chart type or configuration."
 				}
 			},
@@ -2014,7 +2140,7 @@ var Ct = {
 			required: []
 		}
 	},
-	N,
+	F,
 	{
 		name: "create_markdown",
 		description: "Create a rich markdown artifact to display formatted text, summaries, reports, or data-driven content. Supports standard markdown syntax (headers, lists, bold, italic, links, tables, code blocks). When a query is provided, data from the query results can be referenced in the markdown template. Use this for narrative reports, executive summaries, annotated insights, or any rich text content.",
@@ -2107,7 +2233,7 @@ var Ct = {
 					description: "New title for the artifact"
 				},
 				chartConfig: {
-					...j,
+					...N,
 					description: "New chart configuration (for chart/results artifacts)"
 				}
 			},
@@ -2140,28 +2266,28 @@ var Ct = {
 			required: ["artifact_ids"]
 		}
 	},
-	Ct
+	I
 ];
-function Tt(e, t) {
+function Ct(e, t) {
 	if (!t || t.length === 0) return e;
 	let n = new Set(t);
 	return e.filter((e) => !n.has(e.name));
 }
-function Et(e, t) {
+function wt(e, t) {
 	if (!t || t.length === 0) return e;
 	let n = new Set(e.map((e) => e.name)), r = /* @__PURE__ */ new Set(), i = t.map((e) => {
 		let t = e.definition.name;
 		if (n.has(t)) throw Error(`Host tool '${t}' shadows a built-in chat tool`);
 		if (r.has(t)) throw Error(`Host tool '${t}' is declared twice`);
 		return r.add(t), e.definition;
-	}), a = e.findIndex((e) => e.name === Ct.name);
+	}), a = e.findIndex((e) => e.name === I.name);
 	return a === -1 ? [...e, ...i] : [
 		...e.slice(0, a),
 		...i,
 		...e.slice(a)
 	];
 }
-var Dt = [
+var Tt = [
 	{ text: "- Every query and chart tool call returns an artifact ID. Use these IDs to reference, update, or remove artifacts later." },
 	{
 		tool: "create_markdown",
@@ -2187,13 +2313,13 @@ var Dt = [
 		tool: "create_markdown",
 		text: "- When the user asks for a summary, report, or narrative, prefer create_markdown over just text responses - it renders in the artifacts panel."
 	}
-], Ot = [{
+], Et = [{
 	tool: "search_docs",
 	text: "- When you are unsure how to express something in Trilogy — window functions, date handling, filtering on aggregates, an unfamiliar keyword — call search_docs (kind: language or function) and then read_doc, rather than guessing at syntax. The reference above is a summary; the docs carry the full idioms."
 }, {
 	tool: "read_doc",
 	text: "- read_doc returns the full article for an id from search_docs; quote the relevant part back to the user when they ask how the language works."
-}], kt = [
+}], Dt = [
 	{
 		tool: "list_artifacts",
 		text: "Call list_artifacts to see everything currently in the panel."
@@ -2212,11 +2338,11 @@ var Dt = [
 	},
 	{ text: "The artifact panel should tell a coherent story that directly answers the user's latest request — not accumulate a growing pile from every prior turn." }
 ];
-function P(e, t) {
+function L(e, t) {
 	return e.filter((e) => !e.tool || !t.includes(e.tool));
 }
-function At(e) {
-	let { dataConnectionName: t, availableConnections: n, availableConcepts: r, activeImports: i = [], availableImportsForConnection: a = [], isDataConnectionActive: o = !0, disabledTools: s = [] } = e, c = P(Dt, s).map((e) => e.text).join("\n"), l = P(kt, s).map((e, t) => `${t + 1}. ${e.text}`).join("\n"), u = P(Ot, s), d = u.length > 0 ? `\n\nDOCUMENTATION:\n${u.map((e) => e.text).join("\n")}` : "", f = r && r.length > 0 ? `\n\nAVAILABLE FIELDS FOR QUERIES:\n${A(r)}` : "", p = !s.includes("connect_data_connection"), m = t && !o ? p ? " (NOT CONNECTED - use connect_data_connection tool to connect before running queries)" : " (NOT CONNECTED - queries will fail; tell the user the data connection is not available and call return_to_user)" : "", h = p ? "\n8. If the data connection is not active, use connect_data_connection to establish the connection before running queries" : "", g = t ? `ACTIVE DATA CONNECTION: ${t}${m}` : "No data connection currently selected. Ask the user which connection to use.", _ = i.length > 0 ? `\nACTIVE DATA SOURCE: ${i[0].name}` : "\nNo data source currently selected. Use select_active_import to select a data source, or use list_available_imports to see what is available.", v = a.length > 0 ? `\n\nAVAILABLE DATA SOURCES:\n${a.map((e) => `- ${e.name}${i.some((t) => t.id === e.id) ? " (active)" : ""}`).join("\n")}` : "";
+function Ot(e) {
+	let { dataConnectionName: t, availableConnections: n, availableConcepts: r, activeImports: i = [], availableImportsForConnection: a = [], isDataConnectionActive: o = !0, disabledTools: s = [] } = e, c = L(Tt, s).map((e) => e.text).join("\n"), l = L(Dt, s).map((e, t) => `${t + 1}. ${e.text}`).join("\n"), u = L(Et, s), d = u.length > 0 ? `\n\nDOCUMENTATION:\n${u.map((e) => e.text).join("\n")}` : "", f = r && r.length > 0 ? `\n\nAVAILABLE FIELDS FOR QUERIES:\n${j(r)}` : "", p = !s.includes("connect_data_connection"), m = t && !o ? p ? " (NOT CONNECTED - use connect_data_connection tool to connect before running queries)" : " (NOT CONNECTED - queries will fail; tell the user the data connection is not available and call return_to_user)" : "", h = p ? "\n8. If the data connection is not active, use connect_data_connection to establish the connection before running queries" : "", g = t ? `ACTIVE DATA CONNECTION: ${t}${m}` : "No data connection currently selected. Ask the user which connection to use.", _ = i.length > 0 ? `\nACTIVE DATA SOURCE: ${i[0].name}` : "\nNo data source currently selected. Use select_active_import to select a data source, or use list_available_imports to see what is available.", v = a.length > 0 ? `\n\nAVAILABLE DATA SOURCES:\n${a.map((e) => `- ${e.name}${i.some((t) => t.id === e.id) ? " (active)" : ""}`).join("\n")}` : "";
 	return `You are a data analysis assistant with access to Trilogy query capabilities.
 
 You have access to tools that can select datasources, execute queries and generate visualizations. When a user asks about data, analyze their request, make sure you are looking at the right source, write a valid Trilogy query, and use the appropriate tool.
@@ -2226,7 +2352,7 @@ AVAILABLE DATA CONNECTIONS: ${n.length > 0 ? n.join(", ") : "None configured - u
 ${_}${v}
 
 TRILOGY LANGUAGE REFERENCE:
-${k}
+${A}
 ${f}
 
 IMPORTANT GUIDELINES:
@@ -2253,9 +2379,9 @@ COMPLETING YOUR RESPONSE:
 }
 //#endregion
 //#region llm/subchatSummarize.ts
-var jt = "You are summarizing a subchat that has just finished. Read the transcript below (messages and tool calls) and produce a 2–4 sentence summary of what was accomplished, what (if anything) failed or remains, and any concrete artifacts (file names, queries, errors). Be specific. The overseer will use this report to update the user — there is no other source of truth, so do not omit important results.", Mt = "You are summarizing a subchat's progress for an overseer agent. Read the transcript below (messages and tool calls) and produce a concise 2–4 sentence summary of what has happened so far, what has been accomplished, and what (if anything) remains. Be specific about file names, queries, or errors. Do not editorialize.";
-async function Nt(e, t, n = "completion") {
-	let r = Pt(t.messages), i = n === "completion" ? jt : Mt, a = e.getFastModel(), o = e.model, s = !!a && a !== o;
+var kt = "You are summarizing a subchat that has just finished. Read the transcript below (messages and tool calls) and produce a 2–4 sentence summary of what was accomplished, what (if anything) failed or remains, and any concrete artifacts (file names, queries, errors). Be specific. The overseer will use this report to update the user — there is no other source of truth, so do not omit important results.", At = "You are summarizing a subchat's progress for an overseer agent. Read the transcript below (messages and tool calls) and produce a concise 2–4 sentence summary of what has happened so far, what has been accomplished, and what (if anything) remains. Be specific about file names, queries, or errors. Do not editorialize.";
+async function jt(e, t, n = "completion") {
+	let r = Mt(t.messages), i = n === "completion" ? kt : At, a = e.getFastModel(), o = e.model, s = !!a && a !== o;
 	try {
 		return s && (e.model = a), (await e.generateCompletion({
 			prompt: "",
@@ -2268,42 +2394,42 @@ async function Nt(e, t, n = "completion") {
 		s && (e.model = o);
 	}
 }
-function Pt(e) {
+function Mt(e) {
 	return e.map((e, t) => {
-		let n = [`[${t}] ${e.role}: ${Ft(e.content || "", 800)}`];
-		if (e.toolCalls && e.toolCalls.length > 0) for (let t of e.toolCalls) n.push(`  → ${t.name}(${Ft(JSON.stringify(t.input), 200)})`);
-		if (e.toolResults && e.toolResults.length > 0) for (let t of e.toolResults) n.push(`  ← ${t.toolName}: ${Ft(t.result, 300)}`);
+		let n = [`[${t}] ${e.role}: ${Nt(e.content || "", 800)}`];
+		if (e.toolCalls && e.toolCalls.length > 0) for (let t of e.toolCalls) n.push(`  → ${t.name}(${Nt(JSON.stringify(t.input), 200)})`);
+		if (e.toolResults && e.toolResults.length > 0) for (let t of e.toolResults) n.push(`  ← ${t.toolName}: ${Nt(t.result, 300)}`);
 		return n.join("\n");
 	}).join("\n\n");
 }
-function Ft(e, t) {
+function Nt(e, t) {
 	return e.length <= t ? e : e.slice(0, t - 1) + "…";
 }
-var It = 4, Lt = 8, Rt = 1600;
-function F(e) {
+var Pt = 4, Ft = 8, It = 1600;
+function R(e) {
 	return e ? Math.ceil(e.length / 4) : 0;
 }
-function zt(e) {
-	let t = It + F(e.content);
+function Lt(e) {
+	let t = Pt + R(e.content);
 	for (let n of e.toolCalls ?? []) {
-		t += Lt + F(n.name);
+		t += Ft + R(n.name);
 		try {
-			t += F(JSON.stringify(n.input));
+			t += R(JSON.stringify(n.input));
 		} catch {}
 	}
-	for (let n of e.toolResults ?? []) t += Lt + F(n.toolName), t += F(n.result), n.imageData && (t += Rt);
+	for (let n of e.toolResults ?? []) t += Ft + R(n.toolName), t += R(n.result), n.imageData && (t += It);
 	return t;
 }
-function Bt(e) {
-	return e.reduce((e, t) => e + zt(t), 0);
+function Rt(e) {
+	return e.reduce((e, t) => e + Lt(t), 0);
 }
 //#endregion
 //#region llm/toolLoopCore.ts
-var Vt = "<user_input>", Ht = "</user_input>", I = "<system_input>", L = "</system_input>";
-function R(e) {
+var zt = "<user_input>", Bt = "</user_input>", z = "<system_input>", B = "</system_input>";
+function Vt(e) {
 	return e.replace(/<\/?(?:user_input|system_input)>/gi, "");
 }
-function Ut(e) {
+function Ht(e) {
 	let t = e?.data;
 	return !Array.isArray(t) || t.length <= 100 ? {
 		head: t ?? [],
@@ -2317,11 +2443,11 @@ function Ut(e) {
 		cutCount: t.length - 100
 	};
 }
-function Wt(e) {
+function Ut(e) {
 	if (e.success) if (e.artifact) {
 		let t = e.artifact.config, n = e.artifact.data, r = e.artifact.id, i = "";
 		if (n) {
-			let e = typeof n.toJSON == "function" ? n.toJSON() : n, a = t?.resultSize ?? (Array.isArray(e?.data) ? e.data.length : 0), { head: o, tail: s, cutCount: c } = Ut(e);
+			let e = typeof n.toJSON == "function" ? n.toJSON() : n, a = t?.resultSize ?? (Array.isArray(e?.data) ? e.data.length : 0), { head: o, tail: s, cutCount: c } = Ht(e);
 			if (c > 0) {
 				let t = JSON.stringify({
 					...e,
@@ -2339,7 +2465,7 @@ function Wt(e) {
 	else return "Success.";
 	else return `Error: ${e.error}`;
 }
-function Gt(e) {
+function Wt(e) {
 	if (e instanceof Error) return e.message;
 	if (typeof e == "string") return e;
 	try {
@@ -2348,18 +2474,18 @@ function Gt(e) {
 		return String(e);
 	}
 }
-async function Kt(e, t, n, r, i, a, o) {
+async function Gt(e, t, n, r, i, a, o) {
 	let s = o.maxIterations ?? 20, c = r.getMessages().slice(0, -1).map((e) => e.role === "user" && !e.hidden && e.content ? {
 		...e,
-		content: `${Vt}${R(e.content)}${Ht}`
-	} : e), l = `${Vt}${R(e)}${Ht}`, u = l, d = !1, f = 0;
+		content: `${zt}${Vt(e.content)}${Bt}`
+	} : e), l = `${zt}${Vt(e)}${Bt}`, u = l, d = !1, f = 0;
 	for (let e = 0; e < s; e++) {
 		if (a.checkAborted()) return e === 0 && r.addMessage({
 			role: "assistant",
 			content: "(Response in progress when stopped)"
 		}), r.addMessage({
 			role: "user",
-			content: `${I}[User requested pause - conversation can be continued]${L}`,
+			content: `${z}[User requested pause - conversation can be continued]${B}`,
 			hidden: !0
 		}), {
 			terminated: !1,
@@ -2372,7 +2498,7 @@ async function Kt(e, t, n, r, i, a, o) {
 			content: "(Response in progress when stopped)"
 		}), r.addMessage({
 			role: "user",
-			content: `${I}[User requested pause - conversation can be continued]${L}`,
+			content: `${z}[User requested pause - conversation can be continued]${B}`,
 			hidden: !0
 		}), {
 			terminated: !1,
@@ -2389,7 +2515,7 @@ async function Kt(e, t, n, r, i, a, o) {
 			content: g
 		}), r.addMessage({
 			role: "user",
-			content: `${I}[User requested pause - conversation can be continued]${L}`,
+			content: `${z}[User requested pause - conversation can be continued]${B}`,
 			hidden: !0
 		}), {
 			terminated: !1,
@@ -2410,7 +2536,7 @@ async function Kt(e, t, n, r, i, a, o) {
 			};
 			let e = o.noToolCallReminder ?? "You must call a tool to proceed. If you are finished, call the appropriate completion tool to return control to the user. Do not respond with text only.";
 			console.log("[toolLoopCore] No tool call — re-prompting agent to use a tool");
-			let t = `${I}${e}${L}`;
+			let t = `${z}${e}${B}`;
 			r.addMessage({
 				role: "user",
 				content: t,
@@ -2448,7 +2574,7 @@ async function Kt(e, t, n, r, i, a, o) {
 				hidden: !0
 			}), r.addMessage({
 				role: "user",
-				content: `${I}[User requested pause - conversation can be continued]${L}`,
+				content: `${z}[User requested pause - conversation can be continued]${B}`,
 				hidden: !0
 			}), {
 				terminated: !1,
@@ -2462,7 +2588,7 @@ async function Kt(e, t, n, r, i, a, o) {
 			} catch (n) {
 				t = {
 					success: !1,
-					error: `Tool "${e.name}" failed: ${Gt(n)}`
+					error: `Tool "${e.name}" failed: ${Wt(n)}`
 				};
 			}
 			let n = {
@@ -2519,7 +2645,7 @@ async function Kt(e, t, n, r, i, a, o) {
 					finalMessage: t.message
 				};
 			}
-			let i = Wt(t);
+			let i = Ut(t);
 			v.push({
 				toolCallId: e.id,
 				toolName: e.name,
@@ -2566,26 +2692,26 @@ async function Kt(e, t, n, r, i, a, o) {
 }
 //#endregion
 //#region llm/compaction.ts
-var qt = 2e4, Jt = 6, Yt = 20, Xt = 6, Zt = "You are a context summarization assistant. You are given the earlier portion of an assistant conversation that is about to fall out of the context window. Produce a structured summary that the assistant will rely on INSTEAD of those messages.\n\nUse exactly these sections:\n## Goal — what the user is ultimately trying to accomplish.\n## Progress — what was built, changed, or discovered, with exact names and ids (editors, dashboards, jobs, connections, queries, fields).\n## Key decisions — choices made and why, including approaches tried and rejected.\n## Current state — where the work stands right now.\n## Open items — unresolved questions, known failures, and obvious next steps.\n\nBe concrete: prefer exact identifiers, query text and error messages over paraphrase. Aim for 300-600 words. Omit nothing the assistant would need to continue seamlessly. Do not editorialize and do not add recommendations of your own.";
-function Qt(e) {
+var Kt = 2e4, qt = 6, Jt = 20, Yt = 6, Xt = "You are a context summarization assistant. You are given the earlier portion of an assistant conversation that is about to fall out of the context window. Produce a structured summary that the assistant will rely on INSTEAD of those messages.\n\nUse exactly these sections:\n## Goal — what the user is ultimately trying to accomplish.\n## Progress — what was built, changed, or discovered, with exact names and ids (editors, dashboards, jobs, connections, queries, fields).\n## Key decisions — choices made and why, including approaches tried and rejected.\n## Current state — where the work stands right now.\n## Open items — unresolved questions, known failures, and obvious next steps.\n\nBe concrete: prefer exact identifiers, query text and error messages over paraphrase. Aim for 300-600 words. Omit nothing the assistant would need to continue seamlessly. Do not editorialize and do not add recommendations of your own.";
+function Zt(e) {
 	return e.role === "user" && !(e.toolResults && e.toolResults.length > 0);
 }
-function $t(e, t) {
-	let n = t.keepRecentTokens ?? 2e4, r = t.minKeepRecentCount ?? Jt, i = t.maxKeepRecentCount ?? Yt, a = t.minArchiveCount ?? Xt, o = 0, s = 0;
-	for (let t = e.length - 1; t >= 0 && !(o >= i || o >= r && s >= n); t--) s += zt(e[t]), o++;
+function Qt(e, t) {
+	let n = t.keepRecentTokens ?? 2e4, r = t.minKeepRecentCount ?? qt, i = t.maxKeepRecentCount ?? Jt, a = t.minArchiveCount ?? Yt, o = 0, s = 0;
+	for (let t = e.length - 1; t >= 0 && !(o >= i || o >= r && s >= n); t--) s += Lt(e[t]), o++;
 	let c = e.length - o;
-	for (; c > 0 && !Qt(e[c]);) c--;
+	for (; c > 0 && !Zt(e[c]);) c--;
 	return c < a ? -1 : c;
 }
-function en(e, t, n) {
-	return !t || t <= 0 ? !1 : (n ?? Bt(e.getLLMMessages())) > t;
+function $t(e, t, n) {
+	return !t || t <= 0 ? !1 : (n ?? Rt(e.getLLMMessages())) > t;
 }
-async function tn(e, t, n) {
-	let r = Pt(t), i = e.getFastModel(), a = e.model, o = !!i && i !== a;
+async function en(e, t, n) {
+	let r = Mt(t), i = e.getFastModel(), a = e.model, o = !!i && i !== a;
 	try {
 		return o && (e.model = i), (await e.generateCompletion({
 			prompt: "",
-			systemPrompt: n ? `${Zt}\n\nAdditional emphasis requested: ${n}` : Zt
+			systemPrompt: n ? `${Xt}\n\nAdditional emphasis requested: ${n}` : Xt
 		}, [{
 			role: "user",
 			content: `--- TRANSCRIPT ---\n${r}`
@@ -2594,22 +2720,22 @@ async function tn(e, t, n) {
 		o && (e.model = a);
 	}
 }
-function nn(e) {
+function tn(e) {
 	return {
 		role: "user",
 		hidden: !0,
 		content: e
 	};
 }
-async function rn(e, t, n = {}) {
-	let r = t.getLLMMessages(), i = $t(r, n);
+async function nn(e, t, n = {}) {
+	let r = t.getLLMMessages(), i = Qt(r, n);
 	if (i < 0) return null;
-	let a = r.slice(0, i), o = await tn(e, a, n.focus), s = t.messages.indexOf(r[i]);
+	let a = r.slice(0, i), o = await en(e, a, n.focus), s = t.messages.indexOf(r[i]);
 	if (s < 0) return null;
 	a.forEach((e) => {
 		e.archived = !0;
 	});
-	let c = n.createSummaryMessage ?? nn, l = `${I}[Conversation compacted. Summary of the earlier conversation:]\n\n${o}${n.appendix ?? ""}${L}`;
+	let c = n.createSummaryMessage ?? tn, l = `${z}[Conversation compacted. Summary of the earlier conversation:]\n\n${o}${n.appendix ?? ""}${B}`;
 	t.messages.splice(s, 0, c(l));
 	let u = {
 		archivedCount: a.length,
@@ -2617,17 +2743,17 @@ async function rn(e, t, n = {}) {
 	};
 	return n.onCompacted?.(u), u;
 }
-function an(e) {
+function rn(e) {
 	let t = e.artifacts.filter((e) => !e.hidden);
 	return t.length === 0 ? "" : `\n\nArtifacts still available via get_artifact/get_artifact_rows:\n${t.map((e) => {
 		let t = e.config?.title || e.config?.query?.slice(0, 60) || "", n = e.config?.resultSize == null ? "" : `, ${e.config.resultSize} rows`;
 		return `- [${e.id}] ${e.type}${t ? ` "${t}"` : ""}${n}`;
 	}).join("\n")}`;
 }
-async function on(e, t, n = {}) {
-	return rn(e, t, {
+async function an(e, t, n = {}) {
+	return nn(e, t, {
 		...n,
-		appendix: n.appendix ?? an(t),
+		appendix: n.appendix ?? rn(t),
 		createSummaryMessage: n.createSummaryMessage ?? ((e) => ({
 			role: "user",
 			hidden: !0,
@@ -2639,10 +2765,10 @@ async function on(e, t, n = {}) {
 		}
 	});
 }
-async function sn(e, t, n = {}) {
-	if (!en(t, e.getCompactionThresholdTokens(), t.lastContextTokens)) return null;
+async function on(e, t, n = {}) {
+	if (!$t(t, e.getCompactionThresholdTokens(), t.lastContextTokens)) return null;
 	try {
-		let r = await on(e, t, n);
+		let r = await an(e, t, n);
 		return r && (t.lastContextTokens = void 0), r;
 	} catch (e) {
 		return console.error("Automatic conversation compaction failed:", e), null;
@@ -2650,7 +2776,7 @@ async function sn(e, t, n = {}) {
 }
 //#endregion
 //#region llm/editorRefinementTools.ts
-function z(e) {
+function sn(e) {
 	return e.filter((e) => e.trilogyType === "concept").map((e) => ({
 		name: e.label,
 		type: e.datatype || e.type,
@@ -2660,7 +2786,7 @@ function z(e) {
 	}));
 }
 function cn(e) {
-	return A(z(e));
+	return j(sn(e));
 }
 var ln = [
 	{
@@ -2703,10 +2829,10 @@ var ln = [
 		name: "edit_chart_config",
 		description: `Update the chart configuration for visualizing query results. Use this when the user wants to change how results are displayed.
 
-${M}`,
+${P}`,
 		input_schema: {
 			type: "object",
-			properties: { chartConfig: j },
+			properties: { chartConfig: N },
 			required: ["chartConfig"]
 		}
 	},
@@ -2784,7 +2910,7 @@ ${M}`,
 			required: []
 		}
 	},
-	N
+	F
 ], un = [
 	{
 		name: "browse_database_tree",
@@ -2898,7 +3024,7 @@ ${M}`,
 			required: []
 		}
 	},
-	N
+	F
 ], dn = ln;
 function fn(e) {
 	return e === "sql" ? un : ln;
@@ -2912,7 +3038,7 @@ ${i}
 ` : "", c = a ? `
 CURRENT CHART CONFIG:
 ${JSON.stringify(a, null, 2)}
-` : "", l = z(o), u = l.length > 0 ? `
+` : "", l = sn(o), u = l.length > 0 ? `
 AVAILABLE FIELDS FOR QUERIES (${l.length} concepts):
 ${cn(o)}
 ` : "";
@@ -2968,7 +3094,7 @@ AVAILABLE TOOLS:
 - close_session: Immediately close (only after user confirms or says "done")
 ${u}
 TRILOGY LANGUAGE REFERENCE:
-${k}
+${A}
 
 WORKFLOW:
 1. Understand what the user wants to change
@@ -2990,13 +3116,13 @@ IMPORTANT:
 }
 //#endregion
 //#region chats/chat.ts
-function B() {
+function V() {
 	return `art-${Date.now().toString(36)}-${Math.random().toString(36).substr(2, 6)}`;
 }
-function V() {
+function mn() {
 	return `Chat ${(/* @__PURE__ */ new Date()).toLocaleTimeString()}`;
 }
-var mn = class e {
+var hn = class e {
 	id;
 	name;
 	dataConnectionName;
@@ -3020,7 +3146,7 @@ var mn = class e {
 	changed;
 	deleted;
 	constructor(e = {}) {
-		this.id = e.id || `chat-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`, this.name = e.name || V(), this.dataConnectionName = e.dataConnectionName || "", this.dataConnectionId = e.dataConnectionId || "", this.llmConnectionName = e.llmConnectionName || "", this.messages = e.messages || [], this.artifacts = e.artifacts || [], this.activeArtifactIndex = e.activeArtifactIndex ?? -1, this.imports = e.imports || [], this.createdAt = e.createdAt || /* @__PURE__ */ new Date(), this.updatedAt = e.updatedAt || /* @__PURE__ */ new Date(), this.storage = e.storage || "local", this.source = e.source || "user", this.sourceRefId = e.sourceRefId ?? null, this.kind = e.kind || "user", this.parentChatId = e.parentChatId ?? null, this.parentProjectId = e.parentProjectId ?? null, this.pendingInjections = e.pendingInjections || [], this.pendingContextNote = e.pendingContextNote ?? null, this.lastContextTokens = e.lastContextTokens ?? void 0, this.changed = e.changed ?? !0, this.deleted = e.deleted ?? !1;
+		this.id = e.id || `chat-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`, this.name = e.name || mn(), this.dataConnectionName = e.dataConnectionName || "", this.dataConnectionId = e.dataConnectionId || "", this.llmConnectionName = e.llmConnectionName || "", this.messages = e.messages || [], this.artifacts = e.artifacts || [], this.activeArtifactIndex = e.activeArtifactIndex ?? -1, this.imports = e.imports || [], this.createdAt = e.createdAt || /* @__PURE__ */ new Date(), this.updatedAt = e.updatedAt || /* @__PURE__ */ new Date(), this.storage = e.storage || "local", this.source = e.source || "user", this.sourceRefId = e.sourceRefId ?? null, this.kind = e.kind || "user", this.parentChatId = e.parentChatId ?? null, this.parentProjectId = e.parentProjectId ?? null, this.pendingInjections = e.pendingInjections || [], this.pendingContextNote = e.pendingContextNote ?? null, this.lastContextTokens = e.lastContextTokens ?? void 0, this.changed = e.changed ?? !0, this.deleted = e.deleted ?? !1;
 	}
 	setName(e) {
 		this.name !== e && (this.name = e, this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0);
@@ -3035,7 +3161,7 @@ var mn = class e {
 		this.messages.push(e), this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0;
 	}
 	addArtifact(e) {
-		return e.id ||= B(), this.artifacts.push(e), this.activeArtifactIndex = this.artifacts.length - 1, this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0, this.activeArtifactIndex;
+		return e.id ||= V(), this.artifacts.push(e), this.activeArtifactIndex = this.artifacts.length - 1, this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0, this.activeArtifactIndex;
 	}
 	getArtifactById(e) {
 		return this.artifacts.find((t) => t.id === e) || null;
@@ -3069,7 +3195,7 @@ var mn = class e {
 		return this.activeArtifactIndex >= 0 && this.activeArtifactIndex < this.artifacts.length ? this.artifacts[this.activeArtifactIndex] : null;
 	}
 	clearMessages() {
-		this.messages = [], this.artifacts = [], this.activeArtifactIndex = -1, this.lastContextTokens = void 0, this.name = V(), this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0;
+		this.messages = [], this.artifacts = [], this.activeArtifactIndex = -1, this.lastContextTokens = void 0, this.name = mn(), this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0;
 	}
 	addImport(e) {
 		return this.imports.some((t) => t.id === e.id) ? !1 : (this.imports.push(e), this.updatedAt = /* @__PURE__ */ new Date(), this.changed = !0, !0);
@@ -3122,19 +3248,19 @@ var mn = class e {
 			changed: !1
 		});
 	}
-}, hn = [
+}, gn = [
 	"line",
 	"area",
 	"bar",
 	"barh",
 	"point",
 	"heatmap"
-], gn = [
+], _n = [
 	"geo-map",
 	"tree",
 	"donut",
 	"headline"
-], _n = [
+], vn = [
 	"bar",
 	"barh",
 	"line",
@@ -3143,7 +3269,7 @@ var mn = class e {
 	"boxplot",
 	"donut",
 	"heatmap"
-], vn = [
+], yn = [
 	{
 		id: "group-by",
 		label: "Group By",
@@ -3278,7 +3404,7 @@ var mn = class e {
 		field: "trellisField",
 		columnFilter: "categorical",
 		allowEmpty: !0,
-		visibleFor: hn,
+		visibleFor: gn,
 		filterGroup: "appearance"
 	},
 	{
@@ -3287,7 +3413,7 @@ var mn = class e {
 		field: "trellisRowField",
 		columnFilter: "categorical",
 		allowEmpty: !0,
-		visibleFor: hn,
+		visibleFor: gn,
 		filterGroup: "appearance"
 	},
 	{
@@ -3418,7 +3544,7 @@ var mn = class e {
 		],
 		filterGroup: "appearance"
 	}
-], yn = [
+], bn = [
 	{
 		value: "bar",
 		label: "Bar Chart",
@@ -3479,7 +3605,7 @@ var mn = class e {
 		label: "Beeswarm",
 		icon: "mdi mdi-chart-bubble"
 	}
-], bn = "#1f77b4", xn = "#9467bd", Sn = "#FF7F7F", H = (e, t) => e[t], Cn = [
+], xn = "#1f77b4", Sn = "#9467bd", Cn = "#FF7F7F", H = (e, t) => e[t], wn = [
 	"year",
 	"week",
 	"day",
@@ -3487,7 +3613,7 @@ var mn = class e {
 	"minute",
 	"second",
 	"quarter"
-], wn = [
+], Tn = [
 	"decade",
 	"year",
 	"month",
@@ -3497,50 +3623,50 @@ var mn = class e {
 	"minute",
 	"second",
 	"day_of_week"
-], U = (e) => e.traits ? e.traits.some((e) => wn.some((t) => e === t || e.endsWith("_" + t))) : !1, Tn = (e, t) => {
+], U = (e) => e.traits ? e.traits.some((e) => Tn.some((t) => e === t || e.endsWith("_" + t))) : !1, En = (e, t) => {
 	let n = t.get(e);
 	return n ? U(n) : !1;
-}, En = [
+}, Dn = [
 	"rank",
 	"index",
 	"grade",
 	"flag",
 	"letter_grade"
-], Dn = [
-	...Cn,
-	...En,
+], On = [
+	...wn,
+	...Dn,
 	"identifier",
 	"decade"
 ];
-function On(e) {
+function kn(e) {
 	return new Date(e);
 }
 var W = (e, t, n) => {
 	if (!e || !t.get(e)) return !1;
 	let r = t.get(e);
-	return r ? kn(r, n) : !1;
-}, kn = (e, t) => !!(e.traits && e.traits.some((e) => e.endsWith(t))), G = (e) => e.purpose === "key" || U(e) ? !1 : [
+	return r ? An(r, n) : !1;
+}, An = (e, t) => !!(e.traits && e.traits.some((e) => e.endsWith(t))), G = (e) => e.purpose === "key" || U(e) ? !1 : [
 	n.NUMBER,
 	n.INTEGER,
 	n.FLOAT
-].includes(e.type) && !e.traits?.some((e) => e.endsWith("latitude") || e.endsWith("longitude")), An = (e) => !!(e.traits && En.some((t) => e.traits?.includes(t))), jn = (e) => !!([n.STRING].includes(e.type) && e.traits?.some((e) => e.endsWith("url_image"))), K = (e) => !!([
+].includes(e.type) && !e.traits?.some((e) => e.endsWith("latitude") || e.endsWith("longitude")), jn = (e) => !!(e.traits && Dn.some((t) => e.traits?.includes(t))), Mn = (e) => !!([n.STRING].includes(e.type) && e.traits?.some((e) => e.endsWith("url_image"))), K = (e) => !!([
 	n.DATE,
 	n.DATETIME,
 	n.TIME,
 	n.TIMESTAMP
-].includes(e.type) || e.traits && Cn.some((t) => e.traits?.includes(t))), Mn = (e) => !!([n.STRING, n.BOOLEAN].includes(e.type) || e.purpose === "key" || e.traits && Dn.some((t) => e.traits?.includes(t))), Nn = (e) => e.traits?.includes("hex") ?? !1, q = (e, t) => e.traits ? e.traits.some((e) => e.endsWith(t)) : !1, J = (e, t) => {
+].includes(e.type) || e.traits && wn.some((t) => e.traits?.includes(t))), Nn = (e) => !!([n.STRING, n.BOOLEAN].includes(e.type) || e.purpose === "key" || e.traits && On.some((t) => e.traits?.includes(t))), Pn = (e) => e.traits?.includes("hex") ?? !1, q = (e, t) => e.traits ? e.traits.some((e) => e.endsWith(t)) : !1, J = (e, t) => {
 	let n = [];
 	return t.forEach((t, r) => {
-		(e === "all" || e === "numeric" && G(t) && !K(t) || e === "categorical" && Mn(t) || e === "temporal" && K(t) || e === "latitude" && q(t, "latitude") || e === "longitude" && q(t, "longitude") || e === "geographic" && t.traits?.some((e) => e.endsWith("state") || e.endsWith("state_short") || e.endsWith("country"))) && n.push(t);
+		(e === "all" || e === "numeric" && G(t) && !K(t) || e === "categorical" && Nn(t) || e === "temporal" && K(t) || e === "latitude" && q(t, "latitude") || e === "longitude" && q(t, "longitude") || e === "geographic" && t.traits?.some((e) => e.endsWith("state") || e.endsWith("state_short") || e.endsWith("country"))) && n.push(t);
 	}), n;
-}, Pn = (e, t) => {
+}, Fn = (e, t) => {
 	let n = t.filter((t) => t.name !== e.xField && t.name !== e.yField);
 	return n.length > 0 ? n[0] : t[0];
-}, Fn = (e, t, n) => {
+}, In = (e, t, n) => {
 	let r = {
 		showTitle: !1,
 		hideLegend: !1
-	}, i = J("numeric", t), a = J("categorical", t).filter((e) => !Nn(e)), o = J("temporal", t), s = J("latitude", t), c = J("longitude", t), l = J("geographic", t);
+	}, i = J("numeric", t), a = J("categorical", t).filter((e) => !Pn(e)), o = J("temporal", t), s = J("latitude", t), c = J("longitude", t), l = J("geographic", t);
 	if (t.size === 0) return {};
 	if (!n && i.length === 0 && l.length === 0 && c.length === 0 && s.length === 0) return r.chartType = "headline", r;
 	let u = a.filter((e) => U(e));
@@ -3555,7 +3681,7 @@ var W = (e, t, n) => {
 		n.size > 7 ? r.chartType = "barh" : r.chartType = "bar";
 	} else i.length >= 2 ? e.length === 1 ? r.chartType = "headline" : r.chartType = "point" : a.length >= 2 && i.length > 0 ? r.chartType = "heatmap" : i.length > 0 && a.length == 0 && (r.chartType = "headline");
 	if (r.chartType === "barh") {
-		r.yField = H(a, 0)?.name, i.length > 0 && (r.xField = Pn(r, i).name);
+		r.yField = H(a, 0)?.name, i.length > 0 && (r.xField = Fn(r, i).name);
 		let e = a.filter((e) => e.name !== r.yField && e.name !== r.xField);
 		e.length > 0 && (r.colorField = e[0].name), i.length > 1 && !r.colorField && (r.colorField = i[1].name);
 		let t = a.filter((e) => e.name !== r.yField && e.name !== r.xField && e.name !== r.colorField);
@@ -3603,7 +3729,7 @@ var W = (e, t, n) => {
 		n.length > 0 && (r.trellisRowField = n[0].name), n.length > 1 && (r.trellisField = n[1].name);
 	}
 	return r;
-}, In = (e, t) => {
+}, Ln = (e, t) => {
 	let n = J("numeric", t), r = J("categorical", t), i = J("temporal", t), a = J("latitude", t), o = J("longitude", t), s = J("geographic", t), c = [];
 	if (r.length > 0 && c.push("beeswarm"), n.length === 0) return (a.length > 0 && o.length > 0 || s.length > 0) && c.push("geo-map"), c.push("headline"), c;
 	let l = r.filter((e) => U(e));
@@ -3612,19 +3738,19 @@ var W = (e, t, n) => {
 		for (let r = 0; r < Math.min(e.length, 50); r++) e[r] && e[r][t] !== void 0 && n.add(e[r][t]);
 		c.push("bar"), c.push("barh"), c.push("donut");
 	}
-	return n.length >= 2 && c.push("point"), r.length >= 2 && n.length > 0 && c.push("heatmap"), n.length > 0 && (c.push("boxplot"), c.push("headline")), (a.length > 0 && o.length > 0 || s.length > 0) && c.push("geo-map"), c.filter((e) => yn.map((e) => e.value).includes(e));
-}, Ln = (e) => q(e, "latitude") ? "latitude" : q(e, "longitude") ? "longitude" : e.traits?.some((e) => e.endsWith("state") || e.endsWith("state_short") || e.endsWith("country")) ? "geographic" : K(e) ? "temporal" : U(e) ? "categorical" : G(e) ? "numeric" : Mn(e) ? "categorical" : "other", Rn = (e) => {
+	return n.length >= 2 && c.push("point"), r.length >= 2 && n.length > 0 && c.push("heatmap"), n.length > 0 && (c.push("boxplot"), c.push("headline")), (a.length > 0 && o.length > 0 || s.length > 0) && c.push("geo-map"), c.filter((e) => bn.map((e) => e.value).includes(e));
+}, Rn = (e) => q(e, "latitude") ? "latitude" : q(e, "longitude") ? "longitude" : e.traits?.some((e) => e.endsWith("state") || e.endsWith("state_short") || e.endsWith("country")) ? "geographic" : K(e) ? "temporal" : U(e) ? "categorical" : G(e) ? "numeric" : Nn(e) ? "categorical" : "other", zn = (e) => {
 	let t = [];
 	return e.forEach((e) => {
-		t.push(`${e.name} (${Ln(e)})`);
+		t.push(`${e.name} (${Rn(e)})`);
 	}), t.length > 0 ? t.join(", ") : "no fields";
-}, zn = (e, n, r) => {
-	let i = In(e, n), a = [];
+}, Bn = (e, n, r) => {
+	let i = Ln(e, n), a = [];
 	if (r.layers && r.layers.length > 0) {
 		let e = [], a = Array.from(n.keys());
 		return r.layers.forEach((r, i) => {
 			let o = `Layer ${i + 1}`;
-			_n.includes(r.chartType) || e.push(`${o}: chart type "${r.chartType}" cannot be used as a layer. Layerable types: ${_n.join(", ")}.`);
+			vn.includes(r.chartType) || e.push(`${o}: chart type "${r.chartType}" cannot be used as a layer. Layerable types: ${vn.join(", ")}.`);
 			for (let i of t) {
 				let t = r[i];
 				typeof t == "string" && t !== "" && !n.has(t) && e.push(`${o}: field "${t}" (${i}) does not exist in the query results. Available columns: ${a.join(", ")}.`);
@@ -3638,16 +3764,16 @@ var W = (e, t, n) => {
 		};
 	}
 	if (!i.includes(r.chartType)) {
-		let t = Rn(n);
+		let t = zn(n);
 		return {
 			valid: !1,
 			chartTypeError: `Chart type "${r.chartType}" is not compatible with the available fields (${t}). Eligible chart types: ${i.join(", ")}.`,
 			fieldErrors: [],
 			eligibleChartTypes: i,
-			suggestedConfig: Fn(e, n)
+			suggestedConfig: In(e, n)
 		};
 	}
-	let o = Fn(e, n, [
+	let o = In(e, n, [
 		"line",
 		"bar",
 		"barh",
@@ -3674,7 +3800,7 @@ var W = (e, t, n) => {
 		let t = r[e];
 		typeof t == "string" && t !== "" && !n.has(t) && a.push(`Field "${t}" (${e}) does not exist in the query results. Available columns: ${s.join(", ")}.`);
 	}
-	let c = vn.filter((e) => !e.allowEmpty && e.visibleFor.includes(r.chartType));
+	let c = yn.filter((e) => !e.allowEmpty && e.visibleFor.includes(r.chartType));
 	for (let e of c) {
 		let t = r[e.field];
 		(typeof t != "string" || t === "") && a.push(`Chart type "${r.chartType}" requires ${e.label} (${String(e.field)}) to be specified, but it is missing.`);
@@ -3685,7 +3811,7 @@ var W = (e, t, n) => {
 	}
 	if ((r.chartType === "line" || r.chartType === "area") && r.xField && n.has(r.xField)) {
 		let e = n.get(r.xField);
-		!K(e) && !Mn(e) && !G(e) && a.push(`For ${r.chartType} charts, xField should typically be a temporal or categorical column.`);
+		!K(e) && !Nn(e) && !G(e) && a.push(`For ${r.chartType} charts, xField should typically be a temporal or categorical column.`);
 	}
 	let l = { ...o };
 	for (let [e, t] of Object.entries(r)) t != null && (typeof t == "string" && t === "" || (l[e] = t));
@@ -3695,7 +3821,7 @@ var W = (e, t, n) => {
 		eligibleChartTypes: i,
 		suggestedConfig: l
 	};
-}, Bn = (e) => `Chart configuration is invalid for the data:\n${[e.chartTypeError, ...e.fieldErrors].filter(Boolean).map((e) => `  - ${e}`).join("\n")}\nEligible chart types for this data: ${e.eligibleChartTypes.join(", ") || "none"}.\nSuggested auto-detected config: ${JSON.stringify(e.suggestedConfig)}\nTip: Omit chartConfig to let auto-detection choose the best chart type and field mapping.`, Y = (e, t) => {
+}, Vn = (e) => `Chart configuration is invalid for the data:\n${[e.chartTypeError, ...e.fieldErrors].filter(Boolean).map((e) => `  - ${e}`).join("\n")}\nEligible chart types for this data: ${e.eligibleChartTypes.join(", ") || "none"}.\nSuggested auto-detected config: ${JSON.stringify(e.suggestedConfig)}\nTip: Omit chartConfig to let auto-detection choose the best chart type and field mapping.`, Y = (e, t) => {
 	if (!e || !t.get(e)) return {};
 	let r = t.get(e);
 	if (!r) return {};
@@ -3720,7 +3846,7 @@ var W = (e, t, n) => {
 		case n.INTEGER: return {};
 		default: return {};
 	}
-}, Vn = (e, t, n = null) => {
+}, Hn = (e, t, n = null) => {
 	if (!e || !t.get(e)) return {};
 	let r = t.get(e);
 	return r ? W(e, t, "day_of_week_name") ? { sort: [
@@ -3731,7 +3857,7 @@ var W = (e, t, n) => {
 		"Thursday",
 		"Friday",
 		"Saturday"
-	] } : An(r) || U(r) || K(r) ? { sort: {
+	] } : jn(r) || U(r) || K(r) ? { sort: {
 		field: e,
 		order: "ascending"
 	} } : G(r) ? n ? { sort: {
@@ -3756,19 +3882,19 @@ var W = (e, t, n) => {
 		n.DATETIME,
 		n.TIMESTAMP,
 		n.INTEGER
-	].includes(r.type) || [n.DATE].includes(r.type) ? "temporal" : "ordinal" : An(r) || U(r) ? "ordinal" : G(r) ? "quantitative" : "nominal" : "nominal";
-}, Hn = (e, t, n = {}, i = !0, a = {}) => e ? {
+	].includes(r.type) || [n.DATE].includes(r.type) ? "temporal" : "ordinal" : jn(r) || U(r) ? "ordinal" : G(r) ? "quantitative" : "nominal" : "nominal";
+}, Un = (e, t, n = {}, i = !0, a = {}) => e ? {
 	field: e,
 	type: X(e, t),
 	title: r(t.get(e)?.description || e),
 	...Y(e, t),
 	...n,
-	...i ? Vn(e, t) : {},
+	...i ? Hn(e, t) : {},
 	...a.scale !== void 0 || a.zero !== void 0 ? { scale: {
 		...a.scale !== void 0 && { type: a.scale },
 		...a.zero !== void 0 && { zero: a.zero }
 	} } : {}
-} : {}, Un = (e = 0) => e > 0 ? `_l${e}` : "", Z = (e, t = "") => `${e}${t}`, Wn = (e = "") => ({
+} : {}, Wn = (e = 0) => e > 0 ? `_l${e}` : "", Z = (e, t = "") => `${e}${t}`, Gn = (e = "") => ({
 	fillOpacity: {
 		condition: {
 			param: Z("select", e),
@@ -3788,7 +3914,7 @@ var W = (e, t, n) => {
 		}],
 		value: 0
 	}
-}), Gn = (e, t, n, r = "color") => {
+}), Kn = (e, t, n, r = "color") => {
 	let i = !1;
 	return n === "quantitative" && r === "color" && (i = !0), e && e.length > 10 ? {
 		orient: t ? "bottom" : "right",
@@ -3801,14 +3927,14 @@ var W = (e, t, n) => {
 		direction: t ? "horizontal" : "vertical",
 		titleFontSize: t ? 10 : 12
 	};
-}, Kn = 15, qn = (e, t, n, i = !1, a = "light", o = !1, s = [], c = "") => {
-	let l = { tickCount: Kn }, u = [], d = [], f = s || [], p = Array.from(n.entries()).filter(([e, t]) => t.traits?.includes("hex")).map(([e, t]) => e);
+}, qn = 15, Jn = (e, t, n, i = !1, a = "light", o = !1, s = [], c = "") => {
+	let l = { tickCount: qn }, u = [], d = [], f = s || [], p = Array.from(n.entries()).filter(([e, t]) => t.traits?.includes("hex")).map(([e, t]) => e);
 	if (t) {
 		let e = X(t, n);
 		l = {
 			...l,
-			...Gn(t, i, e)
-		}, (e === "nominal" || e === "ordinal") && (d = Array.from(new Set(f.map((e) => String(e[t] ?? "")))).sort((e, t) => e.localeCompare(t))), u = d.slice(0, Kn);
+			...Kn(t, i, e)
+		}, (e === "nominal" || e === "ordinal") && (d = Array.from(new Set(f.map((e) => String(e[t] ?? "")))).sort((e, t) => e.localeCompare(t))), u = d.slice(0, qn);
 	}
 	let m = (e) => (!o && Object.keys(l).length > 0 ? e.legend = l : o && (e.legend = null), e);
 	if (t && n.get(t)) {
@@ -3837,23 +3963,23 @@ var W = (e, t, n) => {
 			...c === null ? {} : { condition: [{
 				param: Z("highlight", c),
 				empty: !1,
-				value: Sn
+				value: Cn
 			}, {
 				param: Z("select", c),
 				empty: !1,
-				value: Sn
+				value: Cn
 			}] },
 			...Y(t, n)
 		});
 	}
 	return m({});
-}, Jn = (e, t, n = !1, i = !1) => {
+}, Yn = (e, t, n = !1, i = !1) => {
 	let a = { tickCount: 5 };
 	if (e) {
 		let r = X(e, t);
 		a = {
 			...a,
-			...Gn(e, n, r, "size")
+			...Kn(e, n, r, "size")
 		};
 	}
 	return e && t.get(e) ? ((e) => (!i && Object.keys(a).length > 0 ? e.legend = a : i && (e.legend = null), e))({
@@ -3868,7 +3994,7 @@ var W = (e, t, n) => {
 };
 //#endregion
 //#region llm/importConcepts.ts
-async function Yn(e, t, n) {
+async function Xn(e, t, n) {
 	let { connectionStore: r, editorStore: i, queryExecutionService: a } = e;
 	try {
 		if (!i?.editors[t.id]?.contents) return "No fields found in this data source.";
@@ -3911,7 +4037,7 @@ function Q(e) {
 function $(e, t) {
 	return e.connections[t] || e.connectionByName(t) || null;
 }
-async function Xn(e, t, n) {
+async function Zn(e, t, n) {
 	if (!t || typeof t != "string") return {
 		success: !1,
 		error: `Connection name is required. Available connections: ${Q(e) || "None"}`
@@ -3938,7 +4064,7 @@ async function Xn(e, t, n) {
 		};
 	}
 }
-function Zn(e, t, n, r) {
+function Qn(e, t, n, r) {
 	let i = /* @__PURE__ */ new Map(), a = $(e, n), o = a?.id || n;
 	return e.getConnectionSources(o).forEach((e) => i.set(e.alias, e.contents)), t && a && Object.values(t.editors).filter((e) => !e.deleted && e.connectionId === a.id).forEach((e) => {
 		i.set(e.name, e.contents);
@@ -3950,7 +4076,7 @@ function Zn(e, t, n, r) {
 		contents: t
 	}));
 }
-function Qn(e, t, n, r) {
+function $n(e, t, n, r) {
 	let i = typeof t?.toJSON == "function" ? t.toJSON() : t, a = i?.data;
 	if (!Array.isArray(a)) return {
 		success: !1,
@@ -3974,7 +4100,7 @@ function Qn(e, t, n, r) {
 		}, null, 2)
 	};
 }
-function $n(e, t, n) {
+function er(e, t, n) {
 	if (!e) return [];
 	let r = n ? $(n, t) : null;
 	return Object.values(e.editors).filter((e) => e.deleted ? !1 : r ? e.connectionId === r.id : e.connection === t).sort((e, t) => e.name.localeCompare(t.name)).map((e) => ({
@@ -3983,7 +4109,7 @@ function $n(e, t, n) {
 		alias: ""
 	}));
 }
-async function er(e, t, n, r, i) {
+async function tr(e, t, n, r, i) {
 	let a = t.getConnectionName(), o = i && a ? $(i, a) : null;
 	if (!e || e.trim() === "") return t.setActiveImports([]), {
 		success: !0,
@@ -3994,27 +4120,27 @@ async function er(e, t, n, r, i) {
 		success: !1,
 		error: "No data connection selected. Please select a data connection first."
 	};
-	let s = $n(r, o?.id || a, i), c = s.find((t) => t.name === e || t.name.endsWith(`.${e}`));
+	let s = er(r, o?.id || a, i), c = s.find((t) => t.name === e || t.name.endsWith(`.${e}`));
 	if (!c) return {
 		success: !1,
 		error: `Import "${e}" not found. Available imports: ${s.map((e) => e.name).join(", ") || "none"}`
 	};
 	let l = t.getActiveImports(), u = l.length === 1 && l[0].id === c.id;
 	u || t.setActiveImports([c]);
-	let d = await Yn(n, c, o?.id || a);
+	let d = await Xn(n, c, o?.id || a);
 	return {
 		success: !0,
 		message: `${u ? `"${c.name}" is already the active data source.` : `Successfully selected "${c.name}" as the active data source.`}\n\n${d}`,
 		triggersSymbolRefresh: !u
 	};
 }
-function tr(e, t, n) {
+function nr(e, t, n) {
 	let r = e.getConnectionName(), i = n && r ? $(n, r) : null, a = i?.name || r;
 	if (!r) return {
 		success: !1,
 		error: "No data connection selected. Please select a data connection first."
 	};
-	let o = $n(t, i?.id || r, n), s = e.getActiveImports(), c = s.length > 0 ? s[0] : null;
+	let o = er(t, i?.id || r, n), s = e.getActiveImports(), c = s.length > 0 ? s[0] : null;
 	return o.length === 0 ? {
 		success: !0,
 		message: `No data sources available on connection "${a}".`
@@ -4023,7 +4149,7 @@ function tr(e, t, n) {
 		message: `${c ? `Current active data source: ${c.name}\n\n` : "No data source currently selected.\n\n"}Available data sources for connection "${a}":\n${o.map((e) => `- ${e.name}${c?.id === e.id ? " (active)" : ""}`).join("\n")}\n\nUse select_active_import to select a data source.`
 	};
 }
-async function nr(e, t, n, r, i, a) {
+async function rr(e, t, n, r, i, a) {
 	if (!i || typeof i != "string" || i.trim() === "") return {
 		success: !1,
 		error: "Query is required and must be a non-empty string",
@@ -4045,7 +4171,7 @@ async function nr(e, t, n, r, i, a) {
 		error: `Connection "${o.name}" is not connected. Use connect_data_connection first.`,
 		query: i
 	};
-	let s = Zn(t, n, o.id, a), c = (a || []).map((e) => ({
+	let s = Qn(t, n, o.id, a), c = (a || []).map((e) => ({
 		name: e.name,
 		alias: e.alias || ""
 	})), l = {
@@ -4082,13 +4208,13 @@ async function nr(e, t, n, r, i, a) {
 }
 //#endregion
 //#region llm/editorRefinementToolExecutor.ts
-function rr() {
+function ir() {
 	return {
 		artifactRegistry: /* @__PURE__ */ new Map(),
 		lastQueryResults: { value: null }
 	};
 }
-var ir = class {
+var ar = class {
 	queryExecutionService;
 	connectionStore;
 	editorStore;
@@ -4097,7 +4223,7 @@ var ir = class {
 	lastQueryResults;
 	constructor(e, t, n, r, i) {
 		this.queryExecutionService = e, this.connectionStore = t, this.editorContext = n, this.editorStore = r || null;
-		let a = i ?? rr();
+		let a = i ?? ir();
 		this.artifactRegistry = a.artifactRegistry, this.lastQueryResults = a.lastQueryResults;
 	}
 	async executeToolCall(e, t) {
@@ -4250,7 +4376,7 @@ var ir = class {
 				generatedSql: i.generatedSql
 			};
 			let a = {
-				id: B(),
+				id: V(),
 				type: "results",
 				data: i.results,
 				config: {
@@ -4316,7 +4442,7 @@ var ir = class {
 		};
 		let t = this.editorContext.getCurrentResults?.() ?? this.lastQueryResults.value ?? null;
 		if (t && t.headers) {
-			let n = zn(t.data, t.headers, e);
+			let n = Bn(t.data, t.headers, e);
 			if (!n.valid) {
 				let e = n.suggestedConfig;
 				try {
@@ -4324,7 +4450,7 @@ var ir = class {
 				} catch {}
 				return {
 					success: !1,
-					error: "Auto-corrected to default configuration.\n" + Bn(n)
+					error: "Auto-corrected to default configuration.\n" + Vn(n)
 				};
 			}
 		}
@@ -4393,7 +4519,7 @@ var ir = class {
 				generatedSql: t.generatedSql
 			};
 			let n = {
-				id: B(),
+				id: V(),
 				type: "results",
 				data: t.results,
 				config: {
@@ -4423,7 +4549,7 @@ var ir = class {
 	}
 	getArtifactRows(e, t, n) {
 		let r = this.artifactRegistry.get(e);
-		return r ? Qn(e, r.data, t, n) : {
+		return r ? $n(e, r.data, t, n) : {
 			success: !1,
 			error: `Artifact "${e}" not found. Only artifacts created by run_query or run_active_editor_query in this session are available.`
 		};
@@ -4450,7 +4576,7 @@ var ir = class {
 		}
 	}
 	async connectDataConnection(e) {
-		return Xn(this.connectionStore, e);
+		return Zn(this.connectionStore, e);
 	}
 	serializeDatabaseTree(e, t, n) {
 		let r = this.connectionStore.connectionByName(this.editorContext.connectionName), i = r?.databases || [], a = (e ? i.filter((t) => t.name === e) : i).map((e) => {
@@ -4491,8 +4617,8 @@ var ir = class {
 		};
 	}
 	buildEditorExtraContent() {
-		return Zn(this.connectionStore, this.editorStore, this.editorContext.connectionName);
+		return Qn(this.connectionStore, this.editorStore, this.editorContext.connectionName);
 	}
 };
 //#endregion
-export { Ut as $, xe as $t, vn as A, We as At, pn as B, D as Bt, X as C, tt as Ct, Un as D, Ye as Dt, jn as E, O as Et, bn as F, He as Ft, rn as G, oe as Gt, fn as H, De as Ht, mn as I, Ae as It, L as J, re as Jt, sn as K, ne as Kt, V as L, Ie as Lt, gn as M, Re as Mt, hn as N, E as Nt, zn as O, Je as Ot, xn as P, Ve as Pt, R as Q, Ce as Qt, B as R, ze as Rt, Vn as S, Xe as St, Nn as T, et as Tt, qt as U, ae as Ut, z as V, Ue as Vt, on as W, te as Wt, Wt as X, le as Xt, I as Y, b as Yt, Kt as Z, ie as Zt, In as _, ut as _t, nr as a, c as an, Ct as at, W as b, Qe as bt, tr as c, Tt as ct, On as d, j as dt, ye as en, Bt as et, qn as f, N as ft, Fn as g, mt as gt, Jn as h, ht, Xn as i, f as in, wt as it, _n as j, Ge as jt, yn as k, Ke as kt, er as l, Et as lt, Wn as m, gt as mt, rr as n, y as nn, F as nt, Qn as o, d as on, At as ot, Hn as p, A as pt, en as q, se as qt, Zn as r, m as rn, Nt as rt, $n as s, u as sn, St as st, ir as t, Se as tn, zt as tt, Sn as u, M as ut, J as v, ot as vt, Tn as w, $e as wt, Y as x, Ze as xt, Bn as y, k as yt, dn as z, Be as zt };
+export { Vt as $, ie as $t, bn as A, qe as At, dn as B, Re as Bt, X as C, Xe as Ct, Wn as D, $e as Dt, Mn as E, Qe as Et, Sn as F, D as Ft, an as G, ae as Gt, sn as H, O as Ht, xn as I, Be as It, $t as J, ne as Jt, nn as K, te as Kt, hn as L, Ve as Lt, vn as M, Ue as Mt, _n as N, We as Nt, Z as O, k as Ot, gn as P, Le as Pt, Gt as Q, le as Qt, mn as R, ke as Rt, Hn as S, Ze as St, Pn as T, et as Tt, fn as U, He as Ut, pn as V, ze as Vt, Kt as W, De as Wt, z as X, re as Xt, B as Y, se as Yt, Ut as Z, b as Zt, Ln as _, mt as _t, rr as a, m as an, St as at, W as b, at as bt, nr as c, d as cn, xt as ct, kn as d, P as dt, Ce as en, Ht as et, Jn as f, N as ft, In as g, ht as gt, Yn as h, gt as ht, Zn as i, y as in, jt as it, yn as j, Ge as jt, Bn as k, Je as kt, tr as l, u as ln, Ct as lt, Gn as m, j as mt, ir as n, ye as nn, Lt as nt, $n as o, f as on, I as ot, Un as p, F as pt, on as q, oe as qt, Qn as r, Se as rn, R as rt, er as s, c as sn, Ot as st, ar as t, xe as tn, Rt as tt, Cn as u, wt as ut, J as v, ut as vt, En as w, Ye as wt, Y as x, A as xt, Vn as y, ot as yt, V as z, Fe as zt };