@wavehouse/chtypes 0.1.1 → 0.2.0

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * `chtypes` — the one CLI surface every SDK carries (docs/fetch.md §6),
+ * `chtypes` — the one CLI surface every SDK carries (docs/guides/fetch.md §6),
  * spelled identically in all four:
  *
  *   chtypes fetch <line>... [--all] [--platform <os-arch>] [--dest <dir>]

package/dist/discover.d.ts

@@ -10,7 +10,7 @@
  *   profile.settings -> compileDdl({ settings }) (compile-time) and per-call settings
  *   columns          -> reconstructDdl -> compileDdl
  *
- * The pattern, in full (spec/bindings.md §Discovery):
+ * The pattern, in full (docs/reference/bindings.md §Discovery):
  *
  *   1. run QUERY_SERVER_VERSION, QUERY_CHANGED_SETTINGS once per connection
  *   2. cache the ServerProfile per deployment/tenant
@@ -20,7 +20,7 @@
  *
  * Never ask the customer for their settings — ask their server. The queries
  * return exactly what the server believes, spelled the way the server spells
- * it, which is what the settings gate (spec/c-abi.md, Settings rule 2)
+ * it, which is what the settings gate (the C ABI contract, Settings rule 2)
  * validates against.
  *
  * The parsers read JSONEachRow bytes through this package's own byte-exact

package/dist/discover.js

@@ -10,7 +10,7 @@
  *   profile.settings -> compileDdl({ settings }) (compile-time) and per-call settings
  *   columns          -> reconstructDdl -> compileDdl
  *
- * The pattern, in full (spec/bindings.md §Discovery):
+ * The pattern, in full (docs/reference/bindings.md §Discovery):
  *
  *   1. run QUERY_SERVER_VERSION, QUERY_CHANGED_SETTINGS once per connection
  *   2. cache the ServerProfile per deployment/tenant
@@ -20,7 +20,7 @@
  *
  * Never ask the customer for their settings — ask their server. The queries
  * return exactly what the server believes, spelled the way the server spells
- * it, which is what the settings gate (spec/c-abi.md, Settings rule 2)
+ * it, which is what the settings gate (the C ABI contract, Settings rule 2)
  * validates against.
  *
  * The parsers read JSONEachRow bytes through this package's own byte-exact

package/dist/errors.d.ts

@@ -1,6 +1,6 @@
 /**
  * The error model, which is three outcomes that must never be conflated
- * (spec/c-abi.md §Error model):
+ * (the C ABI contract §Error model):
  *
  *   - ClickHouse rejects        -> a real ClickHouse error code
  *   - this build refuses        -> CODE_UNSUPPORTED (-2), never a ClickHouse code
@@ -24,7 +24,7 @@ export declare const CODE_UNSUPPORTED = -2;
  * 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).
+ * incompatibility (docs/reference/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` /
@@ -35,7 +35,7 @@ export declare const CODE_UNSUPPORTED = -2;
  * 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.
+ * is undefined behavior, which is exactly what the gate exists to prevent.
  */
 export declare const ABI_REVISION = 4;
 /** Base class for everything this package throws. */
@@ -54,7 +54,7 @@ export declare class RegistryError extends ChtypesError {
  * `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).
+ * (docs/reference/bindings.md rule 12).
  */
 export declare class SchemaError extends ChtypesError {
     readonly code: number;
@@ -103,7 +103,7 @@ export declare class UnsupportedError extends ChtypesError {
  * 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
+ * The SIGN decides (docs/reference/bindings.md rule 12, the C ABI contract §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
@@ -114,8 +114,48 @@ export declare class UnsupportedError extends ChtypesError {
  * Internal: not re-exported from the package index.
  */
 export declare function schemaErrorFor(code: number, detail: string, column?: string): SchemaError | UnsupportedError;
-/** The codes docs/fetch.md §7 shares across every SDK. */
-export type ArtifactErrorCode = 'CHTYPES_ARTIFACT_MISSING' | 'CHTYPES_ARTIFACT_UNTRUSTED' | 'CHTYPES_ARTIFACT_CORRUPT' | 'CHTYPES_ARTIFACT_PINNED' | 'CHTYPES_ARTIFACT_UNPUBLISHED' | 'CHTYPES_SOURCE_UNREACHABLE';
+/**
+ * The codes docs/guides/fetch.md §6 shares across every SDK, as named constants.
+ *
+ * Each error below carries its own `code`, and a caller matches on it. Naming
+ * them here is what lets that caller write `err.code === CODE_ARTIFACT_PINNED`
+ * instead of retyping the string — which is exactly why the Go, Python and Rust
+ * bindings all export them, and why this one already exported
+ * `CODE_UNSUPPORTED`. A typo in a hand-written literal is a comparison that is
+ * silently always false.
+ */
+export declare const CODE_ARTIFACT_MISSING = "CHTYPES_ARTIFACT_MISSING";
+/** docs/guides/fetch.md §6: the signature did not verify against the trust list. */
+export declare const CODE_ARTIFACT_UNTRUSTED = "CHTYPES_ARTIFACT_UNTRUSTED";
+/** docs/guides/fetch.md §6: a hash mismatch, or a release that disagrees with itself. */
+export declare const CODE_ARTIFACT_CORRUPT = "CHTYPES_ARTIFACT_CORRUPT";
+/** docs/guides/fetch.md §6: `--frozen` refused an asset the lock file does not pin. */
+export declare const CODE_ARTIFACT_PINNED = "CHTYPES_ARTIFACT_PINNED";
+/** docs/guides/fetch.md §6: the release offers nothing for this platform or line. */
+export declare const CODE_ARTIFACT_UNPUBLISHED = "CHTYPES_ARTIFACT_UNPUBLISHED";
+/** docs/guides/fetch.md §6: the source could not be reached or does not serve the release. */
+export declare const CODE_SOURCE_UNREACHABLE = "CHTYPES_SOURCE_UNREACHABLE";
+/** The codes docs/guides/fetch.md §7 shares across every SDK. */
+export type ArtifactErrorCode = typeof CODE_ARTIFACT_MISSING | typeof CODE_ARTIFACT_UNTRUSTED | typeof CODE_ARTIFACT_CORRUPT | typeof CODE_ARTIFACT_PINNED | typeof CODE_ARTIFACT_UNPUBLISHED | typeof CODE_SOURCE_UNREACHABLE;
+/**
+ * The single catchable type for every artifact-loading condition: a missing
+ * artifact (`ArtifactMissingError`) or one of the five fetch/verify verdicts
+ * (`FetchError`'s subclasses) — the six conditions docs/guides/fetch.md §3, §5
+ * and §7 name. A caller that wants "the loader could not produce a usable
+ * artifact" now catches exactly this one class, matching Python's
+ * `ArtifactError`, Go's `*ArtifactError` (`.Code`), and Rust's
+ * `Error::artifact_code()` (chtypes-sdk#13 A3, aligned 2026-09-15) — before
+ * this, `ArtifactMissingError` was a `RegistryError` while the other five
+ * were unrelated `FetchError`s, and a caller had to catch both types to
+ * cover all six conditions.
+ *
+ * A `RegistryError`, because every one of these is a reason the loader could
+ * not serve a version — `catch`es written against the pre-existing
+ * `RegistryError` contract keep working unchanged.
+ */
+export declare abstract class ArtifactError extends RegistryError {
+    abstract readonly code: ArtifactErrorCode;
+}
 /** The command this SDK's §7 message tells a user to run. */
 export declare const FETCH_COMMAND = "npx @wavehouse/chtypes fetch";
 /**
@@ -127,16 +167,18 @@ export declare const FETCH_COMMAND = "npx @wavehouse/chtypes fetch";
  */
 export declare function artifactMissingMessage(line: string, platform: string, lookedIn: readonly string[]): string;
 /**
- * The one identifiable error for a missing artifact (docs/fetch.md §7):
+ * The one identifiable error for a missing artifact (docs/guides/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.
+ * A subclass of `ArtifactError` (itself a `RegistryError`), so a `catch`
+ * written against `for()`'s documented `RegistryError`, or against the
+ * single catchable `ArtifactError`, both keep working; the `code` is what a
+ * caller matches on.
  */
-export declare class ArtifactMissingError extends RegistryError {
+export declare class ArtifactMissingError extends ArtifactError {
     readonly code: 'CHTYPES_ARTIFACT_MISSING';
     /** The minor line that was asked for, e.g. `25.8`. */
     readonly line: string;
@@ -147,10 +189,15 @@ export declare class ArtifactMissingError extends RegistryError {
     constructor(line: string, platform: string, lookedIn: readonly string[]);
 }
 /**
- * Base of the fetch-time verdicts (docs/fetch.md §3–§7). `code` is one of the
+ * Base of the fetch-time verdicts (docs/guides/fetch.md §3–§7). `code` is one of the
  * shared codes; the subclasses exist so `instanceof` reads as well as `code`.
+ *
+ * An `ArtifactError`, alongside `ArtifactMissingError` — so `catch (err) { if
+ * (err instanceof ArtifactError) … }` handles all six artifact conditions in
+ * one arm, while `instanceof FetchError` still isolates these five verdicts
+ * from a missing artifact when that distinction matters.
  */
-export declare class FetchError extends ChtypesError {
+export declare class FetchError extends ArtifactError {
     readonly code: Exclude<ArtifactErrorCode, 'CHTYPES_ARTIFACT_MISSING'>;
     constructor(code: Exclude<ArtifactErrorCode, 'CHTYPES_ARTIFACT_MISSING'>, message: string, options?: {
         cause?: unknown;

package/dist/errors.d.ts.map

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

package/dist/errors.js

@@ -1,6 +1,6 @@
 /**
  * The error model, which is three outcomes that must never be conflated
- * (spec/c-abi.md §Error model):
+ * (the C ABI contract §Error model):
  *
  *   - ClickHouse rejects        -> a real ClickHouse error code
  *   - this build refuses        -> CODE_UNSUPPORTED (-2), never a ClickHouse code
@@ -24,7 +24,7 @@ export const CODE_UNSUPPORTED = -2;
  * 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).
+ * incompatibility (docs/reference/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` /
@@ -35,7 +35,7 @@ export const CODE_UNSUPPORTED = -2;
  * 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.
+ * is undefined behavior, which is exactly what the gate exists to prevent.
  */
 export const ABI_REVISION = 4;
 /** Base class for everything this package throws. */
@@ -55,7 +55,7 @@ export class RegistryError extends ChtypesError {
  * `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).
+ * (docs/reference/bindings.md rule 12).
  */
 export class SchemaError extends ChtypesError {
     code;
@@ -117,7 +117,7 @@ export class UnsupportedError extends ChtypesError {
  * 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
+ * The SIGN decides (docs/reference/bindings.md rule 12, the C ABI contract §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
@@ -130,6 +130,52 @@ export class UnsupportedError extends ChtypesError {
 export function schemaErrorFor(code, detail, column) {
     return code < 0 ? new UnsupportedError(detail, column) : new SchemaError(code, detail, column);
 }
+// ---------------------------------------------------------------- artifacts
+//
+// The fetch/verify contract (docs/guides/fetch.md §7) shares six codes across the
+// four SDKs. Five of them are verdicts of the verification chain or of the
+// source and are raised by `ensure` / the CLI; the sixth,
+// `CHTYPES_ARTIFACT_MISSING`, is the loader's — raised when a registry is
+// asked for a line no directory on the search path holds.
+/**
+ * The codes docs/guides/fetch.md §6 shares across every SDK, as named constants.
+ *
+ * Each error below carries its own `code`, and a caller matches on it. Naming
+ * them here is what lets that caller write `err.code === CODE_ARTIFACT_PINNED`
+ * instead of retyping the string — which is exactly why the Go, Python and Rust
+ * bindings all export them, and why this one already exported
+ * `CODE_UNSUPPORTED`. A typo in a hand-written literal is a comparison that is
+ * silently always false.
+ */
+export const CODE_ARTIFACT_MISSING = 'CHTYPES_ARTIFACT_MISSING';
+/** docs/guides/fetch.md §6: the signature did not verify against the trust list. */
+export const CODE_ARTIFACT_UNTRUSTED = 'CHTYPES_ARTIFACT_UNTRUSTED';
+/** docs/guides/fetch.md §6: a hash mismatch, or a release that disagrees with itself. */
+export const CODE_ARTIFACT_CORRUPT = 'CHTYPES_ARTIFACT_CORRUPT';
+/** docs/guides/fetch.md §6: `--frozen` refused an asset the lock file does not pin. */
+export const CODE_ARTIFACT_PINNED = 'CHTYPES_ARTIFACT_PINNED';
+/** docs/guides/fetch.md §6: the release offers nothing for this platform or line. */
+export const CODE_ARTIFACT_UNPUBLISHED = 'CHTYPES_ARTIFACT_UNPUBLISHED';
+/** docs/guides/fetch.md §6: the source could not be reached or does not serve the release. */
+export const CODE_SOURCE_UNREACHABLE = 'CHTYPES_SOURCE_UNREACHABLE';
+/**
+ * The single catchable type for every artifact-loading condition: a missing
+ * artifact (`ArtifactMissingError`) or one of the five fetch/verify verdicts
+ * (`FetchError`'s subclasses) — the six conditions docs/guides/fetch.md §3, §5
+ * and §7 name. A caller that wants "the loader could not produce a usable
+ * artifact" now catches exactly this one class, matching Python's
+ * `ArtifactError`, Go's `*ArtifactError` (`.Code`), and Rust's
+ * `Error::artifact_code()` (chtypes-sdk#13 A3, aligned 2026-09-15) — before
+ * this, `ArtifactMissingError` was a `RegistryError` while the other five
+ * were unrelated `FetchError`s, and a caller had to catch both types to
+ * cover all six conditions.
+ *
+ * A `RegistryError`, because every one of these is a reason the loader could
+ * not serve a version — `catch`es written against the pre-existing
+ * `RegistryError` contract keep working unchanged.
+ */
+export class ArtifactError extends RegistryError {
+}
 /** The command this SDK's §7 message tells a user to run. */
 export const FETCH_COMMAND = 'npx @wavehouse/chtypes fetch';
 /**
@@ -145,16 +191,18 @@ export function artifactMissingMessage(line, platform, lookedIn) {
         'or set CHTYPES_AUTOFETCH=1 to fetch on first use.');
 }
 /**
- * The one identifiable error for a missing artifact (docs/fetch.md §7):
+ * The one identifiable error for a missing artifact (docs/guides/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.
+ * A subclass of `ArtifactError` (itself a `RegistryError`), so a `catch`
+ * written against `for()`'s documented `RegistryError`, or against the
+ * single catchable `ArtifactError`, both keep working; the `code` is what a
+ * caller matches on.
  */
-export class ArtifactMissingError extends RegistryError {
+export class ArtifactMissingError extends ArtifactError {
     code = 'CHTYPES_ARTIFACT_MISSING';
     /** The minor line that was asked for, e.g. `25.8`. */
     line;
@@ -170,10 +218,15 @@ export class ArtifactMissingError extends RegistryError {
     }
 }
 /**
- * Base of the fetch-time verdicts (docs/fetch.md §3–§7). `code` is one of the
+ * Base of the fetch-time verdicts (docs/guides/fetch.md §3–§7). `code` is one of the
  * shared codes; the subclasses exist so `instanceof` reads as well as `code`.
+ *
+ * An `ArtifactError`, alongside `ArtifactMissingError` — so `catch (err) { if
+ * (err instanceof ArtifactError) … }` handles all six artifact conditions in
+ * one arm, while `instanceof FetchError` still isolates these five verdicts
+ * from a missing artifact when that distinction matters.
  */
-export class FetchError extends ChtypesError {
+export class FetchError extends ArtifactError {
     code;
     constructor(code, message, options) {
         super(message, options);

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC;AAE9B,qDAAqD;AACrD,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AAED,0EAA0E;AAC1E,MAAM,OAAO,aAAc,SAAQ,YAAY;CAAG;AAElD;;;;;;;;GAQG;AACH,MAAM,OAAO,WAAY,SAAQ,YAAY;IAClC,IAAI,CAAS;IACb,MAAM,CAAS;IACf,MAAM,CAAqB;IAEpC,YAAY,IAAY,EAAE,MAAc,EAAE,MAAe;QACvD,KAAK,CACH,MAAM;YACJ,CAAC,CAAC,mBAAmB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,IAAI,KAAK,MAAM,EAAE;YAClE,CAAC,CAAC,aAAa,IAAI,KAAK,MAAM,EAAE,CACnC,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IACvC,MAAM,CAAS;IACf,MAAM,CAAqB;IAEpC,YAAY,MAAc,EAAE,MAAe;QACzC,KAAK,CACH,MAAM;YACJ,CAAC,CAAC,mBAAmB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,gBAAgB,KAAK,MAAM,EAAE;YAC9E,CAAC,CAAC,aAAa,gBAAgB,KAAK,MAAM,EAAE,CAC/C,CAAC;QACF,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,MAAc,EACd,MAAe;IAEf,OAAO,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AACjG,CAAC;AAmBD,6DAA6D;AAC7D,MAAM,CAAC,MAAM,aAAa,GAAG,8BAA8B,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY,EAAE,QAAgB,EAAE,QAA2B;IAChG,OAAO,CACL,uCAAuC,IAAI,KAAK,QAAQ,iBAAiB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;QACjG,gBAAgB,aAAa,IAAI,IAAI,IAAI;QACzC,mDAAmD,CACpD,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,oBAAqB,SAAQ,aAAa;IAC5C,IAAI,GAAG,0BAAmC,CAAC;IACpD,sDAAsD;IAC7C,IAAI,CAAS;IACtB,iEAAiE;IACxD,QAAQ,CAAS;IAC1B,oDAAoD;IAC3C,QAAQ,CAAoB;IAErC,YAAY,IAAY,EAAE,QAAgB,EAAE,QAA2B;QACrE,KAAK,CAAC,sBAAsB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;IAChC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,UAAW,SAAQ,YAAY;IACjC,IAAI,CAAyD;IAEtE,YACE,IAA4D,EAC5D,OAAe,EACf,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,sBAAuB,SAAQ,UAAU;IACpD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,4BAA4B,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,oBAAqB,SAAQ,UAAU;IAClD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,0BAA0B,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,UAAU;IACjD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,yBAAyB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACrD,CAAC;CACF;AAED,sGAAsG;AACtG,MAAM,OAAO,wBAAyB,SAAQ,UAAU;IACtD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,8BAA8B,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1D,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,sBAAuB,SAAQ,UAAU;IACpD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,4BAA4B,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/fetch.d.ts

@@ -1,5 +1,5 @@
 /**
- * Fetching, verifying and installing artifacts — docs/fetch.md, the contract
+ * Fetching, verifying and installing artifacts — docs/guides/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).
@@ -25,21 +25,21 @@
  * 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. */
+/** The public artifacts host (docs/guides/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
+ * (docs/guides/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). */
+/** The lock-file schema this SDK writes and reads (docs/guides/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. */
+/** The lock file `frozen` reads when no `lock` names one (docs/guides/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). */
+/** One row of a release's `index.json` (docs/guides/artifacts.md §2). */
 export interface IndexArtifact {
     readonly os: string;
     readonly arch: string;
@@ -76,7 +76,7 @@ export interface LockEntry {
     readonly file: string;
     readonly sha256: string;
 }
-/** `chtypes.lock` (docs/fetch.md §5): `{"schema": 1, "artifacts": {"<os>-<arch>/<minor>": {file, sha256}}}`. */
+/** `chtypes.lock` (docs/guides/fetch.md §5): `{"schema": 1, "artifacts": {"<os>-<arch>/<minor>": {file, sha256}}}`. */
 export interface LockFile {
     readonly schema: number;
     readonly artifacts: Record<string, LockEntry>;
@@ -181,8 +181,15 @@ export interface VersionRequest {
 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. */
+/** The key id docs/guides/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;
+/**
+ * `keyId(RELEASE_PUBLIC_KEYS[0])`, precomputed — the id the signature file's
+ * comment line names for the primary release key. `RELEASE_PUBLIC_KEYS` stays
+ * the list to verify against (rotation adds a second entry); this is the one
+ * short id go/python/rust each export as a scalar constant.
+ */
+export declare const RELEASE_KEY_ID: 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.

package/dist/fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAwBH,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB,oCAAoC,CAAC;AACvE,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAC/C;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAEhD,CAAC;AACF,yEAAyE;AACzE,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,8HAA8H;AAC9H,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAKhD,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;CAC9C;AAED,mFAAmF;AACnF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,gHAAgH;AAChH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAC/C;AAED,qFAAqF;AACrF,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5G,gGAAgG;AAChG,MAAM,WAAW,aAAa;IAC5B,+GAA+G;IAC/G,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,4GAA4G;IAC5G,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,4GAA4G;IAC5G,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,qGAAqG;IACrG,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,2HAA2H;IAC3H,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,wGAAwG;IACxG,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACrD,4GAA4G;IAC5G,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAChE,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+HAA+H;IAC/H,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qGAAqG;IACrG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,0FAA0F;AAC1F,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAID,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mBAAmB;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAID;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CASrE;AAED,wGAAwG;AACxG,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAU5D;AAQD,kHAAkH;AAClH,wBAAgB,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAYpG;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAenG;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAgBlE;AA6TD,sGAAsG;AACtG,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,aAAa,CA4BxG;AAaD,mGAAmG;AACnG,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE,CAOhF;AAmBD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAYjG;AAED,uGAAuG;AACvG,wBAAsB,SAAS,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAcpF;AAgQD;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAQpG;AAED,iHAAiH;AACjH,wBAAsB,aAAa,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CA8BpF;AAID,qDAAqD;AACrD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CA2BtD;AAWD,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAKzD;AA2DD,gFAAgF;AAChF,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9D"}
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"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"}

package/dist/fetch.js

@@ -1,5 +1,5 @@
 /**
- * Fetching, verifying and installing artifacts — docs/fetch.md, the contract
+ * Fetching, verifying and installing artifacts — docs/guides/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).
@@ -37,21 +37,21 @@ import { ArtifactCorruptError, ArtifactPinnedError, ArtifactUnpublishedError, Ar
 import { fetchDestination, hostPlatform, isPlatformKey } from './paths.js';
 import { extractTarGz } from './tar.js';
 // ------------------------------------------------------------- constants
-/** The public artifacts host (docs/fetch.md §2); `CHTYPES_ARTIFACTS_URL` overrides it. */
+/** The public artifacts host (docs/guides/fetch.md §2); `CHTYPES_ARTIFACTS_URL` overrides it. */
 export const DEFAULT_ARTIFACTS_URL = 'https://artifacts.wavehouse.dev';
 /** The rolling release every fetch reads by default; `tag` picks a frozen one. */
 export 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
+ * (docs/guides/fetch.md §4). `CHTYPES_TRUSTED_KEYS` or the `trustedKeys` option
  * REPLACES this list; it is never extended silently.
  */
 export const RELEASE_PUBLIC_KEYS = [
     'fdb5f06a8d4c9918d049a5f1748fa2e3b3238c3f2000986d5bb9e31beff778fc',
 ];
-/** The lock-file schema this SDK writes and reads (docs/fetch.md §5). */
+/** The lock-file schema this SDK writes and reads (docs/guides/fetch.md §5). */
 export const LOCK_SCHEMA = 1;
-/** The lock file `frozen` reads when no `lock` names one (docs/fetch.md, Decisions); relative, so the working directory's. */
+/** The lock file `frozen` reads when no `lock` names one (docs/guides/fetch.md, Decisions); relative, so the working directory's. */
 export const DEFAULT_LOCK_FILE = 'chtypes.lock';
 const INDEX_SCHEMA = 1;
 const CHANNEL = /-(lts|stable|prestable|testing)$/;
@@ -90,10 +90,17 @@ export function compareVersions(a, b) {
 /** The 12-byte SubjectPublicKeyInfo header for an Ed25519 key (RFC 8410): SEQUENCE { AlgorithmIdentifier(1.3.101.112), BIT STRING }. */
 const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
 const RAW_KEY = /^[0-9a-fA-F]{64}$/;
-/** The key id docs/fetch.md §4 defines: the first 16 hex characters of sha256 over the raw 32-byte public key. */
+/** The key id docs/guides/fetch.md §4 defines: the first 16 hex characters of sha256 over the raw 32-byte public key. */
 export function keyId(rawKeyHex) {
     return createHash('sha256').update(Buffer.from(rawKeyHex, 'hex')).digest('hex').slice(0, 16);
 }
+/**
+ * `keyId(RELEASE_PUBLIC_KEYS[0])`, precomputed — the id the signature file's
+ * comment line names for the primary release key. `RELEASE_PUBLIC_KEYS` stays
+ * the list to verify against (rotation adds a second entry); this is the one
+ * short id go/python/rust each export as a scalar constant.
+ */
+export const RELEASE_KEY_ID = keyId(RELEASE_PUBLIC_KEYS[0]);
 /**
  * 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.
@@ -506,7 +513,7 @@ function forPlatform(index, platform) {
     return rows;
 }
 // -------------------------------------------------------------- ensure
-/** Concurrent `ensure`s of one line in one process share one fetch (docs/fetch.md §6). */
+/** Concurrent `ensure`s of one line in one process share one fetch (docs/guides/fetch.md §6). */
 const inFlight = new Map();
 /**
  * Make one ClickHouse line available in a registry directory, through the
@@ -599,7 +606,7 @@ async function installGoldens(release, ctx) {
 }
 function installContext(platform, dest, options) {
     const frozen = options.frozen ?? false;
-    // frozen without a lock path reads ./chtypes.lock (docs/fetch.md, Decisions).
+    // frozen without a lock path reads ./chtypes.lock (docs/guides/fetch.md, Decisions).
     const lockPath = options.lock !== undefined && options.lock !== '' ? path.resolve(options.lock) : frozen ? path.resolve(DEFAULT_LOCK_FILE) : undefined;
     const lock = lockPath !== undefined ? readLock(lockPath) : null;
     if (frozen && lock === null) {