@hypequery/datasets 0.13.6 → 0.14.0

package/dist/utils/agent-catalog-projection.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Per-source projections behind `projectAgentSafeCatalog()`.
+ *
+ * Each function maps one dataset representation onto the logical shape an agent
+ * may see. They all apply the same rules — drop dimensions that are neither
+ * filterable nor groupable, keep only filters whose field survived that drop,
+ * keep only metric references that resolve, snapshot semantic metadata, and
+ * sort every collection by name — so the projection is deterministic regardless
+ * of which source produced it.
+ */
+import type { ProtocolDatasetContract } from '@hypequery/protocol';
+import type { AgentCatalogDataset } from '../agent-catalog.js';
+import type { DatasetDefaults, DatasetFreshness, DatasetLimits, FieldType, SemanticMetadata } from '../types.js';
+/**
+ * The structural shape shared by `DatasetCatalog` and `ContractDataset`.
+ *
+ * Both carry their collections as name-keyed records with the same entry
+ * fields, so one projection covers the local-catalog and semantic-contract
+ * sources. Only what the projection reads is declared here.
+ */
+export interface RecordShapedDataset extends SemanticMetadata {
+    readonly name: string;
+    readonly description?: string;
+    readonly freshness?: DatasetFreshness;
+    readonly owner?: string;
+    readonly defaults?: DatasetDefaults;
+    readonly timeKey?: string;
+    readonly dimensions: Readonly<Record<string, SemanticMetadata & {
+        readonly type: FieldType;
+        readonly label?: string;
+        readonly description?: string;
+        readonly filterable: boolean;
+        readonly groupable: boolean;
+    }>>;
+    readonly measures: Readonly<Record<string, SemanticMetadata & {
+        readonly label?: string;
+        readonly description?: string;
+    }>>;
+    readonly metrics: Readonly<Record<string, SemanticMetadata & {
+        readonly label?: string;
+        readonly description?: string;
+        readonly dimensions: readonly string[];
+        readonly filters: readonly string[];
+        readonly grains: readonly string[];
+        readonly grain?: string;
+    }>>;
+    readonly filters: Readonly<Record<string, SemanticMetadata & {
+        readonly field: string;
+        readonly label?: string;
+        readonly description?: string;
+        readonly operators?: readonly string[];
+        readonly valueType?: FieldType;
+    }>>;
+    readonly relationships: Readonly<Record<string, {
+        readonly target: string;
+        readonly queryable: boolean;
+        readonly fields: readonly string[];
+    }>>;
+    readonly limits?: DatasetLimits;
+}
+export declare function optionalText<T extends {
+    label?: string;
+    description?: string;
+}>(value: T): Pick<T, 'label' | 'description'>;
+/** Reduces a limits object to the four keys the agent-safe catalog publishes. */
+export declare function normalizedLimits(limits: DatasetLimits | undefined): DatasetLimits;
+export declare function datasetDescription(name: string, description?: string): string;
+/** Projects a `DatasetCatalog` or `ContractDataset` — they share one shape. */
+export declare function recordDatasetToAgentDataset(dataset: RecordShapedDataset): AgentCatalogDataset;
+/**
+ * Projects a portable deployment contract dataset.
+ *
+ * Kept separate from `recordDatasetToAgentDataset`: the contract carries its
+ * collections as arrays of named entries, and relationship fields are not
+ * stored — they are derived from the target dataset's publishable dimensions.
+ */
+export declare function protocolDatasetToAgentDataset(dataset: ProtocolDatasetContract, datasets: ReadonlyMap<string, ProtocolDatasetContract>): AgentCatalogDataset;
+//# sourceMappingURL=agent-catalog-projection.d.ts.map

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

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

package/dist/utils/agent-catalog-projection.js

@@ -0,0 +1,179 @@
+/**
+ * Per-source projections behind `projectAgentSafeCatalog()`.
+ *
+ * Each function maps one dataset representation onto the logical shape an agent
+ * may see. They all apply the same rules — drop dimensions that are neither
+ * filterable nor groupable, keep only filters whose field survived that drop,
+ * keep only metric references that resolve, snapshot semantic metadata, and
+ * sort every collection by name — so the projection is deterministic regardless
+ * of which source produced it.
+ */
+import { compareStrings, uniqueSorted } from './canonical-json.js';
+import { snapshotSemanticMetadata } from './semantic-metadata.js';
+export function optionalText(value) {
+    return {
+        ...(value.label !== undefined ? { label: value.label } : {}),
+        ...(value.description !== undefined ? { description: value.description } : {}),
+    };
+}
+/** Reduces a limits object to the four keys the agent-safe catalog publishes. */
+export function normalizedLimits(limits) {
+    return {
+        ...(limits?.maxDimensions !== undefined ? { maxDimensions: limits.maxDimensions } : {}),
+        ...(limits?.maxMeasures !== undefined ? { maxMeasures: limits.maxMeasures } : {}),
+        ...(limits?.maxFilters !== undefined ? { maxFilters: limits.maxFilters } : {}),
+        ...(limits?.maxResultSize !== undefined ? { maxResultSize: limits.maxResultSize } : {}),
+    };
+}
+export function datasetDescription(name, description) {
+    return description ?? `${name} analytics dataset.`;
+}
+function snapshotDefaults(defaults) {
+    return {
+        ...(defaults.dimensions !== undefined
+            ? { dimensions: uniqueSorted(defaults.dimensions) }
+            : {}),
+        ...(defaults.timeGrain !== undefined ? { timeGrain: defaults.timeGrain } : {}),
+    };
+}
+/** The dataset-level metadata every source projects the same way. */
+function datasetMetadata(dataset) {
+    return {
+        ...snapshotSemanticMetadata(dataset),
+        ...(dataset.freshness !== undefined ? { freshness: { ...dataset.freshness } } : {}),
+        ...(dataset.owner !== undefined ? { owner: dataset.owner } : {}),
+        ...(dataset.defaults !== undefined ? { defaults: snapshotDefaults(dataset.defaults) } : {}),
+    };
+}
+function sortedByName(items) {
+    return items.sort((left, right) => compareStrings(left.name, right.name));
+}
+/** Projects a `DatasetCatalog` or `ContractDataset` — they share one shape. */
+export function recordDatasetToAgentDataset(dataset) {
+    const dimensions = sortedByName(Object.entries(dataset.dimensions)
+        .filter(([, dimension]) => dimension.filterable || dimension.groupable)
+        .map(([name, dimension]) => ({
+        name,
+        type: dimension.type,
+        ...optionalText(dimension),
+        ...snapshotSemanticMetadata(dimension),
+        filterable: dimension.filterable,
+        groupable: dimension.groupable,
+    })));
+    const dimensionNames = new Set(dimensions.map(dimension => dimension.name));
+    // A filter is only publishable when its backing dimension survived above;
+    // otherwise it would name a field the agent cannot see or select.
+    const filterNames = new Set(Object.entries(dataset.filters)
+        .filter(([, filter]) => filter.valueType !== undefined && dimensionNames.has(filter.field))
+        .map(([name]) => name));
+    return {
+        name: dataset.name,
+        description: datasetDescription(dataset.name, dataset.description),
+        ...datasetMetadata(dataset),
+        timeDimension: dataset.timeKey !== undefined && dimensionNames.has(dataset.timeKey)
+            ? dataset.timeKey
+            : null,
+        dimensions,
+        measures: sortedByName(Object.entries(dataset.measures).map(([name, measure]) => ({
+            name,
+            ...optionalText(measure),
+            ...snapshotSemanticMetadata(measure),
+        }))),
+        metrics: sortedByName(Object.entries(dataset.metrics).map(([name, metric]) => ({
+            name,
+            ...optionalText(metric),
+            ...snapshotSemanticMetadata(metric),
+            dimensions: uniqueSorted(metric.dimensions.filter(item => dimensionNames.has(item))),
+            filters: uniqueSorted(metric.filters.filter(item => filterNames.has(item))),
+            grains: uniqueSorted(metric.grains),
+            ...(metric.grain !== undefined ? { grain: metric.grain } : {}),
+        }))),
+        filters: sortedByName(Object.entries(dataset.filters)
+            .filter(([name]) => filterNames.has(name))
+            .map(([name, filter]) => ({
+            name,
+            type: filter.valueType,
+            ...optionalText(filter),
+            ...snapshotSemanticMetadata(filter),
+            operators: uniqueSorted(filter.operators ?? []),
+        }))),
+        relationships: sortedByName(Object.entries(dataset.relationships)
+            .filter(([, relationship]) => relationship.queryable)
+            .map(([name, relationship]) => ({
+            name,
+            target: relationship.target,
+            fields: uniqueSorted(relationship.fields),
+        }))),
+        limits: normalizedLimits(dataset.limits),
+    };
+}
+/**
+ * Projects a portable deployment contract dataset.
+ *
+ * Kept separate from `recordDatasetToAgentDataset`: the contract carries its
+ * collections as arrays of named entries, and relationship fields are not
+ * stored — they are derived from the target dataset's publishable dimensions.
+ */
+export function protocolDatasetToAgentDataset(dataset, datasets) {
+    const dimensions = sortedByName(dataset.dimensions
+        .filter(dimension => dimension.filterable || dimension.groupable)
+        .map(dimension => ({
+        name: dimension.name,
+        type: dimension.type,
+        ...optionalText(dimension),
+        ...snapshotSemanticMetadata(dimension),
+        filterable: dimension.filterable,
+        groupable: dimension.groupable,
+    })));
+    const dimensionNames = new Set(dimensions.map(dimension => dimension.name));
+    const dimensionTypes = new Map(dataset.dimensions.map(dimension => [dimension.name, dimension.type]));
+    const filterNames = new Set(dataset.filters
+        .filter(filter => dimensionNames.has(String(filter.field)))
+        .map(filter => String(filter.name)));
+    return {
+        name: dataset.name,
+        description: datasetDescription(dataset.name, dataset.description),
+        ...datasetMetadata(dataset),
+        timeDimension: dataset.timeField !== undefined && dimensionNames.has(String(dataset.timeField))
+            ? String(dataset.timeField)
+            : null,
+        dimensions,
+        measures: sortedByName(dataset.measures.map(measure => ({
+            name: measure.name,
+            ...optionalText(measure),
+            ...snapshotSemanticMetadata(measure),
+        }))),
+        metrics: sortedByName(dataset.metrics.map(metric => ({
+            name: metric.name,
+            ...optionalText(metric),
+            ...snapshotSemanticMetadata(metric),
+            dimensions: uniqueSorted(metric.dimensions.filter(name => dimensionNames.has(String(name)))),
+            filters: uniqueSorted(metric.filters.filter(name => filterNames.has(String(name)))),
+            grains: uniqueSorted(metric.grains),
+            ...(metric.grain !== undefined ? { grain: metric.grain } : {}),
+        }))),
+        filters: sortedByName(dataset.filters
+            .filter(filter => filterNames.has(String(filter.name)))
+            .map((filter) => {
+            const type = dimensionTypes.get(String(filter.field));
+            return type === undefined ? undefined : {
+                name: filter.name,
+                type,
+                ...optionalText(filter),
+                ...snapshotSemanticMetadata(filter),
+                operators: uniqueSorted(filter.operators),
+            };
+        })
+            .filter((filter) => filter !== undefined)),
+        relationships: sortedByName(dataset.relationships
+            .filter(relationship => relationship.queryable)
+            .map(relationship => ({
+            name: relationship.name,
+            target: relationship.target,
+            fields: uniqueSorted((datasets.get(relationship.target)?.dimensions ?? [])
+                .filter(dimension => dimension.filterable || dimension.groupable)
+                .map(dimension => `${relationship.name}.${dimension.name}`)),
+        }))),
+        limits: normalizedLimits(dataset.limits),
+    };
+}

package/dist/utils/dataset-cache-policy.d.ts

@@ -0,0 +1,34 @@
+import type { DatasetCachePolicy, ExecutionContext } from '../types.js';
+import type { SemanticCacheOptions } from '../cache/semantic-query-cache.js';
+/**
+ * Client-level cache defaults, as the resolver needs to see them.
+ *
+ * They have to be resolved here rather than left to the cache: the cache fills a
+ * missing `ttlMs` from its own defaults *after* this runs, so a value left
+ * undefined here would be filled in unclamped and escape the dataset's ceiling
+ * entirely.
+ */
+export type ClientCacheDefaults = Pick<SemanticCacheOptions, 'ttlMs' | 'staleWhileRevalidateMs'>;
+/**
+ * Folds a dataset's declared cache policy into one call's cache runtime.
+ *
+ * Precedence mirrors `resolveCompiledDeadline` in `@hypequery/clickhouse`: the
+ * call site may shorten the window but never extend it. A declared `ttlMs`
+ * supplies the default when neither the call nor the client does; a declared
+ * `maxTtlMs` clamps whatever any of the three asked for.
+ *
+ * **`maxTtlMs` is a ceiling, not a default.** When no layer supplies a TTL, the
+ * result stays uncached — a maximum lifetime is not a reason to start caching
+ * something nobody asked to cache.
+ *
+ * **The ceiling bounds total age, not each window separately.** A cached entry
+ * is servable for `ttlMs + staleWhileRevalidateMs`, so clamping the two
+ * independently would allow twice the declared maximum. The stale window gets
+ * whatever the TTL leaves of the budget.
+ *
+ * A caller that opted out (`cache: false`, `mode: 'bypass'`) stays opted out.
+ * Opting out is a shortening, and a dataset policy is not a way to force a
+ * result into a cache the caller declined.
+ */
+export declare function resolveDatasetCacheRuntime(policy: DatasetCachePolicy | undefined, callerCache: ExecutionContext['cache'], clientDefaults?: ClientCacheDefaults): ExecutionContext['cache'];
+//# sourceMappingURL=dataset-cache-policy.d.ts.map

package/dist/utils/dataset-cache-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-cache-policy.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-cache-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,KAAK,EAAE,oBAAoB,EAAwB,MAAM,kCAAkC,CAAC;AAEnG;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,oBAAoB,EACpB,OAAO,GAAG,wBAAwB,CACnC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,kBAAkB,GAAG,SAAS,EACtC,WAAW,EAAE,gBAAgB,CAAC,OAAO,CAAC,EACtC,cAAc,CAAC,EAAE,mBAAmB,GACnC,gBAAgB,CAAC,OAAO,CAAC,CAsC3B"}

package/dist/utils/dataset-cache-policy.js

@@ -0,0 +1,50 @@
+/**
+ * Folds a dataset's declared cache policy into one call's cache runtime.
+ *
+ * Precedence mirrors `resolveCompiledDeadline` in `@hypequery/clickhouse`: the
+ * call site may shorten the window but never extend it. A declared `ttlMs`
+ * supplies the default when neither the call nor the client does; a declared
+ * `maxTtlMs` clamps whatever any of the three asked for.
+ *
+ * **`maxTtlMs` is a ceiling, not a default.** When no layer supplies a TTL, the
+ * result stays uncached — a maximum lifetime is not a reason to start caching
+ * something nobody asked to cache.
+ *
+ * **The ceiling bounds total age, not each window separately.** A cached entry
+ * is servable for `ttlMs + staleWhileRevalidateMs`, so clamping the two
+ * independently would allow twice the declared maximum. The stale window gets
+ * whatever the TTL leaves of the budget.
+ *
+ * A caller that opted out (`cache: false`, `mode: 'bypass'`) stays opted out.
+ * Opting out is a shortening, and a dataset policy is not a way to force a
+ * result into a cache the caller declined.
+ */
+export function resolveDatasetCacheRuntime(policy, callerCache, clientDefaults) {
+    if (policy === undefined) {
+        return callerCache;
+    }
+    if (callerCache === false || callerCache?.mode === 'bypass') {
+        return callerCache;
+    }
+    // The value each layer would have produced, most specific first. The client
+    // default is included so the ceiling below applies to it too.
+    const requestedTtl = callerCache?.ttlMs ?? policy.ttlMs ?? clientDefaults?.ttlMs;
+    const requestedStale = callerCache?.staleWhileRevalidateMs ?? clientDefaults?.staleWhileRevalidateMs;
+    const resolved = { ...callerCache };
+    if (requestedTtl === undefined) {
+        // No layer asked for caching. The ceiling does not create it, and there is
+        // no default left downstream for it to fall back to.
+        return resolved;
+    }
+    // Set unconditionally once any layer supplied a value, including an explicit
+    // `0`. Returning without it would leave the cache to re-derive a TTL from the
+    // client default, turning "do not cache this dataset" into the client's TTL.
+    resolved.ttlMs =
+        policy.maxTtlMs === undefined ? requestedTtl : Math.min(requestedTtl, policy.maxTtlMs);
+    if (policy.maxTtlMs !== undefined && resolved.ttlMs > 0) {
+        // Set explicitly for the same reason: an undefined stale window would be
+        // filled from the client default and layered on an already-clamped TTL.
+        resolved.staleWhileRevalidateMs = Math.min(requestedStale ?? 0, Math.max(0, policy.maxTtlMs - resolved.ttlMs));
+    }
+    return resolved;
+}

package/dist/utils/dataset-contract.d.ts

@@ -1,3 +1,3 @@
-import type { AggregationSpec, AnyDatasetInstance, DerivedMetricSpec, MetricContract, TimeGrain } from '../types.js';
-export declare function buildMetricContract(metricName: string, ds: AnyDatasetInstance, spec: AggregationSpec | DerivedMetricSpec, label?: string, description?: string, grain?: TimeGrain): MetricContract;
+import type { AggregationSpec, AnyDatasetInstance, DerivedMetricSpec, MetricContract, SemanticMetadata, TimeGrain } from '../types.js';
+export declare function buildMetricContract(metricName: string, ds: AnyDatasetInstance, spec: AggregationSpec | DerivedMetricSpec, label?: string, description?: string, metadata?: SemanticMetadata, grain?: TimeGrain): MetricContract;
 //# sourceMappingURL=dataset-contract.d.ts.map

package/dist/utils/dataset-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-contract.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,SAAS,EACV,MAAM,aAAa,CAAC;AAIrB,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,eAAe,GAAG,iBAAiB,EACzC,KAAK,CAAC,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,EACpB,KAAK,CAAC,EAAE,SAAS,GAChB,cAAc,CA6BhB"}
+{"version":3,"file":"dataset-contract.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,SAAS,EACV,MAAM,aAAa,CAAC;AAKrB,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,eAAe,GAAG,iBAAiB,EACzC,KAAK,CAAC,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,EACpB,QAAQ,GAAE,gBAAqB,EAC/B,KAAK,CAAC,EAAE,SAAS,GAChB,cAAc,CA8BhB"}

package/dist/utils/dataset-contract.js

@@ -1,5 +1,6 @@
+import { snapshotSemanticMetadata } from './semantic-metadata.js';
 const ALL_GRAINS = ['day', 'week', 'month', 'quarter', 'year'];
-export function buildMetricContract(metricName, ds, spec, label, description, grain) {
+export function buildMetricContract(metricName, ds, spec, label, description, metadata = {}, grain) {
     const dimensionNames = Object.keys(ds.dimensions);
     const measureNames = Object.keys(ds.measures);
     const filterNames = Object.keys(ds.filters).length > 0
@@ -17,6 +18,7 @@ export function buildMetricContract(metricName, ds, spec, label, description, gr
         valueType: 'number',
         label,
         description,
+        ...snapshotSemanticMetadata(metadata),
         dimensions: dimensionNames,
         measures: measureNames,
         filters: filterNames,

package/dist/utils/dataset-definition-validation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Definition-time structural validation for `dataset()`.
+ *
+ * Every check here runs when the dataset is *constructed*, not when it is
+ * queried. A dataset is normally defined at module scope, so a malformed model
+ * fails at import — in the build, in CI, and in the first test that touches the
+ * module — instead of on the first request that happens to exercise the broken
+ * part. The alternative is a typo in `tenantKey` that constructs cleanly, passes
+ * review, and is discovered by a query that quietly returns another tenant's
+ * rows.
+ *
+ * Two categories of check live here:
+ *
+ * - **Identifier safety.** `source`, `tenantKey`, `timeKey`, dimension columns
+ *   and measure fields are all interpolated into SQL as identifiers. They are
+ *   validated once here rather than trusted at every call site that builds a
+ *   predicate from them.
+ * - **Raw SQL shape.** The `sql` escape hatch on dimensions and measures is an
+ *   expression, never a statement. A value carrying a statement terminator or a
+ *   comment is rejected structurally, so it cannot become a second statement or
+ *   comment out the rest of a clause.
+ */
+import type { DatasetConfig, DimensionDefinition, MeasureDefinition, RelationshipDefinition } from '../types.js';
+type AnyDimensions = Record<string, DimensionDefinition>;
+type AnyMeasures = Record<string, MeasureDefinition>;
+type AnyRelationships = Record<string, RelationshipDefinition>;
+/**
+ * Validates a dataset definition. Throws on the first problem found.
+ *
+ * Called by `dataset()` before the instance is built, so an invalid model never
+ * becomes a queryable object.
+ */
+export declare function validateDatasetDefinition(name: string, config: DatasetConfig<AnyDimensions, AnyMeasures, AnyRelationships>): void;
+export {};
+//# sourceMappingURL=dataset-definition-validation.d.ts.map

package/dist/utils/dataset-definition-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-definition-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-definition-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAIrB,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AACzD,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AACrD,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AAuM/D;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,CAAC,aAAa,EAAE,WAAW,EAAE,gBAAgB,CAAC,GAClE,IAAI,CAsDN"}

package/dist/utils/dataset-definition-validation.js

@@ -0,0 +1,215 @@
+/**
+ * Definition-time structural validation for `dataset()`.
+ *
+ * Every check here runs when the dataset is *constructed*, not when it is
+ * queried. A dataset is normally defined at module scope, so a malformed model
+ * fails at import — in the build, in CI, and in the first test that touches the
+ * module — instead of on the first request that happens to exercise the broken
+ * part. The alternative is a typo in `tenantKey` that constructs cleanly, passes
+ * review, and is discovered by a query that quietly returns another tenant's
+ * rows.
+ *
+ * Two categories of check live here:
+ *
+ * - **Identifier safety.** `source`, `tenantKey`, `timeKey`, dimension columns
+ *   and measure fields are all interpolated into SQL as identifiers. They are
+ *   validated once here rather than trusted at every call site that builds a
+ *   predicate from them.
+ * - **Raw SQL shape.** The `sql` escape hatch on dimensions and measures is an
+ *   expression, never a statement. A value carrying a statement terminator or a
+ *   comment is rejected structurally, so it cannot become a second statement or
+ *   comment out the rest of a clause.
+ */
+import { escapeRegExp, isSafeSQLIdentifier, stripSqlLiterals } from '../sql-utils.js';
+import { validateDatasetAgentMetadata } from './semantic-metadata-validation.js';
+/**
+ * Statement terminators and comment openers.
+ *
+ * A raw `sql` value is spliced into a larger expression, so any of these turns
+ * one expression into something else: `;` starts a second statement, `--` and
+ * `/*` comment out whatever the builder appends after it.
+ */
+const STATEMENT_BREAKERS = /;|--|\/\*/;
+/** Dataset, dimension and measure names address fields as `<relationship>.<dimension>`. */
+const QUALIFIED_SEPARATOR = '.';
+function fail(datasetName, message) {
+    throw new Error(`Invalid dataset "${datasetName}": ${message}`);
+}
+/**
+ * Validates a possibly-qualified physical name such as `orders` or
+ * `analytics.orders`. Each segment must stand alone as a safe identifier, so a
+ * qualified name cannot smuggle anything past the per-segment check.
+ */
+function isSafeQualifiedName(value, maxSegments) {
+    const segments = value.split(QUALIFIED_SEPARATOR);
+    if (segments.length > maxSegments) {
+        return false;
+    }
+    return segments.every(isSafeSQLIdentifier);
+}
+function assertSafeColumn(datasetName, value, context) {
+    if (!isSafeSQLIdentifier(value)) {
+        fail(datasetName, `${context} "${value}" is not a safe column identifier. It is interpolated into SQL, so it ` +
+            'must contain only letters, numbers and underscores, and start with a letter or underscore.');
+    }
+}
+/**
+ * Validates a semantic name — a dimension or measure key.
+ *
+ * These are not physical columns, but they are identifiers: they appear in query
+ * inputs, generated tool schemas, and protocol artifacts, where the strict
+ * identifier grammar applies. Rejecting here beats failing later during artifact
+ * production, which is far from the definition that caused it.
+ */
+function assertSafeName(datasetName, kind, name) {
+    if (!isSafeSQLIdentifier(name)) {
+        fail(datasetName, `${kind} name "${name}" must contain only letters, numbers and underscores, and start ` +
+            'with a letter or underscore, so it stays a valid identifier in generated artifacts.');
+    }
+}
+/**
+ * Checks a raw `sql` expression and the dependencies declared alongside it.
+ *
+ * The dependency check runs in the direction that fails silently: a declared
+ * dependency the expression never references means the definition believes it
+ * reads a column it does not read. The opposite direction — an identifier used
+ * but not declared — would need a SQL parser, and is caught by the protocol
+ * adapter when the artifact is produced.
+ */
+function validateRawSql(datasetName, kind, name, sql, dependencies) {
+    if (sql.trim().length === 0) {
+        fail(datasetName, `${kind} "${name}" declares an empty sql expression.`);
+    }
+    // Quoted spans are blanked first, so a terminator or comment opener *inside* a
+    // string literal is data rather than syntax. An unterminated quote is itself a
+    // rejection: left as data, an open quote would hide everything after it.
+    let code;
+    let referenceable;
+    try {
+        code = stripSqlLiterals(sql);
+        // A quoted identifier is a column reference, so the dependency check below
+        // needs its text even though the terminator check above must not see it.
+        referenceable = stripSqlLiterals(sql, { keepQuotedIdentifiers: true });
+    }
+    catch {
+        fail(datasetName, `${kind} "${name}" sql has an unterminated quoted literal.`);
+    }
+    if (STATEMENT_BREAKERS.test(code)) {
+        fail(datasetName, `${kind} "${name}" sql must be a single expression without statement terminators or ` +
+            'comments (";", "--", "/*") outside a quoted literal.');
+    }
+    for (const dependency of dependencies ?? []) {
+        // Dependencies are qualified identifiers (`analytics.orders.amount`); the
+        // expression references the column itself, so the final segment is what has
+        // to appear in it. Escaped before it becomes a pattern: a raw value carrying
+        // regex syntax would either throw at construction or match something else.
+        const segments = dependency.split(QUALIFIED_SEPARATOR);
+        const column = segments[segments.length - 1] ?? '';
+        if (column.length === 0 || !new RegExp(`\\b${escapeRegExp(column)}\\b`).test(referenceable)) {
+            fail(datasetName, `${kind} "${name}" declares dependency "${dependency}", but its sql expression never ` +
+                'references it. A dependency the expression does not read makes the definition claim ' +
+                'a column it never touches.');
+        }
+    }
+}
+function validateDimensions(datasetName, dimensions) {
+    for (const [name, definition] of Object.entries(dimensions)) {
+        if (name.includes(QUALIFIED_SEPARATOR)) {
+            fail(datasetName, `dimension "${name}" cannot contain "." because qualified fields are addressed as ` +
+                '"<relationship>.<dimension>".');
+        }
+        // The name is a semantic identifier in its own right — it appears in
+        // protocol artifacts and query inputs — so it is checked whether or not an
+        // explicit column stands in for it below. Without this, the check silently
+        // depended on the column being omitted.
+        assertSafeName(datasetName, 'dimension', name);
+        if (definition.sql !== undefined) {
+            validateRawSql(datasetName, 'dimension', name, definition.sql, definition.dependencies);
+            continue;
+        }
+        // A dimension with no explicit column is backed by a column of the same name.
+        assertSafeColumn(datasetName, definition.column ?? name, `dimension "${name}" column`);
+    }
+}
+function validateMeasures(datasetName, measures, dimensions) {
+    for (const [name, definition] of Object.entries(measures)) {
+        assertSafeName(datasetName, 'measure', name);
+        if (definition.sql !== undefined) {
+            validateRawSql(datasetName, 'measure', name, definition.sql, definition.dependencies);
+        }
+        // `field` and `argField` name either a declared dimension or a physical
+        // column that the model deliberately does not expose (the `allowHiddenField`
+        // case in metric validation). Either way the value reaches SQL, so a name
+        // that is not a declared dimension must at least be a safe identifier.
+        for (const [label, value] of [
+            ['field', definition.field],
+            ['argField', definition.argField],
+        ]) {
+            if (value === undefined || value in dimensions) {
+                continue;
+            }
+            assertSafeColumn(datasetName, value, `measure "${name}" ${label}`);
+        }
+    }
+}
+function validateLimits(datasetName, limits) {
+    if (!limits) {
+        return;
+    }
+    for (const [name, value] of Object.entries(limits)) {
+        if (value === undefined) {
+            continue;
+        }
+        if (!Number.isInteger(value) || value <= 0) {
+            fail(datasetName, `limits.${name} must be a positive integer, received ${String(value)}.`);
+        }
+    }
+}
+/**
+ * Validates a dataset definition. Throws on the first problem found.
+ *
+ * Called by `dataset()` before the instance is built, so an invalid model never
+ * becomes a queryable object.
+ */
+export function validateDatasetDefinition(name, config) {
+    if (typeof name !== 'string' || name.trim().length === 0) {
+        throw new Error('Invalid dataset: a non-empty dataset name is required.');
+    }
+    if (!isSafeSQLIdentifier(name)) {
+        fail(name, 'dataset names must contain only letters, numbers and underscores, and start with a letter ' +
+            'or underscore, so they remain valid identifiers in generated artifacts.');
+    }
+    if (typeof config.source !== 'string' || config.source.trim().length === 0) {
+        fail(name, 'a non-empty source table is required.');
+    }
+    // `database.table` is the deepest qualification ClickHouse addresses.
+    if (!isSafeQualifiedName(config.source, 2)) {
+        fail(name, `source "${config.source}" is not a safe table identifier. Expected "table" or ` +
+            '"database.table", each segment containing only letters, numbers and underscores.');
+    }
+    // The tenant key is the isolation boundary: it becomes a WHERE predicate on
+    // every query against a tenant-scoped dataset, so it is checked here rather
+    // than trusted wherever that predicate is assembled.
+    if (config.tenantKey !== undefined) {
+        if (config.tenantKey.trim().length === 0) {
+            fail(name, 'tenantKey cannot be empty. Omit it entirely for a dataset without tenancy.');
+        }
+        assertSafeColumn(name, config.tenantKey, 'tenantKey');
+    }
+    if (config.timeKey !== undefined) {
+        if (config.timeKey.trim().length === 0) {
+            fail(name, 'timeKey cannot be empty. Omit it entirely for a dataset without a time key.');
+        }
+        if (!(config.timeKey in (config.dimensions ?? {}))) {
+            assertSafeColumn(name, config.timeKey, 'timeKey');
+        }
+    }
+    // A dataset with no dimensions is not rejected here: the query layer already
+    // refuses an empty dataset query, which is the honest place for it — a
+    // measure-only model is a legitimate thing to define.
+    const dimensions = config.dimensions ?? {};
+    validateDimensions(name, dimensions);
+    validateMeasures(name, config.measures ?? {}, dimensions);
+    validateLimits(name, config.limits);
+    validateDatasetAgentMetadata(name, config);
+}

package/dist/utils/dataset-metric-ref.d.ts

@@ -1,9 +1,9 @@
-import type { AggregationSpec, BaseMetricConfig, BaseMetricRef, DatasetInstance, DerivedMetricConfig, DerivedMetricRef, DerivedMetricSpec, DimensionDefinition, MeasureDefinition, MetricRef, RelationshipDefinition } from '../types.js';
+import type { AggregationSpec, BaseMetricConfig, BaseMetricRef, DatasetInstance, DerivedMetricConfig, DerivedMetricRef, DerivedMetricSpec, DimensionDefinition, MeasureDefinition, MetricRef, RelationshipDefinition, SemanticMetadata } from '../types.js';
 type AnyDimensions = Record<string, DimensionDefinition>;
 type AnyMeasures = Record<string, MeasureDefinition>;
 type AnyRelationships = Record<string, RelationshipDefinition>;
 export declare function isDerivedMetricConfig<TMeasures extends Record<string, MeasureDefinition>, TDatasetName extends string>(config: BaseMetricConfig<TMeasures> | DerivedMetricConfig<TDatasetName>): config is DerivedMetricConfig<TDatasetName>;
-export declare function createMetricRef<TDatasetName extends string, TMetricName extends string, TSpec extends AggregationSpec | DerivedMetricSpec<TDatasetName>, TDataset extends DatasetInstance<AnyDimensions, AnyMeasures, AnyRelationships, TDatasetName>>(ds: TDataset, name: TMetricName, spec: TSpec, label?: string, description?: string): MetricRef<TDatasetName, TMetricName, TSpec, TDataset>;
+export declare function createMetricRef<TDatasetName extends string, TMetricName extends string, TSpec extends AggregationSpec | DerivedMetricSpec<TDatasetName>, TDataset extends DatasetInstance<AnyDimensions, AnyMeasures, AnyRelationships, TDatasetName>>(ds: TDataset, name: TMetricName, spec: TSpec, label?: string, description?: string, metadata?: SemanticMetadata): MetricRef<TDatasetName, TMetricName, TSpec, TDataset>;
 export declare function createDerivedMetricSpec<TDatasetName extends string>(config: DerivedMetricConfig<TDatasetName>): DerivedMetricSpec<TDatasetName>;
 export type { BaseMetricRef, DerivedMetricRef };
 //# sourceMappingURL=dataset-metric-ref.d.ts.map