@hypequery/datasets 0.13.6 → 0.14.0

package/README.md

@@ -56,10 +56,14 @@ const result = await analytics.execute(
   },
   {
     runtime: { tenant: session.accountId },
+    abortSignal: request.signal,
   },
 );
 ```
 
+Passing an `AbortSignal` cancels the semantic query and forwards cancellation to
+the backing query builder/database request.
+
 The same definition can become:
 
 - a named KPI or flexible dataset query;
@@ -68,6 +72,12 @@ The same definition can become:
 - an OpenAI, AI SDK, or MCP tool schema;
 - a stable semantic contract for CI and deployment.
 
+`buildCanonicalSemanticQuerySchemas()` compiles the same catalog into strict
+dataset and metric Zod validators, JSON Schemas, and a deterministic manifest
+hash. It accepts either live local Dataset definitions or an already-normalized
+catalog from a hosted activation, so Serve and MCP do not maintain separate
+field or operator lists.
+
 ## Analytics teams actually need
 
 - sums, counts, distinct counts, averages, min, and max;

package/dist/agent-catalog.d.ts

@@ -0,0 +1,97 @@
+import type { ProtocolDeploymentContract } from '@hypequery/protocol';
+import { type DatasetCatalog, type DatasetCatalogMap, type DatasetCatalogSource } from './catalog.js';
+import type { SemanticContract } from './contract.js';
+import type { DatasetDefaults, DatasetFreshness, DatasetLimits, FieldType, SemanticMetadata } from './types.js';
+export interface AgentCatalogDimension extends SemanticMetadata {
+    name: string;
+    type: FieldType;
+    label?: string;
+    description?: string;
+    filterable: boolean;
+    groupable: boolean;
+}
+export interface AgentCatalogMeasure extends SemanticMetadata {
+    name: string;
+    label?: string;
+    description?: string;
+}
+export interface AgentCatalogMetric extends SemanticMetadata {
+    name: string;
+    label?: string;
+    description?: string;
+    dimensions: string[];
+    filters: string[];
+    grains: string[];
+    grain?: string;
+}
+export interface AgentCatalogFilter extends SemanticMetadata {
+    name: string;
+    type: FieldType;
+    label?: string;
+    description?: string;
+    operators: string[];
+}
+export interface AgentCatalogRelationship {
+    name: string;
+    target: string;
+    fields: string[];
+}
+export interface AgentCatalogDataset extends SemanticMetadata {
+    name: string;
+    description: string;
+    freshness?: DatasetFreshness;
+    owner?: string;
+    defaults?: DatasetDefaults;
+    timeDimension: string | null;
+    dimensions: AgentCatalogDimension[];
+    measures: AgentCatalogMeasure[];
+    metrics: AgentCatalogMetric[];
+    filters: AgentCatalogFilter[];
+    relationships: AgentCatalogRelationship[];
+    limits: DatasetLimits;
+}
+export interface AgentSafeCatalog {
+    datasets: AgentCatalogDataset[];
+}
+export interface AgentCatalogProjectionOptions {
+    /** Maximum UTF-8 bytes in the complete safe catalog. Defaults to 256 KiB. */
+    maxCatalogBytes?: number;
+}
+export declare const DEFAULT_AGENT_CATALOG_MAX_BYTES: number;
+export type AgentCatalogDatasetRegistry = Readonly<Record<string, DatasetCatalogSource | DatasetCatalog>>;
+export type AgentCatalogSource = AgentCatalogDatasetRegistry | SemanticContract | ProtocolDeploymentContract;
+/**
+ * Proof supplied by an owning application after it authorizes a trusted-debug
+ * request. The datasets package deliberately does not manufacture this value:
+ * authentication and authorization belong to the calling transport/runtime.
+ */
+export interface TrustedDebugCatalogAuthorization {
+    readonly authorized: true;
+}
+export type TrustedDebugCatalog = {
+    readonly kind: 'dataset-catalog';
+    readonly datasets: DatasetCatalogMap;
+} | {
+    readonly kind: 'semantic-contract';
+    readonly contract: SemanticContract;
+} | {
+    readonly kind: 'deployment-contract';
+    readonly contract: ProtocolDeploymentContract;
+};
+/** Build the deterministic logical catalog that may safely be shown to an agent. */
+export declare function projectAgentSafeCatalog(source: AgentCatalogSource, options?: AgentCatalogProjectionOptions): AgentSafeCatalog;
+/**
+ * Enforce the agent-safe catalog byte budget.
+ *
+ * Exported so an adapter that builds a projection by another route — the MCP
+ * legacy registry fallback is the only one today — gets the same guarantee as
+ * `projectAgentSafeCatalog` rather than serializing an unbounded catalog and
+ * failing later against an unrelated response limit.
+ */
+export declare function assertAgentSafeCatalogBudget(catalog: AgentSafeCatalog, options?: AgentCatalogProjectionOptions): void;
+/**
+ * Return physical diagnostics only after the owning application has performed
+ * a separate authorization check. Never place this projection in model context.
+ */
+export declare function projectTrustedDebugCatalog(source: AgentCatalogSource, authorization: TrustedDebugCatalogAuthorization): TrustedDebugCatalog;
+//# sourceMappingURL=agent-catalog.d.ts.map

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

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

package/dist/agent-catalog.js

@@ -0,0 +1,79 @@
+import { getDatasetCatalog, } from './catalog.js';
+import { compareStrings } from './utils/canonical-json.js';
+import { protocolDatasetToAgentDataset, recordDatasetToAgentDataset, } from './utils/agent-catalog-projection.js';
+export const DEFAULT_AGENT_CATALOG_MAX_BYTES = 256 * 1024;
+function isProtocolDeploymentContract(source) {
+    return 'kind' in source && source.kind === 'hypequery-deployment';
+}
+function isSemanticContract(source) {
+    return 'contentHash' in source && typeof source.contentHash === 'string';
+}
+/** Build the deterministic logical catalog that may safely be shown to an agent. */
+export function projectAgentSafeCatalog(source, options = {}) {
+    let catalog;
+    if (isProtocolDeploymentContract(source)) {
+        const datasets = new Map(source.datasets.map(dataset => [dataset.name, dataset]));
+        catalog = {
+            datasets: source.datasets
+                .map(dataset => protocolDatasetToAgentDataset(dataset, datasets))
+                .sort((left, right) => compareStrings(left.name, right.name)),
+        };
+    }
+    else if (isSemanticContract(source)) {
+        catalog = {
+            datasets: Object.values(source.datasets)
+                .map(recordDatasetToAgentDataset)
+                .sort((left, right) => compareStrings(left.name, right.name)),
+        };
+    }
+    else {
+        catalog = {
+            datasets: Object.entries(source)
+                .map(([, dataset]) => ('requiresTenant' in dataset ? dataset : getDatasetCatalog(dataset)))
+                .map(recordDatasetToAgentDataset)
+                .sort((left, right) => compareStrings(left.name, right.name)),
+        };
+    }
+    assertAgentSafeCatalogBudget(catalog, options);
+    return catalog;
+}
+/**
+ * Enforce the agent-safe catalog byte budget.
+ *
+ * Exported so an adapter that builds a projection by another route — the MCP
+ * legacy registry fallback is the only one today — gets the same guarantee as
+ * `projectAgentSafeCatalog` rather than serializing an unbounded catalog and
+ * failing later against an unrelated response limit.
+ */
+export function assertAgentSafeCatalogBudget(catalog, options = {}) {
+    const maxBytes = options.maxCatalogBytes ?? DEFAULT_AGENT_CATALOG_MAX_BYTES;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+        throw new RangeError('maxCatalogBytes must be a positive safe integer.');
+    }
+    const byteLength = new TextEncoder().encode(JSON.stringify(catalog)).byteLength;
+    if (byteLength > maxBytes) {
+        throw new RangeError(`Agent-safe catalog exceeds the ${maxBytes}-byte limit.`);
+    }
+}
+/**
+ * Return physical diagnostics only after the owning application has performed
+ * a separate authorization check. Never place this projection in model context.
+ */
+export function projectTrustedDebugCatalog(source, authorization) {
+    if (authorization?.authorized !== true) {
+        throw new Error('Trusted debug catalog access requires explicit authorization.');
+    }
+    if (isProtocolDeploymentContract(source)) {
+        return { kind: 'deployment-contract', contract: source };
+    }
+    if (isSemanticContract(source)) {
+        return { kind: 'semantic-contract', contract: source };
+    }
+    return {
+        kind: 'dataset-catalog',
+        datasets: Object.fromEntries(Object.entries(source).map(([name, dataset]) => [
+            name,
+            'requiresTenant' in dataset ? dataset : getDatasetCatalog(dataset),
+        ])),
+    };
+}

package/dist/api.type-test.js

@@ -1,4 +1,4 @@
-import { add, dataset, dimension, measure, eq, between, desc, createDatasetClient } from './index.js';
+import { add, between, buildCanonicalSemanticQuerySchemas, createDatasetClient, dataset, desc, dimension, eq, measure, publishDatasets, } from './index.js';
 const Orders = dataset('orders', {
     source: 'orders',
     tenantKey: 'tenant_id',
@@ -34,6 +34,20 @@ const averageRevenueMetric = Orders.metric('averageRevenueMetric', {
     formula: ({ revenue, completedRevenue }) => add(revenue, completedRevenue),
 });
 const customerCountMetric = Customers.metric('customerCountMetric', { measure: 'customerCount' });
+const _publishedDatasets = publishDatasets()
+    .publish(Orders, { metrics: { revenue: revenueMetric } })
+    .publish(Customers, {
+    alias: 'accounts',
+    metrics: { customers: customerCountMetric },
+})
+    .build();
+// @ts-expect-error published metrics must belong to the dataset being published.
+publishDatasets().publish(Orders, { metrics: { customerCountMetric } });
+const canonicalSchemas = buildCanonicalSemanticQuerySchemas({
+    orders: { ...Orders, metrics: { revenueMetric } },
+});
+canonicalSchemas.queryDataset.parse({ dataset: 'orders', measures: ['revenue'] });
+const _manifestHash = canonicalSchemas.manifestHash;
 const _statusFilter = eq('status', 'completed');
 const _createdAtRange = between('createdAt', '2025-01-01', '2025-01-31');
 const _revenueSort = desc('revenueMetric');
@@ -56,6 +70,10 @@ const runtimeContext = {
         tenant: 'tenant-1',
     },
 };
+const abortableContext = {
+    abortSignal: new AbortController().signal,
+};
+void abortableContext;
 const _legacyTenantRuntimeContext = {
     runtime: {
         tenant: { id: 'tenant-1' },

package/dist/catalog.d.ts

@@ -1,5 +1,5 @@
-import type { AnyDatasetInstance, DimensionDefinition, MeasureDefinition, MetricHandle, RelationshipDefinition, SemanticFilterDefinition, DatasetLimits, TimeGrain } from './types.js';
-export interface DimensionCatalogEntry {
+import type { AnyDatasetInstance, DimensionDefinition, MeasureDefinition, MetricHandle, RelationshipDefinition, SemanticFilterDefinition, DatasetLimits, DatasetDefaults, DatasetFreshness, SemanticMetadata, TimeGrain } from './types.js';
+export interface DimensionCatalogEntry extends SemanticMetadata {
     type: DimensionDefinition['fieldType'];
     column?: string;
     sql?: string;
@@ -8,7 +8,7 @@ export interface DimensionCatalogEntry {
     filterable: boolean;
     groupable: boolean;
 }
-export interface MeasureCatalogEntry {
+export interface MeasureCatalogEntry extends SemanticMetadata {
     aggregation: MeasureDefinition['aggregation'];
     field: string;
     /** Second column for argMax/argMin. */
@@ -20,14 +20,14 @@ export interface MeasureCatalogEntry {
     description?: string;
     filterCount: number;
 }
-export interface FilterCatalogEntry {
+export interface FilterCatalogEntry extends SemanticMetadata {
     field: string;
     label?: string;
     description?: string;
     operators: SemanticFilterDefinition['operators'];
     valueType?: DimensionDefinition['fieldType'];
 }
-export interface MetricCatalogEntry {
+export interface MetricCatalogEntry extends SemanticMetadata {
     kind: ReturnType<MetricHandle['contract']>['kind'];
     dataset: string;
     valueType: 'number';
@@ -47,10 +47,19 @@ export interface RelationshipCatalogEntry {
     to: string;
     queryable: boolean;
     fields: string[];
+    /**
+     * Subset of `fields` usable as a grouping key. Optional so an externally
+     * supplied catalog that predates it still resolves, falling back to `fields`.
+     */
+    groupableFields?: string[];
 }
-export interface DatasetCatalog {
+export interface DatasetCatalog extends SemanticMetadata {
     name: string;
+    description?: string;
     source: string;
+    freshness?: DatasetFreshness;
+    owner?: string;
+    defaults?: DatasetDefaults;
     tenantKey?: string;
     timeKey?: string;
     dimensions: Record<string, DimensionCatalogEntry>;
@@ -70,6 +79,8 @@ export type DatasetCatalogSource = AnyDatasetInstance & {
 };
 /** All queryable relationship field names (`<relationship>.<dimension>`) a catalog advertises. */
 export declare function getQueryableRelationshipFields(catalog: DatasetCatalog): string[];
+/** The queryable relationship fields a catalog also allows as grouping keys. */
+export declare function getGroupableRelationshipFields(catalog: DatasetCatalog): string[];
 export declare function getDatasetCatalog(dataset: DatasetCatalogSource): DatasetCatalog;
 export declare function getDatasetCatalogs(datasets: Record<string, DatasetCatalogSource>): DatasetCatalogMap;
 //# sourceMappingURL=catalog.d.ts.map

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

package/dist/catalog.js

@@ -1,5 +1,6 @@
 import { SEMANTIC_FILTER_OPERATORS, SUPPORTED_TIME_GRAINS } from './constants.js';
-import { listQueryableRelationshipFields } from './utils/relationship-fields.js';
+import { listGroupableRelationshipFields, listQueryableRelationshipFields, } from './utils/relationship-fields.js';
+import { snapshotSemanticMetadata } from './utils/semantic-metadata.js';
 function dimensionToCatalog(dimension) {
     return {
         type: dimension.fieldType,
@@ -7,6 +8,7 @@ function dimensionToCatalog(dimension) {
         sql: dimension.sql,
         label: dimension.label,
         description: dimension.description,
+        ...snapshotSemanticMetadata(dimension),
         filterable: dimension.filterable !== false,
         groupable: dimension.groupable !== false,
     };
@@ -20,6 +22,7 @@ function measureToCatalog(measure) {
         sql: measure.sql,
         label: measure.label,
         description: measure.description,
+        ...snapshotSemanticMetadata(measure),
         filterCount: measure.filters?.length ?? 0,
     };
 }
@@ -28,6 +31,7 @@ function filterToCatalog(filter, dimensions) {
         field: filter.field,
         label: filter.label,
         description: filter.description,
+        ...snapshotSemanticMetadata(filter),
         operators: filter.operators ? [...filter.operators] : [...SEMANTIC_FILTER_OPERATORS],
         valueType: dimensions[filter.field]?.fieldType,
     };
@@ -40,6 +44,7 @@ function metricToCatalog(metric) {
         valueType: contract.valueType,
         label: contract.label,
         description: contract.description,
+        ...snapshotSemanticMetadata(contract),
         dimensions: contract.dimensions,
         measures: contract.measures,
         filters: contract.filters,
@@ -56,6 +61,7 @@ function relationshipToCatalog(name, relationship) {
         to: relationship.to,
         queryable: relationship.kind !== 'hasMany',
         fields: listQueryableRelationshipFields(name, relationship),
+        groupableFields: listGroupableRelationshipFields(name, relationship),
     };
 }
 /** All queryable relationship field names (`<relationship>.<dimension>`) a catalog advertises. */
@@ -64,6 +70,12 @@ export function getQueryableRelationshipFields(catalog) {
         .filter(relationship => relationship.queryable)
         .flatMap(relationship => relationship.fields);
 }
+/** The queryable relationship fields a catalog also allows as grouping keys. */
+export function getGroupableRelationshipFields(catalog) {
+    return Object.values(catalog.relationships)
+        .filter(relationship => relationship.queryable)
+        .flatMap(relationship => relationship.groupableFields ?? relationship.fields);
+}
 export function getDatasetCatalog(dataset) {
     const dimensionNames = Object.keys(dataset.dimensions);
     const measureNames = Object.keys(dataset.measures);
@@ -76,7 +88,12 @@ export function getDatasetCatalog(dataset) {
     ]));
     return {
         name: dataset.name,
+        description: dataset.description,
+        ...snapshotSemanticMetadata(dataset),
         source: dataset.source,
+        freshness: dataset.freshness,
+        owner: dataset.owner,
+        defaults: dataset.defaults,
         tenantKey: dataset.tenantKey,
         timeKey: dataset.timeKey,
         dimensions: Object.fromEntries(Object.entries(dataset.dimensions).map(([name, dimension]) => [

package/dist/contract.d.ts

@@ -1,11 +1,11 @@
 import { type DatasetCatalogSource, type DimensionCatalogEntry, type MeasureCatalogEntry, type MetricCatalogEntry, type FilterCatalogEntry, type RelationshipCatalogEntry } from './catalog.js';
-import type { DatasetLimits } from './types.js';
+import type { DatasetDefaults, DatasetFreshness, DatasetLimits, SemanticMetadata } from './types.js';
 /**
  * Version of the semantic contract format. Bump when the serialized shape
  * changes in a way that snapshot consumers must account for.
  */
-export declare const SEMANTIC_CONTRACT_VERSION = 2;
-export interface ContractDimension {
+export declare const SEMANTIC_CONTRACT_VERSION = 3;
+export interface ContractDimension extends SemanticMetadata {
     type: DimensionCatalogEntry['type'];
     column?: string;
     sql?: string;
@@ -14,7 +14,7 @@ export interface ContractDimension {
     filterable: boolean;
     groupable: boolean;
 }
-export interface ContractMeasure {
+export interface ContractMeasure extends SemanticMetadata {
     aggregation: MeasureCatalogEntry['aggregation'];
     field: string;
     /** Second column for argMax/argMin. */
@@ -25,7 +25,7 @@ export interface ContractMeasure {
     label?: string;
     description?: string;
 }
-export interface ContractMetric {
+export interface ContractMetric extends SemanticMetadata {
     kind: MetricCatalogEntry['kind'];
     valueType: MetricCatalogEntry['valueType'];
     label?: string;
@@ -37,7 +37,7 @@ export interface ContractMetric {
     grain?: string;
     requires?: string[];
 }
-export interface ContractFilter {
+export interface ContractFilter extends SemanticMetadata {
     field: string;
     label?: string;
     description?: string;
@@ -52,9 +52,13 @@ export interface ContractRelationship {
     queryable: boolean;
     fields: string[];
 }
-export interface ContractDataset {
+export interface ContractDataset extends SemanticMetadata {
     name: string;
+    description?: string;
     source: string;
+    freshness?: DatasetFreshness;
+    owner?: string;
+    defaults?: DatasetDefaults;
     tenantKey?: string;
     timeKey?: string;
     requiresTenant: boolean;

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

@@ -2,11 +2,12 @@ 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';
+import { snapshotSemanticMetadata } from './utils/semantic-metadata.js';
 /**
  * Version of the semantic contract format. Bump when the serialized shape
  * changes in a way that snapshot consumers must account for.
  */
-export const SEMANTIC_CONTRACT_VERSION = 2;
+export const SEMANTIC_CONTRACT_VERSION = 3;
 /**
  * Builds a deterministic semantic contract from dataset instances.
  *
@@ -31,7 +32,23 @@ export function serializeSemanticContract(datasets, options = {}) {
 function datasetToContract(catalog, includeSql) {
     return {
         name: catalog.name,
+        ...(catalog.description !== undefined ? { description: catalog.description } : {}),
+        ...snapshotSemanticMetadata(catalog),
         source: catalog.source,
+        ...(catalog.freshness !== undefined ? { freshness: { ...catalog.freshness } } : {}),
+        ...(catalog.owner !== undefined ? { owner: catalog.owner } : {}),
+        ...(catalog.defaults !== undefined
+            ? {
+                defaults: {
+                    ...(catalog.defaults.dimensions !== undefined
+                        ? { dimensions: uniqueSorted(catalog.defaults.dimensions) }
+                        : {}),
+                    ...(catalog.defaults.timeGrain !== undefined
+                        ? { timeGrain: catalog.defaults.timeGrain }
+                        : {}),
+                },
+            }
+            : {}),
         ...(catalog.tenantKey !== undefined ? { tenantKey: catalog.tenantKey } : {}),
         ...(catalog.timeKey !== undefined ? { timeKey: catalog.timeKey } : {}),
         requiresTenant: catalog.requiresTenant,
@@ -64,6 +81,7 @@ function dimensionToContract(entry, includeSql) {
         ...(includeSql && entry.sql !== undefined ? { sql: normalizeSql(entry.sql) } : {}),
         ...(entry.label !== undefined ? { label: entry.label } : {}),
         ...(entry.description !== undefined ? { description: entry.description } : {}),
+        ...snapshotSemanticMetadata(entry),
         filterable: entry.filterable,
         groupable: entry.groupable,
     };
@@ -77,6 +95,7 @@ function measureToContract(entry, includeSql) {
         ...(includeSql && entry.sql !== undefined ? { sql: normalizeSql(entry.sql) } : {}),
         ...(entry.label !== undefined ? { label: entry.label } : {}),
         ...(entry.description !== undefined ? { description: entry.description } : {}),
+        ...snapshotSemanticMetadata(entry),
     };
 }
 function metricToContract(entry) {
@@ -85,6 +104,7 @@ function metricToContract(entry) {
         valueType: entry.valueType,
         ...(entry.label !== undefined ? { label: entry.label } : {}),
         ...(entry.description !== undefined ? { description: entry.description } : {}),
+        ...snapshotSemanticMetadata(entry),
         dimensions: uniqueSorted(entry.dimensions),
         ...(entry.measures !== undefined ? { measures: uniqueSorted(entry.measures) } : {}),
         filters: uniqueSorted(entry.filters),
@@ -98,6 +118,7 @@ function filterToContract(entry) {
         field: entry.field,
         ...(entry.label !== undefined ? { label: entry.label } : {}),
         ...(entry.description !== undefined ? { description: entry.description } : {}),
+        ...snapshotSemanticMetadata(entry),
         operators: uniqueSorted(entry.operators ?? []),
         ...(entry.valueType !== undefined ? { valueType: entry.valueType } : {}),
     };

package/dist/dataset-query.js

@@ -51,7 +51,7 @@ export async function runDatasetQuery(ds, query, options) {
         ...options,
         executionLimit: overfetchLimit(query.limit),
     });
-    const rows = await qb.execute();
+    const rows = await qb.execute({ abortSignal: options.context?.abortSignal });
     const { data, pagination } = applyPagination(rows, query.limit, query.offset);
     const serializedData = serializeSemanticMeasureValues(data, query.measures ?? Object.keys(ds.measures));
     return {

package/dist/dataset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../src/dataset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EAKvB,MAAM,YAAY,CAAC;AAkBpB,wBAAgB,OAAO,CACrB,YAAY,SAAS,MAAM,EAC3B,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC3E,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAErF,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAC5D,eAAe,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,YAAY,CAAC,CA2DvE"}
+{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../src/dataset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EAKvB,MAAM,YAAY,CAAC;AAqBpB,wBAAgB,OAAO,CACrB,YAAY,SAAS,MAAM,EAC3B,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC3E,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAErF,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAC5D,eAAe,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,YAAY,CAAC,CA2EvE"}

package/dist/dataset.js

@@ -32,16 +32,24 @@
 import { createDerivedMetricSpec, createMetricRef, isDerivedMetricConfig, } from './utils/dataset-metric-ref.js';
 import { measureToAggregationSpec, normalizeDimensions, normalizeFilters, normalizeMeasures, normalizeRelationships, } from './utils/dataset-normalization.js';
 import { validateBaseMetric, validateDerivedMetric, } from './utils/dataset-validation.js';
+import { validateDatasetDefinition } from './utils/dataset-definition-validation.js';
+import { snapshotSemanticMetadata } from './utils/semantic-metadata.js';
+import { validateSemanticMetadata } from './utils/semantic-metadata-validation.js';
 export function dataset(name, config) {
+    // Structural validation runs before anything is normalized, so an invalid
+    // model fails at definition time rather than on the first query that reaches
+    // the broken part of it.
+    validateDatasetDefinition(name, config);
     const dimensions = normalizeDimensions(config);
     const measures = normalizeMeasures(config.measures);
     const filters = normalizeFilters(dimensions, config.filters);
     const relationships = normalizeRelationships(config.relationships, config.source);
     function metric(metricName, metricConfig) {
+        validateSemanticMetadata(ds.name, `metrics.${metricName}`, metricConfig);
         if (isDerivedMetricConfig(metricConfig)) {
             validateDerivedMetric(ds, metricName, metricConfig);
             const derivedSpec = createDerivedMetricSpec(metricConfig);
-            return createMetricRef(ds, metricName, derivedSpec, metricConfig.label, metricConfig.description);
+            return createMetricRef(ds, metricName, derivedSpec, metricConfig.label, metricConfig.description, metricConfig);
         }
         const measureName = metricConfig.measure;
         const measure = ds.measures[measureName];
@@ -50,12 +58,20 @@ export function dataset(name, config) {
         }
         const spec = measureToAggregationSpec(measureName, measure);
         validateBaseMetric(ds, metricName, spec, { allowHiddenField: true });
-        return createMetricRef(ds, metricName, spec, metricConfig.label ?? measure.label, metricConfig.description ?? measure.description);
+        return createMetricRef(ds, metricName, spec, metricConfig.label ?? measure.label, metricConfig.description ?? measure.description, { ...measure, ...metricConfig });
     }
     const ds = {
         __type: 'dataset',
         name,
         source: config.source,
+        description: config.description,
+        ...snapshotSemanticMetadata(config),
+        freshness: config.freshness === undefined ? undefined : { ...config.freshness },
+        owner: config.owner,
+        defaults: config.defaults === undefined ? undefined : {
+            ...config.defaults,
+            ...(config.defaults.dimensions === undefined ? {} : { dimensions: [...config.defaults.dimensions] }),
+        },
         tenantKey: config.tenantKey,
         timeKey: config.timeKey,
         dimensions,
@@ -63,6 +79,7 @@ export function dataset(name, config) {
         filters,
         relationships,
         limits: config.limits,
+        cache: config.cache,
         metric,
     };
     return ds;

package/dist/executor.d.ts

@@ -79,6 +79,7 @@ export declare class DatasetClientImpl extends MetricQueryEngine implements Data
     private backend?;
     private readonly queryCache;
     private readonly cacheEnabledByDefault;
+    private readonly cacheDefaults;
     private readonly defaultCacheScope?;
     constructor(options: CreateDatasetClientOptions);
     getCacheStats(): SemanticCacheStats;
@@ -107,6 +108,11 @@ export declare class DatasetClientImpl extends MetricQueryEngine implements Data
     validate<TTarget extends SemanticTarget>(target: TTarget, query?: SemanticQuery<TTarget>, context?: ExecutionContext): ValidationResult;
     private executeMetric;
     private executeDataset;
+    /**
+     * Folds the dataset's declared cache policy into the call's context, so both
+     * the cacheability decision and the lookup see the same resolved TTL.
+     */
+    private datasetCacheContext;
     private toDatasetSQL;
 }
 export declare function createDatasetClient(options: CreateDatasetClientOptions): DatasetClient;