Hibana brings choreographic programming and runtime-enforced protocols to Rust

Hibana, a newly published open-source crate for Rust, lets developers describe a multiparty interaction once as a global choreography and then have every participating endpoint police its own behaviour against that description at runtime. According to the project's README on GitHub, which reached Hacker News's front page, the choreography is compiled down — "projected" — into a compact program for each role, and every send, receive or routing decision must match that program before the runtime commits progress.

How the model works

The workflow runs from one choreography to per-role programs to running endpoints. A developer writes the protocol once, calls project() once per role to obtain compact RoleProgram descriptors, attaches each role to a session identifier, and then drives the endpoint through send, recv and offer operations. Each operation either commits exactly one step the projected program permits, or fails the session generation. There is no path to an out-of-protocol step.

A key design choice is that protocol state lives in small descriptors rather than in a distinct Rust continuation type for every protocol state. The README argues this keeps endpoint types from ballooning as protocols grow: one projected artifact can be reused across many isolated sessions without multiplying endpoint types, and repeated regions add no iteration fields to endpoints, descriptor rows or frame headers. Freshness instead comes from the projected execution rules combined with carrier FIFO ordering, replay exclusion and generation isolation.

The protocol language

Choreographies are assembled from a small set of combinators in the hibana::g module: send for a single asynchronous message, seq for ordering, par for independent arms that may progress concurrently, route for a choice between two arms with an explicit resolver owning non-message decisions, and roll for a guarded structural region that can re-enter. The Projectable trait implemented by choreography values is sealed, so only Hibana's own constructors can produce them.

Projection doubles as a checking pass. The README states it rejects unsupported route shapes, ambiguous simultaneous operations on one endpoint, conflicting parallel lanes, empty parallel arms and unguarded re-entry — malformed protocols fail at projection time rather than in production.

The repository ships a self-checking ping_pong example, runnable with cargo run --example ping_pong, in which two roles exchange a u32 in sequence. The example is executed by the release gate and demonstrates the full loop: caller-owned runtime storage, an in-memory transport, both roles attached to one session, and endpoints driven with send() and recv().

Semantics and integration

Three properties define the model. Multiparty means the peer, direction and order for each interaction come from one choreography projected for every role. Asynchronous means a successful send transfers a frame to the carrier without waiting for the remote receive. Affine means one live endpoint owner can advance a projected step at most once — an endpoint may be dropped, but it cannot be cloned or used to publish duplicate progress.

Transport is deliberately neutral: carriers implement a five-operation Transport trait, and the same public API is exposed on hosted and embedded targets. The crate is unconditionally no_std, needs no allocator and uses caller-provided storage. It has no normal dependencies, uses Rust 2024, and requires stable Rust 1.95 or newer.

Explicit limits and boundaries

Roles cover the complete one-byte domain, 0 to 255, allowing up to 256 participants, while event identities are capped at 65,535 and program images at 65,535 bytes for the global image and per role image. Storage is derived from actual events and local participants; the runtime does not reserve a full 256-entry role table.

The README is unusually direct about what the crate does not guarantee. Hibana is not a network stack and not a distributed algorithm — it enforces the protocol at each attached endpoint, and lifting that local result to a distributed guarantee depends on stated carrier, deployment, codec and scheduling conditions. Splitting a protocol across several sessions also changes the boundary: Hibana checks each session, not the original choreography as a single global protocol.

Why it matters

Choreographic programming — describing a distributed protocol once, globally, instead of role by role — has been largely a research pursuit. Hibana packages the idea for a mainstream systems language under hard practical constraints: no allocator, no standard library, caller-provided memory and a single transport abstraction. That combination makes it plausible for embedded and resource-constrained targets, not just servers.

Just as notable is the candour of the framing. Rather than promising end-to-end correctness, the project pins down exactly what it enforces locally and which external conditions a deployment must satisfy for a distributed result. Combined with projection-time rejection of malformed choreographies, that clarity is what separates a usable enforcement tool from a research artifact, and it gives Rust teams building multiparty protocols a concrete way to make protocol violations fail loudly at the endpoint.