@hypequery/datasets 0.23.1 → 0.25.0

package/dist/utils/dataset-time-keys.js

@@ -0,0 +1,55 @@
+/**
+ * Multiple time axes per dataset (HQ-80).
+ *
+ * `timeKey` is a dataset's default time axis; `timeKeys` names the other axes
+ * a query may select with `query.timeKey`, such as `shipped_at` beside
+ * `created_at`. A query on another axis compiles against a view of the dataset
+ * whose `timeKey` is that axis, so grains, windows, shifts and time-range
+ * checks follow the selection without each of them knowing about it.
+ */
+/** Every time axis a query may select, the default first; empty without a `timeKey`. */
+export function datasetTimeKeys(dataset) {
+    if (!dataset.timeKey)
+        return [];
+    return [dataset.timeKey, ...(dataset.timeKeys ?? []).filter(key => key !== dataset.timeKey)];
+}
+/** The validation message for a query's `timeKey` selection, or undefined. */
+export function selectedTimeKeyError(dataset, timeKey) {
+    if (timeKey === undefined)
+        return undefined;
+    if (typeof timeKey !== 'string')
+        return 'Invalid timeKey: expected a string.';
+    const keys = datasetTimeKeys(dataset);
+    if (keys.length === 0) {
+        return `Cannot select timeKey "${timeKey}" — dataset "${dataset.name}" has no timeKey.`;
+    }
+    if (!keys.includes(timeKey)) {
+        return `Unknown timeKey "${timeKey}" on dataset "${dataset.name}". Available: ${keys.join(', ')}`;
+    }
+    return undefined;
+}
+/**
+ * True when a query selects an axis other than the dataset's default. Naming
+ * the default explicitly is the same query as omitting it.
+ */
+export function selectsAlternateTimeKey(dataset, timeKey) {
+    return timeKey !== undefined && timeKey !== dataset.timeKey;
+}
+/**
+ * The dataset as seen by a query on `timeKey`: the selected axis becomes
+ * `timeKey` and the rest stay declared, so the view is itself a valid dataset
+ * and rebasing it again is a no-op. Throws for an axis the dataset does not
+ * declare; validate first to report it as a query error.
+ */
+export function datasetOnTimeKey(dataset, timeKey) {
+    if (!selectsAlternateTimeKey(dataset, timeKey))
+        return dataset;
+    const error = selectedTimeKeyError(dataset, timeKey);
+    if (error)
+        throw new Error(error);
+    return {
+        ...dataset,
+        timeKey,
+        timeKeys: Object.freeze(datasetTimeKeys(dataset).filter(key => key !== timeKey)),
+    };
+}

package/dist/utils/dataset-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAYrB,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,kBAAkB,EACtB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,GACvC,IAAI,CA0DN;AAED,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,kBAAkB,EACtB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAClC,IAAI,CAmBN"}
+{"version":3,"file":"dataset-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAarB,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,kBAAkB,EACtB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,GACvC,IAAI,CAiEN;AAED,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,kBAAkB,EACtB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAClC,IAAI,CAmBN"}

package/dist/utils/dataset-validation.js

@@ -1,5 +1,6 @@
 import { validateFilterValue } from '../validation.js';
 import { validatePercentileLevel } from '../measure.js';
+import { assertAggregateStateFunction } from './aggregate-state-functions.js';
 const NUMERIC_FIELD_TYPES = new Set(['number']);
 // Aggregations whose output tracks the input field's type, so a metric
 // (contract valueType: 'number') needs a numeric input dimension.
@@ -15,6 +16,12 @@ export function validateBaseMetric(ds, metricName, spec, options) {
             throw new Error(`Invalid metric "${metricName}": measure filters are not supported on ${spec.aggregation} aggregations.`);
         }
     }
+    if (spec.aggregation === 'merge') {
+        assertAggregateStateFunction(spec.stateFunction, `Invalid metric "${metricName}":`);
+        if (spec.filters?.length) {
+            throw new Error(`Invalid metric "${metricName}": measure filters are not supported on merge aggregations.`);
+        }
+    }
     if (spec.aggregation === 'percentile') {
         if (spec.level == null) {
             throw new Error(`Invalid metric "${metricName}": percentile() requires a level.`);

package/dist/utils/deployable-formulas.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The subset of derived-measure formulas a deployment contract accepts.
+ *
+ * Local planning accepts every formula the helpers can build. The RFC 0006
+ * deployment grammar is narrower: a derived measure may reference only base
+ * measures, and a literal may appear only as `round` decimals or as a
+ * `coalesce` fallback. Checking that subset against the definition, rather
+ * than the emitted contract, lets the failure name the dataset and measure
+ * instead of a JSON path such as `$.datasets[2].measures[19].expression.right`.
+ */
+import type { AnyDatasetInstance, DatasetMeasureDefinition, DerivedMeasureDefinition } from '../types.js';
+/**
+ * Why `definition` cannot be deployed, or `undefined` when it can.
+ *
+ * `measures` are the measures of the dataset that owns the definition. The
+ * dataset has already validated references, aliases and cycles, so only the
+ * deployment-specific restrictions are reported here.
+ */
+export declare function deployableFormulaIssue(definition: DerivedMeasureDefinition, measures: Readonly<Record<string, DatasetMeasureDefinition>>): string | undefined;
+/** Every `[measure name, issue]` pair among a dataset's derived measures, in definition order. */
+export declare function deployableMeasureIssues(measures: Readonly<Record<string, DatasetMeasureDefinition>> | undefined): Array<[string, string]>;
+/**
+ * Refuse a dataset whose derived measures the deployment contract cannot carry.
+ *
+ * Local queries accept every formula the helpers build. A deployment contract
+ * accepts a narrower subset: derived measures may reference only base measures,
+ * and a literal may appear only as `round` decimals or as a `coalesce`
+ * fallback. `buildProtocolDeploymentContract` (and so `hypequery deploy`) runs
+ * this check first, so the error names the dataset and measure
+ * (`orders.doubled: ...`) instead of a contract path.
+ */
+export declare function assertDeployable(dataset: AnyDatasetInstance): void;
+//# sourceMappingURL=deployable-formulas.d.ts.map

package/dist/utils/deployable-formulas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployable-formulas.d.ts","sourceRoot":"","sources":["../../src/utils/deployable-formulas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AA6C1G;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,wBAAwB,EACpC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,GAC3D,MAAM,GAAG,SAAS,CAYpB;AAED,kGAAkG;AAClG,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,GAAG,SAAS,GACvE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAOzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAMlE"}

package/dist/utils/deployable-formulas.js

@@ -0,0 +1,102 @@
+/**
+ * The subset of derived-measure formulas a deployment contract accepts.
+ *
+ * Local planning accepts every formula the helpers can build. The RFC 0006
+ * deployment grammar is narrower: a derived measure may reference only base
+ * measures, and a literal may appear only as `round` decimals or as a
+ * `coalesce` fallback. Checking that subset against the definition, rather
+ * than the emitted contract, lets the failure name the dataset and measure
+ * instead of a JSON path such as `$.datasets[2].measures[19].expression.right`.
+ */
+import { isDerivedMeasure, splitDatasetMeasures } from './dataset-measures.js';
+const LITERAL_POSITIONS = 'literals are only accepted as round decimals or a coalesce fallback';
+function literalIssue(expression, where) {
+    if (expression.kind !== 'literal')
+        return undefined;
+    return `a numeric literal cannot be ${where} in a deployable formula; ${LITERAL_POSITIONS}`;
+}
+/** Why `expression` cannot be deployed, or `undefined` when it can. */
+function expressionIssue(expression) {
+    switch (expression.kind) {
+        case 'ref':
+            return undefined;
+        case 'literal':
+            return `a literal cannot be a deployable formula on its own; ${LITERAL_POSITIONS}`;
+        case 'binary':
+            for (const operand of [expression.left, expression.right]) {
+                const issue = literalIssue(operand, 'an arithmetic operand') ?? expressionIssue(operand);
+                if (issue !== undefined)
+                    return issue;
+            }
+            return undefined;
+        case 'function': {
+            const [first, second] = expression.args;
+            if (first === undefined)
+                return undefined;
+            const issue = literalIssue(first, `the value passed to ${expression.name}`) ?? expressionIssue(first);
+            if (issue !== undefined || second === undefined)
+                return issue;
+            if (expression.name === 'round') {
+                return second.kind === 'literal' && typeof second.value === 'number'
+                    ? undefined
+                    : 'round decimals must be a numeric literal in a deployable formula';
+            }
+            if (expression.name === 'coalesce' && second.kind === 'literal') {
+                return typeof second.value === 'number'
+                    ? undefined
+                    : 'a coalesce fallback must be a number in a deployable formula; null, booleans and strings are not accepted';
+            }
+            return expressionIssue(second);
+        }
+        default:
+            return 'formula contains an unsupported expression kind';
+    }
+}
+/**
+ * Why `definition` cannot be deployed, or `undefined` when it can.
+ *
+ * `measures` are the measures of the dataset that owns the definition. The
+ * dataset has already validated references, aliases and cycles, so only the
+ * deployment-specific restrictions are reported here.
+ */
+export function deployableFormulaIssue(definition, measures) {
+    // Window and shift inputs are refused by the contract adapter itself, with
+    // the contract version as the reason; only a derived input is reported here.
+    for (const [alias, measureName] of Object.entries(definition.uses)) {
+        const input = Object.hasOwn(measures, measureName) ? measures[measureName] : undefined;
+        if (!isDerivedMeasure(input))
+            continue;
+        const spelled = alias === measureName ? `"${measureName}"` : `"${measureName}" (as "${alias}")`;
+        return `references derived measure ${spelled}; a deployable formula may only reference base measures, `
+            + 'so inline that formula or reference the base measures directly';
+    }
+    const aliases = Object.fromEntries(Object.keys(definition.uses).map(alias => [alias, alias]));
+    return expressionIssue(definition.formula(aliases).expression);
+}
+/** Every `[measure name, issue]` pair among a dataset's derived measures, in definition order. */
+export function deployableMeasureIssues(measures) {
+    const issues = [];
+    for (const [name, definition] of Object.entries(splitDatasetMeasures(measures).derived)) {
+        const issue = deployableFormulaIssue(definition, measures ?? {});
+        if (issue !== undefined)
+            issues.push([name, issue]);
+    }
+    return issues;
+}
+/**
+ * Refuse a dataset whose derived measures the deployment contract cannot carry.
+ *
+ * Local queries accept every formula the helpers build. A deployment contract
+ * accepts a narrower subset: derived measures may reference only base measures,
+ * and a literal may appear only as `round` decimals or as a `coalesce`
+ * fallback. `buildProtocolDeploymentContract` (and so `hypequery deploy`) runs
+ * this check first, so the error names the dataset and measure
+ * (`orders.doubled: ...`) instead of a contract path.
+ */
+export function assertDeployable(dataset) {
+    const [first] = deployableMeasureIssues(dataset.measures);
+    if (first !== undefined) {
+        const [name, issue] = first;
+        throw new Error(`${dataset.name}.${name}: ${issue}`);
+    }
+}

package/dist/utils/derived-cte-validation.d.ts

@@ -1,3 +1,8 @@
+/**
+ * The top-level GROUP BY terms of a statement. Scans rather than matching a
+ * regex, so quoted names (`limit`), string literals and nested calls with
+ * commas neither end the clause nor split a term.
+ */
 export declare function extractGroupByExpressions(sql: string): string[];
 export declare function validateDerivedCteGrouping(sql: string, aggregateAliases: string[], intendedGroupBy: string[]): string[];
 //# sourceMappingURL=derived-cte-validation.d.ts.map

package/dist/utils/derived-cte-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derived-cte-validation.d.ts","sourceRoot":"","sources":["../../src/utils/derived-cte-validation.ts"],"names":[],"mappings":"AAAA,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAU/D;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,gBAAgB,EAAE,MAAM,EAAE,EAC1B,eAAe,EAAE,MAAM,EAAE,GACxB,MAAM,EAAE,CAgCV"}
+{"version":3,"file":"derived-cte-validation.d.ts","sourceRoot":"","sources":["../../src/utils/derived-cte-validation.ts"],"names":[],"mappings":"AA6BA;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CA4B/D;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,gBAAgB,EAAE,MAAM,EAAE,EAC1B,eAAe,EAAE,MAAM,EAAE,GACxB,MAAM,EAAE,CAkCV"}

package/dist/utils/derived-cte-validation.js

@@ -1,16 +1,85 @@
+/** Compare identifiers by name, whether or not the planner or builder quoted them. */
+function identifierName(expression) {
+    const quote = expression[0];
+    if ((quote === '`' || quote === '"') && expression.length > 1 && expression.endsWith(quote)) {
+        return expression.slice(1, -1).split(quote + quote).join(quote);
+    }
+    return expression;
+}
+const GROUP_BY_START = /^GROUP\s+BY\b/i;
+const GROUP_BY_END = /^(?:HAVING|ORDER\s+BY|LIMIT|OFFSET)\b/i;
+/** Index just past the quoted identifier or string at `index`, or `index` when none starts there. */
+function skipQuoted(sql, index) {
+    const quote = sql[index];
+    if (quote !== '`' && quote !== '"' && quote !== "'")
+        return index;
+    let i = index + 1;
+    while (i < sql.length) {
+        if (sql[i] === '\\') {
+            i += 2;
+            continue;
+        }
+        if (sql[i] === quote) {
+            if (sql[i + 1] !== quote)
+                return i + 1;
+            i += 2;
+            continue;
+        }
+        i++;
+    }
+    return i;
+}
+/**
+ * The top-level GROUP BY terms of a statement. Scans rather than matching a
+ * regex, so quoted names (`limit`), string literals and nested calls with
+ * commas neither end the clause nor split a term.
+ */
 export function extractGroupByExpressions(sql) {
-    const match = sql.match(/\bGROUP BY\b\s+(.+?)(?:\bHAVING\b|\bORDER BY\b|\bLIMIT\b|\bOFFSET\b|$)/is);
-    if (!match) {
-        return [];
+    const terms = [];
+    let depth = 0;
+    let termStart = -1;
+    let i = 0;
+    while (i < sql.length) {
+        const quotedEnd = skipQuoted(sql, i);
+        if (quotedEnd > i) {
+            i = quotedEnd;
+            continue;
+        }
+        const char = sql[i];
+        if (char === '(')
+            depth++;
+        else if (char === ')')
+            depth--;
+        else if (depth === 0) {
+            const atWord = /[A-Za-z]/.test(char) && (i === 0 || !/[\w$]/.test(sql[i - 1]));
+            if (termStart < 0 && atWord) {
+                const start = sql.slice(i).match(GROUP_BY_START);
+                if (start) {
+                    i += start[0].length;
+                    termStart = i;
+                    continue;
+                }
+            }
+            else if (termStart >= 0 && atWord && GROUP_BY_END.test(sql.slice(i))) {
+                break;
+            }
+            else if (termStart >= 0 && char === ',') {
+                terms.push(sql.slice(termStart, i));
+                termStart = i + 1;
+            }
+        }
+        i++;
     }
-    return match[1]
-        .split(',')
-        .map(part => part.trim())
-        .filter(Boolean);
+    if (termStart < 0)
+        return [];
+    terms.push(sql.slice(termStart, i));
+    return terms.map(term => term.trim()).filter(Boolean);
 }
 export function validateDerivedCteGrouping(sql, aggregateAliases, intendedGroupBy) {
     const errors = [];
-    const actualGroupBy = extractGroupByExpressions(sql);
+    const actualGroupBy = extractGroupByExpressions(sql).map(identifierName);
+    aggregateAliases = aggregateAliases.map(identifierName);
+    intendedGroupBy = intendedGroupBy.map(identifierName);
     if (intendedGroupBy.length === 0 && actualGroupBy.length > 0) {
         errors.push('Derived metric planner emitted GROUP BY for an ungrouped query.');
     }

package/dist/utils/derived-measure-sql.d.ts

@@ -1,4 +1,12 @@
+import type { DatasetSqlDialectRules } from '../dataset-sql-dialect.js';
+import type { SemanticExpression } from '../semantic-plan.js';
 import type { DerivedMeasureDefinition } from '../types.js';
-export declare function derivedExpressionSql(definition: DerivedMeasureDefinition, resolve?: (name: string) => string): string;
-export declare function derivedProjection(name: string, definition: DerivedMeasureDefinition): string;
+/**
+ * Render a formula through the dialect. `resolveRef` maps each formula input
+ * to the SQL that reads it, and rejects inputs the formula did not declare.
+ * The one formula renderer for derived measures and derived metrics.
+ */
+export declare function formulaExpressionSql(dialect: DatasetSqlDialectRules, expression: SemanticExpression, resolveRef: (name: string) => string): string;
+export declare function derivedExpressionSql(dialect: DatasetSqlDialectRules, definition: DerivedMeasureDefinition, resolve?: (name: string) => string): string;
+export declare function derivedProjection(dialect: DatasetSqlDialectRules, name: string, definition: DerivedMeasureDefinition): string;
 //# sourceMappingURL=derived-measure-sql.d.ts.map

package/dist/utils/derived-measure-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derived-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/derived-measure-sql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAyC5D,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,wBAAwB,EAAE,OAAO,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAA2B,GAAG,MAAM,CAGzI;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,wBAAwB,GAAG,MAAM,CAE5F"}
+{"version":3,"file":"derived-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/derived-measure-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAE5D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,sBAAsB,EAC/B,UAAU,EAAE,kBAAkB,EAC9B,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GACnC,MAAM,CAeR;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,sBAAsB,EAC/B,UAAU,EAAE,wBAAwB,EACpC,OAAO,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAgC,GAC1D,MAAM,CAQR;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,sBAAsB,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,wBAAwB,GAAG,MAAM,CAE7H"}

package/dist/utils/derived-measure-sql.js

@@ -1,49 +1,29 @@
-import { quoteSQLIdentifier } from '../sql-utils.js';
-function expressionSql(expression, uses, resolve) {
+/**
+ * Render a formula through the dialect. `resolveRef` maps each formula input
+ * to the SQL that reads it, and rejects inputs the formula did not declare.
+ * The one formula renderer for derived measures and derived metrics.
+ */
+export function formulaExpressionSql(dialect, expression, resolveRef) {
     switch (expression.kind) {
-        case 'ref': {
-            if (!Object.hasOwn(uses, expression.name)) {
-                throw new Error(`Formula references undeclared input "${expression.name}".`);
-            }
-            const measureName = uses[expression.name];
-            return resolve(measureName);
-        }
-        case 'literal': {
-            if (expression.value === null)
-                return 'NULL';
-            if (typeof expression.value === 'number') {
-                if (!Number.isFinite(expression.value))
-                    throw new Error('Formula contains a non-finite number.');
-                return String(expression.value);
-            }
-            if (typeof expression.value === 'boolean')
-                return expression.value ? 'true' : 'false';
-            return `'${expression.value.replace(/\\/g, '\\\\').replace(/'/g, "''")}'`;
-        }
-        case 'binary': {
-            const operators = { add: '+', subtract: '-', multiply: '*', divide: '/' };
-            const operator = operators[expression.operator];
-            if (!operator)
-                throw new Error('Formula contains an unsupported binary operator.');
-            return `(${expressionSql(expression.left, uses, resolve)} ${operator} ${expressionSql(expression.right, uses, resolve)})`;
-        }
-        case 'function': {
-            const args = expression.args.map(arg => expressionSql(arg, uses, resolve));
-            switch (expression.name) {
-                case 'nullIfZero': return `NULLIF(${args[0]}, 0)`;
-                case 'coalesce': return `COALESCE(${args.join(', ')})`;
-                case 'round': return `ROUND(${args.join(', ')})`;
-                case 'floor': return `FLOOR(${args[0]})`;
-                case 'ceil': return `CEIL(${args[0]})`;
-                default: throw new Error('Formula contains an unsupported function.');
-            }
-        }
+        case 'ref':
+            return resolveRef(expression.name);
+        case 'literal':
+            return dialect.formulaLiteral(expression.value);
+        case 'binary':
+            return dialect.formulaBinary(expression.operator, formulaExpressionSql(dialect, expression.left, resolveRef), formulaExpressionSql(dialect, expression.right, resolveRef));
+        case 'function':
+            return dialect.formulaFunction(expression.name, expression.args.map(arg => formulaExpressionSql(dialect, arg, resolveRef)));
     }
 }
-export function derivedExpressionSql(definition, resolve = quoteSQLIdentifier) {
+export function derivedExpressionSql(dialect, definition, resolve = dialect.quoteIdentifier) {
     const aliases = Object.fromEntries(Object.keys(definition.uses).map(alias => [alias, alias]));
-    return expressionSql(definition.formula(aliases).expression, definition.uses, resolve);
+    return formulaExpressionSql(dialect, definition.formula(aliases).expression, name => {
+        if (!Object.hasOwn(definition.uses, name)) {
+            throw new Error(`Formula references undeclared input "${name}".`);
+        }
+        return resolve(definition.uses[name]);
+    });
 }
-export function derivedProjection(name, definition) {
-    return `${derivedExpressionSql(definition)} AS ${quoteSQLIdentifier(name)}`;
+export function derivedProjection(dialect, name, definition) {
+    return `${derivedExpressionSql(dialect, definition)} AS ${dialect.quoteIdentifier(name)}`;
 }

package/dist/utils/enforced-constraints.d.ts

@@ -0,0 +1,14 @@
+import type { AnyDatasetInstance, ExecutionContext } from '../types.js';
+/** Constraints are policy, not queries; a handful per call is plenty (RFC 0019). */
+export declare const MAX_ENFORCED_CONSTRAINTS = 32;
+/**
+ * Errors for the call's RFC 0019 enforced constraints on `ds`. A constraint
+ * the dataset cannot enforce refuses the call, with a message that does not
+ * describe the constraint: it is the provider's policy, not the caller's
+ * input. `callerFilters` is the number of filters the caller supplied, which
+ * share the dataset's filter ceiling with the constraints.
+ */
+export declare function enforcedConstraintErrors(ds: AnyDatasetInstance, context: ExecutionContext | undefined, callerFilters: number): string[];
+/** Throws when the call's constraints cannot all be enforced on `ds`. */
+export declare function assertEnforcedConstraints(ds: AnyDatasetInstance, context?: ExecutionContext): void;
+//# sourceMappingURL=enforced-constraints.d.ts.map

package/dist/utils/enforced-constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforced-constraints.d.ts","sourceRoot":"","sources":["../../src/utils/enforced-constraints.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAgB,MAAM,aAAa,CAAC;AAKtF,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAiB3C;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,gBAAgB,GAAG,SAAS,EACrC,aAAa,EAAE,MAAM,GACpB,MAAM,EAAE,CAaV;AAED,yEAAyE;AACzE,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAGlG"}

package/dist/utils/enforced-constraints.js

@@ -0,0 +1,57 @@
+import { isSemanticFilterOperator } from '../constants.js';
+import { validateFilterValue } from '../validation.js';
+import { isQualifiedField, resolveQualifiedField } from './relationship-fields.js';
+import { validateQualifiedFilter } from './relationship-validation.js';
+/** Constraints are policy, not queries; a handful per call is plenty (RFC 0019). */
+export const MAX_ENFORCED_CONSTRAINTS = 32;
+function constraintError(ds, constraint, context) {
+    if (typeof constraint !== 'object' || constraint === null)
+        return true;
+    const filter = constraint;
+    if (typeof filter.field !== 'string' || !isSemanticFilterOperator(filter.operator))
+        return true;
+    if (isQualifiedField(filter.field)) {
+        if (!resolveQualifiedField(ds, filter.field)?.resolved)
+            return true;
+        return validateQualifiedFilter(ds, filter, context) !== null;
+    }
+    if (!Object.hasOwn(ds.filters, filter.field))
+        return true;
+    const definition = ds.filters[filter.field];
+    if (definition.operators && !definition.operators.includes(filter.operator))
+        return true;
+    const fieldType = ds.dimensions[definition.field ?? filter.field]?.fieldType;
+    return !!fieldType && validateFilterValue(filter, fieldType) !== null;
+}
+/**
+ * Errors for the call's RFC 0019 enforced constraints on `ds`. A constraint
+ * the dataset cannot enforce refuses the call, with a message that does not
+ * describe the constraint: it is the provider's policy, not the caller's
+ * input. `callerFilters` is the number of filters the caller supplied, which
+ * share the dataset's filter ceiling with the constraints.
+ */
+export function enforcedConstraintErrors(ds, context, callerFilters) {
+    const constraints = context?.runtime?.constraints;
+    if (constraints === undefined)
+        return [];
+    const unenforceable = [`Dataset "${ds.name}" cannot enforce a runtime constraint.`];
+    if (!Array.isArray(constraints) || constraints.length > MAX_ENFORCED_CONSTRAINTS)
+        return unenforceable;
+    if (constraints.length === 0)
+        return [];
+    const maxFilters = ds.limits?.maxFilters;
+    if (maxFilters && constraints.length > maxFilters)
+        return unenforceable;
+    if (constraints.some(constraint => constraintError(ds, constraint, context)))
+        return unenforceable;
+    if (maxFilters && callerFilters > maxFilters - constraints.length) {
+        return [`Too many filters: ${callerFilters} (max ${maxFilters - constraints.length} under the enforced constraints)`];
+    }
+    return [];
+}
+/** Throws when the call's constraints cannot all be enforced on `ds`. */
+export function assertEnforcedConstraints(ds, context) {
+    const [error] = enforcedConstraintErrors(ds, context, 0);
+    if (error)
+        throw new Error(error);
+}

package/dist/utils/filter-field-type.d.ts

@@ -0,0 +1,14 @@
+import type { AnyDatasetInstance, FieldType } from '../types.js';
+/**
+ * The semantic field type behind a caller filter: a filter alias, a dimension
+ * name, or a relationship-qualified target dimension. Undefined when the
+ * field does not resolve to a declared dimension.
+ */
+export declare function resolveFilterFieldType(ds: AnyDatasetInstance, filterField: string): FieldType | undefined;
+/**
+ * The field type of a dimension named directly, as segment filters name them.
+ * Filter aliases are not consulted: an alias may share a dimension's name
+ * while pointing at a different dimension.
+ */
+export declare function resolveDimensionFieldType(ds: AnyDatasetInstance, dimensionName: string): FieldType | undefined;
+//# sourceMappingURL=filter-field-type.d.ts.map

package/dist/utils/filter-field-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-field-type.d.ts","sourceRoot":"","sources":["../../src/utils/filter-field-type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGjE;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAMzG;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAE9G"}

package/dist/utils/filter-field-type.js

@@ -0,0 +1,21 @@
+import { isQualifiedField, resolveQualifiedField } from './relationship-fields.js';
+/**
+ * The semantic field type behind a caller filter: a filter alias, a dimension
+ * name, or a relationship-qualified target dimension. Undefined when the
+ * field does not resolve to a declared dimension.
+ */
+export function resolveFilterFieldType(ds, filterField) {
+    if (isQualifiedField(filterField)) {
+        return resolveQualifiedField(ds, filterField)?.resolved?.targetDimension.fieldType;
+    }
+    const resolvedField = ds.filters[filterField]?.field ?? filterField;
+    return ds.dimensions[resolvedField]?.fieldType;
+}
+/**
+ * The field type of a dimension named directly, as segment filters name them.
+ * Filter aliases are not consulted: an alias may share a dimension's name
+ * while pointing at a different dimension.
+ */
+export function resolveDimensionFieldType(ds, dimensionName) {
+    return ds.dimensions[dimensionName]?.fieldType;
+}

package/dist/utils/filtered-aggregation-sql.d.ts

@@ -1,6 +1,7 @@
 import type { AggregationSpec, AnyDatasetInstance } from '../types.js';
 import type { RelationshipBuilderContext } from './relationship-builder-plan.js';
+import type { DatasetSqlDialectRules } from '../dataset-sql-dialect.js';
 type DatasetShape = AnyDatasetInstance;
-export declare function applyFilteredAggregationExpression(ds: DatasetShape, spec: AggregationSpec, fieldOrExpr: string, joinCtx?: RelationshipBuilderContext): string;
+export declare function applyFilteredAggregationExpression(ds: DatasetShape, spec: AggregationSpec, fieldOrExpr: string, joinCtx: RelationshipBuilderContext | undefined, dialect: DatasetSqlDialectRules): string;
 export {};
 //# sourceMappingURL=filtered-aggregation-sql.d.ts.map

package/dist/utils/filtered-aggregation-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filtered-aggregation-sql.d.ts","sourceRoot":"","sources":["../../src/utils/filtered-aggregation-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAgB,MAAM,aAAa,CAAC;AAErF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAEjF,KAAK,YAAY,GAAG,kBAAkB,CAAC;AAqEvC,wBAAgB,kCAAkC,CAChD,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CAgCR"}
+{"version":3,"file":"filtered-aggregation-sql.d.ts","sourceRoot":"","sources":["../../src/utils/filtered-aggregation-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAgB,MAAM,aAAa,CAAC;AAErF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AACjF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAExE,KAAK,YAAY,GAAG,kBAAkB,CAAC;AA6CvC,wBAAgB,kCAAkC,CAChD,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,0BAA0B,GAAG,SAAS,EAC/C,OAAO,EAAE,sBAAsB,GAC9B,MAAM,CAmCR"}