@wavehouse/chtypes 0.2.2 → 0.3.1

package/dist/format.d.ts

@@ -3,15 +3,17 @@
  * `Schema#row` / `Schema#rows`. These numbers are part of the C ABI
  * (the C ABI contract §Types and schemas) and MUST NOT be renumbered.
  *
- * Name-addressed: `JSONEachRow`. Positional (the k-th field lands in the k-th
- * insertable column; MATERIALIZED / ALIAS / EPHEMERAL occupy no position):
- * `CSV`, `TSV`, `Values`, `JSONCompactEachRow`, the RowBinary family, and
- * `Buffers`. `Native` is column-oriented and name-addressed.
+ * Name-addressed: `JSONEachRow`, and `CSVWithNames` / `TSVWithNames` through
+ * their header row. Positional (the k-th field lands in the k-th insertable
+ * column; MATERIALIZED / ALIAS / EPHEMERAL occupy no position): `CSV`, `TSV`,
+ * `Values`, `JSONCompactEachRow`, the RowBinary family, and `Buffers`.
+ * `Native` is column-oriented and name-addressed.
  *
- * The RowBinary family, `Native` and `Buffers` depend on when the loaded
- * ARTIFACT was linked, not on this package's version — probe the artifact
- * (feed it one payload) rather than assuming (docs/reference/bindings.md §Values a
- * binding must accept and reject).
+ * The RowBinary family, `Native`, `Buffers`, `CSVWithNames` and
+ * `TSVWithNames` depend on when the loaded ARTIFACT was linked, not on this
+ * package's version — probe the artifact (feed it one payload) rather than
+ * assuming (docs/reference/bindings.md §Values a binding must accept and
+ * reject).
  */
 export declare const Format: {
     /** One JSON object per line, fields matched to columns by name. */
@@ -59,6 +61,23 @@ export declare const Format: {
      * package's version.
      */
     readonly Buffers: 9;
+    /**
+     * CSV whose first row is a header naming the columns, so the data is
+     * addressed by NAME. With a column list as well (`columns`), the list decides
+     * the block and the header decides the layout. Header names match EXACTLY
+     * through ClickHouse 26.4 and case-insensitively from 26.5, exactly as those
+     * servers do. It joined `enum chs_format` inside ABI revision 5, so a
+     * revision-5 artifact built before it existed does not know it — the
+     * revision check cannot tell. Probe it, do not assume it from this package's
+     * version.
+     */
+    readonly CSVWithNames: 10;
+    /**
+     * TSV whose first row is a header naming the columns. Everything
+     * `CSVWithNames` says about the header, a column list, header matching and
+     * probing the artifact applies unchanged.
+     */
+    readonly TSVWithNames: 11;
 };
 /** One of the `chs_format` integer codes — see the `Format` constant object. */
 export type Format = (typeof Format)[keyof typeof Format];

package/dist/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM;IACjB,mEAAmE;aACnE,WAAW,EAAE,CAAC;IACd,yEAAyE;aACzE,GAAG,EAAE,CAAC;IACN,qHAAqH;aACrH,GAAG,EAAE,CAAC;IACN,iDAAiD;aACjD,MAAM,EAAE,CAAC;IACT,2CAA2C;aAC3C,kBAAkB,EAAE,CAAC;IACrB,8EAA8E;aAC9E,SAAS,EAAE,CAAC;IACZ,yEAAyE;aACzE,qBAAqB,EAAE,CAAC;IACxB;;;;OAIG;aACH,qCAAqC,EAAE,CAAC;IACxC;;;;;;;OAOG;aACH,MAAM,EAAE,CAAC;IACT;;;;;;;;;;;;;;OAcG;aACH,OAAO,EAAE,CAAC;CACF,CAAC;AAEX,gFAAgF;AAChF,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,WAAW,KAAK,CAAC;AAE9B;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,UAAU,IAAM,CAAC;AAC9B,yEAAyE;AACzE,eAAO,MAAM,cAAc,IAAM,CAAC;AAClC,iFAAiF;AACjF,eAAO,MAAM,YAAY,IAAM,CAAC;AAChC,0EAA0E;AAC1E,eAAO,MAAM,OAAO,QAA6C,CAAC;AAElE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK5C"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM;IACjB,mEAAmE;aACnE,WAAW,EAAE,CAAC;IACd,yEAAyE;aACzE,GAAG,EAAE,CAAC;IACN,qHAAqH;aACrH,GAAG,EAAE,CAAC;IACN,iDAAiD;aACjD,MAAM,EAAE,CAAC;IACT,2CAA2C;aAC3C,kBAAkB,EAAE,CAAC;IACrB,8EAA8E;aAC9E,SAAS,EAAE,CAAC;IACZ,yEAAyE;aACzE,qBAAqB,EAAE,CAAC;IACxB;;;;OAIG;aACH,qCAAqC,EAAE,CAAC;IACxC;;;;;;;OAOG;aACH,MAAM,EAAE,CAAC;IACT;;;;;;;;;;;;;;OAcG;aACH,OAAO,EAAE,CAAC;IACV;;;;;;;;;OASG;aACH,YAAY,EAAE,EAAE;IAChB;;;;OAIG;aACH,YAAY,EAAE,EAAE;CACR,CAAC;AAEX,gFAAgF;AAChF,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,WAAW,KAAK,CAAC;AAE9B;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,UAAU,IAAM,CAAC;AAC9B,yEAAyE;AACzE,eAAO,MAAM,cAAc,IAAM,CAAC;AAClC,iFAAiF;AACjF,eAAO,MAAM,YAAY,IAAM,CAAC;AAChC,0EAA0E;AAC1E,eAAO,MAAM,OAAO,QAA6C,CAAC;AAElE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK5C"}

package/dist/format.js

@@ -3,15 +3,17 @@
  * `Schema#row` / `Schema#rows`. These numbers are part of the C ABI
  * (the C ABI contract §Types and schemas) and MUST NOT be renumbered.
  *
- * Name-addressed: `JSONEachRow`. Positional (the k-th field lands in the k-th
- * insertable column; MATERIALIZED / ALIAS / EPHEMERAL occupy no position):
- * `CSV`, `TSV`, `Values`, `JSONCompactEachRow`, the RowBinary family, and
- * `Buffers`. `Native` is column-oriented and name-addressed.
+ * Name-addressed: `JSONEachRow`, and `CSVWithNames` / `TSVWithNames` through
+ * their header row. Positional (the k-th field lands in the k-th insertable
+ * column; MATERIALIZED / ALIAS / EPHEMERAL occupy no position): `CSV`, `TSV`,
+ * `Values`, `JSONCompactEachRow`, the RowBinary family, and `Buffers`.
+ * `Native` is column-oriented and name-addressed.
  *
- * The RowBinary family, `Native` and `Buffers` depend on when the loaded
- * ARTIFACT was linked, not on this package's version — probe the artifact
- * (feed it one payload) rather than assuming (docs/reference/bindings.md §Values a
- * binding must accept and reject).
+ * The RowBinary family, `Native`, `Buffers`, `CSVWithNames` and
+ * `TSVWithNames` depend on when the loaded ARTIFACT was linked, not on this
+ * package's version — probe the artifact (feed it one payload) rather than
+ * assuming (docs/reference/bindings.md §Values a binding must accept and
+ * reject).
  */
 export const Format = {
     /** One JSON object per line, fields matched to columns by name. */
@@ -59,6 +61,23 @@ export const Format = {
      * package's version.
      */
     Buffers: 9,
+    /**
+     * CSV whose first row is a header naming the columns, so the data is
+     * addressed by NAME. With a column list as well (`columns`), the list decides
+     * the block and the header decides the layout. Header names match EXACTLY
+     * through ClickHouse 26.4 and case-insensitively from 26.5, exactly as those
+     * servers do. It joined `enum chs_format` inside ABI revision 5, so a
+     * revision-5 artifact built before it existed does not know it — the
+     * revision check cannot tell. Probe it, do not assume it from this package's
+     * version.
+     */
+    CSVWithNames: 10,
+    /**
+     * TSV whose first row is a header naming the columns. Everything
+     * `CSVWithNames` says about the header, a column list, header matching and
+     * probing the artifact applies unchanged.
+     */
+    TSVWithNames: 11,
 };
 /**
  * The `chs_rows` export sentinel: no export requested (`CHS_EXPORT_NONE`,

package/dist/format.js.map

@@ -1 +1 @@
-{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,mEAAmE;IACnE,WAAW,EAAE,CAAC;IACd,yEAAyE;IACzE,GAAG,EAAE,CAAC;IACN,qHAAqH;IACrH,GAAG,EAAE,CAAC;IACN,iDAAiD;IACjD,MAAM,EAAE,CAAC;IACT,2CAA2C;IAC3C,kBAAkB,EAAE,CAAC;IACrB,8EAA8E;IAC9E,SAAS,EAAE,CAAC;IACZ,yEAAyE;IACzE,qBAAqB,EAAE,CAAC;IACxB;;;;OAIG;IACH,qCAAqC,EAAE,CAAC;IACxC;;;;;;;OAOG;IACH,MAAM,EAAE,CAAC;IACT;;;;;;;;;;;;;;OAcG;IACH,OAAO,EAAE,CAAC;CACF,CAAC;AAKX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,CAAC;AAE9B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,CAAC;AAC9B,yEAAyE;AACzE,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAClC,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAChC,0EAA0E;AAC1E,MAAM,CAAC,MAAM,OAAO,GAAG,UAAU,GAAG,cAAc,GAAG,YAAY,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,IAAI,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;IAC9B,CAAC;IACD,OAAO,UAAU,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;AAChC,CAAC"}
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,mEAAmE;IACnE,WAAW,EAAE,CAAC;IACd,yEAAyE;IACzE,GAAG,EAAE,CAAC;IACN,qHAAqH;IACrH,GAAG,EAAE,CAAC;IACN,iDAAiD;IACjD,MAAM,EAAE,CAAC;IACT,2CAA2C;IAC3C,kBAAkB,EAAE,CAAC;IACrB,8EAA8E;IAC9E,SAAS,EAAE,CAAC;IACZ,yEAAyE;IACzE,qBAAqB,EAAE,CAAC;IACxB;;;;OAIG;IACH,qCAAqC,EAAE,CAAC;IACxC;;;;;;;OAOG;IACH,MAAM,EAAE,CAAC;IACT;;;;;;;;;;;;;;OAcG;IACH,OAAO,EAAE,CAAC;IACV;;;;;;;;;OASG;IACH,YAAY,EAAE,EAAE;IAChB;;;;OAIG;IACH,YAAY,EAAE,EAAE;CACR,CAAC;AAKX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,CAAC;AAE9B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,CAAC;AAC9B,yEAAyE;AACzE,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAClC,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAChC,0EAA0E;AAC1E,MAAM,CAAC,MAAM,OAAO,GAAG,UAAU,GAAG,cAAc,GAAG,YAAY,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,IAAI,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;IAC9B,CAAC;IACD,OAAO,UAAU,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;AAChC,CAAC"}

package/dist/index.d.ts

@@ -11,7 +11,7 @@
  * vendored per release behind the frozen `chs_*` C ABI. The one derived answer is
  * `transformed`, and it is the reason the product exists.
  */
-export { parseChangedSettingsResult, parseColumnsResult, parseVersionResult, QUERY_CHANGED_SETTINGS, QUERY_SERVER_VERSION, QUERY_TABLE_COLUMNS, reconstructDdl, type DiscoveredColumn, type ServerProfile, } from './discover.js';
+export { parseChangedSettingsResult, parseColumnsResult, parseVersionResult, QUERY_CHANGED_SETTINGS, QUERY_SERVER_VERSION, QUERY_TABLE_COLUMNS, type DiscoveredColumn, type ServerProfile, } from './discover.js';
 export { ABI_REVISION, ArtifactCorruptError, ArtifactError, ArtifactMissingError, ArtifactPinnedError, ArtifactUnpublishedError, ArtifactUntrustedError, artifactMissingMessage, ChtypesError, CODE_ARTIFACT_CORRUPT, CODE_ARTIFACT_MISSING, CODE_ARTIFACT_PINNED, CODE_ARTIFACT_UNPUBLISHED, CODE_ARTIFACT_UNTRUSTED, CODE_SOURCE_UNREACHABLE, CODE_UNSUPPORTED, FETCH_COMMAND, FetchError, RegistryError, SchemaError, SourceUnreachableError, UnsupportedError, type ArtifactErrorCode, } from './errors.js';
 export { compareVersions, DEFAULT_ARTIFACTS_URL, DEFAULT_LOCK_FILE, DEFAULT_RELEASE_TAG, ensure, ensureAll, keyId, listArtifacts, LOCK_SCHEMA, parseSignatureFile, parseVersionSpelling, readLock, RELEASE_KEY_ID, RELEASE_PUBLIC_KEYS, resolvePlatform, selectAll, selectArtifact, sha256File, trustedKeys, verifyEd25519, verifyInstalled, type EnsureOptions, type EnsureResult, type FetchEvent, type IndexArtifact, type InstalledArtifact, type ListResult, type LockEntry, type LockFile, type ReleaseIndex, type VersionRequest, } from './fetch.js';
 export { cacheRegistryDir, ENV_AUTOFETCH, ENV_REGISTRY, fetchDestination, hostPlatform, isPlatformKey, registrySearchPath, systemRegistryDirs, } from './paths.js';
@@ -20,8 +20,8 @@ export { DOC_ALL, DOC_DEFAULTS, DOC_TRANSFORMS, DOC_VALUES, EXPORT_NONE, Format,
 export { CompileMode, Library, minorOf, type CompileOptions } from './library.js';
 export { nativeStats } from './ffi.js';
 export { compareMinor, defaultRegistryDir, looksLikeRegistry, Registry, resolveRegistryDir, type Manifest, type RegistryOptions, } from './registry.js';
-export { DefaultKind, FilterOutcome, isAnswer, Outcome, Verdict, type BatchResult, type ColumnDoc, type Computed, type FilterResult, type FilterRowError, type RowResult, type Span, type Substitution, type Transform, type Value, } from './results.js';
-export { Block, Filter, Schema, type ColumnInfo, type CompileFilterOptions, type EngineOptions, type RowsOptions, } from './schema.js';
+export { DefaultKind, FilterOutcome, isAnswer, Outcome, Source, Verdict, type BatchResult, type ColumnDoc, type Computed, type FilterResult, type FilterRowError, type RowResult, type Span, type Substitution, type Transform, type Value, } from './results.js';
+export { Block, Filter, Schema, type ColumnInfo, type CompileFilterOptions, type EngineOptions, type RowOptions, type RowsOptions, } from './schema.js';
 export { encodeSettings, type Settings, type SettingValue } from './settings.js';
 export { isLossyReason, Reason } from './transform.js';
 export { isValidUtf8, Json, parseDocument, parseJsonValue, rawBytes, rawText, repairBareDenormals, type JsonKind, } from './json.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

@@ -11,7 +11,7 @@
  * vendored per release behind the frozen `chs_*` C ABI. The one derived answer is
  * `transformed`, and it is the reason the product exists.
  */
-export { parseChangedSettingsResult, parseColumnsResult, parseVersionResult, QUERY_CHANGED_SETTINGS, QUERY_SERVER_VERSION, QUERY_TABLE_COLUMNS, reconstructDdl, } from './discover.js';
+export { parseChangedSettingsResult, parseColumnsResult, parseVersionResult, QUERY_CHANGED_SETTINGS, QUERY_SERVER_VERSION, QUERY_TABLE_COLUMNS, } from './discover.js';
 export { ABI_REVISION, ArtifactCorruptError, ArtifactError, ArtifactMissingError, ArtifactPinnedError, ArtifactUnpublishedError, ArtifactUntrustedError, artifactMissingMessage, ChtypesError, CODE_ARTIFACT_CORRUPT, CODE_ARTIFACT_MISSING, CODE_ARTIFACT_PINNED, CODE_ARTIFACT_UNPUBLISHED, CODE_ARTIFACT_UNTRUSTED, CODE_SOURCE_UNREACHABLE, CODE_UNSUPPORTED, FETCH_COMMAND, FetchError, RegistryError, SchemaError, SourceUnreachableError, UnsupportedError, } from './errors.js';
 export { compareVersions, DEFAULT_ARTIFACTS_URL, DEFAULT_LOCK_FILE, DEFAULT_RELEASE_TAG, ensure, ensureAll, keyId, listArtifacts, LOCK_SCHEMA, parseSignatureFile, parseVersionSpelling, readLock, RELEASE_KEY_ID, RELEASE_PUBLIC_KEYS, resolvePlatform, selectAll, selectArtifact, sha256File, trustedKeys, verifyEd25519, verifyInstalled, } from './fetch.js';
 export { cacheRegistryDir, ENV_AUTOFETCH, ENV_REGISTRY, fetchDestination, hostPlatform, isPlatformKey, registrySearchPath, systemRegistryDirs, } from './paths.js';
@@ -20,7 +20,7 @@ export { DOC_ALL, DOC_DEFAULTS, DOC_TRANSFORMS, DOC_VALUES, EXPORT_NONE, Format,
 export { CompileMode, Library, minorOf } from './library.js';
 export { nativeStats } from './ffi.js';
 export { compareMinor, defaultRegistryDir, looksLikeRegistry, Registry, resolveRegistryDir, } from './registry.js';
-export { DefaultKind, FilterOutcome, isAnswer, Outcome, Verdict, } from './results.js';
+export { DefaultKind, FilterOutcome, isAnswer, Outcome, Source, Verdict, } from './results.js';
 export { Block, Filter, Schema, } from './schema.js';
 export { encodeSettings } from './settings.js';
 export { isLossyReason, Reason } from './transform.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,GAGf,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,YAAY,EACZ,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,aAAa,EACb,WAAW,EACX,sBAAsB,EACtB,gBAAgB,GAEjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,SAAS,EACT,cAAc,EACd,UAAU,EACV,WAAW,EACX,aAAa,EACb,eAAe,GAWhB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAuB,MAAM,UAAU,CAAC;AAC7D,OAAO,EACL,OAAO,EACP,YAAY,EACZ,cAAc,EACd,UAAU,EACV,WAAW,EACX,MAAM,EACN,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAuB,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,kBAAkB,GAGnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,WAAW,EACX,aAAa,EACb,QAAQ,EACR,OAAO,EACP,OAAO,GAWR,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,EACL,MAAM,EACN,MAAM,GAKP,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAoC,MAAM,eAAe,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EACL,WAAW,EACX,IAAI,EACJ,aAAa,EACb,cAAc,EACd,QAAQ,EACR,OAAO,EACP,mBAAmB,GAEpB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,GAGpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,YAAY,EACZ,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,aAAa,EACb,WAAW,EACX,sBAAsB,EACtB,gBAAgB,GAEjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,SAAS,EACT,cAAc,EACd,UAAU,EACV,WAAW,EACX,aAAa,EACb,eAAe,GAWhB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAuB,MAAM,UAAU,CAAC;AAC7D,OAAO,EACL,OAAO,EACP,YAAY,EACZ,cAAc,EACd,UAAU,EACV,WAAW,EACX,MAAM,EACN,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAuB,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,kBAAkB,GAGnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,WAAW,EACX,aAAa,EACb,QAAQ,EACR,OAAO,EACP,MAAM,EACN,OAAO,GAWR,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,EACL,MAAM,EACN,MAAM,GAMP,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAoC,MAAM,eAAe,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EACL,WAAW,EACX,IAAI,EACJ,aAAa,EACb,cAAc,EACd,QAAQ,EACR,OAAO,EACP,mBAAmB,GAEpB,MAAM,WAAW,CAAC"}

package/dist/library.d.ts

@@ -2,6 +2,7 @@
  * One loaded ClickHouse build. It names itself — `chs_clickhouse_version()` —
  * and nothing is ever inferred from the directory or the file name.
  */
+import { type DiscoveredColumn } from './discover.js';
 import type { NativeLibrary } from './ffi.js';
 import { Schema } from './schema.js';
 import { type Settings } from './settings.js';
@@ -128,8 +129,10 @@ export declare class Library {
      *   unknown setting name in `options.settings` carries the server's own 115
      *   (with its did-you-mean hint), and nothing is compiled; a type gate
      *   declared at a refusing value fails with the server's own 455/44, exactly
-     *   as that server's CREATE; an Enum DEFAULT outside the declared domain is
-     *   691 (schema-level poisoning, refused on every version by design).
+     *   as that server's CREATE; an Enum DEFAULT outside the declared domain
+     *   follows that server's CREATE too — 691 (or 70 for an out-of-range
+     *   literal) where it refuses the table (26.x); on 24.8–25.10 it compiles,
+     *   and a row relying on the default answers `accepted_poisoned`.
      * @throws {UnsupportedError} when this build DECLINES rather than guesses —
      *   a `mode` other than `CompileMode.Declared`, or a DEFAULT it refuses to
      *   evaluate (server-property functions like `hostName()`, `sleep`, an
@@ -185,6 +188,66 @@ export declare class Library {
      * @throws {UnsupportedError} when the artifact predates `chs_reference_type`.
      */
     referenceType(typeExpr: string): string;
+    /**
+     * Spell `name` as a back-quoted identifier — ALWAYS quoted, which is the
+     * safe default and the one to reach for without thinking
+     * (`chs_quote_identifier`, the vendored `backQuote`).
+     *
+     * The bytes are this library's own: an embedded back-quote comes back in the
+     * spelling the server's formatter prints, not in a spelling of ours. Reach
+     * for `quoteIdentifierIfNeeded` only when the bare spelling matters to
+     * something downstream.
+     *
+     * @param name - a table, column or alias name.
+     * @returns the quoted identifier.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_quote_identifier`.
+     */
+    quoteIdentifier(name: string): string;
+    /**
+     * Spell `name` bare where THIS library's ClickHouse says a bare spelling is
+     * legal, and back-quote it otherwise (`chs_quote_identifier_if_needed`, the
+     * vendored `backQuoteIfNeed`).
+     *
+     * Which names it leaves bare is a property of the vendored build, not of
+     * this package, and it CHANGES between builds — ask the library you will
+     * compile against rather than caching an answer across versions.
+     *
+     * @param name - a table, column or alias name.
+     * @returns the identifier, bare or quoted.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_quote_identifier_if_needed`.
+     */
+    quoteIdentifierIfNeeded(name: string): string;
+    /**
+     * Spell `text` as a ClickHouse string literal, quotes and escapes included
+     * (`chs_quote_literal`, the vendored `quoteString`) — the call to reach for
+     * when a value is spliced into DDL, e.g. a DEFAULT expression.
+     *
+     * The input is counted, so a value carrying a NUL byte is quoted correctly;
+     * the answer is escaped and therefore NUL-free.
+     *
+     * @param text - the string value.
+     * @returns the ClickHouse string literal.
+     * @throws {UnsupportedError} when the artifact predates `chs_quote_literal`.
+     */
+    quoteLiteral(text: string): string;
+    private quote;
+    /**
+     * Turn `QUERY_TABLE_COLUMNS`' rows back into the column-declaration list
+     * `compileDdl` takes.
+     *
+     * It hangs off a Library because the one thing it spells — the column NAME —
+     * is spelled by this library's own `quoteIdentifier`; see `discover.ts` for
+     * what reconstruction does and does not promise.
+     *
+     * @param cols - the discovered columns, e.g. from `parseColumnsResult`.
+     * @returns the column-declaration list for `compileDdl`.
+     * @throws {ChtypesError} when a column is inconsistent, or there are none.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_quote_identifier`.
+     */
+    reconstructDdl(cols: readonly DiscoveredColumn[]): string;
     /**
      * Every type family in this build's own runtime registry (139 entries on
      * 25.8) — the answer to "does this build track upstream type families?"
@@ -202,7 +265,7 @@ export declare class Library {
      * tab-separated fields — `name`, `deterministic`, `deterministic_in_query`,
      * `server_constant`, `stateful`, `resolver_error_code`. ClickHouse's own
      * answers off this build's own registry, and the input to the statelessness
-     * gate (`lib/tools/gen_function_flags.py`). Part of the three-question
+     * gate (the build's function-flags generator). Part of the three-question
      * introspection surface every SDK exposes (docs/reference/bindings.md
      * §Introspection).
      *

package/dist/library.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"library.d.ts","sourceRoot":"","sources":["../src/library.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW;IACtB;;;;;;;OAOG;aACH,QAAQ,EAAE,CAAC;CACH,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACzC;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,OAAO;IAgBN,OAAO,CAAC,QAAQ,CAAC,MAAM;IAfnC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,8CAA8C;IAC9C,YAA6B,MAAM,EAAE,aAAa,EAKjD;IAED;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIrC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CAIxD;IAED;;;;;;;;OAQG;IACH,kBAAkB,IAAI,OAAO,CAE5B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAE3C;IAED;;;;;;;;;;OAUG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtC;IAED;;;;;;;;;OASG;IACH,kBAAkB,IAAI,MAAM,EAAE,CAE7B;IAED;;;;;;;;;;;;;OAaG;IACH,aAAa,IAAI,MAAM,CAEtB;IAED;;;;;;;;OAQG;IACH,QAAQ,IAAI,IAAI,CAEf;CACF"}
+{"version":3,"file":"library.d.ts","sourceRoot":"","sources":["../src/library.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW;IACtB;;;;;;;OAOG;aACH,QAAQ,EAAE,CAAC;CACH,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACzC;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,OAAO;IAgBN,OAAO,CAAC,QAAQ,CAAC,MAAM;IAfnC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,8CAA8C;IAC9C,YAA6B,MAAM,EAAE,aAAa,EAKjD;IAED;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIrC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CAIxD;IAED;;;;;;;;OAQG;IACH,kBAAkB,IAAI,OAAO,CAE5B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAE3C;IAED;;;;;;;;;;OAUG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtC;IAED;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpC;IAED;;;;;;;;;;;;;OAaG;IACH,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;IAED;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjC;IAED,OAAO,CAAC,KAAK;IASb;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,IAAI,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,CAExD;IAED;;;;;;;;;OASG;IACH,kBAAkB,IAAI,MAAM,EAAE,CAE7B;IAED;;;;;;;;;;;;;OAaG;IACH,aAAa,IAAI,MAAM,CAEtB;IAED;;;;;;;;OAQG;IACH,QAAQ,IAAI,IAAI,CAEf;CACF"}

package/dist/library.js

@@ -2,6 +2,7 @@
  * One loaded ClickHouse build. It names itself — `chs_clickhouse_version()` —
  * and nothing is ever inferred from the directory or the file name.
  */
+import { reconstructDdlWith } from './discover.js';
 import { schemaErrorFor } from './errors.js';
 import { Schema } from './schema.js';
 import { encodeSettings } from './settings.js';
@@ -121,8 +122,10 @@ export class Library {
      *   unknown setting name in `options.settings` carries the server's own 115
      *   (with its did-you-mean hint), and nothing is compiled; a type gate
      *   declared at a refusing value fails with the server's own 455/44, exactly
-     *   as that server's CREATE; an Enum DEFAULT outside the declared domain is
-     *   691 (schema-level poisoning, refused on every version by design).
+     *   as that server's CREATE; an Enum DEFAULT outside the declared domain
+     *   follows that server's CREATE too — 691 (or 70 for an out-of-range
+     *   literal) where it refuses the table (26.x); on 24.8–25.10 it compiles,
+     *   and a row relying on the default answers `accepted_poisoned`.
      * @throws {UnsupportedError} when this build DECLINES rather than guesses —
      *   a `mode` other than `CompileMode.Declared`, or a DEFAULT it refuses to
      *   evaluate (server-property functions like `hostName()`, `sleep`, an
@@ -188,6 +191,79 @@ export class Library {
     referenceType(typeExpr) {
         return this.native.referenceType(typeExpr);
     }
+    /**
+     * Spell `name` as a back-quoted identifier — ALWAYS quoted, which is the
+     * safe default and the one to reach for without thinking
+     * (`chs_quote_identifier`, the vendored `backQuote`).
+     *
+     * The bytes are this library's own: an embedded back-quote comes back in the
+     * spelling the server's formatter prints, not in a spelling of ours. Reach
+     * for `quoteIdentifierIfNeeded` only when the bare spelling matters to
+     * something downstream.
+     *
+     * @param name - a table, column or alias name.
+     * @returns the quoted identifier.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_quote_identifier`.
+     */
+    quoteIdentifier(name) {
+        return this.quote('chs_quote_identifier', name);
+    }
+    /**
+     * Spell `name` bare where THIS library's ClickHouse says a bare spelling is
+     * legal, and back-quote it otherwise (`chs_quote_identifier_if_needed`, the
+     * vendored `backQuoteIfNeed`).
+     *
+     * Which names it leaves bare is a property of the vendored build, not of
+     * this package, and it CHANGES between builds — ask the library you will
+     * compile against rather than caching an answer across versions.
+     *
+     * @param name - a table, column or alias name.
+     * @returns the identifier, bare or quoted.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_quote_identifier_if_needed`.
+     */
+    quoteIdentifierIfNeeded(name) {
+        return this.quote('chs_quote_identifier_if_needed', name);
+    }
+    /**
+     * Spell `text` as a ClickHouse string literal, quotes and escapes included
+     * (`chs_quote_literal`, the vendored `quoteString`) — the call to reach for
+     * when a value is spliced into DDL, e.g. a DEFAULT expression.
+     *
+     * The input is counted, so a value carrying a NUL byte is quoted correctly;
+     * the answer is escaped and therefore NUL-free.
+     *
+     * @param text - the string value.
+     * @returns the ClickHouse string literal.
+     * @throws {UnsupportedError} when the artifact predates `chs_quote_literal`.
+     */
+    quoteLiteral(text) {
+        return this.quote('chs_quote_literal', text);
+    }
+    quote(symbol, text) {
+        const r = this.native.quote(symbol, text);
+        if (!r.ok)
+            throw schemaErrorFor(r.code, r.message || `${symbol} refused the input`);
+        return r.quoted;
+    }
+    /**
+     * Turn `QUERY_TABLE_COLUMNS`' rows back into the column-declaration list
+     * `compileDdl` takes.
+     *
+     * It hangs off a Library because the one thing it spells — the column NAME —
+     * is spelled by this library's own `quoteIdentifier`; see `discover.ts` for
+     * what reconstruction does and does not promise.
+     *
+     * @param cols - the discovered columns, e.g. from `parseColumnsResult`.
+     * @returns the column-declaration list for `compileDdl`.
+     * @throws {ChtypesError} when a column is inconsistent, or there are none.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_quote_identifier`.
+     */
+    reconstructDdl(cols) {
+        return reconstructDdlWith(cols, (name) => this.quoteIdentifier(name));
+    }
     /**
      * Every type family in this build's own runtime registry (139 entries on
      * 25.8) — the answer to "does this build track upstream type families?"
@@ -207,7 +283,7 @@ export class Library {
      * tab-separated fields — `name`, `deterministic`, `deterministic_in_query`,
      * `server_constant`, `stateful`, `resolver_error_code`. ClickHouse's own
      * answers off this build's own registry, and the input to the statelessness
-     * gate (`lib/tools/gen_function_flags.py`). Part of the three-question
+     * gate (the build's function-flags generator). Part of the three-question
      * introspection surface every SDK exposes (docs/reference/bindings.md
      * §Introspection).
      *

package/dist/library.js.map

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

package/dist/registry.d.ts

@@ -20,11 +20,10 @@
  *
  * Where a registry IS follows the search path of docs/guides/fetch.md §1 (`paths.ts`):
  * the explicit directory, `CHTYPES_REGISTRY`, the per-user cache, then the
- * reserved system locations. The first directory holding artifacts is scanned
- * and loaded at construction; a line it lacks is taken, on request, from the
- * first later directory that has it. A line no directory has is the one §7
- * error, `ArtifactMissingError` — or, with `autofetch`, a fetch on first
- * `open()`.
+ * reserved system locations. Construction READS THE MANIFESTS on that path and
+ * `dlopen`s nothing; a line is taken, on request, from the first directory that
+ * has it. A line no directory has is the one §7 error,
+ * `ArtifactMissingError` — or, with `autofetch`, a fetch on first `open()`.
  */
 import { type EnsureOptions } from './fetch.js';
 import { Library } from './library.js';
@@ -52,8 +51,40 @@ export interface RegistryOptions {
      * Re-hash each library and compare against `manifest.library_sha256` before
      * loading. SHOULD be on for an artifact that came from anywhere but a local
      * build, and MUST be on for one that came over a network.
+     *
+     * A policy on the REGISTRY, not a property of `preload`: a library's
+     * checksum is computed immediately before that library is `dlopen`ed and at
+     * no other time — at construction for the preloaded lines, at first use for
+     * the rest, never for a line nobody asks for.
+     *
+     * What this option ADDS is the sha256 comparison. The cheaper
+     * `manifest.library_bytes` size check that runs just before it is NOT
+     * conditional on this option — `load()` below always makes it, on every
+     * open, regardless (issue #82). Its timing is the same as the checksum's:
+     * at construction for the preloaded lines, at first use for the rest.
      */
     verifyChecksums?: boolean;
+    /**
+     * Open these lines AT CONSTRUCTION — the one eager path, and the same option
+     * Go spells `WithPreload(...)`, Python `preload=[...]` and Rust
+     * `RegistryOptions::preload`.
+     *
+     * Each entry is a version spelling resolved exactly as `for()` resolves one:
+     * a minor line (`'25.8'`) or an exact patch (`'25.8.28.1-lts'`), never a
+     * path. They are opened in the order given, before the constructor returns,
+     * and an entry no directory on the §1 search path holds is
+     * `ArtifactMissingError` — the same §7 error the first `for()` would have
+     * thrown, thrown earlier.
+     *
+     * It NEVER fetches, even with `autofetch` on: this constructor is
+     * synchronous and `ensure()` is not, and autofetch is a first-use behavior
+     * in all four bindings. An empty list is exactly the default.
+     *
+     * Deliberately a list of lines rather than "everything in the directory": a
+     * registry directory is whatever a fetch left behind, and each open costs
+     * about 120 MB resident.
+     */
+    preload?: readonly string[] | undefined;
     /**
      * Lazy fetch on first open (docs/guides/fetch.md §6): `open()` of a line no
      * directory on the search path holds runs `ensure()` first, into the
@@ -68,13 +99,20 @@ export interface RegistryOptions {
 }
 /**
  * The artifact-directory loader — the multi-version entry point of this
- * package. Construction scans one subdirectory per ClickHouse version, dlopens
- * each artifact into its own symbol scope (`RTLD_LOCAL`, ~120 MB resident per
- * version), verifies its ABI revision against this binding's `ABI_REVISION`
- * (a different nonzero revision is refused; 0 means the artifact predates the
- * probe and degrades per symbol), and runs each library's one-time
- * `chs_init` with the UTC default timezone and the artifact's own
- * `unsafe_families.txt`.
+ * package.
+ *
+ * **Construction reads `manifest.json` files and `dlopen`s nothing**, with or
+ * without a directory. Nothing in this package opens an artifact except a
+ * request for a specific version (`for()` / `open()`) or an explicit
+ * `preload` — not `versions()`, not `libraries()`, not `has()`. An open costs
+ * about 120 MB resident per version, which a listing call must not spend on a
+ * caller's behalf.
+ *
+ * An open dlopens the artifact into its own symbol scope (`RTLD_LOCAL`),
+ * verifies its ABI revision against this binding's `ABI_REVISION` (a different
+ * nonzero revision is refused; 0 means the artifact predates the probe and
+ * degrades per symbol), and runs that library's one-time `chs_init` with the
+ * registry's timezone and the artifact's own `unsafe_families.txt`.
  *
  * Libraries are never dlclosed; `close()` joins background threads only.
  * Loading the same artifact path from two `Registry` instances shares one
@@ -82,9 +120,9 @@ export interface RegistryOptions {
  */
 export declare class Registry {
     /**
-     * The primary registry directory: the first on the search path that held
-     * artifacts, scanned and loaded at construction — or, with `autofetch` and
-     * nothing installed anywhere, the directory the first fetch will create.
+     * The primary registry directory: the first on the search path that holds
+     * artifacts — or, with `autofetch` and nothing installed anywhere, the
+     * directory the first fetch will create.
      */
     readonly dir: string;
     /** The §1 search path, in order, every candidate whether or not it exists. */
@@ -94,47 +132,88 @@ export declare class Registry {
     private readonly byId;
     private readonly byPath;
     private readonly loaded;
+    /**
+     * Minor line -> the FIRST directory on the search path that holds it, as the
+     * construction-time manifest scan found it. What `versions()` answers from,
+     * and what makes "no artifact anywhere" and a bad `preload` entry decidable
+     * at construction without a single `dlopen`.
+     */
+    private readonly known;
     private readonly timezone;
     private readonly verifyChecksums;
     private readonly autofetch;
     private readonly fetchOptions;
     private readonly explicit;
     /**
-     * Scan and load a registry.
+     * Scan a registry. Reads manifests; opens nothing unless `preload` names a
+     * line.
      *
      * @param dir - the registry root; the head of the search path. Absent, the
      *   path is `CHTYPES_REGISTRY`, the per-user artifact cache, then the system
      *   locations (see `registrySearchPath` / `defaultRegistryDir`).
-     * @param options - timezone, checksum verification, autofetch — see `RegistryOptions`.
-     * @throws {RegistryError} when a directory named explicitly (the argument or
-     *   `CHTYPES_REGISTRY`) does not exist and autofetch is off, when no
-     *   directory on the search path holds an artifact (and autofetch is off),
-     *   the primary directory cannot be read, an artifact fails its checksum,
-     *   fails to load, or reports a ClickHouse version different from its
-     *   manifest's.
+     * @param options - timezone, checksum verification, autofetch, preload — see
+     *   `RegistryOptions`.
+     * @throws {RegistryError} for what manifests can decide, and only that: a
+     *   directory named explicitly (the argument or `CHTYPES_REGISTRY`) that does
+     *   not exist, and no directory on the search path holding a readable
+     *   `<minor>/manifest.json` — both suppressed when autofetch is on. A
+     *   `preload` entry no directory holds is `ArtifactMissingError`. Everything
+     *   a bad artifact can be wrong about — a failed checksum, a load failure, a
+     *   library whose ClickHouse version disagrees with its manifest — is
+     *   reported by the call that opens it, which is `preload`'s open at
+     *   construction or the first `for()` otherwise.
      * @throws {ChtypesError} when an artifact reports a different nonzero ABI
      *   revision than this binding speaks, or `chs_init` fails (e.g. an unknown
-     *   timezone — the message names it).
+     *   timezone — the message names it); again, from the call that opens it.
      */
     constructor(dir?: string, options?: RegistryOptions);
+    /**
+     * Open one `preload` entry, before the constructor returns, without
+     * fetching. Resolution is `for()`'s, and so is the failure: a line no
+     * directory holds is the same `ArtifactMissingError`, raised earlier.
+     */
+    private preloadLine;
     /** dlopen one artifact directory, cross-check it, `chs_init` it, index it. */
     private load;
     /** Load `<dir>/<minor>/` if it is an artifact directory; null when it is not. */
     private loadLine;
     private lookup;
-    /** The ClickHouse minor lines this registry has loaded, oldest first. */
+    /**
+     * Resolve without fetching: what is already open, then the line's directory
+     * as the construction-time scan recorded it, then a fresh walk of the search
+     * path for a line installed since. `undefined` means no directory holds it,
+     * which is a fetch's cue on `open()` and the §7 error everywhere else —
+     * `preload` never fetches, and this is the one function that makes the
+     * preload path and the first-use path identical in everything else.
+     */
+    private resolve;
+    /**
+     * Every ClickHouse minor line this registry CAN ANSWER FOR, oldest first —
+     * the ones it has opened plus the ones its construction-time manifest scan
+     * discovered on the search path.
+     *
+     * That is one meaning in all four bindings, and it is the meaning that
+     * survives lazy loading: "the lines that happen to be open" would read as an
+     * empty registry until the first `for()`. It opens nothing.
+     */
     versions(): string[];
-    /** Every loaded library, in release order (oldest minor line first). */
+    /**
+     * The libraries this registry has OPENED, in release order (oldest minor
+     * line first) — what is open right now, never what could be. A discovered
+     * line that no `for()` and no `preload` has opened appears in `versions()`
+     * and not here. It opens nothing.
+     */
     libraries(): readonly Library[];
     /**
      * Resolve a version to its library. A minor line ("25.8") or an exact patch
      * ("25.8.28.1-lts") both work, and an unknown patch inside a loaded minor line
      * resolves to that line — asking for "25.8.30.16" finds the loaded 25.8.
      *
-     * A line the primary directory lacks is loaded from the first later
-     * directory on the search path that holds it (docs/guides/fetch.md §1), and joins
-     * `versions()` / `libraries()` from then on. Never a fetch: this call is
-     * synchronous; `open()` is the one that may fetch.
+     * **This is what opens an artifact.** Construction does not: the line is
+     * taken from the first directory on the search path that holds it
+     * (docs/guides/fetch.md §1), `dlopen`ed once, and joins `libraries()` from
+     * then on. Never a fetch: this call is synchronous; `open()` is the one that
+     * may fetch.
      *
      * Failure is the one §7 error, never a fallback to the nearest version:
      * answering 26.7 semantics from a 25.8 artifact is a lie, and silent