Language-binding documentation hub

The map of everything written about liblevenshtein's ABI and language bindings, in reading order. Two layers exist and never duplicate each other: the family canon (hosted in the standalone vinary-tree-interop repository) specifies the shared resource ABI every Vinary Tree project speaks; the project corpus (this directory and its satellites) specifies what liblevenshtein builds above it — the llev_* C surface, the resource consumer, the cursor laws, and the JS/WASM topology.

Reading order

1. Decide-and-orient: docs/language-bindings.md — the architecture decision (small versioned C resource ABI + generated constants + hand-written facades; why not UniFFI), the three layers, the snapshot/marshalling contracts, tiers, distribution, and platform policy.
2. The family canon (normative across the core project family): interop README — the portal · ABI reference — the annotated header walk with the refcount/paging/snapshot laws · evolution policy — the four version counters and the additive-versus-fork rules · security model — zones, containment, validation duties.
3. The project corpus (this layer):

Document	What it specifies
c-abi-reference.md	All 36 llev_* functions: signatures, preconditions, exact returnable status sets, ownership, thread safety, complexity; the 13-value status table and its VtStatus mapping; the lease protocol with literate batch-loop and reducer pseudocode; a compile-checked complete C consumer.
resource-consumer.md	The safe-Rust layer under the C ABI: intake (retain-validate-else-release), ForeignNode domains, the CallGate (VT-GATE-1..3), the status wire rule and fault latch, the total BindingError map, and the two-pass arena fixup.
collection-protocols.md	The approved native-Rust and foreign-language collection design: current gaps, generic snapshot traversal, idiomatic Iterator/Set/Map surfaces, batched ABI acceleration, lifecycle rules, gates, and implementation work packages. It is a roadmap, not a claim that every adapter already ships.
wasm-topology.md	The JS exception to modular packaging: the @vinary-tree/javascript-runtime umbrella, the three runtime paths, the runtime-identity guard, WASI preopen policy, and panic-versus-status discipline.
../theory/snapshot-semantics.md	The cursor laws S1-S6 as display math, the $\mathcal{O}(1)$-capture argument from path-copied revisions, the partial-persistence classification, the refcount lineage, and the law ↔ model ↔ test correspondence table.
../security/binding-trust-model.md	The family trust model instantiated for this consumer: boundary(), the bounded error channel, the decoded status wire, lease-refusal as UAF prevention, duty status per hostile-input class.
FINDINGS_LEDGER.md	The scientific ledger of confirmed binding findings (LLEV-B1…), append-only, with fix commits and verification.
../releasing-language-bindings.md	The release process: publish-order DAG, registry coordinates, credentials, pin-coherence preconditions, gates.

4. Machine-readable governance (the sources the gates enforce):

Artifact	Role
bindings/api.json	The single source of truth: versions, status/algorithm/order enums, the 36 modeled cFunctions, marshalling and snapshot law strings, forbidden owned objects, the canonical query snapshot fixture, and entries-v1 identity/status/flag/operation/layout pins. scripts/generate-bindings.py emits the headers, constants, and fixtures; --check pins them in CI.
bindings/api-surface-map.json	The per-facade completeness model driving the coverage matrix.
bindings/conformance/	Generated conformance fixtures: the query-start snapshot oracle, entries-v1 constants and LP64/ARM32 layouts, and the facade completeness matrix.
scripts/check-bindings.py	The contract gate: symbol parity model ↔ Rust ↔ header, entries-v1 metadata/header/mirror/fixture agreement, forbidden retired APIs, umbrella identity guard, coordinates, feature-alias policy.
scripts/generate-binding-guides.py	Idempotently renders liblevenshtein's shared operational contract, exhaustive modeled facade-symbol index, modeled type/protocol exposure, and intended-usage paths in every shipped facade guide while preserving its hand-written tutorial.
scripts/check-binding-docs.py	Fails closed on an undocumented declared language, missing required topic, stale generated section, missing modeled public symbol, absent intended-usage table or executable example, untagged code fence, placeholder, or broken local link.
docs/verification/ABI_INVARIANTS.tsv	The canonical invariant registry (VT-LIFE, VT-QI, VT-GATE, VT-ABI, and the wave-W3 rows as they land) tying each law to its model, test, and gate.

5. Diagrams: the binding suite lives in docs/diagrams/bindings/ (sources + committed SVGs, rendered by docs/diagrams/render.sh bindings): the four canon diagrams (vt-structs class, interface negotiation, evolution timeline, trust zones) and the ten project diagrams (three-layer architecture, family data flow, registry topology, resource handoff, lease lifecycle, cursor-lease FSM, resource-lifecycle FSM, reducer flow, call-gate serialization, WASM umbrella deployment).

Language coverage matrix

Every link is a shipped package guide rather than an implementation-only directory. A shared-runtime guide contains separate executable idioms for each language named in its row. A dash reports current absence; it is an open implementation and documentation cell unless the generated family-completeness-matrix.tsv contains a reviewed architectural inapplicability proof. Absence by itself is never such a proof.

Language/runtime	liblevenshtein	libdictenstein	lling-llang	duallity	llattice	interop
C	guide	ABI and guide	ABI and guide	guide	—	native contract
C++	guide	guide	guide	guide	—	native contract
Python	guide	guide	—	—	—	adapter guide
Java, Kotlin, Scala	JVM guide	JVM guide	—	—	—	JVM adapter
Clojure	guide	guide	—	—	—	Delegates to JVM
JavaScript, TypeScript, ClojureScript	guide	guide	guide	guide	—	adapter guide
C# / .NET	guide	guide	—	—	—	Included in the .NET package
Go	guide	guide	—	—	—	adapter guide
Swift	guide	guide	—	—	—	adapter guide
Ruby	guide	guide	—	—	—	Resource pair is mediated by project gems
Fortran	guide	guide	—	—	—	adapter guide
OCaml	guide	guide	—	—	—	adapter guide
Haskell	guide	guide	—	—	—	adapter guide
Lua	guide	guide	—	—	—	adapter guide
Raku	—	—	—	—	—	—

The llattice crate currently ships only its optimized native Rust API. That is the observed state, not a permanent inapplicability decision: the follow-up campaign must expose host-implementable lattice interfaces wherever the target runtime can uphold the ownership, callback, concurrency, and algebraic-law contracts. Its missing foreign-language guides remain explicit family-matrix gaps until those surfaces ship or receive reviewed architectural proofs.

Collection-protocol parity is tracked separately from package availability. The collection-protocol design records the current gaps and makes the optimized pure Rust API the baseline for Java Set/Map, .NET collection interfaces, Python collection ABCs, and the corresponding idioms in every applicable binding. Per-language guides continue to describe only functionality that has actually passed its conformance gates.

The family, one hop away

Per the separation-of-concerns rule, each repository documents its own ABI surface; these are the sibling entry points this corpus cites:

• vinary-tree-interop (standalone repository) — the canon trio above.
• libdictenstein (producer): binding hub · ldict_* C-ABI reference · resource producer · FFI boundary security
• lling-llang (WFST producer + consumer): lling_* C-ABI reference · resource ABI architecture · ABI trust model
• duallity (dictionary consumer, WFST producer): resource ABI and bindings · language-bindings guide · threat model
• llattice (algebraic lattice interfaces): crate and native Rust API · foreign provider and facade documentation is an explicit follow-up deliverable.

(Sibling links are absolute — these are separate repositories; the sibling documents land with their own waves of this program.)