@hypequery/datasets 0.21.0 → 0.23.0

package/README.md

@@ -102,6 +102,12 @@ Metric changes travel through the workflow your team already trusts: TypeScript,
 - [Relationships](https://hypequery.com/docs/datasets/relationships)
 - [MCP tool generation](https://hypequery.com/docs/datasets/tool-generation)
 
+## Contributing
+
+For repository contributors, see the [implementation guide](./ARCHITECTURE.md)
+for module boundaries and verification requirements, and the
+[testing review](./TESTING_REVIEW.md) for coverage, CI gates, and remaining gaps.
+
 ## License
 
 Apache-2.0.

package/dist/api.type-test.js

@@ -203,6 +203,13 @@ const builderFactory = {
     rawQuery: async () => [],
 };
 const analytics = createDatasetClient({ queryBuilder: builderFactory });
+const _datasetCompilation = analytics.compileDataset(Orders, { measures: ['doubledRevenue'] });
+// @ts-expect-error compilation accepts declared dataset measures only.
+analytics.compileDataset(Orders, { measures: ['missing'] });
+// @ts-expect-error compilation accepts declared dataset dimensions only.
+analytics.compileDataset(Orders, { dimensions: ['missing'] });
+// @ts-expect-error standalone metric handles are not dataset compilation targets.
+analytics.compileDataset(Orders.metric('revenue', { measure: 'revenue' }));
 const explicitAnalytics = analytics;
 const datasetQuery = { dimensions: ['status'], measures: ['revenue'] };
 analytics.validate(revenueMetric, { dimensions: ['status'] }, runtimeContext);

package/dist/cache/protocol-cache-keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-cache-keys.d.ts","sourceRoot":"","sources":["../../src/cache/protocol-cache-keys.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAEhB,WAAW,EACX,SAAS,EACV,MAAM,aAAa,CAAC;AAIrB,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,cAAc,CAAC;AACjD,eAAO,MAAM,yBAAyB,YAAY,CAAC;AAInD,0EAA0E;AAC1E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,uBAAuB,EAChC,WAAW,EAAE,OAAO,GACnB,wBAAwB,CAqC1B;AAkHD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,wBAAwB,EAClC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,gBAAgB,GAAG,SAAS,EACrC,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,MAAM,GAAG,SAAS,CAcpB;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,wBAAwB,EAClC,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GAAG,SAAS,EACrC,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,MAAM,GAAG,SAAS,CAgBpB"}
+{"version":3,"file":"protocol-cache-keys.d.ts","sourceRoot":"","sources":["../../src/cache/protocol-cache-keys.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAEhB,WAAW,EACX,SAAS,EACV,MAAM,aAAa,CAAC;AAIrB,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,cAAc,CAAC;AACjD,eAAO,MAAM,yBAAyB,YAAY,CAAC;AAInD,0EAA0E;AAC1E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,uBAAuB,EAChC,WAAW,EAAE,OAAO,GACnB,wBAAwB,CAqC1B;AAkHD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,wBAAwB,EAClC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,gBAAgB,GAAG,SAAS,EACrC,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,MAAM,GAAG,SAAS,CAkBpB;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,wBAAwB,EAClC,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GAAG,SAAS,EACrC,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,MAAM,GAAG,SAAS,CAgBpB"}

package/dist/cache/protocol-cache-keys.js

@@ -155,6 +155,11 @@ function definitionFor(settings, root, scope, query, metric) {
  * `query` must already carry its effective limit.
  */
 export function datasetCacheKey(settings, ds, query, context, scope) {
+    // RFC 0009's normalized query has no `having`, so no portable key can
+    // separate queries that differ only in their conditions. Run them uncached,
+    // as the Python SDK does, until the shared preimage covers `having`.
+    if (query.having !== undefined && query.having.length > 0)
+        return undefined;
     try {
         const wire = {
             kind: 'dataset',

package/dist/cache/query-signature.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-signature.d.ts","sourceRoot":"","sources":["../../src/cache/query-signature.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAGhB,WAAW,EACX,SAAS,EACV,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D,OAAO,EAAE,eAAe,EAAE,CAAC;AAsF3B;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,CAoBR;AAED,oDAAoD;AACpD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,CAoBR"}
+{"version":3,"file":"query-signature.d.ts","sourceRoot":"","sources":["../../src/cache/query-signature.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAElB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAGhB,WAAW,EACX,SAAS,EACV,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D,OAAO,EAAE,eAAe,EAAE,CAAC;AA8F3B;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,CAsBR;AAED,oDAAoD;AACpD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,CAoBR"}

package/dist/cache/query-signature.js

@@ -21,6 +21,13 @@ function filterSignature(filters) {
         value: filter.value ?? null,
     }));
 }
+function havingSignature(having) {
+    return having.map((condition) => ({
+        measure: condition.measure,
+        operator: condition.operator,
+        value: condition.value,
+    }));
+}
 function orderBySignature(orderBy) {
     return (orderBy ?? []).map((order) => ({
         field: order.field,
@@ -88,6 +95,8 @@ export function buildDatasetQuerySignature(ds, query, context) {
         measures: query.measures ?? null,
         ...windowQuerySignature(ds, query),
         filters: filterSignature(query.filters),
+        // Omitted when absent so queries without conditions keep their existing keys.
+        ...(query.having?.length ? { having: havingSignature(query.having) } : {}),
         ...segmentSignature(ds, query.segments),
         orderBy: orderBySignature(query.orderBy),
         by: query.by ?? null,

package/dist/catalog.d.ts

@@ -1,3 +1,5 @@
+import type { ProtocolExpression } from '@hypequery/protocol';
+import type { RelationshipKey } from './types.js';
 import { type WindowCatalogMetadata } from './utils/window-catalog-metadata.js';
 import type { AnyDatasetInstance, DimensionDefinition, MeasureDefinition, MetricHandle, RelationshipDefinition, SemanticFilterDefinition, DatasetLimits, DatasetDefaults, DatasetFreshness, SemanticMetadata, TimeGrain } from './types.js';
 export interface DimensionCatalogEntry extends SemanticMetadata {
@@ -24,6 +26,11 @@ export interface MeasureCatalogEntry extends SemanticMetadata, WindowCatalogMeta
     approximate?: true;
 }
 export interface DerivedMeasureCatalogEntry extends SemanticMetadata, WindowCatalogMetadata {
+    uses?: {
+        alias: string;
+        measure: string;
+    }[];
+    expression?: ProtocolExpression;
     label?: string;
     description?: string;
     /** Present, as `true`, when any measure the formula uses is approximate. */
@@ -59,6 +66,7 @@ export interface RelationshipCatalogEntry {
     target: string;
     from: string;
     to: string;
+    keys?: readonly RelationshipKey[];
     queryable: boolean;
     fields: string[];
     /**
@@ -66,6 +74,8 @@ export interface RelationshipCatalogEntry {
      * supplied catalog that predates it still resolves, falling back to `fields`.
      */
     groupableFields?: string[];
+    /** Safe selectable base aggregates, keyed by qualified name. */
+    measures?: Record<string, MeasureCatalogEntry>;
 }
 export interface DatasetCatalog extends SemanticMetadata {
     name: string;
@@ -97,6 +107,8 @@ export type DatasetCatalogSource = AnyDatasetInstance & {
 };
 /** All queryable relationship field names (`<relationship>.<dimension>`) a catalog advertises. */
 export declare function getQueryableRelationshipFields(catalog: DatasetCatalog): string[];
+/** Safe relationship aggregates advertised by a catalog. */
+export declare function getQueryableRelationshipMeasures(catalog: DatasetCatalog): string[];
 /** The queryable relationship fields a catalog also allows as grouping keys. */
 export declare function getGroupableRelationshipFields(catalog: DatasetCatalog): string[];
 export declare function getDatasetCatalog(dataset: DatasetCatalogSource): DatasetCatalog;

package/dist/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AACA,OAAO,EAAyB,KAAK,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAEvG,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,sBAAsB,EACtB,wBAAwB,EACxB,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACV,MAAM,YAAY,CAAC;AAYpB,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D,IAAI,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB,EAAE,qBAAqB;IAClF,WAAW,CAAC,EAAE,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,WAAW,CAAC,EAAE,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB,EAAE,qBAAqB;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,IAAI,CAAC;CACpB;AAED,oFAAoF;AACpF,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,wBAAwB,CAAC,WAAW,CAAC,CAAC;IACjD,SAAS,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,QAAQ,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,sBAAsB,CAAC,MAAM,CAAC,CAAC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAClD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC9C,gFAAgF;IAChF,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;IAC7D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC5C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC5C,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC/C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IACxD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,eAAe,EAAE,SAAS,EAAE,CAAC;IAC7B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAC/D,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GAAG;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACxC,CAAC;AA6EF,kGAAkG;AAClG,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,EAAE,CAIhF;AAED,gFAAgF;AAChF,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,EAAE,CAIhF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,cAAc,CAkG/E;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,GAAG,iBAAiB,CAOpG"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}

package/dist/catalog.js

@@ -1,3 +1,5 @@
+import { derivedMeasureCatalogExpression } from './utils/protocol-metric-expressions.js';
+import { listRelationshipMeasures } from './utils/relationship-measures.js';
 import { inheritedBaseMeasure } from './utils/measure-dependencies.js';
 import { windowCatalogMetadata } from './utils/window-catalog-metadata.js';
 import { splitDatasetMeasures } from './utils/dataset-measures.js';
@@ -62,14 +64,18 @@ function metricToCatalog(metric) {
     };
 }
 function relationshipToCatalog(name, relationship) {
+    const measures = Object.fromEntries(Object.entries(listRelationshipMeasures(name, relationship))
+        .map(([key, definition]) => [key, measureToCatalog(definition)]));
     return {
         kind: relationship.kind,
         target: relationship.target().name,
         from: relationship.from,
         to: relationship.to,
+        ...(relationship.keys ? { keys: relationship.keys.map(key => ({ ...key })) } : {}),
         queryable: relationship.kind !== 'hasMany',
         fields: listQueryableRelationshipFields(name, relationship),
         groupableFields: listGroupableRelationshipFields(name, relationship),
+        ...(Object.keys(measures).length ? { measures } : {}),
     };
 }
 /** All queryable relationship field names (`<relationship>.<dimension>`) a catalog advertises. */
@@ -78,6 +84,11 @@ export function getQueryableRelationshipFields(catalog) {
         .filter(relationship => relationship.queryable)
         .flatMap(relationship => relationship.fields);
 }
+/** Safe relationship aggregates advertised by a catalog. */
+export function getQueryableRelationshipMeasures(catalog) {
+    return Object.values(catalog.relationships).filter(relationship => relationship.queryable)
+        .flatMap(relationship => Object.keys(relationship.measures ?? {}));
+}
 /** The queryable relationship fields a catalog also allows as grouping keys. */
 export function getGroupableRelationshipFields(catalog) {
     return Object.values(catalog.relationships)
@@ -129,6 +140,8 @@ export function getDatasetCatalog(dataset) {
                 name,
                 {
                     ...snapshotSemanticMetadata(definition),
+                    uses: Object.entries(definition.uses).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([alias, measure]) => ({ alias, measure })),
+                    expression: derivedMeasureCatalogExpression(definition),
                     ...(usesTimeMeasure(definition, dataset.measures) ? {
                         requiresTimeRange: true,
                         supportedGrains: measureSupportedGrains(dataset.measures, name, supportedGrains),
@@ -162,7 +175,7 @@ export function getDatasetCatalog(dataset) {
             ...measureNames,
             ...derivedMeasureNames,
             ...metricNames,
-            ...Object.values(relationships).flatMap(relationship => relationship.fields),
+            ...Object.values(relationships).flatMap(relationship => [...relationship.fields, ...Object.keys(relationship.measures ?? {})]),
             ...(dataset.timeKey ? ['period'] : []),
         ],
         maxLimit,

package/dist/constants.d.ts

@@ -1,7 +1,7 @@
 /**
  * Shared constants for semantic layer implementation.
  */
-import type { TimeGrain } from './types.js';
+import type { MetricFilter, TimeGrain } from './types.js';
 /**
  * Maps time grain to ClickHouse date truncation functions.
  */
@@ -15,6 +15,17 @@ export declare const SUPPORTED_TIME_GRAINS: TimeGrain[];
  * The filter operators accepted by semantic dataset and metric inputs.
  */
 export declare const SEMANTIC_FILTER_OPERATORS: readonly ["eq", "neq", "gt", "gte", "lt", "lte", "in", "notIn", "between", "like"];
+/**
+ * Narrowing guard for a runtime-provided filter operator. Query builders accept
+ * operators that splice raw SQL (`inSubquery`, `inTable`), so anything outside
+ * the semantic set must never reach one.
+ */
+export declare function isSemanticFilterOperator(operator: unknown): operator is MetricFilter['operator'];
+/**
+ * Operators accepted by dataset `having` conditions. `like` is excluded:
+ * conditions compare aggregated numeric values.
+ */
+export declare const SEMANTIC_HAVING_OPERATORS: readonly ["eq", "neq", "gt", "gte", "lt", "lte", "in", "notIn", "between"];
 /**
  * Narrowing guard for a runtime-provided grain value.
  */

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAgB,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAQrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAmC,SAAS,EAAE,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,yBAAyB,oFAWkB,CAAC;AAEzD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAEvE"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAyB,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAQrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAmC,SAAS,EAAE,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,yBAAyB,oFAWkB,CAAC;AAIzD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,IAAI,YAAY,CAAC,UAAU,CAAC,CAEhG;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,4EAUe,CAAC;AAEtD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAEvE"}

package/dist/constants.js

@@ -33,6 +33,30 @@ export const SEMANTIC_FILTER_OPERATORS = [
     'between',
     'like',
 ];
+const FILTER_OPERATORS = new Set(SEMANTIC_FILTER_OPERATORS);
+/**
+ * Narrowing guard for a runtime-provided filter operator. Query builders accept
+ * operators that splice raw SQL (`inSubquery`, `inTable`), so anything outside
+ * the semantic set must never reach one.
+ */
+export function isSemanticFilterOperator(operator) {
+    return typeof operator === 'string' && FILTER_OPERATORS.has(operator);
+}
+/**
+ * Operators accepted by dataset `having` conditions. `like` is excluded:
+ * conditions compare aggregated numeric values.
+ */
+export const SEMANTIC_HAVING_OPERATORS = [
+    'eq',
+    'neq',
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    'in',
+    'notIn',
+    'between',
+];
 /**
  * Narrowing guard for a runtime-provided grain value.
  */

package/dist/contract.d.ts

@@ -1,5 +1,6 @@
+import type { RelationshipKey } from './types.js';
 import { type WindowCatalogMetadata } from './utils/window-catalog-metadata.js';
-import { type DatasetCatalogSource, type DimensionCatalogEntry, type MeasureCatalogEntry, type SegmentCatalogEntry, type MetricCatalogEntry, type FilterCatalogEntry, type RelationshipCatalogEntry } from './catalog.js';
+import { type DatasetCatalog, type DatasetCatalogSource, type DimensionCatalogEntry, type MeasureCatalogEntry, type SegmentCatalogEntry, type MetricCatalogEntry, type FilterCatalogEntry, type RelationshipCatalogEntry } from './catalog.js';
 import type { DatasetDefaults, DatasetFreshness, DatasetLimits, SemanticMetadata } from './types.js';
 /**
  * Version of the semantic contract format. Bump when the serialized shape
@@ -52,6 +53,7 @@ export interface ContractRelationship {
     target: string;
     from: string;
     to: string;
+    keys?: readonly RelationshipKey[];
     queryable: boolean;
     fields: string[];
 }
@@ -68,6 +70,7 @@ export interface ContractDataset extends SemanticMetadata {
     supportedGrains: string[];
     dimensions: Record<string, ContractDimension>;
     measures: Record<string, ContractMeasure>;
+    derivedMeasures?: DatasetCatalog['derivedMeasures'];
     metrics: Record<string, ContractMetric>;
     filters: Record<string, ContractFilter>;
     /** Named segments (label and description only); absent when none are declared. */

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/contract.js

@@ -56,6 +56,9 @@ function datasetToContract(catalog, includeSql) {
         supportedGrains: uniqueSorted(catalog.supportedGrains),
         dimensions: sortedRecord(Object.entries(catalog.dimensions).map(([name, entry]) => [name, dimensionToContract(entry, includeSql)])),
         measures: sortedRecord(Object.entries(catalog.measures).map(([name, entry]) => [name, measureToContract(entry, includeSql)])),
+        ...(catalog.derivedMeasures !== undefined ? {
+            derivedMeasures: sortedRecord(Object.entries(catalog.derivedMeasures)),
+        } : {}),
         metrics: sortedRecord(Object.entries(catalog.metrics).map(([name, entry]) => [name, metricToContract(entry)])),
         filters: sortedRecord(Object.entries(catalog.filters).map(([name, entry]) => [name, filterToContract(entry)])),
         ...(catalog.segments !== undefined ? {
@@ -138,6 +141,7 @@ function relationshipToContract(entry) {
         target: entry.target,
         from: entry.from,
         to: entry.to,
+        ...(entry.keys ? { keys: entry.keys.map(key => ({ ...key })) } : {}),
         queryable: entry.queryable,
         fields: uniqueSorted(entry.fields),
     };

package/dist/dataset-compilation.d.ts

@@ -0,0 +1,50 @@
+import type { DatasetQuery } from './types.js';
+/** Trusted compiler output. SQL may contain literals supplied by a custom builder. */
+export interface DatasetCompiledStatement {
+    readonly sql: string;
+    readonly parameters: readonly unknown[];
+}
+/** Structural diagnostics: no SQL, physical columns, filter values or tenant IDs. */
+export interface DatasetCompilationDescription {
+    readonly kind: 'dataset-compilation';
+    readonly version: 1;
+    readonly dataset: string;
+    readonly plan: 'aggregate' | 'derived' | 'time';
+    readonly dimensions: readonly string[];
+    readonly measures: readonly string[];
+    readonly measureDependencies: readonly string[];
+    readonly filters: readonly {
+        readonly field: string;
+        readonly operator: string;
+    }[];
+    /** Post-aggregation conditions, without their values. */
+    readonly having: readonly {
+        readonly measure: string;
+        readonly operator: string;
+    }[];
+    readonly segments: readonly string[];
+    readonly by?: string;
+    readonly timezone?: string;
+    readonly effectiveLimit?: number;
+    /** Includes the extra row used to determine pagination.hasMore. */
+    readonly executionLimit?: number;
+    readonly offset: number;
+    readonly parameterCount: number;
+    readonly preflightStatementCount: number;
+}
+/**
+ * Dataset-level envelope around the current query-builder output. This is not
+ * an RFC 0010 CompiledQuery: native named parameter binding remains an adapter
+ * responsibility. Use describe()/JSON serialization for structural diagnostics;
+ * inspect SQL and parameters only in an authorized, trusted debugger.
+ */
+export interface DatasetCompilation extends DatasetCompiledStatement {
+    /** Normalized query, including its effective result limit and default measures. */
+    readonly query: Readonly<DatasetQuery>;
+    /** Statements executed before the result query, such as time-axis guards. */
+    readonly preflightStatements: readonly DatasetCompiledStatement[];
+    describe(): DatasetCompilationDescription;
+    /** JSON serialization deliberately omits trusted SQL, parameters and values. */
+    toJSON(): DatasetCompilationDescription;
+}
+//# sourceMappingURL=dataset-compilation.d.ts.map

package/dist/dataset-compilation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-compilation.d.ts","sourceRoot":"","sources":["../src/dataset-compilation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,sFAAsF;AACtF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,SAAS,OAAO,EAAE,CAAC;CACzC;AAED,qFAAqF;AACrF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;IAChD,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACnF,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACpF,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;CAC1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAmB,SAAQ,wBAAwB;IAClE,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;IACvC,6EAA6E;IAC7E,QAAQ,CAAC,mBAAmB,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAClE,QAAQ,IAAI,6BAA6B,CAAC;IAC1C,gFAAgF;IAChF,MAAM,IAAI,6BAA6B,CAAC;CACzC"}

package/dist/dataset-compilation.js

@@ -0,0 +1 @@
+export {};

package/dist/dataset-query.d.ts

@@ -1,6 +1,7 @@
 import type { AnyDatasetInstance, DatasetQuery, DatasetQueryResult, ExecutionContext } from './types.js';
-import type { QueryBuilderFactoryLike, QueryBuilderLike } from './query-builder-protocol.js';
-import { type ValidationResult } from './validation.js';
+import type { QueryBuilderFactoryLike } from './query-builder-protocol.js';
+import type { ValidationResult } from './validation.js';
+export { buildDatasetQueryBuilder } from './utils/build-dataset-query-builder.js';
 export interface DatasetQueryExecutionOptions {
     builderFactory: QueryBuilderFactoryLike;
     context?: ExecutionContext;
@@ -13,6 +14,5 @@ export interface DatasetQueryExecutionOptions {
     skipDefaultOrderBy?: boolean;
 }
 export declare function validateDatasetQuery(ds: AnyDatasetInstance, query: DatasetQuery, context?: ExecutionContext): ValidationResult;
-export declare function buildDatasetQueryBuilder(ds: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions): QueryBuilderLike;
 export declare function runDatasetQuery(ds: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions): Promise<DatasetQueryResult>;
 //# sourceMappingURL=dataset-query.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"dataset-query.d.ts","sourceRoot":"","sources":["../src/dataset-query.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAS7F,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAgBxD,MAAM,WAAW,4BAA4B;IAC3C,cAAc,EAAE,uBAAuB,CAAC;IACxC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2FAA2F;IAC3F,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAElB;AAED,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,GACpC,gBAAgB,CAyDlB;AAED,wBAAsB,eAAe,CACnC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,kBAAkB,CAAC,CA0B7B"}
+{"version":3,"file":"dataset-query.d.ts","sourceRoot":"","sources":["../src/dataset-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACzG,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAMxD,OAAO,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AAElF,MAAM,WAAW,4BAA4B;IAC3C,cAAc,EAAE,uBAAuB,CAAC;IACxC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2FAA2F;IAC3F,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAElB;AAED,wBAAsB,eAAe,CACnC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,kBAAkB,CAAC,CAW7B"}

package/dist/dataset-query.js

@@ -1,83 +1,19 @@
-import { queryTimeFilterSql } from './utils/query-timezone.js';
-import { selectedTimeMeasures } from './utils/time-query-measures.js';
-import { buildTimeMeasureDatasetSql } from './utils/time-measure-dataset-sql.js';
-import { baseMeasureNames, getBaseMeasure } from './utils/dataset-measures.js';
-import { appendOrderLimitOffset, applyMeasureDefinition, buildDimensionSelectionPlan, resolveDimensionExpression, resolveFilterField, resolveTenantFilterColumn, } from './query-planner.js';
 import { validateDatasetQueryInput } from './utils/dataset-query-validation.js';
-import { getRuntimeTenantPredicate } from './utils/tenant-runtime.js';
-import { overfetchLimit } from './utils/pagination.js';
-import { applyRelationshipJoins, buildRelationshipBuilderContext, qualifyBaseColumn, } from './utils/relationship-builder-plan.js';
-import { hasSelectedDerivedMeasure, runDerivedDatasetQuery, } from './utils/dataset-derived-query.js';
+import { prepareDatasetQuery } from './utils/compile-dataset-query.js';
 import { toDatasetQueryResult } from './utils/dataset-query-result.js';
-import { segmentFilters } from './utils/segments.js';
+// Preserve the shipped builder helper while keeping compilation helpers focused.
+export { buildDatasetQueryBuilder } from './utils/build-dataset-query-builder.js';
 export function validateDatasetQuery(ds, query, context) {
     return validateDatasetQueryInput(ds, query, context);
 }
-export function buildDatasetQueryBuilder(ds, query, options) {
-    if (selectedTimeMeasures(ds, query).size) {
-        throw new Error('A time-based dataset query needs the time-measure SQL planner; use createDatasetClient().toSQL().');
-    }
-    if (hasSelectedDerivedMeasure(ds, query)) {
-        throw new Error('A derived dataset query needs the outer SQL projection; use createDatasetClient().toSQL().');
-    }
-    const validation = validateDatasetQuery(ds, query, options.context);
-    if (!validation.valid) {
-        throw new Error(`Invalid dataset query: ${validation.errors.join('; ')}`);
-    }
-    const joinCtx = buildRelationshipBuilderContext(ds, query, options.context);
-    let qb = options.builderFactory.table(ds.source);
-    qb = applyRelationshipJoins(qb, joinCtx);
-    const { selectParts, groupByParts } = buildDimensionSelectionPlan(ds, query.dimensions ?? [], query.by, joinCtx, query.timezone);
-    const measureNames = query.measures ?? baseMeasureNames(ds.measures);
-    if (selectParts.length > 0) {
-        qb = qb.select(selectParts);
-    }
-    for (const measureName of measureNames) {
-        const definition = getBaseMeasure(ds.measures, measureName);
-        if (!definition)
-            throw new Error(`Measure "${measureName}" is not a base measure.`);
-        qb = applyMeasureDefinition(qb, ds, measureName, definition, joinCtx);
-    }
-    if (groupByParts.length > 0) {
-        qb = qb.groupBy(groupByParts);
-    }
-    const tenantColumn = resolveTenantFilterColumn(ds, options.context);
-    const tenantPredicate = getRuntimeTenantPredicate(options.context);
-    if (tenantPredicate && tenantColumn) {
-        qb = qb.where(qualifyBaseColumn(joinCtx, tenantColumn), tenantPredicate.operator, tenantPredicate.value);
-    }
-    for (const filter of query.filters ?? []) {
-        const resolvedField = resolveFilterField(ds, filter.field, joinCtx);
-        qb = qb.where(queryTimeFilterSql(ds, filter.field, resolvedField, query.timezone), filter.operator, filter.value);
-    }
-    // Segments are author-defined, so they bypass the caller filter allow-list.
-    for (const filter of segmentFilters(ds, query.segments)) {
-        qb = qb.where(resolveDimensionExpression(ds, filter.field, joinCtx), filter.operator, filter.value);
-    }
-    return appendOrderLimitOffset(qb, query.orderBy, options.skipDefaultOrderBy ? undefined : query.by, options.executionLimit ?? query.limit, query.offset, joinCtx);
-}
 export async function runDatasetQuery(ds, query, options) {
-    if (selectedTimeMeasures(ds, query).size) {
-        const start = Date.now();
-        const { sql, parameters, timeAxisSql } = buildTimeMeasureDatasetSql(ds, query, { ...options, executionLimit: overfetchLimit(query.limit) });
-        await options.builderFactory.rawQuery(timeAxisSql, parameters, { abortSignal: options.context?.abortSignal });
-        const rows = await options.builderFactory.rawQuery(sql, parameters, { abortSignal: options.context?.abortSignal });
-        return toDatasetQueryResult(rows, { dataset: ds, query, sql, timingMs: Date.now() - start, context: options.context });
-    }
-    if (hasSelectedDerivedMeasure(ds, query)) {
-        return runDerivedDatasetQuery(ds, query, options, buildDatasetQueryBuilder);
-    }
     const start = Date.now();
-    // Over-fetch one row so we can report `hasMore` without a count query.
-    const qb = buildDatasetQueryBuilder(ds, query, {
-        ...options,
-        executionLimit: overfetchLimit(query.limit),
-    });
-    const rows = await qb.execute({ abortSignal: options.context?.abortSignal });
+    const prepared = prepareDatasetQuery(ds, query, options);
+    const rows = await prepared.execute();
     return toDatasetQueryResult(rows, {
         dataset: ds,
-        query,
-        sql: qb.toSQLWithParams().sql,
+        query: prepared.compilation.query,
+        sql: prepared.compilation.sql,
         timingMs: Date.now() - start,
         context: options.context,
     });

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

@@ -0,0 +1,11 @@
+/**
+ * SQL rendering owned by the semantic datasets layer, separate from a query
+ * builder's compiler dialect. Extend this contract as emission sites migrate.
+ * Only the ClickHouse implementation is supported today.
+ */
+export interface DatasetSqlDialect {
+    readonly name: string;
+    /** Quote one output identifier; dots in a qualified semantic alias are literal. */
+    quoteIdentifier(identifier: string): string;
+}
+//# sourceMappingURL=dataset-sql-dialect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-sql-dialect.d.ts","sourceRoot":"","sources":["../src/dataset-sql-dialect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7C"}

package/dist/dataset-sql-dialect.js

@@ -0,0 +1 @@
+export {};

package/dist/dataset.d.ts

@@ -29,6 +29,7 @@
  * });
  * ```
  */
-import type { DatasetConfig, DatasetInstance, DatasetMeasureDefinition, DerivedMeasures, DimensionDefinition, RelationshipDefinition, SegmentDefinition } from './types.js';
-export declare function dataset<TDatasetName extends string, TDimensions extends Record<string, DimensionDefinition>, TDefinitions extends Record<string, DatasetMeasureDefinition> = {}, TRelationships extends Record<string, RelationshipDefinition> = Record<string, never>, const TSegments extends Record<string, SegmentDefinition> = {}>(name: TDatasetName, config: DatasetConfig<TDimensions, TDefinitions, TRelationships, TSegments>): DatasetInstance<TDimensions, TDefinitions, TRelationships, TDatasetName, DerivedMeasures<TDefinitions>, TSegments>;
+import type { NormalizedDatasetFilters } from './utils/dataset-filter-types.js';
+import type { DatasetConfig, DatasetInstance, DatasetMeasureDefinition, DerivedMeasures, DimensionDefinition, RelationshipDefinition, SegmentDefinition, SemanticFiltersDefinition } from './types.js';
+export declare function dataset<TDatasetName extends string, TDimensions extends Record<string, DimensionDefinition>, TDefinitions extends Record<string, DatasetMeasureDefinition> = {}, TRelationships extends Record<string, RelationshipDefinition> = Record<string, never>, const TSegments extends Record<string, SegmentDefinition> = {}, const TFilters extends SemanticFiltersDefinition | undefined = SemanticFiltersDefinition | undefined>(name: TDatasetName, config: DatasetConfig<TDimensions, TDefinitions, TRelationships, TSegments, TFilters>): DatasetInstance<TDimensions, TDefinitions, TRelationships, TDatasetName, DerivedMeasures<TDefinitions>, TSegments, NormalizedDatasetFilters<TDimensions, TFilters>>;
 //# sourceMappingURL=dataset.d.ts.map

package/dist/dataset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../src/dataset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,wBAAwB,EAExB,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EAKtB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAsBpB,wBAAgB,OAAO,CACrB,YAAY,SAAS,MAAM,EAC3B,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,YAAY,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,EAAE,EAClE,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EACrF,KAAK,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,EAAE,EAE9D,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,CAAC,GAC1E,eAAe,CAAC,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,eAAe,CAAC,YAAY,CAAC,EAAE,SAAS,CAAC,CAoFpH"}
+{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../src/dataset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAEhF,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,wBAAwB,EAExB,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EAKtB,iBAAiB,EACjB,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAsBpB,wBAAgB,OAAO,CACrB,YAAY,SAAS,MAAM,EAC3B,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,YAAY,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,EAAE,EAClE,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EACrF,KAAK,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,EAAE,EAC9D,KAAK,CAAC,QAAQ,SAAS,yBAAyB,GAAG,SAAS,GAAG,yBAAyB,GAAG,SAAS,EAEpG,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,CAAC,GACpF,eAAe,CAAC,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,eAAe,CAAC,YAAY,CAAC,EAAE,SAAS,EAAE,wBAAwB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAoFrK"}

package/dist/execution-capabilities.d.ts

@@ -0,0 +1,28 @@
+export type DatasetFeature = 'baseMeasures' | 'derivedMeasures' | 'segments' | 'windowMeasures' | 'shiftMeasures' | 'approxCountDistinct' | 'subDayGrains';
+export interface DatasetFeatureSupport {
+    readonly feature: DatasetFeature;
+    /** Versions capable of representing the feature, independently of runtime support. */
+    readonly protocolVersions: readonly number[];
+    readonly typescript: {
+        readonly local: boolean;
+        readonly publish: boolean;
+    };
+    readonly python: {
+        readonly local: boolean;
+        readonly publish: boolean;
+    };
+    /** Repository portable runtime support, not qualification of a hosted service. */
+    readonly cloud: boolean;
+}
+export interface DatasetExecutionCapabilities {
+    readonly version: 1;
+    readonly cloudDeploymentVersion: 2;
+    readonly features: readonly DatasetFeatureSupport[];
+}
+/**
+ * Conservative feature matrix tested against TS, Python and portable execution.
+ * Support assumes a compatible builder and a valid definition/query. This is a
+ * discovery aid, not a replacement for contract validation or authorization.
+ */
+export declare const DATASET_EXECUTION_CAPABILITIES: DatasetExecutionCapabilities;
+//# sourceMappingURL=execution-capabilities.d.ts.map

package/dist/execution-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-capabilities.d.ts","sourceRoot":"","sources":["../src/execution-capabilities.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,iBAAiB,GAAG,UAAU,GACxE,gBAAgB,GAAG,eAAe,GAAG,qBAAqB,GAAG,cAAc,CAAC;AAEhF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,sFAAsF;IACtF,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAC5E,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IACxE,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,sBAAsB,EAAE,CAAC,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACrD;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,4BAU3C,CAAC"}

package/dist/execution-capabilities.js

@@ -0,0 +1,17 @@
+import matrix from './execution-capabilities.json' with { type: 'json' };
+/**
+ * Conservative feature matrix tested against TS, Python and portable execution.
+ * Support assumes a compatible builder and a valid definition/query. This is a
+ * discovery aid, not a replacement for contract validation or authorization.
+ */
+export const DATASET_EXECUTION_CAPABILITIES = Object.freeze({
+    version: 1,
+    cloudDeploymentVersion: 2,
+    features: Object.freeze(matrix.features.map(entry => Object.freeze({
+        feature: entry.feature,
+        protocolVersions: Object.freeze([...entry.protocolVersions]),
+        typescript: Object.freeze({ ...entry.typescript }),
+        python: Object.freeze({ ...entry.python }),
+        cloud: entry.cloud,
+    }))),
+});

package/dist/execution-capabilities.json

@@ -0,0 +1,13 @@
+{
+    "version": 1,
+    "cloudDeploymentVersion": 2,
+    "features": [
+        { "feature": "baseMeasures", "protocolVersions": [2, 3], "typescript": { "local": true, "publish": true }, "python": { "local": true, "publish": true }, "cloud": true },
+        { "feature": "derivedMeasures", "protocolVersions": [2, 3], "typescript": { "local": true, "publish": true }, "python": { "local": true, "publish": true }, "cloud": true },
+        { "feature": "segments", "protocolVersions": [3], "typescript": { "local": true, "publish": false }, "python": { "local": false, "publish": false }, "cloud": false },
+        { "feature": "windowMeasures", "protocolVersions": [3], "typescript": { "local": true, "publish": false }, "python": { "local": false, "publish": false }, "cloud": false },
+        { "feature": "shiftMeasures", "protocolVersions": [3], "typescript": { "local": true, "publish": false }, "python": { "local": false, "publish": false }, "cloud": false },
+        { "feature": "approxCountDistinct", "protocolVersions": [3], "typescript": { "local": true, "publish": false }, "python": { "local": false, "publish": false }, "cloud": false },
+        { "feature": "subDayGrains", "protocolVersions": [3], "typescript": { "local": true, "publish": false }, "python": { "local": true, "publish": false }, "cloud": false }
+    ]
+}