@hypequery/datasets 0.21.0 → 0.23.0

package/dist/executor.d.ts

@@ -1,19 +1,14 @@
-/**
- * Semantic dataset client internals.
- *
- * Public callers use `createDatasetClient(...).execute(...)`. The implementation
- * stays database-agnostic via query-builder and backend protocol interfaces.
- */
+/** Dataset client orchestration: runtime defaults, caching, limits and target dispatch. */
 import type { MetricRef, GrainedMetricRef, MetricQuery, MetricQueryFor, MetricResult, MetricResultFor, DatasetQuery, DatasetQueryFor, DatasetQueryResult, DatasetQueryResultFor, ExecutionContext, AnyDatasetInstance, DatasetInstance } from './types.js';
-import type { QueryBuilderFactoryLike, QueryBuilderFactoryInput } from './query-builder-protocol.js';
+import type { QueryBuilderFactoryInput } from './query-builder-protocol.js';
 import type { PlanNode, SemanticBackend } from './semantic-plan.js';
-import { type ValidationResult } from './validation.js';
+import type { ValidationResult } from './validation.js';
+import { MetricQueryEngine } from './metric-query-engine.js';
 import { type DatasetQueryExecutionOptions } from './dataset-query.js';
+import type { DatasetCompilation } from './dataset-compilation.js';
 import { type SemanticCacheOptions, type SemanticCacheStats } from './cache/semantic-query-cache.js';
-export interface MetricQueryEngineOptions {
-    /** Query builder factory for executing metrics. */
-    builderFactory: QueryBuilderFactoryInput;
-}
+export { MetricQueryEngine } from './metric-query-engine.js';
+export type { MetricQueryEngineOptions } from './metric-query-engine.js';
 export interface CreateDatasetClientOptions {
     /** Default IANA timezone for buckets and local time-key bounds. Queries can override it. */
     timezone?: string;
@@ -46,7 +41,14 @@ export interface DatasetClient {
     execute<TDataset extends TypedDataset, const TQuery extends DatasetQueryFor<TDataset> = DatasetQueryFor<TDataset>>(target: TDataset, query?: TQuery, context?: ExecutionContext): Promise<DatasetQueryResultFor<TDataset, TQuery>>;
     execute<TDatasetName extends string, TMetricName extends string, TDataset extends TypedDataset<TDatasetName>, const TQuery extends MetricQueryFor<TDataset, TMetricName> = MetricQueryFor<TDataset, TMetricName>>(target: TypedMetricRef<TDatasetName, TMetricName, TDataset>, query?: TQuery, context?: ExecutionContext): Promise<MetricResultFor<TDataset, TMetricName, TQuery>>;
     execute<TDatasetName extends string, TMetricName extends string, TDataset extends TypedDataset<TDatasetName>, const TQuery extends MetricQueryFor<TDataset, TMetricName> = MetricQueryFor<TDataset, TMetricName>>(target: TypedGrainedMetricRef<TDatasetName, TMetricName, TDataset>, query?: TQuery, context?: ExecutionContext): Promise<MetricResultFor<TDataset, TMetricName, TQuery>>;
-    execute<TRow = Record<string, unknown>, TTarget extends SemanticTarget = SemanticTarget>(target: TTarget, query?: SemanticQuery<TTarget>, context?: ExecutionContext): Promise<SemanticResult<TTarget, TRow>>;
+    execute<TDatasetName extends string, TMetricName extends string, TDataset extends TypedDataset<TDatasetName>, const TQuery extends MetricQueryFor<TDataset, TMetricName> = MetricQueryFor<TDataset, TMetricName>>(target: TypedMetricRef<TDatasetName, TMetricName, TDataset> | TypedGrainedMetricRef<TDatasetName, TMetricName, TDataset>, query?: TQuery, context?: ExecutionContext): Promise<MetricResultFor<TDataset, TMetricName, TQuery>>;
+    /** Explicit row types opt into the legacy dynamic query contract. */
+    execute<TRow = never, TTarget extends SemanticTarget = SemanticTarget>(target: [TRow] extends [never] ? never : TTarget, query?: SemanticQuery<TTarget>, context?: ExecutionContext): Promise<SemanticResult<TTarget, TRow>>;
+    /** Compile the actual dataset execution SQL, including ceilings and pagination overfetch.
+     * SQL and parameters are trusted-only; describe()/JSON serialization omit values.
+     * Frozen semantic backends and standalone metric handles are not supported.
+     */
+    compileDataset<TDataset extends TypedDataset>(target: TDataset, query?: DatasetQueryFor<TDataset>, context?: ExecutionContext): DatasetCompilation;
     toSQL<TTarget extends SemanticTarget>(target: TTarget, query?: SemanticQuery<TTarget>, context?: ExecutionContext): string;
     validate<TTarget extends SemanticTarget>(target: TTarget, query?: SemanticQuery<TTarget>, context?: ExecutionContext): ValidationResult;
     /** Lookup counters for this client's semantic result cache. */
@@ -57,26 +59,6 @@ export interface DatasetClient {
      */
     clearCache(): Promise<boolean>;
 }
-export declare class MetricQueryEngine {
-    private builderFactory;
-    constructor(options: MetricQueryEngineOptions);
-    protected getBuilderFactory(): QueryBuilderFactoryLike;
-    /**
-     * Execute a metric query. Generates SQL, applies tenant/filter context, executes.
-     */
-    run<T = Record<string, unknown>>(metric: MetricRef | GrainedMetricRef, query?: MetricQuery, context?: ExecutionContext): Promise<MetricResult<T>>;
-    /**
-     * Generate SQL without executing.
-     */
-    toSQL(metric: MetricRef | GrainedMetricRef, query?: MetricQuery, context?: ExecutionContext): string;
-    /**
-     * Validate a metric query against the metric's contract.
-     */
-    validate(metric: MetricRef | GrainedMetricRef, query: MetricQuery, context?: ExecutionContext): ValidationResult;
-    private runViaBuilder;
-    private buildBaseQuery;
-    private buildDerivedSQLViaBuilder;
-}
 export declare class DatasetClientImpl extends MetricQueryEngine implements DatasetClient {
     private backend?;
     private readonly defaultTimezone?;
@@ -95,11 +77,6 @@ export declare class DatasetClientImpl extends MetricQueryEngine implements Data
      * the common uncached path.
      */
     private isCacheable;
-    /**
-     * Context used for cache-key building: fills in the client-level default
-     * `cache.scope` unless the call sets its own, so clients sharing a custom
-     * store can be namespaced apart.
-     */
     /** The call's cache partition: its own `cache.scope`, else the client default. */
     private cacheScope;
     planMetric(metric: MetricRef | GrainedMetricRef, query?: MetricQuery, context?: ExecutionContext): PlanNode;
@@ -110,6 +87,8 @@ export declare class DatasetClientImpl extends MetricQueryEngine implements Data
     execute<TDataset extends DatasetInstance<any, any, any, any>, const TQuery extends DatasetQueryFor<TDataset> = DatasetQueryFor<TDataset>>(target: TDataset, query?: TQuery, context?: ExecutionContext): Promise<DatasetQueryResultFor<TDataset, TQuery>>;
     execute<TDatasetName extends string, TMetricName extends string, TDataset extends DatasetInstance<any, any, any, TDatasetName>, const TQuery extends MetricQueryFor<TDataset, TMetricName> = MetricQueryFor<TDataset, TMetricName>>(target: MetricRef<TDatasetName, TMetricName, any, TDataset>, query?: TQuery, context?: ExecutionContext): Promise<MetricResultFor<TDataset, TMetricName, TQuery>>;
     execute<TDatasetName extends string, TMetricName extends string, TDataset extends DatasetInstance<any, any, any, TDatasetName>, const TQuery extends MetricQueryFor<TDataset, TMetricName> = MetricQueryFor<TDataset, TMetricName>>(target: GrainedMetricRef<TDatasetName, TMetricName, any, TDataset>, query?: TQuery, context?: ExecutionContext): Promise<MetricResultFor<TDataset, TMetricName, TQuery>>;
+    execute<TDatasetName extends string, TMetricName extends string, TDataset extends TypedDataset<TDatasetName>, const TQuery extends MetricQueryFor<TDataset, TMetricName> = MetricQueryFor<TDataset, TMetricName>>(target: TypedMetricRef<TDatasetName, TMetricName, TDataset> | TypedGrainedMetricRef<TDatasetName, TMetricName, TDataset>, query?: TQuery, context?: ExecutionContext): Promise<MetricResultFor<TDataset, TMetricName, TQuery>>;
+    compileDataset<TDataset extends TypedDataset>(target: TDataset, query?: DatasetQueryFor<TDataset>, context?: ExecutionContext): DatasetCompilation;
     toSQL<TTarget extends SemanticTarget>(target: TTarget, query?: SemanticQuery<TTarget>, context?: ExecutionContext): string;
     validate<TTarget extends SemanticTarget>(target: TTarget, query?: SemanticQuery<TTarget>, context?: ExecutionContext): ValidationResult;
     private executeMetric;

package/dist/executor.d.ts.map

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

package/dist/executor.js

@@ -1,386 +1,23 @@
-import { queryTimezoneErrors, queryTimeFilterSql } from './utils/query-timezone.js';
-import { selectedTimeMeasures, rejectTimeMeasuresOnBackend } from './utils/time-query-measures.js';
-import { buildTimeMeasureDatasetSql } from './utils/time-measure-dataset-sql.js';
-import { baseMeasureNames } from './utils/dataset-measures.js';
-import { protocolMetricCapabilityErrors } from './utils/protocol-metric-capabilities.js';
 import { toQueryBuilderFactory } from './query-builder-protocol.js';
-import { quoteSQLIdentifier, validateSQLIdentifier } from './sql-utils.js';
-import { unsupportedTimeGrainError } from './utils/dataset-time-grains.js';
-import { validateFilterValue } from './validation.js';
-import { applyAggregationSpec, appendOrderLimitOffset, buildDimensionSelectionPlan, resolveDimensionExpression, resolveFilterField, resolveTenantFilterColumn, } from './query-planner.js';
-import { assertMetricHandle, getMetricGrain, getMetricRef, isTenantScopedFilter, } from './utils/metric-handle.js';
-import { validateDerivedCteGrouping } from './utils/derived-cte-validation.js';
-import { buildDatasetQueryBuilder, runDatasetQuery, validateDatasetQuery, } from './dataset-query.js';
-import { buildDerivedDatasetSql, hasSelectedDerivedMeasure, } from './utils/dataset-derived-query.js';
-import { buildDatasetPlan, buildMetricPlan, } from './semantic-planner.js';
-import { getRuntimeTenantId, getRuntimeTenantPredicate, validateTenantRuntime, } from './utils/tenant-runtime.js';
-import { applyPagination, overfetchLimit } from './utils/pagination.js';
+import { MetricQueryEngine } from './metric-query-engine.js';
+import { runDatasetQuery, validateDatasetQuery } from './dataset-query.js';
+import { buildDatasetPlan, buildMetricPlan } from './semantic-planner.js';
+import { assertMetricHandle, getMetricRef } from './utils/metric-handle.js';
+import { validateMetricQueryInput } from './utils/metric-query-validation.js';
+import { prepareDatasetQuery } from './utils/compile-dataset-query.js';
+import { snapshotExecutionContext } from './utils/snapshot-execution-context.js';
+import { isDatasetInstance } from './utils/dataset-target.js';
+import { queryTimezoneErrors } from './utils/query-timezone.js';
+import { rejectTimeMeasuresOnBackend } from './utils/time-query-measures.js';
+import { baseMeasureNames } from './utils/dataset-measures.js';
+import { hasSelectedDerivedMeasure } from './utils/dataset-derived-query.js';
 import { serializeSemanticMeasureValues } from './utils/semantic-result-serialization.js';
+import { resolveResultLimit, withResultLimit } from './utils/result-limits.js';
+import { resolveDatasetCacheRuntime } from './utils/dataset-cache-policy.js';
 import { SemanticQueryCache, } from './cache/semantic-query-cache.js';
 import { datasetCacheKey, metricCacheKey, resolveProtocolCacheKeySettings, } from './cache/protocol-cache-keys.js';
-import { resolveResultLimit, withResultLimit } from './utils/result-limits.js';
-import { resolveDatasetCacheRuntime, } from './utils/dataset-cache-policy.js';
-import { isQualifiedField, resolveQualifiedField } from './utils/relationship-fields.js';
-import { validateQualifiedFilter, validateRelationshipTenantRuntime, } from './utils/relationship-validation.js';
-import { applyRelationshipJoins, buildRelationshipBuilderContext, qualifyBaseColumn, } from './utils/relationship-builder-plan.js';
-import { segmentFilters, segmentSelectionErrors } from './utils/segments.js';
-function validateQuery(metric, query, context) {
-    const errors = [...protocolMetricCapabilityErrors(metric, query), ...queryTimezoneErrors(query.timezone)];
-    const ref = getMetricRef(metric);
-    const ds = ref.dataset;
-    const dimensionNames = Object.keys(ds.dimensions);
-    const filterNames = Object.keys(ds.filters);
-    const grain = getMetricGrain(metric, query);
-    const orderableFields = new Set([
-        ...(query.dimensions ?? []),
-        ref.name,
-        ...(grain ? ['period'] : []),
-    ]);
-    const tenantRuntimeError = validateTenantRuntime(ds, context);
-    if (tenantRuntimeError) {
-        errors.push(tenantRuntimeError);
-    }
-    const relationshipTenantError = validateRelationshipTenantRuntime(ds, query, context);
-    if (relationshipTenantError) {
-        errors.push(relationshipTenantError);
-    }
-    if (metric.__type === 'grained_metric_ref' && query.by && query.by !== metric.grain) {
-        errors.push(`Metric "${ref.name}" is already grained by "${metric.grain}" and cannot be queried with by="${query.by}".`);
-    }
-    // Validate dimensions
-    for (const dim of query.dimensions ?? []) {
-        if (isQualifiedField(dim)) {
-            const resolution = resolveQualifiedField(ds, dim);
-            if (resolution?.error) {
-                errors.push(resolution.error);
-            }
-            continue;
-        }
-        if (!dimensionNames.includes(dim)) {
-            errors.push(`Unknown dimension "${dim}". Available: ${dimensionNames.join(', ')}`);
-        }
-    }
-    // Validate filters
-    for (const filter of query.filters ?? []) {
-        if (isQualifiedField(filter.field)) {
-            const filterError = validateQualifiedFilter(ds, filter, context);
-            if (filterError) {
-                errors.push(filterError);
-            }
-            continue;
-        }
-        if (!filterNames.includes(filter.field)) {
-            errors.push(`Unknown filter field "${filter.field}". Available: ${filterNames.join(', ')}`);
-            continue;
-        }
-        const filterDefinition = ds.filters[filter.field];
-        if (filterDefinition?.operators && !filterDefinition.operators.includes(filter.operator)) {
-            errors.push(`Filter "${filter.field}" does not allow operator "${filter.operator}". Allowed: ${filterDefinition.operators.join(', ')}`);
-            continue;
-        }
-        const resolvedField = ds.filters[filter.field]?.field ?? filter.field;
-        if (isTenantScopedFilter(ds, filter, context)) {
-            errors.push(`Cannot filter on tenant field "${filter.field}" when runtime tenancy enforcement is active.`);
-            continue;
-        }
-        const fieldType = ds.dimensions[resolvedField]?.fieldType;
-        if (fieldType) {
-            const filterError = validateFilterValue(filter, fieldType);
-            if (filterError) {
-                errors.push(filterError);
-            }
-        }
-    }
-    // Validate order by fields against the metric output shape
-    for (const order of query.orderBy ?? []) {
-        if (!orderableFields.has(order.field)) {
-            errors.push(`Unknown orderBy field "${order.field}". Available: ${Array.from(orderableFields).join(', ')}`);
-        }
-    }
-    // Validate grain requires timeKey
-    if (query.by && !ds.timeKey) {
-        errors.push(`Cannot use "by" grain — dataset "${ds.name}" has no timeKey.`);
-    }
-    // Validate grain is one the planner can bucket on
-    errors.push(...segmentSelectionErrors(ds, query.segments));
-    const grainError = query.by && ds.timeKey ? unsupportedTimeGrainError(ds, query.by) : undefined;
-    if (grainError) {
-        errors.push(grainError);
-    }
-    if (query.limit != null && (!Number.isInteger(query.limit) || query.limit < 0)) {
-        errors.push(`Invalid limit: expected a non-negative integer.`);
-    }
-    if (query.offset != null && (!Number.isInteger(query.offset) || query.offset < 0)) {
-        errors.push(`Invalid offset: expected a non-negative integer.`);
-    }
-    // Validate limits
-    if (ds.limits) {
-        if (ds.limits.maxDimensions && (query.dimensions?.length ?? 0) > ds.limits.maxDimensions) {
-            errors.push(`Too many dimensions (${query.dimensions?.length}). Max: ${ds.limits.maxDimensions}`);
-        }
-        if (ds.limits.maxMeasures && 1 > ds.limits.maxMeasures) {
-            errors.push(`Too many measures (1). Max: ${ds.limits.maxMeasures}`);
-        }
-        if (ds.limits.maxFilters && (query.filters?.length ?? 0) > ds.limits.maxFilters) {
-            errors.push(`Too many filters (${query.filters?.length}). Max: ${ds.limits.maxFilters}`);
-        }
-        if (ds.limits.maxResultSize && query.limit != null && query.limit > ds.limits.maxResultSize) {
-            errors.push(`Too many results requested (${query.limit}). Max: ${ds.limits.maxResultSize}`);
-        }
-    }
-    return { valid: errors.length === 0, errors };
-}
-function isDatasetInstance(target) {
-    return !!target && typeof target === 'object' && '__type' in target && target.__type === 'dataset';
-}
-/** Resolves the per-call builder override, adapted to the call contract. */
-function resolveBuilderFactory(context, fallback) {
-    const override = context?.runtime?.builderFactory;
-    return override ? toQueryBuilderFactory(override) : fallback;
-}
-export class MetricQueryEngine {
-    builderFactory;
-    constructor(options) {
-        this.builderFactory = toQueryBuilderFactory(options.builderFactory);
-    }
-    getBuilderFactory() {
-        return this.builderFactory;
-    }
-    /**
-     * Execute a metric query. Generates SQL, applies tenant/filter context, executes.
-     */
-    async run(metric, query = {}, context) {
-        assertMetricHandle(metric);
-        const validation = this.validate(metric, query, context);
-        if (!validation.valid) {
-            throw new Error(`Invalid metric query: ${validation.errors.join('; ')}`);
-        }
-        const start = Date.now();
-        return this.runViaBuilder(metric, query, context, start);
-    }
-    /**
-     * Generate SQL without executing.
-     */
-    toSQL(metric, query = {}, context) {
-        assertMetricHandle(metric);
-        const validation = this.validate(metric, query, context);
-        if (!validation.valid) {
-            throw new Error(`Invalid metric query: ${validation.errors.join('; ')}`);
-        }
-        const ref = getMetricRef(metric);
-        const grain = getMetricGrain(metric, query);
-        const spec = ref.spec;
-        if (spec.__type === 'derived_metric_spec') {
-            return this.buildDerivedSQLViaBuilder(ref, spec, query, grain, context).sql;
-        }
-        const builder = this.buildBaseQuery(ref, spec, ref.dataset, query, grain, context);
-        return builder.toSQLWithParams().sql;
-    }
-    /**
-     * Validate a metric query against the metric's contract.
-     */
-    validate(metric, query, context) {
-        assertMetricHandle(metric);
-        const queryValidation = validateQuery(metric, query, context);
-        if (!queryValidation.valid) {
-            return queryValidation;
-        }
-        const ref = getMetricRef(metric);
-        const grain = getMetricGrain(metric, query);
-        try {
-            if (ref.spec.__type === 'derived_metric_spec') {
-                this.buildDerivedSQLViaBuilder(ref, ref.spec, query, grain, context);
-            }
-            else {
-                this.buildBaseQuery(ref, ref.spec, ref.dataset, query, grain, context).toSQLWithParams();
-            }
-        }
-        catch (error) {
-            return {
-                valid: false,
-                errors: [error instanceof Error ? error.message : String(error)],
-            };
-        }
-        return queryValidation;
-    }
-    // ---------------------------------------------------------------------------
-    // Query builder path
-    // ---------------------------------------------------------------------------
-    async runViaBuilder(metric, query, context, start) {
-        const ref = getMetricRef(metric);
-        const grain = getMetricGrain(metric, query);
-        const spec = ref.spec;
-        const activeBuilderFactory = resolveBuilderFactory(context, this.builderFactory);
-        // Over-fetch one row so we can report `hasMore` without a count query.
-        const buildQuery = { ...query, limit: overfetchLimit(query.limit) };
-        if (spec.__type === 'derived_metric_spec') {
-            // Derived metrics: build CTE via builder, outer query via string, execute via rawQuery
-            const { sql, params } = this.buildDerivedSQLViaBuilder(ref, spec, buildQuery, grain, context);
-            const rows = await activeBuilderFactory.rawQuery(sql, params, {
-                abortSignal: context?.abortSignal,
-            });
-            const timingMs = Date.now() - start;
-            const { data, pagination } = applyPagination(rows, query.limit, query.offset);
-            const serializedData = serializeSemanticMeasureValues(data, [ref.name]);
-            return {
-                data: serializedData,
-                meta: {
-                    sql,
-                    timingMs,
-                    tenant: getRuntimeTenantId(context),
-                    rowCount: serializedData.length,
-                    pagination,
-                },
-            };
-        }
-        // Base metrics: fully use the builder's execute()
-        const builder = this.buildBaseQuery(ref, spec, ref.dataset, buildQuery, grain, context);
-        const { sql } = builder.toSQLWithParams();
-        const rows = await builder.execute({ abortSignal: context?.abortSignal });
-        const timingMs = Date.now() - start;
-        const { data, pagination } = applyPagination(rows, query.limit, query.offset);
-        const serializedData = serializeSemanticMeasureValues(data, [ref.name]);
-        return {
-            data: serializedData,
-            meta: {
-                sql,
-                timingMs,
-                tenant: getRuntimeTenantId(context),
-                rowCount: serializedData.length,
-                pagination,
-            },
-        };
-    }
-    buildBaseQuery(ref, spec, ds, query, grain, context) {
-        const activeBuilderFactory = resolveBuilderFactory(context, this.builderFactory);
-        const joinCtx = buildRelationshipBuilderContext(ds, query, context);
-        let qb = activeBuilderFactory.table(ds.source);
-        qb = applyRelationshipJoins(qb, joinCtx);
-        const { selectParts, groupByParts } = buildDimensionSelectionPlan(ds, query.dimensions ?? [], grain, joinCtx, query.timezone);
-        if (selectParts.length > 0) {
-            qb = qb.select(selectParts);
-        }
-        // Aggregation (appends to select, auto-sets groupBy on non-agg columns)
-        qb = applyAggregationSpec(qb, ds, spec, ref.name, joinCtx);
-        // Explicit groupBy (ensures period + dims are grouped even if aggregation auto-groupBy misses them)
-        if (groupByParts.length > 0) {
-            qb = qb.groupBy(groupByParts);
-        }
-        // Tenant auto-injection
-        const tenantColumn = resolveTenantFilterColumn(ds, context);
-        const tenantPredicate = getRuntimeTenantPredicate(context);
-        if (tenantPredicate && tenantColumn) {
-            qb = qb.where(qualifyBaseColumn(joinCtx, tenantColumn), tenantPredicate.operator, tenantPredicate.value);
-        }
-        // User filters
-        for (const filter of query.filters ?? []) {
-            if (isTenantScopedFilter(ds, filter, context)) {
-                throw new Error(`Cannot filter on tenant field "${filter.field}" when runtime tenancy enforcement is active.`);
-            }
-            const resolvedField = resolveFilterField(ds, filter.field, joinCtx);
-            qb = qb.where(queryTimeFilterSql(ds, filter.field, resolvedField, query.timezone), filter.operator, filter.value);
-        }
-        // Segments: author-defined, so they resolve dimensions directly rather
-        // than through the caller-facing filter allow-list.
-        for (const filter of segmentFilters(ds, query.segments)) {
-            qb = qb.where(resolveDimensionExpression(ds, filter.field, joinCtx), filter.operator, filter.value);
-        }
-        // Order, limit, offset
-        qb = appendOrderLimitOffset(qb, query.orderBy, grain, query.limit, query.offset, joinCtx);
-        return qb;
-    }
-    buildDerivedSQLViaBuilder(ref, spec, query, grain, context) {
-        const activeBuilderFactory = resolveBuilderFactory(context, this.builderFactory);
-        const ds = ref.dataset;
-        const joinCtx = buildRelationshipBuilderContext(ds, query, context);
-        // Build the CTE inner query using the builder
-        let cteBuilder = activeBuilderFactory.table(ds.source);
-        cteBuilder = applyRelationshipJoins(cteBuilder, joinCtx);
-        const { selectParts, groupByParts } = buildDimensionSelectionPlan(ds, query.dimensions ?? [], grain, joinCtx, query.timezone);
-        if (selectParts.length > 0) {
-            cteBuilder = cteBuilder.select(selectParts);
-        }
-        // Base aggregations
-        const refAliases = {};
-        const aggregateAliases = [];
-        for (const [alias, baseMetric] of Object.entries(spec.uses)) {
-            const baseSpec = baseMetric.spec;
-            if (baseSpec.__type !== 'aggregation_spec') {
-                throw new Error(`Derived metric "${ref.name}" references non-base metric "${alias}".`);
-            }
-            cteBuilder = applyAggregationSpec(cteBuilder, ds, baseSpec, alias, joinCtx);
-            refAliases[alias] = alias;
-            aggregateAliases.push(alias);
-        }
-        if (groupByParts.length > 0) {
-            cteBuilder = cteBuilder.groupBy(groupByParts);
-        }
-        // Filters on CTE
-        const tenantColumn = resolveTenantFilterColumn(ds, context);
-        const tenantPredicate = getRuntimeTenantPredicate(context);
-        if (tenantPredicate && tenantColumn) {
-            cteBuilder = cteBuilder.where(qualifyBaseColumn(joinCtx, tenantColumn), tenantPredicate.operator, tenantPredicate.value);
-        }
-        for (const filter of query.filters ?? []) {
-            if (isTenantScopedFilter(ds, filter, context)) {
-                throw new Error(`Cannot filter on tenant field "${filter.field}" when runtime tenancy enforcement is active.`);
-            }
-            const resolvedField = resolveFilterField(ds, filter.field, joinCtx);
-            cteBuilder = cteBuilder.where(queryTimeFilterSql(ds, filter.field, resolvedField, query.timezone), filter.operator, filter.value);
-        }
-        for (const filter of segmentFilters(ds, query.segments)) {
-            cteBuilder = cteBuilder.where(resolveDimensionExpression(ds, filter.field, joinCtx), filter.operator, filter.value);
-        }
-        const { sql: cteSql, parameters: cteParams } = cteBuilder.toSQLWithParams();
-        const groupingErrors = validateDerivedCteGrouping(cteSql, aggregateAliases, groupByParts);
-        if (groupingErrors.length > 0) {
-            throw new Error(groupingErrors.join('; '));
-        }
-        // Outer query: trivial SELECT from the CTE — stays as string concat
-        // because table('base') would fail schema typing
-        const outerSelectParts = [];
-        if (grain)
-            outerSelectParts.push('period');
-        for (const dim of query.dimensions ?? []) {
-            // Joined dimensions surface from the CTE under their quoted qualified alias.
-            if (joinCtx && isQualifiedField(dim)) {
-                outerSelectParts.push(quoteSQLIdentifier(dim));
-                continue;
-            }
-            validateSQLIdentifier(dim, 'dimension name');
-            outerSelectParts.push(dim);
-        }
-        const formulaExpr = spec.formula(refAliases);
-        validateSQLIdentifier(ref.name, 'metric name');
-        outerSelectParts.push(`${formulaExpr.toSQL()} AS ${ref.name}`);
-        let sql = `WITH base AS (${cteSql}) SELECT ${outerSelectParts.join(', ')} FROM base`;
-        // ORDER BY
-        if (query.orderBy && query.orderBy.length > 0) {
-            const orderParts = query.orderBy.map(o => {
-                if (joinCtx && isQualifiedField(o.field)) {
-                    return `${quoteSQLIdentifier(o.field)} ${o.direction.toUpperCase()}`;
-                }
-                validateSQLIdentifier(o.field, 'order by field');
-                return `${o.field} ${o.direction.toUpperCase()}`;
-            });
-            sql += ` ORDER BY ${orderParts.join(', ')}`;
-        }
-        else if (grain) {
-            sql += ' ORDER BY period';
-        }
-        if (query.limit != null) {
-            // Ensure limit is a safe integer
-            const limit = Math.floor(Math.abs(query.limit));
-            sql += ` LIMIT ${limit}`;
-        }
-        if (query.offset != null) {
-            // Ensure offset is a safe integer
-            const offset = Math.floor(Math.abs(query.offset));
-            sql += ` OFFSET ${offset}`;
-        }
-        return { sql, params: cteParams };
-    }
-}
+// Preserve the existing module surface for internal consumers.
+export { MetricQueryEngine } from './metric-query-engine.js';
 export class DatasetClientImpl extends MetricQueryEngine {
     backend;
     defaultTimezone;
@@ -460,11 +97,6 @@ export class DatasetClientImpl extends MetricQueryEngine {
         }
         return this.cacheEnabledByDefault;
     }
-    /**
-     * Context used for cache-key building: fills in the client-level default
-     * `cache.scope` unless the call sets its own, so clients sharing a custom
-     * store can be namespaced apart.
-     */
     /** The call's cache partition: its own `cache.scope`, else the client default. */
     cacheScope(context) {
         if (context?.cache === false)
@@ -474,7 +106,7 @@ export class DatasetClientImpl extends MetricQueryEngine {
     planMetric(metric, query = {}, context) {
         query = this.withTimezone(query);
         assertMetricHandle(metric);
-        const validation = validateQuery(metric, query, context);
+        const validation = validateMetricQueryInput(metric, query, context);
         if (!validation.valid) {
             throw new Error(`Invalid metric query: ${validation.errors.join('; ')}`);
         }
@@ -484,7 +116,10 @@ export class DatasetClientImpl extends MetricQueryEngine {
         return buildDatasetPlan(ds, this.withTimezone(query), context);
     }
     execute(target, query = {}, context) {
-        query = this.withTimezone(query);
+        // An async cache read must not let caller mutations change the query or
+        // tenant after its key has been derived.
+        query = this.withTimezone(structuredClone(query));
+        context = snapshotExecutionContext(context);
         if (this.backend && query.timezone !== undefined) {
             throw new Error('Execution timezone requires the queryBuilder execution path.');
         }
@@ -493,6 +128,16 @@ export class DatasetClientImpl extends MetricQueryEngine {
         }
         return this.executeMetric(target, query, context);
     }
+    compileDataset(target, query = {}, context) {
+        if (this.backend)
+            throw new Error('Dataset compilation requires the queryBuilder execution path.');
+        if (!isDatasetInstance(target))
+            throw new Error('Dataset compilation requires a dataset target.');
+        return prepareDatasetQuery(target, this.withTimezone(query), {
+            builderFactory: this.resolveBuilderFactory(context),
+            context,
+        }).compilation;
+    }
     toSQL(target, query = {}, context) {
         query = this.withTimezone(query);
         if (this.backend && query.timezone !== undefined) {
@@ -522,7 +167,7 @@ export class DatasetClientImpl extends MetricQueryEngine {
         const cacheRuntime = this.datasetCacheContext(ds, context);
         const run = () => {
             if (this.backend) {
-                const validation = validateQuery(metric, boundedQuery, context);
+                const validation = validateMetricQueryInput(metric, boundedQuery, context);
                 if (!validation.valid) {
                     throw new Error(`Invalid metric query: ${validation.errors.join('; ')}`);
                 }
@@ -540,7 +185,7 @@ export class DatasetClientImpl extends MetricQueryEngine {
         // missing tenant runtime cannot be served from cache. Avoid this.validate()
         // here because it dry-builds SQL, which is unnecessary on cache hits and
         // invalid for backend-only clients.
-        const validation = validateQuery(metric, boundedQuery, context);
+        const validation = validateMetricQueryInput(metric, boundedQuery, context);
         if (!validation.valid) {
             throw new Error(`Invalid metric query: ${validation.errors.join('; ')}`);
         }
@@ -567,6 +212,9 @@ export class DatasetClientImpl extends MetricQueryEngine {
                 if (hasSelectedDerivedMeasure(ds, boundedQuery)) {
                     throw new Error('Derived dataset measures require the queryBuilder execution path.');
                 }
+                if (boundedQuery.having?.length) {
+                    throw new Error('Dataset having conditions require the queryBuilder execution path.');
+                }
                 return this.backend.execute(this.planDataset(ds, boundedQuery, context), { abortSignal: context?.abortSignal }).then((result) => ({
                     ...result,
                     data: serializeSemanticMeasureValues(result.data, 
@@ -575,7 +223,7 @@ export class DatasetClientImpl extends MetricQueryEngine {
                 }));
             }
             return runDatasetQuery(ds, boundedQuery, {
-                builderFactory: resolveBuilderFactory(context, this.getBuilderFactory()),
+                builderFactory: this.resolveBuilderFactory(context),
                 context,
             });
         };
@@ -603,18 +251,10 @@ export class DatasetClientImpl extends MetricQueryEngine {
         return { ...context, cache };
     }
     toDatasetSQL(ds, query, context) {
-        const builderFactory = resolveBuilderFactory(context, this.getBuilderFactory());
-        if (selectedTimeMeasures(ds, query).size) {
-            return buildTimeMeasureDatasetSql(ds, query, { builderFactory, context }).sql;
-        }
-        if (hasSelectedDerivedMeasure(ds, query)) {
-            return buildDerivedDatasetSql(ds, query, { builderFactory, context }, buildDatasetQueryBuilder).sql;
-        }
-        const builder = buildDatasetQueryBuilder(ds, query, {
-            builderFactory,
+        return prepareDatasetQuery(ds, query, {
+            builderFactory: this.resolveBuilderFactory(context),
             context,
-        });
-        return builder.toSQLWithParams().sql;
+        }, 'logical').compilation.sql;
     }
 }
 export function createDatasetClient(options) {