@hypequery/datasets 0.21.0 → 0.23.0

package/dist/utils/relationship-keys.d.ts

@@ -0,0 +1,17 @@
+import type { RelationshipDefinition, RelationshipJoin, RelationshipKey } from '../types.js';
+type NormalizedRelationshipJoin = Pick<RelationshipDefinition, 'from' | 'to' | 'keys'>;
+/**
+ * Snapshot an authored join. `{ from, to }` passes through unchanged, as it
+ * always has; `keys` pairs are validated before they are interpolated into SQL.
+ */
+export declare function normalizeRelationshipJoin(join: RelationshipJoin): NormalizedRelationshipJoin;
+/**
+ * Rebuild a serialized composite key. Portable records carry `keys` only for
+ * composite relationships, and `from`/`to` must mirror the first pair.
+ */
+export declare function rehydrateCompositeRelationshipJoin(from: string, to: string, keys: readonly RelationshipKey[]): NormalizedRelationshipJoin;
+export declare function validateRelationshipKeys(keys: readonly RelationshipKey[]): asserts keys is readonly [RelationshipKey, ...RelationshipKey[]];
+/** Return the whole equality key; legacy relationships remain single-key. */
+export declare function relationshipKeys(relationship: Pick<RelationshipDefinition, 'from' | 'to' | 'keys'>): readonly RelationshipKey[];
+export {};
+//# sourceMappingURL=relationship-keys.d.ts.map

package/dist/utils/relationship-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-keys.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAI7F,KAAK,0BAA0B,GAAG,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC,CAAC;AAEvF;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,gBAAgB,GAAG,0BAA0B,CAgB5F;AAED;;;GAGG;AACH,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,0BAA0B,CAU5B;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,OAAO,CAAC,IAAI,IAAI,SAAS,CAAC,eAAe,EAAE,GAAG,eAAe,EAAE,CAAC,CAYlE;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC,GAAG,SAAS,eAAe,EAAE,CAQ/H"}

package/dist/utils/relationship-keys.js

@@ -0,0 +1,63 @@
+const COLUMN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Snapshot an authored join. `{ from, to }` passes through unchanged, as it
+ * always has; `keys` pairs are validated before they are interpolated into SQL.
+ */
+export function normalizeRelationshipJoin(join) {
+    if (join.keys === undefined) {
+        return { from: join.from, to: join.to };
+    }
+    if (join.from !== undefined || join.to !== undefined) {
+        throw new Error('Relationship keys cannot be combined with from/to.');
+    }
+    const keys = join.keys;
+    validateRelationshipKeys(keys);
+    const copy = [
+        Object.freeze({ from: keys[0].from, to: keys[0].to }),
+        ...keys.slice(1).map(key => Object.freeze({ from: key.from, to: key.to })),
+    ];
+    // A single pair is the legacy relationship: contracts and catalogs carry
+    // `keys` only for composite relationships, however the pair was authored.
+    return { from: copy[0].from, to: copy[0].to, ...(copy.length > 1 ? { keys: Object.freeze(copy) } : {}) };
+}
+/**
+ * Rebuild a serialized composite key. Portable records carry `keys` only for
+ * composite relationships, and `from`/`to` must mirror the first pair.
+ */
+export function rehydrateCompositeRelationshipJoin(from, to, keys) {
+    validateRelationshipKeys(keys);
+    if (keys.length < 2) {
+        throw new Error('Serialized relationship keys must contain at least two pairs; single-key relationships use from/to.');
+    }
+    const join = normalizeRelationshipJoin({ keys });
+    if (join.from !== from || join.to !== to) {
+        throw new Error('Relationship from/to must match the first keys pair.');
+    }
+    return join;
+}
+export function validateRelationshipKeys(keys) {
+    if (!Array.isArray(keys) || keys.length === 0)
+        throw new Error('Relationship keys must be a non-empty array.');
+    const from = new Set();
+    const to = new Set();
+    for (const key of keys) {
+        if (!key || typeof key.from !== 'string' || typeof key.to !== 'string' || !COLUMN.test(key.from) || !COLUMN.test(key.to)) {
+            throw new Error('Relationship keys must contain safe physical from/to column identifiers.');
+        }
+        if (from.has(key.from) || to.has(key.to))
+            throw new Error('Relationship keys must not repeat a source or target column.');
+        from.add(key.from);
+        to.add(key.to);
+    }
+}
+/** Return the whole equality key; legacy relationships remain single-key. */
+export function relationshipKeys(relationship) {
+    const keys = relationship.keys ?? [{ from: relationship.from, to: relationship.to }];
+    if (!relationship.keys)
+        return keys;
+    validateRelationshipKeys(keys);
+    if (keys[0].from !== relationship.from || keys[0].to !== relationship.to) {
+        throw new Error('Relationship from/to must match the first keys pair.');
+    }
+    return keys;
+}

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

@@ -0,0 +1,14 @@
+import type { AnyDatasetInstance } from '../types.js';
+import type { RelationshipBuilderContext } from './relationship-builder-plan.js';
+import type { DatasetSqlDialect } from '../dataset-sql-dialect.js';
+/** Explicit projection avoids marker collisions and makes absent targets detectable under join_use_nulls=0. */
+export declare function relationshipMeasureSource(target: AnyDatasetInstance, to: readonly string[], names: readonly string[], dialect: DatasetSqlDialect): {
+    source: string;
+    marker: string;
+};
+export declare function relationshipMeasureExpressions(ds: AnyDatasetInstance, name: string, joinCtx: RelationshipBuilderContext): {
+    definition: import("../types.js").MeasureDefinition;
+    field: string;
+    arg: string | undefined;
+};
+//# sourceMappingURL=relationship-measure-sql.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-measure-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAmB,MAAM,aAAa,CAAC;AAEvE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAIjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,+GAA+G;AAC/G,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,kBAAkB,EAAE,EAAE,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,iBAAiB;;;EAgBhJ;AAED,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B;;;;EAevH"}

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

@@ -0,0 +1,44 @@
+import { resolveRelationshipMeasure } from './relationship-measures.js';
+import { resolveDimensionExpression } from '../query-planner.js';
+import { measureToAggregationSpec } from './dataset-normalization.js';
+import { applyFilteredAggregationExpression } from './filtered-aggregation-sql.js';
+/** Explicit projection avoids marker collisions and makes absent targets detectable under join_use_nulls=0. */
+export function relationshipMeasureSource(target, to, names, dialect) {
+    const columns = new Set([...to, ...(target.tenantKey ? [target.tenantKey] : [])]);
+    for (const [name, dimension] of Object.entries(target.dimensions))
+        if (!dimension.sql)
+            columns.add(dimension.column ?? name);
+    for (const name of names) {
+        const measure = target.measures[name];
+        if (measure.__type !== 'measure_definition')
+            continue;
+        for (const field of [measure.field, measure.argField, ...(measure.filters ?? []).map(filter => target.filters[filter.field]?.field ?? filter.field)]) {
+            if (field && field !== '*')
+                columns.add(target.dimensions[field]?.column ?? field);
+        }
+    }
+    let marker = '_hq_match';
+    while (columns.has(marker))
+        marker += '_';
+    const quote = dialect.quoteIdentifier;
+    const source = target.source.split('.').map(quote).join('.');
+    const projection = [...columns].map(quote);
+    return { source: `(SELECT ${[...projection, `toNullable(1) AS ${quote(marker)}`].join(', ')} FROM ${source})`, marker };
+}
+export function relationshipMeasureExpressions(ds, name, joinCtx) {
+    const resolved = resolveRelationshipMeasure(ds, name);
+    const { relationshipName, target, definition } = resolved;
+    const marker = joinCtx.joinByRelationship.get(relationshipName)?.matchMarker;
+    if (!marker)
+        throw new Error(`Missing match marker for relationship measure "${name}".`);
+    const ownerContext = { ...joinCtx, baseSource: relationshipName };
+    const spec = measureToAggregationSpec(name, definition);
+    const matched = `isNotNull(${relationshipName}.${marker})`;
+    const field = definition.field === '*' ? `${relationshipName}.${marker}` : resolveDimensionExpression(target, definition.field, ownerContext);
+    const filtered = applyFilteredAggregationExpression(target, spec, field, ownerContext);
+    return {
+        definition,
+        field: `if(${matched}, ${filtered}, NULL)`,
+        arg: definition.argField ? `if(${matched}, ${resolveDimensionExpression(target, definition.argField, ownerContext)}, NULL)` : undefined,
+    };
+}

package/dist/utils/relationship-measure-types.d.ts

@@ -0,0 +1,36 @@
+import type { DatasetInstance, MeasureDefinition, RelationshipDefinition } from '../types.js';
+type SafeAggregation = 'countDistinct' | 'approxCountDistinct' | 'min' | 'max' | 'argMax' | 'argMin';
+type SqlDimensions<TDimensions> = {
+    [K in keyof TDimensions & string]: TDimensions[K] extends {
+        sql: string;
+    } ? K : never;
+}[keyof TDimensions & string];
+/** Fixed filters use their owner's allowlist aliases before dimension resolution. */
+type FixedFilterInputs<TMeasure, TFilters> = TMeasure extends {
+    filters: readonly (infer TFilter)[];
+} ? TFilter extends {
+    field: infer TName extends string;
+} ? TName extends keyof TFilters ? TFilters[TName] extends {
+    field: infer TField extends string;
+} ? TField : TName : TName : never : never;
+type SafeMeasureNames<TMeasures, TKind, TDimensions, TFilters> = {
+    [K in keyof TMeasures & string]: TMeasures[K] extends MeasureDefinition ? TMeasures[K] extends {
+        sql: string;
+    } ? never : TMeasures[K] extends {
+        field: infer F;
+        argField?: infer A;
+    } ? (Extract<F, SqlDimensions<TDimensions>> | Extract<A, SqlDimensions<TDimensions>> | Extract<FixedFilterInputs<TMeasures[K], TFilters>, SqlDimensions<TDimensions>>) extends never ? TKind extends 'hasOne' ? K : TMeasures[K] extends {
+        aggregation: SafeAggregation;
+    } ? K : never : never : never : never;
+}[keyof TMeasures & string];
+/** One-hop base aggregates whose cardinality is safe for the declared relationship. */
+export type QueryableRelationshipMeasureNames<TRelationships> = {
+    [K in keyof TRelationships & string]: TRelationships[K] extends RelationshipDefinition<infer TTarget, infer TKind> ? TKind extends 'hasMany' ? never : TTarget extends DatasetInstance<infer TDimensions, infer TMeasures, any, any> ? `${K}.${SafeMeasureNames<TMeasures, TKind, TDimensions, TTarget['filters']>}` : never : never;
+}[keyof TRelationships & string];
+export type RelationshipMeasureDefinition<TDataset, TName extends string> = TDataset extends {
+    relationships: infer TRelationships;
+} ? TName extends `${infer R}.${infer M}` ? R extends keyof TRelationships ? TRelationships[R] extends RelationshipDefinition<infer TTarget> ? TTarget extends {
+    measures: infer TMeasures;
+} ? M extends keyof TMeasures ? TMeasures[M] : never : never : never : never : never : never;
+export {};
+//# sourceMappingURL=relationship-measure-types.d.ts.map

package/dist/utils/relationship-measure-types.d.ts.map

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

package/dist/utils/relationship-measure-types.js

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

package/dist/utils/relationship-measures.d.ts

@@ -0,0 +1,23 @@
+import type { AnyDatasetInstance, MeasureDefinition, RelationshipDefinition } from '../types.js';
+export interface ResolvedRelationshipMeasure {
+    relationshipName: string;
+    relationship: RelationshipDefinition;
+    target: AnyDatasetInstance;
+    definition: MeasureDefinition;
+}
+/** Resolve only the one-hop, duplicate-safe aggregate vocabulary of RFC 0015. */
+export declare function resolveRelationshipMeasure(ds: AnyDatasetInstance, name: string): ResolvedRelationshipMeasure;
+export declare function listRelationshipMeasures(name: string, relationship: RelationshipDefinition): Record<string, MeasureDefinition>;
+/** Expand selected relationship aggregates for dependency graphs without changing author definitions. */
+export declare function queryMeasureDefinitions(ds: AnyDatasetInstance, selected: readonly string[]): Record<string, import("../types.js").DatasetMeasureDefinition>;
+/** Resolve a selected measure or a dimension reference while collecting joins. */
+export declare function resolveRelationshipReference(ds: AnyDatasetInstance, name: string, measures?: readonly string[]): {
+    resolved: import("./relationship-fields.js").ResolvedQualifiedField;
+    error?: undefined;
+} | {
+    resolved?: undefined;
+    error: string;
+} | {
+    resolved: ResolvedRelationshipMeasure;
+} | null;
+//# sourceMappingURL=relationship-measures.d.ts.map

package/dist/utils/relationship-measures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-measures.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-measures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAMjG,MAAM,WAAW,2BAA2B;IAC1C,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,sBAAsB,CAAC;IACrC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,iBAAiB,CAAC;CAC/B;AAED,iFAAiF;AACjF,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,GAAG,2BAA2B,CAkB5G;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAS9H;AAED,yGAAyG;AACzG,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,kBAAkB,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,kEAM1F;AAED,kFAAkF;AAClF,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,SAAS,MAAM,EAAO;;;;;;;;SAIlH"}

package/dist/utils/relationship-measures.js

@@ -0,0 +1,62 @@
+import { isBaseMeasure } from './dataset-measures.js';
+import { parseQualifiedField, resolveQualifiedField } from './relationship-fields.js';
+const DUPLICATE_INSENSITIVE = new Set(['countDistinct', 'approxCountDistinct', 'min', 'max', 'argMax', 'argMin']);
+/** Resolve only the one-hop, duplicate-safe aggregate vocabulary of RFC 0015. */
+export function resolveRelationshipMeasure(ds, name) {
+    const parsed = parseQualifiedField(name);
+    if (!parsed || parsed.field.includes('.'))
+        throw new Error(`Measure "${name}" must use a one-hop relationship path.`);
+    const relationship = Object.hasOwn(ds.relationships, parsed.relationship) ? ds.relationships[parsed.relationship] : undefined;
+    if (!relationship)
+        throw new Error(`Unknown relationship "${parsed.relationship}" in measure "${name}".`);
+    if (relationship.kind === 'hasMany')
+        throw new Error(`Measure "${name}" cannot traverse hasMany: it would fan out aggregates.`);
+    const target = relationship.target();
+    const definition = Object.hasOwn(target.measures, parsed.field) ? target.measures[parsed.field] : undefined;
+    if (!definition)
+        throw new Error(`Unknown measure "${parsed.field}" on relationship target "${target.name}".`);
+    if (!isBaseMeasure(definition))
+        throw new Error(`Measure "${name}" must reference a base aggregate; derived, window, and shift measures are not selectable through relationships.`);
+    if (relationship.kind === 'belongsTo' && !DUPLICATE_INSENSITIVE.has(definition.aggregation)) {
+        throw new Error(`Measure "${name}" cannot use ${definition.aggregation} through belongsTo: repeated target rows would inflate the aggregation. Use a duplicate-insensitive measure or query the target dataset.`);
+    }
+    const referenced = [definition.field, definition.argField, ...(definition.filters ?? []).map(filter => target.filters[filter.field]?.field ?? filter.field)];
+    if (definition.sql || referenced.some(field => field && target.dimensions[field]?.sql)) {
+        throw new Error(`SQL-backed measure "${name}" or its inputs cannot be traversed through relationships.`);
+    }
+    return { relationshipName: parsed.relationship, relationship, target, definition };
+}
+export function listRelationshipMeasures(name, relationship) {
+    if (relationship.kind === 'hasMany')
+        return {};
+    const ds = { relationships: { [name]: relationship } };
+    const target = relationship.target();
+    return Object.fromEntries(Object.keys(target.measures).flatMap(measure => {
+        const qualified = `${name}.${measure}`;
+        try {
+            return [[qualified, resolveRelationshipMeasure(ds, qualified).definition]];
+        }
+        catch {
+            return [];
+        }
+    }));
+}
+/** Expand selected relationship aggregates for dependency graphs without changing author definitions. */
+export function queryMeasureDefinitions(ds, selected) {
+    const qualified = selected.filter(name => name.includes('.'));
+    return qualified.length ? {
+        ...ds.measures,
+        ...Object.fromEntries(qualified.map(name => [name, resolveRelationshipMeasure(ds, name).definition])),
+    } : ds.measures;
+}
+/** Resolve a selected measure or a dimension reference while collecting joins. */
+export function resolveRelationshipReference(ds, name, measures = []) {
+    if (!measures.includes(name))
+        return resolveQualifiedField(ds, name);
+    try {
+        return { resolved: resolveRelationshipMeasure(ds, name) };
+    }
+    catch (error) {
+        return { error: error.message };
+    }
+}

package/dist/utils/relationship-validation.d.ts

@@ -3,7 +3,7 @@
  * dataset-query and metric-query validators.
  */
 import type { AnyDatasetInstance, DatasetQuery, ExecutionContext, MetricFilter, MetricQuery } from '../types.js';
-type RelationshipQuery = Pick<DatasetQuery & MetricQuery, 'dimensions' | 'filters' | 'orderBy'>;
+type RelationshipQuery = Pick<DatasetQuery & MetricQuery, 'dimensions' | 'filters' | 'orderBy'> & Pick<DatasetQuery, 'measures'>;
 /**
  * Tenant-less base datasets may still reach tenant-scoped data through a
  * relationship. Require either a concrete runtime tenant or the trusted

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

@@ -1 +1 @@
-{"version":3,"file":"relationship-validation.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-validation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACZ,MAAM,aAAa,CAAC;AAWrB,KAAK,iBAAiB,GAAG,IAAI,CAC3B,YAAY,GAAG,WAAW,EAC1B,YAAY,GAAG,SAAS,GAAG,SAAS,CACrC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,iBAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAmBpB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,kBAAkB,EACtB,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,IAAI,CA4Bf"}
+{"version":3,"file":"relationship-validation.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-validation.ts"],"names":[],"mappings":"AACA;;;GAGG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACZ,MAAM,aAAa,CAAC;AAWrB,KAAK,iBAAiB,GAAG,IAAI,CAC3B,YAAY,GAAG,WAAW,EAC1B,YAAY,GAAG,SAAS,GAAG,SAAS,CACrC,GAAG,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;AAEnC;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,iBAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAoBpB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,kBAAkB,EACtB,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,IAAI,CA4Bf"}

package/dist/utils/relationship-validation.js

@@ -1,7 +1,4 @@
-/**
- * Shared validation for relationship-qualified filters, used by both the
- * dataset-query and metric-query validators.
- */
+import { resolveRelationshipReference } from './relationship-measures.js';
 import { validateFilterValue } from '../validation.js';
 import { getRuntimeTenantPredicate, hasTenantRuntime, } from './tenant-runtime.js';
 import { isQualifiedField, resolveQualifiedField, } from './relationship-fields.js';
@@ -16,11 +13,12 @@ export function validateRelationshipTenantRuntime(ds, query, context) {
     }
     const referenced = [
         ...(query.dimensions ?? []),
+        ...(query.measures ?? []),
         ...(query.filters ?? []).map((filter) => filter.field),
         ...(query.orderBy ?? []).map((order) => order.field),
     ].filter(isQualifiedField);
     for (const name of referenced) {
-        const resolution = resolveQualifiedField(ds, name);
+        const resolution = resolveRelationshipReference(ds, name, query.measures);
         if (resolution?.resolved?.target.tenantKey) {
             return `Dataset "${ds.name}" requires runtime tenant scoping because relationship "${resolution.resolved.relationshipName}" targets a tenant-scoped dataset.`;
         }

package/dist/utils/semantic-query-syntax.d.ts

@@ -0,0 +1,6 @@
+import type { DatasetQuery, MetricQuery } from '../types.js';
+/** Reject SQL structure outside the semantic contract before reaching a builder. */
+export declare function semanticQuerySyntaxErrors(query: DatasetQuery | MetricQuery): string[];
+/** Never interpolate a caller-provided direction into raw SQL. */
+export declare function semanticOrderDirection(direction: unknown): 'ASC' | 'DESC';
+//# sourceMappingURL=semantic-query-syntax.d.ts.map

package/dist/utils/semantic-query-syntax.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-query-syntax.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-query-syntax.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE7D,oFAAoF;AACpF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,GAAG,MAAM,EAAE,CAarF;AAED,kEAAkE;AAClE,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,CAIzE"}

package/dist/utils/semantic-query-syntax.js

@@ -0,0 +1,24 @@
+import { isSemanticFilterOperator } from '../constants.js';
+/** Reject SQL structure outside the semantic contract before reaching a builder. */
+export function semanticQuerySyntaxErrors(query) {
+    const errors = [];
+    for (const filter of query.filters ?? []) {
+        if (!isSemanticFilterOperator(filter.operator)) {
+            errors.push(`Unsupported semantic filter operator "${String(filter.operator)}".`);
+        }
+    }
+    for (const order of query.orderBy ?? []) {
+        if (order.direction !== 'asc' && order.direction !== 'desc') {
+            errors.push('Invalid order direction: expected "asc" or "desc".');
+        }
+    }
+    return errors;
+}
+/** Never interpolate a caller-provided direction into raw SQL. */
+export function semanticOrderDirection(direction) {
+    if (direction === 'asc')
+        return 'ASC';
+    if (direction === 'desc')
+        return 'DESC';
+    throw new Error('Invalid order direction: expected "asc" or "desc".');
+}

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

@@ -1 +1 @@
-{"version":3,"file":"shift-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/shift-measure-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAI1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAI9D,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM;;;;;EAclG;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,GAAG,MAAM,CAGpG;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAOrH;AAED,+FAA+F;AAC/F,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,sBAAsB,EAAE,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,MAAM,CAMlH;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAsBhK"}
+{"version":3,"file":"shift-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/shift-measure-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAI1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAK9D,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM;;;;;EAoBlG;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,GAAG,MAAM,CAGpG;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAOrH;AAED,+FAA+F;AAC/F,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,sBAAsB,EAAE,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,MAAM,CAMlH;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAsBhK"}

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

@@ -3,18 +3,25 @@ import { addTimeSql, subtractTimeSql } from './time-arithmetic-sql.js';
 import { calendarBucketGuardSql } from './time-axis-calendar-guard.js';
 import { calendarShiftAtFineGrain } from './shift-measure-grains.js';
 import { shiftWallTimeGuardSql } from './shift-wall-time-sql.js';
+import { anchoredCalendarShiftSql } from './calendar-shift-sql.js';
 /** Preserve the selected portion of a bucket and both authored endpoint operators. */
 export function shiftRangeSql(shift, axis, period) {
     const first = period ?? '_hq_first';
     const last = period ?? '_hq_last';
     const end = addTimeSql(last, 1, axis.grain);
-    const upper = subtractTimeSql(`least(${end}, _hq_upper)`, shift.interval.amount, shift.interval.unit);
+    const calendar = calendarShiftAtFineGrain(shift.interval, axis.grain);
     // Clamp the bucket anchor, then retain its width. Independently clamping both
     // dates would turn March 30–31 into February 28–28, dropping an entire day.
+    // A partial bucket keeps the matching slice of that shifted range, so both
+    // bounds are placed relative to the anchor rather than shifted on their own.
+    const shiftBound = (point, anchor) => calendar
+        ? anchoredCalendarShiftSql(point, anchor, shift.interval)
+        : subtractTimeSql(point, shift.interval.amount, shift.interval.unit);
+    const upper = shiftBound(`least(${end}, _hq_upper)`, last);
     const shiftedEnd = addTimeSql(subtractTimeSql(last, shift.interval.amount, shift.interval.unit), 1, axis.grain);
     return {
-        lower: subtractTimeSql(`greatest(${first}, _hq_lower)`, shift.interval.amount, shift.interval.unit),
-        upper: calendarShiftAtFineGrain(shift.interval, axis.grain) ? `if(_hq_upper >= ${end}, ${shiftedEnd}, ${upper})` : upper,
+        lower: shiftBound(`greatest(${first}, _hq_lower)`, first),
+        upper: calendar ? `if(_hq_upper >= ${end}, ${shiftedEnd}, ${upper})` : upper,
         lowerInclusive: period ? `(${period} > _hq_lower OR ${Number(axis.lowerInclusive)})` : String(Number(axis.lowerInclusive)),
         upperInclusive: `(_hq_upper < ${end} AND ${Number(axis.upperInclusive)})`,
     };

package/dist/utils/snapshot-execution-context.d.ts

@@ -0,0 +1,4 @@
+import type { ExecutionContext } from '../types.js';
+/** Bind cache identity and deferred execution to the same request-owned scope. */
+export declare function snapshotExecutionContext(context?: ExecutionContext): ExecutionContext | undefined;
+//# sourceMappingURL=snapshot-execution-context.d.ts.map

package/dist/utils/snapshot-execution-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-execution-context.d.ts","sourceRoot":"","sources":["../../src/utils/snapshot-execution-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,kFAAkF;AAClF,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,GAAG,SAAS,CAajG"}

package/dist/utils/snapshot-execution-context.js

@@ -0,0 +1,16 @@
+/** Bind cache identity and deferred execution to the same request-owned scope. */
+export function snapshotExecutionContext(context) {
+    if (context === undefined)
+        return undefined;
+    return {
+        ...context,
+        ...(context.runtime === undefined ? {} : {
+            runtime: {
+                ...context.runtime,
+                // Copy tenant objects and ID lists; retain adapter and AbortSignal identity.
+                tenant: structuredClone(context.runtime.tenant),
+            },
+        }),
+        ...(context.cache && { cache: { ...context.cache } }),
+    };
+}

package/dist/utils/time-measure-context-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"time-measure-context-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-context-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAM9D,8EAA8E;AAC9E,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,CAUrH;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAOxG"}
+{"version":3,"file":"time-measure-context-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-context-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAO9D,8EAA8E;AAC9E,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,CAerH;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAOxG"}

package/dist/utils/time-measure-context-sql.js

@@ -2,16 +2,22 @@ import { addTimeSql as add, subtractTimeSql as subtract } from './time-arithmeti
 import { calendarShiftAtFineGrain } from './shift-measure-grains.js';
 import { calendarBucketGuardSql } from './time-axis-calendar-guard.js';
 import { shiftWallTimeGuardSql } from './shift-wall-time-sql.js';
+import { anchoredCalendarShiftSql } from './calendar-shift-sql.js';
 /** Keep output coordinates separate from each shifted evaluation interval. */
 export function timeMeasureContextCtes(contexts, axis) {
     const end = add('_hq_period', 1, axis.grain);
     const root = `_hq_context0 AS (SELECT _hq_period, _hq_period AS _hq_eval_period, ${end} AS _hq_eval_end, greatest(_hq_period, _hq_lower) AS _hq_eval_lower, least(${end}, _hq_upper) AS _hq_eval_upper, (_hq_period > _hq_lower OR ${Number(axis.lowerInclusive)}) AS _hq_lower_inclusive, (_hq_upper < ${end} AND ${Number(axis.upperInclusive)}) AS _hq_upper_inclusive FROM _hq_series CROSS JOIN _hq_bounds)`;
     return [root, ...contexts.slice(1).map(context => {
             const interval = context.interval;
+            const calendar = calendarShiftAtFineGrain(interval, axis.grain);
             const shift = (value) => subtract(`p.${value}`, interval.amount, interval.unit);
+            // Partial bounds stay inside the shifted bucket; see anchoredCalendarShiftSql.
+            const shiftBound = (value) => calendar
+                ? anchoredCalendarShiftSql(`p.${value}`, 'p._hq_eval_period', interval)
+                : shift(value);
             const period = shift('_hq_eval_period');
-            const shiftedEnd = calendarShiftAtFineGrain(interval, axis.grain) ? add(period, 1, axis.grain) : shift('_hq_eval_end');
-            return `_hq_context${context.id} AS (SELECT p._hq_period, ${period} AS _hq_eval_period, ${shiftedEnd} AS _hq_eval_end, ${shift('_hq_eval_lower')} AS _hq_eval_lower, if(p._hq_eval_upper = p._hq_eval_end, ${shiftedEnd}, ${shift('_hq_eval_upper')}) AS _hq_eval_upper, p._hq_lower_inclusive, p._hq_upper_inclusive FROM _hq_context${context.parent} AS p)`;
+            const shiftedEnd = calendar ? add(period, 1, axis.grain) : shift('_hq_eval_end');
+            return `_hq_context${context.id} AS (SELECT p._hq_period, ${period} AS _hq_eval_period, ${shiftedEnd} AS _hq_eval_end, ${shiftBound('_hq_eval_lower')} AS _hq_eval_lower, if(p._hq_eval_upper = p._hq_eval_end, ${shiftedEnd}, ${shiftBound('_hq_eval_upper')}) AS _hq_eval_upper, p._hq_lower_inclusive, p._hq_upper_inclusive FROM _hq_context${context.parent} AS p)`;
         })];
 }
 export function timeMeasureContextGuard(context, axis) {

package/dist/utils/time-measure-dataset-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"time-measure-dataset-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-dataset-sql.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAYxE,+EAA+E;AAC/E,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,GACpC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAmE7D"}
+{"version":3,"file":"time-measure-dataset-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-dataset-sql.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAYxE,+EAA+E;AAC/E,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,GACpC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAmE7D"}

package/dist/utils/time-measure-dataset-sql.js

@@ -1,3 +1,4 @@
+import { queryMeasureDefinitions } from './relationship-measures.js';
 import { buildCompositeTimeMeasureSql } from './composite-time-measure-sql.js';
 import { measureDependencyNames } from './measure-dependencies.js';
 import { getBaseMeasure, getDerivedMeasure, isShiftMeasure, isWindowMeasure } from './dataset-measures.js';
@@ -18,7 +19,7 @@ export function buildTimeMeasureDatasetSql(ds, query, options) {
     const { axis } = analyzeTimeMeasureAxis(ds, query);
     if (!axis || !ds.timeKey)
         throw new Error('Window measures require a bounded time axis.');
-    const dependencies = measureDependencyNames(ds.measures, query.measures ?? []);
+    const dependencies = measureDependencyNames(queryMeasureDefinitions(ds, query.measures ?? []), query.measures ?? []);
     const composite = dependencies.some(name => {
         const definition = ds.measures[name];
         if (isShiftMeasure(definition))
@@ -49,7 +50,7 @@ export function buildTimeMeasureDatasetSql(ds, query, options) {
     // Scan only requested populations: intervening rows must not introduce dimensions.
     const end = add('_hq_last', 1, axis.grain);
     const populations = [];
-    if ([...needed].some(name => getBaseMeasure(ds.measures, name))) {
+    if ([...needed].some(name => name.includes('.') || getBaseMeasure(ds.measures, name))) {
         populations.push(`(_hq_time >= _hq_first AND _hq_time < ${end})`);
     }
     if (windows.length) {

package/dist/utils/time-measure-result-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"time-measure-result-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-result-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAIxE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAE5E,sFAAsF;AACtF,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,IAAI,EAAE,SAAS,uBAAuB,EAAE,EACxC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,eAAe,EAAE,MAAM,EACvB,iBAAiB,UAAQ,GACxB,MAAM,CAuBR"}
+{"version":3,"file":"time-measure-result-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-result-sql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAIxE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAE5E,sFAAsF;AACtF,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,IAAI,EAAE,SAAS,uBAAuB,EAAE,EACxC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,eAAe,EAAE,MAAM,EACvB,iBAAiB,UAAQ,GACxB,MAAM,CAuBR"}

package/dist/utils/time-measure-result-sql.js

@@ -1,3 +1,4 @@
+import { semanticOrderDirection } from './semantic-query-syntax.js';
 import { quoteSQLIdentifier } from '../sql-utils.js';
 import { getDerivedMeasure } from './dataset-measures.js';
 import { derivedProjection } from './derived-measure-sql.js';
@@ -20,7 +21,7 @@ export function buildTimeMeasureResultSql(ds, query, options, dims, ctes, valida
         + ` UNION ALL SELECT ${nullProjections} FROM _hq_bounds WHERE ${validationGuard} = 1)`;
     let sql = `WITH ${[...ctes, resultCte].join(',\n')} SELECT ${outputNames.map(quoteSQLIdentifier).join(', ')} FROM _hq_result`;
     const order = query.orderBy?.length ? query.orderBy : [{ field: 'period', direction: 'asc' }];
-    sql += ` ORDER BY ${order.map(item => `${quoteSQLIdentifier(item.field)} ${item.direction === 'asc' ? 'ASC' : 'DESC'}`).join(', ')}`;
+    sql += ` ORDER BY ${order.map(item => `${quoteSQLIdentifier(item.field)} ${semanticOrderDirection(item.direction)}`).join(', ')}`;
     const limit = options.executionLimit ?? query.limit;
     if (limit !== undefined)
         sql += ` LIMIT ${limit}`;

package/dist/utils/time-measure-source-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"time-measure-source-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-source-sql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACrG,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAUxE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,iBAAiB,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,UAAU,EAAE,OAAO,EAAE,CAAC;IACtB,UAAU,EAAE,uBAAuB,EAAE,CAAC;IACtC,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,0FAA0F;AAC1F,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC3B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,OAAO,EAAE,4BAA4B,GACpC,oBAAoB,CA2DtB"}
+{"version":3,"file":"time-measure-source-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-source-sql.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACrG,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAUxE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,iBAAiB,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,UAAU,EAAE,OAAO,EAAE,CAAC;IACtB,UAAU,EAAE,uBAAuB,EAAE,CAAC;IACtC,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,0FAA0F;AAC1F,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC3B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,OAAO,EAAE,4BAA4B,GACpC,oBAAoB,CA6DtB"}

package/dist/utils/time-measure-source-sql.js

@@ -1,3 +1,5 @@
+import { resolveRelationshipMeasure } from './relationship-measures.js';
+import { relationshipMeasureExpressions } from './relationship-measure-sql.js';
 import { queryTimeSql } from './query-timezone.js';
 import { resolveDimensionExpression, resolveFilterField, resolveTenantFilterColumn } from '../query-planner.js';
 import { applyRelationshipJoins, buildRelationshipBuilderContext, qualifyBaseColumn } from './relationship-builder-plan.js';
@@ -19,7 +21,8 @@ export function buildTimeMeasureSourceSql(ds, query, baseNames, filters, options
     for (const dimension of dims)
         sourceParts.push(resolveDimensionExpression(ds, dimension.name, joinCtx));
     for (const name of baseNames) {
-        const definition = getBaseMeasure(ds.measures, name);
+        const related = name.includes('.') ? resolveRelationshipMeasure(ds, name) : undefined;
+        const definition = related?.definition ?? getBaseMeasure(ds.measures, name);
         if (!definition)
             throw new Error(`Window input "${name}" is not a base measure.`);
         const spec = measureToAggregationSpec(name, definition);
@@ -28,9 +31,10 @@ export function buildTimeMeasureSourceSql(ds, query, baseNames, filters, options
         const value = `_hq_v${bases.length}`;
         const arg = `_hq_a${bases.length}`;
         bases.push({ name, definition, value, arg });
-        const expression = spec.sql ?? resolveDimensionExpression(ds, spec.field, joinCtx);
-        sourceParts.push(applyFilteredAggregationExpression(ds, spec, expression, joinCtx));
-        sourceParts.push(spec.argField ? resolveDimensionExpression(ds, spec.argField, joinCtx) : 'NULL');
+        const expressions = related ? relationshipMeasureExpressions(ds, name, joinCtx) : undefined;
+        const expression = expressions?.field ?? spec.sql ?? resolveDimensionExpression(ds, spec.field, joinCtx);
+        sourceParts.push(expressions ? expression : applyFilteredAggregationExpression(ds, spec, expression, joinCtx));
+        sourceParts.push(expressions?.arg ?? (spec.argField ? resolveDimensionExpression(ds, spec.argField, joinCtx) : 'NULL'));
     }
     // A positional tuple isolates internal names from the source table's names.
     const sourceIdentifiers = [

package/dist/validation.js

@@ -68,6 +68,6 @@ export function validateFilterValue(filter, fieldType) {
                 ? null
                 : `"between" expects ${fieldType} values for field "${filter.field}".`;
         default:
-            return null;
+            return `Unsupported semantic filter operator "${String(filter.operator)}".`;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Code-first TypeScript semantic layer for ClickHouse datasets, metrics, multi-tenancy, and AI agents",
   "keywords": [
     "semantic-layer",
@@ -42,25 +42,29 @@
     "dist"
   ],
   "dependencies": {
-    "@hypequery/protocol": "^0.18.0",
+    "@hypequery/protocol": "^0.19.0",
     "@noble/hashes": "^1.8.0",
     "zod": "^3.22.4",
     "zod-to-json-schema": "^3.25.2"
   },
   "peerDependencies": {
-    "zod": "^3.22.4"
+    "zod": "^3.22.4",
+    "@hypequery/clickhouse": ">=2.13.0"
   },
   "peerDependenciesMeta": {
     "zod": {
       "optional": true
+    },
+    "@hypequery/clickhouse": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/node": "^18.19.80",
-    "typescript": "^5.7.3",
+    "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^5.0.2",
     "vitest": "^5.0.2",
-    "@hypequery/protocol-conformance": "^0.15.0"
+    "@hypequery/protocol-conformance": "^0.15.1"
   },
   "repository": {
     "type": "git",
@@ -83,6 +87,7 @@
     "test:types": "tsc --project tsconfig.type-tests.json",
     "test:watch": "vitest watch",
     "test:coverage": "vitest run --coverage",
+    "test:coverage:full": "node scripts/run-integration-tests.js --include-unit-tests --coverage",
     "lint": "eslint \"src/**/*.ts\""
   }
 }