@hypequery/datasets 0.5.0 → 0.7.0

package/dist/api.type-test.js

@@ -101,3 +101,16 @@ analytics.toSQL(Orders, datasetQuery, runtimeContext);
 void analytics.execute(Orders, datasetQuery, runtimeContext);
 void runtimeContext;
 void explicitAnalytics;
+// Sanity: the simulated shape reproduces the original incompatibility.
+// @ts-expect-error a schema-typed builder does not satisfy the strict protocol
+const strictRejection = simulatedTypedFactory;
+const typedAccepted = simulatedTypedFactory;
+const typedClient = createDatasetClient({ queryBuilder: simulatedTypedFactory });
+const typedRuntime = { runtime: { builderFactory: simulatedTypedFactory } };
+// @ts-expect-error non-builder objects are still rejected
+const rejectedFactory = { notABuilder: true };
+void strictRejection;
+void typedAccepted;
+void typedClient;
+void typedRuntime;
+void rejectedFactory;

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

@@ -0,0 +1,19 @@
+/**
+ * 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 type { AnyDatasetInstance, DatasetQuery, ExecutionContext, GrainedMetricRef, MetricQuery, MetricRef } from '../types.js';
+import { stableStringify } from '../utils/canonical-json.js';
+export { stableStringify };
+export declare function buildDatasetQuerySignature(ds: AnyDatasetInstance, query: DatasetQuery, context?: ExecutionContext): string;
+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

@@ -0,0 +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;AAGrB,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D,OAAO,EAAE,eAAe,EAAE,CAAC;AA8C3B,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"}

package/dist/cache/query-signature.js

@@ -0,0 +1,93 @@
+/**
+ * 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 { getMetricGrain, getMetricRef } from '../utils/metric-handle.js';
+import { getRuntimeTenantPredicate } from '../utils/tenant-runtime.js';
+import { stableStringify } from '../utils/canonical-json.js';
+export { stableStringify };
+const SIGNATURE_VERSION = 1;
+/**
+ * Explicit cache partition. Callers set `cache.scope` when the same semantic
+ * query can resolve against different data sources (per-call builder
+ * overrides, multiple clients sharing one store).
+ */
+function scopeSignature(context) {
+    const cache = context?.cache;
+    return cache ? cache.scope ?? null : null;
+}
+function filterSignature(filters) {
+    return (filters ?? []).map((filter) => ({
+        field: filter.field,
+        operator: filter.operator,
+        value: filter.value ?? null,
+    }));
+}
+function orderBySignature(orderBy) {
+    return (orderBy ?? []).map((order) => ({
+        field: order.field,
+        direction: order.direction,
+    }));
+}
+/**
+ * Tenant portion of the key. Only datasets with a `tenantKey` apply the
+ * runtime tenant predicate, so tenant-less datasets share entries across
+ * callers while tenant-scoped datasets are strictly partitioned per scope.
+ */
+function tenantSignature(ds, context) {
+    if (!ds.tenantKey) {
+        return null;
+    }
+    const predicate = getRuntimeTenantPredicate(context);
+    if (!predicate) {
+        // Trusted cross-tenant scope (`scope: 'all'`) or no runtime tenancy.
+        return { key: ds.tenantKey, scope: 'all' };
+    }
+    return { key: ds.tenantKey, operator: predicate.operator, value: predicate.value };
+}
+export function buildDatasetQuerySignature(ds, query, context) {
+    return stableStringify({
+        v: SIGNATURE_VERSION,
+        kind: 'dataset',
+        target: ds.name,
+        source: ds.source,
+        dimensions: query.dimensions ?? null,
+        // `null` distinguishes the "all measures" default from an explicit [].
+        measures: query.measures ?? null,
+        filters: filterSignature(query.filters),
+        orderBy: orderBySignature(query.orderBy),
+        by: query.by ?? null,
+        limit: query.limit ?? null,
+        offset: query.offset ?? null,
+        tenant: tenantSignature(ds, context),
+        scope: scopeSignature(context),
+    });
+}
+export function buildMetricQuerySignature(metric, query, context) {
+    const ref = getMetricRef(metric);
+    const grain = getMetricGrain(metric, query);
+    return stableStringify({
+        v: SIGNATURE_VERSION,
+        kind: 'metric',
+        target: `${ref.dataset.name}.${ref.name}`,
+        source: ref.dataset.source,
+        metricKind: ref.spec.__type,
+        dimensions: query.dimensions ?? null,
+        filters: filterSignature(query.filters),
+        orderBy: orderBySignature(query.orderBy),
+        by: grain ?? null,
+        limit: query.limit ?? null,
+        offset: query.offset ?? null,
+        tenant: tenantSignature(ref.dataset, context),
+        scope: scopeSignature(context),
+    });
+}

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

@@ -0,0 +1,108 @@
+/**
+ * Semantic query result cache.
+ *
+ * Sits between `DatasetClient.execute()` and the underlying query builder /
+ * backend, keyed by the canonical query signature (see query-signature.ts).
+ * Supports TTL freshness, an optional stale-while-revalidate window, and
+ * deduplication of concurrent identical lookups so a burst of the same query
+ * executes once — including against async stores, where the in-flight lookup
+ * is registered before the store read. Piggybacked callers inherit the
+ * initiating caller's TTL resolution.
+ *
+ * Values are cloned on write and on read: callers can mutate results freely
+ * without contaminating the cache, and cached hits never alias each other.
+ */
+export interface SemanticCacheEntry {
+    value: unknown;
+    storedAt: number;
+}
+/**
+ * Pluggable store. The default is an in-process LRU; provide a custom store
+ * (e.g. Redis-backed) for multi-instance deployments. Stores hold opaque
+ * entries — freshness is decided by the cache from `storedAt` and the
+ * effective TTL, so per-call TTLs work against shared entries.
+ *
+ * Store errors are non-fatal: a failed read is treated as a miss and a failed
+ * write is dropped, so a store outage degrades to uncached execution rather
+ * than failing queries.
+ */
+export interface SemanticCacheStore {
+    get(key: string): SemanticCacheEntry | undefined | Promise<SemanticCacheEntry | undefined>;
+    set(key: string, entry: SemanticCacheEntry): void | Promise<void>;
+    delete(key: string): void | Promise<void>;
+    clear?(): void | Promise<void>;
+}
+/** Client-level cache defaults (see `CreateDatasetClientOptions.cache`). */
+export interface SemanticCacheOptions {
+    /** Fresh window in milliseconds. 0 / omitted = only per-call opt-in caches. */
+    ttlMs?: number;
+    /**
+     * Additional window after `ttlMs` during which a stale result is returned
+     * immediately while a background refresh repopulates the entry.
+     */
+    staleWhileRevalidateMs?: number;
+    /** Max entries for the default in-memory store. Ignored when `store` is set. */
+    maxEntries?: number;
+    /** Custom store; defaults to an in-process LRU. */
+    store?: SemanticCacheStore;
+    /**
+     * Default cache partition included in every key. Set this when multiple
+     * clients pointing at different data sources share one store (e.g. Redis),
+     * so identical queries against different backends never collide.
+     */
+    scope?: string;
+}
+/** Per-call cache controls, passed via `ExecutionContext.cache`. */
+export interface SemanticCacheRuntime {
+    /** Overrides the client-level TTL for this call. */
+    ttlMs?: number;
+    /** Overrides the client-level stale-while-revalidate window for this call. */
+    staleWhileRevalidateMs?: number;
+    /**
+     * `bypass` skips the cache entirely (no read, no write);
+     * `refresh` skips the read but stores the fresh result. Refresh needs a
+     * TTL (per-call or client-level) to store under; when neither is
+     * configured it executes uncached and logs a one-time warning.
+     */
+    mode?: 'bypass' | 'refresh';
+    /**
+     * Cache partition for this call, mixed into the query signature. Required
+     * to cache calls that override the query builder via `runtime.builderFactory`
+     * — without it such calls bypass the cache, because the key alone cannot
+     * tell two data sources apart.
+     */
+    scope?: string;
+}
+/** Cache observability attached to `meta.cache` on cached-path results. */
+export interface SemanticCacheMetaInfo {
+    hit: boolean;
+    /** Milliseconds since the entry was stored; only on hits. */
+    ageMs?: number;
+    /** True when served from the stale-while-revalidate window. */
+    stale?: boolean;
+}
+export declare function createMemoryCacheStore(options?: {
+    maxEntries?: number;
+}): SemanticCacheStore;
+type CacheableResult = {
+    meta?: object;
+};
+export declare class SemanticQueryCache {
+    private readonly store;
+    private readonly defaults;
+    private readonly pending;
+    private readonly refreshing;
+    private warnedRefreshWithoutTtl;
+    constructor(options?: SemanticCacheOptions);
+    private resolveConfig;
+    /**
+     * Runs `execute` through the cache. Errors are never cached; concurrent
+     * identical misses share one execution.
+     */
+    through<T extends CacheableResult>(key: string, execute: () => Promise<T>, runtime?: SemanticCacheRuntime | false): Promise<T>;
+    /** Best-effort write: a failing store degrades to "no caching", never a failed call. */
+    private writeEntry;
+    private refreshInBackground;
+}
+export {};
+//# sourceMappingURL=semantic-query-cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-query-cache.d.ts","sourceRoot":"","sources":["../../src/cache/semantic-query-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAC3F,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,oEAAoE;AACpE,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC5B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,OAAO,CAAC;IACb,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID,wBAAgB,sBAAsB,CACpC,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACpC,kBAAkB,CA+BpB;AAcD,KAAK,eAAe,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAmBzC,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6C;IACrE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,uBAAuB,CAAS;gBAE5B,OAAO,GAAE,oBAAyB;IAK9C,OAAO,CAAC,aAAa;IA8BrB;;;OAGG;IACG,OAAO,CAAC,CAAC,SAAS,eAAe,EACrC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,OAAO,CAAC,EAAE,oBAAoB,GAAG,KAAK,GACrC,OAAO,CAAC,CAAC,CAAC;IAgEb,wFAAwF;YAC1E,UAAU;IAQxB,OAAO,CAAC,mBAAmB;CAc5B"}

package/dist/cache/semantic-query-cache.js

@@ -0,0 +1,184 @@
+/**
+ * Semantic query result cache.
+ *
+ * Sits between `DatasetClient.execute()` and the underlying query builder /
+ * backend, keyed by the canonical query signature (see query-signature.ts).
+ * Supports TTL freshness, an optional stale-while-revalidate window, and
+ * deduplication of concurrent identical lookups so a burst of the same query
+ * executes once — including against async stores, where the in-flight lookup
+ * is registered before the store read. Piggybacked callers inherit the
+ * initiating caller's TTL resolution.
+ *
+ * Values are cloned on write and on read: callers can mutate results freely
+ * without contaminating the cache, and cached hits never alias each other.
+ */
+const DEFAULT_MAX_ENTRIES = 500;
+export function createMemoryCacheStore(options = {}) {
+    const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    const entries = new Map();
+    return {
+        get(key) {
+            const entry = entries.get(key);
+            if (!entry) {
+                return undefined;
+            }
+            // LRU: re-insert on access so iteration order tracks recency.
+            entries.delete(key);
+            entries.set(key, entry);
+            return entry;
+        },
+        set(key, entry) {
+            entries.delete(key);
+            entries.set(key, entry);
+            while (entries.size > maxEntries) {
+                const oldest = entries.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                entries.delete(oldest);
+            }
+        },
+        delete(key) {
+            entries.delete(key);
+        },
+        clear() {
+            entries.clear();
+        },
+    };
+}
+function isPromise(value) {
+    return typeof value?.['then'] === 'function';
+}
+function cloneValue(value) {
+    return structuredClone(value);
+}
+function annotate(result, info) {
+    return {
+        ...result,
+        // Copy `info`: the same outcome is annotated onto every concurrent
+        // caller's result, and results must never alias each other.
+        meta: { ...(result.meta ?? {}), cache: { ...info } },
+    };
+}
+export class SemanticQueryCache {
+    store;
+    defaults;
+    pending = new Map();
+    refreshing = new Set();
+    warnedRefreshWithoutTtl = false;
+    constructor(options = {}) {
+        this.defaults = options;
+        this.store = options.store ?? createMemoryCacheStore({ maxEntries: options.maxEntries });
+    }
+    resolveConfig(runtime) {
+        if (runtime === false) {
+            return undefined;
+        }
+        if (runtime?.mode === 'bypass') {
+            return undefined;
+        }
+        const ttlMs = runtime?.ttlMs ?? this.defaults.ttlMs ?? 0;
+        if (ttlMs <= 0) {
+            // A misconfigured refresh must not fail the request — the fresh result
+            // is still correct — but it should not go undiagnosed either.
+            if (runtime?.mode === 'refresh' && !this.warnedRefreshWithoutTtl) {
+                this.warnedRefreshWithoutTtl = true;
+                console.warn("[hypequery/cache] mode 'refresh' has no TTL to store under; executing uncached. " +
+                    'Pass ttlMs on the call or configure cache.ttlMs on the client.');
+            }
+            return undefined;
+        }
+        return {
+            ttlMs,
+            staleWhileRevalidateMs: runtime?.staleWhileRevalidateMs ?? this.defaults.staleWhileRevalidateMs ?? 0,
+            mode: runtime?.mode === 'refresh' ? 'refresh' : 'read-write',
+        };
+    }
+    /**
+     * Runs `execute` through the cache. Errors are never cached; concurrent
+     * identical misses share one execution.
+     */
+    async through(key, execute, runtime) {
+        const config = this.resolveConfig(runtime);
+        if (!config) {
+            return execute();
+        }
+        if (config.mode === 'refresh') {
+            // Refresh callers asked for an isolated fresh read: never piggyback on
+            // an in-flight miss, just execute and repopulate the entry.
+            const value = await execute();
+            await this.writeEntry(key, value);
+            return annotate(value, { hit: false });
+        }
+        const inFlight = this.pending.get(key);
+        if (inFlight) {
+            // Piggyback on the identical in-flight lookup; clone so concurrent
+            // callers never share a result object. The outcome (hit, staleness) was
+            // resolved with the initiating caller's TTL configuration.
+            const shared = await inFlight;
+            return annotate(cloneValue(shared.value), shared.info);
+        }
+        // The pending registration below happens synchronously, before the store
+        // read inside the IIFE — that is what makes concurrent identical calls
+        // share one execution even with an async store (e.g. Redis), where a
+        // read snapshot taken before our write would otherwise miss and re-run.
+        const promise = (async () => {
+            let entry;
+            try {
+                // Avoid the extra microtask when the store answers synchronously.
+                const read = this.store.get(key);
+                entry = isPromise(read) ? await read : read;
+            }
+            catch {
+                // Read failed; treat it as a miss so a store outage degrades to
+                // "no caching" instead of failing the query.
+            }
+            if (entry) {
+                const ageMs = Date.now() - entry.storedAt;
+                if (ageMs <= config.ttlMs) {
+                    return { value: entry.value, info: { hit: true, ageMs } };
+                }
+                if (ageMs <= config.ttlMs + config.staleWhileRevalidateMs) {
+                    this.refreshInBackground(key, execute);
+                    return { value: entry.value, info: { hit: true, ageMs, stale: true } };
+                }
+            }
+            const value = await execute();
+            await this.writeEntry(key, value);
+            return { value, info: { hit: false } };
+        })();
+        this.pending.set(key, promise);
+        try {
+            const outcome = await promise;
+            // Hits alias the stored entry and must be cloned; a freshly executed
+            // result is owned by this caller.
+            const value = outcome.info.hit ? cloneValue(outcome.value) : outcome.value;
+            return annotate(value, outcome.info);
+        }
+        finally {
+            this.pending.delete(key);
+        }
+    }
+    /** Best-effort write: a failing store degrades to "no caching", never a failed call. */
+    async writeEntry(key, value) {
+        try {
+            await this.store.set(key, { value: cloneValue(value), storedAt: Date.now() });
+        }
+        catch {
+            // Cache write failed; the fresh result is still returned to the caller.
+        }
+    }
+    refreshInBackground(key, execute) {
+        if (this.refreshing.has(key)) {
+            return;
+        }
+        this.refreshing.add(key);
+        void execute()
+            .then((value) => this.writeEntry(key, value))
+            .catch(() => {
+            // Stale entry stays; the next caller past the SWR window re-executes.
+        })
+            .finally(() => {
+            this.refreshing.delete(key);
+        });
+    }
+}

package/dist/contract.d.ts.map

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

package/dist/contract.js

@@ -1,6 +1,7 @@
 import { sha256 } from '@noble/hashes/sha2';
 import { bytesToHex } from '@noble/hashes/utils';
 import { getDatasetCatalogs, } from './catalog.js';
+import { sortedRecord, uniqueSorted } from './utils/canonical-json.js';
 /**
  * Version of the semantic contract format. Bump when the serialized shape
  * changes in a way that snapshot consumers must account for.
@@ -122,22 +123,6 @@ export function contractToStableJson(contract) {
 export function hashContract(contract) {
     return bytesToHex(sha256(contractToStableJson(contract)));
 }
-/**
- * Locale-independent string comparison by UTF-16 code unit. Used everywhere the
- * contract sorts, so the content hash is stable across environments (CI ICU
- * versions, locales) rather than depending on `localeCompare`.
- */
-function compareStrings(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}
-/** Builds an object whose keys are inserted in sorted order for stable JSON. */
-function sortedRecord(entries) {
-    return Object.fromEntries([...entries].sort(([left], [right]) => compareStrings(left, right)));
-}
-/** Deduplicates and sorts a list so logically-equal sets serialize identically. */
-function uniqueSorted(values) {
-    return Array.from(new Set(values)).sort(compareStrings);
-}
 /** Normalizes SQL escape-hatch whitespace so equivalent SQL hashes identically. */
 function normalizeSql(sql) {
     const lines = sql

package/dist/executor.d.ts

@@ -5,19 +5,28 @@
  * stays database-agnostic via query-builder and backend protocol interfaces.
  */
 import type { MetricRef, GrainedMetricRef, MetricQuery, MetricQueryFor, MetricResult, MetricResultFor, DatasetQuery, DatasetQueryFor, DatasetQueryResult, DatasetQueryResultFor, ExecutionContext, AnyDatasetInstance, DatasetInstance } from './types.js';
-import type { QueryBuilderFactoryLike } from './query-builder-protocol.js';
+import type { QueryBuilderFactoryLike, QueryBuilderFactoryInput } from './query-builder-protocol.js';
 import type { PlanNode, SemanticBackend } from './semantic-plan.js';
 import { type ValidationResult } from './validation.js';
 import { type DatasetQueryExecutionOptions } from './dataset-query.js';
+import { type SemanticCacheOptions } from './cache/semantic-query-cache.js';
 export interface MetricQueryEngineOptions {
     /** Query builder factory for executing metrics. */
-    builderFactory: QueryBuilderFactoryLike;
+    builderFactory: QueryBuilderFactoryInput;
 }
 export interface CreateDatasetClientOptions {
     /** Query builder factory for executing semantic metric and dataset queries. */
-    queryBuilder?: QueryBuilderFactoryLike;
+    queryBuilder?: QueryBuilderFactoryInput;
     /** Semantic backend for executing neutral semantic plans. */
     backend?: SemanticBackend;
+    /**
+     * Result-cache defaults for this client. Results are keyed by the canonical
+     * query signature (target, dimensions, measures, filters, ordering,
+     * pagination, grain, and tenant scope). Individual calls can override or
+     * bypass via `ExecutionContext.cache`; per-call `{ cache: { ttlMs } }` works
+     * even when this option is omitted.
+     */
+    cache?: SemanticCacheOptions;
 }
 export type SemanticTarget = MetricRef | GrainedMetricRef | AnyDatasetInstance;
 export type SemanticQuery<TTarget extends SemanticTarget> = TTarget extends AnyDatasetInstance ? DatasetQuery : MetricQuery;
@@ -55,7 +64,22 @@ export declare class MetricQueryEngine {
 }
 export declare class DatasetClientImpl extends MetricQueryEngine implements DatasetClient {
     private backend?;
+    private readonly queryCache;
+    private readonly cacheEnabledByDefault;
+    private readonly defaultCacheScope?;
     constructor(options: CreateDatasetClientOptions);
+    /**
+     * True when this call can hit the cache — either the client has a default
+     * TTL or the call opts in via `context.cache`. Skips signature building for
+     * the common uncached path.
+     */
+    private isCacheable;
+    /**
+     * Context used for cache-key building: fills in the client-level default
+     * `cache.scope` unless the call sets its own, so clients sharing a custom
+     * store can be namespaced apart.
+     */
+    private signatureContext;
     planMetric(metric: MetricRef | GrainedMetricRef, query?: MetricQuery, context?: ExecutionContext): PlanNode;
     planDataset(ds: AnyDatasetInstance, query?: DatasetQuery, context?: ExecutionContext): PlanNode;
     /**

package/dist/executor.d.ts.map

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

package/dist/executor.js

@@ -4,6 +4,7 @@
  * Public callers use `createDatasetClient(...).execute(...)`. The implementation
  * stays database-agnostic via query-builder and backend protocol interfaces.
  */
+import { toQueryBuilderFactory } from './query-builder-protocol.js';
 import { validateSQLIdentifier } from './sql-utils.js';
 import { SUPPORTED_TIME_GRAINS, isSupportedTimeGrain } from './constants.js';
 import { validateFilterValue } from './validation.js';
@@ -14,6 +15,8 @@ import { buildDatasetQueryBuilder, runDatasetQuery, validateDatasetQuery, } from
 import { buildDatasetPlan, buildMetricPlan, } from './semantic-planner.js';
 import { getRuntimeTenantId, getRuntimeTenantPredicate, validateTenantRuntime, } from './utils/tenant-runtime.js';
 import { applyPagination, overfetchLimit } from './utils/pagination.js';
+import { SemanticQueryCache, } from './cache/semantic-query-cache.js';
+import { buildDatasetQuerySignature, buildMetricQuerySignature, } from './cache/query-signature.js';
 function validateQuery(metric, query, context) {
     const errors = [];
     const ref = getMetricRef(metric);
@@ -105,10 +108,15 @@ function validateQuery(metric, query, context) {
 function isDatasetInstance(target) {
     return !!target && typeof target === 'object' && '__type' in target && target.__type === 'dataset';
 }
+/** Resolves the per-call builder override, adapted to the call contract. */
+function resolveBuilderFactory(context, fallback) {
+    const override = context?.runtime?.builderFactory;
+    return override ? toQueryBuilderFactory(override) : fallback;
+}
 export class MetricQueryEngine {
     builderFactory;
     constructor(options) {
-        this.builderFactory = options.builderFactory;
+        this.builderFactory = toQueryBuilderFactory(options.builderFactory);
     }
     getBuilderFactory() {
         return this.builderFactory;
@@ -177,7 +185,7 @@ export class MetricQueryEngine {
         const ref = getMetricRef(metric);
         const grain = getMetricGrain(metric, query);
         const spec = ref.spec;
-        const activeBuilderFactory = context?.runtime?.builderFactory ?? this.builderFactory;
+        const activeBuilderFactory = resolveBuilderFactory(context, this.builderFactory);
         // Over-fetch one row so we can report `hasMore` without a count query.
         const buildQuery = { ...query, limit: overfetchLimit(query.limit) };
         if (spec.__type === 'derived_metric_spec') {
@@ -197,7 +205,7 @@ export class MetricQueryEngine {
         return { data, meta: { sql, timingMs, tenant: getRuntimeTenantId(context), rowCount: data.length, pagination } };
     }
     buildBaseQuery(ref, spec, ds, query, grain, context) {
-        const activeBuilderFactory = context?.runtime?.builderFactory ?? this.builderFactory;
+        const activeBuilderFactory = resolveBuilderFactory(context, this.builderFactory);
         let qb = activeBuilderFactory.table(ds.source);
         const { selectParts, groupByParts } = buildDimensionSelectionPlan(ds, query.dimensions ?? [], grain);
         if (selectParts.length > 0) {
@@ -228,7 +236,7 @@ export class MetricQueryEngine {
         return qb;
     }
     buildDerivedSQLViaBuilder(ref, spec, query, grain, context) {
-        const activeBuilderFactory = context?.runtime?.builderFactory ?? this.builderFactory;
+        const activeBuilderFactory = resolveBuilderFactory(context, this.builderFactory);
         const ds = ref.dataset;
         // Build the CTE inner query using the builder
         let cteBuilder = activeBuilderFactory.table(ds.source);
@@ -308,6 +316,9 @@ export class MetricQueryEngine {
 }
 export class DatasetClientImpl extends MetricQueryEngine {
     backend;
+    queryCache;
+    cacheEnabledByDefault;
+    defaultCacheScope;
     constructor(options) {
         if (!options.queryBuilder && !options.backend) {
             throw new Error('createDatasetClient requires either queryBuilder or backend.');
@@ -323,6 +334,51 @@ export class DatasetClientImpl extends MetricQueryEngine {
             },
         });
         this.backend = options.backend;
+        this.queryCache = new SemanticQueryCache(options.cache);
+        this.cacheEnabledByDefault = (options.cache?.ttlMs ?? 0) > 0;
+        this.defaultCacheScope = options.cache?.scope;
+    }
+    /**
+     * True when this call can hit the cache — either the client has a default
+     * TTL or the call opts in via `context.cache`. Skips signature building for
+     * the common uncached path.
+     */
+    isCacheable(context) {
+        if (context?.cache === false || context?.cache?.mode === 'bypass') {
+            return false;
+        }
+        const builderOverride = context?.runtime?.builderFactory;
+        if (builderOverride &&
+            toQueryBuilderFactory(builderOverride) !== this.getBuilderFactory() &&
+            context.cache?.scope == null) {
+            // A per-call builder override can point at a different data source; the
+            // query signature alone cannot tell them apart, so caching is unsafe
+            // unless the caller partitions entries with an explicit `cache.scope`.
+            // Passing the client's own factory back in is not an override.
+            return false;
+        }
+        if (context?.cache?.mode === 'refresh') {
+            // Always reach the cache: it warns if refresh has no TTL to write under.
+            return true;
+        }
+        if (context?.cache?.ttlMs != null) {
+            return context.cache.ttlMs > 0;
+        }
+        return this.cacheEnabledByDefault;
+    }
+    /**
+     * Context used for cache-key building: fills in the client-level default
+     * `cache.scope` unless the call sets its own, so clients sharing a custom
+     * store can be namespaced apart.
+     */
+    signatureContext(context) {
+        if (this.defaultCacheScope === undefined) {
+            return context;
+        }
+        if (context?.cache === false || context?.cache?.scope != null) {
+            return context;
+        }
+        return { ...context, cache: { ...context?.cache, scope: this.defaultCacheScope } };
     }
     planMetric(metric, query = {}, context) {
         assertMetricHandle(metric);
@@ -354,35 +410,51 @@ export class DatasetClientImpl extends MetricQueryEngine {
         return super.validate(target, query, context);
     }
     executeMetric(metric, query, context) {
-        if (this.backend) {
-            const validation = validateQuery(metric, query, context);
-            if (!validation.valid) {
-                throw new Error(`Invalid metric query: ${validation.errors.join('; ')}`);
+        const run = () => {
+            if (this.backend) {
+                const validation = validateQuery(metric, query, context);
+                if (!validation.valid) {
+                    throw new Error(`Invalid metric query: ${validation.errors.join('; ')}`);
+                }
+                return this.backend.execute(this.planMetric(metric, query, context));
             }
-            return this.backend.execute(this.planMetric(metric, query, context));
+            return this.run(metric, query, context);
+        };
+        if (!this.isCacheable(context)) {
+            return run();
+        }
+        // Validate semantic rules before cache lookup so invalid queries and
+        // missing tenant runtime cannot be served from cache. Avoid this.validate()
+        // here because it dry-builds SQL, which is unnecessary on cache hits and
+        // invalid for backend-only clients.
+        const validation = validateQuery(metric, query, context);
+        if (!validation.valid) {
+            throw new Error(`Invalid metric query: ${validation.errors.join('; ')}`);
         }
-        return this.run(metric, query, context);
+        return this.queryCache.through(buildMetricQuerySignature(metric, query, this.signatureContext(context)), run, context?.cache);
     }
     executeDataset(ds, query, context) {
-        if (this.backend) {
-            const validation = this.validate(ds, query, context);
-            if (!validation.valid) {
-                throw new Error(`Invalid dataset query: ${validation.errors.join('; ')}`);
-            }
-            return this.backend.execute(this.planDataset(ds, query, context));
-        }
         const validation = this.validate(ds, query, context);
         if (!validation.valid) {
             throw new Error(`Invalid dataset query: ${validation.errors.join('; ')}`);
         }
-        return runDatasetQuery(ds, query, {
-            builderFactory: context?.runtime?.builderFactory ?? this.getBuilderFactory(),
-            context,
-        });
+        const run = () => {
+            if (this.backend) {
+                return this.backend.execute(this.planDataset(ds, query, context));
+            }
+            return runDatasetQuery(ds, query, {
+                builderFactory: resolveBuilderFactory(context, this.getBuilderFactory()),
+                context,
+            });
+        };
+        if (!this.isCacheable(context)) {
+            return run();
+        }
+        return this.queryCache.through(buildDatasetQuerySignature(ds, query, this.signatureContext(context)), run, context?.cache);
     }
     toDatasetSQL(ds, query, context) {
         const builder = buildDatasetQueryBuilder(ds, query, {
-            builderFactory: context?.runtime?.builderFactory ?? this.getBuilderFactory(),
+            builderFactory: resolveBuilderFactory(context, this.getBuilderFactory()),
             context,
         });
         return builder.toSQLWithParams().sql;

package/dist/index.d.ts

@@ -14,12 +14,16 @@ export { generateDatasetTools, toOpenAITools, toAISDKTools, toMcpTools, } from '
 export type { AISDKToolDefinition, DatasetToolAnalytics, DatasetToolMode, GenerateDatasetToolsOptions, JsonSchema, McpToolDefinition, OpenAIToolDefinition, SemanticToolDefinition, } from './tools.js';
 export { createDatasetClient } from './executor.js';
 export type { DatasetClient, CreateDatasetClientOptions } from './executor.js';
+export { createMemoryCacheStore } from './cache/semantic-query-cache.js';
+export type { SemanticCacheEntry, SemanticCacheMetaInfo, SemanticCacheOptions, SemanticCacheRuntime, SemanticCacheStore, } from './cache/semantic-query-cache.js';
+export { buildDatasetQuerySignature, buildMetricQuerySignature, } from './cache/query-signature.js';
 export { createInMemoryBackend } from './in-memory-backend.js';
 export type { InMemoryTable, InMemoryTables } from './in-memory-backend.js';
 export type { PlanNode, SemanticBackend, SemanticBackendResult, SemanticExpression, SemanticAggregationPlan, SemanticDimensionPlan, SemanticGrainPlan, } from './semantic-plan.js';
 export type { ValidationResult } from './validation.js';
 export { validateFilterValue, matchesFieldType } from './validation.js';
-export type { QueryBuilderLike, QueryBuilderFactoryLike } from './query-builder-protocol.js';
+export type { QueryBuilderLike, QueryBuilderFactoryLike, QueryBuilderFactoryCompatible, QueryBuilderFactoryInput, } from './query-builder-protocol.js';
+export { toQueryBuilderFactory } from './query-builder-protocol.js';
 export { validateSQLIdentifier, isSafeSQLIdentifier, quoteSQLIdentifier } from './sql-utils.js';
 export { GRAIN_FUNCTIONS, SEMANTIC_FILTER_OPERATORS, SUPPORTED_TIME_GRAINS } from './constants.js';
 export type { FieldType, DimensionType, DimensionOptions, DimensionDefinition, MeasureOptions, MeasureDefinition, InferDimensionType, RelationshipKind, RelationshipDefinition, AggregationType, MeasureAggregation, AggregationSpec, FormulaExpr, DerivedMetricSpec, TimeGrain, MetricRef, BaseMetricRef, DerivedMetricRef, GrainedMetricRef, MetricContract, MetricFilter, MetricOrderBy, MetricQuery, DatasetQuery, MetricResultMeta, MetricResult, DatasetQueryResult, MetricHandle, ExecutionContext, SemanticExecutionRuntime, SemanticTenantRuntime, SemanticFilterDefinition, SemanticFiltersDefinition, DatasetConfig, DatasetLimits, DatasetInstance, AnyDatasetInstance, BaseMetricConfig, DerivedMetricConfig, DatasetRegistryInstance, DatasetFieldNames, DatasetDimensionNames, DatasetMeasureNames, DatasetOrderableNames, DatasetQueryFor, DatasetRow, DatasetRowFor, DatasetQueryResultFor, MetricQueryFor, MetricRow, MetricRowFor, MetricResultFor, KnownStringKeys, } from './types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGhE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAG7E,OAAO,EACL,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAC/B,UAAU,EAAE,QAAQ,EACpB,KAAK,EAAE,KAAK,EAAE,IAAI,GACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EACzB,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAChC,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,KAAK,GACd,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAGtD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACrE,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,YAAY,EACZ,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,gBAAgB,EAChB,gCAAgC,EAChC,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,YAAY,EACZ,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,2BAA2B,EAC3B,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAG/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC5E,YAAY,EACV,QAAQ,EACR,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGxE,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,6BAA6B,EAC7B,wBAAwB,GACzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAGpE,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAGhG,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAGnG,YAAY,EACV,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACxB,yBAAyB,EACzB,aAAa,EACb,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,SAAS,EACT,YAAY,EACZ,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -22,8 +22,12 @@ export { serializeSemanticContract, contractToStableJson, hashContract, SEMANTIC
 export { generateDatasetTools, toOpenAITools, toAISDKTools, toMcpTools, } from './tools.js';
 // Dataset client
 export { createDatasetClient } from './executor.js';
+// Semantic query result cache
+export { createMemoryCacheStore } from './cache/semantic-query-cache.js';
+export { buildDatasetQuerySignature, buildMetricQuerySignature, } from './cache/query-signature.js';
 export { createInMemoryBackend } from './in-memory-backend.js';
 export { validateFilterValue, matchesFieldType } from './validation.js';
+export { toQueryBuilderFactory } from './query-builder-protocol.js';
 // SQL utilities
 export { validateSQLIdentifier, isSafeSQLIdentifier, quoteSQLIdentifier } from './sql-utils.js';
 // Constants

package/dist/query-builder-protocol.d.ts

@@ -33,4 +33,26 @@ export interface QueryBuilderFactoryLike {
     table(name: string): QueryBuilderLike;
     rawQuery<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
 }
+/**
+ * Acceptance shape for query builder factories at public entry points.
+ *
+ * Schema-typed builders (e.g. `createQueryBuilder<Schema>` from
+ * `@hypequery/clickhouse`) narrow column parameters to literal unions, type
+ * `execute()` rows concretely, and overload `where`, so they cannot
+ * structurally satisfy `QueryBuilderFactoryLike` even though they honor its
+ * runtime contract. This looser shape admits both protocol-shaped and
+ * schema-typed builders; entry points adapt with `toQueryBuilderFactory`.
+ */
+export interface QueryBuilderFactoryCompatible {
+    table(name: never): unknown;
+    rawQuery(sql: string, params?: never): Promise<unknown>;
+}
+/** Any query builder factory accepted by public entry points. */
+export type QueryBuilderFactoryInput = QueryBuilderFactoryLike | QueryBuilderFactoryCompatible;
+/**
+ * Adapts an accepted factory to the internal `QueryBuilderFactoryLike` call
+ * contract. Safe because the semantic layer only calls protocol methods with
+ * plain strings, which schema-typed builders handle at runtime.
+ */
+export declare function toQueryBuilderFactory(factory: QueryBuilderFactoryInput): QueryBuilderFactoryLike;
 //# sourceMappingURL=query-builder-protocol.d.ts.map

package/dist/query-builder-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-builder-protocol.d.ts","sourceRoot":"","sources":["../src/query-builder-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,gBAAgB,CAAC;IAGrD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACxD,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAChE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAGtD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC;IAG1E,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,gBAAgB,CAAC;IAGtD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,gBAAgB,CAAC;IACtE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACvC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAGxC,eAAe,IAAI;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAC1D,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACtD;AAED,2EAA2E;AAC3E,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACtF"}
+{"version":3,"file":"query-builder-protocol.d.ts","sourceRoot":"","sources":["../src/query-builder-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,gBAAgB,CAAC;IAGrD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACxD,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAChE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAGtD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC;IAG1E,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,gBAAgB,CAAC;IAGtD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,gBAAgB,CAAC;IACtE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACvC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAGxC,eAAe,IAAI;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAC1D,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACtD;AAED,2EAA2E;AAC3E,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACtF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,6BAA6B;IAC5C,KAAK,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzD;AAED,iEAAiE;AACjE,MAAM,MAAM,wBAAwB,GAChC,uBAAuB,GACvB,6BAA6B,CAAC;AAElC;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,wBAAwB,GAChC,uBAAuB,CAEzB"}

package/dist/query-builder-protocol.js

@@ -8,4 +8,11 @@
  *
  * This keeps @hypequery/serve DB-agnostic while enabling first-class builder usage.
  */
-export {};
+/**
+ * Adapts an accepted factory to the internal `QueryBuilderFactoryLike` call
+ * contract. Safe because the semantic layer only calls protocol methods with
+ * plain strings, which schema-typed builders handle at runtime.
+ */
+export function toQueryBuilderFactory(factory) {
+    return factory;
+}

package/dist/types.d.ts

@@ -1,4 +1,5 @@
-import type { QueryBuilderFactoryLike } from './query-builder-protocol.js';
+import type { QueryBuilderFactoryInput } from './query-builder-protocol.js';
+import type { SemanticCacheMetaInfo, SemanticCacheRuntime } from './cache/semantic-query-cache.js';
 import type { SemanticExpression } from './semantic-plan.js';
 export type FieldType = 'string' | 'number' | 'boolean' | 'timestamp';
 export type DimensionType = FieldType;
@@ -150,6 +151,8 @@ export interface MetricResultMeta {
         offset: number;
         hasMore: boolean;
     };
+    /** Result-cache observability. Present when the call went through the cache. */
+    cache?: SemanticCacheMetaInfo;
 }
 export interface MetricResult<T = Record<string, unknown>> {
     data: T[];
@@ -167,11 +170,16 @@ export type SemanticTenantRuntime = string | {
     scope: 'all';
 };
 export interface SemanticExecutionRuntime {
-    builderFactory?: QueryBuilderFactoryLike;
+    builderFactory?: QueryBuilderFactoryInput;
     tenant?: SemanticTenantRuntime;
 }
 export interface ExecutionContext {
     runtime?: SemanticExecutionRuntime;
+    /**
+     * Per-call result-cache controls. `false` bypasses the cache entirely;
+     * `{ ttlMs }` opts this call into caching (or overrides the client default).
+     */
+    cache?: SemanticCacheRuntime | false;
 }
 export interface SemanticFilterDefinition {
     __type: 'filter_definition';

package/dist/types.d.ts.map

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

package/dist/utils/canonical-json.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Canonical serialization helpers shared by everything that needs stable,
+ * environment-independent output — contract hashing (contract.ts) and
+ * semantic cache keys (cache/query-signature.ts). Keep ordering logic here so
+ * the two paths cannot drift apart.
+ */
+/**
+ * Locale-independent string comparison by UTF-16 code unit. Used everywhere
+ * canonical output sorts, so hashes and cache keys are stable across
+ * environments (CI ICU versions, locales) rather than depending on
+ * `localeCompare`.
+ */
+export declare function compareStrings(left: string, right: string): number;
+/** Builds an object whose keys are inserted in sorted order for stable JSON. */
+export declare function sortedRecord<T>(entries: [string, T][]): Record<string, T>;
+/** Deduplicates and sorts a list so logically-equal sets serialize identically. */
+export declare function uniqueSorted(values: readonly string[]): string[];
+/** JSON.stringify with recursively sorted object keys, so key order never matters. */
+export declare function stableStringify(value: unknown): string;
+//# sourceMappingURL=canonical-json.d.ts.map

package/dist/utils/canonical-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.d.ts","sourceRoot":"","sources":["../../src/utils/canonical-json.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAIzE;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAEhE;AAED,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAwBtD"}

package/dist/utils/canonical-json.js

@@ -0,0 +1,49 @@
+/**
+ * Canonical serialization helpers shared by everything that needs stable,
+ * environment-independent output — contract hashing (contract.ts) and
+ * semantic cache keys (cache/query-signature.ts). Keep ordering logic here so
+ * the two paths cannot drift apart.
+ */
+/**
+ * Locale-independent string comparison by UTF-16 code unit. Used everywhere
+ * canonical output sorts, so hashes and cache keys are stable across
+ * environments (CI ICU versions, locales) rather than depending on
+ * `localeCompare`.
+ */
+export function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/** Builds an object whose keys are inserted in sorted order for stable JSON. */
+export function sortedRecord(entries) {
+    return Object.fromEntries([...entries].sort(([left], [right]) => compareStrings(left, right)));
+}
+/** Deduplicates and sorts a list so logically-equal sets serialize identically. */
+export function uniqueSorted(values) {
+    return Array.from(new Set(values)).sort(compareStrings);
+}
+/** JSON.stringify with recursively sorted object keys, so key order never matters. */
+export function stableStringify(value) {
+    if (typeof value === 'bigint') {
+        // JSON.stringify throws on bigint. The `n` suffix keeps 1n distinct from
+        // both the number 1 and the string "1n" (strings serialize with quotes).
+        return `${value}n`;
+    }
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    const toJSON = value.toJSON;
+    if (typeof toJSON === 'function') {
+        // Match JSON.stringify semantics for Dates and other toJSON carriers.
+        // Without this, every Date serializes to '{}' (no enumerable props) and
+        // distinct date filters collapse onto one cache key.
+        return stableStringify(toJSON.call(value));
+    }
+    const entries = Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .sort(([a], [b]) => compareStrings(a, b))
+        .map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`);
+    return `{${entries.join(',')}}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Semantic layer for defining datasets, metrics, and semantic queries",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",