@hypequery/datasets 0.13.5 → 0.14.0

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

@@ -1 +1 @@
-{"version":3,"file":"dataset-metric-ref.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-metric-ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EAEnB,iBAAiB,EACjB,SAAS,EACT,sBAAsB,EAEvB,MAAM,aAAa,CAAC;AAGrB,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;AAE/D,wBAAgB,qBAAqB,CACnC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACnD,YAAY,SAAS,MAAM,EAE3B,MAAM,EAAE,gBAAgB,CAAC,SAAS,CAAC,GAAG,mBAAmB,CAAC,YAAY,CAAC,GACtE,MAAM,IAAI,mBAAmB,CAAC,YAAY,CAAC,CAE7C;AAED,wBAAgB,eAAe,CAC7B,YAAY,SAAS,MAAM,EAC3B,WAAW,SAAS,MAAM,EAC1B,KAAK,SAAS,eAAe,GAAG,iBAAiB,CAAC,YAAY,CAAC,EAC/D,QAAQ,SAAS,eAAe,CAAC,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,YAAY,CAAC,EAE5F,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,KAAK,EACX,KAAK,CAAC,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,GACnB,SAAS,CAAC,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,CAAC,CAiCvD;AAED,wBAAgB,uBAAuB,CAAC,YAAY,SAAS,MAAM,EACjE,MAAM,EAAE,mBAAmB,CAAC,YAAY,CAAC,GACxC,iBAAiB,CAAC,YAAY,CAAC,CAMjC;AAED,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,CAAC"}
+{"version":3,"file":"dataset-metric-ref.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-metric-ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EAEnB,iBAAiB,EACjB,SAAS,EACT,sBAAsB,EACtB,gBAAgB,EAEjB,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;AAE/D,wBAAgB,qBAAqB,CACnC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACnD,YAAY,SAAS,MAAM,EAE3B,MAAM,EAAE,gBAAgB,CAAC,SAAS,CAAC,GAAG,mBAAmB,CAAC,YAAY,CAAC,GACtE,MAAM,IAAI,mBAAmB,CAAC,YAAY,CAAC,CAE7C;AAED,wBAAgB,eAAe,CAC7B,YAAY,SAAS,MAAM,EAC3B,WAAW,SAAS,MAAM,EAC1B,KAAK,SAAS,eAAe,GAAG,iBAAiB,CAAC,YAAY,CAAC,EAC/D,QAAQ,SAAS,eAAe,CAAC,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,YAAY,CAAC,EAE5F,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,KAAK,EACX,KAAK,CAAC,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,EACpB,QAAQ,GAAE,gBAAqB,GAC9B,SAAS,CAAC,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,CAAC,CAkCvD;AAED,wBAAgB,uBAAuB,CAAC,YAAY,SAAS,MAAM,EACjE,MAAM,EAAE,mBAAmB,CAAC,YAAY,CAAC,GACxC,iBAAiB,CAAC,YAAY,CAAC,CAMjC;AAED,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/utils/dataset-metric-ref.js

@@ -1,8 +1,9 @@
 import { buildMetricContract } from './dataset-contract.js';
+import { snapshotSemanticMetadata } from './semantic-metadata.js';
 export function isDerivedMetricConfig(config) {
     return 'uses' in config && 'formula' in config;
 }
-export function createMetricRef(ds, name, spec, label, description) {
+export function createMetricRef(ds, name, spec, label, description, metadata = {}) {
     const ref = {
         __type: 'metric_ref',
         datasetName: ds.name,
@@ -10,6 +11,7 @@ export function createMetricRef(ds, name, spec, label, description) {
         spec,
         label,
         description,
+        ...snapshotSemanticMetadata(metadata),
         dataset: ds,
         by(grain) {
             if (!ds.timeKey) {
@@ -20,12 +22,12 @@ export function createMetricRef(ds, name, spec, label, description) {
                 metric: ref,
                 grain,
                 contract() {
-                    return buildMetricContract(name, ds, spec, label, description, grain);
+                    return buildMetricContract(name, ds, spec, label, description, metadata, grain);
                 },
             };
         },
         contract() {
-            return buildMetricContract(name, ds, spec, label, description);
+            return buildMetricContract(name, ds, spec, label, description, metadata);
         },
     };
     return ref;

package/dist/utils/metric-alias.d.ts

@@ -0,0 +1,4 @@
+import type { MetricHandle } from '../types.js';
+/** Clone a metric handle with the public name used by a published registry. */
+export declare function aliasMetricHandle(metric: MetricHandle, alias: string, datasetAlias: string): MetricHandle;
+//# sourceMappingURL=metric-alias.d.ts.map

package/dist/utils/metric-alias.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-alias.d.ts","sourceRoot":"","sources":["../../src/utils/metric-alias.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAKV,YAAY,EAEb,MAAM,aAAa,CAAC;AA4BrB,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GACnB,YAAY,CAYd"}

package/dist/utils/metric-alias.js

@@ -0,0 +1,28 @@
+function aliasMetricRef(metric, alias, datasetAlias) {
+    const aliased = {
+        ...metric,
+        datasetName: datasetAlias,
+        name: alias,
+        by(grain) {
+            return aliasMetricHandle(metric.by(grain), alias, datasetAlias);
+        },
+        contract() {
+            return { ...metric.contract(), dataset: datasetAlias, name: alias };
+        },
+    };
+    return aliased;
+}
+/** Clone a metric handle with the public name used by a published registry. */
+export function aliasMetricHandle(metric, alias, datasetAlias) {
+    if (metric.__type === 'metric_ref') {
+        return aliasMetricRef(metric, alias, datasetAlias);
+    }
+    const aliasedMetric = aliasMetricRef(metric.metric, alias, datasetAlias);
+    return {
+        ...metric,
+        metric: aliasedMetric,
+        contract() {
+            return { ...metric.contract(), dataset: datasetAlias, name: alias };
+        },
+    };
+}

package/dist/utils/protocol-metric-capabilities.d.ts

@@ -0,0 +1,7 @@
+import type { ProtocolDatasetMetric } from '@hypequery/protocol';
+import type { MetricHandle, MetricQuery } from '../types.js';
+/** Runtime restrictions travel with a cloned handle, including publication aliases. */
+export declare function protocolMetricCapabilityErrors(handle: MetricHandle, query: MetricQuery): string[];
+/** Pin discovery and execution together, preserving restrictions when graining. */
+export declare function withContractCapabilities(handle: MetricHandle, metric: ProtocolDatasetMetric): MetricHandle;
+//# sourceMappingURL=protocol-metric-capabilities.d.ts.map

package/dist/utils/protocol-metric-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-metric-capabilities.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-metric-capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAwB,MAAM,aAAa,CAAC;AAUnF,uFAAuF;AACvF,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,EAAE,CAajG;AAED,mFAAmF;AACnF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,qBAAqB,GAAG,YAAY,CAkC1G"}

package/dist/utils/protocol-metric-capabilities.js

@@ -0,0 +1,57 @@
+const CAPABILITIES = Symbol('hypequery.protocol-metric-capabilities');
+/** Runtime restrictions travel with a cloned handle, including publication aliases. */
+export function protocolMetricCapabilityErrors(handle, query) {
+    const capabilities = handle[CAPABILITIES];
+    if (!capabilities)
+        return [];
+    const errors = [];
+    for (const dimension of query.dimensions ?? []) {
+        if (!capabilities.dimensions.includes(dimension))
+            errors.push(`Dimension "${dimension}" is not published for this metric.`);
+    }
+    for (const filter of query.filters ?? []) {
+        if (!capabilities.filters.includes(filter.field))
+            errors.push(`Filter "${filter.field}" is not published for this metric.`);
+    }
+    const grain = handle.__type === 'grained_metric_ref' ? handle.grain : query.by;
+    if (grain && !capabilities.grains.includes(grain))
+        errors.push(`Grain "${grain}" is not published for this metric.`);
+    return errors;
+}
+/** Pin discovery and execution together, preserving restrictions when graining. */
+export function withContractCapabilities(handle, metric) {
+    const capabilities = Object.freeze({
+        dimensions: Object.freeze(metric.dimensions.map(String)),
+        filters: Object.freeze(metric.filters.map(String)),
+        grains: Object.freeze([...metric.grains]),
+    });
+    const pin = (target) => {
+        const contract = () => ({
+            ...target.contract(),
+            dimensions: [...capabilities.dimensions],
+            filters: [...capabilities.filters],
+            grains: [...capabilities.grains],
+        });
+        if (target.__type === 'grained_metric_ref') {
+            return Object.freeze({ ...target, [CAPABILITIES]: capabilities, metric: pin(target.metric), contract });
+        }
+        const pinned = {
+            ...target,
+            [CAPABILITIES]: capabilities,
+            contract,
+            by(grain) {
+                if (!capabilities.grains.includes(grain))
+                    throw new Error(`Grain "${grain}" is not published for this metric.`);
+                const grained = target.by(grain);
+                return Object.freeze({
+                    ...grained,
+                    [CAPABILITIES]: capabilities,
+                    metric: pinned,
+                    contract: () => ({ ...contract(), kind: 'grained_metric', grain }),
+                });
+            },
+        };
+        return Object.freeze(pinned);
+    };
+    return pin(handle);
+}

package/dist/utils/protocol-rehydrate-filters.d.ts

@@ -0,0 +1,10 @@
+import type { ProtocolExpression } from '@hypequery/protocol';
+import type { MetricFilter } from '../types.js';
+/**
+ * A measure's fixed filters cross the contract boundary as RFC 0003
+ * expressions. `protocol-adapter.ts` only ever emits `reference <op> literal`
+ * for them, so this inverts exactly that shape and refuses anything else rather
+ * than partially interpreting an expression it cannot faithfully rebuild.
+ */
+export declare function rehydrateMeasureFilter(expression: ProtocolExpression, unsupported: () => Error): MetricFilter;
+//# sourceMappingURL=protocol-rehydrate-filters.d.ts.map

package/dist/utils/protocol-rehydrate-filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-rehydrate-filters.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-rehydrate-filters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,kBAAkB,EAC9B,WAAW,EAAE,MAAM,KAAK,GACvB,YAAY,CASd"}

package/dist/utils/protocol-rehydrate-filters.js

@@ -0,0 +1,36 @@
+/**
+ * A measure's fixed filters cross the contract boundary as RFC 0003
+ * expressions. `protocol-adapter.ts` only ever emits `reference <op> literal`
+ * for them, so this inverts exactly that shape and refuses anything else rather
+ * than partially interpreting an expression it cannot faithfully rebuild.
+ */
+export function rehydrateMeasureFilter(expression, unsupported) {
+    if (expression.kind !== 'comparison')
+        throw unsupported();
+    const { left, right, operator } = expression;
+    if (left.kind !== 'reference' || right.kind !== 'literal')
+        throw unsupported();
+    return {
+        field: String(left.name),
+        operator,
+        value: fromCanonicalValue(right.value, unsupported),
+    };
+}
+/**
+ * Unwraps the RFC 0001 tagged value model back to the plain JavaScript value a
+ * measure filter was authored with.
+ */
+function fromCanonicalValue(value, unsupported) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    const tagged = value
+        .$hypequery;
+    if (tagged === undefined)
+        throw unsupported();
+    if (tagged.type === 'array') {
+        return (tagged.values ?? []).map(item => fromCanonicalValue(item, unsupported));
+    }
+    if (tagged.value === undefined)
+        throw unsupported();
+    return tagged.value;
+}

package/dist/utils/protocol-semantic-metadata.d.ts

@@ -0,0 +1,5 @@
+import type { ProtocolSemanticMetadata } from '@hypequery/protocol';
+import type { SemanticMetadata } from '../types.js';
+/** Map local semantic metadata onto its portable protocol representation. */
+export declare function toProtocolSemanticMetadata(metadata: SemanticMetadata): ProtocolSemanticMetadata;
+//# sourceMappingURL=protocol-semantic-metadata.d.ts.map

package/dist/utils/protocol-semantic-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-semantic-metadata.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-semantic-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,6EAA6E;AAC7E,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,gBAAgB,GACzB,wBAAwB,CAE1B"}

package/dist/utils/protocol-semantic-metadata.js

@@ -0,0 +1,5 @@
+import { snapshotSemanticMetadata } from './semantic-metadata.js';
+/** Map local semantic metadata onto its portable protocol representation. */
+export function toProtocolSemanticMetadata(metadata) {
+    return snapshotSemanticMetadata(metadata);
+}

package/dist/utils/published-name.d.ts

@@ -0,0 +1,3 @@
+/** Validate names that become public dataset, metric, tool, or schema identifiers. */
+export declare function assertPublishedName(name: string, kind: 'dataset' | 'metric'): void;
+//# sourceMappingURL=published-name.d.ts.map

package/dist/utils/published-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"published-name.d.ts","sourceRoot":"","sources":["../../src/utils/published-name.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,IAAI,CAMlF"}

package/dist/utils/published-name.js

@@ -0,0 +1,7 @@
+const PUBLISHED_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Validate names that become public dataset, metric, tool, or schema identifiers. */
+export function assertPublishedName(name, kind) {
+    if (!PUBLISHED_NAME.test(name)) {
+        throw new Error(`Published ${kind} name "${name}" must start with a letter or underscore and contain only letters, numbers, and underscores.`);
+    }
+}

package/dist/utils/published-relationships.d.ts

@@ -0,0 +1,34 @@
+import type { AnyDatasetInstance, RelationshipDefinition } from '../types.js';
+/**
+ * Resolves a published alias back to the materialized instance registered under
+ * it. Deliberately a lookup rather than a value: relationships are rewired
+ * while the registry is still being built, and datasets may reference each
+ * other, so a target is resolved on call rather than at rewiring time.
+ */
+export type PublishedLookup = (alias: string) => AnyDatasetInstance | undefined;
+/**
+ * Maps each published dataset's defined name to the alias it was published
+ * under. Keyed by name because that is the uniqueness the publisher enforces —
+ * it rejects a second entry for the same dataset name — so a copied instance
+ * still resolves to the right alias.
+ */
+export declare function publishedAliasesByName(entries: readonly {
+    readonly alias: string;
+    readonly dataset: AnyDatasetInstance;
+}[]): ReadonlyMap<string, string>;
+/**
+ * Rewires a dataset's relationships onto the aliases their targets were
+ * published under.
+ *
+ * Publishing only renames the copied dataset, so without this a relationship's
+ * `target()` closure still returns the original instance — a dataset published
+ * as `accounts` would still be advertised as `customers` by everything that
+ * relates to it, giving agents a target absent from the registry and a
+ * reference the deployment contract validator rejects.
+ *
+ * A target that was not published is left untouched: the join still resolves
+ * through the original instance, which is how an unpublished target already
+ * behaves in a hand-built registry.
+ */
+export declare function rewirePublishedRelationships(relationships: Readonly<Record<string, RelationshipDefinition>>, aliasesByName: ReadonlyMap<string, string>, lookup: PublishedLookup): Record<string, RelationshipDefinition>;
+//# sourceMappingURL=published-relationships.d.ts.map

package/dist/utils/published-relationships.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"published-relationships.d.ts","sourceRoot":"","sources":["../../src/utils/published-relationships.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,kBAAkB,GAAG,SAAS,CAAC;AAEhF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,SAAS;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,EAAE,GACnF,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAE7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAC1C,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,EAC/D,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1C,MAAM,EAAE,eAAe,GACtB,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAUxC"}

package/dist/utils/published-relationships.js

@@ -0,0 +1,35 @@
+/**
+ * Maps each published dataset's defined name to the alias it was published
+ * under. Keyed by name because that is the uniqueness the publisher enforces —
+ * it rejects a second entry for the same dataset name — so a copied instance
+ * still resolves to the right alias.
+ */
+export function publishedAliasesByName(entries) {
+    return new Map(entries.map(entry => [entry.dataset.name, entry.alias]));
+}
+/**
+ * Rewires a dataset's relationships onto the aliases their targets were
+ * published under.
+ *
+ * Publishing only renames the copied dataset, so without this a relationship's
+ * `target()` closure still returns the original instance — a dataset published
+ * as `accounts` would still be advertised as `customers` by everything that
+ * relates to it, giving agents a target absent from the registry and a
+ * reference the deployment contract validator rejects.
+ *
+ * A target that was not published is left untouched: the join still resolves
+ * through the original instance, which is how an unpublished target already
+ * behaves in a hand-built registry.
+ */
+export function rewirePublishedRelationships(relationships, aliasesByName, lookup) {
+    const rewired = Object.entries(relationships).map(([name, relationship]) => {
+        const alias = aliasesByName.get(relationship.target().name);
+        if (alias === undefined)
+            return [name, relationship];
+        return [name, Object.freeze({
+                ...relationship,
+                target: () => lookup(alias) ?? relationship.target(),
+            })];
+    });
+    return Object.freeze(Object.fromEntries(rewired));
+}

package/dist/utils/relationship-fields.d.ts

@@ -15,6 +15,13 @@ import type { AnyDatasetInstance, DimensionDefinition, RelationshipDefinition }
  * generated input schemas all advertise exactly this list.
  */
 export declare function listQueryableRelationshipFields(name: string, relationship: RelationshipDefinition): string[];
+/**
+ * The subset of {@link listQueryableRelationshipFields} that may be used as a
+ * grouping key, honouring `groupable: false` on the target dimension. The rest
+ * stay queryable as filters, which is why this is a separate list rather than a
+ * narrowing of the one above.
+ */
+export declare function listGroupableRelationshipFields(name: string, relationship: RelationshipDefinition): string[];
 export interface ParsedQualifiedField {
     /** The relationship name (prefix before the first dot). */
     relationship: string;

package/dist/utils/relationship-fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationship-fields.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,sBAAsB,GACnC,MAAM,EAAE,CAQV;AAED,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;CACf;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAM7E;AAED,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,sBAAsB,CAAC;IACrC,4CAA4C;IAC5C,MAAM,EAAE,kBAAkB,CAAC;IAC3B,+DAA+D;IAC/D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,mBAAmB,CAAC;IACrC,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,EAAE,sBAAsB,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,GACX,wBAAwB,GAAG,IAAI,CAuDjC"}
+{"version":3,"file":"relationship-fields.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,sBAAsB,GACnC,MAAM,EAAE,CAEV;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,sBAAsB,GACnC,MAAM,EAAE,CAEV;AAgBD,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;CACf;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAM7E;AAED,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,sBAAsB,CAAC;IACrC,4CAA4C;IAC5C,MAAM,EAAE,kBAAkB,CAAC;IAC3B,+DAA+D;IAC/D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,mBAAmB,CAAC;IACrC,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,EAAE,sBAAsB,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,GACX,wBAAwB,GAAG,IAAI,CAuDjC"}

package/dist/utils/relationship-fields.js

@@ -14,12 +14,24 @@
  * generated input schemas all advertise exactly this list.
  */
 export function listQueryableRelationshipFields(name, relationship) {
+    return relationshipFields(name, relationship, () => true);
+}
+/**
+ * The subset of {@link listQueryableRelationshipFields} that may be used as a
+ * grouping key, honouring `groupable: false` on the target dimension. The rest
+ * stay queryable as filters, which is why this is a separate list rather than a
+ * narrowing of the one above.
+ */
+export function listGroupableRelationshipFields(name, relationship) {
+    return relationshipFields(name, relationship, dimension => dimension.groupable !== false);
+}
+function relationshipFields(name, relationship, include) {
     if (relationship.kind === 'hasMany') {
         return [];
     }
     const target = relationship.target();
     return Object.entries(target?.dimensions ?? {})
-        .filter(([, dimension]) => !dimension.sql)
+        .filter(([, dimension]) => !dimension.sql && include(dimension))
         .map(([field]) => `${name}.${field}`);
 }
 /** True when a field name is relationship-qualified (contains a dot). */

package/dist/utils/result-limits.d.ts

@@ -0,0 +1,34 @@
+import type { DatasetLimits, MetricResultMeta } from '../types.js';
+export type ResultLimitMeta = NonNullable<MetricResultMeta['resultLimit']>;
+export interface ResolvedResultLimit {
+    /** The limit to execute with; `undefined` leaves the query unbounded. */
+    limit?: number;
+    /** Meta to surface, present only when the declared ceiling supplied the limit. */
+    meta?: ResultLimitMeta;
+}
+/**
+ * Applies a dataset's declared `maxResultSize` to a query that set no limit.
+ *
+ * Query validation already rejects a limit *above* the ceiling, so the case
+ * left open is the one with no limit at all: `query.limit != null` guards both
+ * validators, so an unbounded query has always skipped the ceiling entirely and
+ * streamed whatever the table held. A ceiling that only binds callers who
+ * happened to name a limit is not a ceiling.
+ *
+ * Bounding is reported, never silent. A caller who asked for everything and
+ * received 1,000 rows cannot otherwise distinguish a bounded answer from a
+ * complete one, and 1,000 rows is a plausible-looking number.
+ */
+export declare function resolveResultLimit(requested: number | undefined, limits: DatasetLimits | undefined): ResolvedResultLimit;
+/**
+ * Merges result-limit meta onto a pending result.
+ *
+ * Takes the promise rather than the resolved value so the caller stays
+ * synchronous: query validation throws before execution begins, and callers
+ * (and their tests) rely on that being a synchronous throw rather than a
+ * rejected promise.
+ */
+export declare function withResultLimit<T extends {
+    meta?: MetricResultMeta;
+}>(result: Promise<T>, meta: ResultLimitMeta | undefined): Promise<T>;
+//# sourceMappingURL=result-limits.d.ts.map

package/dist/utils/result-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-limits.d.ts","sourceRoot":"","sources":["../../src/utils/result-limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEnE,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC,CAAC;AAE3E,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,aAAa,GAAG,SAAS,GAChC,mBAAmB,CAWrB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,gBAAgB,CAAA;CAAE,EACnE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,IAAI,EAAE,eAAe,GAAG,SAAS,GAChC,OAAO,CAAC,CAAC,CAAC,CAQZ"}

package/dist/utils/result-limits.js

@@ -0,0 +1,40 @@
+/**
+ * Applies a dataset's declared `maxResultSize` to a query that set no limit.
+ *
+ * Query validation already rejects a limit *above* the ceiling, so the case
+ * left open is the one with no limit at all: `query.limit != null` guards both
+ * validators, so an unbounded query has always skipped the ceiling entirely and
+ * streamed whatever the table held. A ceiling that only binds callers who
+ * happened to name a limit is not a ceiling.
+ *
+ * Bounding is reported, never silent. A caller who asked for everything and
+ * received 1,000 rows cannot otherwise distinguish a bounded answer from a
+ * complete one, and 1,000 rows is a plausible-looking number.
+ */
+export function resolveResultLimit(requested, limits) {
+    const maxResultSize = limits?.maxResultSize;
+    if (maxResultSize === undefined || requested !== undefined) {
+        return { limit: requested };
+    }
+    return {
+        limit: maxResultSize,
+        meta: { maxResultSize, applied: maxResultSize },
+    };
+}
+/**
+ * Merges result-limit meta onto a pending result.
+ *
+ * Takes the promise rather than the resolved value so the caller stays
+ * synchronous: query validation throws before execution begins, and callers
+ * (and their tests) rely on that being a synchronous throw rather than a
+ * rejected promise.
+ */
+export function withResultLimit(result, meta) {
+    if (meta === undefined) {
+        return result;
+    }
+    return result.then((value) => ({
+        ...value,
+        meta: { ...(value.meta ?? {}), resultLimit: { ...meta } },
+    }));
+}

package/dist/utils/semantic-metadata-validation.d.ts

@@ -0,0 +1,4 @@
+import type { DatasetConfig, DimensionDefinition, MeasureDefinition, RelationshipDefinition, SemanticMetadata } from '../types.js';
+export declare function validateSemanticMetadata(datasetName: string, location: string, metadata: SemanticMetadata): void;
+export declare function validateDatasetAgentMetadata<TDimensions extends Record<string, DimensionDefinition>, TMeasures extends Record<string, MeasureDefinition>, TRelationships extends Record<string, RelationshipDefinition>>(datasetName: string, config: DatasetConfig<TDimensions, TMeasures, TRelationships>): void;
+//# sourceMappingURL=semantic-metadata-validation.d.ts.map

package/dist/utils/semantic-metadata-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-metadata-validation.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-metadata-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAoBrB,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,gBAAgB,GACzB,IAAI,CA8BN;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACnD,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAE7D,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAC5D,IAAI,CAuDN"}

package/dist/utils/semantic-metadata-validation.js

@@ -0,0 +1,103 @@
+const MAX_METADATA_ITEMS = 100;
+const MAX_METADATA_TEXT_BYTES = 4_096;
+const SENSITIVITIES = new Set(['public', 'internal', 'confidential', 'restricted']);
+const TIME_GRAINS = new Set(['day', 'week', 'month', 'quarter', 'year']);
+const textEncoder = new TextEncoder();
+function fail(datasetName, location, message) {
+    throw new Error(`Invalid dataset "${datasetName}": ${location} ${message}`);
+}
+function validateText(datasetName, location, value) {
+    if (typeof value !== 'string')
+        fail(datasetName, location, 'must be a string.');
+    if (value.trim().length === 0)
+        fail(datasetName, location, 'must not be empty.');
+    if (textEncoder.encode(value).byteLength > MAX_METADATA_TEXT_BYTES) {
+        fail(datasetName, location, `must not exceed ${MAX_METADATA_TEXT_BYTES} UTF-8 bytes.`);
+    }
+}
+export function validateSemanticMetadata(datasetName, location, metadata) {
+    for (const key of ['examples', 'synonyms']) {
+        const values = metadata[key];
+        if (values === undefined)
+            continue;
+        if (!Array.isArray(values) || values.length > MAX_METADATA_ITEMS) {
+            fail(datasetName, `${location}.${key}`, `must contain at most ${MAX_METADATA_ITEMS} strings.`);
+        }
+        if (new Set(values).size !== values.length) {
+            fail(datasetName, `${location}.${key}`, 'must not contain duplicates.');
+        }
+        for (const [index, value] of values.entries()) {
+            if (typeof value !== 'string') {
+                fail(datasetName, `${location}.${key}[${index}]`, 'must be a string.');
+            }
+            validateText(datasetName, `${location}.${key}[${index}]`, value);
+        }
+    }
+    for (const key of ['format', 'unit', 'timezone']) {
+        const value = metadata[key];
+        if (value !== undefined)
+            validateText(datasetName, `${location}.${key}`, value);
+    }
+    if (metadata.currency !== undefined) {
+        if (typeof metadata.currency !== 'string' || !/^[A-Z]{3}$/.test(metadata.currency)) {
+            fail(datasetName, `${location}.currency`, 'must be a three-letter uppercase currency code.');
+        }
+    }
+    if (metadata.sensitivity !== undefined
+        && (typeof metadata.sensitivity !== 'string' || !SENSITIVITIES.has(metadata.sensitivity))) {
+        fail(datasetName, `${location}.sensitivity`, 'is not a supported sensitivity classification.');
+    }
+}
+export function validateDatasetAgentMetadata(datasetName, config) {
+    validateSemanticMetadata(datasetName, 'metadata', config);
+    if (config.description !== undefined)
+        validateText(datasetName, 'description', config.description);
+    if (config.owner !== undefined)
+        validateText(datasetName, 'owner', config.owner);
+    if (config.freshness !== undefined) {
+        if (typeof config.freshness !== 'object' || config.freshness === null
+            || !Number.isSafeInteger(config.freshness.maxAgeSeconds)
+            || config.freshness.maxAgeSeconds < 1) {
+            fail(datasetName, 'freshness.maxAgeSeconds', 'must be a positive safe integer.');
+        }
+    }
+    if (config.defaults !== undefined) {
+        if (typeof config.defaults !== 'object' || config.defaults === null) {
+            fail(datasetName, 'defaults', 'must be an object.');
+        }
+        if (config.defaults.dimensions !== undefined && !Array.isArray(config.defaults.dimensions)) {
+            fail(datasetName, 'defaults.dimensions', 'must be an array.');
+        }
+        const dimensions = config.defaults.dimensions ?? [];
+        if (dimensions.length > MAX_METADATA_ITEMS) {
+            fail(datasetName, 'defaults.dimensions', `must contain at most ${MAX_METADATA_ITEMS} dimensions.`);
+        }
+        if (new Set(dimensions).size !== dimensions.length) {
+            fail(datasetName, 'defaults.dimensions', 'must not contain duplicates.');
+        }
+        for (const dimension of dimensions) {
+            const definition = config.dimensions[dimension];
+            if (!definition || definition.groupable === false) {
+                fail(datasetName, 'defaults.dimensions', `references non-groupable dimension "${dimension}".`);
+            }
+        }
+        if (config.defaults.timeGrain !== undefined && config.timeKey === undefined) {
+            fail(datasetName, 'defaults.timeGrain', 'requires the dataset to define timeKey.');
+        }
+        if (config.defaults.timeGrain !== undefined && !TIME_GRAINS.has(config.defaults.timeGrain)) {
+            fail(datasetName, 'defaults.timeGrain', 'is not a supported time grain.');
+        }
+        if (dimensions.length === 0 && config.defaults.timeGrain === undefined) {
+            fail(datasetName, 'defaults', 'must define dimensions or timeGrain.');
+        }
+    }
+    for (const [name, dimension] of Object.entries(config.dimensions)) {
+        validateSemanticMetadata(datasetName, `dimensions.${name}`, dimension);
+    }
+    for (const [name, measure] of Object.entries(config.measures ?? {})) {
+        validateSemanticMetadata(datasetName, `measures.${name}`, measure);
+    }
+    for (const [name, filter] of Object.entries(config.filters ?? {})) {
+        validateSemanticMetadata(datasetName, `filters.${name}`, filter);
+    }
+}

package/dist/utils/semantic-metadata.d.ts

@@ -0,0 +1,4 @@
+import type { SemanticMetadata } from '../types.js';
+/** Copy agent metadata without carrying unrelated config fields into public contracts. */
+export declare function snapshotSemanticMetadata(metadata: SemanticMetadata): SemanticMetadata;
+//# sourceMappingURL=semantic-metadata.d.ts.map

package/dist/utils/semantic-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-metadata.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,CAUrF"}

package/dist/utils/semantic-metadata.js

@@ -0,0 +1,13 @@
+import { uniqueSorted } from './canonical-json.js';
+/** Copy agent metadata without carrying unrelated config fields into public contracts. */
+export function snapshotSemanticMetadata(metadata) {
+    return {
+        ...(metadata.examples !== undefined ? { examples: uniqueSorted(metadata.examples) } : {}),
+        ...(metadata.synonyms !== undefined ? { synonyms: uniqueSorted(metadata.synonyms) } : {}),
+        ...(metadata.format !== undefined ? { format: metadata.format } : {}),
+        ...(metadata.unit !== undefined ? { unit: metadata.unit } : {}),
+        ...(metadata.currency !== undefined ? { currency: metadata.currency } : {}),
+        ...(metadata.timezone !== undefined ? { timezone: metadata.timezone } : {}),
+        ...(metadata.sensitivity !== undefined ? { sensitivity: metadata.sensitivity } : {}),
+    };
+}

package/dist/utils/semantic-result-serialization.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Normalize semantic measure columns to the public wire contract.
+ *
+ * ClickHouse's JSON formats can return different JavaScript primitives for
+ * different aggregate result types. Semantic results expose one stable shape:
+ * every non-null measure is a string, while SQL NULL remains null.
+ */
+export declare function serializeSemanticMeasureValues<T>(rows: readonly T[], measureNames: readonly string[]): T[];
+//# sourceMappingURL=semantic-result-serialization.d.ts.map

package/dist/utils/semantic-result-serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-result-serialization.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-result-serialization.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,EAC9C,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,CAAC,EAAE,CAkBL"}

package/dist/utils/semantic-result-serialization.js

@@ -0,0 +1,26 @@
+/**
+ * Normalize semantic measure columns to the public wire contract.
+ *
+ * ClickHouse's JSON formats can return different JavaScript primitives for
+ * different aggregate result types. Semantic results expose one stable shape:
+ * every non-null measure is a string, while SQL NULL remains null.
+ */
+export function serializeSemanticMeasureValues(rows, measureNames) {
+    return rows.map((row) => {
+        if (row === null || typeof row !== 'object') {
+            return row;
+        }
+        const serialized = { ...row };
+        for (const name of measureNames) {
+            const value = serialized[name];
+            if (typeof value === 'number' && !Number.isFinite(value)) {
+                // ClickHouse JSON output emits NaN and infinities as null by default.
+                serialized[name] = null;
+            }
+            else if (value != null) {
+                serialized[name] = String(value);
+            }
+        }
+        return serialized;
+    });
+}

package/dist/utils/semantic-tool.d.ts

@@ -0,0 +1,5 @@
+import type { ZodTypeAny } from 'zod';
+export declare function semanticToolNamePart(name: string): string;
+export declare function parseCanonicalToolInput(schema: ZodTypeAny, input: Record<string, unknown>, label: string): Record<string, unknown>;
+export declare function redactSemanticToolSql(result: unknown, includeSql: boolean): unknown;
+//# sourceMappingURL=semantic-tool.d.ts.map