@wavehouse/chtypes 0.1.0

package/dist/errors.js

@@ -0,0 +1,228 @@
+/**
+ * The error model, which is three outcomes that must never be conflated
+ * (spec/c-abi.md §Error model):
+ *
+ *   - ClickHouse rejects        -> a real ClickHouse error code
+ *   - this build refuses        -> CODE_UNSUPPORTED (-2), never a ClickHouse code
+ *   - ClickHouse accepts but the value cannot be read back -> code 691, and it
+ *     is an ACCEPTED insert, surfaced through the row outcome rather than here.
+ *
+ * Mapping `unsupported` onto a rejection manufactures an over-reject the product
+ * never made; mapping it onto an acceptance manufactures an over-accept, which
+ * is the cardinal sin. So it gets its own sentinel on the wire and, since
+ * 2026-08-26, its own ERROR CLASS here — `UnsupportedError`, a peer of
+ * `SchemaError` rather than a subclass, so that a `catch` which handles only
+ * `SchemaError` cannot silently swallow a decline as a rejection.
+ */
+/** "This build refuses to answer." Never a real ClickHouse error code. */
+export const CODE_UNSUPPORTED = -2;
+/**
+ * The chs_* ABI revision this binding was written against — `CHS_ABI_REVISION`
+ * in `include/chtypes.h`.
+ *
+ * This package dlopens artifacts rather than compiling against the header, so
+ * this is a hand-kept mirror and MUST be bumped in the same cycle the header
+ * is. A `Registry` refuses an artifact reporting a different nonzero revision;
+ * 0 means the artifact predates the probe, which is ignorance rather than
+ * incompatibility (spec/artifact.md §Loading).
+ *
+ * Revision 3 (2026-08-31): `chs_rows` gained `export_format` / `doc_flags` /
+ * `out_bytes`, and the `chs_filter_compile` / `chs_filter_free` /
+ * `chs_filter_rows` trio joined the surface.
+ *
+ * Revision 4 (2026-08-31, the filter phase-2 cycle): `chs_filter_compile`
+ * gained `params_json` (`{name:Type}` query parameters), and the block twin
+ * joined — `chs_block_parse` / `chs_block_free` / `chs_filter_eval`. This
+ * binding therefore speaks 4 and refuses revision-3 artifacts — calling the
+ * 5-argument `chs_filter_compile` through the 4-argument revision-3 artifact
+ * is undefined behaviour, which is exactly what the gate exists to prevent.
+ */
+export const ABI_REVISION = 4;
+/** Base class for everything this package throws. */
+export class ChtypesError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/** A registry could not be loaded, or a version could not be resolved. */
+export class RegistryError extends ChtypesError {
+}
+/**
+ * A REFUSAL: ClickHouse itself refused a type, a column list, an engine or a
+ * TTL.
+ *
+ * `code` is ALWAYS a real ClickHouse error code. "This build declines to
+ * answer" is a DIFFERENT CLASS — `UnsupportedError` — never this one carrying
+ * a sentinel, so no `SchemaError` ever holds `CODE_UNSUPPORTED`
+ * (spec/bindings.md rule 12).
+ */
+export class SchemaError extends ChtypesError {
+    code;
+    detail;
+    column;
+    constructor(code, detail, column) {
+        super(column
+            ? `chtypes: column ${JSON.stringify(column)}: [${code}] ${detail}`
+            : `chtypes: [${code}] ${detail}`);
+        this.code = code;
+        this.detail = detail;
+        this.column = column;
+    }
+}
+/**
+ * A DECLINE: "a real server might well have accepted this; I will not guess."
+ * Never ClickHouse rejecting anything, so it carries no `code` property at all
+ * — there is no code to carry.
+ *
+ * It is a PEER of `SchemaError`, deliberately NOT a subclass and deliberately
+ * NOT matched by `err instanceof SchemaError`. A decline that still satisfied
+ * "is a SchemaError" would be the sentinel problem wearing a class hierarchy:
+ * every `catch` that forgot the predicate would keep silently turning declines
+ * into rejections, which is a manufactured over-reject — data loss the product
+ * never made, budgeted at zero. As a peer, forgetting throws on past the
+ * handler, which is loud.
+ *
+ * ```ts
+ * try {
+ *   schema.setEngine(engine, orderBy);
+ * } catch (err) {
+ *   // validate cautiously; do NOT blame the tenant
+ *   if (err instanceof UnsupportedError) return degradeToCarefulPath(err);
+ *   // ClickHouse refused: err.code is its own code
+ *   if (err instanceof SchemaError) return rejectWith(err.code, err.detail);
+ *   throw err;
+ * }
+ * ```
+ *
+ * The MESSAGE still renders the ABI's `CODE_UNSUPPORTED` sentinel in the shape
+ * `SchemaError` renders its code. The sentinel is not a property of this class
+ * — it is the wire value the C ABI returned — but the rendering is frozen: the
+ * conformance driver puts this exact string on the protocol wire as an
+ * `unsupported` scope, and Python's `UnsupportedError` already spells it this
+ * way. Changing the text would move rig records without changing a verdict.
+ */
+export class UnsupportedError extends ChtypesError {
+    detail;
+    column;
+    constructor(detail, column) {
+        super(column
+            ? `chtypes: column ${JSON.stringify(column)}: [${CODE_UNSUPPORTED}] ${detail}`
+            : `chtypes: [${CODE_UNSUPPORTED}] ${detail}`);
+        this.detail = detail;
+        this.column = column;
+    }
+}
+/**
+ * The ONE place an ABI error code becomes an error object, so the
+ * refusal/decline split cannot be decided differently in two files.
+ *
+ * The SIGN decides (spec/bindings.md rule 12, spec/c-abi.md §Error model): a
+ * positive code is the server's own refusal and rides through verbatim; any
+ * negative code is this library declining (`-2` "I will not guess", `-1` a
+ * guarded exception, and a binding's own missing-symbol sentinel) and becomes
+ * an `UnsupportedError`. Keying on the sign rather than on `=== CODE_UNSUPPORTED`
+ * means a negative sentinel a later era adds can never become "a SchemaError
+ * with a negative code", which the class's own contract forbids.
+ *
+ * Internal: not re-exported from the package index.
+ */
+export function schemaErrorFor(code, detail, column) {
+    return code < 0 ? new UnsupportedError(detail, column) : new SchemaError(code, detail, column);
+}
+/** The command this SDK's §7 message tells a user to run. */
+export const FETCH_COMMAND = 'npx @wavehouse/chtypes fetch';
+/**
+ * The §7 message, verbatim apart from the bracketed parts:
+ *
+ *     chtypes: no artifact for ClickHouse <line> (<os>-<arch>). Looked in: <dir1>, <dir2>, ….
+ *     Install it:  npx @wavehouse/chtypes fetch <line>
+ *     or set CHTYPES_AUTOFETCH=1 to fetch on first use.
+ */
+export function artifactMissingMessage(line, platform, lookedIn) {
+    return (`chtypes: no artifact for ClickHouse ${line} (${platform}). Looked in: ${lookedIn.join(', ')}.\n` +
+        `Install it:  ${FETCH_COMMAND} ${line}\n` +
+        'or set CHTYPES_AUTOFETCH=1 to fetch on first use.');
+}
+/**
+ * The one identifiable error for a missing artifact (docs/fetch.md §7):
+ * a `Registry` was asked for a line that no directory on its search path
+ * holds. `code` is `'CHTYPES_ARTIFACT_MISSING'`; the message is the
+ * contract's, and names every directory that was looked in and the command
+ * that installs the line.
+ *
+ * A subclass of `RegistryError`, so a `catch` written against `for()`'s
+ * documented error keeps working; the `code` is what a caller matches on.
+ */
+export class ArtifactMissingError extends RegistryError {
+    code = 'CHTYPES_ARTIFACT_MISSING';
+    /** The minor line that was asked for, e.g. `25.8`. */
+    line;
+    /** The platform key the registry serves, e.g. `darwin-arm64`. */
+    platform;
+    /** Every directory of the search path, in order. */
+    lookedIn;
+    constructor(line, platform, lookedIn) {
+        super(artifactMissingMessage(line, platform, lookedIn));
+        this.line = line;
+        this.platform = platform;
+        this.lookedIn = [...lookedIn];
+    }
+}
+/**
+ * Base of the fetch-time verdicts (docs/fetch.md §3–§7). `code` is one of the
+ * shared codes; the subclasses exist so `instanceof` reads as well as `code`.
+ */
+export class FetchError extends ChtypesError {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/**
+ * `CHTYPES_ARTIFACT_UNTRUSTED`: the release's `SHA256SUMS.sig` is absent,
+ * malformed, or does not verify with any trusted key. Nothing is downloaded
+ * around it (§3 step 0).
+ */
+export class ArtifactUntrustedError extends FetchError {
+    constructor(message, options) {
+        super('CHTYPES_ARTIFACT_UNTRUSTED', message, options);
+    }
+}
+/**
+ * `CHTYPES_ARTIFACT_CORRUPT`: any hash mismatch along the chain, a release
+ * that disagrees with itself (`index.json` vs `SHA256SUMS`, manifest vs
+ * index), or an archive that cannot be read safely.
+ */
+export class ArtifactCorruptError extends FetchError {
+    constructor(message, options) {
+        super('CHTYPES_ARTIFACT_CORRUPT', message, options);
+    }
+}
+/**
+ * `CHTYPES_ARTIFACT_PINNED`: a `--frozen` lock file names a different asset
+ * or sha256 for this line — or none at all — and the fetch refused it (§5).
+ */
+export class ArtifactPinnedError extends FetchError {
+    constructor(message, options) {
+        super('CHTYPES_ARTIFACT_PINNED', message, options);
+    }
+}
+/** `CHTYPES_ARTIFACT_UNPUBLISHED`: the release has nothing for this platform, line or exact patch. */
+export class ArtifactUnpublishedError extends FetchError {
+    constructor(message, options) {
+        super('CHTYPES_ARTIFACT_UNPUBLISHED', message, options);
+    }
+}
+/**
+ * `CHTYPES_SOURCE_UNREACHABLE`: the source could not be reached or does not
+ * serve the release files — or `offline` forbade reaching it and the line is
+ * not installed and verified.
+ */
+export class SourceUnreachableError extends FetchError {
+    constructor(message, options) {
+        super('CHTYPES_SOURCE_UNREACHABLE', message, options);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/fetch.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Fetching, verifying and installing artifacts — docs/fetch.md, the contract
+ * every SDK implements identically: the same source (§2), the same
+ * verification chain (§3), the same signature policy (§4), the same lock
+ * file (§5), the same function (§6) and the same codes (§7).
+ *
+ * Nothing here is a verdict but the chain. No exit code, no
+ * `Content-Length`, no "download finished" ever is:
+ *
+ *   0. `SHA256SUMS.sig` — ed25519 over the exact bytes of `SHA256SUMS`, with a
+ *      trusted key. Failure stops everything; nothing is downloaded around it.
+ *   1. `index.json` names the asset for the line/platform and its sha256.
+ *   2. `SHA256SUMS` — now known-authentic — must list the same file with the
+ *      same sha256; a disagreement is a broken release, reported, not repaired.
+ *   3. The tarball is hashed BEFORE it is unpacked.
+ *   4. `manifest.json` inside names the library and its sha256; after the
+ *      move into `<registry>/<minor>/`, the installed library is hashed again
+ *      in place.
+ *
+ * The install is atomic — unpack into a temporary sibling, rename into place
+ * — and idempotent: an installed line that hashes what the release says is
+ * reported as installed and nothing is downloaded.
+ *
+ * Steady state is offline: once files are in a registry directory the loader
+ * trusts the directory, exactly as a runtime trusts `node_modules`.
+ * Verification is a fetch-time policy, not a load-time gate.
+ */
+/** The public artifacts host (docs/fetch.md §2); `CHTYPES_ARTIFACTS_URL` overrides it. */
+export declare const DEFAULT_ARTIFACTS_URL = "https://artifacts.wavehouse.dev";
+/** The rolling release every fetch reads by default; `tag` picks a frozen one. */
+export declare const DEFAULT_RELEASE_TAG = "artifacts";
+/**
+ * The release signing key(s) — raw 32-byte ed25519 public keys, hex
+ * (docs/fetch.md §4). `CHTYPES_TRUSTED_KEYS` or the `trustedKeys` option
+ * REPLACES this list; it is never extended silently.
+ */
+export declare const RELEASE_PUBLIC_KEYS: readonly string[];
+/** The lock-file schema this SDK writes and reads (docs/fetch.md §5). */
+export declare const LOCK_SCHEMA = 1;
+/** The lock file `frozen` reads when no `lock` names one (docs/fetch.md, Decisions); relative, so the working directory's. */
+export declare const DEFAULT_LOCK_FILE = "chtypes.lock";
+/** One row of a release's `index.json` (docs/artifacts.md §2). */
+export interface IndexArtifact {
+    readonly os: string;
+    readonly arch: string;
+    readonly file: string;
+    /** sha256 of the tarball. */
+    readonly sha256: string;
+    /** size of the tarball. */
+    readonly bytes: number;
+    readonly clickhouse_version: string;
+    readonly clickhouse_minor: string;
+    readonly library: string;
+    readonly library_sha256: string;
+}
+/** A release's `index.json`, schema 1. */
+export interface ReleaseIndex {
+    readonly schema: number;
+    readonly generated_at?: string;
+    readonly release_tag?: string;
+    readonly license?: string;
+    readonly license_url?: string;
+    readonly artifacts: readonly IndexArtifact[];
+}
+/** One pinned line in a lock file: the asset that was installed and its sha256. */
+export interface LockEntry {
+    readonly file: string;
+    readonly sha256: string;
+}
+/** `chtypes.lock` (docs/fetch.md §5): `{"schema": 1, "artifacts": {"<os>-<arch>/<minor>": {file, sha256}}}`. */
+export interface LockFile {
+    readonly schema: number;
+    readonly artifacts: Record<string, LockEntry>;
+}
+/** Progress, for a caller that wants to show it (the CLI prints these on stderr). */
+export type FetchEvent = {
+    readonly type: 'status';
+    readonly message: string;
+} | {
+    readonly type: 'download';
+    readonly file: string;
+    readonly received: number;
+    readonly total: number;
+};
+/** Options for `ensure`, `ensureAll`, `listArtifacts` — the §6 flags, spelled as properties. */
+export interface EnsureOptions {
+    /** Where to install (`--dest`); default: the §1 write target (`CHTYPES_REGISTRY`, else the per-user cache). */
+    readonly dest?: string | undefined;
+    /** `<os>-<arch>` (`--platform`); default: this host (`CHTYPES_TARGET` overrides, as `scripts/fetch.sh`). */
+    readonly platform?: string | undefined;
+    /** A release tag on the artifacts host (`--tag`); default the rolling `artifacts`. Exclusive with `url`. */
+    readonly tag?: string | undefined;
+    /** Any other base (`--url`): `https://…`, `file://…`, or a plain directory. Exclusive with `tag`. */
+    readonly url?: string | undefined;
+    /** A lock file to record into (`--lock`), and to enforce with `frozen`. */
+    readonly lock?: string | undefined;
+    /** Refuse anything the lock does not pin, with `CHTYPES_ARTIFACT_PINNED` (`--frozen`). */
+    readonly frozen?: boolean | undefined;
+    /** Re-download even when the line is installed and verified (`--force`). */
+    readonly force?: boolean | undefined;
+    /** Never touch the source: installed-and-verified is fine, anything else is `CHTYPES_SOURCE_UNREACHABLE` (`--offline`). */
+    readonly offline?: boolean | undefined;
+    /** Raw ed25519 public keys, hex; REPLACES the embedded release key (as `CHTYPES_TRUSTED_KEYS` does). */
+    readonly trustedKeys?: readonly string[] | undefined;
+    /** Skip the signature (step 0) with one loud warning; never the default (as `CHTYPES_ALLOW_UNSIGNED=1`). */
+    readonly allowUnsigned?: boolean | undefined;
+    /** Progress events; silent when absent. */
+    readonly onProgress?: ((event: FetchEvent) => void) | undefined;
+    /** Aborts an in-progress download. */
+    readonly signal?: AbortSignal | undefined;
+}
+/** What `ensure` did: where the line is, what it is, and whether bytes moved. */
+export interface EnsureResult {
+    /** The installed line directory, `<registry>/<minor>` — what `fetch` prints. */
+    readonly dir: string;
+    /** The registry directory the line lives in. */
+    readonly registry: string;
+    readonly line: string;
+    readonly version: string;
+    readonly platform: string;
+    /** The asset name and its sha256 — what the lock records; empty on the offline path. */
+    readonly file: string;
+    readonly sha256: string;
+    readonly library: string;
+    readonly librarySha256: string;
+    /** true when the tarball was downloaded and installed by this call; false when the line was already installed and verified. */
+    readonly installed: boolean;
+    /** The source that was consulted, or `offline`. */
+    readonly source: string;
+    /** Whether `SHA256SUMS` carried a signature a trusted key verified, and that key's id. */
+    readonly signed: boolean;
+    readonly keyId: string | null;
+}
+/** One installed line, as `verify` and `list` report it. */
+export interface InstalledArtifact {
+    readonly line: string;
+    readonly dir: string;
+    readonly version: string;
+    readonly library: string;
+    /** The manifest's sha256; what the file hashes (only `verifyInstalled` fills it in); the verdict. */
+    readonly expected: string;
+    readonly actual: string | null;
+    readonly ok: boolean;
+    readonly problem: string | null;
+}
+/** What `list` shows: what is installed, and what the release offers for the platform. */
+export interface ListResult {
+    readonly registry: string;
+    readonly platform: string;
+    readonly installed: readonly InstalledArtifact[];
+    /** null when offline. */
+    readonly offered: readonly IndexArtifact[] | null;
+    readonly source: string | null;
+}
+/** How a version was asked for: the line, and the exact patch if one was typed. */
+export interface VersionRequest {
+    readonly spelling: string;
+    /** e.g. `25.8`. */
+    readonly line: string;
+    /** `25.8.28.1-lts` when a patch was typed (a hard requirement), else null. */
+    readonly exact: string | null;
+    /** The exact patch without its channel suffix, when one was typed. */
+    readonly bare: string | null;
+}
+/**
+ * `25.8` is a line; `25.8.28.1-lts`, `v25.8.28.1-lts` and `25.8.28.1` are an
+ * exact patch and a hard requirement (a release that publishes another patch
+ * of the line refuses it — ask for the line to take what was published).
+ *
+ * @throws {ChtypesError} when the spelling is not a ClickHouse version at all.
+ */
+export declare function parseVersionSpelling(spelling: string): VersionRequest;
+/** Numeric order over dotted versions, channel suffix ignored: 25.10 > 25.8, 25.8.30.16 > 25.8.28.1. */
+export declare function compareVersions(a: string, b: string): number;
+/** The key id docs/fetch.md §4 defines: the first 16 hex characters of sha256 over the raw 32-byte public key. */
+export declare function keyId(rawKeyHex: string): string;
+/**
+ * Verify an ed25519 signature over `message` with a raw public key, through
+ * `node:crypto` — the key wrapped as SPKI DER, the 64-byte signature as is.
+ * False, never a throw, for a malformed key or signature.
+ */
+export declare function verifyEd25519(message: Uint8Array, signature: Uint8Array, rawKeyHex: string): boolean;
+/**
+ * `SHA256SUMS.sig`: an `untrusted comment:` line, then the base64 of the
+ * 64-byte signature. Null when the file is not in that shape.
+ */
+export declare function parseSignatureFile(bytes: Uint8Array): {
+    comment: string;
+    signature: Buffer;
+} | null;
+/**
+ * The keys a fetch trusts: the `trustedKeys` option, else `CHTYPES_TRUSTED_KEYS`
+ * (`<hex>[,<hex>…]`), else the embedded release key. Each REPLACES the one
+ * below it.
+ *
+ * @throws {ChtypesError} when an entry is not 64 hex characters.
+ */
+export declare function trustedKeys(explicit?: readonly string[]): string[];
+/** The one row for a request, or `CHTYPES_ARTIFACT_UNPUBLISHED` naming what the release does have. */
+export declare function selectArtifact(index: ReleaseIndex, platform: string, req: VersionRequest): IndexArtifact;
+/** Every line the release publishes for the platform, newest patch per line, oldest line first. */
+export declare function selectAll(index: ReleaseIndex, platform: string): IndexArtifact[];
+/**
+ * Make one ClickHouse line available in a registry directory, through the
+ * verification chain, and say where it is. Idempotent: installed and
+ * verified is a no-op that downloads nothing (`force` re-downloads).
+ *
+ * @param spelling - a line (`"25.8"`) or an exact patch (`"25.8.28.1-lts"`, a hard requirement).
+ * @param options - see `EnsureOptions`; every §6 flag has a property here.
+ * @returns where the line is and what it is — `dir` is `<registry>/<minor>`.
+ * @throws {ArtifactUntrustedError} `CHTYPES_ARTIFACT_UNTRUSTED` — no signature, or none a trusted key verifies.
+ * @throws {ArtifactCorruptError} `CHTYPES_ARTIFACT_CORRUPT` — any hash mismatch, a release that disagrees with itself.
+ * @throws {ArtifactPinnedError} `CHTYPES_ARTIFACT_PINNED` — `frozen` and the lock says otherwise.
+ * @throws {ArtifactUnpublishedError} `CHTYPES_ARTIFACT_UNPUBLISHED` — nothing for this platform/line/patch.
+ * @throws {SourceUnreachableError} `CHTYPES_SOURCE_UNREACHABLE` — the source cannot be reached, or `offline` and not installed.
+ * @throws {ChtypesError} for a spelling that is not a version, a bad platform key, or conflicting options.
+ */
+export declare function ensure(spelling: string, options?: EnsureOptions): Promise<EnsureResult>;
+/** `fetch --all`: every line the release publishes for the platform, each through `ensure`'s chain. */
+export declare function ensureAll(options?: EnsureOptions): Promise<EnsureResult[]>;
+/**
+ * `chtypes verify`: re-hash every installed line in a registry directory
+ * against its own manifest. A line whose manifest cannot be read is not a
+ * line (a scratch directory) and is skipped, as the loader skips it.
+ */
+export declare function verifyInstalled(dest?: string, platform?: string): Promise<InstalledArtifact[]>;
+/** `chtypes list`: what is installed in the registry directory, and what the release offers for the platform. */
+export declare function listArtifacts(options?: EnsureOptions): Promise<ListResult>;
+/** Read a lock file; null when it does not exist. */
+export declare function readLock(file: string): LockFile | null;
+/** The platform a fetch is for: the option, else `CHTYPES_TARGET`, else this host. */
+export declare function resolvePlatform(explicit?: string): string;
+/** sha256 of a file, streamed — a 300 MB library never sits in memory whole. */
+export declare function sha256File(file: string): Promise<string>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/fetch.d.ts.map

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