Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Federating under a coalition

audience: operators

A federated coalition is one whose referenced citizens — lattices, standalone organisms, or a mix — are operated by different teams. The blueprint does not make federation special: a CoalitionConfig references citizen stable ids regardless of who runs them. Coordination patterns succeed or fail based on a few out-of-band agreements.

This page catalogues the agreements. Federation provides a shared handshake and a coordination channel.

The blueprint minimum

The coalition operator needs the stable id of each referenced citizen. Any operator holding those ids can publish a CoalitionConfig including those citizens; there is no technical gate on referencing, and the CoalitionConfig does not require the per-citizen operator’s signature.

This is intentional. A stable-id reference is not a claim of authority over the citizen. A per-citizen operator objecting to a coalition reference has no technical recourse, and the reference also has no technical consequence: every confluence committee member still needs tickets from each per-citizen operator to bond into those citizens’ public surfaces.

What a federation agreement should cover

Documented even when trust between operators is high.

Notification cadence

  • Citizen retirements (stable-id bumps). The per- citizen operator notifies the coalition operator at least one business day ahead of a retirement.
  • Content-hash bumps that matter to confluences pinning content (MR_TD rotations on TDX-gated surfaces). Coordinate with any confluence operator whose pinning policy is affected.
  • Ticket rotations. When a per-citizen operator rotates their ticket-issuance root, confluence committee members need new tickets before cutover.
  • Retention changes. A citizen shortening retention of a public surface a confluence subscribes to breaks confluence replay. Notify the coalition operator and the confluence operator.

Ticket issuance for confluence committee members

The confluence committee reads each spanned citizen’s public surfaces and so requires per-citizen tickets. Agreements should cover:

  • Who issues. Each per-citizen operator issues tickets for confluence committee members, exactly as for any integrator.
  • Under what policy. Confluences usually need read- only tickets on specific surfaces (for a lattice: UnsealedPool, tally::Refunds; for an oracle organism: its feed stream). Scope accordingly.
  • Rotation schedule. Tickets expire. A rotation cadence matching the per-citizen operator’s standard schedule is acceptable; unannounced rotations are not.

Optional coalition-scoped ticket issuer

A federated coalition may ship a coalition-scoped ticket issuer (see ticket issuance). Components — confluences, modules, even external integrators — decide per-component whether to recognise its tickets. No component is required to. A federation agreement can document which components plan to recognise the coalition issuer, but recognition itself is always in each component’s own TicketValidator composition.

Confluence governance

When multiple citizens contribute inputs to one confluence, the confluence is itself a governance concern. Agreements cover:

  • Who runs the committee? Often the coalition operator; sometimes a subset of the per-citizen operators; occasionally a separate team. Confluence identity is coalition-independent: the same committee serves every coalition that references it.
  • Who decides on Config bumps? The confluence operator, informed by the affected per-citizen operators and by referencing coalitions.
  • Conflict resolution. The escalation path when the confluence commits a record one per-citizen operator disputes (an attribution split, a cross-feed correlation).

None of this is in-protocol; all of it is contract. The coalition does not arbitrate.

Publishing a federated coalition

The handshake page makes federation visible:

  • Per-citizen links. Each LatticeConfig or OrganismRef reference includes a link to the corresponding per-citizen operator’s handshake page.
  • Per-confluence links. Each ConfluenceConfig reference links to the confluence operator’s handshake.
  • Operator roll call. A table listing each operator and the roles it holds (lattice, organism, confluence, module, ticket issuer, coalition).
  • Federation change channel. Typically a shared channel across all participating operators rather than the coalition operator’s individual channel, so that citizen-side changes are visible to every participant in-flight.

What federation does not change

  • Mosaik-level security. Each citizen’s ACL is unchanged. Each confluence’s ACL is unchanged.
  • Atomicity. No cross-citizen atomic commit. Federation does not provide it; no contract can.
  • Integrator ergonomics. Integrators still compile one CoalitionConfig; a federated coalition is indistinguishable from a single-operator coalition at the handle API.

A healthy federated-coalition checklist

  • Each referenced per-citizen operator has been notified.
  • Each referenced confluence operator has been notified.
  • Ticket issuance for confluence committee members is documented per citizen.
  • The change channel covers citizen retirements, content-hash bumps, ticket rotations, and confluence config changes.
  • The handshake page lists every operator and their role.
  • The coalition’s modules and any referenced confluences have a documented stall / degradation policy consistent with each spanned citizen’s expected availability.

Cross-references