Align Libhegel

Aligning the Go wrapper to a new libhegel release

libhegel is a Rust cdylib built from hegel-rust's hegel-c crate. hegel-go calls it via purego FFI. When the pinned version changes, the C API in hegel-c/include/hegel.h may have added, removed, renamed, or re-typed symbols, and the low-level wrapper in internal/libhegel/ must be re-aligned. The main hegel package's exported API must not change as a result — only the internal binding layer — except when libhegel removes an API. In that case, remove the corresponding API from the public Go package too. Do not preserve it with a compatibility shim, emulation, or another workaround after its upstream libhegel support is gone.

Within that binding layer, the wrapper API should track the C API. When a C function gains a parameter, plumb it through the internal/libhegel wrapper method (Settings.RunStart, …) rather than hardcoding a constant inside the wrapper — the wrapper's exported signature is meant to mirror the C signature. Any behavior-preserving default for a new optional parameter (a NULL callback, a nullable pointer, a 0-means-default flag) belongs in the package-hegel callers (runner.go, …), which pass 0/NULL — not baked into the wrapper. This keeps the binding honest (a future caller can supply a real value) while holding the hegel package's public API stable. Example: hegel_output_callback_t added (callback, user_data) to hegel_run_start; the wrapper takes both and the runner passes 0, 0.

The context-based ABI

Every fallible libhegel call follows one convention, and the whole wrapper is shaped around it:

• The first argument is a hegel_context_t (an error-reporting context).
• The return value is an Error result code (OK is 0; failures are negative — E_INVALID_HANDLE, E_INVALID_ARG, …).
• Any value the call produces (a handle, a count, a bool, a byte buffer) is written through a trailing out-parameter, not returned.
• On a non-OK return, the human-readable message is read back from the context via hegel_context_last_error.

So symbols (the loaded library) is immutable and shared across goroutines, while the per-call error state lives on a *Context. The wrapper threads a *Context through every method and funnels every call through two helpers:

• ctx.invoke(op, fn) — runs fn(ctxT), and if it returns non-OK, reads hegel_context_last_error and wraps it into a Go error.
• allocate(ctx, op, new, free) — invoke for handle constructors: maps a zero out-handle to a nil result (the engine's "no object" sentinel, e.g. a finished run) and registers a GC cleanup that calls free.

1. Vendor the target release first and fetch its actual header

Start by running just vendor-libhegel to vendor the latest stable libhegel release unless the user explicitly specifies a version. The existing pin in internal/libhegel/version.go is the starting state, not the requested target. For an explicit version, run just vendor-libhegel <version-or-tag> instead. The command accepts bare versions, new tags such as libhegel-v0.42.1, and legacy tags such as v0.37.1. It downloads and checksum-verifies the binaries and updates hegelVersion. It uses public GitHub HTTP endpoints; gh login is not required (an optional GH_TOKEN or GITHUB_TOKEN supports CI rate limits).

Record the actual tag printed by the vendoring command. Native packages in hegel-rust have independent release versions, so the repository's overall latest release is not necessarily the latest libhegel. Do not assume a tag is v<VERSION> or derive the target from a native package release.

Fetch the header from that exact tag, and confirm it exists before editing:

curl -fsSL https://raw.githubusercontent.com/hegeldev/hegel-rust/<ACTUAL_TAG>/hegel-c/include/hegel.h

If resuming with only a pinned version, query the GitHub release API for libhegel-v<VERSION> and, if absent, v<VERSION>; use the returned tag_name and verify its assets include libhegel binaries. Keep that resolved tag with the header for the independent audit in §8.

2. Get the matching library — always just check vendored

just check runs integration tests (TestLoadLibVersion, TestLibhegelEndToEnd) against the real library, and TestLoadLibVersion asserts the loaded lib reports exactly hegelVersion. You need a libhegel at that exact version, and the simplest way to get it is to let the loader use the vendored binary:

just check vendored

Always use vendored mode for this work — never a local build. The vendored mode leaves HEGEL_LIBHEGEL_PATH unset, so the loader materializes the go:embed'd vendored binary for hegelVersion (under internal/libhegel/libs/, refreshed by just vendor-libhegel) into the cache. A plain just check would instead build whatever the sibling ../hegel-rust checkout happens to be on (likely an older tag, since you've just bumped the version), point HEGEL_LIBHEGEL_PATH at that stale .so, and fail the version test. Don't touch the checkout; the vendored binary is always the right version.

The cached library lands at:

${XDG_CACHE_HOME:-$HOME/.cache}/hegel-go/libhegel/<VERSION>/libhegel-linux-amd64.so

When you need the symbol table, run nm -D against that cached .so — no build required. Use the exact pinned version so an older or newer cached release cannot be selected:

LIB="${XDG_CACHE_HOME:-$HOME/.cache}/hegel-go/libhegel/<VERSION>/libhegel-linux-amd64.so"
nm -D "$LIB" | grep '^.* T hegel_' | sort

The nm output is ground truth for which hegel_* symbols exist — diff it against the registration table in tryOpen (libhegel.go). A symbol the wrapper registers but the lib no longer exports makes registerSymbols fail and every integration test dies at load.

3. Compare hegel.h against internal/libhegel/libhegel.go

Walk every C declaration and check it against the wrapper. Categorize each:

• Removed symbol/API → delete its symbols field, its registration-table entry, its stub.go closure, and any wrapper method. If it backs an exported API in the main hegel package, remove that public API and its callers too; do not add compatibility code that recreates or retains an API libhegel has removed.
• Renamed/retyped symbol (e.g. hegel_run_result_passed, a bool, became hegel_run_result_status, a hegel_run_status_t written through an out-param) → update the field signature, the registration name, the wrapper method, and the stub.go closure's signature/out-param handling.
• New symbol → add a symbols field, a registration entry, a wrapper method, a stub.go closure, and a test (see §5).
• Changed signature (a new arg, or a value that moved from return to out-param) → remember the ABI convention: ctx first, Error return, produced value through a trailing out-pointer. The symbols field type and the wrapper method change together (stub.go adapts on its own — see §4.3). A new arg must be plumbed through the wrapper method's signature, not hardcoded inside the wrapper. If it is an optional arg with a behavior-preserving default (a NULL callback, a nullable pointer, a 0-means-default flag), leave the wrapper faithful and pass the default from the package-hegel callers (see the charter note in §intro). Do not silently bury a default in the wrapper — that hides the new capability and the §8 audit cannot tell a deliberate default from an oversight.
• Changed enum/constant values (e.g. a new HEGEL_LABEL_*, or a reordered hegel_status_t) → update the Go const block. Binding-invented labels that aren't in upstream (LABEL_COMPOSITE, LABEL_STATEFUL) must be renumbered to sit past the last upstream value so they can't collide.
• Enum-typed param widened to a fixed-width integer (e.g. hegel_settings_set_mode(…, hegel_mode_t mode) became (…, uint32_t mode); same for set_backend, set_verbosity, mark_complete's status) → the Go enum's base type must mirror the parameter's exact width and signedness literally, even though it's ABI-transparent. Change type Mode int32 to type Mode uint32 so it matches the uint32_t param, not the (still-signed) C enum it descends from. This is a real ABI difference to encode even though purego marshals a signed and an unsigned 32-bit value into the argument register identically for the small non-negative values these enums hold — so the integration tests pass either way and a mismatch will not be caught by the test suite; only a literal read of the header catches it. A base-type change needs a go generate ./internal/libhegel (§4), but the generated _string.go is usually byte-identical (the index assertions and string tables don't depend on signedness). Note the asymmetry: a value written through an out-param typed as the enum pointer (hegel_run_status_t *, i.e. RunStatus) is not widened and keeps mirroring the enum (int32).

4. Editing the binding — the things that move together

These must stay consistent or the build/coverage breaks. In practice only the first two are hand-edited for a signature change; stub.go is reflection-driven and adapts on its own (item 3), and the wrapper method (item 4) changes only when the call shape does:

1. libhegel.go — symbols struct: one func-typed field per C symbol. Mirror the C signature exactly: func(ctxT, <args>, <*outParam>) Error for a fallible call. The two exceptions are the C functions that return a value directly rather than through a result code — only hegel_context_last_error (func(ctxT) string) currently does this.

2. libhegel.go — registerSymbols table in tryOpen: {"hegel_x", &syms.x}.

3. stub.go — reflection-driven, usually needs no edit: Stub(tb, returns ...any) builds a symbols by reflection — it walks the struct and installs a reflect.MakeFunc closure on every func-typed field, then returns a *Context. Because the closures are synthesized from each field's type at runtime, adding, removing, reordering, or retyping a symbols field needs no change to stub.go — it adapts automatically. Each synthesized closure recognizes its out-params structurally, not by name: an out[T] argument by reflect.Type identity, or a pointer-to-~uintptr as a produced handle. Every non-pointer argument (a by-value scalar, a string, or the always-NULL outputCallbackT / user_data args) is treated as an input and consumes no scripted return value. Destructors (field name contains Free) are detected and auto-free their handle, scripting no return. Values are supplied by the caller via returns ...any and popped in strict call order by a single retval() helper. So the thing that moves in lockstep with a signature change is not stub.go but each test's returns ...any list when a symbol's output type or call order changes (see §5) — a new input arg that consumes no return value (like the NULL callback) needs no returns change either.

4. libhegel.go — wrapper method: a thin, typed Go method that threads a *Context. Handle constructors live on Context (e.g. SettingsNew) or on the parent handle (e.g. Settings.RunStart, Run.NextTestCase) and go through allocate(ctx, op, new, free). Other fallible calls go through ctx.invoke(op, fn). Reader methods (Result.Status, Result.FailureCount, Failure.Origin, …) use the reusable out* scratch fields on the wrapper struct (TestCase, Result, Failure) so the hot per-draw path doesn't allocate a fresh out-param on every call.

   A pointer to a string is not a valid Go wrapper API choice. Keep nullable pointers where required in the private symbols ABI signature, but expose strings idiomatically from wrapper methods. In order of preference:

   • Use "" as the absent/remove sentinel when the empty string is not itself a distinct valid value. This applies to both inputs and outputs.
   • When "" is a valid value and absence must remain distinguishable, use a (string, bool) pair: accept value string, present bool for an input, or return value string, present bool, err error for a fallible output. Keep the string first, following Go's value/comma-ok convention.

   Do not expose *string merely to mirror a nullable C char *; translate between the idiomatic Go representation and NULL at the wrapper boundary.