Module capi 

The C ABI (impl plan §4 step 8). Verbatim rules: no global state (SoilRuntime* is the instance); explicit init/teardown; no unwinding across the boundary — every entry point is wrapped in catch_unwind, and a caught panic becomes a SoilError of kind Internal.

Threading: a runtime and every handle created under it belong to one thread (non-atomic refcounts by resolved decision). Parallel hosts run one runtime per thread.

Ownership: constructors return owned handles; every input handle is borrowed (internally refcount-bumped as needed), so the caller frees exactly what it was returned — values with soil_value_free, strings with soil_string_free, errors with soil_error_free. Closures are not constructible over this ABI yet (soil_closure_new arrives with compiled code, plan 05).

Structs

SoilRuntime

Opaque C-side names. SoilRuntime* is a Runtime, SoilValue* a Value, SoilError* a SoilError; the internal layouts are not part of the ABI.

Functions

soil_debug_live_values

Live runtime allocations on this thread — debug builds only (always 0 in release). The leak-check hook.

soil_decode^⚠

Type-directed decode — parse (design §3.7). shape_json is a shape in the descriptor-JSON encoding ({"tag": "Named", "value": "Doc"}, {"tag": "List", "value": {"tag": "I64"}}, …).

soil_eq^⚠

Derived structural equality (design §3.7). Returns 1, 0, or -1 with *err set.

soil_error_free^⚠

Safety

soil_error_kind^⚠

The PanicKind as a stable small integer (order of declaration).

soil_error_message^⚠

Safety

soil_f64_new

soil_i64_get^⚠

Read an I64 out of a value handle. Returns 0 on success.

soil_i64_new

soil_init

Create a runtime instance. Never fails; returns null only on an internal panic.

soil_list_new^⚠

Build a list from borrowed elements.

soil_main

The trivial main wrapper (design §3.10): init, hand the runtime to the host’s entry function, tear down, return its exit code.

soil_record_new^⚠

Build a record from its non-ignored fields in declaration order; ignored fields are refilled from their defaults, exactly as in JSON decode (micro-pin §8.6). Field values are borrowed.

soil_register_types^⚠

Register types from descriptor JSON (see descriptor_json). Returns 0 on success, nonzero with *err set on failure.

soil_show^⚠

Canonical JSON of a value — show (design §3.7). Returns an owned NUL-terminated string; free with soil_string_free.

soil_string_free^⚠

Safety

soil_sum_new^⚠

Build a sum value by variant name. payload is null for nullary variants, borrowed otherwise.

soil_teardown^⚠

Tear down a runtime. Values created under it must already be freed.

soil_type_lookup^⚠

Look up a type id by name. Returns UINT32_MAX if unknown.

soil_unit_new

soil_utf8_new^⚠

Safety

soil_value_clone^⚠

Safety

soil_value_free^⚠

Safety