@hypequery/protocol 0.1.0 → 0.2.1

package/dist/deployments/validate.js

@@ -0,0 +1,537 @@
+import { ProtocolExpressionError, validateProtocolExpression } from '../expressions/index.js';
+import { ProtocolIdentifierError, parseProtocolIdentifier, parseProtocolQualifiedIdentifier, } from '../identifiers/index.js';
+import { ProtocolQueryImplementationError, validateProtocolQueryImplementation, validateProtocolSqlExpression, } from '../query-implementations/index.js';
+import { ProtocolSchemaError, validateProtocolSchema, } from '../schemas/index.js';
+import { deploymentError } from './errors.js';
+import { resolveDeploymentLimits } from './limits.js';
+const textEncoder = new TextEncoder();
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+const AGGREGATIONS = new Set([
+    'sum', 'count', 'countDistinct', 'avg', 'min', 'max',
+    'argMax', 'argMin', 'percentile', 'stddev', 'variance',
+]);
+const OPERATORS = new Set([
+    'eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn', 'between', 'like',
+]);
+const GRAINS = new Set(['day', 'week', 'month', 'quarter', 'year']);
+function requireRecord(input, path) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        deploymentError('HQ_DEPLOYMENT_TYPE', path);
+    }
+    const prototype = Object.getPrototypeOf(input);
+    if (prototype !== Object.prototype && prototype !== null) {
+        deploymentError('HQ_DEPLOYMENT_UNSAFE_OBJECT', path);
+    }
+    if (Object.getOwnPropertySymbols(input).length > 0) {
+        deploymentError('HQ_DEPLOYMENT_UNSAFE_OBJECT', path);
+    }
+    for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(input))) {
+        if (!descriptor.enumerable || !('value' in descriptor)) {
+            deploymentError('HQ_DEPLOYMENT_UNSAFE_OBJECT', path);
+        }
+    }
+    return input;
+}
+function requireArray(input, path, maxItems) {
+    if (!Array.isArray(input))
+        deploymentError('HQ_DEPLOYMENT_TYPE', path);
+    if (Object.getPrototypeOf(input) !== Array.prototype || Object.getOwnPropertySymbols(input).length > 0) {
+        deploymentError('HQ_DEPLOYMENT_UNSAFE_OBJECT', path);
+    }
+    if (input.length > maxItems)
+        deploymentError('HQ_DEPLOYMENT_TOO_MANY_ITEMS', path);
+    const descriptors = Object.getOwnPropertyDescriptors(input);
+    for (let index = 0; index < input.length; index += 1) {
+        const descriptor = descriptors[String(index)];
+        if (!descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+            deploymentError('HQ_DEPLOYMENT_UNSAFE_OBJECT', `${path}[${index}]`);
+        }
+    }
+    if (Object.keys(input).length !== input.length)
+        deploymentError('HQ_DEPLOYMENT_UNSAFE_OBJECT', path);
+    return input;
+}
+function exactFields(value, required, optional, path) {
+    const allowed = new Set([...required, ...optional]);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            deploymentError('HQ_DEPLOYMENT_UNKNOWN_FIELD', `${path}.${key}`);
+    }
+    for (const key of required) {
+        if (!Object.hasOwn(value, key))
+            deploymentError('HQ_DEPLOYMENT_TYPE', `${path}.${key}`);
+    }
+}
+function freezeRecord(entries) {
+    return Object.freeze(Object.assign(Object.create(null), entries));
+}
+function identifier(value, path, qualified = false) {
+    try {
+        return qualified ? parseProtocolQualifiedIdentifier(value) : parseProtocolIdentifier(value);
+    }
+    catch (error) {
+        if (error instanceof ProtocolIdentifierError) {
+            deploymentError('HQ_DEPLOYMENT_INVALID_IDENTIFIER', path);
+        }
+        throw error;
+    }
+}
+function boundedText(value, path, maxBytes) {
+    if (typeof value !== 'string')
+        deploymentError('HQ_DEPLOYMENT_TYPE', path);
+    if (value.trim().length === 0)
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', path);
+    for (const character of value) {
+        const code = character.codePointAt(0);
+        if (code <= 0x1f || code === 0x7f || (code >= 0x80 && code <= 0x9f)) {
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', path);
+        }
+    }
+    if (value.length > maxBytes || textEncoder.encode(value).byteLength > maxBytes) {
+        deploymentError('HQ_DEPLOYMENT_TOO_LARGE', path);
+    }
+    return value;
+}
+function optionalText(value, key, result, path, limits) {
+    if (value !== undefined)
+        result[key] = boundedText(value, `${path}.${key}`, limits.maxTextBytes);
+}
+function positiveInteger(value, path) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', path);
+    }
+    return value;
+}
+function uniqueStrings(input, path, maxItems, parse) {
+    const result = requireArray(input, path, maxItems).map((value, index) => parse(value, `${path}[${index}]`));
+    if (new Set(result).size !== result.length)
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', path);
+    return Object.freeze(result);
+}
+function validateAccess(input, path, limits) {
+    const value = requireRecord(input, path);
+    if (value.kind === 'public') {
+        exactFields(value, ['kind'], [], path);
+        return freezeRecord({ kind: 'public' });
+    }
+    if (value.kind === 'authenticated') {
+        exactFields(value, ['kind', 'roles', 'scopes'], [], path);
+        const parseClaim = (claim, claimPath) => boundedText(claim, claimPath, limits.maxTextBytes);
+        return freezeRecord({
+            kind: 'authenticated',
+            roles: uniqueStrings(value.roles, `${path}.roles`, limits.maxDatasetItems, parseClaim),
+            scopes: uniqueStrings(value.scopes, `${path}.scopes`, limits.maxDatasetItems, parseClaim),
+        });
+    }
+    if (typeof value.kind !== 'string')
+        deploymentError('HQ_DEPLOYMENT_TYPE', `${path}.kind`);
+    deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.kind`);
+}
+function validateEndpointTenant(input, path, limits) {
+    const value = requireRecord(input, path);
+    if (value.kind === 'not-required') {
+        exactFields(value, ['kind'], [], path);
+        return freezeRecord({ kind: 'not-required' });
+    }
+    if (value.kind === 'required' || value.kind === 'optional') {
+        exactFields(value, ['kind', 'mode'], ['column'], path);
+        if (value.mode !== 'auto-inject' && value.mode !== 'manual') {
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.mode`);
+        }
+        const result = { kind: value.kind, mode: value.mode };
+        if (value.column !== undefined) {
+            result.column = boundedText(value.column, `${path}.column`, limits.maxSourceBytes);
+        }
+        if (value.mode === 'auto-inject' && value.column === undefined) {
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.column`);
+        }
+        return freezeRecord(result);
+    }
+    if (typeof value.kind !== 'string')
+        deploymentError('HQ_DEPLOYMENT_TYPE', `${path}.kind`);
+    deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.kind`);
+}
+function validateEndpoint(input, path, limits, transport = false) {
+    const value = requireRecord(input, path);
+    exactFields(value, transport ? ['access', 'tenant', 'method', 'path'] : ['access', 'tenant'], transport ? ['cacheTtlMs', 'maxLimit'] : ['cacheTtlMs', 'maxLimit', 'path'], path);
+    const result = {
+        access: validateAccess(value.access, `${path}.access`, limits),
+        tenant: validateEndpointTenant(value.tenant, `${path}.tenant`, limits),
+    };
+    if (value.cacheTtlMs !== undefined)
+        result.cacheTtlMs = positiveInteger(value.cacheTtlMs, `${path}.cacheTtlMs`);
+    if (value.maxLimit !== undefined)
+        result.maxLimit = positiveInteger(value.maxLimit, `${path}.maxLimit`);
+    if (!transport && value.path !== undefined) {
+        const endpointPath = boundedText(value.path, `${path}.path`, limits.maxPathBytes);
+        if (!endpointPath.startsWith('/'))
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.path`);
+        result.path = endpointPath;
+    }
+    if (transport) {
+        if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'].includes(value.method)) {
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.method`);
+        }
+        const endpointPath = boundedText(value.path, `${path}.path`, limits.maxPathBytes);
+        if (!endpointPath.startsWith('/'))
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.path`);
+        result.method = value.method;
+        result.path = endpointPath;
+    }
+    return freezeRecord(result);
+}
+function validateTenant(input, path, limits) {
+    const value = requireRecord(input, path);
+    if (value.kind === 'not-required') {
+        exactFields(value, ['kind'], [], path);
+        return freezeRecord({ kind: 'not-required' });
+    }
+    if (value.kind === 'required') {
+        exactFields(value, ['kind', 'field'], [], path);
+        return freezeRecord({
+            kind: 'required',
+            field: boundedText(value.field, `${path}.field`, limits.maxSourceBytes),
+        });
+    }
+    if (typeof value.kind !== 'string')
+        deploymentError('HQ_DEPLOYMENT_TYPE', `${path}.kind`);
+    deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.kind`);
+}
+function nested(action, path) {
+    try {
+        return action();
+    }
+    catch (error) {
+        if (error instanceof ProtocolExpressionError
+            || error instanceof ProtocolQueryImplementationError
+            || error instanceof ProtocolSchemaError) {
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', path);
+        }
+        throw error;
+    }
+}
+function validateFieldSource(input, path, limits) {
+    const value = requireRecord(input, path);
+    if (value.kind === 'column') {
+        exactFields(value, ['kind', 'column'], [], path);
+        return freezeRecord({
+            kind: 'column',
+            column: boundedText(value.column, `${path}.column`, limits.maxSourceBytes),
+        });
+    }
+    return nested(() => validateProtocolSqlExpression(value), path);
+}
+function validateDimension(input, path, limits) {
+    const value = requireRecord(input, path);
+    exactFields(value, ['name', 'type', 'source', 'filterable', 'groupable'], ['label', 'description'], path);
+    if (!['string', 'number', 'boolean', 'timestamp'].includes(value.type)) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.type`);
+    }
+    if (typeof value.filterable !== 'boolean')
+        deploymentError('HQ_DEPLOYMENT_TYPE', `${path}.filterable`);
+    if (typeof value.groupable !== 'boolean')
+        deploymentError('HQ_DEPLOYMENT_TYPE', `${path}.groupable`);
+    const result = {
+        name: identifier(value.name, `${path}.name`),
+        type: value.type,
+        source: validateFieldSource(value.source, `${path}.source`, limits),
+        filterable: value.filterable,
+        groupable: value.groupable,
+    };
+    optionalText(value.label, 'label', result, path, limits);
+    optionalText(value.description, 'description', result, path, limits);
+    return freezeRecord(result);
+}
+function validateMeasure(input, path, limits) {
+    const value = requireRecord(input, path);
+    exactFields(value, ['name', 'aggregation', 'field', 'filters'], ['argField', 'level', 'sql', 'label', 'description'], path);
+    if (typeof value.aggregation !== 'string' || !AGGREGATIONS.has(value.aggregation)) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.aggregation`);
+    }
+    const needsArg = value.aggregation === 'argMax' || value.aggregation === 'argMin';
+    if (needsArg !== (value.argField !== undefined)) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.argField`);
+    }
+    if (value.aggregation === 'percentile') {
+        if (typeof value.level !== 'number' || !Number.isFinite(value.level) || value.level < 0 || value.level > 1) {
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.level`);
+        }
+    }
+    else if (value.level !== undefined) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.level`);
+    }
+    const result = {
+        name: identifier(value.name, `${path}.name`),
+        aggregation: value.aggregation,
+        field: identifier(value.field, `${path}.field`, true),
+        filters: Object.freeze(requireArray(value.filters, `${path}.filters`, limits.maxDatasetItems)
+            .map((filter, index) => nested(() => validateProtocolExpression(filter), `${path}.filters[${index}]`))),
+    };
+    if (value.argField !== undefined)
+        result.argField = identifier(value.argField, `${path}.argField`, true);
+    if (value.level !== undefined)
+        result.level = value.level;
+    if (value.sql !== undefined)
+        result.sql = nested(() => validateProtocolSqlExpression(value.sql), `${path}.sql`);
+    optionalText(value.label, 'label', result, path, limits);
+    optionalText(value.description, 'description', result, path, limits);
+    return freezeRecord(result);
+}
+function validateFilter(input, path, limits) {
+    const value = requireRecord(input, path);
+    exactFields(value, ['name', 'field', 'operators'], ['label', 'description'], path);
+    const operators = uniqueStrings(value.operators, `${path}.operators`, limits.maxDatasetItems, (operator, operatorPath) => {
+        if (typeof operator !== 'string' || !OPERATORS.has(operator)) {
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', operatorPath);
+        }
+        return operator;
+    });
+    if (operators.length === 0)
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.operators`);
+    const result = {
+        name: identifier(value.name, `${path}.name`),
+        field: identifier(value.field, `${path}.field`, true),
+        operators,
+    };
+    optionalText(value.label, 'label', result, path, limits);
+    optionalText(value.description, 'description', result, path, limits);
+    return freezeRecord(result);
+}
+function validateRelationship(input, path) {
+    const value = requireRecord(input, path);
+    exactFields(value, ['name', 'kind', 'target', 'from', 'to', 'queryable'], [], path);
+    if (!['belongsTo', 'hasMany', 'hasOne'].includes(value.kind)) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.kind`);
+    }
+    if (typeof value.queryable !== 'boolean')
+        deploymentError('HQ_DEPLOYMENT_TYPE', `${path}.queryable`);
+    if ((value.kind === 'hasMany') === value.queryable) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.queryable`);
+    }
+    return freezeRecord({
+        name: identifier(value.name, `${path}.name`),
+        kind: value.kind,
+        target: identifier(value.target, `${path}.target`),
+        from: identifier(value.from, `${path}.from`, true),
+        to: identifier(value.to, `${path}.to`, true),
+        queryable: value.queryable,
+    });
+}
+function validateMetric(input, path, limits) {
+    const value = requireRecord(input, path);
+    exactFields(value, ['name', 'kind', 'expression', 'dimensions', 'filters', 'grains', 'endpoint'], ['grain', 'label', 'description'], path);
+    if (!['metric', 'derived-metric', 'grained-metric'].includes(value.kind)) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.kind`);
+    }
+    const parseGrain = (grain, grainPath) => {
+        if (typeof grain !== 'string' || !GRAINS.has(grain)) {
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', grainPath);
+        }
+        return grain;
+    };
+    const grains = uniqueStrings(value.grains, `${path}.grains`, limits.maxDatasetItems, parseGrain);
+    if ((value.kind === 'grained-metric') !== (value.grain !== undefined)) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.grain`);
+    }
+    const grain = value.grain === undefined
+        ? undefined
+        : parseGrain(value.grain, `${path}.grain`);
+    if (grain !== undefined && grains.length === 0) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.grains`);
+    }
+    if (grain !== undefined && !grains.includes(grain)) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.grain`);
+    }
+    const result = {
+        name: identifier(value.name, `${path}.name`),
+        kind: value.kind,
+        expression: nested(() => validateProtocolExpression(value.expression), `${path}.expression`),
+        dimensions: uniqueStrings(value.dimensions, `${path}.dimensions`, limits.maxDatasetItems, (item, itemPath) => identifier(item, itemPath, true)),
+        filters: uniqueStrings(value.filters, `${path}.filters`, limits.maxDatasetItems, (item, itemPath) => identifier(item, itemPath)),
+        grains,
+        endpoint: validateEndpoint(value.endpoint, `${path}.endpoint`, limits),
+    };
+    if (grain !== undefined)
+        result.grain = grain;
+    optionalText(value.label, 'label', result, path, limits);
+    optionalText(value.description, 'description', result, path, limits);
+    return freezeRecord(result);
+}
+function validateLimits(input, path) {
+    const value = requireRecord(input, path);
+    exactFields(value, [], ['maxDimensions', 'maxMeasures', 'maxFilters', 'maxResultSize'], path);
+    const result = {};
+    for (const key of ['maxDimensions', 'maxMeasures', 'maxFilters', 'maxResultSize']) {
+        if (value[key] !== undefined)
+            result[key] = positiveInteger(value[key], `${path}.${key}`);
+    }
+    return freezeRecord(result);
+}
+function namedItems(input, path, maxItems, validate) {
+    const items = requireArray(input, path, maxItems).map((value, index) => validate(value, `${path}[${index}]`));
+    if (new Set(items.map(item => item.name)).size !== items.length) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', path);
+    }
+    return Object.freeze(items);
+}
+function validateDataset(input, path, limits) {
+    const value = requireRecord(input, path);
+    exactFields(value, ['name', 'source', 'tenant', 'dimensions', 'measures', 'filters', 'metrics', 'relationships'], ['timeField', 'limits', 'endpoint'], path);
+    const result = {
+        name: identifier(value.name, `${path}.name`),
+        source: boundedText(value.source, `${path}.source`, limits.maxSourceBytes),
+        tenant: validateTenant(value.tenant, `${path}.tenant`, limits),
+        dimensions: namedItems(value.dimensions, `${path}.dimensions`, limits.maxDatasetItems, (item, itemPath) => validateDimension(item, itemPath, limits)),
+        measures: namedItems(value.measures, `${path}.measures`, limits.maxDatasetItems, (item, itemPath) => validateMeasure(item, itemPath, limits)),
+        filters: namedItems(value.filters, `${path}.filters`, limits.maxDatasetItems, (item, itemPath) => validateFilter(item, itemPath, limits)),
+        metrics: namedItems(value.metrics, `${path}.metrics`, limits.maxDatasetItems, (item, itemPath) => validateMetric(item, itemPath, limits)),
+        relationships: namedItems(value.relationships, `${path}.relationships`, limits.maxDatasetItems, (item, itemPath) => validateRelationship(item, itemPath)),
+    };
+    if (value.timeField !== undefined)
+        result.timeField = identifier(value.timeField, `${path}.timeField`, true);
+    if (value.limits !== undefined)
+        result.limits = validateLimits(value.limits, `${path}.limits`);
+    if (value.endpoint !== undefined)
+        result.endpoint = validateEndpoint(value.endpoint, `${path}.endpoint`, limits);
+    return freezeRecord(result);
+}
+export function validateProtocolDatasetContract(input, options = {}) {
+    return validateDataset(input, '$', resolveDeploymentLimits(options));
+}
+function validateQuery(input, path, limits) {
+    const value = requireRecord(input, path);
+    exactFields(value, ['name', 'input', 'output', 'implementation', 'endpoint', 'tags'], ['summary', 'description'], path);
+    const result = {
+        name: identifier(value.name, `${path}.name`),
+        input: nested(() => validateProtocolSchema(value.input), `${path}.input`),
+        output: nested(() => validateProtocolSchema(value.output), `${path}.output`),
+        implementation: nested(() => validateProtocolQueryImplementation(value.implementation), `${path}.implementation`),
+        endpoint: validateEndpoint(value.endpoint, `${path}.endpoint`, limits, true),
+        tags: uniqueStrings(value.tags, `${path}.tags`, limits.maxDatasetItems, (tag, tagPath) => boundedText(tag, tagPath, limits.maxTextBytes)),
+    };
+    optionalText(value.summary, 'summary', result, path, limits);
+    optionalText(value.description, 'description', result, path, limits);
+    return freezeRecord(result);
+}
+function validateArtifact(input, path) {
+    const value = requireRecord(input, path);
+    exactFields(value, ['runtime', 'artifactSha256'], [], path);
+    if (value.runtime !== 'node' && value.runtime !== 'python') {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.runtime`);
+    }
+    if (typeof value.artifactSha256 !== 'string' || !SHA256_PATTERN.test(value.artifactSha256)) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.artifactSha256`);
+    }
+    return freezeRecord({
+        runtime: value.runtime,
+        artifactSha256: value.artifactSha256,
+    });
+}
+function validateReferences(contract) {
+    const datasets = new Map(contract.datasets.map(dataset => [dataset.name, dataset]));
+    for (const [datasetIndex, dataset] of contract.datasets.entries()) {
+        for (const [relationshipIndex, relationship] of dataset.relationships.entries()) {
+            if (!datasets.has(relationship.target)) {
+                deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.datasets[${datasetIndex}].relationships[${relationshipIndex}].target`);
+            }
+        }
+        const filters = new Set(dataset.filters.map(filter => filter.name));
+        const hasDimension = (name) => {
+            const [head, ...tail] = name.split('.');
+            if (tail.length === 0)
+                return dataset.dimensions.some(dimension => dimension.name === head);
+            const relationship = dataset.relationships.find(candidate => candidate.name === head && candidate.queryable);
+            const target = relationship ? datasets.get(relationship.target) : undefined;
+            return target?.dimensions.some(dimension => dimension.name === tail.join('.')) ?? false;
+        };
+        for (const [metricIndex, metric] of dataset.metrics.entries()) {
+            if (metric.dimensions.some(dimension => !hasDimension(dimension))
+                || metric.filters.some(filter => !filters.has(filter))) {
+                deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.datasets[${datasetIndex}].metrics[${metricIndex}]`);
+            }
+            if ((metric.kind === 'grained-metric' || metric.grains.length > 0)
+                && dataset.timeField === undefined) {
+                deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.datasets[${datasetIndex}].metrics[${metricIndex}].grains`);
+            }
+            if (dataset.tenant.kind === 'required' && metric.endpoint.tenant.kind !== 'required') {
+                deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.datasets[${datasetIndex}].metrics[${metricIndex}].endpoint.tenant`);
+            }
+        }
+        if (dataset.tenant.kind === 'required'
+            && dataset.endpoint !== undefined
+            && dataset.endpoint.tenant.kind !== 'required') {
+            deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.datasets[${datasetIndex}].endpoint.tenant`);
+        }
+    }
+    const artifacts = new Map(contract.artifacts.map(artifact => [artifact.artifactSha256, artifact.runtime]));
+    for (const [queryIndex, query] of contract.queries.entries()) {
+        if (query.implementation.kind === 'runtime-reference'
+            && artifacts.get(query.implementation.artifactSha256) !== query.implementation.runtime) {
+            deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.queries[${queryIndex}].implementation.artifactSha256`);
+        }
+        if (query.implementation.kind === 'compiled-sql') {
+            const implementationRequiresTenant = query.implementation.tenant.kind === 'required';
+            const endpointRequiresTenant = query.endpoint.tenant.kind === 'required';
+            if (implementationRequiresTenant !== endpointRequiresTenant) {
+                deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.queries[${queryIndex}].endpoint.tenant`);
+            }
+            for (const [parameterIndex, parameter] of query.implementation.parameters.entries()) {
+                if (parameter.source.kind === 'input'
+                    && !schemaContainsPath(query.input, parameter.source.path.split('.'))) {
+                    deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.queries[${queryIndex}].implementation.parameters[${parameterIndex}].source.path`);
+                }
+            }
+        }
+        if (query.implementation.kind === 'semantic-plan') {
+            const dataset = datasets.get(query.implementation.query.dataset);
+            if (!dataset) {
+                deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.queries[${queryIndex}].implementation.query.dataset`);
+            }
+            if (dataset.tenant.kind === 'required' && query.endpoint.tenant.kind !== 'required') {
+                deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.queries[${queryIndex}].endpoint.tenant`);
+            }
+        }
+    }
+}
+function schemaContainsPath(schema, segments) {
+    if (segments.length === 0)
+        return true;
+    if (schema.kind === 'any')
+        return true;
+    if (schema.kind === 'union') {
+        return schema.variants.every(variant => schemaContainsPath(variant, segments));
+    }
+    if (schema.kind === 'record') {
+        return schemaContainsPath(schema.values, segments.slice(1));
+    }
+    if (schema.kind !== 'object')
+        return false;
+    const [head, ...tail] = segments;
+    const property = schema.properties[head];
+    return property !== undefined && schemaContainsPath(property, tail);
+}
+export function validateProtocolDeploymentContract(input, options = {}) {
+    const limits = resolveDeploymentLimits(options);
+    const value = requireRecord(input, '$');
+    exactFields(value, ['kind', 'version', 'datasets', 'queries', 'artifacts'], [], '$');
+    if (value.kind !== 'hypequery-deployment')
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', '$.kind');
+    if (value.version !== 1)
+        deploymentError('HQ_DEPLOYMENT_INVALID_VERSION', '$.version');
+    const datasets = namedItems(value.datasets, '$.datasets', limits.maxDatasets, (dataset, path) => validateDataset(dataset, path, limits));
+    const queries = namedItems(value.queries, '$.queries', limits.maxQueries, (query, path) => validateQuery(query, path, limits));
+    const artifacts = Object.freeze(requireArray(value.artifacts, '$.artifacts', limits.maxArtifacts)
+        .map((artifact, index) => validateArtifact(artifact, `$.artifacts[${index}]`)));
+    if (new Set(artifacts.map(artifact => artifact.artifactSha256)).size !== artifacts.length) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', '$.artifacts');
+    }
+    const result = freezeRecord({
+        kind: 'hypequery-deployment',
+        version: 1,
+        datasets,
+        queries,
+        artifacts,
+    });
+    validateReferences(result);
+    return result;
+}

package/dist/expressions/errors.d.ts

@@ -0,0 +1,8 @@
+import type { ProtocolExpressionErrorCode } from './types.js';
+export declare class ProtocolExpressionError extends TypeError {
+    readonly code: ProtocolExpressionErrorCode;
+    readonly path: string;
+    constructor(code: ProtocolExpressionErrorCode, path?: string);
+}
+export declare function expressionError(code: ProtocolExpressionErrorCode, path?: string): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/expressions/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/expressions/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAE9D,qBAAa,uBAAwB,SAAQ,SAAS;IACpD,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,2BAA2B,EAAE,IAAI,SAAM;CAM1D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,2BAA2B,EAAE,IAAI,SAAM,GAAG,KAAK,CAEpF"}

package/dist/expressions/errors.js

@@ -0,0 +1,13 @@
+export class ProtocolExpressionError extends TypeError {
+    code;
+    path;
+    constructor(code, path = '$') {
+        super(`${code} at ${path}`);
+        this.name = 'ProtocolExpressionError';
+        this.code = code;
+        this.path = path;
+    }
+}
+export function expressionError(code, path = '$') {
+    throw new ProtocolExpressionError(code, path);
+}

package/dist/expressions/index.d.ts

@@ -0,0 +1,5 @@
+export { ProtocolExpressionError } from './errors.js';
+export { DEFAULT_PROTOCOL_EXPRESSION_LIMITS } from './limits.js';
+export { validateProtocolExpression, validateProtocolSemanticQuery } from './validate.js';
+export type { ProtocolAggregation, ProtocolBinaryOperator, ProtocolComparisonOperator, ProtocolDatasetQuery, ProtocolExpression, ProtocolExpressionErrorCode, ProtocolExpressionLimits, ProtocolExpressionOptions, ProtocolFunctionName, ProtocolMetricQuery, ProtocolOrderBy, ProtocolSemanticQuery, ProtocolTimeGrain, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/expressions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/expressions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,kCAAkC,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,0BAA0B,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AAC1F,YAAY,EACV,mBAAmB,EACnB,sBAAsB,EACtB,0BAA0B,EAC1B,oBAAoB,EACpB,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/expressions/index.js

@@ -0,0 +1,3 @@
+export { ProtocolExpressionError } from './errors.js';
+export { DEFAULT_PROTOCOL_EXPRESSION_LIMITS } from './limits.js';
+export { validateProtocolExpression, validateProtocolSemanticQuery } from './validate.js';

package/dist/expressions/limits.d.ts

@@ -0,0 +1,4 @@
+import type { ProtocolExpressionLimits, ProtocolExpressionOptions } from './types.js';
+export declare const DEFAULT_PROTOCOL_EXPRESSION_LIMITS: Readonly<ProtocolExpressionLimits>;
+export declare function resolveExpressionLimits(options?: ProtocolExpressionOptions): Readonly<ProtocolExpressionLimits>;
+//# sourceMappingURL=limits.d.ts.map

package/dist/expressions/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/expressions/limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEtF,eAAO,MAAM,kCAAkC,EAAE,QAAQ,CAAC,wBAAwB,CAIhF,CAAC;AAEH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,yBAA8B,GACtC,QAAQ,CAAC,wBAAwB,CAAC,CAWpC"}

package/dist/expressions/limits.js

@@ -0,0 +1,17 @@
+export const DEFAULT_PROTOCOL_EXPRESSION_LIMITS = Object.freeze({
+    maxDepth: 16,
+    maxNodes: 1_000,
+    maxCollectionItems: 100,
+});
+export function resolveExpressionLimits(options = {}) {
+    const limits = { ...DEFAULT_PROTOCOL_EXPRESSION_LIMITS };
+    for (const key of Object.keys(options.limits ?? {})) {
+        const value = options.limits?.[key];
+        if (!Number.isSafeInteger(value) || value < 1
+            || value > DEFAULT_PROTOCOL_EXPRESSION_LIMITS[key]) {
+            throw new RangeError(`${key} must be a positive integer no greater than the protocol v1 maximum`);
+        }
+        limits[key] = value;
+    }
+    return Object.freeze(limits);
+}