@hypequery/datasets 0.18.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,10 +11,12 @@ 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;
+    /** Present, as `true`, when the value is an estimate; say so when reporting it. */
+    approximate?: true;
 }
 export interface AgentCatalogMetric extends SemanticMetadata {
     name: string;
@@ -47,9 +50,16 @@ export interface AgentCatalogDataset extends SemanticMetadata {
     measures: AgentCatalogMeasure[];
     metrics: AgentCatalogMetric[];
     filters: AgentCatalogFilter[];
+    /** Named segments an agent can select; their conditions are never shown. */
+    segments?: AgentCatalogSegment[];
     relationships: AgentCatalogRelationship[];
     limits: DatasetLimits;
 }
+export interface AgentCatalogSegment {
+    name: string;
+    label?: string;
+    description?: string;
+}
 export interface AgentSafeCatalog {
     datasets: AgentCatalogDataset[];
 }

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/aggregations.d.ts

@@ -18,6 +18,8 @@ import type { AggregationSpec } from './types.js';
 export declare function sum(field: string): AggregationSpec;
 export declare function count(field: string): AggregationSpec;
 export declare function countDistinct(field: string): AggregationSpec;
+/** Estimated distinct count (ClickHouse `uniq`). */
+export declare function approxCountDistinct(field: string): AggregationSpec;
 export declare function avg(field: string): AggregationSpec;
 export declare function min(field: string): AggregationSpec;
 export declare function max(field: string): AggregationSpec;

package/dist/aggregations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregations.d.ts","sourceRoot":"","sources":["../src/aggregations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,YAAY,CAAC;AAWnE,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAElD;AAED,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAEpD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAE5D;AAED,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAElD;AAED,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAElD;AAED,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAElD;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAGxE;AAED,mDAAmD;AACnD,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAErD;AAED,0DAA0D;AAC1D,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,eAAe,CAKjE;AAED,0DAA0D;AAC1D,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,eAAe,CAKjE;AAED,iCAAiC;AACjC,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAErD;AAED,uBAAuB;AACvB,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAEvD"}
+{"version":3,"file":"aggregations.d.ts","sourceRoot":"","sources":["../src/aggregations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,YAAY,CAAC;AAWnE,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAElD;AAED,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAEpD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAE5D;AAED,oDAAoD;AACpD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAElE;AAED,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAElD;AAED,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAElD;AAED,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAElD;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAGxE;AAED,mDAAmD;AACnD,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAErD;AAED,0DAA0D;AAC1D,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,eAAe,CAKjE;AAED,0DAA0D;AAC1D,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,eAAe,CAKjE;AAED,iCAAiC;AACjC,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAErD;AAED,uBAAuB;AACvB,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAEvD"}

package/dist/aggregations.js

@@ -31,6 +31,10 @@ export function count(field) {
 export function countDistinct(field) {
     return createAggregation('countDistinct', field);
 }
+/** Estimated distinct count (ClickHouse `uniq`). */
+export function approxCountDistinct(field) {
+    return createAggregation('approxCountDistinct', field);
+}
 export function avg(field) {
     return createAggregation('avg', field);
 }

package/dist/api.type-test.js

@@ -21,6 +21,25 @@ const Orders = dataset('orders', {
         }),
     },
 });
+const _SegmentedOrders = dataset('segmentedOrders', {
+    source: 'orders',
+    dimensions: { status: dimension.string() },
+    measures: { revenue: measure.sum('amount') },
+    segments: { paid: { filters: [eq('status', 'paid')] } },
+});
+const validDatasetSegments = { segments: ['paid'] };
+const validMetricSegments = { segments: ['paid'] };
+void validDatasetSegments;
+void validMetricSegments;
+// @ts-expect-error only declared segment names are accepted.
+const invalidDatasetSegments = { segments: ['paidd'] };
+// @ts-expect-error only declared segment names are accepted on metric queries.
+const invalidMetricSegments = { segments: ['paidd'] };
+// @ts-expect-error a dataset without segments has no selectable segment names.
+const invalidPlainSegments = { segments: ['paid'] };
+void invalidDatasetSegments;
+void invalidMetricSegments;
+void invalidPlainSegments;
 // @ts-expect-error standalone metrics may only target base measures.
 Orders.metric('invalidDerivedMetric', { measure: 'doubledRevenue' });
 dataset('derivedDependency', {
@@ -33,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', {
@@ -186,3 +227,19 @@ void typedAccepted;
 void typedClient;
 void typedRuntime;
 void rejectedFactory;
+// ---------------------------------------------------------------------------
+// Portable execution exclusions carry a named reason (HQ-45)
+// ---------------------------------------------------------------------------
+import { PortableExecutionUnsupportedError as PortableUnsupported, UNSUPPORTED_CONTRACT_REASONS as REASONS, UnsupportedContractFeatureError as ContractFeatureError, } from './index.js';
+const namedReason = REASONS.ambiguousMeasureSql;
+const literalReason = 'HQ_PORTABLE_DATASET_NOT_ACTIVATED';
+// @ts-expect-error an unnamed reason is not an exclusion
+const unnamedReason = 'HQ_PORTABLE_SOMETHING_ELSE';
+const featureReason = new ContractFeatureError('orders', 'metric', 'detail', namedReason).reason;
+// The three-argument constructor stays valid for existing callers.
+const legacyFeatureError = new ContractFeatureError('orders', 'metric', 'detail');
+const executionReason = new PortableUnsupported('message', { reason: literalReason }).reason;
+void unnamedReason;
+void featureReason;
+void legacyFeatureError;
+void executionReason;

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;AAuE3B,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,CAiBR;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,CAkBR"}
+{"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"}