@hypequery/datasets 0.18.0 → 0.20.0

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

@@ -1 +1 @@
-{"version":3,"file":"portable-semantic-query.d.ts","sourceRoot":"","sources":["../../src/utils/portable-semantic-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAA+B,qBAAqB,EAAa,MAAM,aAAa,CAAC;AAIjG,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,qBAAqB,GAAG,SAAS,CAKhF;AAWD,wBAAgB,aAAa,CAAC,SAAS,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBxG"}
+{"version":3,"file":"portable-semantic-query.d.ts","sourceRoot":"","sources":["../../src/utils/portable-semantic-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAA+B,qBAAqB,EAAa,MAAM,aAAa,CAAC;AAKjG,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,qBAAqB,GAAG,SAAS,CAKhF;AAYD,wBAAgB,aAAa,CAAC,SAAS,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBxG"}

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

@@ -1,5 +1,6 @@
 import { PortableExecutionUnsupportedError } from '../portable-execution-errors.js';
 import { rehydrateMeasureFilter } from './protocol-rehydrate-filters.js';
+import { UNSUPPORTED_CONTRACT_REASONS } from './unsupported-contract-reasons.js';
 export function tenantRuntime(tenant) {
     if (tenant === undefined || tenant === null)
         return undefined;
@@ -10,7 +11,7 @@ export function tenantRuntime(tenant) {
     return tenant;
 }
 function operationFilters(operation) {
-    return (operation.filters ?? []).map((expression, index) => rehydrateMeasureFilter(expression, () => new PortableExecutionUnsupportedError(`Filter ${index} is not a field/operator/value comparison, so it cannot be planned.`)));
+    return (operation.filters ?? []).map((expression, index) => rehydrateMeasureFilter(expression, () => new PortableExecutionUnsupportedError(`Filter ${index} is not a field/operator/value comparison, so it cannot be planned.`, { reason: UNSUPPORTED_CONTRACT_REASONS.queryFilterNotComparison })));
 }
 export function semanticQuery(operation, maxRows) {
     const filters = operationFilters(operation);

package/dist/utils/protocol-metric-expressions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-metric-expressions.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-metric-expressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEgB,KAAK,kBAAkB,EAAE,KAAK,wBAAwB,EAC5E,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsC9G,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB,CAgBzE;AA+CD,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,wBAAwB,GAAG,kBAAkB,CAGjG;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,kBAAkB,CAQ9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,wBAAwB,CASlF"}
+{"version":3,"file":"protocol-metric-expressions.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-metric-expressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEgB,KAAK,kBAAkB,EAAE,KAAK,wBAAwB,EAC5E,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAuC9G,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB,CAgBzE;AA+CD,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,wBAAwB,GAAG,kBAAkB,CAGjG;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,kBAAkB,CAQ9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,wBAAwB,CASlF"}

package/dist/utils/protocol-metric-expressions.js

@@ -1,4 +1,5 @@
 import { parseProtocolIdentifier, parseProtocolQualifiedIdentifier, validateCanonicalValue, } from '@hypequery/protocol';
+import { requirePortableAggregation } from './portable-aggregations.js';
 function canonicalValue(input) {
     if (Array.isArray(input)) {
         return validateCanonicalValue({
@@ -48,7 +49,7 @@ export function filterExpression(filter) {
 function aggregationExpression(spec) {
     const result = {
         kind: 'aggregate',
-        aggregation: spec.aggregation,
+        aggregation: requirePortableAggregation(spec.aggregation, `An aggregate over "${spec.field}"`),
         field: parseProtocolQualifiedIdentifier(spec.field),
         ...(spec.argField !== undefined
             ? { argField: parseProtocolQualifiedIdentifier(spec.argField) }

package/dist/utils/query-timezone.d.ts

@@ -0,0 +1,9 @@
+import type { AnyDatasetInstance } from '../types.js';
+/** Named zones only: reject fixed offsets, invalid zones, and SQL fragments. */
+export declare function isQueryTimezone(value: unknown): value is string;
+export declare function queryTimezoneErrors(timezone: unknown): string[];
+/** Conversion preserves timestamp instants and interprets Date values as local dates. */
+export declare function queryTimeSql(expression: string, timezone: string | undefined): string;
+/** Apply the query zone to time-key predicates, including semantic filter aliases. */
+export declare function queryTimeFilterSql(ds: AnyDatasetInstance, field: string, expression: string, timezone: string | undefined): string;
+//# sourceMappingURL=query-timezone.d.ts.map

package/dist/utils/query-timezone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-timezone.d.ts","sourceRoot":"","sources":["../../src/utils/query-timezone.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAS/D;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,EAAE,CAG/D;AAED,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAMrF;AAED,sFAAsF;AACtF,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GACtF,MAAM,CAMR"}

package/dist/utils/query-timezone.js

@@ -0,0 +1,35 @@
+/** Named zones only: reject fixed offsets, invalid zones, and SQL fragments. */
+export function isQueryTimezone(value) {
+    if (typeof value !== 'string' || value.length > 100
+        || !/^[A-Za-z][A-Za-z0-9._+-]*(?:\/[A-Za-z0-9._+-]+)*$/.test(value))
+        return false;
+    try {
+        new Intl.DateTimeFormat('en', { timeZone: value });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function queryTimezoneErrors(timezone) {
+    return timezone === undefined || isQueryTimezone(timezone)
+        ? [] : ['Invalid timezone: use an IANA name such as UTC or America/New_York.'];
+}
+/** Conversion preserves timestamp instants and interprets Date values as local dates. */
+export function queryTimeSql(expression, timezone) {
+    timezone ??= 'UTC';
+    const errors = queryTimezoneErrors(timezone);
+    if (errors.length)
+        throw new Error(errors[0]);
+    const name = new Intl.DateTimeFormat('en', { timeZone: timezone }).resolvedOptions().timeZone;
+    return `toDateTime64(${expression}, 9, '${name}')`;
+}
+/** Apply the query zone to time-key predicates, including semantic filter aliases. */
+export function queryTimeFilterSql(ds, field, expression, timezone) {
+    if (!ds.timeKey || field.includes('.'))
+        return expression;
+    const resolved = ds.filters[field]?.field ?? field;
+    const column = ds.dimensions[resolved]?.column ?? resolved;
+    const timeColumn = ds.dimensions[ds.timeKey]?.column ?? ds.timeKey;
+    return column === timeColumn ? queryTimeSql(expression, timezone) : expression;
+}

package/dist/utils/relationship-builder-plan.d.ts

@@ -46,10 +46,13 @@ export declare function qualifyBaseColumn(ctx: RelationshipBuilderContext | unde
  */
 export declare function resolveQualifiedColumn(ds: AnyDatasetInstance, name: string): string;
 /**
- * Applies each relationship LEFT JOIN to the builder and, when runtime tenancy
+ * Applies each relationship join to the builder as a single-match LEFT JOIN
+ * (`leftAnyJoin`, e.g. ClickHouse `LEFT ANY JOIN`) and, when runtime tenancy
  * is active on a target, scopes the joined rows with the tenant predicate.
- * Builders that support single-match joins (`leftAnyJoin`, e.g. ClickHouse
- * `LEFT ANY JOIN`) get them so duplicate target keys cannot fan out aggregates.
+ *
+ * A builder without `leftAnyJoin` is refused rather than downgraded to a plain
+ * `leftJoin`: duplicate target keys would fan out base rows and silently
+ * inflate every aggregate in the query.
  */
 export declare function applyRelationshipJoins(qb: QueryBuilderLike, ctx: RelationshipBuilderContext | undefined): QueryBuilderLike;
 export {};

package/dist/utils/relationship-builder-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationship-builder-plan.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-builder-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtF,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,MAAM,CAAC,EAAE,eAAe,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CACtD;AAED,KAAK,SAAS,GAAG,IAAI,CAAC,YAAY,GAAG,WAAW,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC;AAExF;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,0BAA0B,GAAG,SAAS,CAuCxC;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,0BAA0B,GAAG,SAAS,EAC3C,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,GACX,MAAM,CAOR;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,GAAG,EAAE,0BAA0B,GAAG,SAAS,GAC1C,gBAAgB,CAqBlB"}
+{"version":3,"file":"relationship-builder-plan.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-builder-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtF,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,MAAM,CAAC,EAAE,eAAe,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CACtD;AAED,KAAK,SAAS,GAAG,IAAI,CAAC,YAAY,GAAG,WAAW,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC;AAExF;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,0BAA0B,GAAG,SAAS,CAuCxC;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,0BAA0B,GAAG,SAAS,EAC3C,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,GACX,MAAM,CAOR;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,GAAG,EAAE,0BAA0B,GAAG,SAAS,GAC1C,gBAAgB,CA4BlB"}

package/dist/utils/relationship-builder-plan.js

@@ -69,18 +69,26 @@ export function resolveQualifiedColumn(ds, name) {
     return `${relationshipName}.${targetColumn}`;
 }
 /**
- * Applies each relationship LEFT JOIN to the builder and, when runtime tenancy
+ * Applies each relationship join to the builder as a single-match LEFT JOIN
+ * (`leftAnyJoin`, e.g. ClickHouse `LEFT ANY JOIN`) and, when runtime tenancy
  * is active on a target, scopes the joined rows with the tenant predicate.
- * Builders that support single-match joins (`leftAnyJoin`, e.g. ClickHouse
- * `LEFT ANY JOIN`) get them so duplicate target keys cannot fan out aggregates.
+ *
+ * A builder without `leftAnyJoin` is refused rather than downgraded to a plain
+ * `leftJoin`: duplicate target keys would fan out base rows and silently
+ * inflate every aggregate in the query.
  */
 export function applyRelationshipJoins(qb, ctx) {
     if (!ctx) {
         return qb;
     }
     for (const join of ctx.joins) {
-        const applyJoin = qb.leftAnyJoin?.bind(qb) ?? qb.leftJoin.bind(qb);
-        qb = applyJoin(join.source, `${ctx.baseSource}.${join.from}`, `${join.relationship}.${join.to}`, join.relationship, join.tenant
+        if (!qb.leftAnyJoin) {
+            throw new Error(`Relationship "${join.relationship}" cannot be joined: the query builder does not implement ` +
+                'leftAnyJoin (a single-match LEFT JOIN such as ClickHouse "LEFT ANY JOIN"). A plain leftJoin ' +
+                'would fan out duplicate target keys and inflate aggregates, so relationship-qualified fields ' +
+                'are unavailable with this builder.');
+        }
+        qb = qb.leftAnyJoin(join.source, `${ctx.baseSource}.${join.from}`, `${join.relationship}.${join.to}`, join.relationship, join.tenant
             ? {
                 column: `${join.relationship}.${join.tenant.field}`,
                 operator: join.tenant.operator,

package/dist/utils/relationship-key-check.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure helpers for `checkRelationships`: which relationships a check covers,
+ * and how a key-count row becomes a finding.
+ */
+import type { AnyDatasetInstance } from '../types.js';
+export type ToOneRelationshipKind = 'belongsTo' | 'hasOne';
+export interface ToOneRelationshipTarget {
+    relationship: string;
+    kind: ToOneRelationshipKind;
+    /** Target dataset. */
+    target: AnyDatasetInstance;
+    /** Target join column, which a to-one declaration requires to be unique. */
+    column: string;
+}
+/**
+ * Lists the to-one relationships to check. `hasMany` is excluded because it
+ * never joins, so its key has no uniqueness requirement. An explicit
+ * `only` list must name declared to-one relationships.
+ */
+export declare function listToOneRelationships(ds: AnyDatasetInstance, only?: readonly string[]): ToOneRelationshipTarget[];
+export interface RelationshipKeyIssue {
+    relationship: string;
+    kind: ToOneRelationshipKind;
+    /** Target dataset name. */
+    target: string;
+    /** Physical target table. */
+    source: string;
+    /** Target join column. */
+    column: string;
+    /** Target rows with a non-NULL key, within the checked tenant scope. Large counts are decimal strings. */
+    rows: number | string;
+    /** Distinct non-NULL keys, within the checked tenant scope. Large counts are decimal strings. */
+    distinctKeys: number | string;
+    message: string;
+}
+/** Reads a count without losing precision when a driver returns UInt64 as a string. */
+export declare function readCount(value: unknown): bigint;
+/**
+ * Returns the finding for a to-one relationship whose target key repeats, or
+ * undefined when every non-NULL key is unique.
+ */
+export declare function relationshipKeyIssue(entry: ToOneRelationshipTarget, rows: bigint, distinctKeys: bigint): RelationshipKeyIssue | undefined;
+//# sourceMappingURL=relationship-key-check.d.ts.map

package/dist/utils/relationship-key-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-key-check.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-key-check.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAA0B,MAAM,aAAa,CAAC;AAE9E,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,sBAAsB;IACtB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GACvB,uBAAuB,EAAE,CAuB3B;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,0GAA0G;IAC1G,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,iGAAiG;IACjG,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAchD;AAMD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,uBAAuB,EAC9B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GACnB,oBAAoB,GAAG,SAAS,CAkBlC"}

package/dist/utils/relationship-key-check.js

@@ -0,0 +1,72 @@
+/**
+ * Pure helpers for `checkRelationships`: which relationships a check covers,
+ * and how a key-count row becomes a finding.
+ */
+/**
+ * Lists the to-one relationships to check. `hasMany` is excluded because it
+ * never joins, so its key has no uniqueness requirement. An explicit
+ * `only` list must name declared to-one relationships.
+ */
+export function listToOneRelationships(ds, only) {
+    const declared = Object.entries(ds.relationships);
+    if (only) {
+        for (const name of only) {
+            const relationship = Object.hasOwn(ds.relationships, name) ? ds.relationships[name] : undefined;
+            if (!relationship) {
+                throw new Error(`Unknown relationship "${name}" on dataset "${ds.name}".`);
+            }
+            if (relationship.kind === 'hasMany') {
+                throw new Error(`Relationship "${name}" on dataset "${ds.name}" is hasMany; only to-one relationships have a key to check.`);
+            }
+        }
+    }
+    return declared
+        .filter(([name, relationship]) => relationship.kind !== 'hasMany' && (!only || only.includes(name)))
+        .map(([name, relationship]) => ({
+        relationship: name,
+        kind: relationship.kind,
+        target: relationship.target(),
+        column: relationship.to,
+    }));
+}
+/** Reads a count without losing precision when a driver returns UInt64 as a string. */
+export function readCount(value) {
+    if (value == null) {
+        return 0n;
+    }
+    if (typeof value === 'bigint' && value >= 0n) {
+        return value;
+    }
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) {
+        return BigInt(value);
+    }
+    if (typeof value === 'string' && /^\d+$/.test(value)) {
+        return BigInt(value);
+    }
+    throw new Error(`Expected a non-negative integer row count, received ${JSON.stringify(String(value))}.`);
+}
+function displayCount(count) {
+    return count <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(count) : count.toString();
+}
+/**
+ * Returns the finding for a to-one relationship whose target key repeats, or
+ * undefined when every non-NULL key is unique.
+ */
+export function relationshipKeyIssue(entry, rows, distinctKeys) {
+    if (rows <= distinctKeys) {
+        return undefined;
+    }
+    const source = entry.target.source;
+    return {
+        relationship: entry.relationship,
+        kind: entry.kind,
+        target: entry.target.name,
+        source,
+        column: entry.column,
+        rows: displayCount(rows),
+        distinctKeys: displayCount(distinctKeys),
+        message: `Relationship "${entry.relationship}" is declared ${entry.kind}, but "${source}.${entry.column}" ` +
+            `has ${rows} rows for ${distinctKeys} distinct keys. Joins pick an arbitrary matching row; ` +
+            'make the key unique or declare the relationship as hasMany.',
+    };
+}

package/dist/utils/segments.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Dataset segments (RFC 0015): named, author-defined row filters that a query
+ * selects by name.
+ *
+ * A segment compares the dataset's own dimensions with literals. It may use a
+ * dimension that is not exposed as a filter: the filter allow-list governs
+ * what a caller may construct, not what an author may declare. It may not
+ * traverse a relationship or constrain the tenant column, which only trusted
+ * runtime context scopes.
+ */
+import type { AnyDatasetInstance, DimensionDefinition, MetricFilter, SegmentDefinition } from '../types.js';
+interface SegmentOwner {
+    readonly tenantKey?: string;
+    readonly dimensions: Readonly<Record<string, DimensionDefinition>>;
+}
+/** Throws when a declared segment is malformed; returns a frozen copy otherwise. */
+export declare function normalizeSegments(datasetName: string, owner: SegmentOwner, segments: Record<string, SegmentDefinition> | undefined): Record<string, SegmentDefinition>;
+/**
+ * Publishing emits deployment contract 2, which cannot carry segments
+ * (RFC 0015), so a dataset that declares them is refused by name.
+ */
+export declare function assertNoPublishedSegments(ds: Pick<AnyDatasetInstance, 'name' | 'segments'>): void;
+/** Validation errors for a query's `segments` selection. */
+export declare function segmentSelectionErrors(ds: AnyDatasetInstance, names: unknown): string[];
+/**
+ * The conditions a selection applies, as filters over dimension names. Order
+ * follows the selection, then each segment's authored filters.
+ */
+export declare function segmentFilters(ds: AnyDatasetInstance, names: readonly string[] | undefined): MetricFilter[];
+export {};
+//# sourceMappingURL=segments.d.ts.map

package/dist/utils/segments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segments.d.ts","sourceRoot":"","sources":["../../src/utils/segments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAM5G,UAAU,YAAY;IACpB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC;CACpE;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,SAAS,GACtD,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAkCnC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,UAAU,CAAC,GAAG,IAAI,CAQjG;AAED,4DAA4D;AAC5D,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAiBvF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,YAAY,EAAE,CAE3G"}

package/dist/utils/segments.js

@@ -0,0 +1,91 @@
+/**
+ * Dataset segments (RFC 0015): named, author-defined row filters that a query
+ * selects by name.
+ *
+ * A segment compares the dataset's own dimensions with literals. It may use a
+ * dimension that is not exposed as a filter: the filter allow-list governs
+ * what a caller may construct, not what an author may declare. It may not
+ * traverse a relationship or constrain the tenant column, which only trusted
+ * runtime context scopes.
+ */
+import { SEMANTIC_FILTER_OPERATORS } from '../constants.js';
+import { validateFilterValue } from '../validation.js';
+const SEGMENT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const OPERATORS = new Set(SEMANTIC_FILTER_OPERATORS);
+/** Throws when a declared segment is malformed; returns a frozen copy otherwise. */
+export function normalizeSegments(datasetName, owner, segments) {
+    const fail = (name, message) => {
+        throw new Error(`Invalid segment "${name}" on dataset "${datasetName}": ${message}`);
+    };
+    const result = [];
+    for (const [name, segment] of Object.entries(segments ?? {})) {
+        if (!SEGMENT_NAME.test(name))
+            fail(name, 'names must be identifiers (letters, digits, underscores).');
+        if (!Array.isArray(segment?.filters) || segment.filters.length === 0) {
+            fail(name, 'filters must be a non-empty array.');
+        }
+        for (const filter of segment.filters) {
+            const dimension = Object.hasOwn(owner.dimensions, filter.field) ? owner.dimensions[filter.field] : undefined;
+            if (!dimension) {
+                fail(name, `"${filter.field}" is not a dimension of this dataset; segments cannot use relationships.`);
+            }
+            const column = dimension.column ?? filter.field;
+            if (owner.tenantKey !== undefined && (column === owner.tenantKey || filter.field === owner.tenantKey)) {
+                fail(name, `"${filter.field}" is the tenant column, which only runtime tenant scoping may constrain.`);
+            }
+            if (!OPERATORS.has(filter.operator))
+                fail(name, `unsupported operator "${String(filter.operator)}".`);
+            const valueError = validateFilterValue(filter, dimension.fieldType);
+            if (valueError)
+                fail(name, valueError);
+        }
+        result.push([name, Object.freeze({
+                filters: Object.freeze(segment.filters.map(filter => Object.freeze({
+                    ...filter,
+                    value: Array.isArray(filter.value) ? Object.freeze([...filter.value]) : filter.value,
+                }))),
+                ...(segment.label !== undefined ? { label: segment.label } : {}),
+                ...(segment.description !== undefined ? { description: segment.description } : {}),
+            })]);
+    }
+    // Object.fromEntries preserves names such as "__proto__" as own properties.
+    return Object.freeze(Object.fromEntries(result));
+}
+/**
+ * Publishing emits deployment contract 2, which cannot carry segments
+ * (RFC 0015), so a dataset that declares them is refused by name.
+ */
+export function assertNoPublishedSegments(ds) {
+    const names = Object.keys(ds.segments ?? {});
+    if (names.length > 0) {
+        throw new Error(`Dataset "${ds.name}" declares segments (${names.join(', ')}), which cannot be published yet: ` +
+            'segments need deployment contract 3 (RFC 0015). Use them for local queries until publishing emits contract 3.');
+    }
+}
+/** Validation errors for a query's `segments` selection. */
+export function segmentSelectionErrors(ds, names) {
+    if (names === undefined)
+        return [];
+    if (!Array.isArray(names))
+        return ['segments must be an array of segment names.'];
+    const errors = [];
+    const seen = new Set();
+    const available = Object.keys(ds.segments ?? {});
+    for (const name of names) {
+        if (typeof name !== 'string' || !Object.hasOwn(ds.segments ?? {}, name)) {
+            errors.push(`Unknown segment "${String(name)}" on dataset "${ds.name}". Available: ${available.join(', ') || '(none)'}`);
+        }
+        else if (seen.has(name)) {
+            errors.push(`Segment "${name}" is selected more than once.`);
+        }
+        seen.add(String(name));
+    }
+    return errors;
+}
+/**
+ * The conditions a selection applies, as filters over dimension names. Order
+ * follows the selection, then each segment's authored filters.
+ */
+export function segmentFilters(ds, names) {
+    return (names ?? []).flatMap(name => ds.segments?.[name]?.filters ?? []);
+}

package/dist/utils/semantic-metadata-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-metadata-validation.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-metadata-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAoBrB,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,gBAAgB,GACzB,IAAI,CA8BN;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC1D,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAE7D,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAC5D,IAAI,CAuDN"}
+{"version":3,"file":"semantic-metadata-validation.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-metadata-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAsBrB,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,gBAAgB,GACzB,IAAI,CA8BN;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC1D,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAE7D,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAC5D,IAAI,CA4EN"}

package/dist/utils/semantic-metadata-validation.js

@@ -1,7 +1,8 @@
+import { SUPPORTED_TIME_GRAINS } from '../constants.js';
 const MAX_METADATA_ITEMS = 100;
 const MAX_METADATA_TEXT_BYTES = 4_096;
 const SENSITIVITIES = new Set(['public', 'internal', 'confidential', 'restricted']);
-const TIME_GRAINS = new Set(['day', 'week', 'month', 'quarter', 'year']);
+const TIME_GRAINS = new Set(SUPPORTED_TIME_GRAINS);
 const textEncoder = new TextEncoder();
 function fail(datasetName, location, message) {
     throw new Error(`Invalid dataset "${datasetName}": ${location} ${message}`);
@@ -33,7 +34,7 @@ export function validateSemanticMetadata(datasetName, location, metadata) {
             validateText(datasetName, `${location}.${key}[${index}]`, value);
         }
     }
-    for (const key of ['format', 'unit', 'timezone']) {
+    for (const key of ['format', 'unit']) {
         const value = metadata[key];
         if (value !== undefined)
             validateText(datasetName, `${location}.${key}`, value);
@@ -90,6 +91,26 @@ export function validateDatasetAgentMetadata(datasetName, config) {
         if (dimensions.length === 0 && config.defaults.timeGrain === undefined) {
             fail(datasetName, 'defaults', 'must define dimensions or timeGrain.');
         }
+        if (config.defaults.timeGrain !== undefined && config.timeGrains !== undefined
+            && !config.timeGrains.includes(config.defaults.timeGrain)) {
+            fail(datasetName, 'defaults.timeGrain', 'is not one of the dataset timeGrains.');
+        }
+    }
+    if (config.timeGrains !== undefined) {
+        if (!Array.isArray(config.timeGrains) || config.timeGrains.length === 0) {
+            fail(datasetName, 'timeGrains', 'must be a non-empty array.');
+        }
+        if (config.timeKey === undefined) {
+            fail(datasetName, 'timeGrains', 'requires the dataset to define timeKey.');
+        }
+        if (new Set(config.timeGrains).size !== config.timeGrains.length) {
+            fail(datasetName, 'timeGrains', 'must not contain duplicates.');
+        }
+        for (const grain of config.timeGrains) {
+            if (!TIME_GRAINS.has(grain)) {
+                fail(datasetName, 'timeGrains', `contains unsupported time grain "${String(grain)}".`);
+            }
+        }
     }
     for (const [name, dimension] of Object.entries(config.dimensions)) {
         validateSemanticMetadata(datasetName, `dimensions.${name}`, dimension);

package/dist/utils/semantic-metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-metadata.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,CAUrF"}
+{"version":3,"file":"semantic-metadata.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,CAYrF"}

package/dist/utils/semantic-metadata.js

@@ -1,13 +1,15 @@
 import { uniqueSorted } from './canonical-json.js';
 /** Copy agent metadata without carrying unrelated config fields into public contracts. */
 export function snapshotSemanticMetadata(metadata) {
+    if ('timezone' in metadata) {
+        throw new Error('Set timezone on createDatasetClient or the query, not semantic metadata.');
+    }
     return {
         ...(metadata.examples !== undefined ? { examples: uniqueSorted(metadata.examples) } : {}),
         ...(metadata.synonyms !== undefined ? { synonyms: uniqueSorted(metadata.synonyms) } : {}),
         ...(metadata.format !== undefined ? { format: metadata.format } : {}),
         ...(metadata.unit !== undefined ? { unit: metadata.unit } : {}),
         ...(metadata.currency !== undefined ? { currency: metadata.currency } : {}),
-        ...(metadata.timezone !== undefined ? { timezone: metadata.timezone } : {}),
         ...(metadata.sensitivity !== undefined ? { sensitivity: metadata.sensitivity } : {}),
     };
 }

package/dist/utils/shift-measure-definition.d.ts

@@ -0,0 +1,4 @@
+import type { MeasureTimeInterval, ShiftMeasureDefinition } from '../types.js';
+export type ShiftMeasureOptions = Pick<ShiftMeasureDefinition, 'label' | 'description' | 'examples' | 'synonyms' | 'format' | 'unit' | 'currency' | 'sensitivity'>;
+export declare function createShiftMeasure<const TMeasureName extends string>(baseMeasure: TMeasureName, interval: MeasureTimeInterval, options?: ShiftMeasureOptions): ShiftMeasureDefinition<TMeasureName>;
+//# sourceMappingURL=shift-measure-definition.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shift-measure-definition.d.ts","sourceRoot":"","sources":["../../src/utils/shift-measure-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAG/E,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,sBAAsB,EAC3D,OAAO,GAAG,aAAa,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,aAAa,CAAC,CAAC;AAEtG,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,YAAY,SAAS,MAAM,EAClE,WAAW,EAAE,YAAY,EACzB,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,sBAAsB,CAAC,YAAY,CAAC,CAOtC"}

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

@@ -0,0 +1,9 @@
+import { snapshotSemanticMetadata } from './semantic-metadata.js';
+export function createShiftMeasure(baseMeasure, interval, options) {
+    return {
+        __type: 'shift_measure_definition', measure: baseMeasure, interval: { ...interval },
+        ...snapshotSemanticMetadata(options ?? {}),
+        ...(options?.label === undefined ? {} : { label: options.label }),
+        ...(options?.description === undefined ? {} : { description: options.description }),
+    };
+}

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

@@ -0,0 +1,18 @@
+import type { ShiftMeasureDefinition, TimeGrain } from '../types.js';
+import type { TimeMeasureAxis } from './time-measure-axis.js';
+/** Preserve the selected portion of a bucket and both authored endpoint operators. */
+export declare function shiftRangeSql(shift: ShiftMeasureDefinition, axis: TimeMeasureAxis, period?: string): {
+    lower: string;
+    upper: string;
+    lowerInclusive: string;
+    upperInclusive: string;
+};
+export declare function shiftRangePredicateSql(time: string, range: ReturnType<typeof shiftRangeSql>): string;
+/** Check the shifted scan independently of whether it contains source rows. */
+export declare function shiftCalendarGuardSql(shift: ShiftMeasureDefinition, grain: TimeGrain, axisGuard: string): string;
+/** Map output buckets to their earlier half-open ranges, retaining calendar arithmetic. */
+export declare function shiftBucketCtes(shift: ShiftMeasureDefinition, axis: TimeMeasureAxis, index: number): {
+    ctes: string[];
+    rowsSql: string;
+};
+//# sourceMappingURL=shift-measure-sql.d.ts.map

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

@@ -0,0 +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,SAAS,EAAE,MAAM,aAAa,CAAC;AAIrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM;;;;;EAQlG;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,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAOhH;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,CAAA;CAAE,CAkBxI"}

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

@@ -0,0 +1,46 @@
+import { GRAIN_FUNCTIONS } from '../constants.js';
+import { addTimeSql, subtractTimeSql } from './time-arithmetic-sql.js';
+import { calendarBucketGuardSql } from './time-axis-calendar-guard.js';
+/** Preserve the selected portion of a bucket and both authored endpoint operators. */
+export function shiftRangeSql(shift, axis, period) {
+    const end = period ? addTimeSql(period, 1, axis.grain) : undefined;
+    return {
+        lower: subtractTimeSql(period ? `greatest(${period}, _hq_lower)` : '_hq_lower', shift.interval.amount, shift.interval.unit),
+        upper: subtractTimeSql(end ? `least(${end}, _hq_upper)` : '_hq_upper', shift.interval.amount, shift.interval.unit),
+        lowerInclusive: period ? `(${period} > _hq_lower OR ${Number(axis.lowerInclusive)})` : String(Number(axis.lowerInclusive)),
+        upperInclusive: end ? `(_hq_upper < ${end} AND ${Number(axis.upperInclusive)})` : String(Number(axis.upperInclusive)),
+    };
+}
+export function shiftRangePredicateSql(time, range) {
+    return `(${time} > ${range.lower} OR (${range.lowerInclusive} AND ${time} = ${range.lower}))`
+        + ` AND (${time} < ${range.upper} OR (${range.upperInclusive} AND ${time} = ${range.upper}))`;
+}
+/** Check the shifted scan independently of whether it contains source rows. */
+export function shiftCalendarGuardSql(shift, grain, axisGuard) {
+    const lower = subtractTimeSql('_hq_first', shift.interval.amount, shift.interval.unit);
+    const upper = subtractTimeSql(addTimeSql('_hq_last', 1, grain), shift.interval.amount, shift.interval.unit);
+    const first = `${GRAIN_FUNCTIONS[grain]}(${lower})`;
+    const last = `${GRAIN_FUNCTIONS[grain]}(${upper})`;
+    const count = `dateDiff('${grain}', ${first}, ${last}) + ${axisGuard}`;
+    return calendarBucketGuardSql(first, count, grain);
+}
+/** Map output buckets to their earlier half-open ranges, retaining calendar arithmetic. */
+export function shiftBucketCtes(shift, axis, index) {
+    const { grain } = axis;
+    const ranges = `_hq_shift_ranges${index}`;
+    const keys = `_hq_shift_keys${index}`;
+    const range = shiftRangeSql(shift, axis, '_hq_period');
+    const bucket = `${GRAIN_FUNCTIONS[grain]}(_hq_shift_lower)`;
+    const upperBucket = `${GRAIN_FUNCTIONS[grain]}(_hq_shift_upper)`;
+    const count = `greatest(0, dateDiff('${grain}', ${bucket}, ${upperBucket}) + if(_hq_shift_upper > ${upperBucket} OR _hq_shift_upper_inclusive, 1, 0))`;
+    return {
+        ctes: [
+            `${ranges} AS (SELECT _hq_period, ${range.lower} AS _hq_shift_lower, ${range.upper} AS _hq_shift_upper, ${range.lowerInclusive} AS _hq_shift_lower_inclusive, ${range.upperInclusive} AS _hq_shift_upper_inclusive FROM _hq_series CROSS JOIN _hq_bounds)`,
+            // A DST transition can map a one-hour output bucket to zero or two
+            // source hours. Enumerate source bucket keys and keep exact endpoints.
+            // The equality join avoids a source-rows × output-series Cartesian product.
+            `${keys} AS (SELECT *, ${addTimeSql(bucket, `arrayJoin(range(toUInt64(${count})))`, grain)} AS _hq_source_period FROM ${ranges})`,
+        ],
+        rowsSql: `SELECT r.*, b._hq_period FROM _hq_scanned AS r INNER JOIN ${keys} AS b ON ${GRAIN_FUNCTIONS[grain]}(r._hq_time) = b._hq_source_period WHERE ${shiftRangePredicateSql('r._hq_time', { lower: 'b._hq_shift_lower', upper: 'b._hq_shift_upper', lowerInclusive: 'b._hq_shift_lower_inclusive', upperInclusive: 'b._hq_shift_upper_inclusive' })}`,
+    };
+}

package/dist/utils/shift-measure-validation.d.ts

@@ -0,0 +1,3 @@
+import type { DatasetMeasureDefinition } from '../types.js';
+export declare function validateShiftMeasures(datasetName: string, timeKey: string | undefined, measures: Record<string, DatasetMeasureDefinition>): void;
+//# sourceMappingURL=shift-measure-validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shift-measure-validation.d.ts","sourceRoot":"","sources":["../../src/utils/shift-measure-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAK5D,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,IAAI,CAYhJ"}

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

@@ -0,0 +1,20 @@
+import { isSafeSQLIdentifier } from '../sql-utils.js';
+import { isSupportedTimeGrain } from '../constants.js';
+import { getBaseMeasure, isShiftMeasure } from './dataset-measures.js';
+export function validateShiftMeasures(datasetName, timeKey, measures) {
+    for (const [name, definition] of Object.entries(measures)) {
+        if (!isShiftMeasure(definition))
+            continue;
+        const prefix = `Invalid dataset "${datasetName}": shift measure "${name}"`;
+        if (!isSafeSQLIdentifier(name))
+            throw new Error(`${prefix} name is not a safe identifier.`);
+        if (!timeKey)
+            throw new Error(`${prefix} requires a timeKey.`);
+        if (!getBaseMeasure(measures, definition.measure))
+            throw new Error(`${prefix} must wrap a base measure; "${String(definition.measure)}" is not one.`);
+        const interval = definition.interval;
+        if (!interval || !Number.isSafeInteger(interval.amount) || interval.amount <= 0 || !isSupportedTimeGrain(interval.unit)) {
+            throw new Error(`${prefix} interval needs a positive safe integer and supported unit.`);
+        }
+    }
+}

package/dist/utils/sql-under-joins.d.ts

@@ -0,0 +1,10 @@
+import type { RelationshipBuilderContext } from './relationship-builder-plan.js';
+/**
+ * Raw SQL expressions on the base dataset are emitted verbatim, so their column
+ * references are not table-qualified. When relationship joins are active a bare
+ * `price` in such an expression is ambiguous if the joined table also has a
+ * `price` column. Until the builder rewrites identifiers inside expressions,
+ * reject the combination rather than emit ambiguous SQL.
+ */
+export declare function assertNoRawSqlUnderJoins(kind: 'dimension' | 'measure', name: string, sql: string, joinCtx?: RelationshipBuilderContext): void;
+//# sourceMappingURL=sql-under-joins.d.ts.map

package/dist/utils/sql-under-joins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-under-joins.d.ts","sourceRoot":"","sources":["../../src/utils/sql-under-joins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAEjF;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,0BAA0B,GACnC,IAAI,CASN"}