@wavehouse/chtypes 0.5.2 → 1.0.0

package/dist/abi1/libc.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The TS loader's trap and its fix (plan §3.3, "THE TS TRAP").
+ *
+ * ffi-rs opens a library through libloading with `RTLD_LAZY | RTLD_LOCAL`
+ * (measured: v0 `ts/src/registry.ts`'s own header comment states this of
+ * ffi-rs 1.3.7, and nothing in ffi-rs's public API — `open`, `define`,
+ * `load` — takes a dlopen mode flag). `RTLD_LAZY` defers symbol binding
+ * until first use, so a library with an UNRESOLVED external symbol (the
+ * `unbound` stub variant) would `dlopen` successfully under ffi-rs and only
+ * fail later, if ever, when something actually calls the missing function —
+ * which step 2 of the loader (D3/§3.2) requires NEVER happen: a v1 loader
+ * must refuse an artifact that cannot bind completely, at open time.
+ *
+ * The fix: do the REAL `dlopen(path, RTLD_NOW | RTLD_LOCAL)` ourselves,
+ * through libc directly, before ffi-rs ever touches the path. `RTLD_NOW`
+ * binds every relocation immediately, so `unbound` fails exactly where it
+ * must.
+ *
+ * This file is HAND-WRITTEN and declares nothing itself: the actual libc
+ * declarations and the symbol-lookup primitive live in the GENERATED
+ * `./libc.gen.ts` (scripts/abi-v1/emit/ts.py — see its module docstring).
+ * That split is the lead's 2026-10-02 ruling: check-no-hand-decls.py's
+ * `dlsym(` rule exists so every raw symbol lookup lives in generated code,
+ * exempt by construction, rather than being worked around in a hand file
+ * with a renamed table key or a call site shaped to dodge the text match.
+ * This file calls the generated exports only, by their own names.
+ */
+import { type JsExternal } from 'ffi-rs';
+export declare const RTLD_NOW_LOCAL: number;
+/** A NUL-terminated, ASCII/UTF-8-safe C string at `ptr`, read via the generated `cStringLength` (strlen) + a zero-copy view. Never call this on a pointer that may carry non-UTF-8 or embedded-NUL bytes (an ABI document body): it is for libc's own always-ASCII strings and `chs_build_info`'s guaranteed-ASCII, NUL-terminated JSON only. */
+declare function readCString(ptr: JsExternal): string;
+/** `dlopen(path, RTLD_NOW | RTLD_LOCAL)` through the generated primitive (plan §3.3(b)). Returns the raw OS handle, or null on failure — call `lastDlError()` immediately after a null to get libc's own message, before any other libc call. */
+export declare function rawDlopen(path: string): JsExternal | null;
+/** The loader's symbol-presence check (plan §3.3(c)), through the generated `resolveSymbol` helper: the raw symbol address, or null if `name` is not exported by `handle`'s image (this file never calls through the returned pointer — only ffi-rs's own by-name `define`/`load`, on an already-opened path, does that). */
+export declare function rawDlsym(handle: JsExternal, name: string): JsExternal | null;
+/** libc's own diagnostic for the most recent failing open/resolve call, read ONCE (POSIX clears it on read) and only ever called right after that failure. */
+export declare function lastDlError(): string;
+/**
+ * The glibc version string (`gnu_get_libc_version()`), or null when the
+ * symbol is absent — which means this is musl, not glibc (plan step 1:
+ * "Absent → musl → refuse"). Linux only; a caller on darwin never calls
+ * this (step 1 is a no-op there).
+ */
+export declare function glibcVersionString(): string | null;
+/**
+ * Dotted-integer version comparison (`"2.29"` vs `"2.5"`, never lexical):
+ * negative if `a` < `b`, positive if `a` > `b`, 0 if equal. Missing trailing
+ * components compare as 0 (`"2"` == `"2.0"`).
+ */
+export declare function compareDottedVersions(a: string, b: string): number;
+/** Open the target library's path through ffi-rs, under `libraryKey`, for typed calls (plan §3.3(d)). A harmless re-open when `path` is already the image our own `rawDlopen` just bound: dlopen (and the libloading ffi-rs uses underneath) dedupes by canonical path, returning the same already-mapped, already-bound image rather than re-relocating it. Declares no symbol of its own — `open()` only registers a path under a key for a later `define()` — so it is unaffected by the generated/hand-written split above. */
+export declare function ffiOpen(libraryKey: string, path: string): void;
+export { readCString };
+//# sourceMappingURL=libc.d.ts.map

package/dist/abi1/libc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"libc.d.ts","sourceRoot":"","sources":["../../src/abi1/libc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAwB,KAAK,UAAU,EAAQ,MAAM,QAAQ,CAAC;AAwBrE,eAAO,MAAM,cAAc,QAAwB,CAAC;AAEpD,iVAAiV;AACjV,iBAAS,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAI5C;AAED,iPAAiP;AACjP,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAEzD;AAED,6TAA6T;AAC7T,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAE5E;AAED,8JAA8J;AAC9J,wBAAgB,WAAW,IAAI,MAAM,CAGpC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAGlD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAWlE;AAED,mgBAAmgB;AACngB,wBAAgB,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAK9D;AAID,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/abi1/libc.gen.d.ts

@@ -0,0 +1,12 @@
+import { type JsExternal } from 'ffi-rs';
+/** dlopen(path, flags) against the process's own libc. Null on failure. */
+export declare function dlopen(path: string, flags: number): JsExternal | null;
+/** THE one symbol-lookup helper: dlsym(handle, name). Null if `name` is not exported by `handle`'s image. */
+export declare function resolveSymbol(handle: JsExternal, name: string): JsExternal | null;
+/** dlerror(). Null if there is no pending error (POSIX clears it on read, so call this ONCE, right after a failure). */
+export declare function dlerror(): JsExternal | null;
+/** gnu_get_libc_version(). Null if the symbol does not resolve at all (musl) or the call itself returns null. */
+export declare function gnuGetLibcVersion(): JsExternal | null;
+/** strlen(ptr): the length of a NUL-terminated C string, for a byte-safe read via createExternalBuffer. */
+export declare function cStringLength(ptr: JsExternal): number;
+//# sourceMappingURL=libc.gen.d.ts.map

package/dist/abi1/libc.gen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"libc.gen.d.ts","sourceRoot":"","sources":["../../src/abi1/libc.gen.ts"],"names":[],"mappings":"AAeA,OAAO,EAAmC,KAAK,UAAU,EAAQ,MAAM,QAAQ,CAAC;AA0ChF,2EAA2E;AAC3E,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAGrE;AAED,6GAA6G;AAC7G,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAGjF;AAED,wHAAwH;AACxH,wBAAgB,OAAO,IAAI,UAAU,GAAG,IAAI,CAG3C;AAED,iHAAiH;AACjH,wBAAgB,iBAAiB,IAAI,UAAU,GAAG,IAAI,CAOrD;AAED,2GAA2G;AAC3G,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAErD"}

package/dist/abi1/libc.gen.js

@@ -0,0 +1,75 @@
+/* GENERATED by scripts/abi-v1/gen.py from spec/abi-v1/abi.json (CHS_ABI_FINGERPRINT sha256:856e5cb7543db291b4db716662bf6e487b2258973b959bbf5d58b4bd46d73285) — DO NOT EDIT */
+/*
+ * The libc primitives ts/src/abi1/libc.ts needs for plan §3.3's TS-trap fix: dlopen,
+ * dlsym, dlerror, gnu_get_libc_version and strlen, declared through ffi-rs's define()
+ * against the PROCESS'S OWN libc, by their real C names. This file carries the generated
+ * banner, so scripts/abi-v1/check-no-hand-decls.py exempts it outright — the check's own
+ * intent (every raw symbol lookup lives in generated code) is satisfied for real here,
+ * never worked around with a renamed key or a disguised call site in a hand file. See
+ * scripts/abi-v1/emit/ts.py's module docstring.
+ *
+ * `resolveSymbol` is THE ONE symbol-lookup helper hand code uses (dlsym plus the null
+ * check); the other four exports are the raw primitives dlopen/dlerror/gnu_get_libc_version/
+ * strlen need, each with its own null handling where the C function can return NULL.
+ */
+import { DataType, define, isNullPointer, open } from 'ffi-rs';
+const { External, I32, U64, String: Str } = DataType;
+const LIBC_KEY = 'chtypes_abi1_libc';
+function libcPath() {
+    if (process.platform === 'darwin')
+        return '/usr/lib/libSystem.B.dylib';
+    if (process.platform === 'linux')
+        return 'libc.so.6';
+    throw new Error(`chtypes abi1: unsupported platform ${process.platform}; only linux and darwin are v1 platforms`);
+}
+let opened = false;
+function ensureOpen() {
+    if (opened)
+        return;
+    open({ library: LIBC_KEY, path: libcPath() });
+    opened = true;
+}
+let fns = null;
+function libc() {
+    ensureOpen();
+    if (fns === null) {
+        fns = define({
+            dlopen: { library: LIBC_KEY, retType: External, paramsType: [Str, I32] },
+            dlsym: { library: LIBC_KEY, retType: External, paramsType: [External, Str] },
+            dlerror: { library: LIBC_KEY, retType: External, paramsType: [] },
+            gnu_get_libc_version: { library: LIBC_KEY, retType: External, paramsType: [] },
+            strlen: { library: LIBC_KEY, retType: U64, paramsType: [External] },
+        });
+    }
+    return fns;
+}
+/** dlopen(path, flags) against the process's own libc. Null on failure. */
+export function dlopen(path, flags) {
+    const h = libc().dlopen([path, flags]);
+    return isNullPointer(h) ? null : h;
+}
+/** THE one symbol-lookup helper: dlsym(handle, name). Null if `name` is not exported by `handle`'s image. */
+export function resolveSymbol(handle, name) {
+    const p = libc().dlsym([handle, name]);
+    return isNullPointer(p) ? null : p;
+}
+/** dlerror(). Null if there is no pending error (POSIX clears it on read, so call this ONCE, right after a failure). */
+export function dlerror() {
+    const p = libc().dlerror([]);
+    return isNullPointer(p) ? null : p;
+}
+/** gnu_get_libc_version(). Null if the symbol does not resolve at all (musl) or the call itself returns null. */
+export function gnuGetLibcVersion() {
+    try {
+        const p = libc().gnu_get_libc_version([]);
+        return isNullPointer(p) ? null : p;
+    }
+    catch {
+        return null;
+    }
+}
+/** strlen(ptr): the length of a NUL-terminated C string, for a byte-safe read via createExternalBuffer. */
+export function cStringLength(ptr) {
+    return Number(libc().strlen([ptr]));
+}
+//# sourceMappingURL=libc.gen.js.map

package/dist/abi1/libc.gen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"libc.gen.js","sourceRoot":"","sources":["../../src/abi1/libc.gen.ts"],"names":[],"mappings":"AAAA,8KAA8K;AAC9K;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAmB,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEhF,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,QAAQ,CAAC;AAErD,MAAM,QAAQ,GAAG,mBAAmB,CAAC;AAErC,SAAS,QAAQ;IACf,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,4BAA4B,CAAC;IACvE,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,WAAW,CAAC;IACrD,MAAM,IAAI,KAAK,CAAC,sCAAsC,OAAO,CAAC,QAAQ,0CAA0C,CAAC,CAAC;AACpH,CAAC;AAED,IAAI,MAAM,GAAG,KAAK,CAAC;AACnB,SAAS,UAAU;IACjB,IAAI,MAAM;QAAE,OAAO;IACnB,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC9C,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC;AAUD,IAAI,GAAG,GAAmB,IAAI,CAAC;AAC/B,SAAS,IAAI;IACX,UAAU,EAAE,CAAC;IACb,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,GAAG,GAAG,MAAM,CAAC;YACX,MAAM,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE;YACxE,KAAK,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE;YAC5E,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;YACjE,oBAAoB,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;YAC9E,MAAM,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,QAAQ,CAAC,EAAE;SACpE,CAAuB,CAAC;IAC3B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,KAAa;IAChD,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IACvC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,6GAA6G;AAC7G,MAAM,UAAU,aAAa,CAAC,MAAkB,EAAE,IAAY;IAC5D,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IACvC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,wHAAwH;AACxH,MAAM,UAAU,OAAO;IACrB,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC7B,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,oBAAoB,CAAC,EAAE,CAAC,CAAC;QAC1C,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,2GAA2G;AAC3G,MAAM,UAAU,aAAa,CAAC,GAAe;IAC3C,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACtC,CAAC"}

package/dist/abi1/libc.js

@@ -0,0 +1,109 @@
+/**
+ * The TS loader's trap and its fix (plan §3.3, "THE TS TRAP").
+ *
+ * ffi-rs opens a library through libloading with `RTLD_LAZY | RTLD_LOCAL`
+ * (measured: v0 `ts/src/registry.ts`'s own header comment states this of
+ * ffi-rs 1.3.7, and nothing in ffi-rs's public API — `open`, `define`,
+ * `load` — takes a dlopen mode flag). `RTLD_LAZY` defers symbol binding
+ * until first use, so a library with an UNRESOLVED external symbol (the
+ * `unbound` stub variant) would `dlopen` successfully under ffi-rs and only
+ * fail later, if ever, when something actually calls the missing function —
+ * which step 2 of the loader (D3/§3.2) requires NEVER happen: a v1 loader
+ * must refuse an artifact that cannot bind completely, at open time.
+ *
+ * The fix: do the REAL `dlopen(path, RTLD_NOW | RTLD_LOCAL)` ourselves,
+ * through libc directly, before ffi-rs ever touches the path. `RTLD_NOW`
+ * binds every relocation immediately, so `unbound` fails exactly where it
+ * must.
+ *
+ * This file is HAND-WRITTEN and declares nothing itself: the actual libc
+ * declarations and the symbol-lookup primitive live in the GENERATED
+ * `./libc.gen.ts` (scripts/abi-v1/emit/ts.py — see its module docstring).
+ * That split is the lead's 2026-10-02 ruling: check-no-hand-decls.py's
+ * `dlsym(` rule exists so every raw symbol lookup lives in generated code,
+ * exempt by construction, rather than being worked around in a hand file
+ * with a renamed table key or a call site shaped to dodge the text match.
+ * This file calls the generated exports only, by their own names.
+ */
+import { createExternalBuffer, open } from 'ffi-rs';
+import { cStringLength, dlerror, dlopen, gnuGetLibcVersion, resolveSymbol } from './libc.gen.js';
+/**
+ * RTLD_NOW | RTLD_LOCAL, read from this platform's own headers, not from
+ * memory (plan: "The RTLD constants differ between Linux and darwin; get
+ * them from the platform, not from memory"):
+ *
+ *   - glibc (x86_64-linux-gnu/bits/dlfcn.h) and musl (dlfcn.h) AGREE:
+ *     RTLD_LAZY=1, RTLD_NOW=2, RTLD_LOCAL=0, RTLD_GLOBAL=0x100.
+ *     RTLD_LOCAL is the absence of RTLD_GLOBAL, not a bit of its own.
+ *   - darwin (measured from this Mac's SDK,
+ *     `$(xcrun --show-sdk-path)/usr/include/dlfcn.h`):
+ *     RTLD_LAZY=0x1, RTLD_NOW=0x2, RTLD_LOCAL=0x4, RTLD_GLOBAL=0x8.
+ *     RTLD_LOCAL is a REAL bit here, and omitting it would ask for the
+ *     default (which Apple's dlopen(3) documents as RTLD_GLOBAL) — the
+ *     opposite of what D2's per-image symbol scope requires.
+ *
+ * So `RTLD_NOW | RTLD_LOCAL` is numerically 2 on Linux and 6 on darwin:
+ * computed here from named bits, never copied as a bare "2".
+ */
+const RTLD = process.platform === 'darwin' ? { NOW: 0x2, LOCAL: 0x4 } : { NOW: 0x2, LOCAL: 0x0 };
+export const RTLD_NOW_LOCAL = RTLD.NOW | RTLD.LOCAL;
+/** A NUL-terminated, ASCII/UTF-8-safe C string at `ptr`, read via the generated `cStringLength` (strlen) + a zero-copy view. Never call this on a pointer that may carry non-UTF-8 or embedded-NUL bytes (an ABI document body): it is for libc's own always-ASCII strings and `chs_build_info`'s guaranteed-ASCII, NUL-terminated JSON only. */
+function readCString(ptr) {
+    const len = cStringLength(ptr);
+    if (len === 0)
+        return '';
+    return Buffer.from(createExternalBuffer(ptr, len)).toString('utf8');
+}
+/** `dlopen(path, RTLD_NOW | RTLD_LOCAL)` through the generated primitive (plan §3.3(b)). Returns the raw OS handle, or null on failure — call `lastDlError()` immediately after a null to get libc's own message, before any other libc call. */
+export function rawDlopen(path) {
+    return dlopen(path, RTLD_NOW_LOCAL);
+}
+/** The loader's symbol-presence check (plan §3.3(c)), through the generated `resolveSymbol` helper: the raw symbol address, or null if `name` is not exported by `handle`'s image (this file never calls through the returned pointer — only ffi-rs's own by-name `define`/`load`, on an already-opened path, does that). */
+export function rawDlsym(handle, name) {
+    return resolveSymbol(handle, name);
+}
+/** libc's own diagnostic for the most recent failing open/resolve call, read ONCE (POSIX clears it on read) and only ever called right after that failure. */
+export function lastDlError() {
+    const p = dlerror();
+    return p === null ? '(no dlerror message)' : readCString(p);
+}
+/**
+ * The glibc version string (`gnu_get_libc_version()`), or null when the
+ * symbol is absent — which means this is musl, not glibc (plan step 1:
+ * "Absent → musl → refuse"). Linux only; a caller on darwin never calls
+ * this (step 1 is a no-op there).
+ */
+export function glibcVersionString() {
+    const ptr = gnuGetLibcVersion();
+    return ptr === null ? null : readCString(ptr);
+}
+/**
+ * Dotted-integer version comparison (`"2.29"` vs `"2.5"`, never lexical):
+ * negative if `a` < `b`, positive if `a` > `b`, 0 if equal. Missing trailing
+ * components compare as 0 (`"2"` == `"2.0"`).
+ */
+export function compareDottedVersions(a, b) {
+    const as = a.split('.').map((s) => Number.parseInt(s, 10));
+    const bs = b.split('.').map((s) => Number.parseInt(s, 10));
+    const n = Math.max(as.length, bs.length);
+    for (let i = 0; i < n; i++) {
+        const av = as[i] ?? 0;
+        const bv = bs[i] ?? 0;
+        if (Number.isNaN(av) || Number.isNaN(bv))
+            return Number.NaN;
+        if (av !== bv)
+            return av - bv;
+    }
+    return 0;
+}
+/** Open the target library's path through ffi-rs, under `libraryKey`, for typed calls (plan §3.3(d)). A harmless re-open when `path` is already the image our own `rawDlopen` just bound: dlopen (and the libloading ffi-rs uses underneath) dedupes by canonical path, returning the same already-mapped, already-bound image rather than re-relocating it. Declares no symbol of its own — `open()` only registers a path under a key for a later `define()` — so it is unaffected by the generated/hand-written split above. */
+export function ffiOpen(libraryKey, path) {
+    // Once per key: a load that failed after this point (a cross-check mismatch, a missing symbol) and is retried reaches here again for the same image.
+    if (ffiOpened.has(libraryKey))
+        return;
+    open({ library: libraryKey, path });
+    ffiOpened.add(libraryKey);
+}
+const ffiOpened = new Set();
+export { readCString };
+//# sourceMappingURL=libc.js.map

package/dist/abi1/libc.js.map

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

package/dist/abi1/loader.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The ABI v1 loader (plan §3, steps 1-7). Hand-written (the plan's "about 200
+ * lines per binding" FIRM piece); everything it reaches for — `rawDlopen`/
+ * `rawDlsym`/`glibcVersionString` (`./libc.ts`), `defineRawFunctions`/
+ * `rawCall` (`./raw.ts`), `DESCRIBED_SYMBOLS`/`SYMBOL`/`ABI_FINGERPRINT`/
+ * `CROSS_CHECK` (`./decls.gen.ts`) — is generated or generic, so this file
+ * never spells a `chs_` name itself.
+ *
+ * STEPS, IN ORDER (plan §3.2; `spec/abi-v1/sdk.json`'s `loader.refusals`
+ * names each reason):
+ *
+ *   1. glibc (Linux only; darwin skips it). BEFORE dlopen.
+ *   2. `dlopen(path, RTLD_NOW | RTLD_LOCAL)`, through `./libc.ts` (plan
+ *      §3.3(b): the real fix for ffi-rs's own `RTLD_LAZY` open).
+ *   3. `chs_abi_version`: present (`dlsym`, plan §3.3(c)) and, once present,
+ *      `=== 1` (a real call — only now safe through ffi-rs's own by-name
+ *      `open`/`define`, plan §3.3(d), since step 2 already proved the image
+ *      binds completely under `RTLD_NOW`).
+ *   4. `chs_build_info`: present, parses (ASCII, no duplicate keys at any
+ *      nesting depth, `schema === 1`), and its `abi_fingerprint` matches
+ *      this binding's own compiled-in `ABI_FINGERPRINT` byte for byte.
+ *   5. the nine `CROSS_CHECK` fields (`spec/abi-v1/sdk.json`) against
+ *      `LoadInput.predicate`.
+ *   6. every OTHER described symbol, present (`dlsym` only — no call).
+ *   7. `chs_initialize(zone)`, then `chs_set_defaults(defaults)` when there are
+ *      any, once per image, from the process setup the caller passes in
+ *      (`LoadInput.timezone` / `defaults`). A failure here is the CALL's own
+ *      error, mapped by the status table — never a loader refusal reason.
+ *
+ * No `dlclose`, ever (plan: "v0 measured a segfault on reopen"). Images are
+ * deduplicated by realpath + `dev:ino` (plan §3.2), re-implemented here
+ * rather than imported from any v0 file (plan §3.4: this directory touches
+ * no v0 file).
+ *
+ * `openUnverified` (plan §3.1) is the one path that skips steps 1 and 5: for
+ * core's own local builds and the (not-yet-built) linked mode, gated on BOTH
+ * an explicit flag and `CHTYPES_ALLOW_UNVERIFIED_LIBRARY=1`, never the
+ * default.
+ */
+import { type BuildInfo } from './buildinfo.js';
+import { Calls } from './calls.gen.js';
+import { type RawApi } from './raw.js';
+/** The predicate a loaded artifact is checked against: the verified signed statement's own fields, passed through verbatim (plan §3.1 — "predicate is passed verbatim, as the seam promises"). Only the fields this loader reads are typed; a real predicate carries more, and the fetch layer's own `ArtifactPredicate` satisfies this shape as it is. */
+export interface Predicate {
+    readonly abi: number;
+    readonly abi_fingerprint: string;
+    readonly clickhouse_version: string;
+    readonly channel: string;
+    readonly build: string;
+    readonly os: string;
+    readonly arch: string;
+    readonly core_commit: string;
+    readonly inputs_sha256: string;
+    readonly glibc_floor?: string | undefined;
+}
+/** The process setup step 7 applies to every image: the image zone and the default settings. */
+export interface ImageSetup {
+    /** The image zone `chs_initialize` is given (an IANA name); absent or empty means UTC. */
+    readonly timezone?: string;
+    /** Seeded once with `chs_set_defaults` when there are any. */
+    readonly defaults?: Readonly<Record<string, string>>;
+}
+/** The loader's own input, decoupled from the fetch layer's `Resolved` type: the adapter in `../registry.ts` joins them and passes the predicate verbatim. */
+export interface LoadInput extends ImageSetup {
+    readonly libraryPath: string;
+    readonly predicate: Predicate;
+    readonly platform: string;
+}
+/** One opened, verified ABI v1 image: the resolved raw table, its typed call wrappers, and the decoded build info. */
+export declare class LoadedImage {
+    readonly path: string;
+    readonly raw: RawApi;
+    readonly calls: Calls;
+    readonly buildInfo: BuildInfo;
+    constructor(path: string, raw: RawApi, buildInfo: BuildInfo);
+    get version(): string;
+}
+/**
+ * Load, verify and open one ABI v1 artifact (plan §3.2, steps 1-7). Returns
+ * the SAME `LoadedImage` for a path, a hardlink, a symlink or a second
+ * spelling of an already-loaded image: steps 2-4, 6 and 7 run once per image.
+ * An already-open image is still checked against every new signed statement a
+ * request brings (steps 1 and 5; step 4's fingerprint is the binding's own
+ * constant, which the first load already matched): a mismatch refuses that
+ * request and leaves the image open for the requests it did match.
+ */
+export declare function openAbi1(input: LoadInput): LoadedImage;
+/**
+ * Load `path` with NO predicate: skips step 1 (nothing to check a floor
+ * against) and step 5 (nothing to cross-check), still runs 2, 3, 4, 6 and 7.
+ * Refuses with a `UsageError` unless BOTH `options.allow` is true AND
+ * `CHTYPES_ALLOW_UNVERIFIED_LIBRARY=1` is set; warns loudly, once per path,
+ * when it proceeds. Never the default path — a local, trusted build is its
+ * only caller.
+ */
+export declare function openUnverified(path: string, options: {
+    readonly allow: boolean;
+} & ImageSetup): LoadedImage;
+//# sourceMappingURL=loader.d.ts.map

package/dist/abi1/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/abi1/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,EAAE,KAAK,SAAS,EAAmB,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAIvC,OAAO,EAAsB,KAAK,MAAM,EAAW,MAAM,UAAU,CAAC;AAEpE,2VAA2V;AAC3V,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED,gGAAgG;AAChG,MAAM,WAAW,UAAU;IACzB,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD;AAED,8JAA8J;AAC9J,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,sHAAsH;AACtH,qBAAa,WAAW;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAE9B,YAAY,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAK1D;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;CACF;AAsID;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,WAAW,CAkBtD;AA0BD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,UAAU,GAAG,WAAW,CAe3G"}

package/dist/abi1/loader.js

@@ -0,0 +1,261 @@
+/**
+ * The ABI v1 loader (plan §3, steps 1-7). Hand-written (the plan's "about 200
+ * lines per binding" FIRM piece); everything it reaches for — `rawDlopen`/
+ * `rawDlsym`/`glibcVersionString` (`./libc.ts`), `defineRawFunctions`/
+ * `rawCall` (`./raw.ts`), `DESCRIBED_SYMBOLS`/`SYMBOL`/`ABI_FINGERPRINT`/
+ * `CROSS_CHECK` (`./decls.gen.ts`) — is generated or generic, so this file
+ * never spells a `chs_` name itself.
+ *
+ * STEPS, IN ORDER (plan §3.2; `spec/abi-v1/sdk.json`'s `loader.refusals`
+ * names each reason):
+ *
+ *   1. glibc (Linux only; darwin skips it). BEFORE dlopen.
+ *   2. `dlopen(path, RTLD_NOW | RTLD_LOCAL)`, through `./libc.ts` (plan
+ *      §3.3(b): the real fix for ffi-rs's own `RTLD_LAZY` open).
+ *   3. `chs_abi_version`: present (`dlsym`, plan §3.3(c)) and, once present,
+ *      `=== 1` (a real call — only now safe through ffi-rs's own by-name
+ *      `open`/`define`, plan §3.3(d), since step 2 already proved the image
+ *      binds completely under `RTLD_NOW`).
+ *   4. `chs_build_info`: present, parses (ASCII, no duplicate keys at any
+ *      nesting depth, `schema === 1`), and its `abi_fingerprint` matches
+ *      this binding's own compiled-in `ABI_FINGERPRINT` byte for byte.
+ *   5. the nine `CROSS_CHECK` fields (`spec/abi-v1/sdk.json`) against
+ *      `LoadInput.predicate`.
+ *   6. every OTHER described symbol, present (`dlsym` only — no call).
+ *   7. `chs_initialize(zone)`, then `chs_set_defaults(defaults)` when there are
+ *      any, once per image, from the process setup the caller passes in
+ *      (`LoadInput.timezone` / `defaults`). A failure here is the CALL's own
+ *      error, mapped by the status table — never a loader refusal reason.
+ *
+ * No `dlclose`, ever (plan: "v0 measured a segfault on reopen"). Images are
+ * deduplicated by realpath + `dev:ino` (plan §3.2), re-implemented here
+ * rather than imported from any v0 file (plan §3.4: this directory touches
+ * no v0 file).
+ *
+ * `openUnverified` (plan §3.1) is the one path that skips steps 1 and 5: for
+ * core's own local builds and the (not-yet-built) linked mode, gated on BOTH
+ * an explicit flag and `CHTYPES_ALLOW_UNVERIFIED_LIBRARY=1`, never the
+ * default.
+ */
+import { realpathSync, statSync } from 'node:fs';
+import { decodeBuildInfo } from './buildinfo.js';
+import { Calls } from './calls.gen.js';
+import { ABI_FINGERPRINT, CROSS_CHECK, DESCRIBED_SYMBOLS, SYMBOL } from './decls.gen.js';
+import { ArtifactIncompatibleError, LoaderCorruptError, UsageError, usageError } from './errors.js';
+import { compareDottedVersions, ffiOpen, glibcVersionString, lastDlError, rawDlopen, rawDlsym } from './libc.js';
+import { defineRawFunctions, rawCall } from './raw.js';
+/** One opened, verified ABI v1 image: the resolved raw table, its typed call wrappers, and the decoded build info. */
+export class LoadedImage {
+    path;
+    raw;
+    calls;
+    buildInfo;
+    constructor(path, raw, buildInfo) {
+        this.path = path;
+        this.raw = raw;
+        this.calls = new Calls(raw);
+        this.buildInfo = buildInfo;
+    }
+    get version() {
+        return this.buildInfo.clickhouseVersion;
+    }
+}
+function refuseIncompatible(path, reason, want, got) {
+    throw new ArtifactIncompatibleError({ reason, path, want, got });
+}
+function refuseCorrupt(path, reason, want, got) {
+    throw new LoaderCorruptError({ reason, path, want, got });
+}
+// --------------------------------------------------------------- image cache
+const loadedByKey = new Map();
+/** The typed call table per image, so a load retried after a late refusal declares it once. */
+const rawTables = new Map();
+const keyBySpelling = new Map();
+/** The key `dlopen` will dedupe this path to (realpath + dev:ino, or an already-known spelling's key), per plan §3.2. */
+function resolveImageKey(path) {
+    let key;
+    let resolved;
+    try {
+        const st = statSync(path, { bigint: true });
+        key = `${st.dev}:${st.ino}`;
+        resolved = realpathSync(path);
+    }
+    catch (err) {
+        throw new ArtifactIncompatibleError({
+            reason: 'dlopen',
+            path,
+            got: `cannot stat this path: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+    const known = keyBySpelling.get(path) ?? keyBySpelling.get(resolved);
+    const realKey = known ?? key;
+    keyBySpelling.set(path, realKey);
+    keyBySpelling.set(resolved, realKey);
+    return realKey;
+}
+// ------------------------------------------------------------------- step 1
+function checkGlibc(path, predicate, platform) {
+    if (!platform.startsWith('linux'))
+        return; // darwin: skip (plan §3.2 step 1)
+    const actual = glibcVersionString();
+    if (actual === null) {
+        refuseIncompatible(path, 'no_glibc', predicate.glibc_floor, '(musl, or gnu_get_libc_version did not resolve)');
+    }
+    const floor = predicate.glibc_floor;
+    if (floor === undefined) {
+        refuseIncompatible(path, 'predicate_malformed', 'a glibc_floor field', '(absent)');
+    }
+    if (compareDottedVersions(actual, floor) < 0) {
+        refuseIncompatible(path, 'glibc_floor', floor, actual);
+    }
+}
+// ------------------------------------------------------------------- step 2
+function openImage(path) {
+    const handle = rawDlopen(path);
+    if (handle === null)
+        refuseIncompatible(path, 'dlopen', undefined, lastDlError());
+    return handle;
+}
+// ------------------------------------------------------------------- step 5
+/** `abi_fingerprint` -> `abiFingerprint`: the decoded `BuildInfo`'s own spelling of a build-info key. */
+function camelOf(key) {
+    return key.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+function crossCheckField(got, want, compare) {
+    if (compare === 'int')
+        return Number(got) === Number(want);
+    return String(got) === String(want);
+}
+function checkCrossFields(path, buildInfo, predicate) {
+    const pred = predicate;
+    const info = buildInfo;
+    for (const field of CROSS_CHECK) {
+        const got = info[camelOf(field.buildInfo)];
+        const want = pred[field.predicate];
+        if (!crossCheckField(got, want, field.compare)) {
+            refuseCorrupt(path, `build_info_mismatch:${field.buildInfo}`, JSON.stringify(want), JSON.stringify(got));
+        }
+    }
+}
+// ---------------------------------------------------------------- the whole
+/**
+ * Steps 2-4 and 6, shared by the verified and the unverified path: open the
+ * image `RTLD_NOW`, prove the generation, read and decode the build info and
+ * compare its fingerprint, resolve every other described symbol for presence.
+ */
+function openAndCheck(path, key) {
+    const osHandle = openImage(path); // step 2
+    // step 3: chs_abi_version present, then (through ffi-rs, now safe) === 1.
+    if (rawDlsym(osHandle, SYMBOL.ABI_VERSION) === null) {
+        refuseIncompatible(path, 'not_v1', '1', '(the generation handshake is not exported)');
+    }
+    ffiOpen(key, path); // plan §3.3(d): only now, after RTLD_NOW already bound the image.
+    let raw = rawTables.get(key);
+    if (raw === undefined) {
+        raw = defineRawFunctions(key);
+        rawTables.set(key, raw);
+    }
+    const abiVersionCall = rawCall(raw, SYMBOL.ABI_VERSION, []);
+    const abiVersion = abiVersionCall.outcome === 'value' ? Number(abiVersionCall.value) : Number.NaN;
+    if (abiVersion !== 1)
+        refuseIncompatible(path, 'abi_version', '1', String(abiVersion));
+    // step 4: the build info present, decoded (malformed is corrupt), fingerprint matches.
+    if (rawDlsym(osHandle, SYMBOL.BUILD_INFO) === null) {
+        refuseIncompatible(path, `missing_symbol:${SYMBOL.BUILD_INFO}`, undefined, `(${SYMBOL.BUILD_INFO} is not exported)`);
+    }
+    const buildInfoCall = rawCall(raw, SYMBOL.BUILD_INFO, []);
+    const buildInfoText = buildInfoCall.outcome === 'value' ? buildInfoCall.value : null;
+    if (buildInfoText === null)
+        refuseCorrupt(path, 'build_info_malformed', 'a JSON object', 'null');
+    const buildInfo = decodeBuildInfo(path, buildInfoText);
+    if (buildInfo.abiFingerprint !== ABI_FINGERPRINT) {
+        refuseIncompatible(path, 'fingerprint', ABI_FINGERPRINT, buildInfo.abiFingerprint);
+    }
+    // step 6: every other described symbol, present.
+    for (const sym of DESCRIBED_SYMBOLS) {
+        if (sym === SYMBOL.ABI_VERSION || sym === SYMBOL.BUILD_INFO)
+            continue; // already proved present above
+        if (rawDlsym(osHandle, sym) === null) {
+            refuseIncompatible(path, `missing_symbol:${sym}`, undefined, `(${sym} is not exported)`);
+        }
+    }
+    return { raw, buildInfo };
+}
+/**
+ * Load, verify and open one ABI v1 artifact (plan §3.2, steps 1-7). Returns
+ * the SAME `LoadedImage` for a path, a hardlink, a symlink or a second
+ * spelling of an already-loaded image: steps 2-4, 6 and 7 run once per image.
+ * An already-open image is still checked against every new signed statement a
+ * request brings (steps 1 and 5; step 4's fingerprint is the binding's own
+ * constant, which the first load already matched): a mismatch refuses that
+ * request and leaves the image open for the requests it did match.
+ */
+export function openAbi1(input) {
+    const path = input.libraryPath;
+    const key = resolveImageKey(path);
+    const cached = loadedByKey.get(key);
+    if (cached !== undefined) {
+        checkGlibc(path, input.predicate, input.platform); // step 1
+        checkCrossFields(path, cached.buildInfo, input.predicate); // step 5
+        return cached;
+    }
+    checkGlibc(path, input.predicate, input.platform); // step 1
+    const { raw, buildInfo } = openAndCheck(path, key); // steps 2-4, 6
+    checkCrossFields(path, buildInfo, input.predicate); // step 5, before step 7 touches the image
+    const image = new LoadedImage(path, raw, buildInfo);
+    initializeImage(image, input); // step 7
+    loadedByKey.set(key, image);
+    return image;
+}
+/** Step 7: `chs_initialize(zone)`, then `chs_set_defaults` when there are defaults. A failure is the call's own error, mapped by the status table; the zone asked for is named in the message either way. */
+function initializeImage(image, setup) {
+    const timezone = setup.timezone ?? '';
+    try {
+        image.calls.initialize(Buffer.from(timezone, 'utf8'));
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            // The library names the spelling it already holds; name the one asked for too.
+            throw usageError(`a different image zone was asked for (${JSON.stringify(timezone === '' ? 'UTC' : timezone)}) than the one this image already holds: ${err.messageBytes.toString('utf8')}`);
+        }
+        throw err;
+    }
+    const defaults = setup.defaults;
+    if (defaults !== undefined && Object.keys(defaults).length > 0) {
+        image.calls.setDefaults(Buffer.from(JSON.stringify(defaults), 'utf8'));
+    }
+}
+// ----------------------------------------------------------------- unverified
+const UNVERIFIED_ENV = 'CHTYPES_ALLOW_UNVERIFIED_LIBRARY';
+/**
+ * Load `path` with NO predicate: skips step 1 (nothing to check a floor
+ * against) and step 5 (nothing to cross-check), still runs 2, 3, 4, 6 and 7.
+ * Refuses with a `UsageError` unless BOTH `options.allow` is true AND
+ * `CHTYPES_ALLOW_UNVERIFIED_LIBRARY=1` is set; warns loudly, once per path,
+ * when it proceeds. Never the default path — a local, trusted build is its
+ * only caller.
+ */
+export function openUnverified(path, options) {
+    if (!options.allow || process.env[UNVERIFIED_ENV] !== '1') {
+        throw usageError(`opening ${path} unverified requires BOTH allow: true and ${UNVERIFIED_ENV}=1`);
+    }
+    warnUnverifiedOnce(path);
+    const key = resolveImageKey(path);
+    const cached = loadedByKey.get(key);
+    if (cached !== undefined)
+        return cached;
+    const { raw, buildInfo } = openAndCheck(path, key);
+    const image = new LoadedImage(path, raw, buildInfo);
+    initializeImage(image, options);
+    loadedByKey.set(key, image);
+    return image;
+}
+const warnedPaths = new Set();
+function warnUnverifiedOnce(path) {
+    if (warnedPaths.has(path))
+        return;
+    warnedPaths.add(path);
+    console.warn(`chtypes: ${path} was opened UNVERIFIED (${UNVERIFIED_ENV}=1): no predicate was checked. ` +
+        'Never use this path for an artifact that came from anywhere but a local, trusted build.');
+}
+//# sourceMappingURL=loader.js.map