@hypequery/datasets 0.14.0 → 0.16.0

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-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;
@@ -19,6 +20,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'>;
@@ -45,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;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;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;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;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,
@@ -187,9 +188,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));
@@ -216,3 +222,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);
+}

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