@m6d/cortex-cli 0.1.0

package/src/contracts/runtime/dataset-sql.ts

@@ -0,0 +1,2522 @@
+import type {
+    DatasetAggregate,
+    DatasetArithmeticOp,
+    DatasetBucket,
+    DatasetCatalog,
+    DatasetCondition,
+    DatasetDatePart,
+    DatasetDefinition,
+    DatasetFilter,
+    DatasetFilterOp,
+    DatasetFunction,
+    DatasetNamedOperand,
+    DatasetOperand,
+    DatasetQueryInput,
+    DatasetRelation,
+} from "./datasets";
+import { DATASET_BUCKETS, DATASET_DATE_PARTS, describeOperand, groupKeyName } from "./datasets";
+
+/*
+ * The SQL a model writes against a dataset, and how it becomes the wire
+ * query a host runs. One SELECT over one dataset, JOINs along the relations
+ * the host declares (matched by the ON clause, so two links to one dataset
+ * are told apart by their keys), dataset names or aliases as qualifiers,
+ * WHERE with NOT, dates (DATE_TRUNC, EXTRACT, CURRENT_DATE - INTERVAL),
+ * scalar functions and CASE as values, GROUP BY columns or named values,
+ * aggregates with FILTER (WHERE ...) or a CASE argument, calculations
+ * between aggregates, HAVING, windows (AGG(x) OVER (PARTITION BY ...)),
+ * QUALIFY over the finished row, RANK() ranking, ORDER BY, LIMIT and
+ * OFFSET. Anything outside the subset is refused with the clause named and
+ * what to write instead, so a refusal is the whole lesson for the next
+ * attempt. Parsing is deterministic and has no dependency; the grammar is
+ * small enough to read here.
+ */
+
+/**
+ * What a parse answers: the wire query, plus where each answered key goes in
+ * the row the model reads. A qualified column nests under its qualifier as
+ * written (`pets.name` → `{ pets: { name } }`); aliases, aggregates and bare
+ * columns stay at the top level.
+ */
+type ParsedDatasetSql = {
+    query: DatasetQueryInput;
+    /** Row key as the host answers it → the path it is placed at. Has no prototype, so a key like `__proto__` or `constructor` is only ever its own entry. */
+    shape: Record<string, string[]>;
+    /** Aggregates and windows the query added for HAVING, QUALIFY or a calculation but the statement never selected. */
+    hidden: string[];
+};
+
+/** A refusal the model can act on. */
+export class DatasetSqlError extends Error {}
+
+type Token =
+    | { kind: "word"; value: string; upper: string; quoted?: true }
+    | { kind: "string"; value: string }
+    | { kind: "number"; value: number }
+    | { kind: "punct"; value: string }
+    | { kind: "end" };
+
+const PUNCT = ["<=", ">=", "<>", "!=", "(", ")", ",", "*", "=", "<", ">", ".", ";", "+", "-", "/"];
+
+/** Reads a `'...'` literal starting at `start`; `''` is an escaped quote. */
+function stringLiteral(sql: string, start: number) {
+    let value = "";
+    let i = start + 1;
+    for (;;) {
+        if (i >= sql.length) throw new DatasetSqlError("A string literal is not closed.");
+        if (sql[i] === "'" && sql[i + 1] === "'") {
+            value += "'";
+            i += 2;
+        } else if (sql[i] === "'") {
+            return { token: { kind: "string", value } satisfies Token, next: i + 1 };
+        } else {
+            value += sql[i];
+            i += 1;
+        }
+    }
+}
+
+/** Reads the token at `i`: a quoted identifier, a number (negative only where a value is expected), a word or punctuation. */
+function lexeme(sql: string, i: number, previous: Token | undefined) {
+    const char = sql[i]!;
+    if (char === '"' || char === "`") {
+        const close = sql.indexOf(char, i + 1);
+        if (close === -1) throw new DatasetSqlError("A quoted identifier is not closed.");
+        const value = sql.slice(i + 1, close);
+        return {
+            token: {
+                kind: "word",
+                value,
+                upper: value.toUpperCase(),
+                quoted: true,
+            } satisfies Token,
+            next: close + 1,
+        };
+    }
+    const rest = sql.slice(i);
+    const number = /^-?\d+(\.\d+)?/.exec(rest);
+    // After a value or a closing parenthesis a minus subtracts; after a keyword or an operator it signs the number.
+    const afterValue =
+        previous !== undefined &&
+        (previous.kind === "punct"
+            ? previous.value === ")"
+            : previous.kind === "word"
+              ? ["END", "NULL", "TRUE", "FALSE"].includes(previous.upper) || isName(previous)
+              : true);
+    const signIsOperator = char === "-" && afterValue;
+    if (number && !signIsOperator) {
+        return {
+            token: { kind: "number", value: Number(number[0]) } satisfies Token,
+            next: i + number[0].length,
+        };
+    }
+    const word = /^[A-Za-z_][A-Za-z0-9_]*/.exec(rest);
+    if (word) {
+        return {
+            token: { kind: "word", value: word[0], upper: word[0].toUpperCase() } satisfies Token,
+            next: i + word[0].length,
+        };
+    }
+    const punct = PUNCT.find((candidate) => rest.startsWith(candidate));
+    if (punct) {
+        return { token: { kind: "punct", value: punct } satisfies Token, next: i + punct.length };
+    }
+    throw new DatasetSqlError(`Unexpected character "${char}".`);
+}
+
+/** Splits the statement into words, quoted strings, numbers and punctuation. Identifiers may be double quoted or backticked. */
+function tokenize(sql: string) {
+    const tokens: Token[] = [];
+    let i = 0;
+    while (i < sql.length) {
+        const char = sql[i]!;
+        if (/\s/.test(char)) {
+            i += 1;
+            continue;
+        }
+        if (char === "-" && sql[i + 1] === "-") {
+            throw new DatasetSqlError("Comments are not allowed; send the statement alone.");
+        }
+        const read = char === "'" ? stringLiteral(sql, i) : lexeme(sql, i, tokens.at(-1));
+        tokens.push(read.token);
+        i = read.next;
+    }
+    tokens.push({ kind: "end" });
+    return tokens;
+}
+
+type WireAggregate = NonNullable<DatasetQueryInput["aggregate"]>[number];
+type WireWindow = NonNullable<DatasetQueryInput["window"]>[number];
+type Literal = string | number | boolean;
+
+/**
+ * A value expression as written: references keep the statement's own
+ * spelling until compile time, aggregate and window calls are resolved to
+ * aliases on the answered row, and `date` is CURRENT_DATE or NOW() with any
+ * INTERVAL arithmetic already folded in.
+ */
+type Term =
+    | { kind: "ref"; ref: string }
+    | { kind: "num"; value: number }
+    | { kind: "lit"; value: string | boolean }
+    | { kind: "date"; at: Date }
+    | { kind: "interval"; months: number; days: number }
+    | { kind: "agg"; item: AggregateCall }
+    | { kind: "window"; item: WindowItem }
+    | { kind: "arith"; op: DatasetArithmeticOp; left: Term; right: Term }
+    | { kind: "dateTrunc"; unit: DatasetBucket; of: Term }
+    | { kind: "datePart"; unit: DatasetDatePart; of: Term }
+    | { kind: "fn"; fn: DatasetFunction; args: Term[] }
+    | { kind: "case"; branches: { when: Predicate[]; then: Term }[]; else?: Term };
+
+/** A condition as written; groups keep SQL's AND/OR/NOT structure until compile time, and `rank` is `RANK() OVER (...) <= n`. */
+type Predicate =
+    | {
+          kind: "cond";
+          left: Term;
+          op: DatasetFilterOp;
+          value?: Literal | Literal[] | { term: Term };
+      }
+    | { kind: "any"; of: Predicate[] }
+    | { kind: "all"; of: Predicate[] }
+    | { kind: "not"; of: Predicate }
+    | (RankWindow & { kind: "rank"; limit: number });
+
+/** `FN(value) [FILTER (WHERE ...)]` as written. */
+type AggregateCall = {
+    fn: DatasetAggregate;
+    term?: Term;
+    filter: Predicate[];
+    alias?: string;
+};
+
+type AggregateItem = AggregateCall & {
+    kind: "aggregate";
+    /** Added for the query but never answered: an aggregate the outer SELECT of a derived table left out. */
+    hidden?: true;
+};
+
+/** `FN(value) [FILTER (WHERE ...)] OVER ([PARTITION BY ...])`: an aggregate over the answered rows sharing the partition. */
+type WindowItem = AggregateCall & { partitionBy: Term[] };
+
+type SortList = { term: Term; dir: "asc" | "desc" }[];
+/** `RANK() OVER (PARTITION BY ... ORDER BY ...)`. */
+type RankWindow = { partitionBy: Term[]; sort: SortList };
+
+/** A SELECT list entry as written; `ref` is the SQL spelling, resolved to a wire reference at compile time. */
+type SelectItem =
+    | { kind: "column"; ref: string; alias?: string }
+    | AggregateItem
+    | { kind: "window"; item: WindowItem; alias: string; hidden?: true }
+    | { kind: "expr"; term: Term; alias?: string }
+    | (RankWindow & { kind: "rankWindow"; alias?: string })
+    | { kind: "star" };
+
+/** `inner` is JOIN or INNER JOIN: rows without a match are dropped, where LEFT JOIN keeps them. */
+type JoinClause = { dataset: string; alias?: string; left: string; right: string; inner: boolean };
+
+const AGGREGATE_WORDS = {
+    COUNT: "count",
+    SUM: "sum",
+    AVG: "avg",
+    MIN: "min",
+    MAX: "max",
+} satisfies Record<string, DatasetAggregate>;
+
+const FUNCTION_WORDS = {
+    LOWER: "lower",
+    UPPER: "upper",
+    TRIM: "trim",
+    LENGTH: "length",
+    LEN: "length",
+    CHAR_LENGTH: "length",
+    ABS: "abs",
+    ROUND: "round",
+    COALESCE: "coalesce",
+} satisfies Record<string, DatasetFunction>;
+
+const DATE_PART_WORDS = {
+    YEAR: "year",
+    QUARTER: "quarter",
+    MONTH: "month",
+    WEEK: "week",
+    DAY: "day",
+    DAYOFWEEK: "dayOfWeek",
+} satisfies Record<string, DatasetDatePart>;
+
+const NOW_WORDS = ["CURRENT_DATE", "CURRENT_TIMESTAMP", "NOW"];
+
+const RANK_WORDS = ["ROW_NUMBER", "RANK", "DENSE_RANK"];
+
+const RUNNING_TOTAL =
+    "OVER (... ORDER BY ...) running totals are not supported; a window here is an aggregate over the whole partition: write OVER () or OVER (PARTITION BY ...).";
+const WINDOW_IN_CONDITION =
+    "A window is worked out after WHERE and HAVING: name it in SELECT (AVG(x) OVER (...) AS name), use it in a calculation, or compare with a window in QUALIFY.";
+
+const FUNCTIONS = [
+    ...Object.keys(AGGREGATE_WORDS),
+    "DATE_TRUNC('unit', x)",
+    "EXTRACT(part FROM x)",
+    ...Object.keys(DATE_PART_WORDS),
+    ...Object.keys(FUNCTION_WORDS),
+    "NOW()",
+    "RANK() OVER (...)",
+].join(", ");
+
+const ONLY_INNER_OR_LEFT =
+    "Only JOIN (INNER JOIN, rows without a match dropped) and LEFT JOIN (rows without a match kept) along the joins a dataset declares are supported.";
+const SUBQUERY =
+    "Subqueries are not supported, except FROM (SELECT ..., RANK() OVER (...) AS rn FROM ...) WHERE rn <= n: run the inner SELECT on its own and finish the calculation in code.";
+const WINDOW_PLACE =
+    "RANK() goes in QUALIFY (QUALIFY RANK() OVER (PARTITION BY a ORDER BY b DESC) <= n) or in a derived table filtered on its alias (FROM (SELECT ..., RANK() OVER (...) AS rn FROM ...) WHERE rn <= n).";
+const INTERVAL_PLACE =
+    "INTERVAL only shifts CURRENT_DATE (CURRENT_DATE - INTERVAL '7 days'); compare the column against a date instead.";
+
+const REFUSED_CLAUSES = {
+    UNION: "UNION is not supported: ask each dataset in its own query.",
+    WITH: "WITH (CTEs) is not supported: write one SELECT over one dataset.",
+    DISTINCT:
+        "DISTINCT on rows is not supported: GROUP BY the columns instead; COUNT(DISTINCT column) is allowed.",
+    RIGHT: ONLY_INNER_OR_LEFT,
+    FULL: ONLY_INNER_OR_LEFT,
+    CROSS: ONLY_INNER_OR_LEFT,
+    INSERT: "Datasets are read only.",
+    UPDATE: "Datasets are read only.",
+    DELETE: "Datasets are read only.",
+} as const;
+
+/** Words that never serve as an alias or a name. */
+const RESERVED = [
+    "SELECT",
+    "FROM",
+    "WHERE",
+    "GROUP",
+    "ORDER",
+    "LIMIT",
+    "OFFSET",
+    "HAVING",
+    "QUALIFY",
+    "AND",
+    "OR",
+    "NOT",
+    "IN",
+    "IS",
+    "NULL",
+    "LIKE",
+    "BETWEEN",
+    "ASC",
+    "DESC",
+    "JOIN",
+    "INNER",
+    "LEFT",
+    "ON",
+    "FILTER",
+    "OVER",
+    "PARTITION",
+    "INTERVAL",
+    "CASE",
+    "WHEN",
+    "THEN",
+    "ELSE",
+    "END",
+];
+
+function isName(token: Token): token is Token & { kind: "word" } {
+    if (token.kind !== "word") return false;
+    return (
+        token.quoted === true ||
+        (!RESERVED.includes(token.upper) && !(token.upper in REFUSED_CLAUSES))
+    );
+}
+
+/** A unit written as `'month'`, `month` or `MONTH`. */
+function unitOf<U extends string>(token: Token, units: readonly U[]) {
+    const written = token.kind === "string" || token.kind === "word" ? token.value : "";
+    return units.find((unit) => unit.toLowerCase() === written.toLowerCase());
+}
+
+function isoDate(at: Date) {
+    return at.toISOString().slice(0, 10);
+}
+
+/** A month or year step keeps the day, clamped to the target month's last day (Mar 31 minus a month is Feb 28), then the days apply. */
+function shifted(at: Date, sign: 1 | -1, by: { months: number; days: number }) {
+    const date = new Date(at);
+    const day = date.getUTCDate();
+    date.setUTCDate(1);
+    date.setUTCMonth(date.getUTCMonth() + sign * by.months);
+    const lastDay = new Date(
+        Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + 1, 0),
+    ).getUTCDate();
+    date.setUTCDate(Math.min(day, lastDay) + sign * by.days);
+    return date;
+}
+
+function lastSegment(ref: string) {
+    return ref.slice(ref.lastIndexOf(".") + 1);
+}
+
+/** The column a date function is written directly over, whose name the value is answered under when nothing names it. */
+function dateColumnOf(term: Term) {
+    const direct = term.kind === "dateTrunc" || term.kind === "datePart";
+    return direct && term.of.kind === "ref" ? term.of.ref : undefined;
+}
+
+/** `DATE_TRUNC('month', x)`; over CURRENT_DATE it is the date it names. */
+function dateTruncTerm(unit: DatasetBucket, of: Term) {
+    if (of.kind !== "date") return { kind: "dateTrunc", unit, of } satisfies Term;
+    const at = new Date(Date.UTC(of.at.getUTCFullYear(), of.at.getUTCMonth(), of.at.getUTCDate()));
+    if (unit === "week") at.setUTCDate(at.getUTCDate() - ((at.getUTCDay() + 6) % 7));
+    if (unit === "month" || unit === "quarter" || unit === "year") at.setUTCDate(1);
+    if (unit === "quarter") at.setUTCMonth(Math.floor(at.getUTCMonth() / 3) * 3);
+    if (unit === "year") at.setUTCMonth(0);
+    return { kind: "date", at } satisfies Term;
+}
+
+/** `YEAR(x)`; over CURRENT_DATE it is the number it names, weeks counted the ISO way and Monday as weekday 1. */
+function datePartTerm(unit: DatasetDatePart, of: Term) {
+    if (of.kind !== "date") return { kind: "datePart", unit, of } satisfies Term;
+    const at = new Date(Date.UTC(of.at.getUTCFullYear(), of.at.getUTCMonth(), of.at.getUTCDate()));
+    const weekday = ((at.getUTCDay() + 6) % 7) + 1;
+    const thursday = new Date(at);
+    thursday.setUTCDate(at.getUTCDate() - weekday + 4);
+    const january = Date.UTC(thursday.getUTCFullYear(), 0, 1);
+    const week = Math.ceil(((thursday.getTime() - january) / 86_400_000 + 1) / 7);
+    const value = {
+        year: at.getUTCFullYear(),
+        quarter: Math.floor(at.getUTCMonth() / 3) + 1,
+        month: at.getUTCMonth() + 1,
+        week,
+        day: at.getUTCDate(),
+        dayOfWeek: weekday,
+    } satisfies Record<DatasetDatePart, number>;
+    return { kind: "num", value: value[unit] } satisfies Term;
+}
+
+class Parser {
+    private position = 0;
+
+    public constructor(
+        private readonly tokens: Token[],
+        private readonly now: Date,
+    ) {}
+
+    /** One SELECT, or the one derived-table shape accepted: `SELECT ... FROM (SELECT ..., RANK() OVER (...) AS rn FROM ...) WHERE rn <= n`. */
+    public statement() {
+        const items = this.selectHead();
+        const parsed = this.optionalPunct("(")
+            ? this.derivedTable(items)
+            : { items, ...this.body() };
+        if (parsed.items.some((item) => item.kind === "rankWindow")) {
+            throw new DatasetSqlError(WINDOW_PLACE);
+        }
+        this.optionalPunct(";");
+        this.end();
+        return parsed;
+    }
+
+    /** What follows a SELECT item that is not a comma or FROM names the shape that is not supported, instead of blaming FROM. */
+    private assertSelectEnded() {
+        const token = this.peek();
+        if (token.kind === "end" || this.peekWord("FROM")) return;
+        if (isConditionWord(token) || this.peekWord("NOT")) {
+            throw new DatasetSqlError(
+                "A condition in SELECT is written CASE WHEN condition THEN value ELSE value END AS name.",
+            );
+        }
+        const shown = token.kind === "string" ? `'${token.value}'` : String(token.value);
+        throw new DatasetSqlError(`Unexpected "${shown}" in SELECT.`);
+    }
+
+    /** `SELECT [DISTINCT] items FROM`: what precedes the dataset or the derived table. */
+    private selectHead() {
+        this.expectWord("SELECT", "A dataset query starts with SELECT.");
+        if (this.peekWord("DISTINCT")) throw new DatasetSqlError(REFUSED_CLAUSES.DISTINCT);
+        const items = this.selectList();
+        this.assertSelectEnded();
+        this.expectWord("FROM", "SELECT needs FROM <dataset>.");
+        return items;
+    }
+
+    /** `dataset [alias] JOIN ... WHERE ... GROUP BY ... HAVING ... QUALIFY ... ORDER BY ... LIMIT ... OFFSET ...`. */
+    private body() {
+        const from = this.identifier("FROM needs a dataset name.");
+        const alias = this.optionalAlias();
+        const joins = this.joins();
+        const filter = this.peekWord("WHERE") ? (this.take(), this.predicates()) : [];
+        const groupBy = this.groupBy();
+        const having = this.peekWord("HAVING") ? (this.take(), this.predicates()) : [];
+        const qualify = this.peekWord("QUALIFY") ? (this.take(), this.predicates()) : [];
+        return {
+            from,
+            aliases: alias === undefined ? [] : [alias],
+            joins,
+            filter,
+            groupBy,
+            having,
+            qualify,
+            ...this.tail(),
+        };
+    }
+
+    private tail() {
+        const sort = this.orderBy();
+        const limit = this.limit();
+        const offset = this.offset(sort.length > 0);
+        return { sort, limit, offset };
+    }
+
+    /**
+     * `(SELECT ..., RANK() OVER (...) AS rn FROM ...) [AS t] WHERE rn <= n`:
+     * the inner SELECT is the query, its window the rank, the outer list the
+     * values kept; ORDER BY and LIMIT belong to the outer SELECT.
+     */
+    private derivedTable(outer: SelectItem[]) {
+        const inner = this.selectHead();
+        const body = this.body();
+        this.expectPunct(")", "The derived table is not closed.");
+        const table = this.optionalAlias();
+        const windows = inner.filter((item) => item.kind === "rankWindow");
+        const window = windows[0];
+        if (!window || windows.length > 1) throw new DatasetSqlError(SUBQUERY);
+        if (body.sort.length || body.limit !== undefined || body.qualify.length) {
+            throw new DatasetSqlError(
+                "Put ORDER BY, LIMIT and QUALIFY on the outer SELECT; the derived table only adds RANK().",
+            );
+        }
+        const rn = window.alias;
+        if (rn === undefined) {
+            throw new DatasetSqlError(
+                "Name the RANK(): RANK() OVER (...) AS rn, then WHERE rn <= n outside.",
+            );
+        }
+        const filterOn = `Filter the derived table on ${rn}: WHERE ${rn} <= n.`;
+        this.expectWord("WHERE", filterOn);
+        if (unqualified(this.reference(filterOn), table) !== rn)
+            throw new DatasetSqlError(filterOn);
+        const limit = this.rankLimit(rn);
+        if (this.peekWord("AND")) {
+            throw new DatasetSqlError(
+                `Put other conditions in the inner WHERE; the outer one only keeps ${rn} <= n.`,
+            );
+        }
+        return {
+            ...body,
+            aliases: [...body.aliases, ...(table === undefined ? [] : [table])],
+            items: narrowed(inner, outer, table),
+            qualify: [
+                { kind: "rank", partitionBy: window.partitionBy, sort: window.sort, limit },
+            ] satisfies Predicate[],
+            ...this.tail(),
+        };
+    }
+
+    private selectList() {
+        const items: SelectItem[] = [];
+        do {
+            items.push(this.selectItem());
+        } while (this.optionalPunct(","));
+        return items;
+    }
+
+    private selectItem() {
+        if (this.optionalPunct("*")) return { kind: "star" } satisfies SelectItem;
+        if (this.peekRank()) {
+            const window = this.rankWindow(WINDOW_PLACE);
+            return {
+                kind: "rankWindow",
+                ...window,
+                alias: this.optionalAlias(),
+            } satisfies SelectItem;
+        }
+        const term = this.term(
+            "SELECT takes column names, `dataset.column`, aggregates, functions over them, CASE or arithmetic between aggregates.",
+        );
+        const alias = this.optionalAlias();
+        if (term.kind === "agg")
+            return { kind: "aggregate", ...term.item, alias } satisfies SelectItem;
+        if (term.kind === "ref")
+            return { kind: "column", ref: term.ref, alias } satisfies SelectItem;
+        const shown = describeTerm(term);
+        if (term.kind === "window") {
+            if (alias === undefined) {
+                throw new DatasetSqlError(`Give the window a name: ${shown} AS name.`);
+            }
+            return { kind: "window", item: term.item, alias } satisfies SelectItem;
+        }
+        const computed = hasAggregate(term) || hasWindow(term);
+        if (alias === undefined && computed) {
+            throw new DatasetSqlError(`Give the calculation a name: ${shown} AS share.`);
+        }
+        // A named literal or date (`CURRENT_DATE AS today`) is a constant column; bare arithmetic is not.
+        const constant = term.kind === "lit" || term.kind === "date";
+        if (!computed && !constant && termRefs(term).length === 0) {
+            throw new DatasetSqlError(`${shown} reads no data; SELECT columns or aggregates.`);
+        }
+        if (alias === undefined && dateColumnOf(term) === undefined) {
+            throw new DatasetSqlError(`Give the value a name: ${shown} AS name.`);
+        }
+        return { kind: "expr", term, alias } satisfies SelectItem;
+    }
+
+    /** `[INNER|LEFT [OUTER]] JOIN dataset [AS alias] ON a.x = b.y`, repeated; a bare JOIN is INNER. */
+    private joins() {
+        const joins: JoinClause[] = [];
+        for (;;) {
+            const inner = !this.peekWord("LEFT");
+            if (this.peekWord("INNER") || this.peekWord("LEFT")) {
+                this.take();
+                if (this.peekWord("OUTER")) this.take();
+                this.expectWord("JOIN", "INNER and LEFT are followed by JOIN.");
+            } else if (!this.peekWord("JOIN")) {
+                return joins;
+            } else {
+                this.take();
+            }
+            const dataset = this.identifier("JOIN needs a dataset name.");
+            const alias = this.optionalAlias();
+            this.expectWord("ON", "JOIN needs ON dataset.column = other.column.");
+            const left = this.reference("ON needs dataset.column = other.column.");
+            this.expectPunct("=", "ON compares two key columns with =.");
+            const right = this.reference("ON needs dataset.column = other.column.");
+            if (this.peekWord("AND")) {
+                throw new DatasetSqlError("ON takes one key pair; put other conditions in WHERE.");
+            }
+            joins.push({ dataset, alias, left, right, inner });
+        }
+    }
+
+    /** `COUNT(*)`, `FN(value)`, `COUNT(DISTINCT column)`, `FN(CASE WHEN ... THEN ... END)`, each with an optional `FILTER (WHERE ...)`. */
+    private aggregate() {
+        const word = this.take() as Token & { kind: "word" };
+        const base = AGGREGATE_WORDS[word.upper as keyof typeof AGGREGATE_WORDS];
+        this.expectPunct("(", `${word.upper} needs parentheses.`);
+        const argument = this.aggregateArgument(word.upper, base);
+        this.expectPunct(")", `${word.upper}(...) is not closed.`);
+        const filter = [...argument.filter, ...this.filterClause()];
+        return { fn: argument.fn, term: argument.term, filter } satisfies AggregateCall;
+    }
+
+    /** `OVER ([PARTITION BY a, b])` after an aggregate: the rows it is worked out over; an ORDER BY would make it a running total, which the wire has no form for. */
+    private over() {
+        this.take();
+        this.expectPunct("(", "OVER is followed by () or (PARTITION BY ...).");
+        let partitionBy: Term[] = [];
+        if (this.peekWord("PARTITION")) {
+            this.take();
+            this.expectWord("BY", "PARTITION is followed by BY.");
+            partitionBy = this.termList("PARTITION BY takes column names or aliases.");
+        }
+        if (this.peekWord("ORDER")) throw new DatasetSqlError(RUNNING_TOTAL);
+        this.expectPunct(")", "OVER (...) is not closed.");
+        return partitionBy;
+    }
+
+    private aggregateArgument(word: string, base: DatasetAggregate) {
+        if (this.optionalPunct("*")) {
+            if (base !== "count") {
+                throw new DatasetSqlError(`${word}(*) is not valid; name a column.`);
+            }
+            return { fn: base, term: undefined, filter: [] as Predicate[] };
+        }
+        const distinct = this.peekWord("DISTINCT") ? (this.take(), true) : false;
+        if (distinct && base !== "count") {
+            throw new DatasetSqlError(
+                `DISTINCT is only valid inside COUNT; ${word}(DISTINCT ...) is not.`,
+            );
+        }
+        const term = this.term(`${word}() takes a column, arithmetic or a function over columns.`);
+        const fn = distinct ? ("countDistinct" as const) : base;
+        if (term.kind === "num") {
+            if (fn === "count") return { fn, term: undefined, filter: [] as Predicate[] };
+            throw new DatasetSqlError(`${word}(${term.value}) has no meaning; name a column.`);
+        }
+        if (term.kind === "case") return conditional(word, fn, term);
+        return { fn, term, filter: [] as Predicate[] };
+    }
+
+    private filterClause() {
+        if (!this.peekWord("FILTER")) return [] as Predicate[];
+        this.take();
+        this.expectPunct("(", "FILTER is written FILTER (WHERE condition).");
+        this.expectWord("WHERE", "FILTER is written FILTER (WHERE condition).");
+        const filter = this.predicates();
+        this.expectPunct(")", "FILTER (WHERE ...) is not closed.");
+        return filter;
+    }
+
+    private peekRank() {
+        const token = this.peek();
+        return token.kind === "word" && RANK_WORDS.includes(token.upper) && this.peekPunct("(", 1);
+    }
+
+    /** `RANK() OVER (PARTITION BY a, b ORDER BY x DESC, y)`, the ranking the wire keeps: rows tied on every ORDER BY key share a rank. */
+    private rankWindow(message: string) {
+        const word = this.take();
+        if (word.kind !== "word" || !RANK_WORDS.includes(word.upper)) {
+            throw new DatasetSqlError(message);
+        }
+        if (word.upper !== "RANK") {
+            throw new DatasetSqlError(
+                `${word.upper}() is not supported; use RANK(): rows tied on every ORDER BY key share a rank, so RANK() <= n keeps a tie whole rather than cutting it at n rows.`,
+            );
+        }
+        this.expectPunct("(", "RANK() takes no argument.");
+        this.expectPunct(")", "RANK() takes no argument.");
+        const over = "RANK() needs OVER (PARTITION BY ... ORDER BY ...).";
+        this.expectWord("OVER", over);
+        this.expectPunct("(", over);
+        this.expectWord(
+            "PARTITION",
+            "RANK() needs PARTITION BY: ranking every row as one partition is not supported.",
+        );
+        this.expectWord("BY", "PARTITION is followed by BY.");
+        const partitionBy = this.termList("PARTITION BY takes column names or aliases.");
+        this.expectWord("ORDER", "RANK() OVER (...) needs ORDER BY to say which rows come first.");
+        this.expectWord("BY", "ORDER is followed by BY.");
+        const sort = this.sortList();
+        this.expectPunct(")", "OVER (...) is not closed.");
+        return { partitionBy, sort } satisfies RankWindow;
+    }
+
+    private termList(message: string) {
+        const items: Term[] = [];
+        do {
+            items.push(this.term(message));
+        } while (this.optionalPunct(","));
+        return items;
+    }
+
+    /** `<= n`, `< n` (keeps n - 1) or `= 1` after a rank: the ranks of each partition that stay, at most 100. */
+    private rankLimit(shown: string) {
+        const operator = this.take();
+        const count = this.take();
+        const n = count.kind === "number" && Number.isInteger(count.value) ? count.value : NaN;
+        const op = operator.kind === "punct" ? operator.value : "";
+        const limit = op === "<=" ? n : op === "<" ? n - 1 : op === "=" && n === 1 ? 1 : NaN;
+        if (!(limit >= 1)) {
+            throw new DatasetSqlError(
+                `${shown} <= n keeps the rows ranked 1 to n in each partition, ties included (= 1 the first); other comparisons are not supported.`,
+            );
+        }
+        if (limit > 100) {
+            throw new DatasetSqlError(
+                `${shown} keeps at most the first 100 ranks of each partition.`,
+            );
+        }
+        return limit;
+    }
+
+    private dateTrunc() {
+        this.take();
+        this.expectPunct("(", "DATE_TRUNC needs parentheses.");
+        const unit = unitOf(this.take(), DATASET_BUCKETS);
+        if (!unit) {
+            throw new DatasetSqlError(
+                `DATE_TRUNC takes a unit first: DATE_TRUNC('month', column); units are ${DATASET_BUCKETS.join(", ")}.`,
+            );
+        }
+        this.expectPunct(",", "DATE_TRUNC('unit', column) needs the column after the unit.");
+        const of = this.term("DATE_TRUNC needs a date column after the unit.");
+        this.expectPunct(")", "DATE_TRUNC(...) is not closed.");
+        return dateTruncTerm(unit, of);
+    }
+
+    /** `EXTRACT(YEAR FROM column)`, the standard spelling of YEAR(column). */
+    private extract() {
+        this.take();
+        this.expectPunct("(", "EXTRACT is written EXTRACT(part FROM column).");
+        const unit = unitOf(this.take(), DATASET_DATE_PARTS);
+        if (!unit) {
+            throw new DatasetSqlError(
+                `EXTRACT takes a part first: EXTRACT(YEAR FROM column); parts are ${Object.keys(DATE_PART_WORDS).join(", ")}.`,
+            );
+        }
+        this.expectWord("FROM", "EXTRACT is written EXTRACT(part FROM column).");
+        const of = this.term("EXTRACT needs a date column after FROM.");
+        this.expectPunct(")", "EXTRACT(...) is not closed.");
+        return datePartTerm(unit, of);
+    }
+
+    /** `INTERVAL '30 days'`: units are day(s), week(s), month(s) and year(s). */
+    private interval() {
+        this.take();
+        const spec = this.take();
+        const match =
+            spec.kind === "string"
+                ? /^(\d+)\s*(day|week|month|year)s?$/i.exec(spec.value.trim())
+                : null;
+        if (!match) {
+            throw new DatasetSqlError(
+                "INTERVAL takes 'n unit', with unit day(s), week(s), month(s) or year(s).",
+            );
+        }
+        const n = Number(match[1]);
+        const unit = match[2]!.toLowerCase();
+        return {
+            kind: "interval",
+            months: unit === "month" ? n : unit === "year" ? 12 * n : 0,
+            days: unit === "day" ? n : unit === "week" ? 7 * n : 0,
+        } satisfies Term;
+    }
+
+    /** `CASE WHEN p THEN v [WHEN ...] [ELSE v] END`; ELSE NULL is the same as no ELSE. */
+    /** `CASE WHEN p THEN v ... END`, or the simple form `CASE x WHEN v THEN r ... END` where each WHEN compares x with a value. */
+    private caseTerm() {
+        this.take();
+        const subject = this.peekWord("WHEN")
+            ? undefined
+            : this.term("CASE is followed by WHEN, or by a value to compare.");
+        const branches: { when: Predicate[]; then: Term }[] = [];
+        while (this.peekWord("WHEN")) {
+            this.take();
+            const when = subject ? [this.simpleCaseMatch(subject)] : this.predicates();
+            this.expectWord("THEN", "CASE WHEN condition needs THEN value.");
+            if (this.peekWord("NULL")) {
+                throw new DatasetSqlError(
+                    "THEN NULL is not supported; a division by zero is already null, so leave that branch out and keep the ELSE.",
+                );
+            }
+            branches.push({
+                when,
+                then: this.term("THEN takes a column, a literal or arithmetic."),
+            });
+        }
+        if (branches.length === 0) {
+            throw new DatasetSqlError(
+                "CASE is written CASE WHEN condition THEN value [ELSE value] END.",
+            );
+        }
+        let otherwise: Term | undefined;
+        if (this.peekWord("ELSE")) {
+            this.take();
+            if (this.peekWord("NULL")) this.take();
+            else otherwise = this.term("ELSE takes a column, a literal or arithmetic.");
+        }
+        this.expectWord("END", "CASE ... needs END.");
+        return {
+            kind: "case",
+            branches,
+            ...(otherwise === undefined ? {} : { else: otherwise }),
+        } satisfies Term;
+    }
+
+    /** `a AND b OR c AND (d OR e)`: AND binds tighter than OR; the result is an AND list whose OR parts are `any` groups. */
+    // eslint-disable-next-line m6d/no-explicit-return-type -- mutually recursive with predicate through parenthesized groups
+    private predicates(): Predicate[] {
+        const branches = [this.conjunction()];
+        while (this.peekWord("OR")) {
+            this.take();
+            branches.push(this.conjunction());
+        }
+        if (branches.length === 1) return branches[0]!;
+        return [{ kind: "any", of: branches.map((branch) => grouped(branch)) }];
+    }
+
+    private conjunction() {
+        const predicates: Predicate[] = [];
+        do {
+            predicates.push(this.predicate());
+        } while (this.peekWord("AND") && this.take());
+        return predicates;
+    }
+
+    /** `NOT p`, `(p AND q)`, `RANK() OVER (...) <= n` or a condition. */
+    private predicate(): Predicate {
+        if (this.peekWord("NOT")) {
+            this.take();
+            return { kind: "not", of: this.predicate() };
+        }
+        if (this.peekRank()) {
+            const window = this.rankWindow(WINDOW_PLACE);
+            return { kind: "rank", ...window, limit: this.rankLimit("RANK()") };
+        }
+        if (this.peekPunct("(") && this.parenthesizedPredicate()) {
+            this.take();
+            const inner = this.predicates();
+            this.expectPunct(")", "A parenthesized condition is not closed.");
+            return grouped(inner);
+        }
+        return this.condition();
+    }
+
+    /** After `(`: a condition group if a comparison or AND/OR/NOT appears at depth one (outside any CASE) before the matching `)`, else a value. */
+    private parenthesizedPredicate() {
+        let depth = 0;
+        let inCase = 0;
+        for (let offset = 0; ; offset += 1) {
+            const token = this.peek(offset);
+            if (token.kind === "end") return false;
+            depth += nesting(token, "(", ")");
+            if (depth === 0) return false;
+            inCase += nesting(token, "CASE", "END");
+            if (depth === 1 && inCase === 0 && isConditionWord(token)) return true;
+        }
+    }
+
+    private condition() {
+        const left = this.term("A condition starts with a column name.");
+        const shown = describeTerm(left);
+        if (this.peekWord("IS")) return this.nullCheck(left);
+        const negated = this.peekWord("NOT") ? (this.take(), true) : false;
+        if (this.peekWord("IN")) return this.inList(left, negated);
+        let condition: Predicate;
+        if (this.peekWord("BETWEEN")) condition = this.between(left);
+        else if (this.peekWord("LIKE")) condition = this.like(left, shown);
+        else if (negated) {
+            throw new DatasetSqlError(
+                `NOT before a comparison goes first (NOT ${shown} > 5); after a value it is NOT IN, NOT LIKE or NOT BETWEEN.`,
+            );
+        } else condition = this.comparison(left, shown);
+        return negated ? ({ kind: "not", of: condition } satisfies Predicate) : condition;
+    }
+
+    /** Whether the condition ends here: the statement, a closing parenthesis, or the next clause or connective. */
+    private endsCondition() {
+        const token = this.peek();
+        if (token.kind === "end") return true;
+        if (token.kind === "punct") return token.value === ")";
+        return (
+            token.kind === "word" &&
+            [
+                "AND",
+                "OR",
+                "THEN",
+                "GROUP",
+                "HAVING",
+                "ORDER",
+                "LIMIT",
+                "OFFSET",
+                "QUALIFY",
+            ].includes(token.upper)
+        );
+    }
+
+    /** One `WHEN v` of a simple CASE: the subject compared with the value, a literal or a term. */
+    private simpleCaseMatch(subject: Term) {
+        const token = this.peek();
+        if (token.kind === "string" || token.kind === "number") {
+            this.take();
+            return { kind: "cond", left: subject, op: "=", value: token.value } satisfies Predicate;
+        }
+        const value = this.term("WHEN takes a value to compare with.");
+        return {
+            kind: "cond",
+            left: subject,
+            op: "=",
+            value: { term: value },
+        } satisfies Predicate;
+    }
+
+    private nullCheck(left: Term) {
+        this.take();
+        const negated = this.peekWord("NOT") ? (this.take(), true) : false;
+        this.expectWord("NULL", "IS is followed by NULL or NOT NULL.");
+        return { kind: "cond", left, op: negated ? "isNotNull" : "isNull" } satisfies Predicate;
+    }
+
+    private inList(left: Term, negated: boolean) {
+        this.take();
+        this.expectPunct("(", "IN needs a list in parentheses.");
+        if (this.peekWord("SELECT")) throw new DatasetSqlError(SUBQUERY);
+        const values: Literal[] = [];
+        do {
+            values.push(this.literal("IN takes literal values."));
+        } while (this.optionalPunct(","));
+        this.expectPunct(")", "IN (...) is not closed.");
+        return {
+            kind: "cond",
+            left,
+            op: negated ? "notIn" : "in",
+            value: values,
+        } satisfies Predicate;
+    }
+
+    private between(left: Term) {
+        this.take();
+        const low = this.literal("BETWEEN takes two literal values.");
+        this.expectWord("AND", "BETWEEN low AND high.");
+        const high = this.literal("BETWEEN takes two literal values.");
+        return { kind: "cond", left, op: "between", value: [low, high] } satisfies Predicate;
+    }
+
+    private like(left: Term, shown: string) {
+        this.take();
+        const pattern = this.take();
+        if (pattern.kind !== "string") throw new DatasetSqlError("LIKE takes a string pattern.");
+        return { kind: "cond", left, ...likeFilter(shown, pattern.value) } satisfies Predicate;
+    }
+
+    /** `left op right`, where the right side is a literal, or a column or arithmetic (`a < target`, `a > 0.9 * target`). */
+    private comparison(left: Term, shown: string) {
+        // A bare column stands for `column = TRUE`, as SQL reads a boolean on its own.
+        if (left.kind === "ref" && this.endsCondition()) {
+            return { kind: "cond", left, op: "=", value: true } satisfies Predicate;
+        }
+        const operator = this.take();
+        if (
+            operator.kind !== "punct" ||
+            !["=", "!=", "<>", "<", "<=", ">", ">="].includes(operator.value)
+        ) {
+            throw new DatasetSqlError(
+                `"${shown}" needs a comparison: = != < <= > >= IN BETWEEN LIKE IS NULL.`,
+            );
+        }
+        const op = (operator.value === "<>" ? "!=" : operator.value) as DatasetFilterOp;
+        if (this.startsTerm()) {
+            return { kind: "cond", left, op, value: { term: this.term("") } } satisfies Predicate;
+        }
+        const value = this.literal(`"${shown} ${operator.value}" needs a value on the right.`);
+        return { kind: "cond", left, op, value } satisfies Predicate;
+    }
+
+    /** Whether the next tokens are a value expression rather than a literal: a name, `(`, CASE, or a number followed by an operator. */
+    private startsTerm() {
+        const token = this.peek();
+        if (this.peekPunct("(") || this.peekWord("CASE")) return true;
+        if (!isName(token))
+            return (
+                token.kind === "number" &&
+                ARITHMETIC.some((operator) => this.peekPunct(operator, 1))
+            );
+        const typedLiteral =
+            ["DATE", "TIMESTAMP"].includes(token.upper) && this.peek(1).kind === "string";
+        return !["TRUE", "FALSE"].includes(token.upper) && !typedLiteral;
+    }
+
+    /** `a + b * (c - 1)`: `*` and `/` bind before `+` and `-`; a date plus or minus an INTERVAL folds to the date it names. */
+    // eslint-disable-next-line m6d/no-explicit-return-type -- mutually recursive with factor and unit
+    private term(message: string): Term {
+        let left = this.factor(message);
+        while (this.peekPunct("+") || this.peekPunct("-")) {
+            const op = (this.take() as Token & { kind: "punct" }).value as DatasetArithmeticOp;
+            const right = this.factor(message);
+            const folds = left.kind === "date" && right.kind === "interval";
+            if (!folds && (left.kind === "date" || right.kind === "date")) {
+                throw new DatasetSqlError(
+                    "Arithmetic on CURRENT_DATE takes an INTERVAL: CURRENT_DATE - INTERVAL '7 days'.",
+                );
+            }
+            left =
+                left.kind === "date" && right.kind === "interval"
+                    ? { kind: "date", at: shifted(left.at, op === "-" ? -1 : 1, right) }
+                    : { kind: "arith", op, left, right };
+        }
+        return left;
+    }
+
+    private factor(message: string) {
+        let left = this.unit(message);
+        while (this.peekPunct("*") || this.peekPunct("/")) {
+            const op = (this.take() as Token & { kind: "punct" }).value as DatasetArithmeticOp;
+            left = { kind: "arith", op, left, right: this.unit(message) };
+        }
+        return left;
+    }
+
+    private unit(message: string) {
+        const token = this.peek();
+        if (token.kind === "number" || token.kind === "string") {
+            this.take();
+            return token.kind === "number"
+                ? ({ kind: "num", value: token.value } satisfies Term)
+                : ({ kind: "lit", value: token.value } satisfies Term);
+        }
+        const next = this.peek(1);
+        if (this.peekPunct("(") && next.kind === "word" && next.upper === "SELECT") {
+            throw new DatasetSqlError(SUBQUERY);
+        }
+        if (this.optionalPunct("(")) {
+            const inner = this.term(message);
+            this.expectPunct(")", "A parenthesis is not closed.");
+            return inner;
+        }
+        return (
+            (token.kind === "word" ? this.wordUnit(token) : undefined) ??
+            ({ kind: "ref", ref: this.reference(message) } satisfies Term)
+        );
+    }
+
+    /** A word that starts a value other than a column: a boolean, CASE, INTERVAL, the current date, or a call. */
+    private wordUnit(token: Token & { kind: "word" }) {
+        switch (token.upper) {
+            case "TRUE":
+            case "FALSE":
+                this.take();
+                return { kind: "lit", value: token.upper === "TRUE" } satisfies Term;
+            case "CASE":
+                return this.caseTerm();
+            case "INTERVAL":
+                return this.interval();
+            case "CURRENT_DATE":
+            case "CURRENT_TIMESTAMP":
+                this.take();
+                if (this.optionalPunct("("))
+                    this.expectPunct(")", `${token.upper}() takes no value.`);
+                return { kind: "date", at: this.now } satisfies Term;
+            default:
+                return this.peekPunct("(", 1) ? this.call(token) : undefined;
+        }
+    }
+
+    /** `NAME(`: an aggregate, a date function, a scalar function, NOW(), or a refusal naming what exists. */
+    private call(word: Token & { kind: "word" }) {
+        const { upper } = word;
+        if (upper in AGGREGATE_WORDS) {
+            const item = this.aggregate();
+            if (!this.peekWord("OVER")) return { kind: "agg", item } satisfies Term;
+            return { kind: "window", item: { ...item, partitionBy: this.over() } } satisfies Term;
+        }
+        if (upper === "DATE_TRUNC") return this.dateTrunc();
+        if (upper === "EXTRACT") return this.extract();
+        if (upper === "NOW") {
+            this.take();
+            this.expectPunct("(", "NOW takes no argument: NOW().");
+            this.expectPunct(")", "NOW takes no argument: NOW().");
+            return { kind: "date", at: this.now } satisfies Term;
+        }
+        if (upper in DATE_PART_WORDS) {
+            this.take();
+            this.take();
+            const of = this.term(`${upper} needs a date column: ${upper}(column).`);
+            this.expectPunct(")", `${upper}(...) is not closed.`);
+            return datePartTerm(DATE_PART_WORDS[upper as keyof typeof DATE_PART_WORDS], of);
+        }
+        if (upper in FUNCTION_WORDS) {
+            this.take();
+            this.take();
+            const args: Term[] = [];
+            do {
+                args.push(this.term(`${upper}() takes columns, literals or arithmetic.`));
+            } while (this.optionalPunct(","));
+            this.expectPunct(")", `${upper}(...) is not closed.`);
+            const fn = FUNCTION_WORDS[upper as keyof typeof FUNCTION_WORDS];
+            return { kind: "fn", fn, args } satisfies Term;
+        }
+        if (upper === "CAST") {
+            throw new DatasetSqlError(
+                "CAST is not needed: division is already exact; drop the cast.",
+            );
+        }
+        if (RANK_WORDS.includes(upper)) throw new DatasetSqlError(WINDOW_PLACE);
+        if (word.upper === "NULLIF") {
+            throw new DatasetSqlError(
+                "NULLIF() is not needed: a division by zero is already null, so write a / b.",
+            );
+        }
+        throw new DatasetSqlError(`${word.value}() is not available. Functions: ${FUNCTIONS}.`);
+    }
+
+    private groupBy() {
+        if (!this.peekWord("GROUP")) return [] as Term[];
+        this.take();
+        this.expectWord("BY", "GROUP is followed by BY.");
+        const items: Term[] = [];
+        do {
+            const term = this.term(
+                "GROUP BY takes column names, select aliases or values such as DATE_TRUNC('unit', column).",
+            );
+            if (term.kind === "num") {
+                throw new DatasetSqlError("GROUP BY names columns or aliases, not positions.");
+            }
+            items.push(term);
+        } while (this.optionalPunct(","));
+        return items;
+    }
+
+    private orderBy() {
+        if (!this.peekWord("ORDER")) return [] as SortList;
+        this.take();
+        this.expectWord("BY", "ORDER is followed by BY.");
+        return this.sortList();
+    }
+
+    private sortList() {
+        const items: SortList = [];
+        do {
+            const term = this.term("ORDER BY takes a column, an alias or an aggregate.");
+            if (term.kind === "num") {
+                throw new DatasetSqlError("ORDER BY names columns or aliases, not positions.");
+            }
+            const dir = this.peekWord("DESC")
+                ? (this.take(), "desc" as const)
+                : (this.peekWord("ASC") && this.take(), "asc" as const);
+            items.push({ term, dir });
+        } while (this.optionalPunct(","));
+        return items;
+    }
+
+    private limit() {
+        if (!this.peekWord("LIMIT")) return undefined;
+        this.take();
+        const count = this.take();
+        if (count.kind !== "number" || !Number.isInteger(count.value) || count.value < 1) {
+            throw new DatasetSqlError("LIMIT takes a positive whole number.");
+        }
+        return count.value;
+    }
+
+    private offset(sorted: boolean) {
+        if (!this.peekWord("OFFSET")) return undefined;
+        this.take();
+        const count = this.take();
+        if (count.kind !== "number" || !Number.isInteger(count.value) || count.value < 0) {
+            throw new DatasetSqlError("OFFSET takes a whole number.");
+        }
+        if (!sorted) {
+            throw new DatasetSqlError(
+                "OFFSET needs ORDER BY; without one the rows have no order to skip in.",
+            );
+        }
+        return count.value;
+    }
+
+    /** `a.b` as one reference; a bare keyword in reference position gets the caller's message. */
+    private reference(message: string) {
+        const token = this.peek();
+        if (!isName(token)) throw new DatasetSqlError(message);
+        this.take();
+        let ref = token.value;
+        while (this.peekPunct(".")) {
+            this.take();
+            const next = this.take();
+            if (next.kind !== "word")
+                throw new DatasetSqlError(`"${ref}." needs a column name after the dot.`);
+            ref = `${ref}.${next.value}`;
+        }
+        return ref;
+    }
+
+    private identifier(message: string) {
+        const token = this.take();
+        if (!isName(token)) throw new DatasetSqlError(message);
+        return token.value;
+    }
+
+    /** A string, number or boolean; `DATE '...'` and `TIMESTAMP '...'` are the string they wrap, CURRENT_DATE and NOW() the date they fold to. */
+    private literal(message: string) {
+        if (NOW_WORDS.some((word) => this.peekWord(word))) {
+            const term = this.term(message);
+            if (term.kind !== "date") throw new DatasetSqlError(message);
+            return isoDate(term.at);
+        }
+        const token = this.take();
+        if (token.kind === "word" && ["DATE", "TIMESTAMP"].includes(token.upper)) {
+            const wrapped = this.take();
+            if (wrapped.kind !== "string") {
+                throw new DatasetSqlError(
+                    `${token.upper} takes a quoted value: ${token.upper} '2026-01-01'.`,
+                );
+            }
+            return wrapped.value;
+        }
+        if (token.kind === "string") return token.value;
+        if (token.kind === "number") return token.value;
+        if (token.kind === "word" && (token.upper === "TRUE" || token.upper === "FALSE"))
+            return token.upper === "TRUE";
+        if (token.kind === "word" && token.upper === "NULL") {
+            throw new DatasetSqlError("Compare with NULL using IS NULL or IS NOT NULL.");
+        }
+        throw new DatasetSqlError(message);
+    }
+
+    private optionalAlias() {
+        if (this.peekWord("AS")) {
+            this.take();
+            return this.identifier("AS needs a name.");
+        }
+        const token = this.peek();
+        if (!isName(token)) return undefined;
+        this.take();
+        return token.value;
+    }
+
+    private end() {
+        const token = this.peek();
+        if (token.kind === "end") return;
+        if (token.kind === "word" && token.upper in REFUSED_CLAUSES) {
+            throw new DatasetSqlError(REFUSED_CLAUSES[token.upper as keyof typeof REFUSED_CLAUSES]);
+        }
+        const shown = token.kind === "punct" ? token.value : String(token.value);
+        throw new DatasetSqlError(`Unexpected "${shown}" after the statement.`);
+    }
+
+    private peek(offset = 0) {
+        return this.tokens[this.position + offset] ?? { kind: "end" };
+    }
+    private take() {
+        const token = this.peek();
+        this.position += 1;
+        return token;
+    }
+    private peekWord(upper: string) {
+        const token = this.peek();
+        return token.kind === "word" && token.upper === upper;
+    }
+    private peekPunct(value: string, offset = 0) {
+        const token = this.peek(offset);
+        return token.kind === "punct" && token.value === value;
+    }
+    private optionalPunct(value: string) {
+        if (!this.peekPunct(value)) return false;
+        this.take();
+        return true;
+    }
+    private expectWord(upper: string, message: string) {
+        if (!this.peekWord(upper)) {
+            const token = this.peek();
+            if (token.kind === "word" && token.upper in REFUSED_CLAUSES) {
+                throw new DatasetSqlError(
+                    REFUSED_CLAUSES[token.upper as keyof typeof REFUSED_CLAUSES],
+                );
+            }
+            throw new DatasetSqlError(message);
+        }
+        this.take();
+    }
+    private expectPunct(value: string, message: string) {
+        if (!this.optionalPunct(value)) throw new DatasetSqlError(message);
+    }
+}
+
+const ARITHMETIC = ["+", "-", "*", "/"];
+
+/** `'%x%'` contains, `'x%'` starts with, `'%x'` ends with, `'x'` equals; a wildcard inside the text has no wire operator. */
+function likeFilter(shown: string, pattern: string) {
+    const inner = pattern.replace(/^%/, "").replace(/%$/, "");
+    if (inner.includes("%") || inner.includes("_")) {
+        throw new DatasetSqlError(
+            `LIKE supports '%text%' (contains), 'text%' (starts with) and '%text' (ends with); "${shown} LIKE '${pattern}'" is none of those.`,
+        );
+    }
+    const starts = pattern.startsWith("%");
+    const ends = pattern.endsWith("%");
+    const op = starts && ends ? "contains" : ends ? "startsWith" : starts ? "endsWith" : "=";
+    return { op, value: inner } satisfies Pick<DatasetCondition, "op" | "value">;
+}
+
+const COMPARISONS = ["=", "!=", "<>", "<", "<=", ">", ">="];
+const CONDITION_WORDS = ["AND", "OR", "NOT", "IN", "IS", "LIKE", "BETWEEN"];
+
+/** A token that can only appear inside a condition, never inside a value. */
+/** +1 on the opener, -1 on the closer, 0 otherwise; punctuation and words alike. */
+function nesting(token: Token, open: string, close: string) {
+    const text = token.kind === "word" ? token.upper : token.kind === "punct" ? token.value : "";
+    return text === open ? 1 : text === close ? -1 : 0;
+}
+
+function isConditionWord(token: Token) {
+    if (token.kind === "punct") return COMPARISONS.includes(token.value);
+    return token.kind === "word" && CONDITION_WORDS.includes(token.upper);
+}
+
+/** One predicate for a list: itself when alone, else an `all` group. */
+function grouped(predicates: Predicate[]) {
+    if (predicates.length === 1) return predicates[0]!;
+    return { kind: "all", of: predicates } satisfies Predicate;
+}
+
+/**
+ * `SUM(CASE WHEN p THEN 1 ELSE 0 END)` counts the rows p holds for and
+ * `AVG(CASE WHEN p THEN total END)` averages them: one branch whose ELSE
+ * changes nothing is the aggregate filtered by p. Any other CASE is
+ * aggregated as the value it is. COUNT counts every non-null answer, so a
+ * COUNT over a CASE with an ELSE would count the other rows too.
+ */
+function conditional(word: string, fn: DatasetAggregate, term: Term & { kind: "case" }) {
+    if (fn === "count" && term.else !== undefined) {
+        throw new DatasetSqlError(
+            `ELSE would count the other rows into ${word}(); drop the ELSE, or write ${word}(...) FILTER (WHERE condition).`,
+        );
+    }
+    const plain = { fn, term, filter: [] as Predicate[] };
+    const elseZero = term.else?.kind === "num" && term.else.value === 0;
+    const harmlessElse = term.else === undefined || (elseZero && fn === "sum");
+    const [branch] = term.branches;
+    if (branch === undefined || term.branches.length !== 1 || !harmlessElse) return plain;
+    const { then } = branch;
+    const counting =
+        (then.kind === "num" && then.value === 1) || (then.kind === "lit" && then.value === true);
+    if (counting) {
+        return fn === "count" || fn === "sum"
+            ? { fn: "count" as const, term: undefined, filter: branch.when }
+            : plain;
+    }
+    if (then.kind === "num") return plain;
+    return { fn, term: then, filter: branch.when };
+}
+
+function unqualified(ref: string, table: string | undefined) {
+    return table !== undefined && ref.startsWith(`${table}.`) ? ref.slice(table.length + 1) : ref;
+}
+
+/** The outer list of a derived table: `*` keeps every inner value, names keep those; the RANK() itself is never answered. */
+function narrowed(inner: SelectItem[], outer: SelectItem[], table: string | undefined) {
+    const values = inner.filter((item) => item.kind !== "rankWindow");
+    if (outer.some((item) => item.kind === "star")) return values;
+    const windowNames = inner.flatMap((item) => (item.kind === "rankWindow" ? [item.alias] : []));
+    const kept = outer.flatMap((item) => {
+        const name =
+            item.kind === "column" && item.alias === undefined
+                ? unqualified(item.ref, table)
+                : undefined;
+        if (name !== undefined && windowNames.includes(name)) return [];
+        const found =
+            name === undefined ? undefined : values.find((value) => namesOf(value).includes(name));
+        if (!found) {
+            throw new DatasetSqlError(
+                "The outer SELECT of a derived table lists names the inner SELECT answers, or *.",
+            );
+        }
+        return [found];
+    });
+    const unnamed = values.flatMap((value) =>
+        (value.kind === "aggregate" || value.kind === "window") && !kept.includes(value)
+            ? [{ ...value, hidden: true as const }]
+            : [],
+    );
+    return [...kept, ...unnamed];
+}
+
+function namesOf(item: SelectItem) {
+    if (item.kind === "star" || item.kind === "rankWindow") return [];
+    if (item.alias !== undefined) return [item.alias];
+    return item.kind === "column" ? [item.ref, lastSegment(item.ref)] : [];
+}
+
+/** Every column reference a term names, in order, conditions inside a CASE included. */
+function termRefs(term: Term): string[] {
+    switch (term.kind) {
+        case "ref":
+            return [term.ref];
+        case "num":
+        case "lit":
+        case "date":
+        case "interval":
+        case "agg":
+        case "window":
+            return [];
+        case "arith":
+            return [...termRefs(term.left), ...termRefs(term.right)];
+        case "dateTrunc":
+        case "datePart":
+            return termRefs(term.of);
+        case "fn":
+            return term.args.flatMap(termRefs);
+        case "case":
+            return [
+                ...term.branches.flatMap((branch) => [
+                    ...branch.when.flatMap(predicateRefs),
+                    ...termRefs(branch.then),
+                ]),
+                ...(term.else === undefined ? [] : termRefs(term.else)),
+            ];
+    }
+}
+
+function predicateRefs(predicate: Predicate): string[] {
+    if (predicate.kind === "rank") return [];
+    if (predicate.kind === "not") return predicateRefs(predicate.of);
+    if (predicate.kind !== "cond") return predicate.of.flatMap(predicateRefs);
+    const right = isTermValue(predicate.value) ? termRefs(predicate.value.term) : [];
+    return [...termRefs(predicate.left), ...right];
+}
+
+function isTermValue(
+    value: Extract<Predicate, { kind: "cond" }>["value"],
+): value is { term: Term } {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Whether the term, or any value inside it (a window's operand and conditions included), passes `test`. */
+function termHas(term: Term, test: (term: Term) => boolean): boolean {
+    if (test(term)) return true;
+    const has = (inner: Term) => termHas(inner, test);
+    switch (term.kind) {
+        case "arith":
+            return has(term.left) || has(term.right);
+        case "dateTrunc":
+        case "datePart":
+            return has(term.of);
+        case "fn":
+            return term.args.some(has);
+        case "case":
+            return (
+                term.branches.some(
+                    (branch) => has(branch.then) || branch.when.some((p) => predicateHas(p, test)),
+                ) ||
+                (term.else !== undefined && has(term.else))
+            );
+        case "window":
+            return (
+                (term.item.term !== undefined && has(term.item.term)) ||
+                term.item.filter.some((p) => predicateHas(p, test)) ||
+                term.item.partitionBy.some(has)
+            );
+        default:
+            return false;
+    }
+}
+
+function predicateHas(predicate: Predicate, test: (term: Term) => boolean): boolean {
+    if (predicate.kind === "rank") return false;
+    if (predicate.kind === "not") return predicateHas(predicate.of, test);
+    if (predicate.kind !== "cond") return predicate.of.some((p) => predicateHas(p, test));
+    return (
+        termHas(predicate.left, test) ||
+        (isTermValue(predicate.value) && termHas(predicate.value.term, test))
+    );
+}
+
+function isAggregateCall(term: Term) {
+    return term.kind === "agg";
+}
+
+/** An aggregate call anywhere in the term, a window's operand included: what makes the query a grouped one. */
+function hasAggregate(term: Term) {
+    return termHas(term, isAggregateCall);
+}
+
+function hasWindow(term: Term) {
+    return termHas(term, (inner) => inner.kind === "window");
+}
+
+/** A term as written, for messages. */
+function describeTerm(term: Term): string {
+    switch (term.kind) {
+        case "ref":
+            return term.ref;
+        case "num":
+            return String(term.value);
+        case "lit":
+            return typeof term.value === "string"
+                ? `'${term.value}'`
+                : String(term.value).toUpperCase();
+        case "date":
+            return `'${isoDate(term.at)}'`;
+        case "interval":
+            return "INTERVAL";
+        case "agg":
+            return `${term.item.fn.toUpperCase()}(${term.item.term ? describeTerm(term.item.term) : "*"})`;
+        case "window": {
+            const { partitionBy } = term.item;
+            const over = partitionBy.length
+                ? `PARTITION BY ${partitionBy.map(describeTerm).join(", ")}`
+                : "";
+            return `${describeTerm({ kind: "agg", item: term.item })} OVER (${over})`;
+        }
+        case "arith":
+            return `${describeTerm(term.left)} ${term.op} ${describeTerm(term.right)}`;
+        case "dateTrunc":
+            return `DATE_TRUNC('${term.unit}', ${describeTerm(term.of)})`;
+        case "datePart":
+            return `${term.unit.toUpperCase()}(${describeTerm(term.of)})`;
+        case "fn":
+            return `${term.fn.toUpperCase()}(${term.args.map(describeTerm).join(", ")})`;
+        case "case":
+            return "CASE ... END";
+    }
+}
+/**
+ * The JOIN clause(s) that reach a relation, as `describeDataset` prints them
+ * and refusals suggest them. Hosts always join left, so that is what is
+ * printed. `alias` names the target when the dataset joins it more than once.
+ */
+export function datasetJoinSql(from: string, relation: DatasetRelation, alias?: string) {
+    const { through } = relation;
+    const target = alias ?? relation.dataset;
+    const as = alias ? ` AS ${alias}` : "";
+    if (!through) {
+        return `LEFT JOIN ${relation.dataset}${as} ON ${from}.${relation.on[0]} = ${target}.${relation.on[1]}`;
+    }
+    return [
+        `LEFT JOIN ${through.dataset} ON ${from}.${relation.on[0]} = ${through.dataset}.${relation.on[1]}`,
+        `LEFT JOIN ${relation.dataset}${as} ON ${through.dataset}.${through.on[0]} = ${target}.${through.on[1]}`,
+    ].join(" ");
+}
+
+/** Every join a dataset declares, one line each; a target reached by two relations is aliased by the relation name so both can appear in one statement. */
+export function datasetJoinLines(definition: DatasetDefinition) {
+    const relations = Object.entries(definition.relations);
+    const targets = relations.map(([, r]) => r.dataset);
+    return relations.map(([name, relation]) => {
+        const repeated = targets.filter((t) => t === relation.dataset).length > 1;
+        return datasetJoinSql(definition.name, relation, repeated ? name : undefined);
+    });
+}
+
+/** A name that is no dataset; a link table of a many-to-many says which datasets to start from instead. */
+function unknownDataset(catalog: DatasetCatalog, name: string) {
+    for (const definition of catalog.values()) {
+        for (const relation of Object.values(definition.relations)) {
+            if (relation.through?.dataset === name) {
+                return `"${name}" is the link table between "${definition.name}" and "${relation.dataset}"; start FROM one of those.`;
+            }
+        }
+    }
+    return `Unknown dataset "${name}".`;
+}
+
+/** A dataset the statement reads, under the relation path the wire query reaches it by (empty for FROM). */
+type Source = { path: string; dataset: DatasetDefinition };
+/** The link table of a many-to-many, joined but not readable; the next JOIN to the relation's target completes it. */
+type Link = {
+    from: Source;
+    relationName: string;
+    relation: DatasetRelation;
+    completed?: true;
+    /** Joined with JOIN or INNER JOIN; the JOIN completing it must be the same kind. */
+    inner: boolean;
+};
+
+function isLink(entry: Source | Link): entry is Link {
+    return "relation" in entry;
+}
+
+/** The two sides of `a.x = b.y` as [qualifier, column]. */
+function keyOf(ref: string) {
+    const parts = ref.split(".");
+    if (parts.length !== 2) {
+        throw new DatasetSqlError(`ON needs dataset.column on both sides; "${ref}" is not that.`);
+    }
+    return parts as [string, string];
+}
+
+/**
+ * The datasets a statement names and how each is reached: FROM is the
+ * root, every JOIN is matched to a relation the parent declares by its
+ * target and ON keys. Qualifiers are dataset names or aliases; a dataset
+ * joined twice is only reachable through its aliases.
+ */
+class Sources {
+    private readonly byName = new Map<string, Source | Link | "ambiguous">();
+    private readonly root: Source;
+    /** Relation paths the wire query joins, in JOIN order. */
+    public readonly paths: string[] = [];
+    /**
+     * What each INNER JOIN adds to WHERE. The wire joins keep rows without a
+     * match, whose joined key is null; a matched row's key never is, so
+     * requiring it drops exactly the rows an inner join would.
+     */
+    public readonly matched: DatasetCondition[] = [];
+
+    public constructor(
+        private readonly catalog: DatasetCatalog,
+        from: string,
+        aliases: string[],
+    ) {
+        const dataset = catalog.get(from);
+        if (!dataset) throw new DatasetSqlError(unknownDataset(catalog, from));
+        this.root = { path: "", dataset };
+        for (const name of [from, ...aliases]) this.name(name, this.root);
+    }
+
+    /** An aliased JOIN is known by its alias only, as in SQL, so `JOIN employees m` leaves `employees` pointing at FROM. */
+    public join({ dataset, alias, left, right, inner }: JoinClause) {
+        const [leftQualifier, leftColumn] = keyOf(left);
+        const [rightQualifier, rightColumn] = keyOf(right);
+        const own = alias ?? dataset;
+        const isNew = (qualifier: string) => qualifier === own;
+        if (!isNew(leftQualifier) && !isNew(rightQualifier)) {
+            throw new DatasetSqlError(
+                `JOIN ${dataset} ... ON must compare a column of ${own} with a column of a dataset already in the query.`,
+            );
+        }
+        const [parentQualifier, parentKey, targetKey] = isNew(rightQualifier)
+            ? [leftQualifier, leftColumn, rightColumn]
+            : [rightQualifier, rightColumn, leftColumn];
+        const parent = this.byName.get(parentQualifier);
+        if (parent === undefined || parent === "ambiguous") {
+            throw new DatasetSqlError(
+                `"${parentQualifier}" is not in the query before JOIN ${dataset}.`,
+            );
+        }
+        const source = isLink(parent)
+            ? this.completeLink(parent, dataset, parentKey, targetKey)
+            : this.joinTo(parent, dataset, parentKey, targetKey, inner);
+        // A link table and its target are one hop on the wire, which cannot keep a row whose link matched but whose target did not: the link's columns are never read.
+        if (isLink(parent) && parent.inner !== inner) {
+            throw new DatasetSqlError(
+                `JOIN ${parent.relation.through!.dataset} and JOIN ${dataset} are one many-to-many join: write both as JOIN or both as LEFT JOIN.`,
+            );
+        }
+        this.name(own, source);
+        if ("path" in source && inner) {
+            this.matched.push({ col: `${source.path}.${targetKey}`, op: "isNotNull" });
+        }
+    }
+
+    /** A link table joined without the JOIN to its target is a join to nothing; say what completes it. */
+    public assertComplete() {
+        for (const [qualifier, entry] of this.byName) {
+            if (entry === "ambiguous" || !isLink(entry) || entry.completed) continue;
+            throw new DatasetSqlError(
+                `"${qualifier}" is only the link to "${entry.relation.dataset}"; write ${datasetJoinSql(entry.from.dataset.name, entry.relation)}.`,
+            );
+        }
+    }
+
+    /** `qualifier.column` as the wire reference `relationPath.column`; a bare column is looked up on FROM first, then on the joined datasets. */
+    public resolve(ref: string) {
+        const dot = ref.indexOf(".");
+        if (dot === -1) return this.bareColumn(ref);
+        const qualifier = ref.slice(0, dot);
+        const column = ref.slice(dot + 1);
+        if (column.includes(".")) {
+            throw new DatasetSqlError(
+                `"${ref}": write one JOIN per dataset and reference dataset.column.`,
+            );
+        }
+        const source = this.byName.get(qualifier);
+        if (source === undefined) throw new DatasetSqlError(this.unknownQualifier(qualifier));
+        if (source === "ambiguous") {
+            throw new DatasetSqlError(
+                `"${qualifier}" names more than one dataset in the query; give each JOIN its own alias.`,
+            );
+        }
+        if (isLink(source)) {
+            throw new DatasetSqlError(
+                `"${qualifier}" is a link table; read its columns from the datasets it links.`,
+            );
+        }
+        return source.path ? `${source.path}.${column}` : column;
+    }
+
+    private name(qualifier: string, source: Source | Link) {
+        this.byName.set(qualifier, this.byName.has(qualifier) ? "ambiguous" : source);
+    }
+
+    /** FROM's own column names, what a plain row answers bare. */
+    public get columnNames() {
+        return this.root.dataset.columns.map((column) => column.name);
+    }
+
+    /** Where a wire reference lands in the answered row: under the qualifier its dataset was named by, or bare for FROM's own columns. */
+    public placeOf(wireRef: string) {
+        const dot = wireRef.lastIndexOf(".");
+        if (dot === -1) return [wireRef];
+        const path = wireRef.slice(0, dot);
+        for (const [qualifier, entry] of this.byName) {
+            if (entry !== "ambiguous" && !isLink(entry) && entry.path === path) {
+                return [qualifier, wireRef.slice(dot + 1)];
+            }
+        }
+        return [wireRef];
+    }
+
+    /** The relation whose target (or link table) and ON keys match; two relations to one dataset differ by their keys. */
+    private joinTo(
+        parent: Source,
+        dataset: string,
+        parentKey: string,
+        targetKey: string,
+        inner: boolean,
+    ) {
+        const candidates = Object.entries(parent.dataset.relations).filter(
+            ([, r]) => (r.through?.dataset ?? r.dataset) === dataset,
+        );
+        if (candidates.length === 0) {
+            throw new DatasetSqlError(
+                `"${parent.dataset.name}" declares no join to "${dataset}". ${this.inverseOf(parent, dataset) ?? this.joinsOf(parent)}`,
+            );
+        }
+        const found = candidates.find(([, r]) => r.on[0] === parentKey && r.on[1] === targetKey);
+        if (!found) {
+            const all = datasetJoinLines(parent.dataset);
+            const names = Object.keys(parent.dataset.relations);
+            const lines = candidates.map(([name]) => all[names.indexOf(name)]!);
+            throw new DatasetSqlError(
+                `"${parent.dataset.name}" reaches "${dataset}" as ${lines.join(", or ")}.`,
+            );
+        }
+        const [relationName, relation] = found;
+        if (!relation.through) return this.source(parent, relationName, relation.dataset);
+        return { from: parent, relationName, relation, inner } satisfies Link;
+    }
+
+    private completeLink(link: Link, dataset: string, linkKey: string, targetKey: string) {
+        const { relation } = link;
+        const through = relation.through!;
+        const matches =
+            relation.dataset === dataset &&
+            through.on[0] === linkKey &&
+            through.on[1] === targetKey;
+        if (!matches) {
+            throw new DatasetSqlError(
+                `"${through.dataset}" is the link to "${relation.dataset}": ${datasetJoinSql(link.from.dataset.name, relation)}.`,
+            );
+        }
+        link.completed = true;
+        return this.source(link.from, link.relationName, dataset);
+    }
+
+    private source(parent: Source, relationName: string, datasetName: string) {
+        const dataset = this.catalog.get(datasetName);
+        if (!dataset) throw new DatasetSqlError(`"${datasetName}" is not an exposed dataset.`);
+        const path = parent.path ? `${parent.path}.${relationName}` : relationName;
+        this.paths.push(path);
+        return { path, dataset } satisfies Source;
+    }
+
+    private bareColumn(column: string) {
+        const has = (source: Source) => source.dataset.columns.some((c) => c.name === column);
+        if (has(this.root)) return column;
+        const owners = this.sources().filter((source) => source.path && has(source));
+        if (owners.length === 1) return `${owners[0]!.path}.${column}`;
+        if (owners.length > 1) {
+            throw new DatasetSqlError(
+                `"${column}" is a column of ${owners.map((o) => o.dataset.name).join(" and ")}; qualify it as dataset.column.`,
+            );
+        }
+        const joined = this.paths.length ? " or of the joined datasets" : "";
+        throw new DatasetSqlError(
+            `"${column}" is not a column of ${this.root.dataset.name}${joined}.`,
+        );
+    }
+
+    /** Every readable dataset once, whatever it is named as. */
+    private sources() {
+        const seen = new Set<Source>();
+        for (const entry of this.byName.values()) {
+            if (entry !== "ambiguous" && !isLink(entry)) seen.add(entry);
+        }
+        return [...seen];
+    }
+
+    private unknownQualifier(qualifier: string) {
+        for (const source of this.sources()) {
+            const relations = Object.entries(source.dataset.relations);
+            const index = relations.findIndex(
+                ([name, r]) => name === qualifier || r.dataset === qualifier,
+            );
+            if (index === -1) continue;
+            const [, relation] = relations[index]!;
+            const line = datasetJoinLines(source.dataset)[index]!;
+            return this.byName.has(relation.dataset)
+                ? `"${qualifier}" is the relation's name; reference ${relation.dataset}.column.`
+                : `"${qualifier}" is not joined. Add ${line} and reference ${relation.dataset}.column.`;
+        }
+        return `"${qualifier}" is neither the dataset, a joined dataset nor an alias. ${this.joinsOf(this.root)}`;
+    }
+
+    /** A one-to-many written from the parent side (`FROM plans JOIN planTasks`) is declared the other way round; say where to start. */
+    private inverseOf(parent: Source, dataset: string) {
+        const child = this.catalog.get(dataset);
+        if (!child) return undefined;
+        const index = Object.values(child.relations).findIndex(
+            (r) => r.dataset === parent.dataset.name && !r.through,
+        );
+        if (index === -1) return undefined;
+        return `"${dataset}" joins "${parent.dataset.name}", so start there: FROM ${dataset} ${datasetJoinLines(child)[index]}.`;
+    }
+
+    private joinsOf(source: Source) {
+        const lines = datasetJoinLines(source.dataset);
+        return lines.length
+            ? `Joins "${source.dataset.name}" declares: ${lines.join("; ")}.`
+            : `"${source.dataset.name}" declares no joins.`;
+    }
+}
+
+type Statement = ReturnType<Parser["statement"]>;
+type Resolve = (ref: string) => string;
+type SelectEntry = string | DatasetNamedOperand;
+type GroupKey = NonNullable<DatasetQueryInput["groupBy"]>[number];
+
+/**
+ * Where a term is compiled: a row (columns only), the grouped row, where
+ * names are aliases or group keys and an aggregate call finds or adds its
+ * alias, or the finished row, where a window call finds or adds its alias too.
+ */
+type Scope = {
+    resolve: Resolve;
+    aggregateAlias?: (item: AggregateCall, clause?: string) => string;
+    windowAlias?: (item: WindowItem, clause?: string) => string;
+};
+
+function toOperand(term: Term, scope: Scope): DatasetOperand {
+    switch (term.kind) {
+        case "ref":
+            return scope.resolve(term.ref);
+        case "num":
+            return term.value;
+        case "lit":
+            return { value: term.value };
+        case "date":
+            return { value: isoDate(term.at) };
+        case "interval":
+            throw new DatasetSqlError(INTERVAL_PLACE);
+        case "agg":
+            if (!scope.aggregateAlias) {
+                throw new DatasetSqlError(
+                    `${describeTerm(term)} belongs in SELECT or HAVING, not in a row condition.`,
+                );
+            }
+            return scope.aggregateAlias(term.item);
+        case "window":
+            if (!scope.windowAlias) throw new DatasetSqlError(WINDOW_IN_CONDITION);
+            return scope.windowAlias(term.item);
+        case "arith":
+            return {
+                op: term.op,
+                left: toOperand(term.left, scope),
+                right: toOperand(term.right, scope),
+            };
+        case "dateTrunc":
+            return { fn: "dateTrunc", unit: term.unit, of: toOperand(term.of, scope) };
+        case "datePart":
+            return { fn: "datePart", unit: term.unit, of: toOperand(term.of, scope) };
+        case "fn":
+            return { fn: term.fn, args: term.args.map((arg) => toOperand(arg, scope)) };
+        case "case":
+            return {
+                case: term.branches.map((branch) => ({
+                    when: toFilter(grouped(branch.when), scope),
+                    then: toOperand(branch.then, scope),
+                })),
+                ...(term.else === undefined ? {} : { else: toOperand(term.else, scope) }),
+            };
+    }
+}
+
+function toFilter(predicate: Predicate, scope: Scope): DatasetFilter {
+    if (predicate.kind === "rank") {
+        throw new DatasetSqlError(
+            scope.windowAlias
+                ? "RANK() OVER (...) <= n stands on its own in QUALIFY, not under NOT, OR or parentheses."
+                : WINDOW_PLACE,
+        );
+    }
+    if (predicate.kind === "not") return { not: toFilter(predicate.of, scope) };
+    if (predicate.kind === "any")
+        return { any: predicate.of.map((entry) => toFilter(entry, scope)) };
+    if (predicate.kind === "all")
+        return { all: predicate.of.map((entry) => toFilter(entry, scope)) };
+    const col = toOperand(predicate.left, scope);
+    if (typeof col === "number" || (typeof col === "object" && "value" in col)) {
+        throw new DatasetSqlError(
+            `A condition starts with a column, not the literal ${describeOperand(col)}.`,
+        );
+    }
+    const value = isTermValue(predicate.value)
+        ? asValue(toOperand(predicate.value.term, scope))
+        : predicate.value;
+    return {
+        col,
+        op: predicate.op,
+        ...(value === undefined ? {} : { value }),
+    } satisfies DatasetCondition;
+}
+
+/** A compared value that is a literal stays one on the wire; a column or arithmetic is `{ col }`. */
+function asValue(operand: DatasetOperand) {
+    if (typeof operand === "number") return operand;
+    if (typeof operand === "object" && "value" in operand) return operand.value;
+    return { col: operand };
+}
+
+function same(left: unknown, right: unknown) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function isNamed(entry: SelectEntry | GroupKey): entry is DatasetNamedOperand {
+    return typeof entry === "object";
+}
+
+/** `SUM(total) AS revenue` becomes a wire aggregate; the alias (or the default one) is what ORDER BY and HAVING may name. */
+function toAggregate(item: AggregateCall, scope: Scope) {
+    const col = item.term ? toOperand(item.term, scope) : undefined;
+    if (typeof col === "number")
+        throw new DatasetSqlError(`${item.fn.toUpperCase()}(${col}) has no meaning.`);
+    const as = item.alias ?? defaultAlias(item.fn, col);
+    const filter = item.filter.map((entry) => toFilter(entry, scope));
+    return {
+        fn: item.fn,
+        ...(col === undefined ? {} : { col }),
+        as,
+        ...(filter.length ? { filter } : {}),
+    } satisfies WireAggregate;
+}
+
+function sameAggregate(left: WireAggregate, right: WireAggregate) {
+    return (
+        left.fn === right.fn &&
+        same(left.col ?? null, right.col ?? null) &&
+        same(left.filter ?? [], right.filter ?? [])
+    );
+}
+
+/** `AVG(total) OVER (PARTITION BY customerId)` becomes a wire window: the aggregate, plus the partition its rows share. */
+function toWindow(item: WindowItem, scope: Scope, named: DatasetNamedOperand[]) {
+    const partitionBy = item.partitionBy.map((term) =>
+        resolveSort(term, scope, named, "PARTITION BY"),
+    );
+    return { ...toAggregate(item, scope), partitionBy } satisfies WireWindow;
+}
+
+function sameWindow(left: WireWindow, right: WireWindow) {
+    return sameAggregate(left, right) && same(left.partitionBy, right.partitionBy);
+}
+
+/**
+ * Walks the SELECT list in order: aggregates become wire aggregates;
+ * columns and values the entries a plain query selects and a grouped one
+ * must group by; calculations over aggregates (or their aliases) the
+ * compute items, compiled once the group keys are known. Every entry lands
+ * in the row where the statement wrote it.
+ */
+function collectSelect(items: SelectItem[], resolve: Resolve) {
+    const list = {
+        shape: Object.create(null) as Record<string, string[]>,
+        aggregates: [] as WireAggregate[],
+        entries: [] as SelectEntry[],
+        compute: [] as { as: string; term: Term }[],
+        /** Windows as written, compiled once the group keys are known since they name the row's own values. */
+        windows: [] as (WindowItem & { alias: string })[],
+        /** The term behind each named entry, for a grouped query to work out instead of group by. */
+        terms: new Map<string, Term>(),
+        aliasToKey: new Map<string, string>(),
+        selected: new Set<string>(),
+        star: items.some((item) => item.kind === "star"),
+    };
+    for (const item of items) {
+        if (item.kind === "aggregate") collectAggregate(list, item, resolve);
+        else if (item.kind === "window") collectWindow(list, item);
+        else if (item.kind === "column") collectColumn(list, item, resolve);
+        else if (item.kind === "expr") collectValue(list, item, resolve);
+    }
+    return list;
+}
+
+type SelectList = ReturnType<typeof collectSelect>;
+
+function collectWindow(list: SelectList, item: Extract<SelectItem, { kind: "window" }>) {
+    const taken =
+        list.selected.has(item.alias) || list.windows.some((other) => other.alias === item.alias);
+    if (taken) throw new DatasetSqlError(`"${item.alias}" names two things; pick another alias.`);
+    list.windows.push({ ...item.item, alias: item.alias });
+    list.aliasToKey.set(item.alias, item.alias);
+    if (!item.hidden) list.selected.add(item.alias);
+}
+
+function collectAggregate(list: SelectList, item: AggregateItem, resolve: Resolve) {
+    const aggregate = toAggregate(item, { resolve });
+    if (list.aggregates.some((other) => other.as === aggregate.as)) {
+        throw new DatasetSqlError(
+            `Two aggregates would answer as "${aggregate.as}"; give each its own alias.`,
+        );
+    }
+    list.aggregates.push(aggregate);
+    list.aliasToKey.set(aggregate.as, aggregate.as);
+    if (!item.hidden) list.selected.add(aggregate.as);
+}
+
+function collectColumn(
+    list: SelectList,
+    item: Extract<SelectItem, { kind: "column" }>,
+    resolve: Resolve,
+) {
+    const key = resolve(item.ref);
+    list.entries.push(key);
+    claim(list, key, item.alias ? [item.alias] : item.ref.split("."));
+    if (item.alias) list.aliasToKey.set(item.alias, key);
+}
+
+/** A row key is answered once: two select items landing on one key have nowhere to go. */
+function claim(list: SelectList, key: string, path: string[]) {
+    if (list.shape[key] !== undefined) {
+        throw new DatasetSqlError(`"${key}" names two things; pick another alias.`);
+    }
+    list.shape[key] = path;
+}
+
+/**
+ * A named value: over aggregates, their aliases or an earlier calculation it
+ * is worked out per grouped row (compute); otherwise it is a select entry a
+ * grouped query must group by.
+ */
+function collectValue(
+    list: SelectList,
+    item: Extract<SelectItem, { kind: "expr" }>,
+    resolve: Resolve,
+) {
+    const column = dateColumnOf(item.term);
+    const name = item.alias ?? lastSegment(column ?? "");
+    list.aliasToKey.set(name, name);
+    const overAggregates =
+        hasAggregate(item.term) ||
+        hasWindow(item.term) ||
+        termRefs(item.term).some(
+            (ref) => list.selected.has(ref) || list.compute.some((entry) => entry.as === ref),
+        );
+    if (overAggregates) {
+        list.compute.push({ as: name, term: item.term });
+        return;
+    }
+    list.entries.push({ expr: toOperand(item.term, { resolve } satisfies Scope), as: name });
+    list.terms.set(name, item.term);
+    claim(list, name, (item.alias ?? column ?? name).split("."));
+}
+
+/**
+ * GROUP BY may name a column, a select alias, or repeat a selected value;
+ * a bare column a selected date value is over takes that value as its key
+ * (`SELECT DATE_TRUNC('month', placedAt) ... GROUP BY placedAt`). A value
+ * nobody selected is keyed under the date column's own name, or refused.
+ */
+function resolveGroupKeys(
+    entries: SelectEntry[],
+    groupBy: Term[],
+    aliasToKey: Map<string, string>,
+    scope: Scope,
+) {
+    const named = entries.filter(isNamed);
+    const keys = new Map<string, GroupKey>();
+    for (const group of groupBy) {
+        let key: GroupKey;
+        if (group.kind === "ref") {
+            const name = aliasToKey.get(group.ref) ?? scope.resolve(group.ref);
+            const lends = !entries.includes(name);
+            key =
+                named.find(
+                    (entry) =>
+                        entry.as === name || (lends && dateColumnOfOperand(entry.expr) === name),
+                ) ?? name;
+        } else {
+            const expr = toOperand(group, scope);
+            const twin = named.find((entry) => same(entry.expr, expr));
+            const column = dateColumnOf(group);
+            if (!twin && column === undefined) {
+                throw new DatasetSqlError(
+                    `Name the value in SELECT (${describeTerm(group)} AS name) and GROUP BY name.`,
+                );
+            }
+            key = twin ?? { expr, as: lastSegment(column ?? "") };
+        }
+        const taken = keys.get(groupKeyName(key));
+        if (taken && !same(operandOf(taken), operandOf(key))) {
+            throw new DatasetSqlError(
+                `Two group keys would answer as "${groupKeyName(key)}"; name each value: ${describeTerm(group)} AS name.`,
+            );
+        }
+        keys.set(groupKeyName(key), key);
+    }
+    return keys;
+}
+
+function operandOf(key: GroupKey) {
+    return typeof key === "string" ? key : key.expr;
+}
+
+function dateColumnOfOperand(operand: DatasetOperand) {
+    const dated = typeof operand === "object" && "of" in operand;
+    return dated && typeof operand.of === "string" ? operand.of : undefined;
+}
+
+/** A grouped query answers only group keys and aggregates; a selected column or value must be one of the keys. */
+function assertGrouped(entries: SelectEntry[], star: boolean, groupKeys: Map<string, GroupKey>) {
+    const offending = star ? "*" : entries.map(groupKeyName).find((name) => !groupKeys.has(name));
+    if (offending !== undefined) {
+        throw new DatasetSqlError(
+            `"${offending}" is selected beside an aggregate but not grouped: add it to GROUP BY, wrap it in an aggregate, or drop it.`,
+        );
+    }
+}
+
+/**
+ * Every name at the top of the answered row must be one thing: not two
+ * select items, and not also a qualifier rows nest under (`COUNT(*) AS pets`
+ * beside `pets.name` has nowhere to go). Returns the names the row uses.
+ */
+function assertShapeFits(shape: Record<string, string[]>, flatNames: string[]) {
+    const paths = Object.values(shape);
+    const nested = new Set(paths.filter((path) => path.length > 1).map((path) => path[0]!));
+    const flat = [
+        ...flatNames,
+        ...paths.filter((path) => path.length === 1).map((path) => path[0]!),
+    ];
+    const seen = new Set<string>();
+    for (const name of flat) {
+        if (seen.has(name)) {
+            throw new DatasetSqlError(`"${name}" names two things; pick another alias.`);
+        }
+        seen.add(name);
+    }
+    const clash = flat.find((name) => nested.has(name));
+    if (clash !== undefined) {
+        throw new DatasetSqlError(
+            `"${clash}" is both a dataset the row nests under and a top-level name; pick another alias.`,
+        );
+    }
+    return seen;
+}
+
+/**
+ * HAVING, compute, rank and ORDER BY see the grouped row: a name is a select
+ * alias, a group key or a computed alias; an aggregate call is the SELECT
+ * aggregate it repeats, or, where adding is allowed, one added to the query
+ * under a default alias.
+ */
+function groupedScope(
+    aliasToKey: Map<string, string>,
+    aggregates: WireAggregate[],
+    used: (as: string) => boolean,
+    resolve: Resolve,
+    addMissing: boolean,
+) {
+    return {
+        resolve: (ref) => aliasToKey.get(ref) ?? resolve(ref),
+        aggregateAlias(item, clause = "ORDER BY") {
+            const wanted = toAggregate({ ...item, alias: "_" }, { resolve });
+            const found = aggregates.find((aggregate) => sameAggregate(aggregate, wanted));
+            if (found) return found.as;
+            if (!addMissing) {
+                throw new DatasetSqlError(
+                    `${clause} ${item.fn.toUpperCase()}(...) must also appear in SELECT; give it an alias and use that.`,
+                );
+            }
+            const added = toAggregate(item, { resolve });
+            added.as = freshAlias(added.as, used);
+            aggregates.push(added);
+            return added.as;
+        },
+    } satisfies Scope;
+}
+
+/**
+ * Unselected aggregates and windows take a default alias, which must not be
+ * a name the row already uses (`used`): a filtered and an unfiltered COUNT(*)
+ * would collide, and a column or calculation called `count` would be dropped with it.
+ */
+function freshAlias(base: string, used: (as: string) => boolean) {
+    let as = base;
+    for (let n = 2; used(as); n++) as = `${base}_${n}`;
+    return as;
+}
+
+/**
+ * The finished row: the grouped (or plain) row plus its windows, where a
+ * window call is the SELECT window it repeats by shape, or, where adding is
+ * allowed, one added to the query under a default alias. `scope` is the row
+ * a window reads, so an added window is checked like a selected one.
+ */
+function windowed(
+    scope: ReturnType<typeof groupedScope>,
+    windows: WireWindow[],
+    used: (as: string) => boolean,
+    named: DatasetNamedOperand[],
+    addMissing: boolean,
+) {
+    return {
+        ...scope,
+        windowAlias(item, clause = "ORDER BY") {
+            const wanted = toWindow({ ...item, alias: "_" }, scope, named);
+            const found = windows.find((window) => sameWindow(window, wanted));
+            if (found) return found.as;
+            if (!addMissing) {
+                throw new DatasetSqlError(
+                    `${clause} ${item.fn.toUpperCase()}(...) OVER (...) must also appear in SELECT; give it an alias and use that.`,
+                );
+            }
+            const added = toWindow(item, scope, named);
+            added.as = freshAlias(added.as, used);
+            windows.push(added);
+            return added.as;
+        },
+    } satisfies Required<Scope>;
+}
+
+/** On a grouped query a name must be one the row answers; a plain row reads its columns as they are. */
+function inRow<S extends Scope>(
+    scope: S,
+    known: (key: string) => boolean,
+    unknown: (ref: string) => string,
+) {
+    const resolve: Resolve = (ref) => {
+        const key = scope.resolve(ref);
+        if (known(key)) return key;
+        throw new DatasetSqlError(unknown(ref));
+    };
+    return { ...scope, resolve };
+}
+
+/** A sort or partition key: a name (alias, group key or column), an aggregate or window repeated from SELECT, or a selected value written again; the scope's refusal stands where it has no alias for the call. */
+function resolveSort(term: Term, scope: Scope, named: DatasetNamedOperand[], clause: string) {
+    if (term.kind === "ref") return scope.resolve(term.ref);
+    if (term.kind === "agg" && scope.aggregateAlias) return scope.aggregateAlias(term.item, clause);
+    if (term.kind === "window" && scope.windowAlias) return scope.windowAlias(term.item, clause);
+    const expr = toOperand(term, scope);
+    const twin = named.find((entry) => same(entry.expr, expr));
+    if (!twin) {
+        throw new DatasetSqlError(
+            `${clause} takes a column, an alias or an aggregate; name ${describeTerm(term)} in SELECT and use that.`,
+        );
+    }
+    return twin.as;
+}
+
+/** Turns the parsed statement into the wire query, resolving qualifiers, aliases and the grouped/ungrouped shape. */
+function compile(catalog: DatasetCatalog, statement: Statement) {
+    const { from, aliases, joins, items, filter, groupBy, having, qualify, sort, limit, offset } =
+        statement;
+    const sources = new Sources(catalog, from, aliases);
+    for (const join of joins) sources.join(join);
+    sources.assertComplete();
+    const resolve: Resolve = (ref) => sources.resolve(ref);
+    const rowScope = { resolve } satisfies Scope;
+    const list = collectSelect(items, resolve);
+    const { shape, aggregates, compute, aliasToKey, selected, star } = list;
+    const groupKeys = resolveGroupKeys(list.entries, groupBy, aliasToKey, rowScope);
+    // An aggregate call anywhere, a window's operand included, groups the query; a window over columns leaves it plain.
+    const aggregated =
+        [
+            ...compute.map((entry) => entry.term),
+            ...list.windows.map((item) => ({ kind: "window", item }) satisfies Term),
+        ].some(hasAggregate) || qualify.some((entry) => predicateHas(entry, isAggregateCall));
+    const grouped = groupKeys.size > 0 || aggregates.length > 0 || having.length > 0 || aggregated;
+    if (!grouped && !star && list.entries.length === 0 && list.windows.length) {
+        throw new DatasetSqlError(
+            "A window is answered on each row; SELECT the row's columns beside it, or write the aggregate without OVER (GROUP BY the partition for one row per group).",
+        );
+    }
+    // A grouped query answers group keys; a selected value that is none is worked out from them per grouped row.
+    const entries = list.entries.filter((entry) => {
+        const term = typeof entry === "string" ? undefined : list.terms.get(entry.as);
+        if (!grouped || term === undefined || groupKeys.has(groupKeyName(entry))) return true;
+        compute.push({ as: groupKeyName(entry), term });
+        delete shape[groupKeyName(entry)];
+        return false;
+    });
+    if (grouped) assertGrouped(entries, star, groupKeys);
+    // Group keys the SELECT list left out are answered too; they nest like the columns they are.
+    for (const key of groupKeys.keys()) shape[key] ??= sources.placeOf(key);
+    const row = finishRow(list, {
+        grouped,
+        groupKeys,
+        entries,
+        having,
+        qualify,
+        sort,
+        resolve,
+        columns: sources.columnNames,
+    });
+    // `*` is FROM's columns as the catalog lists them, then whatever else the SELECT names.
+    const starred = star ? sources.columnNames : [];
+    const select = [
+        ...starred,
+        ...entries.filter((entry) => typeof entry !== "string" || !starred.includes(entry)),
+    ];
+    const query = {
+        from,
+        join: sources.paths,
+        filter: [...sources.matched, ...filter.map((entry) => toFilter(entry, rowScope))],
+        ...(grouped
+            ? { groupBy: [...groupKeys.values()], aggregate: aggregates }
+            : { select: select.length ? select : undefined }),
+        ...row.clauses,
+        ...(limit === undefined ? {} : { limit }),
+        ...(offset === undefined ? {} : { offset }),
+    } satisfies DatasetQueryInput;
+    const hidden = [...aggregates, ...row.windows]
+        .map((entry) => entry.as)
+        .filter((as) => !selected.has(as));
+    return { query, shape, hidden } satisfies ParsedDatasetSql;
+}
+
+/**
+ * The clauses over the finished row, in the order the host works them out:
+ * windows over the grouped or plain row, calculations over that and the
+ * windows, HAVING (which sees no window), QUALIFY, the rank and ORDER BY.
+ * On a grouped query every name must be one the row answers; a plain row
+ * reads its columns as they are.
+ */
+function finishRow(
+    list: SelectList,
+    row: {
+        grouped: boolean;
+        groupKeys: Map<string, GroupKey>;
+        entries: SelectEntry[];
+        having: Predicate[];
+        qualify: Predicate[];
+        sort: SortList;
+        resolve: Resolve;
+        /** The FROM dataset's column names, which a plain row answers under their own names. */
+        columns: string[];
+    },
+) {
+    const { shape, aggregates, compute, aliasToKey, selected } = list;
+    const { grouped, groupKeys, entries, having, qualify, sort, resolve } = row;
+    const computeNames = new Set(compute.map((entry) => entry.as));
+    const rowNames = assertShapeFits(shape, [...selected, ...computeNames]);
+    const windows: WireWindow[] = [];
+    // A plain row reads its columns as they are, so a default alias must not shadow one either.
+    const columnNames = new Set(grouped ? [] : row.columns);
+    const used = (as: string) =>
+        rowNames.has(as) ||
+        columnNames.has(as) ||
+        aggregates.some((aggregate) => aggregate.as === as) ||
+        windows.some((window) => window.as === as);
+    // What the grouped row answers so far; a plain row reads its columns as they are.
+    const answered = (key: string) =>
+        !grouped ||
+        groupKeys.has(key) ||
+        aggregates.some((aggregate) => aggregate.as === key) ||
+        windows.some((window) => window.as === key);
+    const named = [...groupKeys.values(), ...entries].filter(isNamed);
+    const adding = groupedScope(aliasToKey, aggregates, used, resolve, true);
+    // A window reads the row before any calculation and before every window: SQL nests none.
+    const windowNames = new Set(list.windows.map((item) => item.alias));
+    const windowScope = inRow(
+        adding,
+        (key) => answered(key) && !computeNames.has(key) && !windowNames.has(key),
+        (ref) =>
+            computeNames.has(ref)
+                ? `"${ref}" is a calculation, worked out after the windows; put the arithmetic inside the window (SUM(n * 2) OVER ()).`
+                : windowNames.has(ref)
+                  ? `"${ref}" is a window; a window cannot read another window. Aggregate the column inside this one instead.`
+                  : `"${ref}" in a window is a column outside the grouped row; aggregate it inside the window (AVG(SUM(${ref})) OVER (...)) or GROUP BY it.`,
+    );
+    for (const item of list.windows) windows.push(toWindow(item, windowScope, named));
+    const finished = windowed(windowScope, windows, used, named, true);
+    // The finished row a calculation or QUALIFY reads: the row, its windows and the calculations; window calls still resolve through `finished`.
+    const finishedRow = (unknown: (ref: string) => string) =>
+        inRow(
+            { ...finished, resolve: adding.resolve },
+            (key) => answered(key) || computeNames.has(key),
+            unknown,
+        );
+    // A calculation reads the finished row: aggregates and windows (added if unselected), group keys and earlier calculations; a bare column is outside every aggregate.
+    const wireCompute = compute.map(({ as, term }) => {
+        const scope = finishedRow((ref) =>
+            hasAggregate(term)
+                ? `"${ref}" in ${describeTerm(term)} is a column outside an aggregate: put the arithmetic inside one (SUM(${ref} / other)), work between aggregates (SUM(${ref}) / COUNT(*)), or GROUP BY it.`
+                : `"${as}" is selected beside an aggregate but not grouped: add it to GROUP BY, wrap it in an aggregate, or drop it.`,
+        );
+        return { as, expr: toOperand(term, scope) };
+    });
+    // HAVING sees the grouped row and the calculations over it, never a window or a calculation over one: those are worked out after it.
+    const late = new Set(list.windows.map((item) => item.alias));
+    for (const { as, term } of compute) {
+        if (hasWindow(term) || termRefs(term).some((ref) => late.has(ref))) late.add(as);
+    }
+    const havingScope = inRow(
+        adding,
+        (key) => !late.has(key),
+        (ref) => `"${ref}" is worked out after HAVING; filter on it in QUALIFY.`,
+    );
+    const wireHaving = having.map((entry) => toFilter(entry, havingScope));
+    const ranks = qualify.flatMap((entry) => (entry.kind === "rank" ? [entry] : []));
+    if (ranks.length > 1) {
+        throw new DatasetSqlError("QUALIFY takes one RANK() OVER (...) <= n.");
+    }
+    // SQL ranks every row before QUALIFY drops any; the wire ranks the rows QUALIFY kept.
+    // Both at once would answer rows SQL would not, so the mix is refused.
+    if (ranks.length === 1 && qualify.length > 1) {
+        throw new DatasetSqlError(
+            "QUALIFY takes either RANK() OVER (...) <= n or other conditions, not both: SQL ranks the rows before QUALIFY filters them. Put the other conditions in WHERE or HAVING, or finish in code.",
+        );
+    }
+    const qualifying = finishedRow(
+        (ref) =>
+            `"${ref}" in QUALIFY is a column outside the grouped row; QUALIFY names group keys, aggregates, calculations and windows.`,
+    );
+    const wireQualify = qualify.flatMap((entry) =>
+        entry.kind === "rank" ? [] : [toFilter(entry, qualifying)],
+    );
+    const [rank] = ranks;
+    const sorting = windowed(
+        groupedScope(aliasToKey, aggregates, used, resolve, false),
+        windows,
+        used,
+        named,
+        false,
+    );
+    const sortNamed = [...named, ...wireCompute];
+    const sortOf = (terms: SortList, clause: string) =>
+        terms.map(({ term, dir }) => ({ col: resolveSort(term, sorting, sortNamed, clause), dir }));
+    const clauses = {
+        ...(windows.length ? { window: windows } : {}),
+        ...(wireCompute.length ? { compute: wireCompute } : {}),
+        ...(wireHaving.length ? { having: wireHaving } : {}),
+        ...(wireQualify.length ? { qualify: wireQualify } : {}),
+        ...(rank
+            ? {
+                  rank: {
+                      partitionBy: rank.partitionBy.map((term) =>
+                          resolveSort(term, sorting, sortNamed, "PARTITION BY"),
+                      ),
+                      sort: sortOf(rank.sort, "OVER (... ORDER BY)"),
+                      limit: rank.limit,
+                  },
+              }
+            : {}),
+        sort: sortOf(sort, "ORDER BY"),
+    } satisfies Partial<DatasetQueryInput>;
+    return { clauses, windows };
+}
+
+/** `COUNT(*)` answers as `count`, `SUM(total)` as `sum_total`, `AVG(a / target)` as `avg_a_target`, when the statement gives no alias. */
+function defaultAlias(fn: DatasetAggregate, col: DatasetOperand | undefined) {
+    const base = fn === "countDistinct" ? "count_distinct" : fn;
+    if (col === undefined) return base;
+    const words = describeOperand(col)
+        .replace(/[^A-Za-z0-9]+/g, "_")
+        .replace(/^_|_$/g, "");
+    return `${base}_${words}`;
+}
+
+/** What a parse needs beyond the statement: the moment CURRENT_DATE and NOW() name, and the IANA time zone whose calendar date that is (UTC when missing or unknown). */
+type ParseOptions = { now: Date; timeZone?: string };
+
+/** The calendar date `now` falls on in `timeZone`, as the UTC midnight the date folding runs on. */
+function calendarDate(now: Date, timeZone: string | undefined) {
+    const utc = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+    if (timeZone === undefined) return utc;
+    try {
+        const parts = new Intl.DateTimeFormat("en-US", {
+            timeZone,
+            year: "numeric",
+            month: "numeric",
+            day: "numeric",
+        }).formatToParts(now);
+        const part = (type: "year" | "month" | "day") =>
+            Number(parts.find((entry) => entry.type === type)?.value);
+        return new Date(Date.UTC(part("year"), part("month") - 1, part("day")));
+    } catch {
+        return utc;
+    }
+}
+
+/** Parses one SELECT against the catalog into the wire query; throws {@link DatasetSqlError} with what to write instead. */
+export function parseDatasetSql(sql: string, catalog: DatasetCatalog, options: ParseOptions) {
+    const trimmed = sql.trim();
+    if (!trimmed) throw new DatasetSqlError("The query is empty.");
+    const today = calendarDate(options.now, options.timeZone);
+    return compile(catalog, new Parser(tokenize(trimmed), today).statement());
+}
+
+/**
+ * Rebuilds each answered row as the statement reads: unselected aggregates
+ * dropped, and `pet.name` placed under `pets.name` as `{ pets: { name } }`.
+ * Every level has no prototype: the path segments are names the statement
+ * wrote, and `__proto__` must land as a key, not reach Object.prototype.
+ */
+export function shapeDatasetRows(
+    rows: ReadonlyArray<Record<string, unknown>>,
+    parsed: Pick<ParsedDatasetSql, "shape" | "hidden">,
+) {
+    const { shape, hidden } = parsed;
+    return rows.map((row) => {
+        const shaped = Object.create(null) as Record<string, unknown>;
+        for (const [key, value] of Object.entries(row)) {
+            if (hidden.includes(key)) continue;
+            const path = Object.hasOwn(shape, key) ? shape[key]! : [key];
+            let target = shaped;
+            for (const segment of path.slice(0, -1)) {
+                target = (target[segment] ??= Object.create(null)) as Record<string, unknown>;
+            }
+            target[path.at(-1)!] = value;
+        }
+        return shaped;
+    });
+}