@hypequery/datasets 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -19,11 +19,13 @@ 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';
 export { generateDatasetTools, toOpenAITools, toAISDKTools, toMcpTools, } from './tools.js';
-export { buildDatasetInputSchema, buildMetricInputSchema, buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS, } from './semantic-query-schema.js';
+export { buildDatasetInputSchema, buildMetricInputSchema, buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS, buildDatasetInputProtocolSchema, buildMetricInputProtocolSchema, } from './semantic-query-schema.js';
 export type { CanonicalSemanticQuerySchemas, SemanticMetricQueryContract, SemanticQuerySchemaLimits, SemanticQuerySchemaOptions, SemanticQuerySchemaSource, } from './semantic-query-schema.js';
 export type { AISDKToolDefinition, DatasetToolAnalytics, DatasetToolMode, GenerateDatasetToolsOptions, JsonSchema, McpToolDefinition, OpenAIToolDefinition, SemanticToolDefinition, } from './tools.js';
 export { createDatasetClient } from './executor.js';
@@ -41,4 +43,5 @@ export { toQueryBuilderFactory } from './query-builder-protocol.js';
 export { validateSQLIdentifier, isSafeSQLIdentifier, quoteSQLIdentifier } from './sql-utils.js';
 export { GRAIN_FUNCTIONS, SEMANTIC_FILTER_OPERATORS, SUPPORTED_TIME_GRAINS } from './constants.js';
 export type { FieldType, DimensionType, DimensionOptions, DimensionDefinition, MeasureOptions, MeasureDefinition, InferDimensionType, RelationshipKind, RelationshipDefinition, AggregationType, MeasureAggregation, AggregationSpec, FormulaExpr, DerivedMetricSpec, TimeGrain, MetricRef, BaseMetricRef, DerivedMetricRef, GrainedMetricRef, MetricContract, MetricFilter, MetricOrderBy, MetricQuery, DatasetQuery, MetricResultMeta, MetricResult, DatasetQueryResult, MetricHandle, ExecutionContext, SemanticExecutionRuntime, SemanticTenantRuntime, SemanticFilterDefinition, SemanticFiltersDefinition, DatasetConfig, DatasetDefaults, DatasetFreshness, DatasetLimits, DatasetCachePolicy, SemanticMetadata, SemanticSensitivity, DatasetInstance, AnyDatasetInstance, BaseMetricConfig, DerivedMetricConfig, DatasetRegistryInstance, DatasetFieldNames, DatasetDimensionNames, DatasetQueryableDimensions, DatasetMeasureNames, DatasetOrderableNames, DatasetQueryFor, DatasetRow, DatasetRowFor, DatasetQueryResultFor, MetricQueryFor, MetricRow, MetricRowFor, MetricResultFor, KnownStringKeys, } from './types.js';
+export { ProtocolSchemaAdapterError, zodToProtocolSchema } from './protocol-schema-adapter.js';
 //# sourceMappingURL=index.d.ts.map

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,12 +26,14 @@ 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
 export { generateDatasetTools, toOpenAITools, toAISDKTools, toMcpTools, } from './tools.js';
 // Canonical semantic query schemas shared by Serve, MCP, and agent adapters.
-export { buildDatasetInputSchema, buildMetricInputSchema, buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS, } from './semantic-query-schema.js';
+export { buildDatasetInputSchema, buildMetricInputSchema, buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS, buildDatasetInputProtocolSchema, buildMetricInputProtocolSchema, } from './semantic-query-schema.js';
 // Dataset client
 export { createDatasetClient } from './executor.js';
 // Semantic query result cache
@@ -47,3 +49,4 @@ export { toQueryBuilderFactory } from './query-builder-protocol.js';
 export { validateSQLIdentifier, isSafeSQLIdentifier, quoteSQLIdentifier } from './sql-utils.js';
 // Constants
 export { GRAIN_FUNCTIONS, SEMANTIC_FILTER_OPERATORS, SUPPORTED_TIME_GRAINS } from './constants.js';
+export { ProtocolSchemaAdapterError, zodToProtocolSchema } from './protocol-schema-adapter.js';

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/protocol-schema-adapter.d.ts

@@ -0,0 +1,9 @@
+import type { ZodTypeAny } from 'zod';
+import { type ProtocolSchema } from '@hypequery/protocol';
+export declare class ProtocolSchemaAdapterError extends TypeError {
+    readonly path: string;
+    constructor(message: string, path?: string);
+}
+/** Converts the portable subset of a Zod v3 schema into RFC 0004. */
+export declare function zodToProtocolSchema(schema: ZodTypeAny | undefined, path?: string): ProtocolSchema;
+//# sourceMappingURL=protocol-schema-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-schema-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-schema-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAE7B,qBAAa,0BAA2B,SAAQ,SAAS;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EAAE,IAAI,SAAM;CAKxC;AAoPD,qEAAqE;AACrE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,IAAI,SAAM,GACT,cAAc,CAGhB"}