@hypequery/datasets 0.13.6 → 0.15.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/portable-execution-deadline.d.ts

@@ -0,0 +1,4 @@
+import type { PortableSemanticBudget } from '../portable-executor.js';
+/** Abort the underlying request and independently settle the invocation on expiry. */
+export declare function withDeadline<T>(budget: PortableSemanticBudget, signal: AbortSignal | undefined, execute: (signal: AbortSignal) => Promise<T>): Promise<T>;
+//# sourceMappingURL=portable-execution-deadline.d.ts.map

package/dist/utils/portable-execution-deadline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-execution-deadline.d.ts","sourceRoot":"","sources":["../../src/utils/portable-execution-deadline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAGtE,sFAAsF;AACtF,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE,sBAAsB,EAC9B,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3C,OAAO,CAAC,CAAC,CAAC,CAuBZ"}

package/dist/utils/portable-execution-deadline.js

@@ -0,0 +1,27 @@
+import { PortableExecutionBudgetError } from '../portable-execution-errors.js';
+/** Abort the underlying request and independently settle the invocation on expiry. */
+export async function withDeadline(budget, signal, execute) {
+    if (signal?.aborted)
+        throw signal.reason ?? new Error('The invocation was cancelled.');
+    const controller = new AbortController();
+    const abort = () => controller.abort(signal?.reason);
+    let rejectAbort = () => { };
+    const cancelled = new Promise((_resolve, reject) => {
+        rejectAbort = () => reject(controller.signal.reason);
+        controller.signal.addEventListener('abort', rejectAbort, { once: true });
+    });
+    signal?.addEventListener('abort', abort, { once: true });
+    const timer = budget.deadlineMs === undefined ? undefined : setTimeout(() => {
+        controller.abort(new PortableExecutionBudgetError(`The invocation exceeded its ${String(budget.deadlineMs)}ms deadline.`));
+    }, budget.deadlineMs);
+    try {
+        // Promise.race also observes a late driver rejection after cancellation.
+        return await Promise.race([cancelled, execute(controller.signal)]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        signal?.removeEventListener('abort', abort);
+        controller.signal.removeEventListener('abort', rejectAbort);
+    }
+}

package/dist/utils/portable-result-budget.d.ts

@@ -0,0 +1,12 @@
+import type { ProtocolSemanticInvocationResult } from '@hypequery/protocol';
+import type { PortableSemanticBudget } from '../portable-executor.js';
+/**
+ * Bounds a result by row count and serialized size before it leaves the
+ * deployment, so an oversized answer fails rather than being streamed on.
+ *
+ * The byte budget is measured against the whole record a caller receives, not
+ * only its rows, so this agrees with the data plane's own check rather than
+ * undercounting by the envelope.
+ */
+export declare function bounded(result: ProtocolSemanticInvocationResult, budget: PortableSemanticBudget): ProtocolSemanticInvocationResult;
+//# sourceMappingURL=portable-result-budget.d.ts.map

package/dist/utils/portable-result-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-result-budget.d.ts","sourceRoot":"","sources":["../../src/utils/portable-result-budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAGtE;;;;;;;GAOG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,gCAAgC,EACxC,MAAM,EAAE,sBAAsB,GAC7B,gCAAgC,CAelC"}

package/dist/utils/portable-result-budget.js

@@ -0,0 +1,21 @@
+import { PortableExecutionBudgetError } from '../portable-execution-errors.js';
+/**
+ * Bounds a result by row count and serialized size before it leaves the
+ * deployment, so an oversized answer fails rather than being streamed on.
+ *
+ * The byte budget is measured against the whole record a caller receives, not
+ * only its rows, so this agrees with the data plane's own check rather than
+ * undercounting by the envelope.
+ */
+export function bounded(result, budget) {
+    if (result.data.length > budget.maxRows) {
+        throw new PortableExecutionBudgetError(`The result has ${result.data.length} rows; the effective limit is ${budget.maxRows}.`);
+    }
+    if (budget.maxResponseBytes !== undefined) {
+        const bytes = new TextEncoder().encode(JSON.stringify(result)).byteLength;
+        if (bytes > budget.maxResponseBytes) {
+            throw new PortableExecutionBudgetError(`The result is ${bytes} bytes; the effective limit is ${budget.maxResponseBytes}.`);
+        }
+    }
+    return result;
+}

package/dist/utils/portable-semantic-query.d.ts

@@ -0,0 +1,5 @@
+import type { ProtocolSemanticQuery } from '@hypequery/protocol';
+import type { SemanticTenantRuntime } from '../types.js';
+export declare function tenantRuntime(tenant: unknown): SemanticTenantRuntime | undefined;
+export declare function semanticQuery(operation: ProtocolSemanticQuery, maxRows: number): Record<string, unknown>;
+//# sourceMappingURL=portable-semantic-query.d.ts.map

package/dist/utils/portable-semantic-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-semantic-query.d.ts","sourceRoot":"","sources":["../../src/utils/portable-semantic-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAA+B,qBAAqB,EAAa,MAAM,aAAa,CAAC;AAIjG,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,qBAAqB,GAAG,SAAS,CAKhF;AAWD,wBAAgB,aAAa,CAAC,SAAS,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBxG"}

package/dist/utils/portable-semantic-query.js

@@ -0,0 +1,36 @@
+import { PortableExecutionUnsupportedError } from '../portable-execution-errors.js';
+import { rehydrateMeasureFilter } from './protocol-rehydrate-filters.js';
+export function tenantRuntime(tenant) {
+    if (tenant === undefined || tenant === null)
+        return undefined;
+    if (typeof tenant === 'string')
+        return tenant;
+    if (Array.isArray(tenant))
+        return { in: tenant.map(String) };
+    return tenant;
+}
+function operationFilters(operation) {
+    return (operation.filters ?? []).map((expression, index) => rehydrateMeasureFilter(expression, () => new PortableExecutionUnsupportedError(`Filter ${index} is not a field/operator/value comparison, so it cannot be planned.`)));
+}
+export function semanticQuery(operation, maxRows) {
+    const filters = operationFilters(operation);
+    const orderBy = (operation.orderBy ?? []).map(entry => ({
+        field: String(entry.field),
+        direction: entry.direction,
+    }));
+    return {
+        ...(operation.dimensions === undefined
+            ? {}
+            : { dimensions: operation.dimensions.map(String) }),
+        ...(operation.kind === 'dataset' && operation.measures !== undefined
+            ? { measures: operation.measures.map(String) }
+            : {}),
+        ...(filters.length > 0 ? { filters } : {}),
+        ...(orderBy.length > 0 ? { orderBy } : {}),
+        // An omitted limit becomes the budget, so a caller cannot ask for an
+        // unbounded scan by leaving it out.
+        limit: operation.limit ?? maxRows,
+        ...(operation.offset === undefined ? {} : { offset: operation.offset }),
+        ...(operation.by === undefined ? {} : { by: operation.by }),
+    };
+}

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-metric-expressions.d.ts

@@ -0,0 +1,17 @@
+import { type ProtocolExpression, type ProtocolMetricDerivation } from '@hypequery/protocol';
+import type { AggregationSpec, DerivedMetricSpec, MetricFilter } from '../types.js';
+export declare function filterExpression(filter: MetricFilter): ProtocolExpression;
+export declare function metricExpression(spec: AggregationSpec | DerivedMetricSpec): ProtocolExpression;
+/**
+ * The formula in the shape it was authored in, beside the inlined form.
+ *
+ * `metricExpression` above substitutes each input's aggregate where the formula
+ * named it, which states what the metric means but drops the aliases. Those
+ * aliases are the column names of the intermediate aggregate, so a catalog
+ * rebuilt without them computes the same number through different SQL.
+ *
+ * Input order follows `uses` and is not sorted: each entry becomes a column of
+ * that intermediate result in this order.
+ */
+export declare function metricDerivation(spec: DerivedMetricSpec): ProtocolMetricDerivation;
+//# sourceMappingURL=protocol-metric-expressions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-metric-expressions.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-metric-expressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEgB,KAAK,kBAAkB,EAAE,KAAK,wBAAwB,EAC5E,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsCpF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB,CAgBzE;AA+CD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,kBAAkB,CAQ9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,wBAAwB,CASlF"}

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

@@ -0,0 +1,118 @@
+import { parseProtocolIdentifier, parseProtocolQualifiedIdentifier, validateCanonicalValue, } from '@hypequery/protocol';
+function canonicalValue(input) {
+    if (Array.isArray(input)) {
+        return validateCanonicalValue({
+            $hypequery: {
+                type: 'array',
+                version: 1,
+                values: input.map(canonicalValue),
+            },
+        });
+    }
+    if (typeof input === 'object' && input !== null) {
+        if ('$hypequery' in input)
+            return validateCanonicalValue(input);
+        const prototype = Object.getPrototypeOf(input);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError('Dataset protocol adapter only accepts plain filter values.');
+        }
+        return validateCanonicalValue({
+            $hypequery: {
+                type: 'map',
+                version: 1,
+                entries: Object.entries(input)
+                    .sort(([left], [right]) => left.localeCompare(right))
+                    .map(([key, value]) => [key, canonicalValue(value)]),
+            },
+        });
+    }
+    return validateCanonicalValue(input);
+}
+export function filterExpression(filter) {
+    const left = {
+        kind: 'reference',
+        name: parseProtocolQualifiedIdentifier(filter.field),
+    };
+    const right = {
+        kind: 'literal',
+        value: canonicalValue(filter.value),
+    };
+    const result = {
+        kind: 'comparison',
+        operator: filter.operator,
+        left,
+        right,
+    };
+    return result;
+}
+function aggregationExpression(spec) {
+    const result = {
+        kind: 'aggregate',
+        aggregation: spec.aggregation,
+        field: parseProtocolQualifiedIdentifier(spec.field),
+        ...(spec.argField !== undefined
+            ? { argField: parseProtocolQualifiedIdentifier(spec.argField) }
+            : {}),
+        ...(spec.level !== undefined ? { level: spec.level } : {}),
+        ...(spec.filters?.length
+            ? { filters: spec.filters.map(filterExpression) }
+            : {}),
+    };
+    return result;
+}
+function semanticExpression(expression, references = {}) {
+    switch (expression.kind) {
+        case 'ref':
+            return references[expression.name]
+                ?? {
+                    kind: 'reference',
+                    name: parseProtocolQualifiedIdentifier(expression.name),
+                };
+        case 'literal':
+            return { kind: 'literal', value: canonicalValue(expression.value) };
+        case 'binary':
+            return {
+                kind: 'binary',
+                operator: expression.operator,
+                left: semanticExpression(expression.left, references),
+                right: semanticExpression(expression.right, references),
+            };
+        case 'function':
+            return {
+                kind: 'call',
+                function: expression.name,
+                args: expression.args.map(argument => semanticExpression(argument, references)),
+            };
+    }
+}
+export function metricExpression(spec) {
+    if (spec.__type === 'aggregation_spec')
+        return aggregationExpression(spec);
+    const aliases = Object.fromEntries(Object.keys(spec.uses).map(alias => [alias, alias]));
+    const references = Object.fromEntries(Object.entries(spec.uses).map(([alias, metric]) => [
+        alias,
+        aggregationExpression(metric.spec),
+    ]));
+    return semanticExpression(spec.formula(aliases).expression, references);
+}
+/**
+ * The formula in the shape it was authored in, beside the inlined form.
+ *
+ * `metricExpression` above substitutes each input's aggregate where the formula
+ * named it, which states what the metric means but drops the aliases. Those
+ * aliases are the column names of the intermediate aggregate, so a catalog
+ * rebuilt without them computes the same number through different SQL.
+ *
+ * Input order follows `uses` and is not sorted: each entry becomes a column of
+ * that intermediate result in this order.
+ */
+export function metricDerivation(spec) {
+    const aliases = Object.fromEntries(Object.keys(spec.uses).map(alias => [alias, alias]));
+    return {
+        inputs: Object.entries(spec.uses).map(([alias, metric]) => ({
+            alias: parseProtocolIdentifier(alias),
+            expression: aggregationExpression(metric.spec),
+        })),
+        expression: semanticExpression(spec.formula(aliases).expression),
+    };
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Rebuilds a derived metric's formula from the contract's authored form.
+ *
+ * The formula is reconstructed by calling the same helpers in `formulas.ts`
+ * that authored it, rather than by compiling the expression to SQL here. That
+ * is deliberate: those helpers carry the `toSQL` closures that decide spacing,
+ * parenthesisation, and function spelling, so reusing them makes byte-identity
+ * structural. A second compiler would be a second place for that spelling to
+ * live, and the two would drift the first time either changed.
+ */
+import type { ProtocolMetricDerivation } from '@hypequery/protocol';
+import type { FormulaExpr } from '../types.js';
+type Unsupported = (reason: string) => Error;
+/**
+ * The formula function a derived metric spec expects.
+ *
+ * The returned function maps each declared alias through the caller-supplied
+ * `inputs` record, exactly as an authored formula does — both the plan builder
+ * and the query-builder path pass alias-to-alias, so the emitted column names
+ * are the ones the contract declared.
+ *
+ * The formula is built once here as well, so a malformed one is refused when
+ * the metric is rebuilt rather than on the first query that reaches it.
+ */
+export declare function rehydrateDerivedFormula(derivation: ProtocolMetricDerivation, unsupported: Unsupported): (inputs: Record<string, string>) => FormulaExpr;
+export {};
+//# sourceMappingURL=protocol-rehydrate-derivation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-rehydrate-derivation.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-rehydrate-derivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAsB,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAYxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAQ/C,KAAK,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,KAAK,CAAC;AA8G7C;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,wBAAwB,EACpC,WAAW,EAAE,WAAW,GACvB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,WAAW,CAGjD"}

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

@@ -0,0 +1,104 @@
+/**
+ * Rebuilds a derived metric's formula from the contract's authored form.
+ *
+ * The formula is reconstructed by calling the same helpers in `formulas.ts`
+ * that authored it, rather than by compiling the expression to SQL here. That
+ * is deliberate: those helpers carry the `toSQL` closures that decide spacing,
+ * parenthesisation, and function spelling, so reusing them makes byte-identity
+ * structural. A second compiler would be a second place for that spelling to
+ * live, and the two would drift the first time either changed.
+ */
+import { add, ceil, coalesce, divide, floor, multiply, nullIfZero, round, subtract, } from '../formulas.js';
+const BINARY = {
+    add, subtract, multiply, divide,
+};
+function arity(args, expected, name, unsupported) {
+    if (args.length !== expected) {
+        throw unsupported(`"${name}" takes ${expected} argument(s), received ${args.length}`);
+    }
+}
+function literalNumber(expression, unsupported) {
+    if (expression.kind !== 'literal' || typeof expression.value !== 'number') {
+        throw unsupported('expected a numeric literal argument');
+    }
+    return expression.value;
+}
+/**
+ * A `coalesce` fallback, the one position that accepts a bare value.
+ *
+ * `formulas.ts` renders a number through `String(...)` and anything else
+ * through the operand path, so both round-trip to the same SQL.
+ */
+function fallback(expression, resolve, unsupported) {
+    if (expression.kind !== 'literal')
+        return operand(expression, resolve, unsupported);
+    if (typeof expression.value !== 'number') {
+        throw unsupported('a "coalesce" fallback literal must be numeric');
+    }
+    return expression.value;
+}
+function operand(expression, resolve, unsupported) {
+    switch (expression.kind) {
+        case 'reference':
+            // An alias, or a column the formula named directly. `resolveArg` in
+            // `formulas.ts` passes a string through unchanged, which is what the
+            // authored form did with the same name.
+            return resolve(String(expression.name));
+        case 'binary': {
+            const build = BINARY[expression.operator];
+            if (build === undefined)
+                throw unsupported(`unsupported operator "${expression.operator}"`);
+            return build(operand(expression.left, resolve, unsupported), operand(expression.right, resolve, unsupported));
+        }
+        case 'call':
+            switch (expression.function) {
+                case 'nullIfZero':
+                    arity(expression.args, 1, 'nullIfZero', unsupported);
+                    return nullIfZero(operand(expression.args[0], resolve, unsupported));
+                case 'floor':
+                    arity(expression.args, 1, 'floor', unsupported);
+                    return floor(operand(expression.args[0], resolve, unsupported));
+                case 'ceil':
+                    arity(expression.args, 1, 'ceil', unsupported);
+                    return ceil(operand(expression.args[0], resolve, unsupported));
+                case 'round':
+                    arity(expression.args, 2, 'round', unsupported);
+                    return round(operand(expression.args[0], resolve, unsupported), literalNumber(expression.args[1], unsupported));
+                case 'coalesce':
+                    arity(expression.args, 2, 'coalesce', unsupported);
+                    return coalesce(operand(expression.args[0], resolve, unsupported), fallback(expression.args[1], resolve, unsupported));
+                default:
+                    throw unsupported(`unsupported function "${String(expression.function)}"`);
+            }
+        default:
+            // A literal outside a `round` precision or `coalesce` fallback, or an
+            // aggregate that should have been carried as a named input. Either way
+            // the authoring API cannot express it, so rebuilding would be a guess.
+            throw unsupported(`a formula cannot contain a "${expression.kind}" expression here`);
+    }
+}
+function buildFormula(derivation, resolve, unsupported) {
+    const built = operand(derivation.expression, resolve, unsupported);
+    if (typeof built === 'string') {
+        // `spec.formula(...)` must return a `FormulaExpr`. A formula that is a bare
+        // reference names one of its inputs instead of combining them, which the
+        // authoring API cannot produce.
+        throw unsupported('a formula must combine its inputs rather than name one');
+    }
+    return built;
+}
+/**
+ * The formula function a derived metric spec expects.
+ *
+ * The returned function maps each declared alias through the caller-supplied
+ * `inputs` record, exactly as an authored formula does — both the plan builder
+ * and the query-builder path pass alias-to-alias, so the emitted column names
+ * are the ones the contract declared.
+ *
+ * The formula is built once here as well, so a malformed one is refused when
+ * the metric is rebuilt rather than on the first query that reaches it.
+ */
+export function rehydrateDerivedFormula(derivation, unsupported) {
+    buildFormula(derivation, name => name, unsupported);
+    return inputs => buildFormula(derivation, name => inputs[name] ?? name, unsupported);
+}

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.`);
+    }
+}