@hypequery/datasets 0.23.1 → 0.24.0

package/dist/utils/dataset-having.d.ts

@@ -1,4 +1,5 @@
 import type { AnyDatasetInstance, DatasetHavingCondition, DatasetQuery } from '../types.js';
+import type { StatementParameters } from './statement-parameters.js';
 /**
  * Validates `having` conditions against the query they belong to.
  *
@@ -8,14 +9,11 @@ import type { AnyDatasetInstance, DatasetHavingCondition, DatasetQuery } from '.
  */
 export declare function datasetHavingErrors(ds: AnyDatasetInstance, query: DatasetQuery, selectedMeasures: readonly string[]): string[];
 /**
- * Renders validated `having` conditions as one parameterized predicate.
+ * Renders validated `having` conditions as one predicate.
  *
  * `measureSql` maps a selected measure to the expression that reads its
- * aggregated value in the outer query. Values are only ever bound as `?`
- * parameters, appended in placeholder order.
+ * aggregated value in the outer query. Values are only ever bound through
+ * `statement`, never written into the SQL text.
  */
-export declare function datasetHavingSql(conditions: readonly DatasetHavingCondition[], measureSql: (measure: string) => string): {
-    sql: string;
-    parameters: unknown[];
-};
+export declare function datasetHavingSql(conditions: readonly DatasetHavingCondition[], measureSql: (measure: string) => string, statement: StatementParameters): string;
 //# sourceMappingURL=dataset-having.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"dataset-having.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-having.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAmC5F;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,gBAAgB,EAAE,SAAS,MAAM,EAAE,GAClC,MAAM,EAAE,CA0CV;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,SAAS,sBAAsB,EAAE,EAC7C,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GACtC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,EAAE,CAAA;CAAE,CAmBxC"}
+{"version":3,"file":"dataset-having.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-having.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE5F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAkCrE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,gBAAgB,EAAE,SAAS,MAAM,EAAE,GAClC,MAAM,EAAE,CA0CV;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,SAAS,sBAAsB,EAAE,EAC7C,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,EACvC,SAAS,EAAE,mBAAmB,GAC7B,MAAM,CAgBR"}

package/dist/utils/dataset-having.js

@@ -77,30 +77,27 @@ export function datasetHavingErrors(ds, query, selectedMeasures) {
     return errors;
 }
 /**
- * Renders validated `having` conditions as one parameterized predicate.
+ * Renders validated `having` conditions as one predicate.
  *
  * `measureSql` maps a selected measure to the expression that reads its
- * aggregated value in the outer query. Values are only ever bound as `?`
- * parameters, appended in placeholder order.
+ * aggregated value in the outer query. Values are only ever bound through
+ * `statement`, never written into the SQL text.
  */
-export function datasetHavingSql(conditions, measureSql) {
-    const parameters = [];
+export function datasetHavingSql(conditions, measureSql, statement) {
+    const bind = (value) => statement.bind(value, 'number');
     const predicates = conditions.map((condition) => {
         const column = measureSql(condition.measure);
         if (condition.operator === 'between') {
-            parameters.push(condition.value[0], condition.value[1]);
-            return `${column} BETWEEN ? AND ?`;
+            return `${column} BETWEEN ${bind(condition.value[0])} AND ${bind(condition.value[1])}`;
         }
         if (condition.operator === 'in' || condition.operator === 'notIn') {
-            parameters.push(...condition.value);
-            const placeholders = condition.value.map(() => '?').join(', ');
+            const placeholders = condition.value.map(bind).join(', ');
             return `${column} ${condition.operator === 'in' ? 'IN' : 'NOT IN'} (${placeholders})`;
         }
         const comparison = COMPARISONS[condition.operator];
         if (!comparison)
             throw new Error(`Unsupported having operator "${String(condition.operator)}".`);
-        parameters.push(condition.value);
-        return `${column} ${comparison} ?`;
+        return `${column} ${comparison} ${bind(condition.value)}`;
     });
-    return { sql: predicates.join(' AND '), parameters };
+    return predicates.join(' AND ');
 }

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

@@ -1 +1 @@
-{"version":3,"file":"dataset-normalization.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-normalization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAGrB,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;AAC5D,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AAE/D,wBAAgB,mBAAmB,CAAC,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACzF,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,EAAE,gBAAgB,CAAC,GAChE,WAAW,CAEb;AAED,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC/C,OAAO,CAAC,EAAE,yBAAyB,GAClC,yBAAyB,CAgB3B;AAED,wBAAgB,iBAAiB,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC1F,QAAQ,EAAE,SAAS,GAAG,SAAS,GAC9B,SAAS,CAEX;AAED,wBAAgB,sBAAsB,CAAC,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAClG,aAAa,EAAE,cAAc,GAAG,SAAS,EACzC,MAAM,EAAE,MAAM,GACb,cAAc,CAkBhB;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,iBAAiB,GAC5B,eAAe,CAcjB"}
+{"version":3,"file":"dataset-normalization.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-normalization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAGrB,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;AAC5D,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AAE/D,wBAAgB,mBAAmB,CAAC,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACzF,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,EAAE,gBAAgB,CAAC,GAChE,WAAW,CAEb;AAED,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC/C,OAAO,CAAC,EAAE,yBAAyB,GAClC,yBAAyB,CAgB3B;AAED,wBAAgB,iBAAiB,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC1F,QAAQ,EAAE,SAAS,GAAG,SAAS,GAC9B,SAAS,CAEX;AAED,wBAAgB,sBAAsB,CAAC,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAClG,aAAa,EAAE,cAAc,GAAG,SAAS,EACzC,MAAM,EAAE,MAAM,GACb,cAAc,CAkBhB;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,iBAAiB,GAC5B,eAAe,CAejB"}

package/dist/utils/dataset-normalization.js

@@ -45,6 +45,7 @@ export function measureToAggregationSpec(measureName, definition) {
         field: definition.field,
         argField: definition.argField,
         level: definition.level,
+        ...(definition.stateFunction !== undefined ? { stateFunction: definition.stateFunction } : {}),
         sql: definition.sql,
         filters: definition.filters,
     };

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

@@ -1 +1 @@
-{"version":3,"file":"dataset-query-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-query-validation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAkB9E,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAyKlB"}
+{"version":3,"file":"dataset-query-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-query-validation.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAkB9E,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CA6KlB"}

package/dist/utils/dataset-query-validation.js

@@ -1,3 +1,4 @@
+import { notGroupableError } from './groupable.js';
 import { resolveRelationshipMeasure } from './relationship-measures.js';
 import { semanticQuerySyntaxErrors } from './semantic-query-syntax.js';
 import { queryTimezoneErrors } from './query-timezone.js';
@@ -45,11 +46,17 @@ export function validateDatasetQueryInput(ds, query, context) {
                 if (resolution?.error) {
                     errors.push(resolution.error);
                 }
+                else if (resolution?.resolved?.targetDimension.groupable === false) {
+                    errors.push(notGroupableError(dimension));
+                }
                 continue;
             }
             if (!dimensionNames.includes(dimension)) {
                 errors.push(`Unknown dimensions: ${dimension}. Available: ${dimensionNames.join(', ')}`);
             }
+            else if (ds.dimensions[dimension]?.groupable === false) {
+                errors.push(notGroupableError(dimension));
+            }
         }
     }
     if (query.measures) {

package/dist/utils/dataset-source.d.ts

@@ -0,0 +1,9 @@
+import type { AnyDatasetInstance } from '../types.js';
+import type { QueryBuilderFactoryLike, QueryBuilderLike } from '../query-builder-protocol.js';
+/**
+ * The dataset's source table as a builder, read with `FINAL` when the dataset
+ * is declared `final: true`. Every builder-path read of a dataset source goes
+ * through here so no query can skip row-version resolution.
+ */
+export declare function datasetSourceBuilder(builderFactory: Pick<QueryBuilderFactoryLike, 'table'>, ds: Pick<AnyDatasetInstance, 'name' | 'source' | 'final'>): QueryBuilderLike;
+//# sourceMappingURL=dataset-source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-source.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAE9F;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,IAAI,CAAC,uBAAuB,EAAE,OAAO,CAAC,EACtD,EAAE,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,GACxD,gBAAgB,CAYlB"}

package/dist/utils/dataset-source.js

@@ -0,0 +1,16 @@
+/**
+ * The dataset's source table as a builder, read with `FINAL` when the dataset
+ * is declared `final: true`. Every builder-path read of a dataset source goes
+ * through here so no query can skip row-version resolution.
+ */
+export function datasetSourceBuilder(builderFactory, ds) {
+    const qb = builderFactory.table(ds.source);
+    if (!ds.final) {
+        return qb;
+    }
+    if (typeof qb.final !== 'function') {
+        throw new Error(`Dataset "${ds.name}" is declared final: true, but the query builder does not implement final(). ` +
+            'Reading it without FINAL would count every unmerged row version, so the query is refused.');
+    }
+    return qb.final();
+}

package/dist/utils/dataset-sql-dialect.d.ts

@@ -1,5 +1,16 @@
-import type { DatasetSqlDialect } from '../dataset-sql-dialect.js';
+import type { DatasetSqlDialect, DatasetSqlDialectRules } from '../dataset-sql-dialect.js';
 import type { QueryBuilderFactoryInput } from '../query-builder-protocol.js';
+/**
+ * Register a complete engine rule set, so a factory can carry it as its
+ * `datasetSqlDialect` and have it used as-is rather than completed with the
+ * ClickHouse rules. Internal: for engine packages and tests.
+ */
+export declare function defineDatasetSqlDialectRules<TRules extends DatasetSqlDialectRules>(rules: TRules): Readonly<TRules>;
+/**
+ * Complete a public dialect hook with the ClickHouse rules it does not
+ * override. Memoized, so one hook always resolves to one rule set.
+ */
+export declare function completeDatasetSqlDialect(dialect: DatasetSqlDialect): DatasetSqlDialectRules;
 /** Resolve from the active factory, so a runtime builder override carries its dialect. */
-export declare function resolveDatasetSqlDialect(factory: QueryBuilderFactoryInput): DatasetSqlDialect;
+export declare function resolveDatasetSqlDialect(factory: QueryBuilderFactoryInput): DatasetSqlDialectRules;
 //# sourceMappingURL=dataset-sql-dialect.d.ts.map

package/dist/utils/dataset-sql-dialect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-sql-dialect.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-sql-dialect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAG7E,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAE7F"}
+{"version":3,"file":"dataset-sql-dialect.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-sql-dialect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAC3F,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAM7E;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,SAAS,sBAAsB,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAInH;AAsCD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,GAAG,sBAAsB,CAgB5F;AAED,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,wBAAwB,GAAG,sBAAsB,CAIlG"}

package/dist/utils/dataset-sql-dialect.js

@@ -1,5 +1,78 @@
 import { clickhouseDatasetSqlDialect } from './clickhouse-dataset-sql-dialect.js';
+const resolved = new WeakMap();
+const complete = new WeakSet();
+/**
+ * Register a complete engine rule set, so a factory can carry it as its
+ * `datasetSqlDialect` and have it used as-is rather than completed with the
+ * ClickHouse rules. Internal: for engine packages and tests.
+ */
+export function defineDatasetSqlDialectRules(rules) {
+    const frozen = Object.isFrozen(rules) ? rules : receiverBoundSnapshot(rules);
+    complete.add(frozen);
+    return frozen;
+}
+/**
+ * A frozen snapshot of a rule set that leaves the caller's object unfrozen.
+ *
+ * Own members are copied as they are, so a rule shared with another rule set
+ * (spread from the ClickHouse rules, say) keeps its identity. Members a class
+ * declares are read through the original instance, methods bound to it and
+ * getters evaluated on it: its `#private` fields exist only on the object its
+ * constructor ran on, so a copy must not become their receiver. Members
+ * inherited from a plain object stay inherited.
+ */
+function receiverBoundSnapshot(rules) {
+    const snapshot = Object.create(Object.getPrototypeOf(rules), Object.getOwnPropertyDescriptors(rules));
+    for (let owner = Object.getPrototypeOf(rules); owner && isClassPrototype(owner); owner = Object.getPrototypeOf(owner)) {
+        for (const key of Reflect.ownKeys(owner)) {
+            if (key === 'constructor' || Object.hasOwn(snapshot, key))
+                continue;
+            // Read through the original, so a getter sees its own private fields;
+            // a method is bound to it for the same reason.
+            const value = Reflect.get(rules, key);
+            // Define rather than assign: assignment cannot shadow a read-only
+            // member inherited from a frozen prototype such as the ClickHouse rules.
+            Object.defineProperty(snapshot, key, {
+                value: typeof value === 'function' ? value.bind(rules) : value,
+                enumerable: true,
+            });
+        }
+    }
+    return Object.freeze(snapshot);
+}
+/** A prototype a class declaration created: its constructor points back at it. */
+function isClassPrototype(owner) {
+    if (owner === Object.prototype || !Object.hasOwn(owner, 'constructor'))
+        return false;
+    const constructor = owner.constructor;
+    return typeof constructor === 'function' && constructor.prototype === owner;
+}
+/**
+ * Complete a public dialect hook with the ClickHouse rules it does not
+ * override. Memoized, so one hook always resolves to one rule set.
+ */
+export function completeDatasetSqlDialect(dialect) {
+    if (dialect === clickhouseDatasetSqlDialect)
+        return clickhouseDatasetSqlDialect;
+    if (complete.has(dialect))
+        return dialect;
+    let rules = resolved.get(dialect);
+    if (!rules) {
+        // Read the public members explicitly: a class-based hook keeps its methods
+        // on the prototype, which spreading would silently drop.
+        rules = Object.freeze({
+            ...clickhouseDatasetSqlDialect,
+            name: dialect.name,
+            quoteIdentifier: (identifier) => dialect.quoteIdentifier(identifier),
+            quoteQualifiedName: (name) => name.split('.').map(part => dialect.quoteIdentifier(part)).join('.'),
+        });
+        resolved.set(dialect, rules);
+    }
+    return rules;
+}
 /** Resolve from the active factory, so a runtime builder override carries its dialect. */
 export function resolveDatasetSqlDialect(factory) {
-    return factory.datasetSqlDialect ?? clickhouseDatasetSqlDialect;
+    return factory.datasetSqlDialect
+        ? completeDatasetSqlDialect(factory.datasetSqlDialect)
+        : clickhouseDatasetSqlDialect;
 }

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)}`;
 }