Atomicity boundary
audience: contributors
This chapter states what the coalition layer does and does not guarantee about atomicity, supplying one reference page for design reviews of new confluences or extensions to the coalition model.
The rules are inherited from zipnet and builder. The coalition layer introduces no new atomicity primitive; it makes the inherited boundary legible one rung higher.
What the coalition layer does not provide
The coalition layer does not provide:
- Cross-Group atomicity inside a citizen. Rejected by builder for lattices and by each organism’s own design for standalone organisms. Two organisms commit independently and subscribe to each other’s public surfaces.
- Cross-citizen atomicity inside a coalition. Rejected by this blueprint. Two citizens in the same coalition commit independently and a confluence subscribes to both.
- Cross-coalition atomicity. Rejected by this blueprint. Two coalitions coexist on the shared universe and have no shared consensus unit.
- Multi-confluence atomicity. Rejected by this blueprint. Two confluences referenced by the same coalition each commit to their own Group; integrators that need joint commits join by key.
The rejection is load-bearing at every rung. Admitting one atomicity primitive at any rung forces every rung below to carry it, collapsing the trust and operational boundaries the rungs were designed to isolate.
What the coalition layer does provide
The coalition layer provides, as a consequence of the composition discipline:
- Per-component atomicity. Every organism, every confluence, and every module commits atomically within its own Group. Mosaik’s Raft variant guarantees single-Group atomicity.
- Determinism of replay. Given the commit logs of all components the coalition references, each component’s per-key decision is reproducible. The evidence pointers confluences carry make cross-component replay legible.
- Independent auditability. A consumer verifying a confluence’s commit need trust only the spanned citizens’ own commit logs (and the confluence’s committee, to whatever its trust shape permits). They do not need a coalition-wide replay to audit one confluence’s decision.
- Provenance (if Chronicle is shipped). Not
atomicity, but a record of coalition-level decisions
over time: which
CoalitionConfigs were published when, which confluences were referenced or unreferenced, which modules were added or retired. Audit trail, not atomicity.
What integrators and operators must design around
Three recurring realities.
Partial outcomes across citizens
An integrator placing paired bundles on two lattices, or correlating an oracle tick with a lattice auction outcome, must tolerate partial observation: citizen A commits, citizen B does not. The coalition layer surfaces this, it does not mitigate it. Every integrator driver spanning citizens carries reconciliation logic (post-bond collateral, on-chain HTLCs, searcher-level risk management, timestamp tolerance windows — whichever matches the domain).
Staggered commits through confluences
A confluence’s commit for (citizen_id, clock_event)
lags the upstream citizens’ own commits for that event by
at least one Raft round inside the confluence’s
committee. Consumers reading both treat the citizen commit
as ground truth and the confluence commit as derived
aggregation.
Citizen identity bumps
A citizen’s stable id changes on retirement; its content
hash bumps more often (ACL rotations, MR_TD bumps). A
coalition that references that citizen sees its modules
re-derive on stable-id bumps (because COALITION_ROOT
changes); confluences re-derive only when they themselves
span the bumped citizen. During the transition, old and
new deployments may coexist. If the coalition ships a
Chronicle, the next Chronicle entry records the
transition.
Promotion path if atomicity is genuinely required
If a concrete use case forces atomicity across components:
- If it’s one lattice, two organisms: design a lattice organism that owns both decisions. That is the same answer builder topology-intro gives.
- If it’s one coalition, two citizens: design a confluence that owns both decisions, subscribing to the two citizens’ relevant public surfaces. The state machine will commit one atomic record per event-pair; the two citizens themselves still commit independently, but the confluence’s commit is the authoritative joint fact. HTLC-style commit semantics live inside the confluence’s state machine, not across citizens.
- If it’s two coalitions: the cross-coalition commit is a confluence folding the relevant citizen references directly; both coalitions reference that confluence independently. No cross-coalition consensus is needed because the confluence is coalition-independent.
In every case the atomicity primitive lives inside one Group, not across Groups. This is the rule the whole ladder obeys.