@hegeldev/hegel 0.2.2 → 0.3.0

package/dist/libhegel.js

@@ -0,0 +1,338 @@
+/**
+ * Thin, typed binding to the native `libhegel` C ABI (see
+ * `hegel-rust/hegel-c/include/hegel.h`, version 0.23.0) via {@link koffi}.
+ *
+ * The {@link Libhegel} class owns the loaded library's function pointers and
+ * exposes ergonomic wrappers. Every fallible call takes a `hegel_context_t*`
+ * first argument and returns a `hegel_result_t` code (`HEGEL_OK` is zero;
+ * negatives are errors), writing any value it produces — a handle, a string, a
+ * count — through a trailing out-parameter. The wrappers map those codes to
+ * thrown errors ({@link StopTestError} / {@link AssumeError} for the
+ * choice-budget / rejected-draw cases, otherwise {@link LibhegelError} carrying
+ * the diagnostic from `hegel_context_last_error`) and read the out-parameters
+ * back into JS values.
+ *
+ * libhegel frees nothing for you: every handle from a constructor
+ * (`hegel_context_new`, `hegel_settings_new`, `hegel_run_start`,
+ * `hegel_test_case_from_blob`) must be released by the caller with its matching
+ * free (the runner does so in `finally` blocks). Test cases from
+ * `hegel_next_test_case` are borrowed and released by `hegel_run_free`.
+ *
+ * @packageDocumentation
+ */
+import koffi from "koffi";
+import { StopTestError, AssumeError } from "./testCase.js";
+/** `hegel_status_t` — outcome of a single test case. */
+export const Status = {
+    VALID: 0,
+    INVALID: 1,
+    OVERRUN: 2,
+    INTERESTING: 3,
+};
+/** `hegel_run_status_t` — aggregate outcome of a finished run. */
+export const RunStatus = {
+    PASSED: 0,
+    FAILED: 1,
+    ERROR: 2,
+};
+/** `hegel_verbosity_t`. */
+export const NativeVerbosity = {
+    QUIET: 0,
+    NORMAL: 1,
+    VERBOSE: 2,
+    DEBUG: 3,
+};
+/** Relevant `hegel_result_t` codes. */
+const RESULT_OK = 0;
+const RESULT_STOP_TEST = -1;
+const RESULT_ASSUME = -2;
+/** An error returned by a fallible libhegel call. */
+export class LibhegelError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "LibhegelError";
+        this.code = code;
+    }
+}
+/**
+ * Bind every libhegel function used by the client against a loaded koffi
+ * library handle.
+ *
+ * Calls that cannot fail for the inputs the client gives them (constructors,
+ * frees, setters, result getters) pass a NULL context — which the ABI accepts,
+ * simply opting out of error messages — and discard the result code here; the
+ * genuinely fallible calls return the code for {@link Libhegel} to map to an
+ * exception.
+ */
+export function bindLibrary(lib) {
+    // The koffi FFI boundary is inherently dynamically typed; `Bindings` re-imposes
+    // static types on the wrappers below.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const f = (proto) => lib.func(proto);
+    const contextNew = f("void* hegel_context_new()");
+    const contextFree = f("void hegel_context_free(void* ctx)");
+    const contextLastError = f("const char* hegel_context_last_error(void* ctx)");
+    const settingsNew = f("int hegel_settings_new(void* ctx, _Out_ void** out)");
+    const settingsFree = f("void hegel_settings_free(void* ctx, void* s)");
+    const settingsTestCases = f("int hegel_settings_set_test_cases(void* ctx, void* s, uint64_t n)");
+    const settingsVerbosity = f("int hegel_settings_set_verbosity(void* ctx, void* s, int v)");
+    const settingsSeed = f("int hegel_settings_set_seed(void* ctx, void* s, uint64_t seed, bool has_seed)");
+    const settingsDerandomize = f("int hegel_settings_set_derandomize(void* ctx, void* s, bool d)");
+    const settingsDatabase = f("int hegel_settings_set_database(void* ctx, void* s, const char* db)");
+    const settingsDatabaseKey = f("int hegel_settings_set_database_key(void* ctx, void* s, const char* key)");
+    const settingsSuppressHealthCheck = f("int hegel_settings_set_suppress_health_check(void* ctx, void* s, uint32_t checks)");
+    const runStart = f("int hegel_run_start(void* ctx, void* settings, _Out_ void** out_run)");
+    const nextTestCase = f("int hegel_next_test_case(void* ctx, void* run, _Out_ void** out_tc)");
+    const runResult = f("int hegel_run_result(void* ctx, void* run, _Out_ void** out_result)");
+    const runFree = f("void hegel_run_free(void* ctx, void* run)");
+    const testCaseFromBlob = f("int hegel_test_case_from_blob(void* ctx, void* s, const char* blob, _Out_ void** out_tc)");
+    const testCaseFree = f("void hegel_test_case_free(void* ctx, void* tc)");
+    const generate = f("int hegel_generate(void* ctx, void* tc, uint8_t* schema, size_t schema_len, _Out_ void** out, _Out_ size_t* out_len)");
+    const startSpan = f("int hegel_start_span(void* ctx, void* tc, uint64_t label)");
+    const stopSpan = f("int hegel_stop_span(void* ctx, void* tc, bool discard)");
+    const newCollection = f("int hegel_new_collection(void* ctx, void* tc, uint64_t min, uint64_t max, _Out_ int64_t* out)");
+    const collectionMore = f("int hegel_collection_more(void* ctx, void* tc, int64_t id, _Out_ bool* out)");
+    const collectionReject = f("int hegel_collection_reject(void* ctx, void* tc, int64_t id, const char* why)");
+    const markComplete = f("int hegel_mark_complete(void* ctx, void* tc, int status, const char* origin)");
+    const runResultStatus = f("int hegel_run_result_status(void* ctx, void* r, _Out_ int* out)");
+    const runResultError = f("int hegel_run_result_error(void* ctx, void* r, _Out_ char** out)");
+    const runResultFailureCount = f("int hegel_run_result_failure_count(void* ctx, void* r, _Out_ size_t* out)");
+    const runResultFailure = f("int hegel_run_result_failure(void* ctx, void* r, size_t index, _Out_ void** out)");
+    const failureOrigin = f("int hegel_failure_origin(void* ctx, void* f, _Out_ char** out)");
+    const failureReproductionBlob = f("int hegel_failure_reproduction_blob(void* ctx, void* f, _Out_ char** out)");
+    const version = f("int hegel_version(void* ctx, _Out_ char** out)");
+    return {
+        contextNew: () => contextNew(),
+        contextFree: (ctx) => contextFree(ctx),
+        contextLastError: (ctx) => contextLastError(ctx),
+        settingsNew: () => {
+            const out = [null];
+            settingsNew(null, out);
+            return out[0];
+        },
+        settingsFree: (s) => settingsFree(null, s),
+        settingsTestCases: (s, n) => void settingsTestCases(null, s, n),
+        settingsVerbosity: (s, v) => void settingsVerbosity(null, s, v),
+        settingsSeed: (s, seed, hasSeed) => void settingsSeed(null, s, seed, hasSeed),
+        settingsDerandomize: (s, on) => void settingsDerandomize(null, s, on),
+        settingsDatabase: (ctx, s, db) => void settingsDatabase(ctx, s, db),
+        settingsDatabaseKey: (ctx, s, key) => void settingsDatabaseKey(ctx, s, key),
+        settingsSuppressHealthCheck: (s, checks) => void settingsSuppressHealthCheck(null, s, checks),
+        runStart: (ctx, s, out) => runStart(ctx, s, out),
+        nextTestCase: (ctx, run, out) => nextTestCase(ctx, run, out),
+        runResult: (ctx, run, out) => runResult(ctx, run, out),
+        runFree: (run) => runFree(null, run),
+        testCaseFromBlob: (ctx, s, blob, out) => testCaseFromBlob(ctx, s, blob, out),
+        testCaseFree: (tc) => testCaseFree(null, tc),
+        generate: (ctx, tc, schema, schemaLen, out, outLen) => generate(ctx, tc, schema, schemaLen, out, outLen),
+        startSpan: (ctx, tc, label) => startSpan(ctx, tc, label),
+        stopSpan: (ctx, tc, discard) => stopSpan(ctx, tc, discard),
+        newCollection: (ctx, tc, min, max, out) => newCollection(ctx, tc, min, max, out),
+        collectionMore: (ctx, tc, id, out) => collectionMore(ctx, tc, id, out),
+        collectionReject: (ctx, tc, id, why) => collectionReject(ctx, tc, id, why),
+        markComplete: (ctx, tc, status, origin) => markComplete(ctx, tc, status, origin),
+        runResultStatus: (r) => {
+            const out = [0];
+            runResultStatus(null, r, out);
+            return out[0];
+        },
+        runResultError: (r) => {
+            const out = [null];
+            runResultError(null, r, out);
+            return out[0];
+        },
+        runResultFailureCount: (r) => {
+            const out = [0];
+            runResultFailureCount(null, r, out);
+            return Number(out[0]);
+        },
+        runResultFailure: (r, index) => {
+            const out = [null];
+            runResultFailure(null, r, index, out);
+            return out[0];
+        },
+        failureOrigin: (fp) => {
+            const out = [null];
+            failureOrigin(null, fp, out);
+            return out[0];
+        },
+        failureReproductionBlob: (fp) => {
+            const out = [null];
+            failureReproductionBlob(null, fp, out);
+            return out[0];
+        },
+        version: () => {
+            // `hegel_version` always writes a non-null static string (it only fails on
+            // a NULL out-pointer, which we never pass), so the seeded "" is never read.
+            const out = [""];
+            version(null, out);
+            return out[0];
+        },
+    };
+}
+const UINT64_MAX = 0xffffffffffffffffn;
+/**
+ * High-level wrapper over the libhegel C ABI.
+ */
+export class Libhegel {
+    fns;
+    constructor(fns) {
+        this.fns = fns;
+    }
+    /** Load libhegel from a shared-library path. */
+    static load(path) {
+        return new Libhegel(bindLibrary(koffi.load(path)));
+    }
+    version() {
+        return this.fns.version();
+    }
+    newContext() {
+        return this.fns.contextNew();
+    }
+    freeContext(ctx) {
+        this.fns.contextFree(ctx);
+    }
+    lastError(ctx) {
+        return this.fns.contextLastError(ctx) ?? "";
+    }
+    newSettings() {
+        return this.fns.settingsNew();
+    }
+    freeSettings(s) {
+        this.fns.settingsFree(s);
+    }
+    setTestCases(s, n) {
+        this.fns.settingsTestCases(s, n);
+    }
+    setVerbosity(s, v) {
+        this.fns.settingsVerbosity(s, v);
+    }
+    setSeed(s, seed) {
+        this.fns.settingsSeed(s, seed, true);
+    }
+    setDerandomize(s, on) {
+        this.fns.settingsDerandomize(s, on);
+    }
+    setDatabase(ctx, s, db) {
+        this.fns.settingsDatabase(ctx, s, db);
+    }
+    setDatabaseKey(ctx, s, key) {
+        this.fns.settingsDatabaseKey(ctx, s, key);
+    }
+    setSuppressHealthCheck(s, checks) {
+        this.fns.settingsSuppressHealthCheck(s, checks);
+    }
+    /** Start a run. Throws {@link LibhegelError} on failure. */
+    runStart(ctx, settings) {
+        const out = [null];
+        this.check(ctx, this.fns.runStart(ctx, settings, out), "hegel_run_start");
+        return out[0];
+    }
+    /**
+     * Pull the next test case, or `null` when the run is finished. Throws if the
+     * engine reported a mid-run error (e.g. the previous case was not completed).
+     */
+    nextTestCase(ctx, run) {
+        const out = [null];
+        this.check(ctx, this.fns.nextTestCase(ctx, run, out), "hegel_next_test_case");
+        return out[0] ?? null;
+    }
+    /** Read the aggregated run result. Throws on failure. */
+    runResult(ctx, run) {
+        const out = [null];
+        this.check(ctx, this.fns.runResult(ctx, run, out), "hegel_run_result");
+        return out[0];
+    }
+    freeRun(run) {
+        this.fns.runFree(run);
+    }
+    /**
+     * Build a standalone test case that replays a base64 failure blob (from
+     * {@link reproductionBlob}). Owned by the caller — release with
+     * {@link freeTestCase}. Throws {@link LibhegelError} on a malformed blob.
+     */
+    testCaseFromBlob(ctx, settings, blob) {
+        const out = [null];
+        this.check(ctx, this.fns.testCaseFromBlob(ctx, settings, blob, out), "hegel_test_case_from_blob");
+        return out[0];
+    }
+    freeTestCase(tc) {
+        this.fns.testCaseFree(tc);
+    }
+    /**
+     * Map a fallible `int`-returning result code to an exception.
+     * `HEGEL_E_STOP_TEST` becomes {@link StopTestError}, `HEGEL_E_ASSUME` becomes
+     * {@link AssumeError}; any other non-OK code becomes a {@link LibhegelError}
+     * carrying the context diagnostic.
+     */
+    check(ctx, code, op) {
+        if (code === RESULT_OK) {
+            return;
+        }
+        if (code === RESULT_STOP_TEST) {
+            throw new StopTestError();
+        }
+        if (code === RESULT_ASSUME) {
+            // The engine rejected this draw (e.g. a format generator's internal
+            // precondition failed); discard the test case like a failed assume().
+            throw new AssumeError();
+        }
+        throw new LibhegelError(`${op} failed: ${this.lastError(ctx)}`, code);
+    }
+    /** Draw a CBOR value for the given CBOR-encoded schema. */
+    generate(ctx, tc, schema) {
+        const out = [null];
+        const outLen = [0];
+        const code = this.fns.generate(ctx, tc, schema, schema.length, out, outLen);
+        this.check(ctx, code, "hegel_generate");
+        const len = Number(outLen[0]);
+        return Buffer.from(koffi.decode(out[0], "uint8_t", len));
+    }
+    startSpan(ctx, tc, label) {
+        this.check(ctx, this.fns.startSpan(ctx, tc, label), "hegel_start_span");
+    }
+    stopSpan(ctx, tc, discard) {
+        this.check(ctx, this.fns.stopSpan(ctx, tc, discard), "hegel_stop_span");
+    }
+    newCollection(ctx, tc, min, max) {
+        const out = [0];
+        const maxArg = max === undefined ? UINT64_MAX : BigInt(max);
+        this.check(ctx, this.fns.newCollection(ctx, tc, min, maxArg, out), "hegel_new_collection");
+        return BigInt(out[0]);
+    }
+    collectionMore(ctx, tc, id) {
+        const out = [false];
+        this.check(ctx, this.fns.collectionMore(ctx, tc, id, out), "hegel_collection_more");
+        return out[0];
+    }
+    collectionReject(ctx, tc, id, why) {
+        this.check(ctx, this.fns.collectionReject(ctx, tc, id, why), "hegel_collection_reject");
+    }
+    markComplete(ctx, tc, status, origin) {
+        this.check(ctx, this.fns.markComplete(ctx, tc, status, origin), "hegel_mark_complete");
+    }
+    runStatus(r) {
+        return this.fns.runResultStatus(r);
+    }
+    runError(r) {
+        return this.fns.runResultError(r);
+    }
+    failureCount(r) {
+        return this.fns.runResultFailureCount(r);
+    }
+    failure(r, index) {
+        return this.fns.runResultFailure(r, index);
+    }
+    failureOrigin(fp) {
+        return this.fns.failureOrigin(fp) ?? "";
+    }
+    /**
+     * The failure's base64 reproduce blob, or `null` if the engine produced none.
+     * Replay it via {@link testCaseFromBlob} to surface the test's own error.
+     */
+    reproductionBlob(fp) {
+        return this.fns.failureReproductionBlob(fp);
+    }
+}
+//# sourceMappingURL=libhegel.js.map

package/dist/libhegel.js.map

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

package/dist/locate.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Locates the native `libhegel` shared library for the host platform.
+ *
+ * The per-platform shared libraries are bundled into the published npm package
+ * (under `native/`, fetched at pack time by `scripts/fetch-libhegel.mjs`), so
+ * there is nothing to download or cache at runtime. Resolution is:
+ *
+ * 1. `$HEGEL_LIBHEGEL_PATH`, if set — used directly (a local build / override).
+ * 2. The bundled artifact for the host platform under the package's `native/`
+ *    directory.
+ *
+ * Resolution is synchronous: the library must be available before the
+ * (synchronous) `hegel.test` run loop starts.
+ *
+ * @packageDocumentation
+ */
+/** Env var pinning libhegel to an explicit path (overrides the bundled copy). */
+export declare const LIBRARY_PATH_ENV = "HEGEL_LIBHEGEL_PATH";
+/**
+ * Returns the bundled asset filename for the given platform and architecture,
+ * e.g. `libhegel-linux-arm64.so`. Throws for an unsupported OS or CPU
+ * architecture.
+ */
+export declare function libhegelAssetName(platform: NodeJS.Platform, arch: string): string;
+/** Directory holding the bundled shared libraries, relative to this module. */
+export declare function nativeDir(): string;
+/**
+ * Resolves a filesystem path to the native libhegel library. The environment,
+ * platform, architecture and native directory are passed in so the resolution
+ * logic is fully unit-testable.
+ */
+export declare function resolveLibrary(opts: {
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+    arch: string;
+    nativeDir: string;
+}): string;
+/**
+ * Resolves the libhegel path for the current process environment.
+ */
+export declare function locateLibhegel(): string;
+//# sourceMappingURL=locate.d.ts.map

package/dist/locate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locate.d.ts","sourceRoot":"","sources":["../src/locate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AAEtD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAiCjF;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,IAAI,MAAM,CAIlC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAgBT;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAOvC"}

package/dist/locate.js

@@ -0,0 +1,94 @@
+/**
+ * Locates the native `libhegel` shared library for the host platform.
+ *
+ * The per-platform shared libraries are bundled into the published npm package
+ * (under `native/`, fetched at pack time by `scripts/fetch-libhegel.mjs`), so
+ * there is nothing to download or cache at runtime. Resolution is:
+ *
+ * 1. `$HEGEL_LIBHEGEL_PATH`, if set — used directly (a local build / override).
+ * 2. The bundled artifact for the host platform under the package's `native/`
+ *    directory.
+ *
+ * Resolution is synchronous: the library must be available before the
+ * (synchronous) `hegel.test` run loop starts.
+ *
+ * @packageDocumentation
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** Env var pinning libhegel to an explicit path (overrides the bundled copy). */
+export const LIBRARY_PATH_ENV = "HEGEL_LIBHEGEL_PATH";
+/**
+ * Returns the bundled asset filename for the given platform and architecture,
+ * e.g. `libhegel-linux-arm64.so`. Throws for an unsupported OS or CPU
+ * architecture.
+ */
+export function libhegelAssetName(platform, arch) {
+    let osName;
+    let ext;
+    switch (platform) {
+        case "linux":
+            osName = "linux";
+            ext = "so";
+            break;
+        case "darwin":
+            osName = "darwin";
+            ext = "dylib";
+            break;
+        case "win32":
+            osName = "windows";
+            ext = "dll";
+            break;
+        default:
+            throw new Error(`Unsupported platform '${platform}' for libhegel`);
+    }
+    let archName;
+    switch (arch) {
+        case "x64":
+            archName = "amd64";
+            break;
+        case "arm64":
+            archName = "arm64";
+            break;
+        default:
+            throw new Error(`Unsupported architecture '${arch}' for libhegel`);
+    }
+    return `libhegel-${osName}-${archName}.${ext}`;
+}
+/** Directory holding the bundled shared libraries, relative to this module. */
+export function nativeDir() {
+    // At runtime this module is `dist/locate.js`; under tests it is `src/locate.ts`.
+    // Either way the bundled `native/` directory sits one level up.
+    return path.join(import.meta.dirname, "..", "native");
+}
+/**
+ * Resolves a filesystem path to the native libhegel library. The environment,
+ * platform, architecture and native directory are passed in so the resolution
+ * logic is fully unit-testable.
+ */
+export function resolveLibrary(opts) {
+    const override = opts.env[LIBRARY_PATH_ENV];
+    if (override !== undefined && override !== "") {
+        return override;
+    }
+    const asset = libhegelAssetName(opts.platform, opts.arch);
+    const bundled = path.join(opts.nativeDir, asset);
+    if (!fs.existsSync(bundled)) {
+        throw new Error(`Bundled libhegel not found at ${bundled}. This usually means the package ` +
+            `was built without its native libraries; run \`just fetch-libhegel\` (or set ` +
+            `${LIBRARY_PATH_ENV} to a local libhegel).`);
+    }
+    return bundled;
+}
+/**
+ * Resolves the libhegel path for the current process environment.
+ */
+export function locateLibhegel() {
+    return resolveLibrary({
+        env: process.env,
+        platform: process.platform,
+        arch: process.arch,
+        nativeDir: nativeDir(),
+    });
+}
+//# sourceMappingURL=locate.js.map

package/dist/locate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locate.js","sourceRoot":"","sources":["../src/locate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,iFAAiF;AACjF,MAAM,CAAC,MAAM,gBAAgB,GAAG,qBAAqB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAyB,EAAE,IAAY;IACvE,IAAI,MAAc,CAAC;IACnB,IAAI,GAAW,CAAC;IAChB,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,OAAO;YACV,MAAM,GAAG,OAAO,CAAC;YACjB,GAAG,GAAG,IAAI,CAAC;YACX,MAAM;QACR,KAAK,QAAQ;YACX,MAAM,GAAG,QAAQ,CAAC;YAClB,GAAG,GAAG,OAAO,CAAC;YACd,MAAM;QACR,KAAK,OAAO;YACV,MAAM,GAAG,SAAS,CAAC;YACnB,GAAG,GAAG,KAAK,CAAC;YACZ,MAAM;QACR;YACE,MAAM,IAAI,KAAK,CAAC,yBAAyB,QAAQ,gBAAgB,CAAC,CAAC;IACvE,CAAC;IAED,IAAI,QAAgB,CAAC;IACrB,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,KAAK;YACR,QAAQ,GAAG,OAAO,CAAC;YACnB,MAAM;QACR,KAAK,OAAO;YACV,QAAQ,GAAG,OAAO,CAAC;YACnB,MAAM;QACR;YACE,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,gBAAgB,CAAC,CAAC;IACvE,CAAC;IAED,OAAO,YAAY,MAAM,IAAI,QAAQ,IAAI,GAAG,EAAE,CAAC;AACjD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,SAAS;IACvB,iFAAiF;IACjF,gEAAgE;IAChE,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAK9B;IACC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC5C,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QAC9C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACjD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,iCAAiC,OAAO,mCAAmC;YACzE,8EAA8E;YAC9E,GAAG,gBAAgB,wBAAwB,CAC9C,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,cAAc,CAAC;QACpB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,SAAS,EAAE,SAAS,EAAE;KACvB,CAAC,CAAC;AACL,CAAC"}

package/dist/runner.d.ts

@@ -1,10 +1,11 @@
 /**
- * Test runner: Hegel builder, Settings, and test lifecycle.
+ * Test runner: the `hegel.test` / `hegel.testAsync` entry points, Settings, and
+ * the test lifecycle driving the native libhegel run loop.
  *
  * @packageDocumentation
  */
 import { TestCase, type DataSource } from "./testCase.js";
-import type { Connection, Stream } from "./connection.js";
+import { Libhegel, type Ptr } from "./libhegel.js";
 export declare enum Verbosity {
     Quiet = "quiet",
     Normal = "normal",
@@ -40,28 +41,29 @@ export interface Settings {
 }
 export declare function defaultSettings(): Settings;
 /**
- * DataSource implementation that communicates with the hegel server
- * over a multiplexed stream connection.
+ * {@link DataSource} backed by a native libhegel test case. All draws, spans
+ * and collection operations dispatch to the engine via the {@link Libhegel}
+ * C-ABI wrapper.
  */
-export declare class ServerDataSource implements DataSource {
-    private stream;
-    private connection;
-    private _aborted;
-    constructor(connection: Connection, stream: Stream);
-    private sendRequest;
+export declare class NativeDataSource implements DataSource {
+    private readonly lib;
+    private readonly ctx;
+    private readonly tc;
+    constructor(lib: Libhegel, ctx: Ptr, tc: Ptr);
     generate(schema: Record<string, unknown>): unknown;
     startSpan(label: number): void;
     stopSpan(discard: boolean): void;
     newCollection(minSize: number, maxSize?: number): number;
     collectionMore(collectionId: number): boolean;
     collectionReject(collectionId: number, why?: string): void;
-    markComplete(status: string, origin: string | null): void;
-    testAborted(): boolean;
+    markComplete(status: number, origin: string | null): void;
 }
 export type TestCaseResult = {
     status: "valid";
 } | {
     status: "invalid";
+} | {
+    status: "overrun";
 } | {
     status: "interesting";
     error: unknown;
@@ -84,12 +86,18 @@ export declare class Hegel {
     /** Set the test location for Antithesis integration. */
     testLocation(location: TestLocation): this;
     /**
-     * Generator that drives the wire protocol but yields a `ServerDataSource`
-     * (plus an `isFinal` flag) each time a test case needs to be executed.
-     * The driver ({@link run} or {@link runSync}) calls the user's test body
-     * and resumes the generator with the resulting {@link TestCaseResult}.
-     * This factoring lets the sync and async drivers share one implementation
-     * of the protocol loop.
+     * Generator that drives the libhegel run loop, yielding a
+     * {@link NativeDataSource} (plus an `isFinal` flag) for each test case the
+     * driver ({@link run} or {@link runSync}) should execute the body against. The
+     * driver runs the user's body and resumes the generator with the
+     * {@link TestCaseResult}. This factoring lets the sync and async drivers share
+     * one loop implementation.
+     *
+     * The engine only *explores* (generate / shrink), so every pumped case is
+     * non-final. The client owns the final replays: once the loop drains and the
+     * run has failed, each discovered counterexample's reproduce blob is replayed
+     * (via `hegel_test_case_from_blob`) as a final case to surface the test's own
+     * error for the thrown message.
      */
     private runSteps;
     run(): Promise<void>;
@@ -103,8 +111,8 @@ export declare class Hegel {
  * @example
  * ```ts
  * import { test } from 'vitest';
- * import * as hegel from 'hegel';
- * import * as gs from 'hegel/generators';
+ * import * as hegel from '@hegeldev/hegel';
+ * import * as gs from '@hegeldev/hegel/generators';
  *
  * test('addition is commutative', () =>
  *   hegel.test((tc) => {
@@ -125,8 +133,8 @@ export declare function test(testFn: (tc: TestCase) => void, settings?: Partial<
  * @example
  * ```ts
  * import { test } from 'vitest';
- * import * as hegel from 'hegel';
- * import * as gs from 'hegel/generators';
+ * import * as hegel from '@hegeldev/hegel';
+ * import * as gs from '@hegeldev/hegel/generators';
  *
  * test('my async test', () =>
  *   hegel.testAsync(async (tc) => {

package/dist/runner.d.ts.map

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