Rotations and upgrades

audience: operators

Rotation discipline at the coalition layer is thin: most rotations occur inside one member (a lattice or a standalone organism) or inside a composite organism or module. The coalition operator’s task is to republish the CoalitionConfig when any referenced component changes identity in a way that folds into COALITION_ROOT. This page lists the rotations that materially affect a coalition and the operation order for each.

For rotations inside a block-building lattice organism, follow the builder rotations page. For rotations inside a standalone organism, follow that organism’s own runbook.

Rotations that change a coalition’s fingerprint

Any of the following forces a new CoalitionConfig fingerprint. Publication is not optional: integrators compiled against the old fingerprint see ConnectTimeout on every handle until they recompile against the new one.

1. A referenced lattice’s stable id changes (retirement).
2. A referenced organism’s stable id changes (retirement of a standalone or composite organism).
3. A referenced composite organism’s OrganismConfig fingerprint changes and the coalition pinned the content hash (content, ACL, span, or TDX Measurements bump on a TDX-gated organism).
4. A module’s ModuleConfig fingerprint changes (content, ACL, or TDX Measurements bump).
5. The coalition’s lattice set changes (add or remove a lattice).
6. The coalition’s organism set changes (add or remove a standalone or composite organism).
7. The coalition’s module set changes (add or remove a module).
8. The coalition’s ticket issuer is added, rotated, or removed.
9. The coalition instance name changes (rare — effectively a retirement; see below).

Rotations that do not change a coalition’s fingerprint

• Committee member rotations inside a referenced member, under a stable per-member Config.
• Committee member rotations inside a composite organism or module, under a stable OrganismConfig / ModuleConfig.
• TDX Measurements republications that match the previously pinned value (i.e. the image was rebuilt from the same source).
• Per-member content-hash bumps (TDX Measurements rotations, ACL rotations) if organisms pin only the stable id, not the content hash. Organisms that pinned content hash do bump.

These are invisible to integrators at the coalition layer. Documented per-member or per-organism, not per- coalition.

Ordering a member retirement

When a referenced member’s stable id changes, follow this sequence.

1. Receive the retirement notification from the per- member operator via the multi-operator coalition change channel. The notification includes the old and new stable ids and the cutover time.
2. Prepare the new CoalitionConfig. Update the member’s reference in the CoalitionConfig definition. Re-derive the coalition fingerprint. Modules re-derive automatically because COALITION_ROOT has changed. Commissioned organisms referenced by the coalition re-derive only if they themselves span the retired member.
3. Redeploy modules under the new OrganismConfigs. Because each module’s content folds the coalition root, module fingerprints have bumped. Bring up new committee members on the new OrganismConfigs while old members continue on the old ones; rotate over.
4. Publish the new CoalitionConfig fingerprint on the handshake page and change channel.
5. Wait for integrators to recompile. Old- fingerprint handles time out (or, better, see a RetirementMarker from each retiring committee pointing at the replacement); integrators reach out if they miss the change.
6. Retire the old module deployments once the old CoalitionConfig is no longer in use by the integrators the operator cares about. Each committee emits a terminal RetirementMarker before shutdown.

Ordering a composite-organism or module upgrade

A composite organism or module’s Config may change for reasons other than upstream member retirements: new content parameters, TDX Measurements bump, ACL change.

1. Stand up the new deployment under the new OrganismConfig / ModuleConfig alongside the old.
2. Update any referencing coalitions’ CoalitionConfigs to reference the new fingerprint. Recompute each coalition fingerprint.
3. Publish each new CoalitionConfig.
4. Announce the change via the change channel, with migration notes. If any referencing coalition ships a Chronicle, its next commit records the rotation.
5. Retire the old deployment. The committee emits a RetirementMarker pointing at the new deployment so integrators rebind cleanly.

A transition window where old and new coexist is required; a hard cutover leaves every integrator timing out simultaneously.

Retiring a coalition

A coalition may be retired (renamed). Reasons:

• The composition has drifted far enough from the original intent that a clean break is preferable to incremental bumps.
• The set of operators participating in the coalition has reorganised.
• Branding or regulatory considerations.

Sequence:

1. Announce retirement with substantial lead time. Integrators relying on the coalition need weeks to migrate. A shipped Chronicle records the retirement in its next commit.
2. Stand up the replacement coalition (e.g. ethereum.superchain-v2026q2) with a fresh CoalitionConfig fingerprint and the desired composition.
3. Run both coalitions in parallel until most integrator traffic has migrated.
4. Retire the old coalition’s modules (committees emit RetirementMarkers pointing at the replacement coalition’s modules) once integrator traffic drops to zero or acceptable levels. Referenced organisms are independent of the retired coalition and continue if other coalitions or direct integrators still use them.
5. Publish a retirement note. The old CoalitionConfig fingerprint is formally deprecated; integrators still on it see ConnectTimeout once the old modules are down.

Do not reuse an instance name for a different composition. A retired coalition’s name is spent; reissuing it under a new composition would produce silent mis-bindings across the integrator base.

Cross-references

• Coalition overview
• Running an organism
• Multi-operator coalitions
• builder rotations