@m6d/cortex-cli 0.1.0

package/src/contracts/runtime/datasets.ts

@@ -0,0 +1,1391 @@
+import { z } from "zod";
+
+/*
+ * Datasets: governed tabular reads over a host's own data. A dataset host
+ * serves a manifest of the tables it exposes and runs one JSON query per
+ * read under the forwarded user identity, applying its own access rules
+ * before the query. Cortex validates a query against the manifest, caps it,
+ * forwards it, trims the answer, and logs the read; it never evaluates who
+ * may see which rows.
+ */
+
+export const DATASET_IDENTIFIER_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+/** `column` on the dataset queried, or `relation.relation.column` along declared relations. */
+export const DATASET_COLUMN_REF_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)*$/;
+
+export const datasetIdentifierSchema = z.string().regex(DATASET_IDENTIFIER_PATTERN).max(64);
+export const datasetColumnRefSchema = z.string().regex(DATASET_COLUMN_REF_PATTERN).max(256);
+
+export const DATASET_COLUMN_TYPES = ["string", "number", "boolean", "date"] as const;
+export type DatasetColumnType = (typeof DATASET_COLUMN_TYPES)[number];
+
+export const datasetColumnSchema = z.object({
+    name: datasetIdentifierSchema,
+    type: z.enum(DATASET_COLUMN_TYPES),
+    description: z.string().max(200).default(""),
+});
+export type DatasetColumn = z.infer<typeof datasetColumnSchema>;
+
+/**
+ * A join the host can honor: `on` pairs a column of this dataset with a
+ * column of the target; `through` names the link dataset of a many-to-many,
+ * whose `on` pairs its own column with the target's.
+ */
+export const datasetRelationSchema = z.object({
+    dataset: datasetIdentifierSchema,
+    on: z.tuple([datasetIdentifierSchema, datasetIdentifierSchema]),
+    through: z
+        .object({
+            dataset: datasetIdentifierSchema,
+            on: z.tuple([datasetIdentifierSchema, datasetIdentifierSchema]),
+        })
+        .optional(),
+});
+export type DatasetRelation = z.infer<typeof datasetRelationSchema>;
+
+export const DATASET_MAX_ROWS_DEFAULT = 500;
+
+export const datasetDefinitionSchema = z.object({
+    name: datasetIdentifierSchema,
+    /** What the model reads in the catalog; the columns come only on request. */
+    description: z.string().max(500),
+    columns: z.array(datasetColumnSchema).min(1).max(200),
+    relations: z.record(datasetIdentifierSchema, datasetRelationSchema).default({}),
+    /** The most rows one query may answer with; the host clamps to it whatever the caller sent. */
+    maxRows: z.number().int().min(1).max(5000).default(DATASET_MAX_ROWS_DEFAULT),
+});
+export type DatasetDefinition = z.infer<typeof datasetDefinitionSchema>;
+export type DatasetDefinitionInput = z.input<typeof datasetDefinitionSchema>;
+
+/** What `GET {host}/` answers: every dataset the host exposes, under a version that changes when any of them does. */
+export const datasetManifestSchema = z.object({
+    version: z.string().min(1).max(128),
+    datasets: z.array(datasetDefinitionSchema).max(500),
+});
+export type DatasetManifest = z.infer<typeof datasetManifestSchema>;
+
+export const DATASET_FILTER_OPS = [
+    "=",
+    "!=",
+    "<",
+    "<=",
+    ">",
+    ">=",
+    "in",
+    "notIn",
+    "between",
+    "contains",
+    "startsWith",
+    "endsWith",
+    "isNull",
+    "isNotNull",
+] as const;
+export type DatasetFilterOp = (typeof DATASET_FILTER_OPS)[number];
+
+/** The periods a date truncates to; a truncated value is the ISO date of the period's first day, weeks starting on Monday. */
+export const DATASET_BUCKETS = ["day", "week", "month", "quarter", "year"] as const;
+export type DatasetBucket = (typeof DATASET_BUCKETS)[number];
+/** The parts a date answers as an integer: the period's number, or the weekday 1 (Monday) to 7 (Sunday). */
+export const DATASET_DATE_PARTS = [...DATASET_BUCKETS, "dayOfWeek"] as const;
+export type DatasetDatePart = (typeof DATASET_DATE_PARTS)[number];
+/** Scalar functions over a value: the text ones over strings, `abs` and `round` (optional digits) over numbers, `coalesce` over two or more of one type. */
+export const DATASET_FUNCTIONS = [
+    "lower",
+    "upper",
+    "trim",
+    "length",
+    "abs",
+    "round",
+    "coalesce",
+] as const;
+export type DatasetFunction = (typeof DATASET_FUNCTIONS)[number];
+
+export const DATASET_AGGREGATES = ["count", "countDistinct", "sum", "avg", "min", "max"] as const;
+export type DatasetAggregate = (typeof DATASET_AGGREGATES)[number];
+
+const filterValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+
+export const DATASET_ARITHMETIC_OPS = ["+", "-", "*", "/"] as const;
+export type DatasetArithmeticOp = (typeof DATASET_ARITHMETIC_OPS)[number];
+
+/**
+ * A value read off a row: a column (or, on a grouped row, an aggregate or
+ * computed alias), a number, a text or boolean literal, arithmetic (division
+ * is exact, no integer division, and x / 0 is null), a date truncated to a period or one of its
+ * parts, a scalar function over values, or a CASE whose branches share a type.
+ */
+export type DatasetOperand =
+    | string
+    | number
+    | { value: string | boolean }
+    | { op: DatasetArithmeticOp; left: DatasetOperand; right: DatasetOperand }
+    | { fn: "dateTrunc"; unit: DatasetBucket; of: DatasetOperand }
+    | { fn: "datePart"; unit: DatasetDatePart; of: DatasetOperand }
+    | { fn: DatasetFunction; args: DatasetOperand[] }
+    | { case: { when: DatasetFilter; then: DatasetOperand }[]; else?: DatasetOperand };
+/**
+ * Every object variant has its own key, and the `fn` variants are told apart
+ * by `fn` before their arguments are read, so a malformed value is checked by
+ * one variant per level: tried by each variant alike, `dateTrunc` and
+ * `datePart` would both read `of` and the error would double per level.
+ */
+export const datasetOperandSchema: z.ZodType<DatasetOperand, DatasetOperand> = z.lazy(() =>
+    z.union([
+        datasetColumnRefSchema,
+        z.number(),
+        z.object({ value: z.union([z.string().max(500), z.boolean()]) }),
+        z.object({
+            op: z.enum(DATASET_ARITHMETIC_OPS),
+            left: datasetOperandSchema,
+            right: datasetOperandSchema,
+        }),
+        z.discriminatedUnion("fn", [
+            z.object({
+                fn: z.literal("dateTrunc"),
+                unit: z.enum(DATASET_BUCKETS),
+                of: datasetOperandSchema,
+            }),
+            z.object({
+                fn: z.literal("datePart"),
+                unit: z.enum(DATASET_DATE_PARTS),
+                of: datasetOperandSchema,
+            }),
+            z.object({
+                fn: z.enum(DATASET_FUNCTIONS),
+                args: z.array(datasetOperandSchema).min(1).max(10),
+            }),
+        ]),
+        z.object({
+            case: z
+                .array(z.object({ when: datasetFilterSchema, then: datasetOperandSchema }))
+                .min(1)
+                .max(20),
+            else: datasetOperandSchema.optional(),
+        }),
+    ]),
+);
+/** A value under the key it comes back as; what select, groupBy and compute name. */
+export const datasetNamedOperandSchema = z.object({
+    expr: datasetOperandSchema,
+    as: datasetIdentifierSchema,
+});
+export type DatasetNamedOperand = z.infer<typeof datasetNamedOperandSchema>;
+/** The left side of a condition: a column or arithmetic, never a bare number. */
+const datasetConditionLeftSchema = datasetOperandSchema.refine(
+    (operand) => typeof operand !== "number",
+    "a condition starts with a column",
+);
+
+export type DatasetCondition = {
+    col: Exclude<DatasetOperand, number>;
+    op: DatasetFilterOp;
+    /** A scalar, a list for `in` and `notIn`, a pair for `between`, nothing for the null checks, or `{ col }` to compare with another column or arithmetic. */
+    value?: string | number | boolean | (string | number | boolean)[] | { col: DatasetOperand };
+};
+export const datasetConditionSchema: z.ZodType<DatasetCondition, DatasetCondition> = z.object({
+    col: datasetConditionLeftSchema as z.ZodType<
+        Exclude<DatasetOperand, number>,
+        Exclude<DatasetOperand, number>
+    >,
+    op: z.enum(DATASET_FILTER_OPS),
+    value: z
+        .union([
+            filterValueSchema,
+            z.array(filterValueSchema).max(500),
+            z.object({ col: datasetOperandSchema }),
+        ])
+        .optional(),
+});
+
+/**
+ * A condition, a group of filters that must all hold (`all`) or of which one
+ * must hold (`any`), or the negation of one (`not`, with SQL's null
+ * semantics: a row whose comparison is unknown is left out either way). A
+ * filter list is an `all`.
+ */
+export type DatasetFilter =
+    | DatasetCondition
+    | { any: DatasetFilter[] }
+    | { all: DatasetFilter[] }
+    | { not: DatasetFilter };
+export const datasetFilterSchema: z.ZodType<DatasetFilter, DatasetFilter> = z.lazy(() =>
+    z.union([
+        datasetConditionSchema,
+        z.object({ any: z.array(datasetFilterSchema).min(1).max(20) }),
+        z.object({ all: z.array(datasetFilterSchema).min(1).max(20) }),
+        z.object({ not: datasetFilterSchema }),
+    ]),
+);
+
+/** A column, answered under its own reference, or a value answered under its alias. */
+export const datasetGroupBySchema = z.union([datasetColumnRefSchema, datasetNamedOperandSchema]);
+const datasetSortSchema = z.object({
+    col: datasetColumnRefSchema,
+    dir: z.enum(["asc", "desc"]),
+});
+
+export const datasetAggregateSchema = z.object({
+    fn: z.enum(DATASET_AGGREGATES),
+    /** The column or arithmetic aggregated; `count` may omit it to count rows. */
+    col: (
+        datasetConditionLeftSchema as z.ZodType<
+            Exclude<DatasetOperand, number>,
+            Exclude<DatasetOperand, number>
+        >
+    )
+        .optional()
+        .describe("The column or arithmetic to aggregate; omit for count."),
+    as: datasetIdentifierSchema.describe(
+        "The key the value comes back under; also what sort may name.",
+    ),
+    /** Only rows matching these (after the query filter) enter this aggregate: SQL's `FILTER (WHERE ...)`. Over no rows, count and sum answer 0, avg/min/max null. */
+    filter: z.array(datasetFilterSchema).max(20).default([]),
+});
+
+/**
+ * One read. Column references beyond the dataset's own walk the relations
+ * named in `join`, as `relation.column`; a grouped query answers one row per
+ * group with the group columns and the aggregate aliases as keys.
+ */
+const datasetQueryObjectSchema = z.object({
+    from: datasetIdentifierSchema,
+    /** Relation paths the query reaches, e.g. `["department", "plan.ownerDepartment"]`; a path a column reference names is joined without being listed. */
+    join: z
+        .array(datasetColumnRefSchema)
+        .max(8)
+        .default([])
+        .describe("Relations to join, by name; referencing relation.column joins it too."),
+    /** Columns and named values to return for an ungrouped query; when absent, every column the definition lists (filled in before the query reaches a host). As many as a definition may have columns. */
+    select: z
+        .array(z.union([datasetColumnRefSchema, datasetNamedOperandSchema]))
+        .max(200)
+        .optional()
+        .describe(
+            "Columns or named values to return when not grouping; aggregates go in aggregate, not here.",
+        ),
+    filter: z.array(datasetFilterSchema).max(20).default([]),
+    groupBy: z
+        .array(datasetGroupBySchema)
+        .max(8)
+        .default([])
+        .describe(
+            "Group keys: a column name, or { expr, as } for a value such as a truncated date.",
+        ),
+    aggregate: z
+        .array(datasetAggregateSchema)
+        .max(10)
+        .default([])
+        .describe(
+            "One entry per computed value; a grouped row holds the group keys and these aliases.",
+        ),
+    /**
+     * An aggregate over the answered rows that share a partition (every row
+     * when `partitionBy` is empty), answered on each of those rows: SQL's
+     * `fn(col) OVER (PARTITION BY ...)`. Names are the row's own: columns and
+     * select aliases on a plain query, group keys and aggregate aliases on a
+     * grouped one. Worked out after `having`, before `compute` and `qualify`.
+     */
+    window: z
+        .array(
+            datasetAggregateSchema.extend({
+                partitionBy: z.array(datasetColumnRefSchema).max(4).default([]),
+            }),
+        )
+        .max(10)
+        .default([]),
+    /** Values worked out per row from the aggregate aliases, group keys and window aliases: `{ as, expr }`, where `having`, `qualify`, `rank` and `sort` may name them. */
+    compute: z.array(datasetNamedOperandSchema).max(10).default([]),
+    /** Conditions on the grouped rows: they name aggregate aliases, computed aliases or group keys. SQL's HAVING. */
+    having: z.array(datasetFilterSchema).max(20).default([]),
+    /** Conditions on the finished rows, window and computed aliases included, before `rank`, `sort` and `limit`: SQL's QUALIFY. */
+    qualify: z.array(datasetFilterSchema).max(20).default([]),
+    /** The first `limit` rows of each partition, in `sort` order, taken before the query's own sort and limit: SQL's RANK() OVER (PARTITION BY ... ORDER BY ...) <= n, so rows tied on every sort key share a rank and all stay within the limit. */
+    rank: z
+        .object({
+            partitionBy: z.array(datasetColumnRefSchema).min(1).max(4),
+            sort: z.array(datasetSortSchema).min(1).max(5),
+            limit: z.number().int().min(1).max(100),
+        })
+        .optional(),
+    sort: z
+        .array(datasetSortSchema)
+        .max(5)
+        .default([])
+        .describe(
+            "By a column or select alias, a group key, an aggregate alias or a computed alias.",
+        ),
+    limit: z.number().int().min(1).optional(),
+    /** Rows to skip before `limit`; only with a `sort`, since the row order is undefined without one. */
+    offset: z.number().int().min(0).optional(),
+});
+
+/** How deep a query's JSON may nest, objects and arrays alike; far past what a statement needs. */
+export const DATASET_QUERY_MAX_DEPTH = 32;
+
+/** Whether `value` nests at most `budget` objects and arrays deep; the walk stops at the budget, so a deeper value costs no more than an allowed one. */
+function nestsWithin(value: unknown, budget: number): boolean {
+    if (typeof value !== "object" || value === null) return true;
+    return budget > 0 && Object.values(value).every((item) => nestsWithin(item, budget - 1));
+}
+
+export type DatasetQueryInput = z.input<typeof datasetQueryObjectSchema>;
+
+/** A query, refused before it is read when it nests past the budget, so a body nested thousands deep costs what one at the budget does. */
+export const datasetQuerySchema = z
+    .custom<DatasetQueryInput>(
+        (value) => nestsWithin(value, DATASET_QUERY_MAX_DEPTH),
+        `A query nests at most ${DATASET_QUERY_MAX_DEPTH} levels deep; write a flatter expression`,
+    )
+    .pipe(datasetQueryObjectSchema);
+export type DatasetQuery = z.infer<typeof datasetQuerySchema>;
+
+/** What `POST {host}/{name}` receives: the validated query, capped, plus what the host may want in its own logs. */
+export const datasetRequestSchema = z.object({
+    query: datasetQuerySchema,
+    context: z.object({
+        threadId: z.string().max(128),
+        requestId: z.string().max(128).optional(),
+    }),
+});
+export type DatasetRequest = z.infer<typeof datasetRequestSchema>;
+
+export const datasetResultSchema = z.object({
+    /** Keyed by the column reference as written in the query, or the aggregate alias. */
+    rows: z.array(z.record(z.string(), z.unknown())),
+    rowCount: z.number().int().nonnegative(),
+    /** More rows matched than were returned. */
+    truncated: z.boolean(),
+});
+export type DatasetResult = z.infer<typeof datasetResultSchema>;
+
+export const DATASET_ERROR_KINDS = [
+    "invalid_query",
+    "unsupported",
+    "forbidden",
+    "timeout",
+    "internal",
+] as const;
+export type DatasetErrorKind = (typeof DATASET_ERROR_KINDS)[number];
+
+/** The HTTP status each error kind travels under, both from a host and from the server's own refusals. */
+export const DATASET_ERROR_STATUS = {
+    invalid_query: 400,
+    unsupported: 400,
+    forbidden: 403,
+    timeout: 504,
+    internal: 500,
+} as const satisfies Record<DatasetErrorKind, number>;
+
+export const datasetErrorSchema = z.object({
+    error: z.object({
+        kind: z.enum(DATASET_ERROR_KINDS),
+        detail: z.string().max(512),
+    }),
+});
+export type DatasetError = z.infer<typeof datasetErrorSchema>;
+
+/**
+ * A dataset host as an agent's published configuration carries it: the
+ * datasets the agent exposes, already the published manifest's definitions,
+ * and which of them ride in every turn. The Control Center runs the queries
+ * for a host it registered, so the server needs no URL or credential here.
+ */
+export const datasetHostDeclarationSchema = z.object({
+    name: datasetIdentifierSchema,
+    manifestVersion: datasetManifestSchema.shape.version,
+    datasets: z.array(datasetDefinitionSchema).max(500),
+    pinned: z.array(datasetIdentifierSchema).max(50).default([]),
+});
+export type DatasetHostDeclaration = z.infer<typeof datasetHostDeclarationSchema>;
+
+/** The definitions a query may reach, by dataset name. */
+export type DatasetCatalog = ReadonlyMap<string, DatasetDefinition>;
+
+export function datasetCatalogOf(definitions: Iterable<DatasetDefinition>) {
+    return new Map([...definitions].map((definition) => [definition.name, definition]));
+}
+
+/** The operators a filter may use on a column of the given type. */
+const OPERATORS_BY_TYPE = {
+    string: ["=", "!=", "in", "notIn", "contains", "startsWith", "endsWith", "isNull", "isNotNull"],
+    number: ["=", "!=", "<", "<=", ">", ">=", "in", "notIn", "between", "isNull", "isNotNull"],
+    date: ["=", "!=", "<", "<=", ">", ">=", "in", "notIn", "between", "isNull", "isNotNull"],
+    boolean: ["=", "!=", "isNull", "isNotNull"],
+} as const satisfies Record<DatasetColumnType, readonly DatasetFilterOp[]>;
+
+/**
+ * The column a reference names, walking `relation.relation.column` through
+ * the catalog, or why it names none. `path` is the relation path the query
+ * has to join for it, empty for the dataset's own columns.
+ */
+export function resolveDatasetColumn(catalog: DatasetCatalog, from: string, ref: string) {
+    const segments = ref.split(".");
+    const columnName = segments.pop()!;
+    const missing = (error: string) => ({ ok: false as const, error });
+    let dataset = catalog.get(from);
+    if (!dataset) return missing(`Unknown dataset "${from}"`);
+    for (const segment of segments) {
+        const relation = dataset.relations[segment];
+        if (!relation) return missing(`"${dataset.name}" has no relation "${segment}"`);
+        const target = catalog.get(relation.dataset);
+        if (!target) {
+            return missing(`Relation "${segment}" points at unknown dataset "${relation.dataset}"`);
+        }
+        dataset = target;
+    }
+    const column = dataset.columns.find((candidate) => candidate.name === columnName);
+    if (!column) return missing(`"${dataset.name}" has no column "${columnName}"`);
+    return { ok: true as const, column, path: segments.join(".") };
+}
+
+function refError(kind: string, ref: string, reason: string) {
+    return `${kind} "${ref}": ${reason}`;
+}
+
+function filterValueIssue(filter: DatasetCondition) {
+    const { op, value } = filter;
+    if (op === "isNull" || op === "isNotNull") {
+        return value === undefined ? undefined : `${op} takes no value`;
+    }
+    if (op === "in" || op === "notIn") {
+        return Array.isArray(value) && value.length > 0
+            ? undefined
+            : `${op} takes a non-empty list`;
+    }
+    if (op === "between") {
+        return Array.isArray(value) && value.length === 2 ? undefined : "between takes a pair";
+    }
+    return value !== undefined && !Array.isArray(value) ? undefined : `${op} takes one value`;
+}
+
+/**
+ * The query as the host runs it: habits the model brings from SQL are
+ * absorbed here rather than refused. A reference prefixed with the dataset's
+ * own name (`orders.total` on `orders`) drops the prefix when no relation
+ * has that name; a relation any reference names is joined without being
+ * listed; a `select` on a grouped query that only repeats the group keys is
+ * dropped, and an ungrouped query without one selects the definition's
+ * columns. Every host receives this shape, so all of them agree on it.
+ */
+function normalizeDatasetQuery(catalog: DatasetCatalog, query: DatasetQuery) {
+    const dataset = catalog.get(query.from);
+    if (!dataset) return query;
+    const ownPrefix = `${query.from}.`;
+    const strip = (ref: string) =>
+        ref.startsWith(ownPrefix) && !Object.hasOwn(dataset.relations, query.from)
+            ? ref.slice(ownPrefix.length)
+            : ref;
+    const stripFilter = (entry: DatasetFilter) => mapFilterRefs(entry, strip);
+    const stripNamed = (entry: DatasetNamedOperand) => ({
+        ...entry,
+        expr: mapOperandRefs(entry.expr, strip),
+    });
+    const groupBy = query.groupBy.map((group) =>
+        typeof group === "string" ? strip(group) : stripNamed(group),
+    );
+    const aggregate = query.aggregate.map((entry) => ({
+        ...entry,
+        ...(entry.col === undefined
+            ? {}
+            : { col: mapOperandRefs(entry.col, strip) as DatasetCondition["col"] }),
+        filter: entry.filter.map(stripFilter),
+    }));
+    const filter = query.filter.map(stripFilter);
+    const having = query.having.map(stripFilter);
+    const compute = query.compute.map(stripNamed);
+    const window = query.window.map((entry) => ({
+        ...entry,
+        ...(entry.col === undefined
+            ? {}
+            : { col: mapOperandRefs(entry.col, strip) as DatasetCondition["col"] }),
+        filter: entry.filter.map(stripFilter),
+        partitionBy: entry.partitionBy.map(strip),
+    }));
+    const qualify = query.qualify.map(stripFilter);
+    const sort = query.sort.map((entry) => ({ ...entry, col: strip(entry.col) }));
+    const rank = query.rank && {
+        ...query.rank,
+        partitionBy: query.rank.partitionBy.map(strip),
+        sort: query.rank.sort.map((entry) => ({ ...entry, col: strip(entry.col) })),
+    };
+    const grouped = groupBy.length > 0 || aggregate.length > 0;
+    const groupKeys = new Set(groupBy.map((group) => groupKeyName(group)));
+    const selected = query.select
+        ?.map((entry) => (typeof entry === "string" ? strip(entry) : stripNamed(entry)))
+        .filter((entry) => !(grouped && typeof entry === "string" && groupKeys.has(entry)));
+    // An ungrouped query without a select reads the columns the catalog publishes, never whatever the host's table has grown since.
+    const select = selected?.length
+        ? selected
+        : grouped
+          ? undefined
+          : dataset.columns.map((column) => column.name);
+    const referenced = [
+        ...(select ?? []).flatMap((entry) =>
+            typeof entry === "string" ? [entry] : operandRefs(entry.expr),
+        ),
+        ...filter.flatMap(filterRefs),
+        ...groupBy.flatMap((group) =>
+            typeof group === "string" ? [group] : operandRefs(group.expr),
+        ),
+        ...aggregate.flatMap((entry) => [
+            ...(entry.col === undefined ? [] : operandRefs(entry.col)),
+            ...entry.filter.flatMap(filterRefs),
+        ]),
+        ...sort.map((entry) => entry.col),
+        ...(rank ? [...rank.partitionBy, ...rank.sort.map((entry) => entry.col)] : []),
+        ...window.flatMap((entry) => [
+            ...(entry.col === undefined ? [] : operandRefs(entry.col)),
+            ...entry.filter.flatMap(filterRefs),
+            ...entry.partitionBy,
+        ]),
+        ...qualify.flatMap(filterRefs),
+    ]
+        .filter((ref) => ref.includes("."))
+        .map((ref) => ref.slice(0, ref.lastIndexOf(".")));
+    const join = [...new Set([...query.join.map(strip), ...referenced])];
+    return {
+        ...query,
+        join,
+        select,
+        filter,
+        groupBy,
+        aggregate,
+        having,
+        compute,
+        window,
+        qualify,
+        sort,
+        ...(rank ? { rank } : {}),
+    } satisfies DatasetQuery;
+}
+
+/** The key a group answers under: the column reference, or the value's alias. */
+export function groupKeyName(group: DatasetQuery["groupBy"][number]) {
+    return typeof group === "string" ? group : group.as;
+}
+
+function mapOperandRefs(operand: DatasetOperand, fn: (ref: string) => string): DatasetOperand {
+    if (typeof operand === "string") return fn(operand);
+    if (typeof operand === "number" || "value" in operand) return operand;
+    if ("op" in operand) {
+        return {
+            op: operand.op,
+            left: mapOperandRefs(operand.left, fn),
+            right: mapOperandRefs(operand.right, fn),
+        };
+    }
+    if ("case" in operand) {
+        return {
+            case: operand.case.map((branch) => ({
+                when: mapFilterRefs(branch.when, fn),
+                then: mapOperandRefs(branch.then, fn),
+            })),
+            ...(operand.else === undefined ? {} : { else: mapOperandRefs(operand.else, fn) }),
+        };
+    }
+    if ("args" in operand) {
+        return { fn: operand.fn, args: operand.args.map((arg) => mapOperandRefs(arg, fn)) };
+    }
+    return { ...operand, of: mapOperandRefs(operand.of, fn) };
+}
+
+function mapFilterRefs(filter: DatasetFilter, fn: (ref: string) => string): DatasetFilter {
+    if ("any" in filter) return { any: filter.any.map((entry) => mapFilterRefs(entry, fn)) };
+    if ("all" in filter) return { all: filter.all.map((entry) => mapFilterRefs(entry, fn)) };
+    if ("not" in filter) return { not: mapFilterRefs(filter.not, fn) };
+    const value =
+        typeof filter.value === "object" && filter.value !== null && !Array.isArray(filter.value)
+            ? { col: mapOperandRefs(filter.value.col, fn) }
+            : filter.value;
+    return {
+        col: mapOperandRefs(filter.col, fn) as DatasetCondition["col"],
+        op: filter.op,
+        ...(value === undefined ? {} : { value }),
+    };
+}
+
+/** Every column reference an operand names. */
+export function operandRefs(operand: DatasetOperand): string[] {
+    if (typeof operand === "string") return [operand];
+    if (typeof operand === "number" || "value" in operand) return [];
+    if ("op" in operand) return [...operandRefs(operand.left), ...operandRefs(operand.right)];
+    if ("case" in operand) {
+        return [
+            ...operand.case.flatMap((branch) => [
+                ...filterRefs(branch.when),
+                ...operandRefs(branch.then),
+            ]),
+            ...(operand.else === undefined ? [] : operandRefs(operand.else)),
+        ];
+    }
+    if ("args" in operand) return operand.args.flatMap(operandRefs);
+    return operandRefs(operand.of);
+}
+
+/** Every column reference a filter names, on either side, at any depth. */
+export function filterRefs(filter: DatasetFilter): string[] {
+    if ("any" in filter) return filter.any.flatMap(filterRefs);
+    if ("all" in filter) return filter.all.flatMap(filterRefs);
+    if ("not" in filter) return filterRefs(filter.not);
+    const right = isColumnValue(filter.value) ? operandRefs(filter.value.col) : [];
+    return [...operandRefs(filter.col), ...right];
+}
+
+/** A condition's right side that names a column or arithmetic rather than a literal. */
+export function isColumnValue(value: DatasetCondition["value"]): value is { col: DatasetOperand } {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * What every reader of a query does before acting on it: normalizes,
+ * validates, and caps `limit` at the dataset's `maxRows` whatever the caller
+ * sent. The answer is bounded to that `limit` with `boundDatasetResult`.
+ */
+export function checkDatasetQuery(catalog: DatasetCatalog, raw: DatasetQuery) {
+    const normalized = normalizeDatasetQuery(catalog, raw);
+    const maxRows = catalog.get(raw.from)?.maxRows ?? DATASET_MAX_ROWS_DEFAULT;
+    return {
+        query: { ...normalized, limit: Math.min(normalized.limit ?? maxRows, maxRows) },
+        issues: validateDatasetQuery(catalog, normalized),
+    };
+}
+
+/** An answer cut to the query's `limit`: a host that sent more rows than asked is trimmed and marked truncated, never trusted to have capped itself. */
+export function boundDatasetResult(
+    result: Omit<DatasetResult, "rows"> & { rows: ReadonlyArray<DatasetResult["rows"][number]> },
+    limit: number,
+) {
+    return {
+        rows: result.rows.slice(0, limit),
+        rowCount: Math.min(result.rowCount, limit),
+        truncated: result.truncated || result.rows.length > limit,
+    } satisfies DatasetResult;
+}
+
+/**
+ * Every way a query can be wrong given the catalog, as messages the model
+ * can act on; an empty list means the host will understand it. Checked
+ * before anything leaves the server, so a host can trust the shape and only
+ * has to translate.
+ */
+export function validateDatasetQuery(catalog: DatasetCatalog, query: DatasetQuery) {
+    if (!catalog.has(query.from)) return [`Unknown dataset "${query.from}"`];
+    const issues: string[] = [];
+    const joined = joinedPaths(catalog, query, issues);
+    const check = {
+        issue: (message: string) => issues.push(message),
+        columnOf(kind, ref) {
+            const resolved = resolveDatasetColumn(catalog, query.from, ref);
+            if (!resolved.ok) {
+                issues.push(refError(kind, ref, resolved.error));
+                return undefined;
+            }
+            if (resolved.path && !joined.has(resolved.path)) {
+                issues.push(
+                    refError(
+                        kind,
+                        ref,
+                        `relation "${resolved.path}" is not among this dataset's relations`,
+                    ),
+                );
+                return undefined;
+            }
+            return resolved.column;
+        },
+    } satisfies QueryCheck;
+
+    for (const filter of query.filter) checkFilter(check, filter);
+    const groupKeys = checkGroupBy(check, query.groupBy);
+    const aliases = checkAggregates(check, query.aggregate);
+    for (const alias of aliases.keys()) {
+        if (groupKeys.has(alias)) check.issue(`aggregate alias "${alias}" is also a group key`);
+    }
+    const grouped = query.groupBy.length > 0 || query.aggregate.length > 0;
+    if (query.having.length && !grouped) check.issue("having needs a grouped query");
+    if (query.compute.length && !grouped && query.window.length === 0) {
+        check.issue("compute needs a grouped query or a window");
+    }
+    // Models send every key; an empty select means the same as none.
+    if (grouped && query.select?.length) {
+        check.issue(
+            "a grouped query answers the group keys, the aggregate aliases and the computed aliases; put computed values in aggregate or compute and leave select out",
+        );
+    }
+    const selectAliases = checkSelect(check, query.select ?? []);
+    const row = grouped
+        ? { names: new Map([...groupKeys, ...aliases]), kind: "grouped" as const }
+        : { names: selectAliases, kind: "plain" as const };
+    checkFinishedRow(check, query, row);
+    checkExpansion(check, query, catalog.get(query.from)?.columns.length ?? 0);
+    return issues;
+}
+
+/** How large any one expression a host translates may grow once every alias it names is written out in place. */
+export const DATASET_EXPANSION_BUDGET = 2_000;
+
+/**
+ * Hosts write a computed alias out again wherever a later calculation or
+ * HAVING names it, as SQL requires, so ten aliases each naming the previous
+ * one ten times grow to 10^10 nodes from a few hundred bytes, with or without
+ * a column among them. Each alias costs what it expands to, worked out once in
+ * order, so the expansion is measured without being performed: a named select
+ * value or group key, an aggregate and a window cost their own trees wherever
+ * they are named, since hosts write them out. Every expression a host
+ * translates is held to the budget: select values, group keys, WHERE,
+ * aggregates and their filters, windows, calculations, HAVING and QUALIFY.
+ * Sort and rank name values and add none. A window is a correlated subquery
+ * that carries the row it counts over, so it also costs that row: WHERE and
+ * every value the row projects (`columnCount` of them for a plain query with
+ * no select).
+ */
+function checkExpansion(check: QueryCheck, query: DatasetQuery, columnCount: number) {
+    // The source row: what WHERE, select values, group keys and aggregates read, each column once.
+    const source = new Map<string, number>();
+    const named = [...(query.select ?? []), ...query.groupBy].flatMap((entry) =>
+        typeof entry === "string" ? [] : [[entry.as, operandCost(entry.expr, source)] as const],
+    );
+    const where = query.filter.map((filter) => filterCost(filter, source));
+    const costs = [...named.map(([, total]) => total), ...where];
+    const expanded = new Map(named);
+    const aggregates = query.aggregate.map((entry) => {
+        const parts = [
+            ...(entry.col === undefined ? [] : [operandCost(entry.col, source)]),
+            ...entry.filter.map((filter) => filterCost(filter, source)),
+        ];
+        costs.push(...parts);
+        expanded.set(entry.as, nodeCost(parts));
+        return nodeCost(parts);
+    });
+    const grouped = query.groupBy.length > 0 || query.aggregate.length > 0;
+    const projected = grouped ? query.groupBy : (query.select ?? []);
+    const carried = Math.min(
+        DATASET_EXPANSION_BUDGET + 1,
+        [
+            ...where,
+            ...projected.map((entry) =>
+                typeof entry === "string" ? 1 : (expanded.get(entry.as) ?? 1),
+            ),
+            ...(grouped || projected.length ? [] : Array<number>(columnCount).fill(1)),
+            ...aggregates,
+        ].reduce((total, cost) => total + cost, 0),
+    );
+    // Every window reads the row as it was before any window, its partition and the row it carries included.
+    const windows = query.window.map((entry) => {
+        const total = nodeCost([
+            ...(entry.col === undefined ? [] : [operandCost(entry.col, expanded)]),
+            ...entry.filter.map((filter) => filterCost(filter, expanded)),
+            ...entry.partitionBy.map((name) => operandCost(name, expanded)),
+            carried,
+        ]);
+        costs.push(total);
+        return [entry.as, total] as const;
+    });
+    for (const [as, total] of windows) expanded.set(as, total);
+    for (const entry of query.compute) {
+        const total = operandCost(entry.expr, expanded);
+        expanded.set(entry.as, total);
+        costs.push(total);
+    }
+    for (const filter of query.having) costs.push(filterCost(filter, expanded));
+    // A grouped row is materialized before QUALIFY reads it; without group keys the
+    // .NET host writes the calculations QUALIFY names out in full.
+    const qualifying = query.groupBy.length ? source : expanded;
+    for (const filter of query.qualify) costs.push(filterCost(filter, qualifying));
+    if (costs.some((total) => total > DATASET_EXPANSION_BUDGET)) {
+        check.issue(
+            `Computed aliases expand to more than ${DATASET_EXPANSION_BUDGET} references; name intermediate results and reuse them less`,
+        );
+    }
+}
+
+/**
+ * How many times a host writes one part out when it spells the node holding
+ * it, the most either host does; every other part is written once. A divisor
+ * is tested for zero before the division, ROUND's digits scale the value
+ * before and after, and LENGTH's text is tested for NULL besides measured. A
+ * date is read once per part a truncation or part needs (Zeller's congruence
+ * for the week and weekday), and a truncation other than the week, packed as
+ * a number, is read 3 more times when it meets a real date in a COALESCE, a
+ * CASE or a comparison, so those factors are the product. A condition guards
+ * its sides against NULL, and a negated condition with no opposite operator
+ * (`between`, the text matches) tests its left side once more.
+ */
+const EXPANSION_WEIGHTS = {
+    divisor: 2,
+    roundDigits: 2,
+    lengthText: 2,
+    conditionLeft: 3,
+    conditionRight: 2,
+    dateTrunc: { day: 9, month: 6, quarter: 6, year: 3, week: 17 },
+    datePart: { day: 1, month: 1, quarter: 1, year: 1, dayOfWeek: 16, week: 17 },
+} as const;
+
+/** One node plus its children's costs, held at one past the budget so no sum can overflow. */
+function nodeCost(children: number[]) {
+    return Math.min(
+        DATASET_EXPANSION_BUDGET + 1,
+        children.reduce((total, cost) => total + cost, 1),
+    );
+}
+
+/** How often a scalar function's argument is written out. */
+function argumentWeight(fn: DatasetFunction, index: number) {
+    if (fn === "length") return EXPANSION_WEIGHTS.lengthText;
+    return fn === "round" && index === 1 ? EXPANSION_WEIGHTS.roundDigits : 1;
+}
+
+/**
+ * An operand's size written out: a literal or a column is 1, a reference to an
+ * earlier computed alias is that alias's cost (a self or forward one, refused
+ * elsewhere, is 1), and arithmetic, a date function, a scalar function, a CASE
+ * and each of its branches are 1 plus their parts, each part times its weight.
+ */
+function operandCost(operand: DatasetOperand, expanded: ReadonlyMap<string, number>): number {
+    if (typeof operand === "string") return expanded.get(operand) ?? 1;
+    if (typeof operand === "number" || "value" in operand) return 1;
+    if ("op" in operand) {
+        const divisor = operand.op === "/" ? EXPANSION_WEIGHTS.divisor : 1;
+        return nodeCost([
+            operandCost(operand.left, expanded),
+            operandCost(operand.right, expanded) * divisor,
+        ]);
+    }
+    if ("case" in operand) {
+        return nodeCost([
+            ...operand.case.map((branch) =>
+                nodeCost([filterCost(branch.when, expanded), operandCost(branch.then, expanded)]),
+            ),
+            ...(operand.else === undefined ? [] : [operandCost(operand.else, expanded)]),
+        ]);
+    }
+    if ("args" in operand) {
+        return nodeCost(
+            operand.args.map(
+                (arg, index) => operandCost(arg, expanded) * argumentWeight(operand.fn, index),
+            ),
+        );
+    }
+    const weight =
+        operand.fn === "dateTrunc"
+            ? EXPANSION_WEIGHTS.dateTrunc[operand.unit]
+            : EXPANSION_WEIGHTS.datePart[operand.unit];
+    return nodeCost([operandCost(operand.of, expanded) * weight]);
+}
+
+/** A filter's size written out: 1 per condition or group plus its parts; a condition's left side is weighted, each literal on its right is 1, and a `{ col }` right side is its weighted operand cost. */
+function filterCost(filter: DatasetFilter, expanded: ReadonlyMap<string, number>): number {
+    if ("not" in filter) return nodeCost([filterCost(filter.not, expanded)]);
+    if ("any" in filter || "all" in filter) {
+        const entries = "any" in filter ? filter.any : filter.all;
+        return nodeCost(entries.map((entry) => filterCost(entry, expanded)));
+    }
+    const right = isColumnValue(filter.value)
+        ? operandCost(filter.value.col, expanded) * EXPANSION_WEIGHTS.conditionRight
+        : Array.isArray(filter.value)
+          ? filter.value.length
+          : filter.value === undefined
+            ? 0
+            : 1;
+    return nodeCost([operandCost(filter.col, expanded) * EXPANSION_WEIGHTS.conditionLeft, right]);
+}
+
+/**
+ * The row a window, a calculation, QUALIFY, sort and rank see: on a grouped
+ * query its keys and aggregates, on a plain one its columns and select
+ * aliases. Windows and calculations join it as they are worked out.
+ */
+function checkFinishedRow(
+    check: QueryCheck,
+    query: DatasetQuery,
+    row: { names: Map<string, DatasetColumnType>; kind: "grouped" | "plain" },
+) {
+    const rowCheck = rowScope(check, row);
+    // On a plain row a selected column is a name too; a window or calculation may not take it.
+    const taken = new Set(
+        (query.select ?? []).flatMap((entry) => (typeof entry === "string" ? [entry] : [])),
+    );
+    checkWindows(rowCheck, query, row.names, taken);
+    checkComputeAndHaving(
+        rowCheck,
+        row.kind === "grouped" ? rowCheck : check,
+        query,
+        row.names,
+        taken,
+    );
+    for (const filter of query.qualify) checkFilter(rowCheck, filter, "qualify");
+    checkRowOrder(check, query, row);
+}
+
+/** A check whose references are the answered row's names; on a plain query a column is one too. */
+function rowScope(check: QueryCheck, row: RowNames) {
+    return {
+        issue: (message: string) => check.issue(message),
+        columnOf(kind, ref) {
+            const type = row.names.get(ref);
+            if (type) return { name: ref, type, description: "" };
+            if (row.kind === "plain") return check.columnOf(kind, ref);
+            check.issue(
+                refError(
+                    kind,
+                    ref,
+                    `${kind} names a group key, an aggregate alias, a window alias or a computed alias`,
+                ),
+            );
+            return undefined;
+        },
+    } satisfies QueryCheck;
+}
+
+/**
+ * Each window over the row it partitions, typed like an aggregate. Every
+ * window reads the row as it was before any window (SQL nests none), so
+ * their aliases join the row only once all are checked.
+ */
+function checkWindows(
+    check: QueryCheck,
+    query: DatasetQuery,
+    rowValues: Map<string, DatasetColumnType>,
+    taken: ReadonlySet<string>,
+) {
+    const answered = new Map<string, DatasetColumnType>();
+    // A window's own name, unless it is already the row's (that is the duplicate the loop reports).
+    const names = new Set(
+        query.window.flatMap((entry) =>
+            rowValues.has(entry.as) || taken.has(entry.as) ? [] : [entry.as],
+        ),
+    );
+    const beforeWindows = {
+        issue: (message: string) => check.issue(message),
+        columnOf(kind, ref) {
+            if (!names.has(ref)) return check.columnOf(kind, ref);
+            check.issue(refError(kind, ref, "a window cannot read another window"));
+            return undefined;
+        },
+    } satisfies QueryCheck;
+    for (const entry of query.window) {
+        if (rowValues.has(entry.as) || answered.has(entry.as) || taken.has(entry.as)) {
+            check.issue(`window alias "${entry.as}" is used twice`);
+        }
+        if (entry.fn === "countDistinct") {
+            check.issue(
+                `window "${entry.as}": countDistinct cannot be a window; SQL allows no DISTINCT in OVER`,
+            );
+        }
+        for (const filter of entry.filter)
+            checkFilter(beforeWindows, filter, `window "${entry.as}" filter`);
+        for (const name of entry.partitionBy)
+            beforeWindows.columnOf(`window "${entry.as}" partitionBy`, name);
+        answered.set(entry.as, aggregateType(beforeWindows, entry, `window "${entry.as}"`));
+    }
+    for (const [as, type] of answered) rowValues.set(as, type);
+}
+
+/**
+ * Calculations are typed in order so a later one may name an earlier one, and
+ * join the row; HAVING then sees the grouped row (keys, aggregates and the
+ * calculations over them), never a window or a calculation over one, which
+ * are worked out after it and belong in QUALIFY.
+ */
+function checkComputeAndHaving(
+    rowCheck: QueryCheck,
+    havingCheck: QueryCheck,
+    query: DatasetQuery,
+    rowValues: Map<string, DatasetColumnType>,
+    taken: ReadonlySet<string>,
+) {
+    const windows = new Set(query.window.map((entry) => entry.as));
+    const late = new Set(windows);
+    const later = new Set(query.compute.map((entry) => entry.as));
+    for (const entry of query.compute) {
+        later.delete(entry.as);
+        if (rowValues.has(entry.as) || taken.has(entry.as)) {
+            rowCheck.issue(`compute alias "${entry.as}" is used twice`);
+        }
+        const refs = operandRefs(entry.expr);
+        const ahead = refs.find(
+            (ref) => (later.has(ref) || ref === entry.as) && !rowValues.has(ref),
+        );
+        if (ahead !== undefined) {
+            rowCheck.issue(
+                refError(
+                    "compute",
+                    ahead,
+                    "is computed after this entry; order compute so each names only earlier ones",
+                ),
+            );
+        }
+        if (refs.some((ref) => late.has(ref))) late.add(entry.as);
+        const type = operandType(rowCheck, "compute", entry.expr);
+        rowValues.set(entry.as, type ?? "number");
+    }
+    const havingRow = {
+        issue: (message: string) => havingCheck.issue(message),
+        columnOf(kind, ref) {
+            if (late.has(ref)) {
+                havingCheck.issue(
+                    refError(kind, ref, "is worked out after HAVING; filter on it in QUALIFY"),
+                );
+                return undefined;
+            }
+            return havingCheck.columnOf(kind, ref);
+        },
+    } satisfies QueryCheck;
+    for (const filter of query.having) checkFilter(havingRow, filter, "having");
+}
+
+/** Every selected column must be reachable and every named value typed; answers the names the row gains. */
+function checkSelect(check: QueryCheck, select: NonNullable<DatasetQuery["select"]>) {
+    const aliases = new Map<string, DatasetColumnType>();
+    const columns = new Set(select.filter((entry) => typeof entry === "string"));
+    for (const entry of select) {
+        if (typeof entry === "string") {
+            check.columnOf("select", entry);
+            continue;
+        }
+        if (aliases.has(entry.as) || columns.has(entry.as)) {
+            check.issue(`select alias "${entry.as}" is used twice`);
+        }
+        aliases.set(entry.as, operandType(check, "select", entry.expr) ?? "string");
+    }
+    return aliases;
+}
+
+/** Sort, rank and offset all speak in the answered row's names. */
+function checkRowOrder(check: QueryCheck, query: DatasetQuery, row: RowNames) {
+    checkSort(check, query.sort, "sort", row);
+    if (query.rank) {
+        for (const col of query.rank.partitionBy) checkRowName(check, "rank", col, row);
+        checkSort(check, query.rank.sort, "rank", row);
+    }
+    if (query.offset !== undefined && query.sort.length === 0) {
+        check.issue("offset needs a sort; without one the rows have no order to skip in");
+    }
+}
+
+/** What each clause check needs: a resolver that records why a reference fails, and a place for other issues. */
+type QueryCheck = {
+    issue(message: string): void;
+    columnOf(kind: string, ref: string): DatasetColumn | undefined;
+};
+
+/** The relation paths the query joins, prefixes included: `plan.ownerDepartment` reaches `plan` too. */
+function joinedPaths(catalog: DatasetCatalog, query: DatasetQuery, issues: string[]) {
+    const joined = new Set<string>();
+    for (const path of query.join) {
+        const probe = resolveDatasetColumn(
+            catalog,
+            query.from,
+            `${path}.${firstColumnOf(catalog, query.from, path)}`,
+        );
+        if (!probe.ok) {
+            issues.push(refError("join", path, probe.error));
+            continue;
+        }
+        const segments = path.split(".");
+        segments.forEach((_, index) => joined.add(segments.slice(0, index + 1).join(".")));
+    }
+    return joined;
+}
+
+/** An operand as the model wrote it, for messages: `a / target`. */
+export function describeOperand(operand: DatasetOperand): string {
+    if (typeof operand !== "object") return String(operand);
+    if ("value" in operand) return JSON.stringify(operand.value);
+    if ("op" in operand) {
+        return `${describeOperand(operand.left)} ${operand.op} ${describeOperand(operand.right)}`;
+    }
+    if ("case" in operand) return "CASE ... END";
+    if ("args" in operand) return `${operand.fn}(${operand.args.map(describeOperand).join(", ")})`;
+    return `${operand.fn}(${operand.unit}, ${describeOperand(operand.of)})`;
+}
+
+/** What each scalar function takes and answers; `coalesce` answers its arguments' shared type. */
+export const FUNCTION_SIGNATURES = {
+    lower: { args: ["string"], answers: "string" },
+    upper: { args: ["string"], answers: "string" },
+    trim: { args: ["string"], answers: "string" },
+    length: { args: ["string"], answers: "number" },
+    abs: { args: ["number"], answers: "number" },
+    round: { args: ["number", "number"], optional: 1, answers: "number" },
+    coalesce: { args: [], answers: undefined },
+} as const satisfies Record<
+    DatasetFunction,
+    {
+        args: readonly DatasetColumnType[];
+        optional?: number;
+        answers: DatasetColumnType | undefined;
+    }
+>;
+
+/**
+ * The type an operand yields: the column's own, number for a literal number
+ * or arithmetic, a date part, a truncated date, a function's answer, or the
+ * type every branch of a CASE shares. Undefined once an issue was recorded.
+ */
+function operandType(
+    check: QueryCheck,
+    kind: string,
+    operand: DatasetOperand,
+): DatasetColumnType | undefined {
+    if (typeof operand === "number") return "number";
+    if (typeof operand === "string") return check.columnOf(kind, operand)?.type;
+    if ("value" in operand) return typeof operand.value === "string" ? "string" : "boolean";
+    const shown = describeOperand(operand);
+    const expect = (side: DatasetOperand, wanted: DatasetColumnType, what: string) => {
+        const type = operandType(check, kind, side);
+        if (type !== undefined && type !== wanted) {
+            check.issue(refError(kind, shown, `${what} needs a ${wanted}, not a ${type}`));
+            return false;
+        }
+        return type !== undefined;
+    };
+    if ("op" in operand) {
+        const fine = [operand.left, operand.right].map((side) =>
+            expect(side, "number", "arithmetic"),
+        );
+        return fine.every(Boolean) ? "number" : undefined;
+    }
+    if ("case" in operand) return caseType(check, kind, operand, shown);
+    if ("args" in operand) return functionType(check, kind, operand, shown, expect);
+    return expect(operand.of, "date", operand.fn)
+        ? operand.fn === "dateTrunc"
+            ? "date"
+            : "number"
+        : undefined;
+}
+
+/** Every branch of a CASE, and its ELSE, answer one type; a CASE without ELSE answers null where nothing matched. */
+function caseType(
+    check: QueryCheck,
+    kind: string,
+    operand: Extract<DatasetOperand, { case: unknown }>,
+    shown: string,
+) {
+    const results = operand.case.map((branch) => {
+        checkFilter(check, branch.when, kind);
+        return operandType(check, kind, branch.then);
+    });
+    if (operand.else !== undefined) results.push(operandType(check, kind, operand.else));
+    return sharedType(check, kind, shown, results, "branches answer");
+}
+
+/** One type across several values (CASE branches, coalesce arguments), or an issue naming the mix. */
+function sharedType(
+    check: QueryCheck,
+    kind: string,
+    shown: string,
+    types: (DatasetColumnType | undefined)[],
+    what: string,
+) {
+    const known = types.filter((type) => type !== undefined);
+    if (new Set(known).size > 1) {
+        check.issue(refError(kind, shown, `${what} a ${known.join(" and a ")}; use one type`));
+        return undefined;
+    }
+    return known.length === types.length ? known[0] : undefined;
+}
+
+function functionType(
+    check: QueryCheck,
+    kind: string,
+    operand: Extract<DatasetOperand, { args: unknown }>,
+    shown: string,
+    expect: (side: DatasetOperand, wanted: DatasetColumnType, what: string) => boolean,
+) {
+    const signature: {
+        args: readonly DatasetColumnType[];
+        optional?: number;
+        answers: DatasetColumnType | undefined;
+    } = FUNCTION_SIGNATURES[operand.fn];
+    if (operand.fn === "coalesce") {
+        if (operand.args.length < 2) {
+            check.issue(refError(kind, shown, "coalesce takes two or more values"));
+            return undefined;
+        }
+        const types = operand.args.map((arg) => operandType(check, kind, arg));
+        return sharedType(check, kind, shown, types, "mixes");
+    }
+    const least = signature.args.length - (signature.optional ?? 0);
+    if (operand.args.length < least || operand.args.length > signature.args.length) {
+        const count =
+            least === signature.args.length ? `${least}` : `${least} or ${signature.args.length}`;
+        check.issue(refError(kind, shown, `${operand.fn} takes ${count} value(s)`));
+        return undefined;
+    }
+    const digits = operand.fn === "round" ? operand.args[1] : undefined;
+    if (
+        digits !== undefined &&
+        (typeof digits !== "number" || !Number.isInteger(digits) || digits < 0 || digits > 10)
+    ) {
+        check.issue(refError(kind, shown, "round takes a whole number of digits from 0 to 10"));
+        return undefined;
+    }
+    const fine = operand.args.map((arg, index) => expect(arg, signature.args[index]!, operand.fn));
+    return fine.every(Boolean) ? signature.answers : undefined;
+}
+
+const COLUMN_COMPARISONS: readonly DatasetFilterOp[] = ["=", "!=", "<", "<=", ">", ">="];
+
+function checkFilter(check: QueryCheck, filter: DatasetFilter, kind = "filter") {
+    if ("not" in filter) {
+        checkFilter(check, filter.not, kind);
+        return;
+    }
+    if ("any" in filter || "all" in filter) {
+        for (const entry of "any" in filter ? filter.any : filter.all)
+            checkFilter(check, entry, kind);
+        return;
+    }
+    const shown = describeOperand(filter.col);
+    const type = operandType(check, kind, filter.col);
+    if (!type) return;
+    const allowed: readonly DatasetFilterOp[] = OPERATORS_BY_TYPE[type];
+    if (!allowed.includes(filter.op)) {
+        check.issue(refError(kind, shown, `${filter.op} is not valid on a ${type} column`));
+        return;
+    }
+    const issue = isColumnValue(filter.value)
+        ? columnValueIssue(check, kind, type, filter.op, filter.value.col)
+        : (filterValueIssue(filter) ??
+          filterValueTypeIssue(type, filter) ??
+          truncatedDateIssue(filter));
+    if (issue) check.issue(refError(kind, shown, issue));
+}
+
+/** A truncated date is a whole day, so a literal against it is one too ("2024-03-01"); a time or a bare month would never match. */
+function truncatedDateIssue(filter: DatasetCondition) {
+    const truncated =
+        typeof filter.col === "object" && "fn" in filter.col && filter.col.fn === "dateTrunc";
+    if (!truncated || filter.value === undefined || isColumnValue(filter.value)) return undefined;
+    const values = Array.isArray(filter.value) ? filter.value : [filter.value];
+    const odd = values.find(
+        (value) => typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value),
+    );
+    return odd === undefined ? undefined : `${JSON.stringify(odd)} is not a whole day (YYYY-MM-DD)`;
+}
+
+/** A right side that is a column or arithmetic: only the six comparisons take it, and its type must match the left side's. */
+function columnValueIssue(
+    check: QueryCheck,
+    kind: string,
+    type: DatasetColumnType,
+    op: DatasetFilterOp,
+    right: DatasetOperand,
+) {
+    if (!COLUMN_COMPARISONS.includes(op)) return `${op} takes a literal, not a column`;
+    const rightType = operandType(check, kind, right);
+    return rightType && rightType !== type ? `compares a ${type} with a ${rightType}` : undefined;
+}
+
+/** A value the column's type cannot hold is refused here, not answered as an empty result by the host. */
+function filterValueTypeIssue(type: DatasetColumnType, filter: DatasetCondition) {
+    if (filter.value === undefined || isColumnValue(filter.value)) return undefined;
+    const values = Array.isArray(filter.value) ? filter.value : [filter.value];
+    const fits = (value: string | number | boolean) => {
+        switch (type) {
+            case "number":
+                return (
+                    typeof value === "number" ||
+                    (typeof value === "string" &&
+                        value.trim() !== "" &&
+                        Number.isFinite(Number(value)))
+                );
+            case "date":
+                return typeof value === "string" && !Number.isNaN(Date.parse(value));
+            case "boolean":
+                return typeof value === "boolean" || value === "true" || value === "false";
+            case "string":
+                return true;
+        }
+    };
+    const odd = values.find((value) => !fits(value));
+    return odd === undefined ? undefined : `${JSON.stringify(odd)} is not a ${type}`;
+}
+
+/** Each group key with the type its value has: a column's own, or what the named value answers. */
+function checkGroupBy(check: QueryCheck, groupBy: DatasetQuery["groupBy"]) {
+    const groupKeys = new Map<string, DatasetColumnType>();
+    for (const group of groupBy) {
+        const name = groupKeyName(group);
+        if (typeof group !== "string" && operandRefs(group.expr).length === 0) {
+            check.issue(
+                refError("groupBy", name, "a group key reads a column; a constant groups nothing"),
+            );
+        }
+        const type =
+            typeof group === "string"
+                ? check.columnOf("groupBy", group)?.type
+                : operandType(check, "groupBy", group.expr);
+        // Row keys are the names as written, so a name may appear once.
+        if (groupKeys.has(name)) check.issue(refError("groupBy", name, "is grouped twice"));
+        groupKeys.set(name, type ?? "string");
+    }
+    return groupKeys;
+}
+
+/** Each alias with the type its value has, what HAVING and sort may name. */
+function checkAggregates(check: QueryCheck, aggregates: DatasetQuery["aggregate"]) {
+    const aliases = new Map<string, DatasetColumnType>();
+    for (const aggregate of aggregates) {
+        if (aliases.has(aggregate.as))
+            check.issue(`aggregate alias "${aggregate.as}" is used twice`);
+        for (const filter of aggregate.filter)
+            checkFilter(check, filter, `aggregate "${aggregate.as}" filter`);
+        aliases.set(aggregate.as, aggregateType(check, aggregate));
+    }
+    return aliases;
+}
+
+/** The type an aggregate answers: number for counts, sums and averages, the operand's own for min and max. */
+function aggregateType(
+    check: QueryCheck,
+    aggregate: DatasetQuery["aggregate"][number],
+    label = `aggregate "${aggregate.as}"`,
+) {
+    if (aggregate.col === undefined) {
+        if (aggregate.fn !== "count") check.issue(`${label}: ${aggregate.fn} needs a column`);
+        return "number";
+    }
+    const kind = label.startsWith("window") ? label : "aggregate";
+    const type = operandType(check, kind, aggregate.col);
+    const numeric = aggregate.fn === "sum" || aggregate.fn === "avg";
+    if (type && numeric && type !== "number") {
+        check.issue(
+            refError(kind, describeOperand(aggregate.col), `${aggregate.fn} needs a number column`),
+        );
+    }
+    const counts = aggregate.fn === "count" || aggregate.fn === "countDistinct";
+    return counts || numeric ? "number" : (type ?? "number");
+}
+
+/** What sort and rank may name: on a grouped query a group key or an alias; on a plain one a select alias or any reachable column. */
+type RowNames = { names: ReadonlyMap<string, DatasetColumnType>; kind: "grouped" | "plain" };
+
+function checkSort(check: QueryCheck, sort: DatasetQuery["sort"], kind: string, row: RowNames) {
+    for (const { col } of sort) checkRowName(check, kind, col, row);
+}
+
+function checkRowName(check: QueryCheck, kind: string, name: string, row: RowNames) {
+    if (row.names.has(name)) return;
+    if (row.kind === "plain") {
+        check.columnOf(kind, name);
+        return;
+    }
+    check.issue(
+        refError(
+            kind,
+            name,
+            "a grouped query names a group key, an aggregate alias, a window alias or a computed alias",
+        ),
+    );
+}
+
+/** Any column of the dataset a relation path reaches, so a bare path can be probed through the column resolver. */
+function firstColumnOf(catalog: DatasetCatalog, from: string, path: string) {
+    let dataset = catalog.get(from);
+    for (const segment of path.split(".")) {
+        const target = dataset?.relations[segment];
+        dataset = target ? catalog.get(target.dataset) : undefined;
+    }
+    return dataset?.columns[0]?.name ?? "";
+}