Who this book is for

audience: all

The book has three audiences, the same three the zipnet and builder books use, scoped to multi-citizen govs rather than single lattices or single organisms:

• Integrators — external developers whose agent binds across citizens (lattices, standalone organisms), into a confluence, or into a gov’s basic services.
• Operators — teams standing up and running a gov (a confluence, a standalone organism, a basic service, a federated multi-citizen composition, or any combination).
• Contributors — engineers commissioning a new confluence, commissioning a new class of mid-rung composition, specifying a new basic service, or extending the gov-level composition model.

Each page declares its audience on the first line (audience: integrators | operators | contributors | both | all) and respects that audience’s conventions. When content serves more than one audience, use both or all, and structure the page so each audience gets its answer in the first paragraph.

Integrators

Who. External Rust developers whose mosaik agent binds across multiple citizens of a gov, or into a confluence’s public surface. Typical roles:

• Cross-chain searchers — placing bundle bids on several block-building lattices’ offer organisms and reconciling paired-leg outcomes.
• Multi-chain wallets — submitting intents via zipnet on several lattices and reading refund attestations across their tally organisms.
• Oracle and attestation consumers — subscribing to standalone organisms (price feeds, attestation aggregators, identity substrates) referenced by a gov.
• Analytics agents — aggregating per-citizen public surfaces across any mix of lattices and organisms into a single view.
• Confluence consumers — reading from an intent router, a shared ledger, a cross-chain oracle aggregator, or any other commissioned confluence.
• Basic-service consumers — reading the gov’s Atlas, aligning to its Almanac, auditing its Chronicle, or presenting a Passport.

They do not run committee servers (operator role); they do not modify organism, lattice-organism, or confluence crates (contributor role).

Assumed background.

• Async Rust, the mosaik book, and — for block-building use cases — the builder book.
• Per-organism ergonomics (Organism::<D>::verb(&network, &Config) constructors); the gov layer extends this pattern rather than replacing it.
• Own Arc<Network> lifecycle.
• Zipnet book if submission-layer anonymity is relevant.

Not expected.

• Citizen internals beyond the corresponding organism or lattice book.
• A full census of confluences or organisms unused by their workload.
• Re-exposition of mosaik, zipnet, or builder primitives.

Concerns.

• Which citizens and which confluences the workload touches.
• Which GovConfig to compile in.
• How to reconcile partial outcomes across citizens.
• What the gov operator owes out of band: the GovConfig, citizen fingerprints, and MR_TDs for any TDX-gated confluences or organisms.

Tone. Code-forward and cookbook-style. Snippets are rust,ignore, self-contained, and meant to be lifted. Public API surfaces are listed as tables. Pitfalls are called out inline. Second person throughout.

Entry point. Quickstart — bind many citizens from one agent.

Operators

Who. Teams running one or more of:

• Confluence operators — running committee members for an intent router, shared ledger, attestation aggregator, or other commissioned confluence.
• Basic-service operators — running committee members for an Atlas, Almanac, Chronicle, or Passport.
• Standalone-organism operators — running committee members for an organism living directly on the universe and referenced by a gov as a citizen.
• Lattice federators — publishing a GovConfig that names a set of lattices they (or a peer coalition) run.
• Multi-role operators — running several of the above simultaneously.

Assumed background.

• Linux ops, systemd units, cloud networking, TLS, Prometheus.
• Builder operator overview and comfort with lattice-level runbooks when the gov includes block-building lattices. The gov layer adds runbooks for confluences, basic services, and federated composition; it does not replace per-citizen runbooks.
• Not expected to read Rust source. Any Rust or protocol detail that is load-bearing for an operational decision belongs in a marked dev-note aside that may be skipped.

Not expected.

• Confluence or organism internals.
• Integrator-side ergonomics.

Concerns.

• What to run, on what hardware, with what environment variables, for a confluence, basic service, or standalone organism.
• How to publish a GovConfig that references citizens run by other operators.
• What cross-operator agreements federation requires.
• How to rotate a confluence’s committee without breaking the gov’s fingerprint.

Tone. Runbook register. Numbered procedures, parameter tables, one-line shell snippets. Pre-empt the obvious what-ifs inline. Avoid “simply” and “just”. Each command is either safe verbatim or clearly marked as needing adaptation.

Entry point. Quickstart — stand up a gov.

Contributors

Who. Senior Rust engineers with distributed-systems and cryptography backgrounds, commissioning a new confluence, a new class of mid-rung composition, a new basic service, or extending the gov-level composition model itself.

Assumed background.

• The mosaik book, zipnet book, builder book, and the corresponding CLAUDE.md convention files.
• Async Rust, modified Raft, threshold cryptography, TDX attestation flows, and organism-level primitives.
• Familiarity with at least one production organism shape (a zipnet deployment, a tally organism, an oracle or attestation organism on another production universe) and with the builder book’s cross-chain chapter.

Not expected.

• Re-exposition of mosaik, zipnet, or builder primitives.
• Integrator ergonomics unless they drive a design choice.
• Motivation for cross-citizen coordination in the abstract.

Concerns.

• The confluence pattern and when to use it versus a cross-citizen integrator.
• Composition with lattice organisms, standalone organisms, and basic services.
• Invariants a confluence must hold and where they are enforced.
• Interaction of gov-level derivation with existing LatticeConfig or organism Config fingerprints.
• Behaviour when a citizen referenced by a gov upgrades.
• Extension points: which trait, which test, which fingerprint field.

Tone. Dense, precise, design-review. ASCII diagrams, pseudocode, rationale. rust,ignore snippets and structural comparisons without apology.

Entry point. Designing governments on mosaik.

Shared writing rules

• No emojis.
• No exclamation marks outside explicit security warnings.
• Link the mosaik, zipnet, and builder books rather than re-explaining their primitives.
• Tag security-relevant facts with a visible admonition, not inline prose.
• Keep the three quickstarts synchronised. When the gov shape, a confluence’s public surface, a basic service’s specification, or the composition handshake changes, update integrators, operators, and contributors quickstarts in one pass.
• Use the terms in Glossary consistently. Do not coin synonyms for gov, lattice, citizen, confluence, organism, universe mid-page.
• Minimise ornament. No epigraphs, no literary or sci-fi name-drops, no rhetorical flourishes. Restate the non-authority stance where it is load-bearing; otherwise keep prose dense.