Binding to a confluence

audience: integrators

A confluence is a mosaik organism whose public surface spans multiple citizens — some combination of block-building lattices and standalone organisms. Binding is the same as for any organism — Confluence::<D>::verb(&network, &Config) — with two small differences in what the operator owes the integrator and in failure-mode reasoning.

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

One handle per verb

Each confluence 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 confluence's output.
let intents = intents::Router::<Intent>::routed(&network, &INTENTS_CONF).await?;

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

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

What the confluence operator owes you

A confluence operator (who may coincide with the coalition operator) is responsible for:

The ConfluenceConfig fingerprint, publishable and byte-for-byte compilable.
The ordered list of spanned citizen references the confluence depends on — lattices, standalone organisms, or any mix. Cross-check each against the corresponding per-citizen operator’s publication.
MR_TDs if the confluence is TDX-gated.
The confluence’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 citizen 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 confluence 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 confluence consumers

Three properties to internalise before reading a confluence.

The confluence commit lags the upstream commits

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

Partial evidence is a valid confluence commit

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

A stalled confluence does not block upstream pipelines

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

What to do when your agent relies on a confluence that changes

Confluence Config fingerprints change for three reasons:

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

In every case the old handle starts failing with ConnectTimeout — or, better, the confluence 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 ConfluenceConfig) and restart.

AI