@hypequery/datasets 0.14.0 → 0.15.0

package/dist/index.d.ts

@@ -19,6 +19,8 @@ export { rehydrateProtocolDatasets, UnsupportedContractFeatureError, } from './p
 export type { RehydratedDataset, RehydrateProtocolDatasetsOptions, } from './protocol-rehydrate.js';
 export { buildProtocolDatasetContract } from './protocol-adapter.js';
 export type { BuildProtocolDatasetContractOptions } from './protocol-adapter.js';
+export { createPortableSemanticExecutor, PortableExecutionBudgetError, PortableExecutionTenantError, PortableExecutionUnsupportedError, } from './portable-executor.js';
+export type { PortableSemanticBudget, PortableSemanticExecutionInput, PortableSemanticExecutorOptions, } from './portable-executor.js';
 export { compilePortableSqlExpression, DEFAULT_SQL_PORTABILITY_LIMITS, } from './sql-portability.js';
 export type { SqlPortabilityIssue, SqlPortabilityIssueCode, SqlPortabilityLimits, SqlPortabilityOptions, SqlPortabilityResult, } from './sql-portability.js';
 export type { SemanticContract, SerializeSemanticContractOptions, ContractDataset, ContractDimension, ContractMeasure, ContractMetric, ContractFilter, ContractRelationship, } from './contract.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -26,6 +26,8 @@ export { serializeSemanticContract, contractToStableJson, hashContract, SEMANTIC
 // Portable deployment contract adapter
 export { rehydrateProtocolDatasets, UnsupportedContractFeatureError, } from './protocol-rehydrate.js';
 export { buildProtocolDatasetContract } from './protocol-adapter.js';
+// Portable native execution of a semantic invocation (decision 0005).
+export { createPortableSemanticExecutor, PortableExecutionBudgetError, PortableExecutionTenantError, PortableExecutionUnsupportedError, } from './portable-executor.js';
 // SQL portability compiler (R1A-07)
 export { compilePortableSqlExpression, DEFAULT_SQL_PORTABILITY_LIMITS, } from './sql-portability.js';
 // Agent/tool metadata

package/dist/portable-execution-errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * An error that deliberately claims a portable failure category.
+ *
+ * A data plane forwards the category and message of an error carrying this
+ * marker instead of reporting a generic executor failure, so the marker — not
+ * the shape of the error — is what grants that. A provider exception cannot
+ * acquire one by accident, which is the point: the two packages are siblings
+ * and cannot share a class, but a raw driver error must never be able to pass
+ * itself off as a deliberate claim and put its own message in front of a
+ * caller.
+ *
+ * Deliberately not exported. The three errors below are, because this package's
+ * own executor throws them; this base is only how they share the marker. A
+ * supported way for someone else's executor to claim a category belongs beside
+ * the data plane that honours it, not beside one implementation of the slot it
+ * fills.
+ */
+declare abstract class PortableExecutionError extends Error {
+    /** The opt-in a data plane checks before trusting anything below it. */
+    readonly hypequerySemanticFailure: true;
+    abstract readonly code: string;
+    abstract readonly category: string;
+}
+/** Signalled when portable execution cannot faithfully serve a target. */
+export declare class PortableExecutionUnsupportedError extends PortableExecutionError {
+    readonly code = "HQ_SEMANTIC_UNSUPPORTED_CAPABILITY";
+    readonly category = "unsupported-capability";
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class PortableExecutionBudgetError extends PortableExecutionError {
+    readonly code = "HQ_SEMANTIC_BUDGET_EXCEEDED";
+    readonly category = "budget-exceeded";
+    constructor(message: string);
+}
+/**
+ * Signalled when tenancy cannot be enforced for a call that resolved a tenant.
+ *
+ * `configuration-invalid` rather than a caller-facing category: nothing the
+ * caller sent is wrong, and nothing it can send would make the call succeed.
+ */
+export declare class PortableExecutionTenantError extends PortableExecutionError {
+    readonly code = "HQ_SEMANTIC_TENANT_UNENFORCEABLE";
+    readonly category = "configuration-invalid";
+    constructor(message: string);
+}
+export {};
+//# sourceMappingURL=portable-execution-errors.d.ts.map

package/dist/portable-execution-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-execution-errors.d.ts","sourceRoot":"","sources":["../src/portable-execution-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,uBAAe,sBAAuB,SAAQ,KAAK;IACjD,wEAAwE;IACxE,QAAQ,CAAC,wBAAwB,EAAG,IAAI,CAAU;IAClD,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CACpC;AAED,0EAA0E;AAC1E,qBAAa,iCAAkC,SAAQ,sBAAsB;IAC3E,QAAQ,CAAC,IAAI,wCAAwC;IACrD,QAAQ,CAAC,QAAQ,4BAA4B;gBAEjC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAI/D;AAED,qBAAa,4BAA6B,SAAQ,sBAAsB;IACtE,QAAQ,CAAC,IAAI,iCAAiC;IAC9C,QAAQ,CAAC,QAAQ,qBAAqB;gBAE1B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,4BAA6B,SAAQ,sBAAsB;IACtE,QAAQ,CAAC,IAAI,sCAAsC;IACnD,QAAQ,CAAC,QAAQ,2BAA2B;gBAEhC,OAAO,EAAE,MAAM;CAI5B"}

package/dist/portable-execution-errors.js

@@ -0,0 +1,52 @@
+/**
+ * An error that deliberately claims a portable failure category.
+ *
+ * A data plane forwards the category and message of an error carrying this
+ * marker instead of reporting a generic executor failure, so the marker — not
+ * the shape of the error — is what grants that. A provider exception cannot
+ * acquire one by accident, which is the point: the two packages are siblings
+ * and cannot share a class, but a raw driver error must never be able to pass
+ * itself off as a deliberate claim and put its own message in front of a
+ * caller.
+ *
+ * Deliberately not exported. The three errors below are, because this package's
+ * own executor throws them; this base is only how they share the marker. A
+ * supported way for someone else's executor to claim a category belongs beside
+ * the data plane that honours it, not beside one implementation of the slot it
+ * fills.
+ */
+class PortableExecutionError extends Error {
+    /** The opt-in a data plane checks before trusting anything below it. */
+    hypequerySemanticFailure = true;
+}
+/** Signalled when portable execution cannot faithfully serve a target. */
+export class PortableExecutionUnsupportedError extends PortableExecutionError {
+    code = 'HQ_SEMANTIC_UNSUPPORTED_CAPABILITY';
+    category = 'unsupported-capability';
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = 'PortableExecutionUnsupportedError';
+    }
+}
+export class PortableExecutionBudgetError extends PortableExecutionError {
+    code = 'HQ_SEMANTIC_BUDGET_EXCEEDED';
+    category = 'budget-exceeded';
+    constructor(message) {
+        super(message);
+        this.name = 'PortableExecutionBudgetError';
+    }
+}
+/**
+ * Signalled when tenancy cannot be enforced for a call that resolved a tenant.
+ *
+ * `configuration-invalid` rather than a caller-facing category: nothing the
+ * caller sent is wrong, and nothing it can send would make the call succeed.
+ */
+export class PortableExecutionTenantError extends PortableExecutionError {
+    code = 'HQ_SEMANTIC_TENANT_UNENFORCEABLE';
+    category = 'configuration-invalid';
+    constructor(message) {
+        super(message);
+        this.name = 'PortableExecutionTenantError';
+    }
+}

package/dist/portable-executor.d.ts

@@ -0,0 +1,61 @@
+export { PortableExecutionUnsupportedError, PortableExecutionBudgetError, PortableExecutionTenantError } from './portable-execution-errors.js';
+/**
+ * Portable native execution of a semantic invocation.
+ *
+ * Decision 0005 chose this over a supervised runtime binding: resolve the
+ * dataset or metric from the validated active contract, rebuild its catalog
+ * with `rehydrateProtocolDatasets`, and plan the query with the existing
+ * semantic planner. No customer module is loaded and no isolated runtime is
+ * required, so customer code only ever runs on the author's machine at deploy
+ * time.
+ *
+ * The input is typed structurally rather than against
+ * `@hypequery/deployment`'s execution input, so this package stays a sibling of
+ * that one. A caller wires the returned function into the data plane's injected
+ * `execute` slot.
+ */
+import type { ProtocolDatasetContract, ProtocolDatasetMetric, ProtocolSemanticInvocationResult, ProtocolSemanticQuery } from '@hypequery/protocol';
+import type { QueryBuilderFactoryInput } from './query-builder-protocol.js';
+/** Ceilings the data plane already reduced to the most restrictive value. */
+export interface PortableSemanticBudget {
+    readonly maxRows: number;
+    readonly deadlineMs?: number;
+    readonly maxResponseBytes?: number;
+}
+/**
+ * Structurally compatible with the deployment data plane's execution input.
+ * Only the fields portable execution reads are declared, so the two packages
+ * stay independent.
+ */
+export interface PortableSemanticExecutionInput {
+    readonly deployment: {
+        readonly datasets: readonly ProtocolDatasetContract[];
+    };
+    readonly dataset: ProtocolDatasetContract;
+    readonly metric?: ProtocolDatasetMetric;
+    readonly operation: ProtocolSemanticQuery;
+    /** Resolved by the provider callback; never caller-supplied. */
+    readonly tenant: unknown;
+    readonly budget: PortableSemanticBudget;
+    /** Identifies the immutable generation, and keys the rebuilt catalog. */
+    readonly activationRevision: string;
+    readonly signal?: AbortSignal;
+}
+export interface PortableSemanticExecutorOptions {
+    readonly queryBuilder: QueryBuilderFactoryInput;
+    /**
+     * Rebuilt catalogs are memoized by activation revision. A release is
+     * immutable and content-addressed, so the revision is an exact key with no
+     * invalidation problem. Only the most recent generation is kept here;
+     * `CLOUD-09` owns the bounded multi-release cache.
+     */
+    readonly cacheRebuiltCatalogs?: boolean;
+}
+/**
+ * Build the executor the deployment data plane injects.
+ *
+ * Returns the portable result record; the data plane validates it before it
+ * reaches a caller.
+ */
+export declare function createPortableSemanticExecutor(options: PortableSemanticExecutorOptions): (input: PortableSemanticExecutionInput) => Promise<ProtocolSemanticInvocationResult>;
+//# sourceMappingURL=portable-executor.d.ts.map

package/dist/portable-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-executor.d.ts","sourceRoot":"","sources":["../src/portable-executor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iCAAiC,EAAE,4BAA4B,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAK/I;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,uBAAuB,EACvB,qBAAqB,EACrB,gCAAgC,EAChC,qBAAqB,EACtB,MAAM,qBAAqB,CAAC;AAO7B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAC5E,6EAA6E;AAC7E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAA;KAAE,CAAC;IAC/E,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;IAC1C,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,yEAAyE;IACzE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,YAAY,EAAE,wBAAwB,CAAC;IAChD;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAID;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,CAAC,KAAK,EAAE,8BAA8B,KAAK,OAAO,CAAC,gCAAgC,CAAC,CAgGtF"}

package/dist/portable-executor.js

@@ -0,0 +1,90 @@
+import { PortableExecutionUnsupportedError, PortableExecutionTenantError } from './portable-execution-errors.js';
+export { PortableExecutionUnsupportedError, PortableExecutionBudgetError, PortableExecutionTenantError } from './portable-execution-errors.js';
+import { tenantRuntime, semanticQuery } from './utils/portable-semantic-query.js';
+import { bounded } from './utils/portable-result-budget.js';
+import { withDeadline } from './utils/portable-execution-deadline.js';
+import { createDatasetClient } from './executor.js';
+import { rehydrateProtocolDatasets, UnsupportedContractFeatureError, } from './protocol-rehydrate.js';
+/**
+ * Build the executor the deployment data plane injects.
+ *
+ * Returns the portable result record; the data plane validates it before it
+ * reaches a caller.
+ */
+export function createPortableSemanticExecutor(options) {
+    const client = createDatasetClient({ queryBuilder: options.queryBuilder });
+    let memo;
+    function registryFor(input) {
+        if (options.cacheRebuiltCatalogs !== false && memo?.revision === input.activationRevision) {
+            return memo.registry;
+        }
+        let registry;
+        try {
+            // Skip rather than throw: a single derived metric anywhere in the
+            // contract must not make every other dataset unexecutable. The requested
+            // target is still refused below when it is one of the skipped ones.
+            registry = rehydrateProtocolDatasets(input.deployment.datasets, {
+                onUnsupportedMetric: 'skip',
+            });
+        }
+        catch (error) {
+            if (error instanceof UnsupportedContractFeatureError) {
+                // Decision 0005: a surface portable execution cannot reproduce is
+                // excluded from it, never approximated.
+                throw new PortableExecutionUnsupportedError(error.message, { cause: error });
+            }
+            throw error;
+        }
+        memo = { revision: input.activationRevision, registry };
+        return registry;
+    }
+    return async function execute(input) {
+        if (input.metric?.kind === 'derived-metric' && input.metric.derivation === undefined) {
+            // A derived metric is executable once the contract carries the formula in
+            // the shape it was authored in. One written before that field existed
+            // still states only what the metric means, not the aliases its SQL is
+            // written in terms of, so it stays excluded rather than approximated.
+            throw new PortableExecutionUnsupportedError(`Metric "${String(input.metric.name)}" is derived, and this deployment contract does not `
+                + 'carry the authored formula portable execution needs to plan it.');
+        }
+        const registry = registryFor(input);
+        const rebuilt = registry[String(input.dataset.name)];
+        if (rebuilt === undefined) {
+            throw new PortableExecutionUnsupportedError(`Dataset "${String(input.dataset.name)}" is not part of the activated contract.`);
+        }
+        const target = input.metric === undefined
+            ? rebuilt
+            : rebuilt.metrics[String(input.metric.name)];
+        if (target === undefined) {
+            throw new PortableExecutionUnsupportedError(`Metric "${String(input.metric?.name)}" could not be rebuilt from the contract.`);
+        }
+        const tenant = tenantRuntime(input.tenant);
+        // A tenant with nothing to scope by is the one failure that is silent
+        // everywhere else: the runtime accepts it, the planner emits no predicate,
+        // and the query reads every tenant while each layer believes tenancy was
+        // enforced. Contract validation refuses that shape, but this executor is
+        // exported on its own and typed structurally, so it must refuse it too
+        // rather than trusting the caller to have validated the contract.
+        if (tenant !== undefined && rebuilt.tenantKey === undefined) {
+            throw new PortableExecutionTenantError(`Dataset "${String(input.dataset.name)}" declares no tenant field, so a resolved tenant `
+                + 'cannot be applied to it.');
+        }
+        const query = semanticQuery(input.operation, input.budget.maxRows);
+        const output = await withDeadline(input.budget, input.signal, async (signal) => (await client.execute(target, query, {
+            abortSignal: signal,
+            ...(tenant === undefined ? {} : { runtime: { tenant } }),
+        })));
+        const rows = output.data ?? [];
+        const pagination = output.meta?.pagination;
+        return bounded(Object.freeze({
+            kind: 'hypequery-semantic-invocation-result',
+            version: 1,
+            activationRevision: input.activationRevision,
+            data: rows,
+            meta: {
+                rowCount: rows.length,
+                ...(pagination === undefined ? {} : { pagination }),
+            },
+        }), input.budget);
+    };
+}

package/dist/protocol-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,uBAAuB,EAE5B,KAAK,sBAAsB,EAI5B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAEV,kBAAkB,EAIlB,YAAY,EAEb,MAAM,YAAY,CAAC;AAUpB,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAC3C,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;CAC7E;AAyLD;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,mCAAwC,GAChD,uBAAuB,CAiHzB"}
+{"version":3,"file":"protocol-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,uBAAuB,EAE5B,KAAK,sBAAsB,EAG5B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,kBAAkB,EAElB,YAAY,EAEb,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAC3C,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;CAC7E;AAsFD;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,mCAAwC,GAChD,uBAAuB,CAiHzB"}

package/dist/protocol-adapter.js

@@ -1,4 +1,5 @@
-import { parseProtocolIdentifier, parseProtocolQualifiedIdentifier, validateCanonicalValue, validateProtocolDatasetContract, } from '@hypequery/protocol';
+import { filterExpression, metricExpression, metricDerivation } from './utils/protocol-metric-expressions.js';
+import { parseProtocolIdentifier, parseProtocolQualifiedIdentifier, validateProtocolDatasetContract, } from '@hypequery/protocol';
 import { SEMANTIC_FILTER_OPERATORS } from './constants.js';
 import { toProtocolSemanticMetadata } from './utils/protocol-semantic-metadata.js';
 function byName(left, right) {
@@ -17,107 +18,11 @@ function fieldSchema(type) {
             return { kind: 'any' };
     }
 }
-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);
-}
-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)),
-            };
-    }
-}
 function unwrapMetric(metric) {
     return metric.__type === 'grained_metric_ref'
         ? { ref: metric.metric, grain: metric.grain }
         : { ref: metric };
 }
-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);
-}
 function metricContract(exposedName, metric, endpoint) {
     const { ref, grain } = unwrapMetric(metric);
     const contract = metric.contract();
@@ -129,6 +34,9 @@ function metricContract(exposedName, metric, endpoint) {
                 ? 'derived-metric'
                 : 'metric',
         expression: metricExpression(ref.spec),
+        ...(ref.spec.__type === 'derived_metric_spec'
+            ? { derivation: metricDerivation(ref.spec) }
+            : {}),
         dimensions: [...contract.dimensions].sort().map(parseProtocolQualifiedIdentifier),
         filters: [...contract.filters].sort().map(parseProtocolIdentifier),
         grains: [...contract.grains].sort(),

package/dist/protocol-rehydrate.d.ts

@@ -23,6 +23,16 @@ export interface RehydrateProtocolDatasetsOptions {
      * an operational concern of whoever runs the query, not of the deployment.
      */
     readonly cache?: DatasetCachePolicy;
+    /**
+     * What to do with a metric portable execution cannot rebuild.
+     *
+     * `throw` (the default) refuses the whole contract, which is right when a
+     * caller is checking whether a deployment is fully portable. `skip` omits
+     * just that metric, which is what a runtime wants: one derived metric must
+     * not make every other dataset in the deployment unexecutable. A caller that
+     * skips is responsible for refusing the skipped target at the point of use.
+     */
+    readonly onUnsupportedMetric?: 'throw' | 'skip';
 }
 /**
  * Thrown when a contract describes something portable execution cannot rebuild.

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

@@ -1 +1 @@
-{"version":3,"file":"protocol-rehydrate.d.ts","sourceRoot":"","sources":["../src/protocol-rehydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,uBAAuB,EAGxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAIlB,YAAY,EAIb,MAAM,YAAY,CAAC;AAKpB,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG;IACnD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;CACrC;AAED;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAMjE;AAmLD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,uBAAuB,EAAE,EAC7C,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CA8D7C"}
+{"version":3,"file":"protocol-rehydrate.d.ts","sourceRoot":"","sources":["../src/protocol-rehydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,uBAAuB,EAKxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAKlB,YAAY,EAIb,MAAM,YAAY,CAAC;AAMpB,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG;IACnD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACjD;AAED;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAMjE;AAwOD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,uBAAuB,EAAE,EAC7C,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAqE7C"}

package/dist/protocol-rehydrate.js

@@ -14,6 +14,7 @@
 import { dataset } from './dataset.js';
 import { snapshotSemanticMetadata } from './utils/semantic-metadata.js';
 import { withContractCapabilities } from './utils/protocol-metric-capabilities.js';
+import { rehydrateDerivedFormula } from './utils/protocol-rehydrate-derivation.js';
 import { rehydrateMeasureFilter } from './utils/protocol-rehydrate-filters.js';
 /**
  * Thrown when a contract describes something portable execution cannot rebuild.
@@ -119,38 +120,75 @@ function aggregationKey(value) {
         value.filters ?? [],
     ]);
 }
-function rehydrateMetric(instance, contract, metric) {
-    const name = String(metric.name);
-    if (metric.kind === 'derived-metric') {
-        // The symbolic expression a derived metric needs is not carried by contract
-        // v1; CORE-17 adds it. Until then this fails closed rather than guessing.
-        throw new UnsupportedContractFeatureError(instance.name, `metric "${name}"`, 'a derived metric requires its symbolic expression, which deployment contract v1 does not carry');
-    }
-    const expression = metric.expression;
+/**
+ * The declared measure an aggregate expression was built from.
+ *
+ * A metric's expression names an aggregation and a field, not the measure that
+ * produced it, so the measure is recovered by matching aggregation identity.
+ */
+function measureForAggregate(instance, contract, subject, expression) {
     if (expression.kind !== 'aggregate') {
-        throw new UnsupportedContractFeatureError(instance.name, `metric "${name}"`, `expected an aggregate expression, received "${expression.kind}"`);
+        throw new UnsupportedContractFeatureError(instance.name, subject, `expected an aggregate expression, received "${expression.kind}"`);
     }
     const field = String(expression.field);
     const candidates = contract.measures.filter(measure => (aggregationKey(measure) === aggregationKey(expression)));
     if (candidates.length === 0) {
-        throw new UnsupportedContractFeatureError(instance.name, `metric "${name}"`, `no declared measure matches ${expression.aggregation}(${field})`);
+        throw new UnsupportedContractFeatureError(instance.name, subject, `no declared measure matches ${expression.aggregation}(${field})`);
     }
     // A metric expression carries no raw SQL, so two measures that share an
     // aggregation identity but override SQL differently are indistinguishable in
     // contract v1. Binding to either would be a guess at which SQL to emit.
     const distinctSql = new Set(candidates.map(measure => measure.sql?.sql ?? null));
     if (distinctSql.size > 1) {
-        throw new UnsupportedContractFeatureError(instance.name, `metric "${name}"`, `${candidates.map(measure => `"${String(measure.name)}"`).join(' and ')} share `
+        throw new UnsupportedContractFeatureError(instance.name, subject, `${candidates.map(measure => `"${String(measure.name)}"`).join(' and ')} share `
             + `${expression.aggregation}(${field}) but emit different SQL, so the contract cannot `
             + 'say which one this metric was built from');
     }
-    const measureName = candidates[0].name;
-    const base = instance.metric(name, {
-        measure: measureName,
+    return String(candidates[0].name);
+}
+/**
+ * Rebuilds the `uses` map and formula of a derived metric.
+ *
+ * Each input becomes a base metric named by its alias, because that alias is
+ * what both plan builders emit as the column of the intermediate aggregate.
+ */
+function derivedMetricConfig(instance, contract, subject, derivation) {
+    const unsupported = (reason) => new UnsupportedContractFeatureError(instance.name, subject, reason);
+    const uses = Object.fromEntries(derivation.inputs.map(input => {
+        const alias = String(input.alias);
+        return [
+            alias,
+            instance.metric(alias, {
+                measure: measureForAggregate(instance, contract, `${subject} input "${alias}"`, input.expression),
+            }),
+        ];
+    }));
+    return { uses, formula: rehydrateDerivedFormula(derivation, unsupported) };
+}
+function rehydrateMetric(instance, contract, metric) {
+    const name = String(metric.name);
+    const subject = `metric "${name}"`;
+    const derived = metric.expression.kind !== 'aggregate';
+    if (derived && metric.derivation === undefined) {
+        // The inlined expression states what a derived metric means but drops the
+        // aliases its SQL is written in terms of. Without them a rebuild computes
+        // the same number through different SQL, which decision 0005 excludes.
+        throw new UnsupportedContractFeatureError(instance.name, subject, 'a derived metric requires its authored formula, which this contract does not carry');
+    }
+    const metadata = {
         ...snapshotSemanticMetadata(metric),
         ...(metric.label !== undefined ? { label: metric.label } : {}),
         ...(metric.description !== undefined ? { description: metric.description } : {}),
-    });
+    };
+    const base = (metric.derivation === undefined
+        ? instance.metric(name, {
+            measure: measureForAggregate(instance, contract, subject, metric.expression),
+            ...metadata,
+        })
+        : instance.metric(name, {
+            ...derivedMetricConfig(instance, contract, subject, metric.derivation),
+            ...metadata,
+        }));
     const handle = metric.grain === undefined
         ? base
         : base.by(metric.grain);
@@ -210,7 +248,15 @@ export function rehydrateProtocolDatasets(contracts, options = {}) {
         const instance = instances.get(name);
         const metrics = {};
         for (const metric of contract.metrics) {
-            metrics[String(metric.name)] = rehydrateMetric(instance, contract, metric);
+            try {
+                metrics[String(metric.name)] = rehydrateMetric(instance, contract, metric);
+            }
+            catch (error) {
+                if (options.onUnsupportedMetric !== 'skip'
+                    || !(error instanceof UnsupportedContractFeatureError)) {
+                    throw error;
+                }
+            }
         }
         registry[name] = Object.assign(Object.create(Object.getPrototypeOf(instance)), instance, { metrics });
     }

package/dist/semantic-query-schema.d.ts

@@ -19,6 +19,18 @@ export interface SemanticQuerySchemaOptions extends SemanticQuerySchemaLimits {
     requireSelection?: boolean;
     /** Validate result limits in the schema. Disable when a consumer clamps them. */
     enforceResultLimit?: boolean;
+    /**
+     * Datasets that may be queried directly. Defaults to all of them.
+     *
+     * A dataset outside this list still contributes its metrics and can still be
+     * joined to, but is not offered as a `query_dataset` target. That split is not
+     * hypothetical: a deployment contract authorizes a dataset and each of its
+     * metrics through separate endpoint policies, so a caller can be entitled to
+     * a metric on a dataset it may not query directly. Compiling one schema for
+     * both would either advertise a target the caller cannot use or hide a metric
+     * it can.
+     */
+    queryableDatasets?: readonly string[];
 }
 /** Metric-specific query capabilities used when they are not embedded in the Dataset source. */
 export type SemanticMetricQueryContract = Pick<MetricCatalogEntry, 'dimensions' | 'filters' | 'grains' | 'grain'>;

package/dist/semantic-query-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-query-schema.d.ts","sourceRoot":"","sources":["../src/semantic-query-schema.ts"],"names":[],"mappings":"AAEA,OAAO,EAAK,KAAK,UAAU,EAAE,MAAM,KAAK,CAAC;AAEzC,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,MAAM,WAAW,yBAAyB;IACxC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA2B,SAAQ,yBAAyB;IAC3E,iFAAiF;IACjF,UAAU,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;IAC5B,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,gGAAgG;AAChG,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,kBAAkB,EAClB,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAC9C,CAAC;AAEF,eAAO,MAAM,oCAAoC;;;;;;;EAO/C,CAAC;AAEH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,UAAU,CAAC;IAC5C,QAAQ,CAAC,qBAAqB,EAAE,UAAU,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,oFAAoF;AACpF,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,GAAG,cAAc,CAAC;AA6I9E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,yBAAyB,EAClC,OAAO,GAAE,0BAA+B,GACvC,UAAU,CAOZ;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,0BAA+B,EACxC,cAAc,CAAC,EAAE,2BAA2B,GAC3C,UAAU,CAaZ;AAsBD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3C,UAAU,CAMZ;AAyBD,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,EACnD,OAAO,GAAE,0BAA+B,GACvC,6BAA6B,CA0C/B"}
+{"version":3,"file":"semantic-query-schema.d.ts","sourceRoot":"","sources":["../src/semantic-query-schema.ts"],"names":[],"mappings":"AAEA,OAAO,EAAK,KAAK,UAAU,EAAE,MAAM,KAAK,CAAC;AAEzC,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,MAAM,WAAW,yBAAyB;IACxC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA2B,SAAQ,yBAAyB;IAC3E,iFAAiF;IACjF,UAAU,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;IAC5B,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,gGAAgG;AAChG,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,kBAAkB,EAClB,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAC9C,CAAC;AAEF,eAAO,MAAM,oCAAoC;;;;;;;EAO/C,CAAC;AAEH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,UAAU,CAAC;IAC5C,QAAQ,CAAC,qBAAqB,EAAE,UAAU,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,oFAAoF;AACpF,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,GAAG,cAAc,CAAC;AA6I9E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,yBAAyB,EAClC,OAAO,GAAE,0BAA+B,GACvC,UAAU,CAOZ;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,0BAA+B,EACxC,cAAc,CAAC,EAAE,2BAA2B,GAC3C,UAAU,CAaZ;AAsBD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3C,UAAU,CAMZ;AAyBD,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,EACnD,OAAO,GAAE,0BAA+B,GACvC,6BAA6B,CAgD/B"}

package/dist/semantic-query-schema.js

@@ -187,9 +187,14 @@ function addSelectionRequirement(schema) {
 export function buildCanonicalSemanticQuerySchemas(datasets, options = {}) {
     const datasetSchemas = [];
     const metricSchemas = [];
+    const queryable = options.queryableDatasets === undefined
+        ? undefined
+        : new Set(options.queryableDatasets);
     for (const [datasetName, dataset] of Object.entries(datasets)
         .sort(([left], [right]) => compareStrings(left, right))) {
-        datasetSchemas.push(withSelectors(buildDatasetInputSchema(dataset, { ...options, requireSelection: false }), { dataset: z.literal(datasetName) }, options.requireSelection !== false));
+        if (queryable === undefined || queryable.has(datasetName)) {
+            datasetSchemas.push(withSelectors(buildDatasetInputSchema(dataset, { ...options, requireSelection: false }), { dataset: z.literal(datasetName) }, options.requireSelection !== false));
+        }
         const catalog = resolveCatalog(dataset);
         for (const metricName of Object.keys(catalog.metrics).sort(compareStrings)) {
             metricSchemas.push(withSelectors(buildMetricInputSchema(dataset, metricName, options, catalog.metrics[metricName]), { dataset: z.literal(datasetName), metric: z.literal(metricName) }, false));

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-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/package.json

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