@hypequery/datasets 0.19.0 → 0.20.0

package/dist/agent-catalog.d.ts

@@ -1,3 +1,4 @@
+import { type WindowCatalogMetadata } from './utils/window-catalog-metadata.js';
 import type { ProtocolDeploymentContract } from '@hypequery/protocol';
 import { type DatasetCatalog, type DatasetCatalogMap, type DatasetCatalogSource } from './catalog.js';
 import type { SemanticContract } from './contract.js';
@@ -10,7 +11,7 @@ export interface AgentCatalogDimension extends SemanticMetadata {
     filterable: boolean;
     groupable: boolean;
 }
-export interface AgentCatalogMeasure extends SemanticMetadata {
+export interface AgentCatalogMeasure extends SemanticMetadata, WindowCatalogMetadata {
     name: string;
     label?: string;
     description?: string;

package/dist/agent-catalog.d.ts.map

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

package/dist/api.type-test.js

@@ -52,6 +52,28 @@ dataset('derivedDependency', {
         quadrupled: measure.derived({ uses: { value: 'doubled' }, formula: ({ value }) => add(value, value) }),
     },
 });
+const _WindowOrders = dataset('windowOrders', {
+    source: 'orders', timeKey: 'createdAt',
+    dimensions: { createdAt: dimension.timestamp(), amount: dimension.number() },
+    measures: {
+        revenue: measure.sum('amount'),
+        trailingRevenue: measure.trailing('revenue', { amount: 7, unit: 'day' }),
+        runningRevenue: measure.cumulative('revenue'),
+        growth: measure.derived({ uses: { running: 'runningRevenue' }, formula: ({ running }) => add(running, running) }),
+    },
+});
+// @ts-expect-error standalone metrics may only target base measures, even in the unified registry.
+_WindowOrders.metric('invalidWindowMetric', { measure: 'runningRevenue' });
+dataset('invalidWindowInput', {
+    source: 'orders', timeKey: 'createdAt',
+    dimensions: { createdAt: dimension.timestamp(), amount: dimension.number() },
+    measures: {
+        revenue: measure.sum('amount'),
+        growth: measure.derived({ uses: { value: 'revenue' }, formula: ({ value }) => add(value, value) }),
+        // @ts-expect-error a window must wrap a base measure.
+        invalid: measure.cumulative('growth'),
+    },
+});
 const deploymentContract = buildProtocolDeploymentContract([Orders]);
 rehydrateProtocolDeploymentContract(deploymentContract);
 dataset('invalidDependency', {

package/dist/cache/definition-identity.d.ts

@@ -0,0 +1,26 @@
+import type { AnyDatasetInstance } from '../types.js';
+/**
+ * The local definition identity RFC 0009 leaves implementation-defined: a
+ * digest of every definition that could affect the rows of a query over
+ * `root`, plus the metric spec, cache scope, and timezone when present.
+ *
+ * Throws when a definition holds a function it cannot describe safely; the
+ * caller then runs the query uncached.
+ *
+ * Entries under it are never shared with released deployments or with other
+ * implementations. That costs only misses, and any definition change starts
+ * fresh.
+ */
+export declare function localDefinitionIdentity(root: AnyDatasetInstance, extra?: {
+    metric?: unknown;
+    scope?: string;
+    timezone?: string;
+}): string;
+/**
+ * Folds a cache scope and a non-default timezone into a deployed definition
+ * identity. Both change the rows one release returns (`scope` picks the data
+ * source, the timezone moves bucket boundaries), so they must separate keys
+ * even when the definitions are identical.
+ */
+export declare function scopedDefinitionIdentity(identity: string, scope: string | undefined, timezone?: string): string;
+//# sourceMappingURL=definition-identity.d.ts.map

package/dist/cache/definition-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-identity.d.ts","sourceRoot":"","sources":["../../src/cache/definition-identity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAe,MAAM,aAAa,CAAC;AA8InE;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,kBAAkB,EACxB,KAAK,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE,MAAM,CAWR;AAMD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAKR"}

package/dist/cache/definition-identity.js

@@ -0,0 +1,164 @@
+import { sha256 } from '@noble/hashes/sha2';
+import { bytesToHex } from '@noble/hashes/utils';
+import { stableStringify } from '../utils/canonical-json.js';
+const LOCAL_DEFINITION_DOMAIN = 'hypequery.ts.local-definitions.v2\0';
+/**
+ * Library-created methods, by the `__type` of the object that carries them.
+ * They read only state that is described alongside them, so they contribute
+ * nothing of their own.
+ */
+const LIBRARY_METHODS = {
+    dataset: ['metric'],
+    metric_ref: ['by', 'contract'],
+    grained_metric_ref: ['contract'],
+};
+function isDataset(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && value.__type === 'dataset'
+        && typeof value.name === 'string');
+}
+function isFormulaExpr(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && value.__type === 'formula_expr'
+        && typeof value.toSQL === 'function');
+}
+/**
+ * The formula's own SQL, which derived metrics execute. `null` when it throws:
+ * derived measures compile the expression instead, so it need not render.
+ */
+function formulaSql(formula) {
+    try {
+        return formula.toSQL();
+    }
+    catch {
+        return null;
+    }
+}
+function undescribable(key) {
+    throw new Error(`Cannot derive a local definition identity: the function at "${key ?? '?'}" `
+        + 'is not a formula, relationship target, or library method.');
+}
+/**
+ * Builds a deterministic description of every definition a query over a root
+ * dataset could read.
+ *
+ * A function never contributes its source text: that omits the values it
+ * captures, so `make(2)` and `make(3)` over `({ r }) => round(r, digits)`
+ * would collide. Instead:
+ * - a formula is evaluated, and its resolved expression and SQL are described;
+ * - a relationship target contributes its dataset's name, and that dataset is
+ *   described separately;
+ * - a known library method contributes nothing.
+ *
+ * Any other function throws, so the caller runs the query uncached rather
+ * than risk serving another definition's rows.
+ */
+class DefinitionDescriber {
+    found = new Map();
+    pending = [];
+    /** Queues a dataset for description and stands in for it by name. */
+    reference(dataset) {
+        if (!this.found.has(dataset.name)) {
+            this.found.set(dataset.name, dataset);
+            this.pending.push(dataset);
+        }
+        return { dataset: dataset.name };
+    }
+    /** Describes every queued dataset, including those queued along the way. */
+    describeDatasets() {
+        const described = {};
+        while (this.pending.length > 0) {
+            const dataset = this.pending.pop();
+            described[dataset.name] = this.describeFields(dataset, new WeakSet());
+        }
+        return described;
+    }
+    describe(value, seen, owner, key) {
+        if (typeof value === 'function')
+            return this.describeFunction(value, seen, owner, key);
+        if (value instanceof Date)
+            return { date: value.toISOString() };
+        if (typeof value === 'bigint')
+            return { bigint: value.toString() };
+        if (typeof value !== 'object' || value === null)
+            return value;
+        if (isDataset(value))
+            return this.reference(value);
+        return this.describeFields(value, seen);
+    }
+    describeFields(value, seen) {
+        if (seen.has(value))
+            return '[cycle]';
+        seen.add(value);
+        const described = Array.isArray(value)
+            ? value.map((item) => this.describe(item, seen))
+            : Object.fromEntries(Object.entries(value).map(([name, item]) => [
+                name,
+                this.describe(item, seen, value, name),
+            ]));
+        seen.delete(value);
+        return described;
+    }
+    describeFunction(fn, seen, owner, key) {
+        if (key === 'target') {
+            const target = fn();
+            return isDataset(target) ? this.reference(target) : undescribable(key);
+        }
+        if (key === 'formula' && owner && typeof owner.uses === 'object' && owner.uses !== null) {
+            // The same identity aliases the planner and validation evaluate with.
+            const aliases = Object.fromEntries(Object.keys(owner.uses).map((alias) => [alias, alias]));
+            const result = fn(aliases);
+            if (!isFormulaExpr(result))
+                return undescribable(key);
+            return { expression: this.describe(result.expression, seen), sql: formulaSql(result) };
+        }
+        const type = typeof owner?.__type === 'string' ? owner.__type : undefined;
+        if (type !== undefined && key !== undefined && LIBRARY_METHODS[type]?.includes(key)) {
+            return 'method';
+        }
+        return undescribable(key);
+    }
+}
+/**
+ * The local definition identity RFC 0009 leaves implementation-defined: a
+ * digest of every definition that could affect the rows of a query over
+ * `root`, plus the metric spec, cache scope, and timezone when present.
+ *
+ * Throws when a definition holds a function it cannot describe safely; the
+ * caller then runs the query uncached.
+ *
+ * Entries under it are never shared with released deployments or with other
+ * implementations. That costs only misses, and any definition change starts
+ * fresh.
+ */
+export function localDefinitionIdentity(root, extra = {}) {
+    const describer = new DefinitionDescriber();
+    describer.reference(root);
+    const metric = extra.metric === undefined ? null : describer.describe(extra.metric, new WeakSet());
+    const description = stableStringify({
+        datasets: describer.describeDatasets(),
+        metric,
+        scope: extra.scope ?? null,
+        timezone: extra.timezone ?? null,
+    });
+    return bytesToHex(sha256(new TextEncoder().encode(LOCAL_DEFINITION_DOMAIN + description)));
+}
+function foldPartition(identity, domain, value) {
+    return bytesToHex(sha256(new TextEncoder().encode(`${domain}\0${identity}\0${value}`)));
+}
+/**
+ * Folds a cache scope and a non-default timezone into a deployed definition
+ * identity. Both change the rows one release returns (`scope` picks the data
+ * source, the timezone moves bucket boundaries), so they must separate keys
+ * even when the definitions are identical.
+ */
+export function scopedDefinitionIdentity(identity, scope, timezone) {
+    let folded = identity;
+    if (scope !== undefined)
+        folded = foldPartition(folded, 'hypequery.ts.cache-scope.v1', scope);
+    if (timezone !== undefined)
+        folded = foldPartition(folded, 'hypequery.ts.cache-timezone.v1', timezone);
+    return folded;
+}

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

@@ -0,0 +1,38 @@
+import type { AnyDatasetInstance, DatasetQuery, ExecutionContext, GrainedMetricRef, MetricQuery, MetricRef } from '../types.js';
+/** Namespace defaults, so caching works without any configuration. */
+export declare const DEFAULT_CACHE_PROJECT = "hypequery";
+export declare const DEFAULT_CACHE_ENVIRONMENT = "default";
+/** Key settings from `SemanticCacheOptions`, resolved once per client. */
+export interface ProtocolCacheKeySettings {
+    readonly secret: Uint8Array;
+    readonly project: string;
+    readonly environment: string;
+    readonly keyVersion: number;
+    readonly definitionIdentity?: string;
+}
+export interface ProtocolCacheKeyOptions {
+    secret?: Uint8Array;
+    project?: string;
+    environment?: string;
+    keyVersion?: number;
+    definitionIdentity?: string;
+}
+/**
+ * Resolves and validates key settings at client construction, so a
+ * misconfiguration fails at startup rather than silently caching nothing.
+ *
+ * Without a secret the cache generates a random one for its lifetime. Keys
+ * stay HMAC-derived and opaque; entries are simply not shared beyond this
+ * client. An explicitly empty or short secret is an error, never a reason to
+ * generate one.
+ */
+export declare function resolveProtocolCacheKeySettings(options: ProtocolCacheKeyOptions, sharedStore: boolean): ProtocolCacheKeySettings;
+/**
+ * The RFC 0013 store key for a dataset query, or `undefined` when the call
+ * cannot be cached (for example, a filter value with no portable form).
+ * `query` must already carry its effective limit.
+ */
+export declare function datasetCacheKey(settings: ProtocolCacheKeySettings, ds: AnyDatasetInstance, query: DatasetQuery, context: ExecutionContext | undefined, scope: string | undefined): string | undefined;
+/** The RFC 0013 store key for a metric query; see `datasetCacheKey`. */
+export declare function metricCacheKey(settings: ProtocolCacheKeySettings, metric: MetricRef | GrainedMetricRef, query: MetricQuery, context: ExecutionContext | undefined, scope: string | undefined): string | undefined;
+//# sourceMappingURL=protocol-cache-keys.d.ts.map

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

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

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

@@ -0,0 +1,191 @@
+import { buildProtocolCachePreimage, deriveProtocolCacheKey, validateCanonicalValue, } from '@hypequery/protocol';
+import { getMetricGrain, getMetricRef } from '../utils/metric-handle.js';
+import { localDefinitionIdentity, scopedDefinitionIdentity } from './definition-identity.js';
+/** Namespace defaults, so caching works without any configuration. */
+export const DEFAULT_CACHE_PROJECT = 'hypequery';
+export const DEFAULT_CACHE_ENVIRONMENT = 'default';
+const SECRET_BYTES = 32;
+const DEFINITION_IDENTITY = /^[0-9a-f]{64}$/;
+let warnedSharedStoreWithoutSecret = false;
+/**
+ * Resolves and validates key settings at client construction, so a
+ * misconfiguration fails at startup rather than silently caching nothing.
+ *
+ * Without a secret the cache generates a random one for its lifetime. Keys
+ * stay HMAC-derived and opaque; entries are simply not shared beyond this
+ * client. An explicitly empty or short secret is an error, never a reason to
+ * generate one.
+ */
+export function resolveProtocolCacheKeySettings(options, sharedStore) {
+    let secret = options.secret;
+    if (secret === undefined) {
+        secret = globalThis.crypto.getRandomValues(new Uint8Array(SECRET_BYTES));
+        if (sharedStore && !warnedSharedStoreWithoutSecret) {
+            warnedSharedStoreWithoutSecret = true;
+            console.warn('[hypequery/cache] No cache secret is configured, so this client generated one. '
+                + 'Other instances sharing this store will not reuse its entries. '
+                + 'Pass the same cache.secret to every instance to share them.');
+        }
+    }
+    if (options.definitionIdentity !== undefined
+        && !DEFINITION_IDENTITY.test(options.definitionIdentity)) {
+        throw new Error('cache.definitionIdentity must be 64 lowercase hexadecimal characters.');
+    }
+    const settings = {
+        secret,
+        project: options.project ?? DEFAULT_CACHE_PROJECT,
+        environment: options.environment ?? DEFAULT_CACHE_ENVIRONMENT,
+        keyVersion: options.keyVersion ?? 1,
+        ...(options.definitionIdentity !== undefined
+            ? { definitionIdentity: options.definitionIdentity }
+            : {}),
+    };
+    // Throws ProtocolCacheKeyError for an empty or short secret, an invalid
+    // namespace, or an out-of-range key version.
+    deriveProtocolCacheKey({
+        secret: settings.secret,
+        namespace: { project: settings.project, environment: settings.environment },
+        keyVersion: settings.keyVersion,
+        preimage: '',
+    });
+    return settings;
+}
+function datetimeValue(value) {
+    return validateCanonicalValue({
+        $hypequery: {
+            type: 'datetime',
+            version: 1,
+            clickhouseType: 'DateTime64',
+            precision: 3,
+            timezone: 'UTC',
+            value: value.toISOString(),
+        },
+    });
+}
+/** A filter value as an RFC 0001 canonical value. Throws when it has none. */
+function canonicalLiteral(value) {
+    if (value instanceof Date)
+        return datetimeValue(value);
+    if (Array.isArray(value)) {
+        return validateCanonicalValue({
+            $hypequery: { type: 'array', version: 1, values: value.map(canonicalLiteral) },
+        });
+    }
+    return validateCanonicalValue(value);
+}
+function filterNode(filter) {
+    let literal;
+    if (filter.operator === 'between' && Array.isArray(filter.value)) {
+        // RFC 0003 bounds are a two-item tuple; in/notIn take an array.
+        literal = validateCanonicalValue({
+            $hypequery: { type: 'tuple', version: 1, values: filter.value.map(canonicalLiteral) },
+        });
+    }
+    else {
+        literal = canonicalLiteral(filter.value);
+    }
+    return {
+        kind: 'comparison',
+        operator: filter.operator,
+        left: { kind: 'reference', name: filter.field },
+        right: { kind: 'literal', value: literal },
+    };
+}
+function sharedQueryFields(query) {
+    return {
+        ...(query.dimensions !== undefined ? { dimensions: [...query.dimensions] } : {}),
+        ...(query.filters !== undefined ? { filters: query.filters.map(filterNode) } : {}),
+        ...(query.segments !== undefined ? { segments: [...query.segments] } : {}),
+        ...(query.orderBy !== undefined
+            ? { orderBy: query.orderBy.map(({ field, direction }) => ({ field, direction })) }
+            : {}),
+        ...(query.limit !== undefined ? { limit: query.limit } : {}),
+        ...(query.offset !== undefined ? { offset: query.offset } : {}),
+    };
+}
+/** The tenant capability present on the call, whether or not it is applied. */
+function tenantScope(context) {
+    const tenant = context?.runtime?.tenant;
+    if (tenant === undefined)
+        return { mode: 'none' };
+    if (typeof tenant === 'string')
+        return { mode: 'scoped', ids: [tenant] };
+    if ('scope' in tenant && tenant.scope === 'all')
+        return { mode: 'all' };
+    if ('id' in tenant)
+        return { mode: 'scoped', ids: [tenant.id] };
+    if ('in' in tenant)
+        return { mode: 'scoped', ids: [...tenant.in] };
+    // Unrecognized runtime shapes fail preimage validation and run uncached.
+    return tenant;
+}
+function deriveKey(settings, query, definitionIdentity, context, rowLimit) {
+    const preimage = buildProtocolCachePreimage({
+        secret: settings.secret,
+        definitionIdentity,
+        query,
+        tenant: tenantScope(context),
+        rowLimit: rowLimit ?? null,
+    });
+    return deriveProtocolCacheKey({
+        secret: settings.secret,
+        namespace: { project: settings.project, environment: settings.environment },
+        keyVersion: settings.keyVersion,
+        preimage,
+    });
+}
+/**
+ * RFC 0009's normalized query has no timezone, yet it moves bucket boundaries
+ * and local time-key bounds. It is folded into the definition identity, as
+ * `scope` is. UTC, the client default, folds in nothing, so default queries
+ * keep the keys other runtimes derive for the same release.
+ */
+function partitionTimezone(query) {
+    return query.timezone === 'UTC' ? undefined : query.timezone;
+}
+function definitionFor(settings, root, scope, query, metric) {
+    const timezone = partitionTimezone(query);
+    return settings.definitionIdentity !== undefined
+        ? scopedDefinitionIdentity(settings.definitionIdentity, scope, timezone)
+        : localDefinitionIdentity(root, { metric, scope, timezone });
+}
+/**
+ * The RFC 0013 store key for a dataset query, or `undefined` when the call
+ * cannot be cached (for example, a filter value with no portable form).
+ * `query` must already carry its effective limit.
+ */
+export function datasetCacheKey(settings, ds, query, context, scope) {
+    try {
+        const wire = {
+            kind: 'dataset',
+            dataset: ds.name,
+            ...sharedQueryFields(query),
+            ...(query.measures !== undefined ? { measures: [...query.measures] } : {}),
+            ...(query.by !== undefined ? { by: query.by } : {}),
+        };
+        return deriveKey(settings, wire, definitionFor(settings, ds, scope, query), context, query.limit);
+    }
+    catch {
+        // A cache failure never fails a query: run uncached.
+        return undefined;
+    }
+}
+/** The RFC 0013 store key for a metric query; see `datasetCacheKey`. */
+export function metricCacheKey(settings, metric, query, context, scope) {
+    try {
+        const ref = getMetricRef(metric);
+        const grain = getMetricGrain(metric, query);
+        const wire = {
+            kind: 'metric',
+            dataset: ref.dataset.name,
+            metric: ref.name,
+            ...sharedQueryFields(query),
+            ...(grain !== undefined ? { by: grain } : {}),
+        };
+        const definition = definitionFor(settings, ref.dataset, scope, query, ref.spec);
+        return deriveKey(settings, wire, definition, context, query.limit);
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -14,6 +14,12 @@
 import type { AnyDatasetInstance, DatasetQuery, ExecutionContext, GrainedMetricRef, MetricQuery, MetricRef } from '../types.js';
 import { stableStringify } from '../utils/canonical-json.js';
 export { stableStringify };
+/**
+ * @deprecated The result cache no longer keys entries by this readable
+ * signature. It uses opaque RFC 0009/0013 keys, which never contain tenant ids,
+ * filter values, or table names. Kept for callers that used it directly.
+ */
 export declare function buildDatasetQuerySignature(ds: AnyDatasetInstance, query: DatasetQuery, context?: ExecutionContext): string;
+/** @deprecated See `buildDatasetQuerySignature`. */
 export declare function buildMetricQuerySignature(metric: MetricRef | GrainedMetricRef, query: MetricQuery, context?: ExecutionContext): string;
 //# sourceMappingURL=query-signature.d.ts.map

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

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

package/dist/cache/query-signature.js

@@ -1,16 +1,4 @@
-/**
- * Canonical cache keys for semantic queries.
- *
- * A signature captures everything that changes a query's result set: the
- * target (dataset or metric), selected dimensions/measures, filters, ordering,
- * pagination, time grain, the effective tenant scope, and any explicit cache
- * scope (see `SemanticCacheRuntime.scope`). Two calls with the
- * same signature are guaranteed to produce the same rows against the same
- * underlying data, so the signature is safe to use as a result-cache key.
- *
- * Keys are readable canonical strings rather than hashes so stores can inspect
- * them and tests can assert on them; stores are free to hash internally.
- */
+import { windowQuerySignature } from '../utils/window-query-signature.js';
 import { getMetricGrain, getMetricRef } from '../utils/metric-handle.js';
 import { getRuntimeTenantPredicate } from '../utils/tenant-runtime.js';
 import { buildRelationshipBuilderContext } from '../utils/relationship-builder-plan.js';
@@ -84,6 +72,11 @@ function segmentSignature(ds, names) {
         })),
     };
 }
+/**
+ * @deprecated The result cache no longer keys entries by this readable
+ * signature. It uses opaque RFC 0009/0013 keys, which never contain tenant ids,
+ * filter values, or table names. Kept for callers that used it directly.
+ */
 export function buildDatasetQuerySignature(ds, query, context) {
     return stableStringify({
         v: SIGNATURE_VERSION,
@@ -93,16 +86,19 @@ export function buildDatasetQuerySignature(ds, query, context) {
         dimensions: query.dimensions ?? null,
         // `null` distinguishes the "all measures" default from an explicit [].
         measures: query.measures ?? null,
+        ...windowQuerySignature(ds, query),
         filters: filterSignature(query.filters),
         ...segmentSignature(ds, query.segments),
         orderBy: orderBySignature(query.orderBy),
         by: query.by ?? null,
+        ...(query.timezone === undefined ? {} : { timezone: query.timezone }),
         limit: query.limit ?? null,
         offset: query.offset ?? null,
         tenant: tenantSignature(ds, query, context),
         scope: scopeSignature(context),
     });
 }
+/** @deprecated See `buildDatasetQuerySignature`. */
 export function buildMetricQuerySignature(metric, query, context) {
     const ref = getMetricRef(metric);
     const grain = getMetricGrain(metric, query);
@@ -117,6 +113,7 @@ export function buildMetricQuerySignature(metric, query, context) {
         ...segmentSignature(ref.dataset, query.segments),
         orderBy: orderBySignature(query.orderBy),
         by: grain ?? null,
+        ...(query.timezone === undefined ? {} : { timezone: query.timezone }),
         limit: query.limit ?? null,
         offset: query.offset ?? null,
         tenant: tenantSignature(ref.dataset, query, context),

package/dist/cache/semantic-query-cache.d.ts

@@ -51,6 +51,29 @@ export interface SemanticCacheOptions {
      * so identical queries against different backends never collide.
      */
     scope?: string;
+    /**
+     * RFC 0013 cache-key secret: at least 32 random bytes, the same on every
+     * instance that shares a store, distinct per environment, never shipped.
+     *
+     * Optional. Without it the client generates a random secret for its
+     * lifetime, so keys stay opaque but entries are not shared with other
+     * instances or across restarts. That is all an in-memory store needs; set
+     * it for a shared store such as Redis. Keys never contain tenant ids,
+     * filter values, or table names either way.
+     */
+    secret?: Uint8Array;
+    /** Namespace project for RFC 0013 keys. Defaults to `'hypequery'`. */
+    project?: string;
+    /** Namespace environment for RFC 0013 keys. Defaults to `'default'`. */
+    environment?: string;
+    /** Increment whenever `secret` rotates; old entries become unreachable. Defaults to 1. */
+    keyVersion?: number;
+    /**
+     * The deployed bundle identity (RFC 0007), to share entries with other
+     * runtimes serving the same release, including Python. Without it, a digest
+     * of the local definitions is used.
+     */
+    definitionIdentity?: string;
 }
 /** Per-call cache controls, passed via `ExecutionContext.cache`. */
 export interface SemanticCacheRuntime {

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

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

package/dist/catalog.d.ts

@@ -1,3 +1,4 @@
+import { type WindowCatalogMetadata } from './utils/window-catalog-metadata.js';
 import type { AnyDatasetInstance, DimensionDefinition, MeasureDefinition, MetricHandle, RelationshipDefinition, SemanticFilterDefinition, DatasetLimits, DatasetDefaults, DatasetFreshness, SemanticMetadata, TimeGrain } from './types.js';
 export interface DimensionCatalogEntry extends SemanticMetadata {
     type: DimensionDefinition['fieldType'];
@@ -8,7 +9,7 @@ export interface DimensionCatalogEntry extends SemanticMetadata {
     filterable: boolean;
     groupable: boolean;
 }
-export interface MeasureCatalogEntry extends SemanticMetadata {
+export interface MeasureCatalogEntry extends SemanticMetadata, WindowCatalogMetadata {
     aggregation: MeasureDefinition['aggregation'];
     field: string;
     /** Second column for argMax/argMin. */
@@ -22,7 +23,7 @@ export interface MeasureCatalogEntry extends SemanticMetadata {
     /** Present, as `true`, when the measure returns an estimate. */
     approximate?: true;
 }
-export interface DerivedMeasureCatalogEntry extends SemanticMetadata {
+export interface DerivedMeasureCatalogEntry extends SemanticMetadata, WindowCatalogMetadata {
     label?: string;
     description?: string;
     /** Present, as `true`, when any measure the formula uses is approximate. */

package/dist/catalog.d.ts.map

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