@hypequery/datasets 0.15.0 → 0.17.0

package/dist/protocol-deployment-adapter.js

@@ -0,0 +1,31 @@
+import { parseProtocolIdentifier, validateProtocolDeploymentContract, } from '@hypequery/protocol';
+import { buildProtocolDatasetContract } from './protocol-adapter.js';
+import { derivedMeasureExpression } from './utils/protocol-metric-expressions.js';
+import { toProtocolSemanticMetadata } from './utils/protocol-semantic-metadata.js';
+/** Build the deployment contract; local metrics are not carried. */
+export function buildProtocolDeploymentContract(datasets, options = {}) {
+    const contracts = datasets.map(dataset => {
+        const contract = buildProtocolDatasetContract(dataset, {
+            endpoint: options.endpoints?.[dataset.name],
+        });
+        const { metrics: _metrics, ...base } = contract;
+        const derived = Object.entries(dataset.derivedMeasures ?? {}).map(([name, definition]) => ({
+            kind: 'derived',
+            name: parseProtocolIdentifier(name),
+            uses: Object.entries(definition.uses).map(([alias, measure]) => ({
+                alias: parseProtocolIdentifier(alias),
+                measure: parseProtocolIdentifier(measure),
+            })),
+            expression: derivedMeasureExpression(definition),
+            ...(definition.label !== undefined ? { label: definition.label } : {}),
+            ...(definition.description !== undefined ? { description: definition.description } : {}),
+            ...toProtocolSemanticMetadata(definition),
+        }));
+        return { ...base, measures: [...base.measures, ...derived] };
+    });
+    return validateProtocolDeploymentContract({
+        kind: 'hypequery-deployment',
+        version: 2,
+        datasets: contracts,
+    });
+}

package/dist/protocol-rehydrate.d.ts

@@ -11,7 +11,7 @@
  * exactly the same code path as an authored one. That is what makes the
  * byte-identical SQL claim mitigated by construction rather than by review.
  */
-import type { ProtocolDatasetContract } from '@hypequery/protocol';
+import type { ProtocolDatasetContract, ProtocolDeploymentDataset } from '@hypequery/protocol';
 import type { AnyDatasetInstance, DatasetCachePolicy, MetricHandle } from './types.js';
 /** A rebuilt dataset in the registry shape Serve, MCP, and the planner accept. */
 export type RehydratedDataset = AnyDatasetInstance & {
@@ -52,5 +52,7 @@ export declare class UnsupportedContractFeatureError extends Error {
  * attached, which is the registry shape `getDatasetCatalog`,
  * `projectAgentSafeCatalog`, and `DatasetClient` already accept.
  */
-export declare function rehydrateProtocolDatasets(contracts: readonly ProtocolDatasetContract[], options?: RehydrateProtocolDatasetsOptions): Readonly<Record<string, RehydratedDataset>>;
+export declare function rehydrateProtocolDatasets(contracts: readonly (ProtocolDatasetContract | ProtocolDeploymentDataset)[], options?: RehydrateProtocolDatasetsOptions): Readonly<Record<string, RehydratedDataset>>;
+/** Strict v2 reader that returns executable datasets without metric handles. */
+export declare function rehydrateProtocolDeploymentContract(input: unknown, options?: RehydrateProtocolDatasetsOptions): Readonly<Record<string, RehydratedDataset>>;
 //# sourceMappingURL=protocol-rehydrate.d.ts.map

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,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"}
+{"version":3,"file":"protocol-rehydrate.d.ts","sourceRoot":"","sources":["../src/protocol-rehydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,uBAAuB,EAEvB,yBAAyB,EAM1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAMlB,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;AAyPD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,CAAC,uBAAuB,GAAG,yBAAyB,CAAC,EAAE,EAC3E,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAmF7C;AAED,gFAAgF;AAChF,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAG7C"}

package/dist/protocol-rehydrate.js

@@ -11,6 +11,7 @@
  * exactly the same code path as an authored one. That is what makes the
  * byte-identical SQL claim mitigated by construction rather than by review.
  */
+import { validateProtocolDeploymentContract } from '@hypequery/protocol';
 import { dataset } from './dataset.js';
 import { snapshotSemanticMetadata } from './utils/semantic-metadata.js';
 import { withContractCapabilities } from './utils/protocol-metric-capabilities.js';
@@ -72,6 +73,16 @@ function rehydrateMeasure(datasetName, measure) {
         ...(filters.length > 0 ? { filters: filters } : {}),
     };
 }
+function rehydrateDerivedMeasure(datasetName, measure) {
+    return {
+        __type: 'derived_measure_definition',
+        ...snapshotSemanticMetadata(measure),
+        uses: Object.fromEntries(measure.uses.map(input => [String(input.alias), String(input.measure)])),
+        formula: rehydrateDerivedFormula({ inputs: [], expression: measure.expression }, reason => new UnsupportedContractFeatureError(datasetName, `measure "${measure.name}"`, reason)),
+        ...(measure.label !== undefined ? { label: measure.label } : {}),
+        ...(measure.description !== undefined ? { description: measure.description } : {}),
+    };
+}
 function rehydrateFilters(contract) {
     const filters = {};
     for (const filter of contract.filters) {
@@ -137,7 +148,7 @@ function measureForAggregate(instance, contract, subject, expression) {
     }
     // 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.
+    // this dataset snapshot. Binding to either would guess which SQL to emit.
     const distinctSql = new Set(candidates.map(measure => measure.sql?.sql ?? null));
     if (distinctSql.size > 1) {
         throw new UnsupportedContractFeatureError(instance.name, subject, `${candidates.map(measure => `"${String(measure.name)}"`).join(' and ')} share `
@@ -202,14 +213,24 @@ function rehydrateMetric(instance, contract, metric) {
  * `projectAgentSafeCatalog`, and `DatasetClient` already accept.
  */
 export function rehydrateProtocolDatasets(contracts, options = {}) {
+    const normalized = contracts.map(contract => {
+        const measures = contract.measures;
+        const derived = measures.filter((measure) => 'kind' in measure);
+        const base = {
+            ...contract,
+            measures: measures.filter((measure) => !('kind' in measure)),
+            metrics: contract.metrics ?? [],
+        };
+        return { base, derived };
+    });
     const instances = new Map();
-    const registry = {};
+    const registry = new Map();
     // Relationship targets resolve to the published entry, not the bare instance
     // built below, so a caller that follows a relationship lands on the same
     // object the registry exposes. Safe because `target()` is only called after
     // the registry is complete.
     const resolve = (target) => {
-        const instance = registry[target] ?? instances.get(target);
+        const instance = registry.get(target) ?? instances.get(target);
         if (!instance) {
             // The deployment validator already rejects a dangling relationship, so
             // reaching this means the caller passed a partial contract.
@@ -217,7 +238,7 @@ export function rehydrateProtocolDatasets(contracts, options = {}) {
         }
         return instance;
     };
-    for (const contract of contracts) {
+    for (const { base: contract, derived } of normalized) {
         const name = String(contract.name);
         const instance = dataset(name, {
             source: contract.source,
@@ -232,10 +253,14 @@ export function rehydrateProtocolDatasets(contracts, options = {}) {
             ...(contract.tenant.kind === 'required' ? { tenantKey: contract.tenant.field } : {}),
             ...(contract.timeField !== undefined ? { timeKey: String(contract.timeField) } : {}),
             dimensions: rehydrateDimensions(contract),
-            measures: Object.fromEntries(contract.measures.map(measure => [
-                String(measure.name),
-                rehydrateMeasure(name, measure),
-            ])),
+            measures: Object.fromEntries([
+                ...contract.measures.map(measure => [
+                    String(measure.name), rehydrateMeasure(name, measure),
+                ]),
+                ...derived.map(measure => [
+                    String(measure.name), rehydrateDerivedMeasure(name, measure),
+                ]),
+            ]),
             filters: rehydrateFilters(contract),
             relationships: rehydrateRelationships(contract, resolve),
             ...(contract.limits !== undefined ? { limits: { ...contract.limits } } : {}),
@@ -243,11 +268,11 @@ export function rehydrateProtocolDatasets(contracts, options = {}) {
         });
         instances.set(name, instance);
     }
-    for (const contract of contracts) {
+    for (const { base: contract } of normalized) {
         const name = String(contract.name);
         const instance = instances.get(name);
         const metrics = {};
-        for (const metric of contract.metrics) {
+        for (const metric of contract.metrics ?? []) {
             try {
                 metrics[String(metric.name)] = rehydrateMetric(instance, contract, metric);
             }
@@ -258,7 +283,14 @@ export function rehydrateProtocolDatasets(contracts, options = {}) {
                 }
             }
         }
-        registry[name] = Object.assign(Object.create(Object.getPrototypeOf(instance)), instance, { metrics });
+        const published = { ...instance, metrics };
+        registry.set(name, published);
     }
-    return registry;
+    // Object.fromEntries defines "__proto__" as an own property, unlike assignment to {}.
+    return Object.fromEntries(registry);
+}
+/** Strict v2 reader that returns executable datasets without metric handles. */
+export function rehydrateProtocolDeploymentContract(input, options = {}) {
+    const contract = validateProtocolDeploymentContract(input);
+    return rehydrateProtocolDatasets(contract.datasets, options);
 }

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

package/dist/protocol-schema-adapter.js

@@ -0,0 +1,249 @@
+import { validateCanonicalValue, validateProtocolSchema, } from '@hypequery/protocol';
+export class ProtocolSchemaAdapterError extends TypeError {
+    path;
+    constructor(message, path = '$') {
+        super(`${message} at ${path}`);
+        this.name = 'ProtocolSchemaAdapterError';
+        this.path = path;
+    }
+}
+function canonicalValue(input, path) {
+    try {
+        if (Array.isArray(input)) {
+            return validateCanonicalValue({
+                $hypequery: {
+                    type: 'array',
+                    version: 1,
+                    values: input.map((item, index) => canonicalValue(item, `${path}[${index}]`)),
+                },
+            });
+        }
+        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 ProtocolSchemaAdapterError('Default is not portable plain data', path);
+            }
+            return validateCanonicalValue({
+                $hypequery: {
+                    type: 'map',
+                    version: 1,
+                    entries: Object.entries(input)
+                        .sort(([left], [right]) => left.localeCompare(right))
+                        .map(([key, value]) => [key, canonicalValue(value, `${path}.${key}`)]),
+                },
+            });
+        }
+        return validateCanonicalValue(input);
+    }
+    catch (error) {
+        if (error instanceof ProtocolSchemaAdapterError)
+            throw error;
+        throw new ProtocolSchemaAdapterError('Default is not a canonical protocol value', path);
+    }
+}
+function typeName(schema) {
+    return String(schema?._def?.typeName ?? 'Unknown');
+}
+function description(schema) {
+    return typeof schema.description === 'string'
+        ? schema.description
+        : undefined;
+}
+function annotate(schema, result) {
+    const value = description(schema);
+    return value === undefined ? result : { ...result, description: value };
+}
+function convertString(schema, path) {
+    const result = { kind: 'string' };
+    for (const check of schema._def.checks) {
+        switch (check.kind) {
+            case 'min':
+                result.minLength = check.value;
+                break;
+            case 'max':
+                result.maxLength = check.value;
+                break;
+            case 'length':
+                result.minLength = check.value;
+                result.maxLength = check.value;
+                break;
+            default:
+                throw new ProtocolSchemaAdapterError(`Unsupported Zod string check "${String(check.kind)}"`, path);
+        }
+    }
+    return annotate(schema, result);
+}
+function convertNumber(schema, path) {
+    const result = { kind: 'number' };
+    for (const check of schema._def.checks) {
+        switch (check.kind) {
+            case 'int':
+                result.kind = 'integer';
+                break;
+            case 'min':
+                result[check.inclusive === false ? 'exclusiveMinimum' : 'minimum'] = check.value;
+                break;
+            case 'max':
+                result[check.inclusive === false ? 'exclusiveMaximum' : 'maximum'] = check.value;
+                break;
+            case 'finite':
+                break;
+            default:
+                throw new ProtocolSchemaAdapterError(`Unsupported Zod number check "${String(check.kind)}"`, path);
+        }
+    }
+    return annotate(schema, result);
+}
+function isOptionalProperty(schema) {
+    const name = typeName(schema);
+    return name === 'ZodOptional' || name === 'ZodDefault';
+}
+function nativeEnumValues(input) {
+    const values = Object.keys(input)
+        .filter(key => typeof input[String(input[key])] !== 'number')
+        .map(key => input[key]);
+    return [...new Set(values)];
+}
+function isUnconstrainedRecordKey(schema) {
+    if (schema === undefined || typeName(schema) !== 'ZodString')
+        return false;
+    const definition = schema._def;
+    return Array.isArray(definition.checks)
+        && definition.checks.length === 0
+        && definition.coerce !== true;
+}
+function convert(schema, path) {
+    const definition = schema._def;
+    switch (typeName(schema)) {
+        case 'ZodAny':
+        case 'ZodUnknown':
+            return annotate(schema, { kind: 'any' });
+        case 'ZodNever':
+        case 'ZodVoid':
+        case 'ZodUndefined':
+            return annotate(schema, { kind: 'void' });
+        case 'ZodNull':
+            return annotate(schema, { kind: 'null' });
+        case 'ZodBoolean':
+            return annotate(schema, { kind: 'boolean' });
+        case 'ZodString':
+            return convertString(schema, path);
+        case 'ZodNumber':
+            return convertNumber(schema, path);
+        case 'ZodLiteral':
+            return annotate(schema, {
+                kind: 'literal',
+                value: canonicalValue(definition.value, `${path}.value`),
+            });
+        case 'ZodEnum':
+            return annotate(schema, {
+                kind: 'enum',
+                values: [...definition.values],
+            });
+        case 'ZodNativeEnum': {
+            const values = nativeEnumValues(definition.values);
+            return annotate(schema, { kind: 'enum', values });
+        }
+        case 'ZodArray': {
+            const result = {
+                kind: 'array',
+                items: convert(definition.type, `${path}.items`),
+            };
+            if (definition.minLength?.value !== undefined)
+                result.minItems = definition.minLength.value;
+            if (definition.maxLength?.value !== undefined)
+                result.maxItems = definition.maxLength.value;
+            if (definition.exactLength?.value !== undefined) {
+                result.minItems = definition.exactLength.value;
+                result.maxItems = definition.exactLength.value;
+            }
+            return annotate(schema, result);
+        }
+        case 'ZodObject': {
+            if (typeName(definition.catchall) !== 'ZodNever') {
+                throw new ProtocolSchemaAdapterError('Unsupported Zod object catchall', path);
+            }
+            const shape = definition.shape();
+            const properties = Object.fromEntries(Object.entries(shape).map(([name, property]) => [
+                name,
+                convert(property, `${path}.properties.${name}`),
+            ]));
+            const required = Object.entries(shape)
+                .filter(([, property]) => !isOptionalProperty(property))
+                .map(([name]) => name);
+            const unknownProperties = definition.unknownKeys === 'passthrough'
+                ? 'preserve'
+                : definition.unknownKeys === 'strict'
+                    ? 'reject'
+                    : 'strip';
+            return annotate(schema, {
+                kind: 'object',
+                properties,
+                required,
+                unknownProperties,
+            });
+        }
+        case 'ZodRecord':
+            if (!isUnconstrainedRecordKey(definition.keyType)) {
+                throw new ProtocolSchemaAdapterError('Unsupported constrained Zod record key', path);
+            }
+            return annotate(schema, {
+                kind: 'record',
+                values: convert(definition.valueType, `${path}.values`),
+            });
+        case 'ZodUnion':
+            return annotate(schema, {
+                kind: 'union',
+                variants: definition.options.map((option, index) => convert(option, `${path}.variants[${index}]`)),
+            });
+        case 'ZodDiscriminatedUnion':
+            // RFC 0004 has no separate discriminator index. Converting every option
+            // drops only Zod's lookup metadata; each object's literal discriminator
+            // property remains part of its protocol variant.
+            return annotate(schema, {
+                kind: 'union',
+                variants: [...definition.options.values()].map((option, index) => convert(option, `${path}.variants[${index}]`)),
+            });
+        case 'ZodNullable':
+            return annotate(schema, {
+                kind: 'union',
+                variants: [convert(definition.innerType, `${path}.variants[0]`), { kind: 'null' }],
+            });
+        case 'ZodOptional':
+            return annotate(schema, convert(definition.innerType, path));
+        case 'ZodDefault': {
+            const inner = convert(definition.innerType, path);
+            if (inner.kind === 'void') {
+                throw new ProtocolSchemaAdapterError('Void schemas cannot carry defaults', path);
+            }
+            return annotate(schema, {
+                ...inner,
+                default: canonicalValue(definition.defaultValue(), `${path}.default`),
+            });
+        }
+        case 'ZodBranded':
+            return annotate(schema, convert(definition.type, path));
+        case 'ZodReadonly':
+            return annotate(schema, convert(definition.innerType, path));
+        case 'ZodEffects': {
+            const effectType = String(definition.effect?.type ?? 'unknown');
+            if (effectType !== 'refinement') {
+                throw new ProtocolSchemaAdapterError(`Unsupported Zod effect "${effectType}"`, path);
+            }
+            // A refinement preserves the wrapped schema's input and output shape.
+            // The rule itself remains enforced by Zod, but cannot be advertised by
+            // ProtocolSchema (for example, a cross-field selection requirement).
+            return annotate(schema, convert(definition.schema, path));
+        }
+        default:
+            throw new ProtocolSchemaAdapterError(`Unsupported Zod type "${typeName(schema)}"`, path);
+    }
+}
+/** Converts the portable subset of a Zod v3 schema into RFC 0004. */
+export function zodToProtocolSchema(schema, path = '$') {
+    if (schema === undefined)
+        return validateProtocolSchema({ kind: 'any' });
+    return validateProtocolSchema(convert(schema, path));
+}

package/dist/relationships.d.ts

@@ -1,19 +1,40 @@
 /**
  * Relationship helpers for dataset definitions.
  *
- * These helpers currently define semantic model metadata only. The shipped
- * semantic client does not yet resolve relationship paths into joined dataset queries
- * or cross-dataset metrics.
+ * To-one relationships (`belongsTo`, `hasOne`) are queryable one hop deep as
+ * `<relationship>.<dimension>` and execute as LEFT JOINs. `hasMany` is metadata
+ * only: joining it would fan out and corrupt aggregates, so it is refused at
+ * query time.
+ *
+ * Only the target's *dimensions* are reachable. A measure on the target dataset
+ * is not addressable through a relationship, so there are no cross-dataset
+ * metrics.
+ *
+ * Note that the `kind` passed here is a declaration, not something checked
+ * against the data — there is no uniqueness concept in the model, so nothing
+ * verifies that a `belongsTo` target column really is unique. What a
+ * mis-declaration costs depends on the builder. One that implements the
+ * optional `leftAnyJoin` (ClickHouse `LEFT ANY JOIN`) takes at most one target
+ * row per base row, so the aggregate cannot inflate — it just silently picks an
+ * arbitrary one of the matches. A builder without it falls back to `leftJoin`,
+ * where duplicate target keys fan out and do inflate the aggregate. Either way
+ * the declaration has to be right.
  *
  * @example
  * ```ts
  * const Orders = dataset("orders", {
  *   source: "orders",
- *   fields: { ... },
+ *   dimensions: {
+ *     id: dimension.string(),
+ *     customerId: dimension.string({ column: "customer_id" }),
+ *   },
  *   relationships: {
  *     customer: belongsTo(() => Customers, { from: "customerId", to: "id" }),
  *   },
  * });
+ *
+ * // Groups by a dimension on Customers, joining through the relationship.
+ * await client.execute(Orders, { dimensions: ["customer.country"] });
  * ```
  */
 import type { RelationshipDefinition } from './types.js';

package/dist/relationships.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../src/relationships.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAoB,MAAM,YAAY,CAAC;AAmB3E,mDAAmD;AACnD,wBAAgB,SAAS,CAAC,OAAO,SAAS;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAC3E,MAAM,EAAE,MAAM,OAAO,EACrB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAAC,OAAO,EAAE,WAAW,CAAC,CAE9C;AAED,qDAAqD;AACrD,wBAAgB,OAAO,CAAC,OAAO,SAAS;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACzE,MAAM,EAAE,MAAM,OAAO,EACrB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAAC,OAAO,EAAE,SAAS,CAAC,CAE5C;AAED,oDAAoD;AACpD,wBAAgB,MAAM,CAAC,OAAO,SAAS;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACxE,MAAM,EAAE,MAAM,OAAO,EACrB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAE3C"}
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../src/relationships.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAoB,MAAM,YAAY,CAAC;AAmB3E,mDAAmD;AACnD,wBAAgB,SAAS,CAAC,OAAO,SAAS;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAC3E,MAAM,EAAE,MAAM,OAAO,EACrB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAAC,OAAO,EAAE,WAAW,CAAC,CAE9C;AAED,qDAAqD;AACrD,wBAAgB,OAAO,CAAC,OAAO,SAAS;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACzE,MAAM,EAAE,MAAM,OAAO,EACrB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAAC,OAAO,EAAE,SAAS,CAAC,CAE5C;AAED,oDAAoD;AACpD,wBAAgB,MAAM,CAAC,OAAO,SAAS;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACxE,MAAM,EAAE,MAAM,OAAO,EACrB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAE3C"}

package/dist/relationships.js

@@ -1,19 +1,40 @@
 /**
  * Relationship helpers for dataset definitions.
  *
- * These helpers currently define semantic model metadata only. The shipped
- * semantic client does not yet resolve relationship paths into joined dataset queries
- * or cross-dataset metrics.
+ * To-one relationships (`belongsTo`, `hasOne`) are queryable one hop deep as
+ * `<relationship>.<dimension>` and execute as LEFT JOINs. `hasMany` is metadata
+ * only: joining it would fan out and corrupt aggregates, so it is refused at
+ * query time.
+ *
+ * Only the target's *dimensions* are reachable. A measure on the target dataset
+ * is not addressable through a relationship, so there are no cross-dataset
+ * metrics.
+ *
+ * Note that the `kind` passed here is a declaration, not something checked
+ * against the data — there is no uniqueness concept in the model, so nothing
+ * verifies that a `belongsTo` target column really is unique. What a
+ * mis-declaration costs depends on the builder. One that implements the
+ * optional `leftAnyJoin` (ClickHouse `LEFT ANY JOIN`) takes at most one target
+ * row per base row, so the aggregate cannot inflate — it just silently picks an
+ * arbitrary one of the matches. A builder without it falls back to `leftJoin`,
+ * where duplicate target keys fan out and do inflate the aggregate. Either way
+ * the declaration has to be right.
  *
  * @example
  * ```ts
  * const Orders = dataset("orders", {
  *   source: "orders",
- *   fields: { ... },
+ *   dimensions: {
+ *     id: dimension.string(),
+ *     customerId: dimension.string({ column: "customer_id" }),
+ *   },
  *   relationships: {
  *     customer: belongsTo(() => Customers, { from: "customerId", to: "id" }),
  *   },
  * });
+ *
+ * // Groups by a dimension on Customers, joining through the relationship.
+ * await client.execute(Orders, { dimensions: ["customer.country"] });
  * ```
  */
 function createRelationship(kind, target, join) {

package/dist/semantic-planner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-planner.d.ts","sourceRoot":"","sources":["../src/semantic-planner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAGhB,WAAW,EACX,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,QAAQ,EAIT,MAAM,oBAAoB,CAAC;AAyL5B,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,kBAAkB,EACtB,KAAK,GAAE,YAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAaV;AA2FD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAYV"}
+{"version":3,"file":"semantic-planner.d.ts","sourceRoot":"","sources":["../src/semantic-planner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAGhB,WAAW,EACX,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,QAAQ,EAIT,MAAM,oBAAoB,CAAC;AAyL5B,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,kBAAkB,EACtB,KAAK,GAAE,YAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAgBV;AA2FD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAYV"}

package/dist/semantic-planner.js

@@ -145,6 +145,9 @@ function aggregatePlan(ds, query, aggregations, context) {
     };
 }
 export function buildDatasetPlan(ds, query = {}, context) {
+    if ((query.measures ?? []).some(name => Object.hasOwn(ds.derivedMeasures, name))) {
+        throw new Error('Derived dataset measures require the queryBuilder execution path.');
+    }
     const validation = validateDatasetQuery(ds, query, context);
     if (!validation.valid) {
         throw new Error(`Invalid dataset query: ${validation.errors.join('; ')}`);

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

@@ -1,6 +1,7 @@
 import { type ZodTypeAny } from 'zod';
 import { type DatasetCatalog, type DatasetCatalogSource, type MetricCatalogEntry } from './catalog.js';
 import type { JsonSchema } from './tools.js';
+import type { ProtocolSchema } from '@hypequery/protocol';
 export interface SemanticQuerySchemaLimits {
     defaultResultSize?: number;
     maxResultSize?: number;
@@ -57,4 +58,22 @@ export declare function toSemanticJsonSchema(schema: ZodTypeAny, options?: {
     requireSelection?: boolean;
 }): JsonSchema;
 export declare function buildCanonicalSemanticQuerySchemas(datasets: Record<string, SemanticQuerySchemaSource>, options?: SemanticQuerySchemaOptions): CanonicalSemanticQuerySchemas;
+/**
+ * The same input schema, as a `ProtocolSchema`.
+ *
+ * A hosted registry advertises one endpoint per dataset and per metric, and it
+ * advertises them in the protocol's own schema format rather than Zod or JSON
+ * Schema. Without this it has to rebuild the shape by hand — which is a second
+ * generator of the knowledge `CORE-03` exists to keep in one place, and it
+ * drifts silently: an advertised field the validator rejects, or a ceiling the
+ * data plane does not apply.
+ *
+ * Derived from `buildDatasetInputSchema`, so there is one source for which
+ * dimensions are groupable, which measures exist, what the filter operators
+ * are, what the orderable fields are, which grains are supported, and what the
+ * row ceiling is.
+ */
+export declare function buildDatasetInputProtocolSchema(dataset: SemanticQuerySchemaSource, options?: SemanticQuerySchemaOptions, path?: string): ProtocolSchema;
+/** The metric form of {@link buildDatasetInputProtocolSchema}. */
+export declare function buildMetricInputProtocolSchema(dataset: SemanticQuerySchemaSource, metricName: string, options?: SemanticQuerySchemaOptions, metricContract?: SemanticMetricQueryContract, path?: string): ProtocolSchema;
 //# sourceMappingURL=semantic-query-schema.d.ts.map

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;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"}
+{"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;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D,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;AA8I9E,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;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,yBAAyB,EAClC,OAAO,GAAE,0BAA+B,EACxC,IAAI,SAAkB,GACrB,cAAc,CAEhB;AAED,kEAAkE;AAClE,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,0BAA+B,EACxC,cAAc,CAAC,EAAE,2BAA2B,EAC5C,IAAI,SAAiB,GACpB,cAAc,CAKhB"}

package/dist/semantic-query-schema.js

@@ -4,6 +4,7 @@ import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { getDatasetCatalog, getGroupableRelationshipFields, getQueryableRelationshipFields, } from './catalog.js';
 import { SEMANTIC_FILTER_OPERATORS } from './constants.js';
+import { zodToProtocolSchema } from './protocol-schema-adapter.js';
 import { compareStrings, stableStringify, uniqueSorted } from './utils/canonical-json.js';
 export const DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS = Object.freeze({
     maxResultSize: 10_000,
@@ -95,6 +96,7 @@ function queryShape(catalog, metricName, options, metric, localRelationshipField
         : uniqueSorted([
             ...dimensions,
             ...Object.keys(catalog.measures),
+            ...Object.keys(catalog.derivedMeasures ?? {}),
             ...(catalog.supportedGrains.length > 0 ? ['period'] : []),
         ]);
     const maxResultSize = options.enforceResultLimit === false
@@ -110,7 +112,7 @@ function queryShape(catalog, metricName, options, metric, localRelationshipField
     return {
         dimensions: boundedArray(fieldEnum(dimensions), lowerLimit(catalog.limits?.maxDimensions, limits.maxDimensions)),
         ...(metricName ? {} : {
-            measures: boundedArray(fieldEnum(Object.keys(catalog.measures)), lowerLimit(catalog.limits?.maxMeasures, limits.maxMeasures)),
+            measures: boundedArray(fieldEnum([...Object.keys(catalog.measures), ...Object.keys(catalog.derivedMeasures ?? {})]), lowerLimit(catalog.limits?.maxMeasures, limits.maxMeasures)),
         }),
         filters: boundedArray(filterSchema(catalog, filterFields), lowerLimit(catalog.limits?.maxFilters, limits.maxFilters)),
         orderBy: boundedArray(z.object({
@@ -221,3 +223,25 @@ export function buildCanonicalSemanticQuerySchemas(datasets, options = {}) {
         manifestHash,
     });
 }
+/**
+ * The same input schema, as a `ProtocolSchema`.
+ *
+ * A hosted registry advertises one endpoint per dataset and per metric, and it
+ * advertises them in the protocol's own schema format rather than Zod or JSON
+ * Schema. Without this it has to rebuild the shape by hand — which is a second
+ * generator of the knowledge `CORE-03` exists to keep in one place, and it
+ * drifts silently: an advertised field the validator rejects, or a ceiling the
+ * data plane does not apply.
+ *
+ * Derived from `buildDatasetInputSchema`, so there is one source for which
+ * dimensions are groupable, which measures exist, what the filter operators
+ * are, what the orderable fields are, which grains are supported, and what the
+ * row ceiling is.
+ */
+export function buildDatasetInputProtocolSchema(dataset, options = {}, path = 'dataset.input') {
+    return zodToProtocolSchema(buildDatasetInputSchema(dataset, options), path);
+}
+/** The metric form of {@link buildDatasetInputProtocolSchema}. */
+export function buildMetricInputProtocolSchema(dataset, metricName, options = {}, metricContract, path = 'metric.input') {
+    return zodToProtocolSchema(buildMetricInputSchema(dataset, metricName, options, metricContract), path);
+}