@hypequery/datasets 0.19.0 → 0.21.0

package/dist/utils/measure-dependencies.js

@@ -0,0 +1,44 @@
+import { isBaseMeasure, isDerivedMeasure, isShiftMeasure, isWindowMeasure } from './dataset-measures.js';
+export function measureDependencies(definition) {
+    if (isDerivedMeasure(definition))
+        return Object.values(definition.uses);
+    if (isShiftMeasure(definition) || isWindowMeasure(definition))
+        return [definition.measure];
+    return [];
+}
+/** Dependency order, with each shared input visited once. */
+export function measureDependencyNames(measures, selected) {
+    const visited = new Set();
+    const visiting = new Set();
+    const names = [];
+    const visit = (name) => {
+        if (visiting.has(name))
+            throw new Error(`Measure "${name}" contains a dependency cycle.`);
+        if (visited.has(name) || !Object.hasOwn(measures, name))
+            return;
+        visiting.add(name);
+        measureDependencies(measures[name]).forEach(visit);
+        visiting.delete(name);
+        visited.add(name);
+        names.push(name);
+    };
+    selected.forEach(visit);
+    return names;
+}
+export function assertMeasureDependenciesAcyclic(dataset, measures) {
+    try {
+        measureDependencyNames(measures, Object.keys(measures));
+    }
+    catch (error) {
+        throw new Error(`Invalid dataset "${dataset}": ${String(error)}`);
+    }
+}
+/** Wrappers inherit aggregation metadata only when their input has one. */
+export function inheritedBaseMeasure(measures, name) {
+    const definition = measures[name];
+    if (isBaseMeasure(definition))
+        return definition;
+    if (isWindowMeasure(definition) || isShiftMeasure(definition))
+        return inheritedBaseMeasure(measures, definition.measure);
+    return undefined;
+}

package/dist/utils/measure-evaluation-graph.d.ts

@@ -0,0 +1,23 @@
+import type { DatasetMeasureDefinition, DerivedMeasureDefinition, MeasureTimeInterval } from '../types.js';
+export interface MeasureEvaluationContext {
+    id: number;
+    parent?: number;
+    interval?: MeasureTimeInterval;
+}
+export interface MeasureEvaluationNode {
+    id: number;
+    name: string;
+    context: number;
+    definition: DatasetMeasureDefinition;
+    inputs?: Record<string, number>;
+}
+/** A shift changes evaluation context; formulas combine values in that context. */
+export declare function buildMeasureEvaluationGraph(measures: Readonly<Record<string, DatasetMeasureDefinition>>, selected: readonly string[]): {
+    contexts: MeasureEvaluationContext[];
+    nodes: MeasureEvaluationNode[];
+    outputs: {
+        [k: string]: number;
+    };
+};
+export declare function evaluationFormula(node: MeasureEvaluationNode): DerivedMeasureDefinition;
+//# sourceMappingURL=measure-evaluation-graph.d.ts.map

package/dist/utils/measure-evaluation-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-evaluation-graph.d.ts","sourceRoot":"","sources":["../../src/utils/measure-evaluation-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAG3G,MAAM,WAAW,wBAAwB;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAE;AACzG,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,wBAAwB,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE;;;;;;EA+BpI;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG,wBAAwB,CAIvF"}

package/dist/utils/measure-evaluation-graph.js

@@ -0,0 +1,38 @@
+import { isDerivedMeasure, isShiftMeasure } from './dataset-measures.js';
+/** A shift changes evaluation context; formulas combine values in that context. */
+export function buildMeasureEvaluationGraph(measures, selected) {
+    const contexts = [{ id: 0 }];
+    const nodes = [];
+    const memo = new Map();
+    const contextMemo = new Map();
+    const visit = (name, context) => {
+        const key = `${context}:${name}`;
+        const existing = memo.get(key);
+        if (existing !== undefined)
+            return existing;
+        const definition = measures[name];
+        if (isShiftMeasure(definition)) {
+            const contextKey = `${context}:${definition.interval.amount}:${definition.interval.unit}`;
+            let shifted = contextMemo.get(contextKey);
+            if (shifted === undefined) {
+                shifted = contexts.length;
+                contexts.push({ id: shifted, parent: context, interval: definition.interval });
+                contextMemo.set(contextKey, shifted);
+            }
+            const input = visit(definition.measure, shifted);
+            memo.set(key, input);
+            return input;
+        }
+        const inputs = isDerivedMeasure(definition)
+            ? Object.fromEntries(Object.entries(definition.uses).map(([alias, input]) => [alias, visit(input, context)])) : undefined;
+        const id = nodes.length;
+        nodes.push({ id, name, context, definition, inputs });
+        memo.set(key, id);
+        return id;
+    };
+    const outputs = Object.fromEntries(selected.map(name => [name, visit(name, 0)]));
+    return { contexts, nodes, outputs };
+}
+export function evaluationFormula(node) {
+    return { ...node.definition, uses: Object.fromEntries(Object.entries(node.inputs ?? {}).map(([alias, id]) => [alias, `_hq_value${id}`])) };
+}

package/dist/utils/measure-time-grains.d.ts

@@ -0,0 +1,4 @@
+import type { DatasetMeasureDefinition, TimeGrain } from '../types.js';
+/** Intersect time-measure requirements with the dataset's declared grains. */
+export declare function measureSupportedGrains(measures: Readonly<Record<string, DatasetMeasureDefinition>>, name: string, grains: readonly TimeGrain[]): TimeGrain[];
+//# sourceMappingURL=measure-time-grains.d.ts.map

package/dist/utils/measure-time-grains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-time-grains.d.ts","sourceRoot":"","sources":["../../src/utils/measure-time-grains.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAKvE,8EAA8E;AAC9E,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAS,EAAE,GACvG,SAAS,EAAE,CAWb"}

package/dist/utils/measure-time-grains.js

@@ -0,0 +1,18 @@
+import { getDerivedMeasure, isShiftMeasure, isWindowMeasure } from './dataset-measures.js';
+import { windowGrainErrors } from './time-axis-intervals.js';
+import { supportsShiftGrain } from './shift-measure-grains.js';
+/** Intersect time-measure requirements with the dataset's declared grains. */
+export function measureSupportedGrains(measures, name, grains) {
+    const definition = measures[name];
+    if (isShiftMeasure(definition)) {
+        return measureSupportedGrains(measures, definition.measure, grains)
+            .filter(grain => supportsShiftGrain(definition.interval, grain));
+    }
+    if (isWindowMeasure(definition))
+        return grains.filter(grain => !windowGrainErrors(name, definition, grain).length);
+    const derived = getDerivedMeasure(measures, name);
+    if (!derived)
+        return [...grains];
+    const inputs = Object.values(derived.uses).map(input => measureSupportedGrains(measures, input, grains));
+    return grains.filter(grain => inputs.every(supported => supported.includes(grain)));
+}

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/semantic-metadata-validation.js

@@ -34,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);

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-grains.d.ts

@@ -0,0 +1,5 @@
+import type { MeasureTimeInterval, TimeGrain } from '../types.js';
+/** Calendar shifts preserve dates; they do not convert months into fixed durations. */
+export declare function calendarShiftAtFineGrain(interval: MeasureTimeInterval, grain: TimeGrain): boolean;
+export declare function supportsShiftGrain(interval: MeasureTimeInterval, grain: TimeGrain): boolean;
+//# sourceMappingURL=shift-measure-grains.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shift-measure-grains.d.ts","sourceRoot":"","sources":["../../src/utils/shift-measure-grains.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGlE,uFAAuF;AACvF,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,mBAAmB,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAGjG;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,mBAAmB,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAG3F"}

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

@@ -0,0 +1,10 @@
+import { intervalBuckets } from './time-axis-intervals.js';
+/** Calendar shifts preserve dates; they do not convert months into fixed durations. */
+export function calendarShiftAtFineGrain(interval, grain) {
+    return ['month', 'quarter', 'year'].includes(interval.unit)
+        && ['minute', 'hour', 'day', 'week'].includes(grain);
+}
+export function supportsShiftGrain(interval, grain) {
+    return calendarShiftAtFineGrain(interval, grain)
+        || intervalBuckets(interval.amount, interval.unit, grain) !== undefined;
+}

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

@@ -0,0 +1,21 @@
+import type { ShiftMeasureDefinition } 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, axis: TimeMeasureAxis, axisGuard: string): string;
+/** Validate each output bucket after the series exists, including empty source populations. */
+export declare function shiftWallTimeSeriesGuardSql(shift: ShiftMeasureDefinition, grain: TimeMeasureAxis['grain']): 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;
+    sourceTimesSql: 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,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"}

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

@@ -0,0 +1,63 @@
+import { GRAIN_FUNCTIONS } from '../constants.js';
+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';
+/** 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);
+    // 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.
+    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,
+        lowerInclusive: period ? `(${period} > _hq_lower OR ${Number(axis.lowerInclusive)})` : String(Number(axis.lowerInclusive)),
+        upperInclusive: `(_hq_upper < ${end} AND ${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, axis, axisGuard) {
+    const { grain } = axis;
+    const { lower, upper } = shiftRangeSql(shift, axis);
+    const first = `${GRAIN_FUNCTIONS[grain]}(${lower})`;
+    const last = `${GRAIN_FUNCTIONS[grain]}(${upper})`;
+    const count = `dateDiff('${grain}', ${first}, ${last}) + ${axisGuard}`;
+    return calendarBucketGuardSql(first, count, grain);
+}
+/** Validate each output bucket after the series exists, including empty source populations. */
+export function shiftWallTimeSeriesGuardSql(shift, grain) {
+    const end = addTimeSql('_hq_period', 1, grain);
+    return shiftWallTimeGuardSql(shift.interval, grain, '_hq_series CROSS JOIN _hq_bounds', '_hq_period', 'greatest(_hq_period, _hq_lower)', `least(${end}, _hq_upper)`, end);
+}
+/** 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))`;
+    const join = ` 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' })}`;
+    return {
+        // Membership preserves duplicate source rows while excluding dates and
+        // partial ranges that no output bucket maps to, including clamped overlaps.
+        sourceTimesSql: `SELECT r._hq_time FROM _hq_source${join}`,
+        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${join}`,
+    };
+}

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 { 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 (!Object.hasOwn(measures, definition.measure))
+            throw new Error(`${prefix} references missing measure "${String(definition.measure)}".`);
+        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/shift-wall-time-sql.d.ts

@@ -0,0 +1,4 @@
+import type { MeasureTimeInterval, TimeGrain } from '../types.js';
+/** Reject DST normalization that moves a shifted sub-day bucket to another local time. */
+export declare function shiftWallTimeGuardSql(interval: MeasureTimeInterval, grain: TimeGrain, source: string, period: string, lower: string, upper: string, end: string): string;
+//# sourceMappingURL=shift-wall-time-sql.d.ts.map

package/dist/utils/shift-wall-time-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shift-wall-time-sql.d.ts","sourceRoot":"","sources":["../../src/utils/shift-wall-time-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIlE,0FAA0F;AAC1F,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,MAAM,CAYR"}

package/dist/utils/shift-wall-time-sql.js

@@ -0,0 +1,17 @@
+import { subtractTimeSql } from './time-arithmetic-sql.js';
+import { calendarShiftAtFineGrain } from './shift-measure-grains.js';
+/** Reject DST normalization that moves a shifted sub-day bucket to another local time. */
+export function shiftWallTimeGuardSql(interval, grain, source, period, lower, upper, end) {
+    if (!calendarShiftAtFineGrain(interval, grain) || (grain !== 'minute' && grain !== 'hour'))
+        return '0';
+    const changesWallTime = (value) => {
+        const shifted = subtractTimeSql(value, interval.amount, interval.unit);
+        return ['Hour', 'Minute', 'Second']
+            .map(part => `to${part}(${value}) != to${part}(${shifted})`)
+            .join(' OR ');
+    };
+    const changed = `(${changesWallTime(period)}) OR (${changesWallTime(lower)})`
+        + ` OR (${upper} != ${end} AND (${changesWallTime(upper)}))`;
+    return `(SELECT throwIf(countIf(${changed}) > 0, `
+        + `'Calendar shift lands on a nonexistent local time; use a UTC query timezone.') FROM ${source})`;
+}

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"}

package/dist/utils/sql-under-joins.js

@@ -0,0 +1,15 @@
+/**
+ * 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 function assertNoRawSqlUnderJoins(kind, name, sql, joinCtx) {
+    if (!joinCtx) {
+        return;
+    }
+    throw new Error(`SQL-backed ${kind} "${name}" cannot be combined with relationship joins: its expression ` +
+        `("${sql}") is not table-qualified and may collide with joined columns. Query it without ` +
+        `relationship-qualified fields, or redeclare it as a plain column.`);
+}

package/dist/utils/time-arithmetic-sql.d.ts

@@ -0,0 +1,4 @@
+import type { TimeGrain } from '../types.js';
+export declare function addTimeSql(time: string, amount: string | number, grain: TimeGrain): string;
+export declare function subtractTimeSql(time: string, amount: number, grain: TimeGrain): string;
+//# sourceMappingURL=time-arithmetic-sql.d.ts.map

package/dist/utils/time-arithmetic-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-arithmetic-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-arithmetic-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAE1F;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAEtF"}

package/dist/utils/time-arithmetic-sql.js

@@ -0,0 +1,9 @@
+const INTERVAL_FUNCTIONS = {
+    minute: 'Minutes', hour: 'Hours', day: 'Days', week: 'Weeks', month: 'Months', quarter: 'Quarters', year: 'Years',
+};
+export function addTimeSql(time, amount, grain) {
+    return `add${INTERVAL_FUNCTIONS[grain]}(${time}, ${amount})`;
+}
+export function subtractTimeSql(time, amount, grain) {
+    return `subtract${INTERVAL_FUNCTIONS[grain]}(${time}, ${amount})`;
+}

package/dist/utils/time-axis-bounds.d.ts

@@ -0,0 +1,24 @@
+import type { AnyDatasetInstance, MetricFilter } from '../types.js';
+export interface ParsedTimeBound {
+    /** Preserve the authored text: SQL interprets local bounds in the query timezone. */
+    text: string;
+    /** UTC instant for offset bounds; a wall-clock estimate for local bounds. */
+    milliseconds: number;
+    subMillisecond: boolean;
+    nanoseconds: bigint;
+    hasOffset: boolean;
+}
+export interface TimeAxisRange {
+    start: ParsedTimeBound;
+    end: ParsedTimeBound;
+    lowerInclusive: boolean;
+    upperInclusive: boolean;
+    filters: MetricFilter[];
+}
+/** Parse without applying the process timezone, preserving nanosecond precision. */
+export declare function parseTimeBound(value: unknown): ParsedTimeBound | undefined;
+/** Extract exactly one bounded time range, retaining all non-time predicates. */
+export declare function resolveTimeAxisRange(dataset: AnyDatasetInstance, filters: MetricFilter[]): TimeAxisRange | undefined;
+/** Mixed offset/local bounds cannot be ordered until the query timezone is known. */
+export declare function isDefinitelyEmptyTimeRange(range: TimeAxisRange): boolean;
+//# sourceMappingURL=time-axis-bounds.d.ts.map

package/dist/utils/time-axis-bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-axis-bounds.d.ts","sourceRoot":"","sources":["../../src/utils/time-axis-bounds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEpE,MAAM,WAAW,eAAe;IAC9B,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,eAAe,CAAC;IACvB,GAAG,EAAE,eAAe,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAID,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAuB1E;AAMD,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,aAAa,GAAG,SAAS,CA2BpH;AAED,qFAAqF;AACrF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAKxE"}

package/dist/utils/time-axis-bounds.js

@@ -0,0 +1,71 @@
+const ISO_TIME_BOUND = /^(\d{4}-\d{2}-\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|[+-]\d{2}:\d{2})?)?$/;
+/** Parse without applying the process timezone, preserving nanosecond precision. */
+export function parseTimeBound(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const match = ISO_TIME_BOUND.exec(value);
+    if (!match)
+        return undefined;
+    const [, day, hour, minute, second, fraction = '', offset] = match;
+    // Date.parse normalizes invalid calendar dates, so verify the authored day first.
+    const date = new Date(`${day}T00:00:00Z`);
+    if (!Number.isFinite(date.getTime()) || date.toISOString().slice(0, 10) !== day)
+        return undefined;
+    if (Number(hour ?? 0) > 23 || Number(minute ?? 0) > 59 || Number(second ?? 0) > 59)
+        return undefined;
+    const clock = hour === undefined ? `${day}T00:00:00` : value.replace(' ', 'T');
+    const hasOffset = offset !== undefined;
+    const milliseconds = Date.parse(hasOffset ? clock : `${clock}Z`);
+    if (!Number.isFinite(milliseconds))
+        return undefined;
+    const nanosecondRemainder = BigInt(fraction.padEnd(9, '0').slice(3));
+    return {
+        text: value,
+        milliseconds,
+        subMillisecond: nanosecondRemainder !== 0n,
+        nanoseconds: BigInt(milliseconds) * 1000000n + nanosecondRemainder,
+        hasOffset,
+    };
+}
+function timeColumn(dataset, name) {
+    return dataset.dimensions[name]?.column ?? name;
+}
+/** Extract exactly one bounded time range, retaining all non-time predicates. */
+export function resolveTimeAxisRange(dataset, filters) {
+    const timeFilters = filters.filter(filter => {
+        const field = dataset.filters[filter.field]?.field ?? filter.field;
+        return !field.includes('.') && timeColumn(dataset, field) === timeColumn(dataset, dataset.timeKey ?? '');
+    });
+    let lower;
+    let upper;
+    let lowerInclusive = true;
+    let upperInclusive = true;
+    const between = timeFilters.length === 1 ? timeFilters[0] : undefined;
+    if (between?.operator === 'between' && Array.isArray(between.value) && between.value.length === 2) {
+        [lower, upper] = between.value;
+    }
+    else if (timeFilters.length === 2) {
+        const start = timeFilters.find(filter => filter.operator === 'gt' || filter.operator === 'gte');
+        const end = timeFilters.find(filter => filter.operator === 'lt' || filter.operator === 'lte');
+        lower = start?.value;
+        upper = end?.value;
+        lowerInclusive = start?.operator === 'gte';
+        upperInclusive = end?.operator === 'lte';
+    }
+    const start = parseTimeBound(lower);
+    const end = parseTimeBound(upper);
+    if (!start || !end)
+        return undefined;
+    return {
+        start, end, lowerInclusive, upperInclusive,
+        filters: filters.filter(filter => !timeFilters.includes(filter)),
+    };
+}
+/** Mixed offset/local bounds cannot be ordered until the query timezone is known. */
+export function isDefinitelyEmptyTimeRange(range) {
+    const { start, end, lowerInclusive, upperInclusive } = range;
+    if (start.hasOffset !== end.hasOffset)
+        return false;
+    return start.nanoseconds > end.nanoseconds
+        || (start.nanoseconds === end.nanoseconds && !(lowerInclusive && upperInclusive));
+}

package/dist/utils/time-axis-calendar-guard.d.ts

@@ -0,0 +1,9 @@
+import type { TimeGrain } from '../types.js';
+/**
+ * Calendar arithmetic can clamp a nonexistent date onto the previous bucket
+ * (for example Pacific/Apia, 2011-12-30). Reject non-increasing bucket starts:
+ * repeating them would duplicate aggregates and cumulative contributions.
+ * `count` must already include the series/fanout guards, bounding enumeration.
+ */
+export declare function calendarBucketGuardSql(start: string, count: string, grain: TimeGrain): string;
+//# sourceMappingURL=time-axis-calendar-guard.d.ts.map

package/dist/utils/time-axis-calendar-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-axis-calendar-guard.d.ts","sourceRoot":"","sources":["../../src/utils/time-axis-calendar-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAQ7F"}

package/dist/utils/time-axis-calendar-guard.js

@@ -0,0 +1,17 @@
+import { addTimeSql } from './time-arithmetic-sql.js';
+/**
+ * Calendar arithmetic can clamp a nonexistent date onto the previous bucket
+ * (for example Pacific/Apia, 2011-12-30). Reject non-increasing bucket starts:
+ * repeating them would duplicate aggregates and cumulative contributions.
+ * `count` must already include the series/fanout guards, bounding enumeration.
+ */
+export function calendarBucketGuardSql(start, count, grain) {
+    if (grain === 'minute' || grain === 'hour')
+        return '0';
+    const current = addTimeSql(start, '_hq_calendar_index', grain);
+    const next = addTimeSql(start, '_hq_calendar_index + 1', grain);
+    // Include the end boundary, which also bounds the source-row scan.
+    const indices = `range(toUInt64(greatest(1, ${count})))`;
+    return `throwIf(arrayExists(_hq_calendar_index -> ${next} <= ${current}, ${indices}), `
+        + "'Time range crosses a skipped local calendar bucket; use a UTC time key for this range.')";
+}