@hypequery/datasets 0.13.6 → 0.15.0

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-tool.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAEtC,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,MAAM,GACZ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,GAAG,OAAO,CAenF"}

package/dist/utils/semantic-tool.js

@@ -0,0 +1,29 @@
+export function semanticToolNamePart(name) {
+    const normalized = name.replace(/[^A-Za-z0-9_-]/g, '_');
+    return /^[A-Za-z_]/.test(normalized) ? normalized : `_${normalized}`;
+}
+export function parseCanonicalToolInput(schema, input, label) {
+    const result = schema.safeParse(input);
+    if (!result.success) {
+        const issues = result.error.issues.map((issue) => {
+            const path = issue.path.length > 0 ? issue.path.join('.') : 'input';
+            return `${path}: ${issue.message}`;
+        }).join('; ');
+        throw new Error(`Invalid ${label}: ${issues}`);
+    }
+    return result.data;
+}
+export function redactSemanticToolSql(result, includeSql) {
+    if (includeSql || !result || typeof result !== 'object') {
+        return result;
+    }
+    const resultObject = result;
+    if (!resultObject.meta || typeof resultObject.meta !== 'object' || !('sql' in resultObject.meta)) {
+        return result;
+    }
+    const { sql: _sql, ...meta } = resultObject.meta;
+    return {
+        ...resultObject,
+        meta,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.13.6",
+  "version": "0.15.0",
   "description": "Code-first TypeScript semantic layer for ClickHouse datasets, metrics, multi-tenancy, and AI agents",
   "keywords": [
     "semantic-layer",
@@ -42,9 +42,10 @@
     "dist"
   ],
   "dependencies": {
-    "@hypequery/protocol": "^0.11.0",
+    "@hypequery/protocol": "^0.13.0",
     "@noble/hashes": "^1.8.0",
-    "zod": "^3.22.4"
+    "zod": "^3.22.4",
+    "zod-to-json-schema": "^3.23.5"
   },
   "peerDependencies": {
     "zod": "^3.22.4"
@@ -59,7 +60,7 @@
     "typescript": "^5.7.3",
     "@vitest/coverage-v8": "^3.2.6",
     "vitest": "^3.2.6",
-    "@hypequery/protocol-conformance": "^0.10.4"
+    "@hypequery/protocol-conformance": "^0.11.1"
   },
   "repository": {
     "type": "git",