@hypequery/datasets 0.25.0 → 0.26.0

package/dist/protocol-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-adapter.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,uBAAuB,EAE5B,KAAK,sBAAsB,EAI5B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,kBAAkB,EAElB,YAAY,EAEb,MAAM,YAAY,CAAC;AAMpB,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAC3C,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;CAC7E;AAmFD;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,mCAAwC,GAChD,uBAAuB,CAqIzB"}
+{"version":3,"file":"protocol-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-adapter.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,uBAAuB,EAE5B,KAAK,sBAAsB,EAI5B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,kBAAkB,EAElB,YAAY,EAEb,MAAM,YAAY,CAAC;AAMpB,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAC3C,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;CAC7E;AAmFD;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,mCAAwC,GAChD,uBAAuB,CAsIzB"}

package/dist/protocol-adapter.js

@@ -5,7 +5,7 @@ import { parseProtocolIdentifier, parseProtocolQualifiedIdentifier, validateProt
 import { SEMANTIC_FILTER_OPERATORS } from './constants.js';
 import { toProtocolSemanticMetadata } from './utils/protocol-semantic-metadata.js';
 import { assertPublishableTimeGrains, isPortableTimeGrain, requirePortableTimeGrain } from './utils/portable-grains.js';
-import { requirePortableAggregation } from './utils/portable-aggregations.js';
+import { requirePublishableMeasureAggregation } from './utils/portable-aggregations.js';
 import { assertNoPublishedSegments } from './utils/segments.js';
 function fieldSchema(type) {
     switch (type) {
@@ -131,8 +131,9 @@ export function buildProtocolDatasetContract(dataset, options = {}) {
         })).sort(byName),
         measures: Object.entries(baseMeasures).map(([name, measure]) => ({
             name,
-            aggregation: requirePortableAggregation(measure.aggregation, `Measure "${dataset.name}.${name}"`),
+            aggregation: requirePublishableMeasureAggregation(measure.aggregation, `Measure "${dataset.name}.${name}"`),
             field: measure.field,
+            ...(measure.stateFunction !== undefined ? { stateFunction: measure.stateFunction } : {}),
             ...(measure.argField !== undefined ? { argField: measure.argField } : {}),
             ...(measure.level !== undefined ? { level: measure.level } : {}),
             ...(measure.sql !== undefined

package/dist/protocol-rehydrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-rehydrate.d.ts","sourceRoot":"","sources":["../src/protocol-rehydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,uBAAuB,EAEvB,yBAAyB,EAM1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAMlB,YAAY,EAIb,MAAM,YAAY,CAAC;AAOpB,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,4BAA4B,EAC5B,KAAK,yBAAyB,GAC/B,MAAM,yCAAyC,CAAC;AAEjD,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG;IACnD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACjD;AAED;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,SAAS,CAAC;gBAGrD,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,yBAAyB;CAQrC;AA8QD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,CAAC,uBAAuB,GAAG,yBAAyB,CAAC,EAAE,EAC3E,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAyF7C;AAED,gFAAgF;AAChF,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAG7C"}
+{"version":3,"file":"protocol-rehydrate.d.ts","sourceRoot":"","sources":["../src/protocol-rehydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,uBAAuB,EAEvB,yBAAyB,EAM1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAMlB,YAAY,EAIb,MAAM,YAAY,CAAC;AAOpB,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,4BAA4B,EAC5B,KAAK,yBAAyB,GAC/B,MAAM,yCAAyC,CAAC;AAEjD,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG;IACnD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACjD;AAED;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,SAAS,CAAC;gBAGrD,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,yBAAyB;CAQrC;AA+QD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,CAAC,uBAAuB,GAAG,yBAAyB,CAAC,EAAE,EAC3E,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAyF7C;AAED,gFAAgF;AAChF,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAG7C"}

package/dist/protocol-rehydrate.js

@@ -70,6 +70,7 @@ function rehydrateMeasure(datasetName, measure) {
         ...snapshotSemanticMetadata(measure),
         aggregation: measure.aggregation,
         field: String(measure.field),
+        ...(measure.stateFunction !== undefined ? { stateFunction: measure.stateFunction } : {}),
         ...(measure.argField !== undefined ? { argField: String(measure.argField) } : {}),
         ...(measure.level !== undefined ? { level: measure.level } : {}),
         ...(measure.sql !== undefined

package/dist/utils/aggregate-state-functions.d.ts

@@ -11,9 +11,10 @@
  * cannot read back from the column type. The name is interpolated into SQL, so
  * it must come from this list.
  */
+import { type ProtocolAggregateStateFunction } from '@hypequery/protocol';
 import type { MeasureDefinition } from '../types.js';
 export declare const AGGREGATE_STATE_FUNCTIONS: readonly ["uniq", "uniqExact", "uniqCombined", "uniqCombined64", "uniqHLL12", "uniqTheta", "count", "sum", "avg", "min", "max", "any", "anyLast", "groupBitmap"];
-export type AggregateStateFunction = (typeof AGGREGATE_STATE_FUNCTIONS)[number];
+export type AggregateStateFunction = ProtocolAggregateStateFunction;
 export declare function isAggregateStateFunction(value: unknown): value is AggregateStateFunction;
 /** Throws unless `value` is a supported state function; `owner` names the measure. */
 export declare function assertAggregateStateFunction(value: unknown, owner: string): asserts value is AggregateStateFunction;

package/dist/utils/aggregate-state-functions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregate-state-functions.d.ts","sourceRoot":"","sources":["../../src/utils/aggregate-state-functions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,eAAO,MAAM,yBAAyB,kKAe5B,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAchF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CAExF;AAED,sFAAsF;AACtF,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,sBAAsB,CAOnH;AAED,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAElG;AAED,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAErF;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,IAAI,CAAC,iBAAiB,EAAE,aAAa,GAAG,eAAe,CAAC,GAAG,OAAO,CAI/G"}
+{"version":3,"file":"aggregate-state-functions.d.ts","sourceRoot":"","sources":["../../src/utils/aggregate-state-functions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAGL,KAAK,8BAA8B,EACpC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAIrD,eAAO,MAAM,yBAAyB,kKAAqC,CAAC;AAE5E,MAAM,MAAM,sBAAsB,GAAG,8BAA8B,CAAC;AAYpE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CAExF;AAED,sFAAsF;AACtF,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,sBAAsB,CAOnH;AAED,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAElG;AAED,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAErF;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,IAAI,CAAC,iBAAiB,EAAE,aAAa,GAAG,eAAe,CAAC,GAAG,OAAO,CAI/G"}

package/dist/utils/aggregate-state-functions.js

@@ -11,27 +11,13 @@
  * cannot read back from the column type. The name is interpolated into SQL, so
  * it must come from this list.
  */
-export const AGGREGATE_STATE_FUNCTIONS = [
-    'uniq',
-    'uniqExact',
-    'uniqCombined',
-    'uniqCombined64',
-    'uniqHLL12',
-    'uniqTheta',
-    'count',
-    'sum',
-    'avg',
-    'min',
-    'max',
-    'any',
-    'anyLast',
-    'groupBitmap',
-];
+import { PROTOCOL_AGGREGATE_STATE_FUNCTIONS, PROTOCOL_APPROXIMATE_STATE_FUNCTIONS, } from '@hypequery/protocol';
+// One list, shared with the deployment contract (RFC 0022), so what can be
+// authored is exactly what can be published.
+export const AGGREGATE_STATE_FUNCTIONS = PROTOCOL_AGGREGATE_STATE_FUNCTIONS;
 const STATE_FUNCTIONS = new Set(AGGREGATE_STATE_FUNCTIONS);
 /** States whose merged value is an estimate. */
-const APPROXIMATE_STATE_FUNCTIONS = new Set([
-    'uniq', 'uniqCombined', 'uniqCombined64', 'uniqHLL12', 'uniqTheta',
-]);
+const APPROXIMATE_STATE_FUNCTIONS = new Set(PROTOCOL_APPROXIMATE_STATE_FUNCTIONS);
 /** States whose merged value is a count: 0, not NULL, over an empty population. */
 const COUNT_STATE_FUNCTIONS = new Set([
     'uniq', 'uniqExact', 'uniqCombined', 'uniqCombined64', 'uniqHLL12', 'uniqTheta', 'count', 'groupBitmap',

package/dist/utils/portable-aggregations.d.ts

@@ -4,12 +4,15 @@
  * `approxCountDistinct` runs locally, but it is an expression extension 2 and
  * deployment contract 3 feature (RFC 0015). Publishing emits contract 2 until
  * it can emit contract 3, so it refuses the measure with an error naming it.
- * `merge` reads ClickHouse aggregate-state columns and has no contract form.
+ * `merge` is a deployment measure with its state function (RFC 0022), but the
+ * expression grammar has no merge aggregate, so a metric over one is refused.
  */
-import type { ProtocolAggregation } from '@hypequery/protocol';
+import type { ProtocolAggregation, ProtocolDatasetMeasure } from '@hypequery/protocol';
 import type { AggregationType } from '../types.js';
 type PortableAggregation = Exclude<ProtocolAggregation, 'approxCountDistinct'>;
-/** Returns `aggregation` when publishing can carry it; otherwise throws naming `owner`. */
+/** A dataset measure's aggregation as the contract carries it; otherwise throws naming `owner`. */
+export declare function requirePublishableMeasureAggregation(aggregation: AggregationType, owner: string): ProtocolDatasetMeasure['aggregation'];
+/** Returns `aggregation` when an expression can carry it; otherwise throws naming `owner`. */
 export declare function requirePortableAggregation(aggregation: AggregationType, owner: string): PortableAggregation;
 export {};
 //# sourceMappingURL=portable-aggregations.d.ts.map

package/dist/utils/portable-aggregations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"portable-aggregations.d.ts","sourceRoot":"","sources":["../../src/utils/portable-aggregations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,KAAK,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,EAAE,qBAAqB,CAAC,CAAC;AAE/E,2FAA2F;AAC3F,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,eAAe,EAC5B,KAAK,EAAE,MAAM,GACZ,mBAAmB,CAcrB"}
+{"version":3,"file":"portable-aggregations.d.ts","sourceRoot":"","sources":["../../src/utils/portable-aggregations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,KAAK,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,EAAE,qBAAqB,CAAC,CAAC;AAc/E,mGAAmG;AACnG,wBAAgB,oCAAoC,CAClD,WAAW,EAAE,eAAe,EAC5B,KAAK,EAAE,MAAM,GACZ,sBAAsB,CAAC,aAAa,CAAC,CAGvC;AAED,8FAA8F;AAC9F,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,eAAe,EAC5B,KAAK,EAAE,MAAM,GACZ,mBAAmB,CASrB"}

package/dist/utils/portable-aggregations.js

@@ -4,17 +4,26 @@
  * `approxCountDistinct` runs locally, but it is an expression extension 2 and
  * deployment contract 3 feature (RFC 0015). Publishing emits contract 2 until
  * it can emit contract 3, so it refuses the measure with an error naming it.
- * `merge` reads ClickHouse aggregate-state columns and has no contract form.
+ * `merge` is a deployment measure with its state function (RFC 0022), but the
+ * expression grammar has no merge aggregate, so a metric over one is refused.
  */
-/** Returns `aggregation` when publishing can carry it; otherwise throws naming `owner`. */
-export function requirePortableAggregation(aggregation, owner) {
-    if (aggregation === 'merge') {
-        throw new Error(`${owner} uses merge, which cannot be published: the deployment contract has no aggregate-state ` +
-            'measures. Use it for local queries only.');
-    }
+function refuseApproximate(aggregation, owner) {
     if (aggregation === 'approxCountDistinct') {
         throw new Error(`${owner} uses approxCountDistinct, which cannot be published yet: approximate aggregations ` +
             'need deployment contract 3 (RFC 0015). Use it for local queries, or publish countDistinct instead.');
     }
+}
+/** A dataset measure's aggregation as the contract carries it; otherwise throws naming `owner`. */
+export function requirePublishableMeasureAggregation(aggregation, owner) {
+    refuseApproximate(aggregation, owner);
+    return aggregation;
+}
+/** Returns `aggregation` when an expression can carry it; otherwise throws naming `owner`. */
+export function requirePortableAggregation(aggregation, owner) {
+    if (aggregation === 'merge') {
+        throw new Error(`${owner} uses merge, which a published metric cannot express: the expression grammar has no ` +
+            'aggregate-state merge. Publish the merge measure itself and query it, or use it for local queries only.');
+    }
+    refuseApproximate(aggregation, owner);
     return aggregation;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Code-first TypeScript semantic layer for ClickHouse datasets, metrics, multi-tenancy, and AI agents",
   "keywords": [
     "semantic-layer",
@@ -55,7 +55,7 @@
     "!dist/**/type-tests/**"
   ],
   "dependencies": {
-    "@hypequery/protocol": "^0.22.0",
+    "@hypequery/protocol": "^0.23.0",
     "@noble/hashes": "^2.4.0",
     "zod": "^4.6.6",
     "zod-to-json-schema": "^3.25.2"
@@ -73,7 +73,7 @@
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^5.0.5",
     "vitest": "^5.0.5",
-    "@hypequery/protocol-conformance": "^0.16.1"
+    "@hypequery/protocol-conformance": "^0.16.2"
   },
   "repository": {
     "type": "git",