@hypequery/protocol 0.1.0 → 0.2.1

package/dist/query-implementations/errors.js

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

package/dist/query-implementations/index.d.ts

@@ -0,0 +1,5 @@
+export { ProtocolQueryImplementationError } from './errors.js';
+export { DEFAULT_PROTOCOL_QUERY_IMPLEMENTATION_LIMITS } from './limits.js';
+export { validateProtocolQueryImplementation, validateProtocolSqlExpression, } from './validate.js';
+export type { ProtocolQueryImplementation, ProtocolQueryImplementationErrorCode, ProtocolQueryImplementationLimits, ProtocolQueryImplementationOptions, ProtocolSqlDialect, ProtocolSqlExpression, ProtocolSqlParameter, ProtocolSqlParameterSource, ProtocolSqlTenantPolicy, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/query-implementations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/query-implementations/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gCAAgC,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,4CAA4C,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EACL,mCAAmC,EACnC,6BAA6B,GAC9B,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,2BAA2B,EAC3B,oCAAoC,EACpC,iCAAiC,EACjC,kCAAkC,EAClC,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/query-implementations/index.js

@@ -0,0 +1,3 @@
+export { ProtocolQueryImplementationError } from './errors.js';
+export { DEFAULT_PROTOCOL_QUERY_IMPLEMENTATION_LIMITS } from './limits.js';
+export { validateProtocolQueryImplementation, validateProtocolSqlExpression, } from './validate.js';

package/dist/query-implementations/limits.d.ts

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

package/dist/query-implementations/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/query-implementations/limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iCAAiC,EACjC,kCAAkC,EACnC,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,4CAA4C,EAAE,QAAQ,CAAC,iCAAiC,CAMnG,CAAC;AAEH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,kCAAkC,GAC1C,QAAQ,CAAC,iCAAiC,CAAC,CAa7C"}

package/dist/query-implementations/limits.js

@@ -0,0 +1,22 @@
+export const DEFAULT_PROTOCOL_QUERY_IMPLEMENTATION_LIMITS = Object.freeze({
+    maxStatementBytes: 1_048_576,
+    maxExpressionBytes: 65_536,
+    maxTypeBytes: 256,
+    maxSourceBytes: 1_024,
+    maxCollectionItems: 100,
+});
+export function resolveQueryImplementationLimits(options) {
+    const configured = options.limits ?? {};
+    const result = { ...DEFAULT_PROTOCOL_QUERY_IMPLEMENTATION_LIMITS };
+    for (const key of Object.keys(result)) {
+        const value = configured[key];
+        if (value === undefined)
+            continue;
+        if (!Number.isSafeInteger(value) || value < 1
+            || value > DEFAULT_PROTOCOL_QUERY_IMPLEMENTATION_LIMITS[key]) {
+            throw new RangeError(`Invalid query implementation limit: ${key}`);
+        }
+        result[key] = value;
+    }
+    return Object.freeze(result);
+}

package/dist/query-implementations/types.d.ts

@@ -0,0 +1,57 @@
+import type { ProtocolSemanticQuery } from '../expressions/index.js';
+import type { ProtocolIdentifier, ProtocolQualifiedIdentifier } from '../identifiers/index.js';
+import type { ProtocolSchema } from '../schemas/index.js';
+export type ProtocolSqlDialect = 'clickhouse';
+export interface ProtocolSqlExpression {
+    readonly kind: 'sql-expression';
+    readonly dialect: ProtocolSqlDialect;
+    readonly sql: string;
+    readonly output: ProtocolSchema;
+    readonly dependencies: readonly ProtocolQualifiedIdentifier[];
+}
+export type ProtocolSqlParameterSource = {
+    readonly kind: 'input';
+    readonly path: ProtocolQualifiedIdentifier;
+} | {
+    readonly kind: 'tenant';
+};
+export interface ProtocolSqlParameter {
+    readonly name: ProtocolIdentifier;
+    readonly source: ProtocolSqlParameterSource;
+    readonly clickHouseType: string;
+}
+export type ProtocolSqlTenantPolicy = {
+    readonly kind: 'required';
+    readonly parameter: ProtocolIdentifier;
+} | {
+    readonly kind: 'not-required';
+};
+export type ProtocolQueryImplementation = {
+    readonly kind: 'semantic-plan';
+    readonly query: ProtocolSemanticQuery;
+} | {
+    readonly kind: 'compiled-sql';
+    readonly dialect: ProtocolSqlDialect;
+    readonly operation: 'select';
+    readonly statement: string;
+    readonly parameters: readonly ProtocolSqlParameter[];
+    readonly readSources: readonly string[];
+    readonly tenant: ProtocolSqlTenantPolicy;
+} | {
+    readonly kind: 'runtime-reference';
+    readonly runtime: 'node' | 'python';
+    readonly artifactSha256: string;
+    readonly entrypoint: ProtocolQualifiedIdentifier;
+};
+export interface ProtocolQueryImplementationLimits {
+    readonly maxStatementBytes: number;
+    readonly maxExpressionBytes: number;
+    readonly maxTypeBytes: number;
+    readonly maxSourceBytes: number;
+    readonly maxCollectionItems: number;
+}
+export interface ProtocolQueryImplementationOptions {
+    readonly limits?: Partial<ProtocolQueryImplementationLimits>;
+}
+export type ProtocolQueryImplementationErrorCode = 'HQ_QUERY_IMPLEMENTATION_TYPE' | 'HQ_QUERY_IMPLEMENTATION_UNKNOWN_FIELD' | 'HQ_QUERY_IMPLEMENTATION_UNKNOWN_KIND' | 'HQ_QUERY_IMPLEMENTATION_INVALID_IDENTIFIER' | 'HQ_QUERY_IMPLEMENTATION_INVALID_VALUE' | 'HQ_QUERY_IMPLEMENTATION_INVALID_REFERENCE' | 'HQ_QUERY_IMPLEMENTATION_TOO_MANY_ITEMS' | 'HQ_QUERY_IMPLEMENTATION_TOO_LARGE' | 'HQ_QUERY_IMPLEMENTATION_UNSAFE_OBJECT';
+//# sourceMappingURL=types.d.ts.map

package/dist/query-implementations/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/query-implementations/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAC/F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAE9C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,SAAS,2BAA2B,EAAE,CAAC;CAC/D;AAED,MAAM,MAAM,0BAA0B,GAClC;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAA;CAAE,GACtE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEhC,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAA;CAAE,GACrE;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,CAAC;AAEtC,MAAM,MAAM,2BAA2B,GACnC;IACE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;CACvC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACrD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;CAC1C,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,2BAA2B,CAAC;CAClD,CAAC;AAEN,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,iCAAiC,CAAC,CAAC;CAC9D;AAED,MAAM,MAAM,oCAAoC,GAC5C,8BAA8B,GAC9B,uCAAuC,GACvC,sCAAsC,GACtC,4CAA4C,GAC5C,uCAAuC,GACvC,2CAA2C,GAC3C,wCAAwC,GACxC,mCAAmC,GACnC,uCAAuC,CAAC"}

package/dist/query-implementations/types.js

@@ -0,0 +1 @@
+export {};

package/dist/query-implementations/validate.d.ts

@@ -0,0 +1,4 @@
+import type { ProtocolQueryImplementation, ProtocolQueryImplementationOptions, ProtocolSqlExpression } from './types.js';
+export declare function validateProtocolSqlExpression(input: unknown, options?: ProtocolQueryImplementationOptions): ProtocolSqlExpression;
+export declare function validateProtocolQueryImplementation(input: unknown, options?: ProtocolQueryImplementationOptions): ProtocolQueryImplementation;
+//# sourceMappingURL=validate.d.ts.map

package/dist/query-implementations/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/query-implementations/validate.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,2BAA2B,EAE3B,kCAAkC,EAClC,qBAAqB,EAItB,MAAM,YAAY,CAAC;AAqLpB,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,kCAAuC,GAC/C,qBAAqB,CA6BvB;AAED,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,kCAAuC,GAC/C,2BAA2B,CAsD7B"}

package/dist/query-implementations/validate.js

@@ -0,0 +1,248 @@
+import { ProtocolExpressionError, validateProtocolSemanticQuery } from '../expressions/index.js';
+import { ProtocolIdentifierError, parseProtocolIdentifier, parseProtocolQualifiedIdentifier, } from '../identifiers/index.js';
+import { ProtocolSchemaError, validateProtocolSchema } from '../schemas/index.js';
+import { queryImplementationError } from './errors.js';
+import { resolveQueryImplementationLimits } from './limits.js';
+const textEncoder = new TextEncoder();
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+function requireRecord(input, path) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_TYPE', path);
+    }
+    const prototype = Object.getPrototypeOf(input);
+    if (prototype !== Object.prototype && prototype !== null) {
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_UNSAFE_OBJECT', path);
+    }
+    if (Object.getOwnPropertySymbols(input).length > 0) {
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_UNSAFE_OBJECT', path);
+    }
+    for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(input))) {
+        if (!descriptor.enumerable || !('value' in descriptor)) {
+            queryImplementationError('HQ_QUERY_IMPLEMENTATION_UNSAFE_OBJECT', path);
+        }
+    }
+    return input;
+}
+function requireArray(input, path, maxItems) {
+    if (!Array.isArray(input))
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_TYPE', path);
+    if (Object.getPrototypeOf(input) !== Array.prototype || Object.getOwnPropertySymbols(input).length > 0) {
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_UNSAFE_OBJECT', path);
+    }
+    if (input.length > maxItems)
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_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)) {
+            queryImplementationError('HQ_QUERY_IMPLEMENTATION_UNSAFE_OBJECT', `${path}[${index}]`);
+        }
+    }
+    if (Object.keys(input).length !== input.length) {
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_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))
+            queryImplementationError('HQ_QUERY_IMPLEMENTATION_UNKNOWN_FIELD', `${path}.${key}`);
+    }
+    for (const key of required) {
+        if (!Object.hasOwn(value, key))
+            queryImplementationError('HQ_QUERY_IMPLEMENTATION_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) {
+            queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_IDENTIFIER', path);
+        }
+        throw error;
+    }
+}
+function boundedText(value, path, maxBytes, allowSqlWhitespace = false) {
+    if (typeof value !== 'string')
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_TYPE', path);
+    if (value.trim().length === 0)
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_VALUE', path);
+    for (const character of value) {
+        const code = character.codePointAt(0);
+        if ((code <= 0x1f && !(allowSqlWhitespace && (code === 0x09 || code === 0x0a || code === 0x0d)))
+            || code === 0x7f || (code >= 0x80 && code <= 0x9f)) {
+            queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_VALUE', path);
+        }
+    }
+    if (value.length > maxBytes || textEncoder.encode(value).byteLength > maxBytes) {
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_TOO_LARGE', path);
+    }
+    return value;
+}
+function dialect(value, path) {
+    if (value !== 'clickhouse')
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_VALUE', path);
+    return value;
+}
+function validateParameterSource(input, path) {
+    const value = requireRecord(input, path);
+    if (value.kind === 'input') {
+        exactFields(value, ['kind', 'path'], [], path);
+        return freezeRecord({
+            kind: 'input', path: identifier(value.path, `${path}.path`, true),
+        });
+    }
+    if (value.kind === 'tenant') {
+        exactFields(value, ['kind'], [], path);
+        return freezeRecord({ kind: 'tenant' });
+    }
+    if (typeof value.kind !== 'string')
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_TYPE', `${path}.kind`);
+    queryImplementationError('HQ_QUERY_IMPLEMENTATION_UNKNOWN_KIND', `${path}.kind`);
+}
+function validateParameters(input, path, limits) {
+    const values = requireArray(input, path, limits.maxCollectionItems);
+    const names = new Set();
+    const result = values.map((inputValue, index) => {
+        const itemPath = `${path}[${index}]`;
+        const value = requireRecord(inputValue, itemPath);
+        exactFields(value, ['name', 'source', 'clickHouseType'], [], itemPath);
+        const name = identifier(value.name, `${itemPath}.name`);
+        if (names.has(name))
+            queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_REFERENCE', `${itemPath}.name`);
+        names.add(name);
+        return freezeRecord({
+            name,
+            source: validateParameterSource(value.source, `${itemPath}.source`),
+            clickHouseType: boundedText(value.clickHouseType, `${itemPath}.clickHouseType`, limits.maxTypeBytes),
+        });
+    });
+    return Object.freeze(result);
+}
+function validateTenant(input, path, parameters) {
+    const value = requireRecord(input, path);
+    if (value.kind === 'not-required') {
+        exactFields(value, ['kind'], [], path);
+        if (parameters.some(parameter => parameter.source.kind === 'tenant')) {
+            queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_REFERENCE', path);
+        }
+        return freezeRecord({ kind: 'not-required' });
+    }
+    if (value.kind === 'required') {
+        exactFields(value, ['kind', 'parameter'], [], path);
+        const parameter = identifier(value.parameter, `${path}.parameter`);
+        if (!parameters.some(candidate => candidate.name === parameter && candidate.source.kind === 'tenant')) {
+            queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_REFERENCE', `${path}.parameter`);
+        }
+        if (parameters.filter(candidate => candidate.source.kind === 'tenant').length !== 1) {
+            queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_REFERENCE', path);
+        }
+        return freezeRecord({ kind: 'required', parameter });
+    }
+    if (typeof value.kind !== 'string')
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_TYPE', `${path}.kind`);
+    queryImplementationError('HQ_QUERY_IMPLEMENTATION_UNKNOWN_KIND', `${path}.kind`);
+}
+function validateReadSources(input, path, limits) {
+    const values = requireArray(input, path, limits.maxCollectionItems);
+    const result = values.map((value, index) => boundedText(value, `${path}[${index}]`, limits.maxSourceBytes));
+    if (new Set(result).size !== result.length) {
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_VALUE', path);
+    }
+    return Object.freeze(result);
+}
+export function validateProtocolSqlExpression(input, options = {}) {
+    const limits = resolveQueryImplementationLimits(options);
+    const value = requireRecord(input, '$');
+    exactFields(value, ['kind', 'dialect', 'sql', 'output', 'dependencies'], [], '$');
+    if (value.kind !== 'sql-expression') {
+        if (typeof value.kind !== 'string')
+            queryImplementationError('HQ_QUERY_IMPLEMENTATION_TYPE', '$.kind');
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_UNKNOWN_KIND', '$.kind');
+    }
+    const dependencies = requireArray(value.dependencies, '$.dependencies', limits.maxCollectionItems)
+        .map((dependency, index) => identifier(dependency, `$.dependencies[${index}]`, true));
+    if (new Set(dependencies).size !== dependencies.length) {
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_VALUE', '$.dependencies');
+    }
+    let output;
+    try {
+        output = validateProtocolSchema(value.output);
+    }
+    catch (error) {
+        if (error instanceof ProtocolSchemaError) {
+            queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_VALUE', '$.output');
+        }
+        throw error;
+    }
+    return freezeRecord({
+        kind: 'sql-expression',
+        dialect: dialect(value.dialect, '$.dialect'),
+        sql: boundedText(value.sql, '$.sql', limits.maxExpressionBytes, true),
+        output,
+        dependencies: Object.freeze(dependencies),
+    });
+}
+export function validateProtocolQueryImplementation(input, options = {}) {
+    const limits = resolveQueryImplementationLimits(options);
+    const value = requireRecord(input, '$');
+    if (typeof value.kind !== 'string')
+        queryImplementationError('HQ_QUERY_IMPLEMENTATION_TYPE', '$.kind');
+    switch (value.kind) {
+        case 'semantic-plan': {
+            exactFields(value, ['kind', 'query'], [], '$');
+            try {
+                return freezeRecord({
+                    kind: 'semantic-plan', query: validateProtocolSemanticQuery(value.query),
+                });
+            }
+            catch (error) {
+                if (error instanceof ProtocolExpressionError) {
+                    queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_VALUE', '$.query');
+                }
+                throw error;
+            }
+        }
+        case 'compiled-sql': {
+            exactFields(value, [
+                'kind', 'dialect', 'operation', 'statement', 'parameters', 'readSources', 'tenant',
+            ], [], '$');
+            if (value.operation !== 'select') {
+                queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_VALUE', '$.operation');
+            }
+            const parameters = validateParameters(value.parameters, '$.parameters', limits);
+            return freezeRecord({
+                kind: 'compiled-sql',
+                dialect: dialect(value.dialect, '$.dialect'),
+                operation: 'select',
+                statement: boundedText(value.statement, '$.statement', limits.maxStatementBytes, true),
+                parameters,
+                readSources: validateReadSources(value.readSources, '$.readSources', limits),
+                tenant: validateTenant(value.tenant, '$.tenant', parameters),
+            });
+        }
+        case 'runtime-reference': {
+            exactFields(value, ['kind', 'runtime', 'artifactSha256', 'entrypoint'], [], '$');
+            if (value.runtime !== 'node' && value.runtime !== 'python') {
+                queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_VALUE', '$.runtime');
+            }
+            if (typeof value.artifactSha256 !== 'string' || !SHA256_PATTERN.test(value.artifactSha256)) {
+                queryImplementationError('HQ_QUERY_IMPLEMENTATION_INVALID_VALUE', '$.artifactSha256');
+            }
+            return freezeRecord({
+                kind: 'runtime-reference',
+                runtime: value.runtime,
+                artifactSha256: value.artifactSha256,
+                entrypoint: identifier(value.entrypoint, '$.entrypoint', true),
+            });
+        }
+        default:
+            queryImplementationError('HQ_QUERY_IMPLEMENTATION_UNKNOWN_KIND', '$.kind');
+    }
+}

package/dist/schemas/errors.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/schemas/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,qBAAa,mBAAoB,SAAQ,SAAS;IAChD,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,uBAAuB,EAAE,IAAI,SAAM;CAMtD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,uBAAuB,EAAE,IAAI,SAAM,GAAG,KAAK,CAE5E"}

package/dist/schemas/errors.js

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

package/dist/schemas/index.d.ts

@@ -0,0 +1,5 @@
+export { ProtocolSchemaError } from './errors.js';
+export { DEFAULT_PROTOCOL_SCHEMA_LIMITS } from './limits.js';
+export { validateProtocolSchema } from './validate.js';
+export type { ProtocolSchema, ProtocolSchemaErrorCode, ProtocolSchemaLimits, ProtocolSchemaOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EACV,cAAc,EACd,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/schemas/index.js

@@ -0,0 +1,3 @@
+export { ProtocolSchemaError } from './errors.js';
+export { DEFAULT_PROTOCOL_SCHEMA_LIMITS } from './limits.js';
+export { validateProtocolSchema } from './validate.js';

package/dist/schemas/limits.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/schemas/limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE9E,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,oBAAoB,CAKxE,CAAC;AAEH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,qBAA0B,GAClC,QAAQ,CAAC,oBAAoB,CAAC,CAYhC"}

package/dist/schemas/limits.js

@@ -0,0 +1,20 @@
+export const DEFAULT_PROTOCOL_SCHEMA_LIMITS = Object.freeze({
+    maxDepth: 16,
+    maxNodes: 1_000,
+    maxCollectionItems: 100,
+    maxDescriptionBytes: 4_096,
+});
+export function resolveSchemaLimits(options = {}) {
+    const limits = { ...DEFAULT_PROTOCOL_SCHEMA_LIMITS };
+    for (const key of Object.keys(options.limits ?? {})) {
+        const value = options.limits?.[key];
+        if (value === undefined)
+            continue;
+        if (!Number.isSafeInteger(value) || value < 1
+            || value > DEFAULT_PROTOCOL_SCHEMA_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);
+}

package/dist/schemas/types.d.ts

@@ -0,0 +1,60 @@
+import type { ProtocolIdentifier } from '../identifiers/index.js';
+import type { CanonicalValue } from '../values/index.js';
+interface ProtocolSchemaAnnotations {
+    readonly description?: string;
+    readonly default?: CanonicalValue;
+}
+export type ProtocolSchema = (ProtocolSchemaAnnotations & {
+    readonly kind: 'any';
+}) | {
+    readonly kind: 'void';
+    readonly description?: string;
+} | (ProtocolSchemaAnnotations & {
+    readonly kind: 'null';
+}) | (ProtocolSchemaAnnotations & {
+    readonly kind: 'boolean';
+}) | (ProtocolSchemaAnnotations & {
+    readonly kind: 'string';
+    readonly minLength?: number;
+    readonly maxLength?: number;
+}) | (ProtocolSchemaAnnotations & {
+    readonly kind: 'number' | 'integer';
+    readonly minimum?: number;
+    readonly exclusiveMinimum?: number;
+    readonly maximum?: number;
+    readonly exclusiveMaximum?: number;
+}) | (ProtocolSchemaAnnotations & {
+    readonly kind: 'literal';
+    readonly value: CanonicalValue;
+}) | (ProtocolSchemaAnnotations & {
+    readonly kind: 'enum';
+    readonly values: readonly CanonicalValue[];
+}) | (ProtocolSchemaAnnotations & {
+    readonly kind: 'array';
+    readonly items: ProtocolSchema;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+}) | (ProtocolSchemaAnnotations & {
+    readonly kind: 'object';
+    readonly properties: Readonly<Record<ProtocolIdentifier, ProtocolSchema>>;
+    readonly required: readonly ProtocolIdentifier[];
+    readonly unknownProperties: 'reject' | 'strip' | 'preserve';
+}) | (ProtocolSchemaAnnotations & {
+    readonly kind: 'record';
+    readonly values: ProtocolSchema;
+}) | (ProtocolSchemaAnnotations & {
+    readonly kind: 'union';
+    readonly variants: readonly ProtocolSchema[];
+});
+export interface ProtocolSchemaLimits {
+    readonly maxDepth: number;
+    readonly maxNodes: number;
+    readonly maxCollectionItems: number;
+    readonly maxDescriptionBytes: number;
+}
+export interface ProtocolSchemaOptions {
+    readonly limits?: Partial<ProtocolSchemaLimits>;
+}
+export type ProtocolSchemaErrorCode = 'HQ_SCHEMA_TYPE' | 'HQ_SCHEMA_UNKNOWN_FIELD' | 'HQ_SCHEMA_UNKNOWN_KIND' | 'HQ_SCHEMA_INVALID_IDENTIFIER' | 'HQ_SCHEMA_INVALID_VALUE' | 'HQ_SCHEMA_INVALID_CONSTRAINT' | 'HQ_SCHEMA_INVALID_REQUIRED' | 'HQ_SCHEMA_DUPLICATE_VALUE' | 'HQ_SCHEMA_TOO_DEEP' | 'HQ_SCHEMA_TOO_MANY_NODES' | 'HQ_SCHEMA_TOO_MANY_ITEMS' | 'HQ_SCHEMA_TOO_LARGE' | 'HQ_SCHEMA_UNSAFE_OBJECT';
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/schemas/types.d.ts.map

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

package/dist/schemas/types.js

@@ -0,0 +1 @@
+export {};

package/dist/schemas/validate.d.ts

@@ -0,0 +1,3 @@
+import type { ProtocolSchema, ProtocolSchemaOptions } from './types.js';
+export declare function validateProtocolSchema(input: unknown, options?: ProtocolSchemaOptions): ProtocolSchema;
+//# sourceMappingURL=validate.d.ts.map

package/dist/schemas/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/schemas/validate.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,cAAc,EAEd,qBAAqB,EACtB,MAAM,YAAY,CAAC;AA2ZpB,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAMhB"}