package vinary-tree-interop

vinary-tree-interop

One ABI, zero algorithms. vinary-tree-interop is the stable C ABI the vinary-tree family uses to hand live resources — dictionaries and weighted finite-state transducers — between independently built libraries and language bindings. The crate is #![no_std], dependency-free, and contains layouts and constants only: no functions, no allocator, no I/O, nothing executable. Every function that exists at this boundary is a pointer inside a provider-supplied vtable. Project crates own the safe wrappers and the concrete resource implementations; this crate owns the bytes they agree on.

That inversion is what makes the family modular: a consumer that reads only include/vinary_tree_interop.h (or the bit-identical Rust definitions in src/lib.rs) can consume resources from any provider — another family repo, another version of a family repo, or a third party — without linking against it and without touching Rust's unstable dynamic-library ABI.

The two-word resource

A resource is exactly two machine words:

typedef struct VtResource {
    void* context;                          /* provider-defined state  */
    const struct VtResourceVTable* vtable;  /* provider-owned, immutable */
} VtResource;

Handing one across the boundary is `\mathcal{O}(1)` — sixteen bytes on a 64-bit target, never a serialization. The base vtable carries a reference-counting pair (retain / release) and versioned capability discovery (query_interface), the portable core of COM's IUnknown. Three laws do the heavy lifting (stated precisely, with their proofs and pins, in the ABI reference):

• Two-word law — sizeof(VtResource) is exactly two pointers; asserted at compile time in Rust and C++ and at runtime on the JVM.
• Copy-is-not-retain — copying the two words is free and confers no ownership; each owned copy is paid for with one retain and settled with exactly one release.
• Snapshot capture is `\mathcal{O}(1)` — mutable dictionaries hand consumers an immutable, structurally shared revision at operation start; copying the dictionary or holding a long-lived read lock violates the interface contract. Batched paging (node_edges / state_arcs, 256 entries recommended) keeps boundary crossings to `\lceil \deg(v) / 256 \rceil` per node expansion.

Interface catalog

Interfaces are named by 16-byte identifiers compared byte-for-byte and negotiated through query_interface with a consumer-supplied minimum version:

Base protocol version: VT_ABI_VERSION = 1. The full change rules — what may be added, what forks an identity, and the four distinct version counters — are the ABI evolution policy.

Who produces and consumes what

Documentation

Language packages

Nine language-native mirrors of the interop structs and constants live under bindings/, so non-C ecosystems consume the ABI idiomatically without generating from the header at build time:

Fortran · Go · Haskell · JavaScript · JVM · Lua · OCaml · Python · Swift

Each mirror is layout-checked against the canonical definitions by the repository's binding gates (scripts/generate-bindings.py and scripts/check-bindings.py at the repo root).

The optional entries-v1 surface is canonical in the Rust crate, C header, and generator-owned bundled C-header mirrors. Its generated conformance fixture pins status, flag, operation-order, and LP64/ARM32 layout values. Higher-level language adapters that do not yet expose a typed entries cursor continue to negotiate only the interfaces they model; entries-v1 is never inferred from a partial hand-written definition.

The executable contract

Three test suites in tests/ are the normative documents' teeth; CI runs them on every push (cargo test --locked -p vinary-tree-interop):

• tests/layout_contract.rs — exact sizes, alignments, and field offsets for every published type on the 64-bit and 32-bit ARM tiers; the two-word law; byte-exact interface identifiers; the Option<extern "C" fn> null niche that makes NULL-slot vtables one ABI.
• tests/discriminant_pins.rs — every enum discriminant and flag bit pinned exactly and matched wildcard-free, so adding a variant fails compilation until the evolution policy is consulted; zeroed reserved-field defaults.
• tests/vtable_evolution.rs — the query_interface negotiation surface against a hand-rolled provider, including the additive-evolution proof: a future, larger vtable remains consumable through its v1 prefix, discovered via struct_size.

Crate facts

Language adapter documentation

Every published adapter uses the same retained-resource laws while mapping ownership and failures into its host language:

The generated dictionary_entries_v1.tsv fixture pins entries-v1 identifiers, statuses, flags, operation order, and LP64/ARM32 layouts for adapter conformance.

The adapters are intentionally policy-free. Concrete dictionary and automaton APIs live in their project packages; these guides explain only resource representation, discovery, ownership, and safe handoff.