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 composite organisms 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 member. 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-member atomicity inside a coalition. Rejected by this blueprint. Two members in the same coalition commit independently and a composite organism subscribes to both.
- Cross-coalition atomicity. Rejected by this blueprint. Two coalitions coexist on the shared universe and have no shared consensus unit.
- Multi-organism atomicity. Rejected by this blueprint. Two composite organisms 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 — standalone, composite, or 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 composite organisms carry make cross-component replay legible.
- Independent auditability. A consumer verifying a composite organism’s commit need trust only the spanned members’ own commit logs (and the composite organism’s committee, to whatever its trust shape permits). They do not need a coalition-wide replay to audit one composite organism’s decision.
- Provenance (if Chronicle is shipped). Not
atomicity, but a record of coalition-level decisions
over time: which
CoalitionConfigs were published when, which composite organisms 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 members
An integrator placing paired bundles on two lattices, or correlating an oracle tick with a lattice auction outcome, must tolerate partial observation: member A commits, member B does not. The coalition layer surfaces this, it does not mitigate it. Every integrator driver spanning members carries reconciliation logic (post-bond collateral, on-chain HTLCs, searcher-level risk management, timestamp tolerance windows — whichever matches the domain).
Staggered commits through composite organisms
A composite organism’s commit for
(member_id, clock_event) lags the upstream members’ own
commits for that event by at least one Raft round inside
the composite organism’s committee. Consumers reading
both treat the member commit as ground truth and the
composite-organism commit as derived aggregation.
Member identity bumps
A member’s stable id changes on retirement; its content
hash bumps more often (ACL rotations, TDX Measurements bumps). A
coalition that references that member sees its modules
re-derive on stable-id bumps (because COALITION_ROOT
changes); composite organisms re-derive only when they
themselves span the bumped member. 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 members: design a composite organism that owns both decisions, subscribing to the two members’ relevant public surfaces. The state machine will commit one atomic record per event-pair; the two members themselves still commit independently, but the composite organism’s commit is the authoritative joint fact. HTLC-style commit semantics live inside the composite organism’s state machine, not across members.
- If it’s two coalitions: the cross-coalition commit is a composite organism folding the relevant member references directly; both coalitions reference that composite organism independently. No cross-coalition consensus is needed because the composite organism is coalition-independent.
In every case the atomicity primitive lives inside one Group, not across Groups. This is the rule the whole ladder obeys.