Binding to an organism

audience: integrators

An organism referenced by a coalition can be a standalone organism (living directly on the universe) or a composite organism whose public surface spans multiple members — some combination of block-building lattices and standalone organisms. Binding is the same in every case — Organism::<D>::verb(&network, &Config) — with two small differences in what the operator owes the integrator and in failure-mode reasoning when the organism is composite.

The same reasoning applies to a coalition’s modules (Atlas, Almanac, Chronicle, Compute, Randomness) — each is a coalition-scoped organism with a well-known shape.

One handle per verb

Each organism exposes one or two public primitives. A read-only integrator typically needs exactly one handle; a write-side integrator a second. Typical shapes:

// Read-only: subscribe to the organism's output.
let intents = intents::Router::<Intent>::routed(&network, &INTENTS_CONF).await?;

// Write-side (if the organism publishes a write stream):
let publish = intents::Router::<Intent>::publish(&network, &INTENTS_CONF).await?;

Verb names come from the organism’s own crate docs, following the same convention as every organism (Offer::bid, Tally::read, Zipnet::submit, Aggregator::read, Atlas::read).

What the organism operator owes you

An organism operator (who may coincide with the coalition operator) is responsible for:

The OrganismConfig fingerprint, publishable and byte-for-byte compilable.
The ordered list of spanned member references the organism depends on — lattices, standalone organisms, or any mix. Cross-check each against the corresponding per-member operator’s publication.
TDX Measurements if the organism is TDX-gated.
The organism’s state-machine version / signature. A bump surfaces as ConnectTimeout on compiled handles; the change channel warns ahead.
A failure-mode statement. Whether a stall in spanned member A causes a commit with partial evidence or an event stall. Documented in the crate’s composition-hooks page.
A retirement commitment. Before shutting the committee down, the organism emits a RetirementMarker on its public stream pointing at a replacement (if any). Watch for it rather than timing out blindly.

Failure-mode reasoning for composite-organism consumers

Three properties to internalise before reading a composite organism.

The composite commit lags the upstream commits

A composite organism’s (member_id, slot) commit is observable only after the underlying member commits are observable, plus one Raft round inside the organism’s committee. Latency-sensitive consumers read the upstream member surfaces directly and use the composite organism only for the aggregated view.

Partial evidence is a valid composite-organism commit

Depending on the organism’s stall policy, a commit may reflect inputs from only some spanned members. The commit carries evidence pointers; checking the pointers indicates which members’ inputs were present. Do not assume every spanned member contributed to every commit.

A stalled composite organism does not block upstream pipelines

If the organism’s committee loses majority or lags, the spanned members’ pipelines are unaffected. Fall back to binding per-member handles directly; the organism’s precomputation is a convenience, not a dependency.

What to do when your agent relies on an organism that changes

Organism Config fingerprints change for three reasons:

Organism upgrade. The organism’s content, ACL, or spanned member set changed; its fingerprint bumps independently.
Upstream member retirement. A member the organism spans published a new stable id; the organism inherits the change if it pinned the old stable id.
Upstream member content bump (only if pinned). If the organism pinned the upstream content hash, an TDX Measurements or ACL bump in the upstream bumps the organism’s fingerprint.

In every case the old handle starts failing with ConnectTimeout — or, better, the organism emits a RetirementMarker on its stream pointing at the replacement. The operator’s change channel should warn ahead; the integrator’s process should include a path to recompile against the new CoalitionConfig (or OrganismConfig) and restart.

ai on mosaik