@zeyolabs/kit 0.0.0-stage → 2026.11.6

package/storage/clickhouse/dev.ts

@@ -0,0 +1,18 @@
+import type { ClickHouseSettings } from './schema';
+
+import { ClickHouseClientCore } from './client';
+
+export type ClickHouseDevClientConfig = {
+	keepAlive?: boolean;
+	password: string;
+	requestTimeoutMs?: number;
+	settings?: ClickHouseSettings;
+	url: string;
+	user: string;
+};
+
+export class ClickHouseDevClient extends ClickHouseClientCore {
+	constructor({ url, ...config }: ClickHouseDevClientConfig) {
+		super(url, undefined, config);
+	}
+}

package/storage/clickhouse/error.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+
+/**
+ * An `AggregateFunction()` column holds the aggregate function's own serialized state
+ * (function-specific binary blob with NO length prefix, https://clickhouse.com/docs/sql-reference/data-types/aggregatefunction) so there is no generic way to delimit or
+ * interpret it without reimplementing each function's deserializer (and trying would desync the rest
+ * of the block). Finalize it server-side instead with `finalizeAggregation(col)` or `<func>Merge(col)`
+ */
+export class AggregateFunctionNativeDecodingError extends Error {
+	constructor(type: string) {
+		super(
+			`Native decode: AggregateFunction state is opaque and not generically decodable (${type})`
+		);
+		this.name = 'AggregateFunctionNativeDecodingError';
+	}
+}
+
+/**
+ * A ClickHouse wire type with no Native decoder — either genuinely opaque/self-describing (`Dynamic`,
+ * `JSON`, `QBit`: variable per-row layouts we don't parse) or simply not implemented yet. To read such
+ * a column, project a decodable form in SQL (cast it, extract fields, or `toString()` it).
+ */
+export class UnsupportedClickHouseTypeError extends Error {
+	constructor(type: string) {
+		super(`Native decode: unsupported ClickHouse type ${type}`);
+		this.name = 'UnsupportedClickHouseTypeError';
+	}
+}
+
+/**
+ * ClickHouse `Interval*` columns aren't decodable here. An Interval is a duration whose meaning depends on
+ * its unit (Day/Second/…) and it carries no stable value mapping worth decoding — and CH won't return it
+ * from most reads anyway. Store the duration as a plain integer column instead (e.g. `UInt32` of days or
+ * `Int64` of seconds) and read that.
+ */
+export class IntervalColumnUnsupportedError extends Error {
+	constructor(type: string) {
+		super(
+			`Native decode: Interval columns are not supported (${type}) — store the duration as an integer column (e.g. UInt32 days / Int64 seconds) and read that instead`
+		);
+		this.name = 'IntervalColumnUnsupportedError';
+	}
+}
+
+/**
+ * A column's zod type can't be mapped to a ClickHouse wire type: it carries no `.meta({ ch })` and
+ * isn't a structurally-derivable shape. Fixes by case: a bare leaf needs `.meta({ ch: '<type>' })`;
+ * `z.intersection` should be one `z.object` (merge with `.extend()`); types with no column meaning
+ * (`z.function`, `z.promise`, a `.transform()` whose source carries no `ch`, …) can't be read.
+ */
+export class UndecodableColumnError extends Error {
+	constructor(field: z.core.$ZodType) {
+		const kind = field.constructor?.name ?? 'unknown zod type';
+		const hint =
+			field instanceof z.ZodIntersection
+				? ' — merge the schemas into one z.object with .extend()'
+				: " — tag it with .meta({ ch: '<ClickHouse type>' })";
+		super(`Native decode: cannot derive a ClickHouse type from ${kind}${hint}`);
+		this.name = 'UndecodableColumnError';
+	}
+}

package/storage/clickhouse/index.ts

@@ -0,0 +1,4 @@
+export * from './client';
+export * from './config';
+export * from './retry';
+export * from './schema';

package/storage/clickhouse/native-decoder.ts

@@ -0,0 +1,192 @@
+import {
+	Cursor,
+	readString,
+	readUInt8,
+	readUInt16,
+	readUInt32,
+	readUInt64,
+	readUVarint,
+} from '@clickhouse/rowbinary';
+
+import type { ClickHouseColumn, ColumnNode, DecodedColumn, NodeKind } from './schema';
+
+/** Decode each Native block against the precompiled columns. Binding is POSITIONAL — the SELECT must
+ *  project columns in schema field order — guarded by a name + CH-type assert per column (a mismatch
+ *  throws loudly rather than mis-binding). Rows are NOT validated: the client trusts CH and the decode
+ *  tree already carries the only boundary transform (DateTime/DateTime64 → ZonedDateTime, in the leaf). */
+export function decodeNativeBuffer(
+	buf: Buffer,
+	columns: ClickHouseColumn[]
+): Record<string, unknown>[] {
+	const nCols = columns.length;
+	const cursor = new Cursor(buf);
+	const rows: Record<string, unknown>[] = [];
+	while (cursor.pos < buf.length) {
+		const blockCols = readUVarint(cursor);
+		const nRows = readUVarint(cursor);
+		if (blockCols !== nCols)
+			throw new Error(`Native decode: schema has ${nCols} columns, block has ${blockCols}`);
+		const colArrays = new Array<DecodedColumn>(nCols);
+		// CH is a columnar DBMS, data is stored per-column, NOT per-row
+		for (let colIndex = 0; colIndex < nCols; colIndex++) {
+			const name = readString(cursor);
+			const chType = readString(cursor);
+			const col = columns[colIndex];
+			if (name !== col.name)
+				throw new Error(
+					`Native decode: column ${colIndex} is '${name}', schema expects '${col.name}'`
+				);
+			if (chType !== col.type)
+				throw new Error(`Native decode: column ${name} wire type ${chType} ≠ schema ${col.type}`);
+			colArrays[colIndex] = decodeColumn(cursor, col.decodeTree, nRows);
+		}
+		for (let rowIndex = 0; rowIndex < nRows; rowIndex++) {
+			const row: Record<string, unknown> = {};
+			for (let colIndex = 0; colIndex < nCols; colIndex++)
+				row[columns[colIndex].name] = colArrays[colIndex][rowIndex];
+			rows.push(row);
+		}
+	}
+	return rows;
+}
+
+/** Walk a decode tree, decoding `n` column values; each kind's Native framing lives in its decoder. */
+function decodeColumn(cursor: Cursor, tree: ColumnNode, n: number): DecodedColumn {
+	switch (tree.kind) {
+		case 'scalar':
+			return decodeScalar(cursor, tree, n);
+		case 'nullable':
+			return decodeNullable(cursor, tree, n);
+		case 'array':
+			return decodeArray(cursor, tree, n);
+		case 'lowCardinality':
+			return decodeLowCardinality(cursor, tree);
+		case 'map':
+			return decodeMap(cursor, tree, n);
+		case 'tuple':
+			return decodeTuple(cursor, tree, n);
+		case 'variant':
+			return decodeVariant(cursor, tree, n);
+	}
+}
+
+function decodeScalar(cursor: Cursor, node: NodeKind<'scalar'>, n: number): DecodedColumn {
+	const out = new Array<unknown>(n);
+	for (let rowIndex = 0; rowIndex < n; rowIndex++) out[rowIndex] = node.read(cursor);
+	return out;
+}
+
+/** Full null map (one byte per row), then all inner values. */
+function decodeNullable(cursor: Cursor, node: NodeKind<'nullable'>, n: number): DecodedColumn {
+	const mask = new Uint8Array(n);
+	for (let rowIndex = 0; rowIndex < n; rowIndex++) mask[rowIndex] = readUInt8(cursor);
+	const values = decodeColumn(cursor, node.inner, n);
+	for (let rowIndex = 0; rowIndex < n; rowIndex++) if (mask[rowIndex]) values[rowIndex] = null;
+	return values;
+}
+
+/** Cumulative u64 offsets, then the flattened elements sliced per row. */
+function decodeArray(cursor: Cursor, node: NodeKind<'array'>, n: number): DecodedColumn {
+	const offsets = new Array<number>(n);
+	for (let rowIndex = 0; rowIndex < n; rowIndex++) offsets[rowIndex] = Number(readUInt64(cursor));
+	const elems = decodeColumn(cursor, node.inner, n > 0 ? offsets[n - 1] : 0);
+	const out = new Array<unknown>(n);
+	let start = 0;
+	for (let rowIndex = 0; rowIndex < n; rowIndex++) {
+		const slice = elems.slice(start, offsets[rowIndex]);
+		out[rowIndex] = node.asSet ? new Set(slice) : slice; // z.set → JS Set (dedups, drops order)
+		start = offsets[rowIndex];
+	}
+	return out;
+}
+
+/** u64 version, u64 index-flags (low byte = index width), u64 dict size, the dict, u64 row count,
+ *  then one dict index per row. For Nullable inner, index 0 means NULL. */
+function decodeLowCardinality(cursor: Cursor, node: NodeKind<'lowCardinality'>): DecodedColumn {
+	readUInt64(cursor); // serialization version (SharedDictionariesWithAdditionalKeys = 1)
+	const indexWidth = Number(readUInt64(cursor)) & 0xff;
+	const dict = decodeColumn(cursor, node.inner, Number(readUInt64(cursor)));
+	const rows = Number(readUInt64(cursor));
+	const narrowReader = [readUInt8, readUInt16, readUInt32][indexWidth]; // undefined ⇒ 8-byte index
+	const out = new Array<unknown>(rows);
+	for (let rowIndex = 0; rowIndex < rows; rowIndex++) {
+		const dictIndex = narrowReader ? narrowReader(cursor) : Number(readUInt64(cursor));
+		out[rowIndex] = node.nullable && dictIndex === 0 ? null : dict[dictIndex];
+	}
+	return out;
+}
+
+/** Cumulative u64 offsets, then the flat keys column, then the flat values column. */
+function decodeMap(cursor: Cursor, node: NodeKind<'map'>, n: number): DecodedColumn {
+	const offsets = new Array<number>(n);
+	for (let rowIndex = 0; rowIndex < n; rowIndex++) offsets[rowIndex] = Number(readUInt64(cursor));
+	const total = n > 0 ? offsets[n - 1] : 0;
+	const keys = decodeColumn(cursor, node.key, total);
+	const vals = decodeColumn(cursor, node.value, total);
+	const out = new Array<unknown>(n);
+	let start = 0;
+	for (let rowIndex = 0; rowIndex < n; rowIndex++) {
+		if (node.asMap) {
+			// z.map → JS Map, preserving typed keys (a number key stays a number, unlike object keys).
+			const map = new Map<unknown, unknown>();
+			for (let entryIndex = start; entryIndex < offsets[rowIndex]; entryIndex++)
+				map.set(keys[entryIndex], vals[entryIndex]);
+			out[rowIndex] = map;
+		} else {
+			const obj: Record<string, unknown> = {};
+			for (let entryIndex = start; entryIndex < offsets[rowIndex]; entryIndex++)
+				obj[String(keys[entryIndex])] = vals[entryIndex];
+			out[rowIndex] = obj;
+		}
+		start = offsets[rowIndex];
+	}
+	return out;
+}
+
+/** Each element is a full column of n values, laid out one after another. */
+function decodeTuple(cursor: Cursor, node: NodeKind<'tuple'>, n: number): DecodedColumn {
+	const cols = node.fields.map((field) => decodeColumn(cursor, field.node, n));
+	const out = new Array<unknown>(n);
+	for (let rowIndex = 0; rowIndex < n; rowIndex++) {
+		if (node.named) {
+			const obj: Record<string, unknown> = {};
+			for (let fieldIndex = 0; fieldIndex < node.fields.length; fieldIndex++)
+				obj[node.fields[fieldIndex].name as string] = cols[fieldIndex][rowIndex];
+			out[rowIndex] = obj;
+		} else {
+			out[rowIndex] = cols.map((fieldValues) => fieldValues[rowIndex]);
+		}
+	}
+	return out;
+}
+
+/** u64 discriminator mode (0 = basic), one discriminator byte per row (variant index, or 255 = NULL),
+ *  then each variant's values compacted in type order. */
+function decodeVariant(cursor: Cursor, node: NodeKind<'variant'>, n: number): DecodedColumn {
+	const mode = readUInt64(cursor);
+	if (mode !== 0n) throw new Error(`Native decode: Variant compact mode (${mode}) not supported`);
+	const discriminators = new Uint8Array(n);
+	for (let rowIndex = 0; rowIndex < n; rowIndex++) discriminators[rowIndex] = readUInt8(cursor);
+	const counts = new Array<number>(node.variants.length).fill(0);
+	for (let rowIndex = 0; rowIndex < n; rowIndex++) {
+		const disc = discriminators[rowIndex];
+		if (disc === 255) continue;
+		// Guard an out-of-range discriminator with a clear error — otherwise `counts[disc]` is undefined,
+		// increments to NaN, and later crashes cryptically on `cols[disc]` in the assembly loop.
+		if (disc >= node.variants.length)
+			throw new Error(
+				`Native decode: Variant discriminator ${disc} out of range (0..${node.variants.length - 1})`
+			);
+		counts[disc]++;
+	}
+	const cols = node.variants.map((variantNode, variantIndex) =>
+		decodeColumn(cursor, variantNode, counts[variantIndex])
+	);
+	const positions = new Array<number>(node.variants.length).fill(0);
+	const out = new Array<unknown>(n);
+	for (let rowIndex = 0; rowIndex < n; rowIndex++) {
+		const discriminator = discriminators[rowIndex];
+		out[rowIndex] = discriminator === 255 ? null : cols[discriminator][positions[discriminator]++];
+	}
+	return out;
+}

package/storage/clickhouse/readers.ts

@@ -0,0 +1,167 @@
+import {
+	formatDecimal,
+	formatIPv4,
+	formatIPv6,
+	formatUUID,
+	readBFloat16,
+	readBool,
+	readDecimal32,
+	readDecimal64,
+	readDecimal128,
+	readDecimal256,
+	readEnum8,
+	readEnum16,
+	type Reader,
+	readFixedString,
+	readFloat32,
+	readFloat64,
+	readInt8,
+	readInt16,
+	readInt32,
+	readInt64,
+	readInt128,
+	readInt256,
+	readIPv4,
+	readIPv6,
+	readNothing,
+	readString,
+	readTime,
+	readTime64,
+	readUInt8,
+	readUInt16,
+	readUInt32,
+	readUInt64,
+	readUInt128,
+	readUInt256,
+	readUUID,
+} from '@clickhouse/rowbinary';
+
+import { IntervalColumnUnsupportedError, UnsupportedClickHouseTypeError } from './error';
+
+// The single source of truth for CH scalar type → @clickhouse/rowbinary leaf reader. Two callers:
+// the CH primitives in ./schema seed their `.meta({ read })` from it (so the compile path reads the
+// reader off the leaf, not a switch), and the compiler's string parser resolves raw-`ch`-string
+// escapes (geo leaves, Variant/Nested fields, LowCardinality inner) through it.
+
+/** Resolve a scalar CH type to its @clickhouse/rowbinary leaf reader. */
+export function scalarReader(type: string): Reader<unknown> {
+	/** Pick the right fixed-width Decimal reader for `Decimal(P,S)` / `Decimal32..256(S)`. */
+	function decimalReader(t: string) {
+		const m = t.match(/^Decimal(32|64|128|256)?\((\d+)(?:,\s*(\d+))?\)$/);
+		if (!m) throw new Error(`Native decode: cannot parse ${t}`);
+		if (m[1]) {
+			const scale = Number(m[2]);
+			if (m[1] === '32') return readDecimal32(scale);
+			if (m[1] === '64') return readDecimal64(scale);
+			if (m[1] === '128') return readDecimal128(scale);
+			return readDecimal256(scale);
+		}
+		const precision = Number(m[2]);
+		const scale = Number(m[3]);
+		if (precision <= 9) return readDecimal32(scale);
+		if (precision <= 18) return readDecimal64(scale);
+		if (precision <= 38) return readDecimal128(scale);
+		return readDecimal256(scale);
+	}
+	/** Map an `Enum8/16('name' = n, ...)` type string to value → name. */
+	function parseEnum(t: string): Map<number, string> {
+		const names = new Map<number, string>();
+		const re = /'((?:[^'\\]|\\.)*)'\s*=\s*(-?\d+)/g;
+		let m: null | RegExpExecArray;
+		while ((m = re.exec(t)) !== null) names.set(Number(m[2]), m[1]);
+		return names;
+	}
+	switch (type) {
+		case 'String':
+			return readString;
+		case 'UInt8':
+			return readUInt8;
+		case 'UInt16':
+			return readUInt16;
+		case 'UInt32':
+			return readUInt32;
+		case 'UInt64':
+			return readUInt64;
+		case 'UInt128':
+			return readUInt128;
+		case 'UInt256':
+			return readUInt256;
+		case 'Int8':
+			return readInt8;
+		case 'Int16':
+			return readInt16;
+		case 'Int32':
+			return readInt32;
+		case 'Int64':
+			return readInt64;
+		case 'Int128':
+			return readInt128;
+		case 'Int256':
+			return readInt256;
+		case 'Float32':
+			return readFloat32;
+		case 'Float64':
+			return readFloat64;
+		case 'Bool':
+		case 'Boolean':
+			return readBool;
+		case 'Date':
+			return (s) => new Date(readUInt16(s) * 86_400_000).toISOString().slice(0, 10);
+		case 'Date32':
+			return (s) => new Date(readInt32(s) * 86_400_000).toISOString().slice(0, 10);
+		case 'UUID':
+			return (s) => formatUUID(readUUID(s));
+		case 'IPv4':
+			return (s) => formatIPv4(readIPv4(s));
+		case 'IPv6':
+			return (s) => formatIPv6(readIPv6(s));
+		case 'Time':
+			return readTime; // Int32 seconds-of-day
+		case 'BFloat16':
+			return readBFloat16;
+		case 'Nothing':
+			return readNothing; // only reachable via a malformed empty Array(Nothing)/Nullable(Nothing)
+	}
+	if (type.startsWith('FixedString(')) {
+		return readFixedString(Number(type.slice('FixedString('.length, -1)));
+	}
+	if (type.startsWith('Time64')) {
+		const p = Number(type.slice('Time64('.length).split(/[,)]/)[0]);
+		const reader = readTime64(p);
+		const div = 10 ** p;
+		return (s) => Number(reader(s)[0]) / div; // fractional seconds-of-day
+	}
+	if (type.startsWith('Interval')) throw new IntervalColumnUnsupportedError(type);
+	// Binary formats ignore date_time_output_format — DateTime is always the raw epoch integer on the
+	// wire. Return epoch seconds (Date as 'YYYY-MM-DD'), matching the JSONEachRow path so the row-map
+	// conversion to ZonedDateTime/CalendarDate is identical across both formats.
+	if (type.startsWith('DateTime64')) {
+		// Ticks (Int64) at scale p. Split seconds/fraction via bigint so a ns value (>2^53) doesn't
+		// lose precision through Number() before the divide. Yields fractional epoch seconds.
+		const div = 10n ** BigInt(Number(type.slice('DateTime64('.length).split(/[,)]/)[0]));
+		return (s) => {
+			const ticks = readInt64(s);
+			return Number(ticks / div) + Number(ticks % div) / Number(div);
+		};
+	}
+	if (type.startsWith('DateTime')) return readUInt32; // epoch seconds
+	if (type.startsWith('Enum8(')) {
+		const names = parseEnum(type);
+		return (s) => {
+			const v = readEnum8(s);
+			return names.get(v) ?? v;
+		};
+	}
+	if (type.startsWith('Enum16(')) {
+		const names = parseEnum(type);
+		return (s) => {
+			const v = readEnum16(s);
+			return names.get(v) ?? v;
+		};
+	}
+	if (type.startsWith('Decimal')) {
+		const reader = decimalReader(type);
+		return (s) => formatDecimal(reader(s));
+	}
+	throw new UnsupportedClickHouseTypeError(type);
+}

package/storage/clickhouse/retry.ts

@@ -0,0 +1,30 @@
+import { ClickHouseError } from '@clickhouse/client-web';
+
+/** A `ClickHouseError` is a deterministic server rejection (bad SQL, memory limit, unknown table) — not
+ *  worth retrying. Anything else is a transient transport blip, retryable for an idempotent read. Our own
+ *  deadline is caught via `signal.aborted` in `withTransportRetry`, never by matching `err.name`. */
+export function isRetryableTransportError(err: unknown): boolean {
+	return !(err instanceof ClickHouseError);
+}
+
+/** Retry an idempotent CH transport call over a transient connection drop — exp backoff + jitter. Owns a
+ *  per-attempt deadline (`AbortSignal.timeout`) and passes it to `run`, which MUST forward it to the CH
+ *  call's `abort_signal`. A fired deadline is detected via `signal.aborted`, so our own timeout stops the
+ *  loop while a fast transport failure is still retried. */
+export async function withTransportRetry<T>(
+	run: (signal: AbortSignal) => Promise<T>,
+	{ attempts = 3, timeoutMs = 60_000 }: { attempts?: number; timeoutMs?: number } = {}
+): Promise<T> {
+	for (let i = 0; ; i++) {
+		const signal = AbortSignal.timeout(timeoutMs);
+		try {
+			return await run(signal);
+		} catch (err) {
+			// Our own deadline elapsed → stop; retrying would only stack latency past the ceiling.
+			if (signal.aborted) throw err;
+			if (i >= attempts - 1 || !isRetryableTransportError(err)) throw err;
+			const backoff = 2 ** i * 50 + Math.random() * 50; // 50ms/100ms + jitter
+			await new Promise((resolve) => setTimeout(resolve, backoff));
+		}
+	}
+}

package/storage/clickhouse/schema.ts

@@ -0,0 +1,163 @@
+import type { Reader } from '@clickhouse/rowbinary';
+
+import { ZonedDateTime } from '@internationalized/date';
+import { z } from 'zod';
+
+import { Datetime } from '../../utils/datetime';
+import { chWireType } from './compiler';
+import { scalarReader } from './readers';
+
+/** Per-query ClickHouse settings, passed straight through to the server (e.g. `max_block_size`). */
+export type ClickHouseSettings = Record<string, boolean | number | string | undefined>;
+
+/**
+ * A compiled decode tree for one column: the CH type parsed once into a tree the decoder walks.
+ * `decodeColumn` recurses over this (cheap, tagged dispatch) instead of re-parsing the type string.
+ */
+export type ColumnNode =
+	| { asMap?: boolean; key: ColumnNode; kind: 'map'; value: ColumnNode }
+	| { asSet?: boolean; inner: ColumnNode; kind: 'array' }
+	| { fields: { name?: string; node: ColumnNode }[]; kind: 'tuple'; named: boolean }
+	| { inner: ColumnNode; kind: 'lowCardinality'; nullable: boolean }
+	| { inner: ColumnNode; kind: 'nullable' }
+	| { kind: 'scalar'; read: Reader<unknown> }
+	| { kind: 'variant'; variants: ColumnNode[] };
+
+/** The ColumnNode variant for a given kind — used to type each decoder's `node`. */
+export type NodeKind<K extends ColumnNode['kind']> = Extract<ColumnNode, { kind: K }>;
+
+/** A compiled column: its name, its CH wire type (the drift-guard key), and its decode tree. */
+export type ClickHouseColumn = { decodeTree: ColumnNode; name: string; type: string };
+
+export type DecodedColumn = unknown[];
+
+/**
+ * Read-time engine semantics — how the builder collapses each engine to return final rows. `sortKey` /
+ * `version` / `measures` are column names (any CH expression is allowed — they're spliced into the SQL).
+ *
+ * For the merge engines, a read ALWAYS returns the collapsed state (latest-per-key / summed). For
+ * Replacing/Summing, `final` picks the METHOD and is a correctness lever, so it's REQUIRED:
+ *   • `final: true`  → `FINAL` — collapses THEN filters (correct when you filter on MUTABLE columns).
+ *   • `final: false` → cheaper `LIMIT 1 BY` / `sum()+GROUP BY` — filters THEN collapses (only safe for
+ *     filters on the sortKey / immutable columns; a mutable filter can keep a stale-but-matching version).
+ * Collapsing/VersionedCollapsing read via the universal `FINAL` (their value columns are real, so FINAL is
+ * the correct read). `AggregatingMergeTree` is intentionally absent — its per-column combinator collapse
+ * lives in the ORM (see the ch-aggregating-mergetree-debt memory), not this flat client.
+ */
+export type TableEngine =
+	| { final: boolean; kind: 'ReplacingMergeTree'; sortKey: string[]; version?: string }
+	| { final: boolean; kind: 'SummingMergeTree'; measures: string[]; sortKey: string[] }
+	| { kind: 'CollapsingMergeTree' }
+	| { kind: 'MergeTree' }
+	| { kind: 'Plain' }
+	// Straight-read engines (no merge collapse): Log/TinyLog/StripeLog/Memory/Buffer/Null/Join/View/
+	// MaterializedView/Distributed/Merge/File/URL/…
+	| { kind: 'VersionedCollapsingMergeTree' };
+
+// The `ClickHouseTable` runtime object lives in ./client (a class that owns its compiled-query cache and
+// builds engine-correct SQL); the engine descriptor it consumes — `TableEngine` above — stays here with
+// the rest of the wire-type vocabulary.
+
+// ── CH-typed zod primitives (the `CH` factory) ─────────────────────────────────────────────────────
+// One namespace of reusable validators, each tagged with its leaf CH wire type via .meta({ ch }) and
+// — for scalars — its @clickhouse/rowbinary leaf reader via .meta({ read }), so the decoder reads the
+// reader straight off the leaf instead of re-deriving it from a type-string switch. Wrappers compose
+// structurally: z.array(CH.UInt32) → Array(UInt32), CH.String.nullable() → Nullable(String), because
+// compileColumn derives Array/Nullable/Tuple/Map from the zod structure. Types invisible in zod
+// (LowCardinality, geo, and the Enum/Decimal/DateTime params) carry an explicit ch string; the
+// non-scalar ones (LowCardinality, geo) omit `read` and are compiled via the string path.
+
+// Builds a scalar CH primitive: a base zod type tagged with its ch wire type + leaf reader.
+// Named `scalar` (not `leaf`/`node`) — `node` collides with the decode tree's ColumnNode.
+const scalar = <T extends z.ZodType>(base: T, ch: string) =>
+	base.meta({ ch, read: scalarReader(ch) });
+
+const enumType = (bits: 8 | 16, members: Record<string, number>) =>
+	`Enum${bits}(${Object.entries(members)
+		.map(([k, v]) => `'${k}' = ${v}`)
+		.join(', ')})`;
+
+export const CH = {
+	BFloat16: scalar(z.number(), 'BFloat16'),
+	Bool: scalar(z.boolean(), 'Bool'),
+	Date: scalar(z.string(), 'Date'),
+	Date32: scalar(z.string(), 'Date32'),
+	DateTime: scalar(z.number(), 'DateTime'),
+	// DateTime64 epoch ↔ ZonedDateTime — the domain always stores instants, so DateTime64 IS zoned (like
+	// `ZonedDateTime` for plain DateTime). Reads decode fractional epoch seconds → ZonedDateTime (sub-second
+	// kept); the ch + read live on the codec's INPUT scalar (compileColumn unwraps the codec to it).
+	DateTime64: (precision: number, tz?: string) =>
+		z.codec(
+			scalar(z.number(), tz ? `DateTime64(${precision}, '${tz}')` : `DateTime64(${precision})`),
+			z.instanceof(ZonedDateTime),
+			{
+				decode: (epoch) => Datetime.zonedFromUnixSeconds(epoch),
+				encode: (zdt) => Datetime.toUnixSeconds(zdt),
+			}
+		),
+	Decimal: (precision: number, scale: number) =>
+		scalar(z.string(), `Decimal(${precision}, ${scale})`),
+	Enum: (bits: 8 | 16, members: Record<string, number>) =>
+		scalar(z.enum(Object.keys(members) as [string, ...string[]]), enumType(bits, members)),
+	// Parameterized scalar constructors.
+	FixedString: (n: number) => scalar(z.string(), `FixedString(${n})`),
+	Float32: scalar(z.number(), 'Float32'),
+	Float64: scalar(z.number(), 'Float64'),
+	Int128: scalar(z.bigint(), 'Int128'),
+	Int16: scalar(z.number(), 'Int16'),
+	Int256: scalar(z.bigint(), 'Int256'),
+	Int32: scalar(z.number(), 'Int32'),
+	Int64: scalar(z.bigint(), 'Int64'),
+	Int8: scalar(z.number(), 'Int8'),
+	IPv4: scalar(z.string(), 'IPv4'),
+	IPv6: scalar(z.string(), 'IPv6'),
+	LineString: z.array(z.tuple([z.number(), z.number()])).meta({ ch: 'LineString' }),
+	LowCardNullableString: z.string().nullable().meta({ ch: 'LowCardinality(Nullable(String))' }),
+	// Non-scalar wrappers carry a raw ch string and no `read` — compiled via the string path.
+	LowCardString: z.string().meta({ ch: 'LowCardinality(String)' }),
+	MultiLineString: z
+		.array(z.array(z.tuple([z.number(), z.number()])))
+		.meta({ ch: 'MultiLineString' }),
+	MultiPolygon: z
+		.array(z.array(z.array(z.tuple([z.number(), z.number()]))))
+		.meta({ ch: 'MultiPolygon' }),
+	// Nested(name Type, …) — decodes as `Array(Tuple(named …))`, i.e. an array of row-objects. The
+	// `z.array(z.object(shape))` validates; the `Nested(…)` ch string drives the decode.
+	Nested: <T extends z.ZodRawShape>(shape: T) =>
+		z.array(z.object(shape)).meta({
+			ch: `Nested(${Object.entries(shape)
+				.map(([name, t]) => `${name} ${chWireType(t)}`)
+				.join(', ')})`,
+		}),
+	// Geo types report their own wire name (Point/Ring/…), not the underlying Tuple/Array. A Point is a
+	// (Float64, Float64) tuple; each further geo type nests one Array deeper (LineString/Ring share a shape,
+	// as do Polygon/MultiLineString — see the decoder's geo cases).
+	Point: z.tuple([z.number(), z.number()]).meta({ ch: 'Point' }),
+	Polygon: z.array(z.array(z.tuple([z.number(), z.number()]))).meta({ ch: 'Polygon' }),
+	Ring: z.array(z.tuple([z.number(), z.number()])).meta({ ch: 'Ring' }),
+	String: scalar(z.string(), 'String'),
+	Time: scalar(z.number(), 'Time'),
+	Time64: (precision: number) => scalar(z.number(), `Time64(${precision})`),
+	UInt128: scalar(z.bigint(), 'UInt128'),
+	UInt16: scalar(z.number(), 'UInt16'),
+	UInt256: scalar(z.bigint(), 'UInt256'),
+	UInt32: scalar(z.number(), 'UInt32'),
+	UInt64: scalar(z.bigint(), 'UInt64'),
+	UInt8: scalar(z.number(), 'UInt8'),
+	UUID: scalar(z.string(), 'UUID'),
+	// Variant(T1, T2, …) — a column holding one of several types OR NULL (a Variant is implicitly nullable in CH:
+	// a row can be "none of the types"), so the validation union includes `z.null()`. The `Variant(…)` ch string
+	// (built from each inner's full wire type — inners may themselves be wrapped) drives the decode via the string
+	// path (no single leaf reader).
+	Variant: <T extends [z.ZodType, z.ZodType, ...z.ZodType[]]>(...inners: T) =>
+		z.union([...inners, z.null()]).meta({
+			ch: `Variant(${inners.map((i) => chWireType(i)).join(', ')})`,
+		}),
+	// DateTime epoch ↔ domain instant, a BIDIRECTIONAL codec: `.parse` (read) decodes epoch → ZonedDateTime;
+	// `z.encode` (insert) encodes ZonedDateTime → epoch. The ch + read live on the codec's INPUT (the
+	// `scalar` DateTime) — `compileColumn` unwraps the codec to its input to drive the wire decode of epoch.
+	ZonedDateTime: z.codec(scalar(z.number(), 'DateTime'), z.instanceof(ZonedDateTime), {
+		decode: (epoch) => Datetime.zonedFromUnixSeconds(epoch),
+		encode: (zdt) => Datetime.toUnixSeconds(zdt),
+	}),
+} as const;