@hypequery/clickhouse 2.4.0 → 2.5.0

package/dist/core/compiled/compile.d.ts

@@ -0,0 +1,25 @@
+import { type CompiledIdentifiers, type CompiledOperation, type CompiledParameterDeclaration, type CompiledParameterValue, type CompiledQueryV1, type CompiledSensitivity, type CompiledSettings } from './types.js';
+export interface CompileQueryInput {
+    readonly operation: CompiledOperation;
+    /** Trusted build/server output. Callers never author this. */
+    readonly sql: string;
+    readonly parameters?: readonly CompiledParameterDeclaration[];
+    /** Values supplied for declared parameter names. */
+    readonly values?: Readonly<Record<string, CompiledParameterValue>>;
+    readonly settings?: CompiledSettings;
+    readonly sensitivity?: CompiledSensitivity;
+    /** Server-generated authoritative identifier; the caller may add a correlation id. */
+    readonly identifiers: CompiledIdentifiers;
+    readonly deadline?: {
+        readonly callerAtEpochMs?: number;
+        readonly policyMaxMs?: number;
+        readonly nowEpochMs: number;
+    };
+}
+/**
+ * Assemble and validate a `CompiledQueryV1` (RFC 0010). This constructs the execution
+ * request beside the legacy positional path; it performs every fail-closed check before an
+ * adapter is ever handed the query, but performs no I/O.
+ */
+export declare function compileQueryV1(input: CompileQueryInput): CompiledQueryV1;
+//# sourceMappingURL=compile.d.ts.map

package/dist/core/compiled/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/core/compiled/compile.ts"],"names":[],"mappings":"AAQA,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAmBpB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,4BAA4B,EAAE,CAAC;IAC9D,oDAAoD;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAC3C,sFAAsF;IACtF,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,iBAAiB,GAAG,eAAe,CAqCxE"}

package/dist/core/compiled/compile.js

@@ -0,0 +1,134 @@
+import { buildDebugForm } from './debug.js';
+import { CompiledQueryError } from './errors.js';
+import { assertNoValuesInSql, buildParameterBindings, validateParameterReferences, } from './parameters.js';
+import { resolveCompiledDeadline, resolveCompiledSettings } from './settings.js';
+import { COMPILED_QUERY_VERSION, } from './types.js';
+const MAX_CORRELATION_ID_BYTES = 1024;
+const MAX_QUERY_ID_BYTES = 200;
+const MAX_SQL_BYTES = 1_048_576;
+const MAX_PARAMETERS = 256;
+const MAX_CLICKHOUSE_TYPE_BYTES = 256;
+const MAX_SENSITIVITY_LABELS = 32;
+const MAX_SENSITIVITY_LABEL_BYTES = 64;
+// eslint-disable-next-line no-control-regex -- control chars are exactly what we reject
+const CONTROL_CHAR_PATTERN = /[\u0000-\u001F\u007F-\u009F]/;
+const QUERY_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+const SENSITIVITY_LABEL_PATTERN = /^[a-z][a-z0-9._-]*$/;
+const LOGICAL_TYPES = new Set([
+    'array', 'boolean', 'bytes', 'date', 'datetime', 'decimal', 'enum', 'float',
+    'integer', 'map', 'null', 'string', 'tuple', 'uuid',
+]);
+const utf8 = new TextEncoder();
+/**
+ * Assemble and validate a `CompiledQueryV1` (RFC 0010). This constructs the execution
+ * request beside the legacy positional path; it performs every fail-closed check before an
+ * adapter is ever handed the query, but performs no I/O.
+ */
+export function compileQueryV1(input) {
+    validateOperation(input.operation);
+    validateSql(input.sql);
+    const parameters = snapshotParameters(input.parameters ?? []);
+    const values = input.values ?? {};
+    validateParameterReferences(input.sql, parameters);
+    const bindings = buildParameterBindings(parameters, values);
+    assertNoValuesInSql(input.sql, bindings);
+    const settings = resolveCompiledSettings(input.settings ?? {});
+    const identifiers = validateIdentifiers(input.identifiers);
+    const deadlineInputs = input.deadline
+        ? {
+            ...input.deadline,
+            policyMaxMs: minimumDefined(input.deadline.policyMaxMs, settings.maxExecutionMs),
+        }
+        : undefined;
+    const deadline = deadlineInputs
+        ? resolveCompiledDeadline(deadlineInputs)
+        : undefined;
+    const sensitivity = snapshotSensitivity(input.sensitivity);
+    const debug = buildDebugForm(input.sql, parameters, settings);
+    return Object.freeze({
+        version: COMPILED_QUERY_VERSION,
+        operation: input.operation,
+        sql: input.sql,
+        parameters,
+        bindings,
+        settings,
+        identifiers,
+        deadline,
+        sensitivity,
+        debug,
+    });
+}
+function minimumDefined(left, right) {
+    if (left === undefined)
+        return right;
+    if (right === undefined)
+        return left;
+    return Math.min(left, right);
+}
+function validateOperation(operation) {
+    if (operation !== 'query' && operation !== 'command' && operation !== 'insert') {
+        throw new CompiledQueryError('input-invalid', 'The compiled operation is invalid.');
+    }
+}
+function validateSql(sql) {
+    if (typeof sql !== 'string' || sql.length === 0 || utf8.encode(sql).length > MAX_SQL_BYTES) {
+        throw new CompiledQueryError('input-invalid', 'The compiled SQL is empty or too large.');
+    }
+}
+function snapshotParameters(input) {
+    if (!Array.isArray(input) || input.length > MAX_PARAMETERS) {
+        throw new CompiledQueryError('too-large', 'The compiled query has too many parameters.');
+    }
+    return Object.freeze(input.map((declaration) => {
+        const logical = declaration?.type?.logical;
+        const clickHouseType = declaration?.type?.clickHouseType;
+        if (!LOGICAL_TYPES.has(logical)
+            || typeof clickHouseType !== 'string'
+            || clickHouseType.length === 0
+            || CONTROL_CHAR_PATTERN.test(clickHouseType)
+            || utf8.encode(clickHouseType).length > MAX_CLICKHOUSE_TYPE_BYTES
+            || typeof declaration.optional !== 'boolean') {
+            throw new CompiledQueryError('input-invalid', 'A parameter declaration is invalid.');
+        }
+        return Object.freeze({
+            name: declaration.name,
+            type: Object.freeze({ logical, clickHouseType }),
+            optional: declaration.optional,
+        });
+    }));
+}
+function snapshotSensitivity(input) {
+    const tenantScoped = input?.tenantScoped ?? false;
+    const labels = input?.labels ?? [];
+    if (typeof tenantScoped !== 'boolean' || !Array.isArray(labels) || labels.length > MAX_SENSITIVITY_LABELS) {
+        throw new CompiledQueryError('input-invalid', 'Sensitivity metadata is invalid.');
+    }
+    const snapshot = labels.map((label) => {
+        if (typeof label !== 'string'
+            || !SENSITIVITY_LABEL_PATTERN.test(label)
+            || utf8.encode(label).length > MAX_SENSITIVITY_LABEL_BYTES) {
+            throw new CompiledQueryError('input-invalid', 'A sensitivity label is invalid.');
+        }
+        return label;
+    });
+    return Object.freeze({ tenantScoped, labels: Object.freeze(snapshot) });
+}
+function validateIdentifiers(identifiers) {
+    if (typeof identifiers.queryId !== 'string'
+        || !QUERY_ID_PATTERN.test(identifiers.queryId)
+        || utf8.encode(identifiers.queryId).length > MAX_QUERY_ID_BYTES) {
+        throw new CompiledQueryError('internal', 'A server-generated query id is required.');
+    }
+    const { correlationId } = identifiers;
+    if (correlationId !== undefined) {
+        if (CONTROL_CHAR_PATTERN.test(correlationId)) {
+            throw new CompiledQueryError('input-invalid', 'The correlation id contains control characters.');
+        }
+        if (utf8.encode(correlationId).length > MAX_CORRELATION_ID_BYTES) {
+            throw new CompiledQueryError('too-large', 'The correlation id exceeds the allowed size.');
+        }
+    }
+    return Object.freeze(correlationId === undefined
+        ? { queryId: identifiers.queryId }
+        : { queryId: identifiers.queryId, correlationId });
+}

package/dist/core/compiled/debug.d.ts

@@ -0,0 +1,7 @@
+import type { CompiledDebugForm, CompiledParameterDeclaration, CompiledSettings } from './types.js';
+/**
+ * Build the redacted, non-executable debug form. It carries no parameter values, tenant
+ * values, credentials, or setting values — only names, declared types, and structure.
+ */
+export declare function buildDebugForm(sql: string, parameters: readonly CompiledParameterDeclaration[], settings: CompiledSettings): CompiledDebugForm;
+//# sourceMappingURL=debug.d.ts.map

package/dist/core/compiled/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../../src/core/compiled/debug.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,4BAA4B,EAC5B,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAWpB;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,SAAS,4BAA4B,EAAE,EACnD,QAAQ,EAAE,gBAAgB,GACzB,iBAAiB,CAkBnB"}

package/dist/core/compiled/debug.js

@@ -0,0 +1,25 @@
+import { replaceParameterPlaceholders } from './parameters.js';
+/**
+ * Marker wrapping placeholders in the debug form. The guillemets make the rendered SQL
+ * deliberately invalid as database SQL — it cannot be pasted into a client and run — while
+ * still showing structure and declared types (RFC 0010 §Debug form).
+ */
+const DEBUG_OPEN = '«param ';
+const DEBUG_CLOSE = '»';
+/**
+ * Build the redacted, non-executable debug form. It carries no parameter values, tenant
+ * values, credentials, or setting values — only names, declared types, and structure.
+ */
+export function buildDebugForm(sql, parameters, settings) {
+    const redactedSql = replaceParameterPlaceholders(sql, (name, type) => `${DEBUG_OPEN}${name}: ${type}${DEBUG_CLOSE}`);
+    return Object.freeze({
+        sql: redactedSql,
+        parameters: Object.freeze(parameters.map((p) => Object.freeze({
+            name: p.name,
+            type: p.type.clickHouseType,
+            optional: p.optional,
+        }))),
+        // Setting names only; values are policy and never appear in diagnostics.
+        settings: Object.freeze(Object.keys(settings).filter((key) => settings[key] !== undefined)),
+    });
+}

package/dist/core/compiled/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Public execution-failure envelope from RFC 0010 §Error envelope.
+ *
+ * The category set is closed and stable within version 1. It matches the frozen set in
+ * `@hypequery/protocol` (`events` module) so runtime failures and emitted diagnostics
+ * speak the same vocabulary. New categories require a new contract version.
+ */
+export declare const COMPILED_ERROR_CATEGORIES: readonly ["input-invalid", "unauthenticated", "forbidden", "tenant-required", "not-found", "too-large", "aborted", "deadline-exceeded", "unavailable", "internal"];
+export type CompiledErrorCategory = (typeof COMPILED_ERROR_CATEGORIES)[number];
+export declare function isCompiledErrorCategory(value: unknown): value is CompiledErrorCategory;
+export declare function isClientFaultCategory(category: CompiledErrorCategory): boolean;
+/** The stable, serializable error object surfaced to callers. */
+export interface CompiledErrorEnvelope {
+    readonly category: CompiledErrorCategory;
+    readonly message: string;
+    /** Authoritative query identifier; safe for logs. Absent only before one is assigned. */
+    readonly queryId?: string;
+}
+export interface CompiledQueryErrorOptions {
+    readonly queryId?: string;
+    /** Non-public cause retained for local logging; never serialized into the envelope. */
+    readonly cause?: unknown;
+}
+/**
+ * The only execution-failure shape a runtime may surface for a compiled query. For
+ * server-fault categories the caller-facing message is fixed to a generic string so no
+ * adapter text, SQL, value, or tenant identifier can leak.
+ */
+export declare class CompiledQueryError extends Error {
+    readonly category: CompiledErrorCategory;
+    readonly queryId?: string;
+    readonly cause?: unknown;
+    constructor(category: CompiledErrorCategory, message: string, options?: CompiledQueryErrorOptions);
+    private static resolveMessage;
+    /** The redacted, serializable envelope. Only closed fields; no `cause`, no stack. */
+    toEnvelope(): CompiledErrorEnvelope;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/compiled/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/compiled/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,oKAW5B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAoB/E,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAKtF;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAE9E;AAED,iEAAiE;AACjE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yFAAyF;IACzF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAGhC,QAAQ,EAAE,qBAAqB,EAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,yBAA8B;IAUzC,OAAO,CAAC,MAAM,CAAC,cAAc;IAY7B,qFAAqF;IACrF,UAAU,IAAI,qBAAqB;CAKpC"}

package/dist/core/compiled/errors.js

@@ -0,0 +1,91 @@
+/**
+ * Public execution-failure envelope from RFC 0010 §Error envelope.
+ *
+ * The category set is closed and stable within version 1. It matches the frozen set in
+ * `@hypequery/protocol` (`events` module) so runtime failures and emitted diagnostics
+ * speak the same vocabulary. New categories require a new contract version.
+ */
+export const COMPILED_ERROR_CATEGORIES = [
+    'input-invalid',
+    'unauthenticated',
+    'forbidden',
+    'tenant-required',
+    'not-found',
+    'too-large',
+    'aborted',
+    'deadline-exceeded',
+    'unavailable',
+    'internal',
+];
+/**
+ * Categories that describe a client-supplied fault. Their messages MAY carry a safe,
+ * caller-facing explanation. Every other category is a server/dependency fault whose
+ * message MUST NOT expose adapter error text, SQL, values, or tenant identifiers.
+ */
+const CLIENT_FAULT_CATEGORIES = new Set([
+    'input-invalid',
+    'unauthenticated',
+    'forbidden',
+    'tenant-required',
+    'not-found',
+    'too-large',
+    'aborted',
+    'deadline-exceeded',
+]);
+const SAFE_MESSAGE_PATTERN = /[\r\n\t]/;
+export function isCompiledErrorCategory(value) {
+    return (typeof value === 'string' &&
+        COMPILED_ERROR_CATEGORIES.includes(value));
+}
+export function isClientFaultCategory(category) {
+    return CLIENT_FAULT_CATEGORIES.has(category);
+}
+/**
+ * The only execution-failure shape a runtime may surface for a compiled query. For
+ * server-fault categories the caller-facing message is fixed to a generic string so no
+ * adapter text, SQL, value, or tenant identifier can leak.
+ */
+export class CompiledQueryError extends Error {
+    category;
+    queryId;
+    cause;
+    constructor(category, message, options = {}) {
+        const safeMessage = CompiledQueryError.resolveMessage(category, message);
+        super(safeMessage);
+        this.name = 'CompiledQueryError';
+        this.category = category;
+        this.queryId = options.queryId;
+        this.cause = options.cause;
+    }
+    static resolveMessage(category, message) {
+        if (!isClientFaultCategory(category)) {
+            // Server-fault categories never carry a caller-authored message.
+            return DEFAULT_SERVER_FAULT_MESSAGE[category] ?? 'The request could not be completed.';
+        }
+        const trimmed = typeof message === 'string' ? message.trim() : '';
+        if (trimmed.length === 0 || SAFE_MESSAGE_PATTERN.test(trimmed)) {
+            return DEFAULT_CLIENT_FAULT_MESSAGE[category] ?? 'The request was rejected.';
+        }
+        return trimmed;
+    }
+    /** The redacted, serializable envelope. Only closed fields; no `cause`, no stack. */
+    toEnvelope() {
+        return this.queryId === undefined
+            ? { category: this.category, message: this.message }
+            : { category: this.category, message: this.message, queryId: this.queryId };
+    }
+}
+const DEFAULT_CLIENT_FAULT_MESSAGE = {
+    'input-invalid': 'The request parameters were invalid.',
+    unauthenticated: 'Authentication is required.',
+    forbidden: 'Access is denied.',
+    'tenant-required': 'A tenant context is required.',
+    'not-found': 'The requested resource was not found.',
+    'too-large': 'The request or result exceeded an allowed bound.',
+    aborted: 'The request was cancelled.',
+    'deadline-exceeded': 'The request deadline was exceeded.',
+};
+const DEFAULT_SERVER_FAULT_MESSAGE = {
+    unavailable: 'The executor is temporarily unavailable.',
+    internal: 'The request could not be completed.',
+};

package/dist/core/compiled/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CompiledQuery v1 (RFC 0010) — the versioned execution-request contract for the
+ * ClickHouse runtime, introduced beside the legacy positional path. See `./types.ts`.
+ *
+ * CH-01 provides the shape, validation, and redacted debug/error surfaces. Wiring the real
+ * `@clickhouse/client` `{name:Type}` + `query_params` transport, capability negotiation,
+ * and end-to-end cancellation is CH-02+ and does not touch the legacy adapter signature.
+ */
+export { COMPILED_QUERY_VERSION, type CompiledDeadline, type CompiledDebugForm, type CompiledIdentifiers, type CompiledOperation, type CompiledParameterBindings, type CompiledParameterDeclaration, type CompiledParameterType, type CompiledParameterValue, type CompiledQueryV1, type CompiledSensitivity, type CompiledSettings, } from './types.js';
+export { compileQueryV1, type CompileQueryInput } from './compile.js';
+export { assertNoValuesInSql, buildParameterBindings, extractReferencedParameters, validateParameterReferences, } from './parameters.js';
+export { COMPILED_SETTING_BOUNDS, type CompiledSettingName, type DeadlineInputs, type SettingBound, resolveCompiledDeadline, resolveCompiledSettings, } from './settings.js';
+export { COMPILED_ERROR_CATEGORIES, CompiledQueryError, type CompiledErrorCategory, type CompiledErrorEnvelope, type CompiledQueryErrorOptions, isClientFaultCategory, isCompiledErrorCategory, } from './errors.js';
+export { buildDebugForm } from './debug.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/compiled/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/compiled/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,4BAA4B,EACjC,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtE,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,uBAAuB,EACvB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,yBAAyB,EACzB,kBAAkB,EAClB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/core/compiled/index.js

@@ -0,0 +1,14 @@
+/**
+ * CompiledQuery v1 (RFC 0010) — the versioned execution-request contract for the
+ * ClickHouse runtime, introduced beside the legacy positional path. See `./types.ts`.
+ *
+ * CH-01 provides the shape, validation, and redacted debug/error surfaces. Wiring the real
+ * `@clickhouse/client` `{name:Type}` + `query_params` transport, capability negotiation,
+ * and end-to-end cancellation is CH-02+ and does not touch the legacy adapter signature.
+ */
+export { COMPILED_QUERY_VERSION, } from './types.js';
+export { compileQueryV1 } from './compile.js';
+export { assertNoValuesInSql, buildParameterBindings, extractReferencedParameters, validateParameterReferences, } from './parameters.js';
+export { COMPILED_SETTING_BOUNDS, resolveCompiledDeadline, resolveCompiledSettings, } from './settings.js';
+export { COMPILED_ERROR_CATEGORIES, CompiledQueryError, isClientFaultCategory, isCompiledErrorCategory, } from './errors.js';
+export { buildDebugForm } from './debug.js';

package/dist/core/compiled/parameters.d.ts

@@ -0,0 +1,28 @@
+import type { CompiledParameterBindings, CompiledParameterDeclaration, CompiledParameterValue } from './types.js';
+/** Extract the set of parameter names a SQL text references via `{name:Type}`. */
+export declare function extractReferencedParameters(sql: string): Set<string>;
+export declare function replaceParameterPlaceholders(sql: string, replace: (name: string, type: string) => string): string;
+/**
+ * Validate that the SQL only references declared parameters. Fails closed when a
+ * placeholder names an undeclared parameter (RFC 0010 §Parameters).
+ */
+export declare function validateParameterReferences(sql: string, declarations: readonly CompiledParameterDeclaration[]): void;
+/**
+ * Resolve supplied values against declarations into the native `{name: value}` bindings
+ * an adapter binds to server parameters. Fail-closed rules (RFC 0010 §Parameters):
+ *   - a supplied name that is not declared is rejected;
+ *   - a required declared name with no supplied value is rejected;
+ *   - an optional declared name may be absent;
+ *   - every supplied value is validated (RFC 0001 for tagged values).
+ *
+ * No value is ever concatenated into SQL text: values live only in the returned bindings.
+ */
+export declare function buildParameterBindings(declarations: readonly CompiledParameterDeclaration[], values: Readonly<Record<string, CompiledParameterValue>>): CompiledParameterBindings;
+/**
+ * Assert the invariant that no bound value has leaked into the SQL text. The compile path
+ * never substitutes values, so this is a defense-in-depth check: the SQL must reference
+ * every non-optional bound name through a placeholder and must not be the legacy
+ * positional form (`?`).
+ */
+export declare function assertNoValuesInSql(sql: string, bindings: CompiledParameterBindings): void;
+//# sourceMappingURL=parameters.d.ts.map

package/dist/core/compiled/parameters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameters.d.ts","sourceRoot":"","sources":["../../../src/core/compiled/parameters.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,yBAAyB,EACzB,4BAA4B,EAC5B,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAsIpB,kFAAkF;AAClF,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAEpE;AAED,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,GAC9C,MAAM,CAUR;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,SAAS,4BAA4B,EAAE,GACpD,IAAI,CAoBN;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,SAAS,4BAA4B,EAAE,EACrD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,GACvD,yBAAyB,CAyC3B;AAmFD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,yBAAyB,GAClC,IAAI,CAyBN"}

package/dist/core/compiled/parameters.js

@@ -0,0 +1,282 @@
+import { ProtocolValueError, isProtocolIdentifier, validateCanonicalValue, } from '@hypequery/protocol';
+import { CompiledQueryError } from './errors.js';
+const LOGICAL_TYPES = new Set([
+    'array', 'boolean', 'bytes', 'date', 'datetime', 'decimal', 'enum', 'float',
+    'integer', 'map', 'null', 'string', 'tuple', 'uuid',
+]);
+function skipQuoted(sql, start, quote) {
+    let index = start + 1;
+    while (index < sql.length) {
+        if (sql[index] === '\\') {
+            index += 2;
+            continue;
+        }
+        if (sql[index] === quote) {
+            if (sql[index + 1] === quote) {
+                index += 2;
+                continue;
+            }
+            return index + 1;
+        }
+        index += 1;
+    }
+    return sql.length;
+}
+function parsePlaceholder(sql, start) {
+    let index = start + 1;
+    while (/\s/.test(sql[index] ?? ''))
+        index += 1;
+    const nameStart = index;
+    if (!/[A-Za-z_]/.test(sql[index] ?? ''))
+        return undefined;
+    index += 1;
+    while (/[A-Za-z0-9_]/.test(sql[index] ?? ''))
+        index += 1;
+    const name = sql.slice(nameStart, index);
+    while (/\s/.test(sql[index] ?? ''))
+        index += 1;
+    if (sql[index] !== ':')
+        return undefined;
+    index += 1;
+    const typeStart = index;
+    let quote;
+    let parenthesisDepth = 0;
+    while (index < sql.length) {
+        const character = sql[index];
+        if (quote) {
+            if (character === '\\') {
+                index += 2;
+                continue;
+            }
+            if (character === quote) {
+                if (sql[index + 1] === quote) {
+                    index += 2;
+                    continue;
+                }
+                quote = undefined;
+            }
+            index += 1;
+            continue;
+        }
+        if (character === "'" || character === '"' || character === '`') {
+            quote = character;
+            index += 1;
+            continue;
+        }
+        if (character === '(')
+            parenthesisDepth += 1;
+        if (character === ')') {
+            parenthesisDepth -= 1;
+            if (parenthesisDepth < 0)
+                return undefined;
+        }
+        if (character === '{')
+            return undefined;
+        if (character === '}' && parenthesisDepth === 0) {
+            const type = sql.slice(typeStart, index).trim();
+            if (type.length === 0)
+                return undefined;
+            return { name, type, start, end: index + 1 };
+        }
+        index += 1;
+    }
+    return undefined;
+}
+function scanSqlParameters(sql) {
+    const references = [];
+    let hasPositionalPlaceholder = false;
+    let index = 0;
+    while (index < sql.length) {
+        const character = sql[index];
+        if (character === "'" || character === '"' || character === '`') {
+            index = skipQuoted(sql, index, character);
+            continue;
+        }
+        if (character === '-' && sql[index + 1] === '-') {
+            const newline = sql.indexOf('\n', index + 2);
+            index = newline === -1 ? sql.length : newline + 1;
+            continue;
+        }
+        if (character === '#') {
+            const newline = sql.indexOf('\n', index + 1);
+            index = newline === -1 ? sql.length : newline + 1;
+            continue;
+        }
+        if (character === '/' && sql[index + 1] === '*') {
+            const close = sql.indexOf('*/', index + 2);
+            index = close === -1 ? sql.length : close + 2;
+            continue;
+        }
+        if (character === '?')
+            hasPositionalPlaceholder = true;
+        if (character === '{') {
+            const reference = parsePlaceholder(sql, index);
+            if (reference) {
+                references.push(reference);
+                index = reference.end;
+                continue;
+            }
+        }
+        index += 1;
+    }
+    return { references, hasPositionalPlaceholder };
+}
+/** Extract the set of parameter names a SQL text references via `{name:Type}`. */
+export function extractReferencedParameters(sql) {
+    return new Set(scanSqlParameters(sql).references.map(({ name }) => name));
+}
+export function replaceParameterPlaceholders(sql, replace) {
+    const references = scanSqlParameters(sql).references;
+    let result = '';
+    let offset = 0;
+    for (const reference of references) {
+        result += sql.slice(offset, reference.start);
+        result += replace(reference.name, reference.type);
+        offset = reference.end;
+    }
+    return result + sql.slice(offset);
+}
+/**
+ * Validate that the SQL only references declared parameters. Fails closed when a
+ * placeholder names an undeclared parameter (RFC 0010 §Parameters).
+ */
+export function validateParameterReferences(sql, declarations) {
+    const declared = new Map(declarations.map((declaration) => [
+        declaration.name,
+        declaration,
+    ]));
+    for (const reference of scanSqlParameters(sql).references) {
+        const declaration = declared.get(reference.name);
+        if (!declaration) {
+            throw new CompiledQueryError('input-invalid', `SQL references undeclared parameter ${reference.name}.`);
+        }
+        if (reference.type !== declaration.type.clickHouseType) {
+            throw new CompiledQueryError('input-invalid', `SQL parameter ${reference.name} does not match its declared ClickHouse type.`);
+        }
+    }
+}
+/**
+ * Resolve supplied values against declarations into the native `{name: value}` bindings
+ * an adapter binds to server parameters. Fail-closed rules (RFC 0010 §Parameters):
+ *   - a supplied name that is not declared is rejected;
+ *   - a required declared name with no supplied value is rejected;
+ *   - an optional declared name may be absent;
+ *   - every supplied value is validated (RFC 0001 for tagged values).
+ *
+ * No value is ever concatenated into SQL text: values live only in the returned bindings.
+ */
+export function buildParameterBindings(declarations, values) {
+    const declaredByName = new Map();
+    for (const declaration of declarations) {
+        if (!isProtocolIdentifier(declaration.name)) {
+            throw new CompiledQueryError('input-invalid', 'Parameter declaration has an invalid name.');
+        }
+        if (declaredByName.has(declaration.name)) {
+            throw new CompiledQueryError('input-invalid', `Duplicate parameter declaration ${declaration.name}.`);
+        }
+        declaredByName.set(declaration.name, declaration);
+    }
+    for (const suppliedName of Object.keys(values)) {
+        if (!declaredByName.has(suppliedName)) {
+            throw new CompiledQueryError('input-invalid', `Value supplied for undeclared parameter ${suppliedName}.`);
+        }
+    }
+    const bindings = {};
+    for (const [name, declaration] of declaredByName) {
+        const present = Object.prototype.hasOwnProperty.call(values, name);
+        if (!present) {
+            if (declaration.optional)
+                continue;
+            throw new CompiledQueryError('input-invalid', `Required parameter ${name} is missing.`);
+        }
+        bindings[name] = validateParameterValue(name, declaration, values[name]);
+    }
+    return Object.freeze(bindings);
+}
+function validateParameterValue(name, declaration, value) {
+    try {
+        const validated = validateCanonicalValue(value, {
+            declaredClickHouseType: declaration.type.clickHouseType,
+        });
+        validateLogicalType(name, declaration, validated);
+        return validated;
+    }
+    catch (error) {
+        if (error instanceof ProtocolValueError) {
+            throw new CompiledQueryError('input-invalid', `Parameter ${name} failed value validation (${error.code}).`, { cause: error });
+        }
+        throw error;
+    }
+}
+function logicalTypeOf(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return 'string';
+    if (typeof value === 'number')
+        return 'float';
+    if (typeof value === 'boolean')
+        return 'boolean';
+    return value.$hypequery.type;
+}
+function unwrapNullable(type) {
+    const trimmed = type.trim();
+    if (trimmed.startsWith('Nullable(') && trimmed.endsWith(')')) {
+        return { nullable: true, inner: trimmed.slice(9, -1).trim() };
+    }
+    return { nullable: false, inner: trimmed };
+}
+function clickHouseTypeSupportsLogical(type, logical) {
+    const { nullable, inner } = unwrapNullable(type);
+    if (logical === 'null')
+        return nullable;
+    switch (logical) {
+        case 'string': return /^(?:String|FixedString\(\d+\)|LowCardinality\(String\))$/.test(inner);
+        case 'float': return /^Float(?:32|64)$/.test(inner);
+        case 'boolean': return /^(?:Bool|Boolean)$/.test(inner);
+        case 'integer': return /^(?:U?Int)(?:8|16|32|64|128|256)$/.test(inner);
+        case 'decimal': return /^Decimal(?:(?:32|64|128|256)\(\d+\)|\(\d+\s*,\s*\d+\))$/.test(inner);
+        case 'date': return /^(?:Date|Date32)$/.test(inner);
+        case 'datetime': return /^DateTime(?:64)?(?:\(.*\))?$/.test(inner);
+        case 'uuid': return inner === 'UUID';
+        case 'bytes': return /^(?:String|FixedString\(\d+\))$/.test(inner);
+        case 'enum': return /^Enum(?:8|16)\(.*\)$/.test(inner);
+        case 'array': return /^Array\(.+\)$/.test(inner);
+        case 'tuple': return /^Tuple\(.+\)$/.test(inner);
+        case 'map': return /^Map\(.+\)$/.test(inner);
+        default: return false;
+    }
+}
+function validateLogicalType(name, declaration, value) {
+    const actual = logicalTypeOf(value);
+    const declared = declaration.type.logical;
+    if (!LOGICAL_TYPES.has(declared) || (actual !== declared && actual !== 'null')) {
+        throw new CompiledQueryError('input-invalid', `Parameter ${name} does not match its declared logical type.`);
+    }
+    if (!clickHouseTypeSupportsLogical(declaration.type.clickHouseType, actual)) {
+        throw new CompiledQueryError('input-invalid', `Parameter ${name} does not match its declared ClickHouse type.`);
+    }
+}
+/**
+ * Assert the invariant that no bound value has leaked into the SQL text. The compile path
+ * never substitutes values, so this is a defense-in-depth check: the SQL must reference
+ * every non-optional bound name through a placeholder and must not be the legacy
+ * positional form (`?`).
+ */
+export function assertNoValuesInSql(sql, bindings) {
+    const scan = scanSqlParameters(sql);
+    if (scan.hasPositionalPlaceholder) {
+        throw new CompiledQueryError('input-invalid', 'Compiled SQL must not use positional placeholders.');
+    }
+    const referenced = new Set(scan.references.map(({ name }) => name));
+    for (const name of Object.keys(bindings)) {
+        if (!referenced.has(name)) {
+            throw new CompiledQueryError('input-invalid', `Bound parameter ${name} is not referenced by the SQL.`);
+        }
+    }
+    for (const name of referenced) {
+        if (!Object.prototype.hasOwnProperty.call(bindings, name)) {
+            throw new CompiledQueryError('input-invalid', `SQL parameter ${name} does not have a bound value.`);
+        }
+    }
+}

package/dist/core/compiled/settings.d.ts

@@ -0,0 +1,49 @@
+import type { CompiledDeadline, CompiledSettings } from './types.js';
+/**
+ * Closed, typed settings allow-list (RFC 0010 §Settings). Each entry defines an inclusive
+ * range; products may TIGHTEN a range but never loosen it. Settings originate only from
+ * trusted components — a request can never set, override, or relax them.
+ */
+export interface SettingBound {
+    readonly min: number;
+    readonly max: number;
+}
+export declare const COMPILED_SETTING_BOUNDS: Readonly<{
+    readonly maxExecutionMs: {
+        readonly min: 1;
+        readonly max: 3600000;
+    };
+    readonly maxResultRows: {
+        readonly min: 0;
+        readonly max: 1000000000000;
+    };
+    readonly maxResultBytes: {
+        readonly min: 0;
+        readonly max: 1099511627776;
+    };
+}>;
+export type CompiledSettingName = keyof typeof COMPILED_SETTING_BOUNDS;
+/**
+ * Clamp trusted settings into the allow-list. A value outside the closed range is
+ * rejected fail-closed rather than silently coerced, since settings are trusted input and
+ * an out-of-range value signals a policy bug, not caller data.
+ */
+export declare function resolveCompiledSettings(input: CompiledSettings): CompiledSettings;
+export interface DeadlineInputs {
+    /** Absolute caller-supplied deadline, epoch-millis. */
+    readonly callerAtEpochMs?: number;
+    /** Policy-derived maximum window from `now`, milliseconds. */
+    readonly policyMaxMs?: number;
+    /** Current time, epoch-millis. Injected so resolution stays deterministic/testable. */
+    readonly nowEpochMs: number;
+}
+/**
+ * Resolve the effective deadline (RFC 0010 §Deadline and cancellation precedence).
+ *
+ * The effective deadline is the EARLIER of the caller-supplied deadline and the
+ * policy-derived maximum — a caller can shorten but never extend the window. A supplied
+ * deadline at or before `now` fails immediately with `deadline-exceeded` rather than being
+ * extended or ignored.
+ */
+export declare function resolveCompiledDeadline(inputs: DeadlineInputs): CompiledDeadline | undefined;
+//# sourceMappingURL=settings.d.ts.map

package/dist/core/compiled/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../src/core/compiled/settings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;EAI8B,CAAC;AAEnE,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,uBAAuB,CAAC;AAEvE;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,gBAAgB,GAAG,gBAAgB,CAejF;AAED,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,uFAAuF;IACvF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,SAAS,CAyC5F"}

package/dist/core/compiled/settings.js

@@ -0,0 +1,65 @@
+import { CompiledQueryError } from './errors.js';
+export const COMPILED_SETTING_BOUNDS = Object.freeze({
+    maxExecutionMs: { min: 1, max: 3_600_000 },
+    maxResultRows: { min: 0, max: 1_000_000_000_000 },
+    maxResultBytes: { min: 0, max: 1_099_511_627_776 },
+});
+/**
+ * Clamp trusted settings into the allow-list. A value outside the closed range is
+ * rejected fail-closed rather than silently coerced, since settings are trusted input and
+ * an out-of-range value signals a policy bug, not caller data.
+ */
+export function resolveCompiledSettings(input) {
+    const resolved = {};
+    for (const key of Object.keys(COMPILED_SETTING_BOUNDS)) {
+        const value = input[key];
+        if (value === undefined)
+            continue;
+        const bound = COMPILED_SETTING_BOUNDS[key];
+        if (!Number.isInteger(value) || value < bound.min || value > bound.max) {
+            throw new CompiledQueryError('input-invalid', `Setting ${key} is outside its allowed range.`);
+        }
+        resolved[key] = value;
+    }
+    return Object.freeze(resolved);
+}
+/**
+ * Resolve the effective deadline (RFC 0010 §Deadline and cancellation precedence).
+ *
+ * The effective deadline is the EARLIER of the caller-supplied deadline and the
+ * policy-derived maximum — a caller can shorten but never extend the window. A supplied
+ * deadline at or before `now` fails immediately with `deadline-exceeded` rather than being
+ * extended or ignored.
+ */
+export function resolveCompiledDeadline(inputs) {
+    const { callerAtEpochMs, policyMaxMs, nowEpochMs } = inputs;
+    if (!Number.isSafeInteger(nowEpochMs) || nowEpochMs < 0) {
+        throw new CompiledQueryError('input-invalid', 'The current time is invalid.');
+    }
+    if (callerAtEpochMs !== undefined
+        && (!Number.isSafeInteger(callerAtEpochMs) || callerAtEpochMs < 0)) {
+        throw new CompiledQueryError('input-invalid', 'The supplied deadline is invalid.');
+    }
+    if (policyMaxMs !== undefined && (!Number.isSafeInteger(policyMaxMs) || policyMaxMs <= 0)) {
+        throw new CompiledQueryError('input-invalid', 'The policy deadline window is invalid.');
+    }
+    const policyAt = policyMaxMs === undefined ? undefined : nowEpochMs + policyMaxMs;
+    if (policyAt !== undefined && !Number.isSafeInteger(policyAt)) {
+        throw new CompiledQueryError('input-invalid', 'The policy deadline is outside the safe range.');
+    }
+    if (callerAtEpochMs !== undefined && callerAtEpochMs <= nowEpochMs) {
+        throw new CompiledQueryError('deadline-exceeded', 'The supplied deadline is at or before the current time.');
+    }
+    if (callerAtEpochMs === undefined && policyAt === undefined) {
+        return undefined;
+    }
+    if (callerAtEpochMs === undefined) {
+        return Object.freeze({ atEpochMs: policyAt, source: 'policy' });
+    }
+    if (policyAt === undefined) {
+        return Object.freeze({ atEpochMs: callerAtEpochMs, source: 'caller' });
+    }
+    return Object.freeze(callerAtEpochMs <= policyAt
+        ? { atEpochMs: callerAtEpochMs, source: 'caller' }
+        : { atEpochMs: policyAt, source: 'policy' });
+}

package/dist/core/compiled/types.d.ts

@@ -0,0 +1,115 @@
+import type { ProtocolIdentifier, TaggedValue } from '@hypequery/protocol';
+/**
+ * Execution-request contract from RFC 0010 (compiled query, error, cancellation),
+ * realized for the ClickHouse runtime.
+ *
+ * This is the versioned shape a runtime hands to an adapter. It sits *beside* the
+ * legacy positional path (`adapter.query(sql, params: unknown[])`, which renders
+ * values into SQL text via `substituteParameters`). Nothing here lets a request
+ * author SQL, tenant proof, or settings — those are trusted build/policy output.
+ *
+ * NOTE: distinct from the internal `CompiledQuery` in `../../types/base.ts`, which
+ * is the SQL-formatter fragment `{ query, parameters }`.
+ */
+export declare const COMPILED_QUERY_VERSION: 1;
+/** Closed operation set (RFC 0010 §Operations). The operation belongs to the compiled
+ * query, never to the request. */
+export type CompiledOperation = 'query' | 'command' | 'insert';
+/**
+ * A logical parameter type. The logical tag drives validation and the `{name:Type}`
+ * placeholder the adapter sends; `clickHouseType` is the concrete server type string
+ * (e.g. `UInt64`, `DateTime64(3, 'UTC')`, `Array(String)`).
+ */
+export interface CompiledParameterType {
+    /** RFC 0001 logical tag, or a scalar shorthand for native JSON scalars. */
+    readonly logical: TaggedValue['$hypequery']['type'] | 'boolean' | 'string' | 'float' | 'null';
+    /** Concrete ClickHouse server type used to build the native placeholder. */
+    readonly clickHouseType: string;
+}
+/**
+ * A named, typed parameter declaration carried beside the SQL text. A request supplies
+ * only values for declared names; it can neither add names nor change types.
+ */
+export interface CompiledParameterDeclaration {
+    readonly name: ProtocolIdentifier;
+    readonly type: CompiledParameterType;
+    /** Optional parameters may be absent from a request; required ones fail closed. */
+    readonly optional: boolean;
+}
+/** A supplied parameter value: an RFC 0001 tagged value or a native JSON scalar. */
+export type CompiledParameterValue = TaggedValue | string | number | boolean | null;
+/**
+ * The resolved `{name: value}` map the adapter binds to native server parameters.
+ * Every key is a declared parameter name; no value is ever rendered into SQL text.
+ */
+export type CompiledParameterBindings = Readonly<Record<string, CompiledParameterValue>>;
+/**
+ * Data sensitivity metadata. Marks whether the query touches tenant-scoped or otherwise
+ * sensitive data so diagnostics/redaction downstream can act without inspecting values.
+ */
+export interface CompiledSensitivity {
+    /** The compiled SQL already contains trusted tenant predicates (RFC 0010 §Operations). */
+    readonly tenantScoped: boolean;
+    /** Free-form trusted classification labels (e.g. 'pii'); never request-supplied. */
+    readonly labels: readonly string[];
+}
+/**
+ * Bounded settings the runtime applies per execution. These originate only from trusted
+ * components; a request can never set, override, or relax them. See `settings.ts` for the
+ * closed allow-list and ranges.
+ */
+export interface CompiledSettings {
+    /** Wall-clock ceiling for server-side execution, milliseconds. Always enforced. */
+    readonly maxExecutionMs?: number;
+    /** Maximum rows the result may contain. */
+    readonly maxResultRows?: number;
+    /** Maximum bytes the result may contain. */
+    readonly maxResultBytes?: number;
+}
+/** Effective deadline + cancellation inputs (RFC 0010 §Deadline and cancellation). */
+export interface CompiledDeadline {
+    /** Epoch-millis absolute deadline. Earlier of caller-supplied and policy-derived. */
+    readonly atEpochMs: number;
+    /** Which side set the effective deadline, for honest diagnostics. */
+    readonly source: 'caller' | 'policy';
+}
+/** Authoritative + optional correlation identifiers (RFC 0010 §Query identifier). */
+export interface CompiledIdentifiers {
+    /** Server-generated, unique per execution, unguessable, safe for logs/cache metadata. */
+    readonly queryId: string;
+    /** Caller-supplied, non-authoritative, ≤1024 UTF-8 bytes, no control chars; never
+     * influences routing, cache keys, or authorization. */
+    readonly correlationId?: string;
+}
+/**
+ * Redacted, non-executable debug form (RFC 0010 §Debug form). Shows SQL structure with
+ * placeholders and declared types; carries no values, tenant values, credentials, or
+ * settings beyond their names. `sql` here is deliberately not valid database SQL.
+ */
+export interface CompiledDebugForm {
+    readonly sql: string;
+    readonly parameters: readonly {
+        readonly name: string;
+        readonly type: string;
+        readonly optional: boolean;
+    }[];
+    readonly settings: readonly string[];
+}
+/**
+ * The compiled query: the only way a runtime asks a ClickHouse adapter to execute.
+ */
+export interface CompiledQueryV1 {
+    readonly version: typeof COMPILED_QUERY_VERSION;
+    readonly operation: CompiledOperation;
+    /** Trusted build/server output. Callers influence execution only via `bindings`. */
+    readonly sql: string;
+    readonly parameters: readonly CompiledParameterDeclaration[];
+    /** Resolved values for declared names, bound to native server parameters. */
+    readonly bindings: CompiledParameterBindings;
+    readonly settings: CompiledSettings;
+    readonly identifiers: CompiledIdentifiers;
+    readonly deadline?: CompiledDeadline;
+    readonly sensitivity: CompiledSensitivity;
+    readonly debug: CompiledDebugForm;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/compiled/types.d.ts.map

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

package/dist/core/compiled/types.js

@@ -0,0 +1,13 @@
+/**
+ * Execution-request contract from RFC 0010 (compiled query, error, cancellation),
+ * realized for the ClickHouse runtime.
+ *
+ * This is the versioned shape a runtime hands to an adapter. It sits *beside* the
+ * legacy positional path (`adapter.query(sql, params: unknown[])`, which renders
+ * values into SQL text via `substituteParameters`). Nothing here lets a request
+ * author SQL, tenant proof, or settings — those are trusted build/policy output.
+ *
+ * NOTE: distinct from the internal `CompiledQuery` in `../../types/base.ts`, which
+ * is the SQL-formatter fragment `{ query, parameters }`.
+ */
+export const COMPILED_QUERY_VERSION = 1;

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export type { SqlDialect } from './core/dialects/sql-dialect.js';
 export type { ClickHouseConfig, ClickHouseClientConfig, CreateQueryBuilderConfig, ExecuteOptions } from './core/query-builder.js';
 export { isClientConfig } from './core/query-builder.js';
 export { substituteParameters, escapeValue } from './core/utils.js';
+export * from './core/compiled/index.js';
 export type { CacheOptions, CacheConfig, CacheProvider, CacheEntry, CacheStatus } from './core/cache/types.js';
 export { CacheController } from './core/cache/controller.js';
 export { MemoryCacheProvider } from './core/cache/providers/memory-lru.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -9,6 +9,11 @@ export { isClientConfig } from './core/query-builder.js';
 // SQL rendering used by the built-in adapter; exported so third-party DatabaseAdapter
 // implementations (e.g. embedded engines) reproduce identical ?-param rendering.
 export { substituteParameters, escapeValue } from './core/utils.js';
+// CompiledQuery v1 (RFC 0010) — versioned execution-request contract with named typed
+// parameters, closed operations/settings, authoritative ids, deadlines, a redacted debug
+// form, and the public error envelope. Introduced beside the legacy ?-param path (CH-01);
+// the built-in adapter transport is wired in a later change.
+export * from './core/compiled/index.js';
 export { CacheController } from './core/cache/controller.js';
 export { MemoryCacheProvider } from './core/cache/providers/memory-lru.js';
 export { MemoryCacheProvider as MemoryLRUCacheProvider } from './core/cache/providers/memory-lru.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/clickhouse",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "ClickHouse typescript query builder",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -35,7 +35,8 @@
   ],
   "dependencies": {
     "@clickhouse/client": "^1.18.3",
-    "dotenv": "^16.0.0"
+    "dotenv": "^16.0.0",
+    "@hypequery/protocol": "0.9.0"
   },
   "peerDependencies": {
     "@clickhouse/client-web": "^0.2.0 || ^1.0.0",
@@ -61,7 +62,7 @@
     "typescript": "^5.7.3",
     "@vitest/coverage-v8": "^3.2.6",
     "vitest": "^3.2.6",
-    "@hypequery/datasets": "0.10.0"
+    "@hypequery/datasets": "0.13.0"
   },
   "ts-node": {
     "esm": true,