Who this book is for

audience: all

The book has four audiences, listed in order of proximity to the thesis (AI and self-organization):

• AI — authors, human or agent, of self-organizing agent populations that coordinate on mosaik without a central actor. The central audience.
• Integrators — external developers whose agent binds across citizens (lattices, standalone organisms), into a confluence, or into a coalition’s basic services.
• Operators — teams standing up and running a coalition (a confluence, a standalone organism, a module, a multi-operator coalition, 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 coalition-level composition model.

Each page declares its audience on the first line (audience: integrators | operators | contributors | ai | 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.

AI

Who. Authors — human or agent — of populations of autonomous agents that bind, coordinate, and self-organize on mosaik. Typical roles:

• Agent authors — building a single AI agent as a mosaik integrator or as a standalone organism.
• Swarm authors — composing a population of agents plus the organisms that observe, score, match, or attest them, under a coalition handshake.
• Emergent-coordination designers — specifying the reputation loops, coordination markets, attestation fabrics, or stigmergic collections through which the population self-organizes.
• Agents reading the book directly — the book’s register assumes a reader who may be an LLM-class agent following references; snippets are self-contained enough to be lifted.

Assumed background.

• Async Rust (or another language via FFI to a mosaik Network handle) and the mosaik book.
• Familiarity with multi-agent coordination as a concept. The section does not re-derive it.
• The non-AI audiences’ framing of coalitions, confluences, and modules is referenced, not repeated.

Not expected.

• AI-system internals (model architectures, training loops, inference stacks). The agent’s policy is a black box from mosaik’s perspective.
• A theory of intelligence, consciousness, or agency. The section speaks only about composition.

Concerns.

• Which of the four agent shapes fits the workload (integrator, standalone organism, confluence member, swarm-as-confluence).
• How to expose an agent’s outputs as a mosaik public surface.
• How a population of agents reaches coordinated outcomes without a supra-agent authority.
• Identity hygiene across shape changes and operational rotations.

Tone. Code-forward and pattern-forward. Snippets are rust,ignore or pseudocode. No sci-fi analogies, no hype vocabulary; technical register. Patterns are described as compositions of primitives the rest of the book already specified.

Entry point. What a coalition gives AI agents.

Integrators

Who. External Rust developers whose mosaik agent binds across multiple citizens of a coalition, 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 coalition.
• 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 coalition’s Atlas, aligning to its Almanac, or auditing its Chronicle.

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 coalition 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 CoalitionConfig to compile in.
• How to reconcile partial outcomes across citizens.
• What the coalition operator owes out of band: the CoalitionConfig, 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.
• Module operators — running committee members for an Atlas, Almanac, or Chronicle.
• Ticket-issuer operators — running a coalition-scoped mosaik ticket issuer, when the coalition ships one.
• Standalone-organism operators — running committee members for an organism living directly on the universe and referenced by a coalition as a citizen.
• Coalition operators — publishing a CoalitionConfig that names a set of citizens.
• 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 coalition includes block-building lattices. The coalition layer adds runbooks for confluences, modules, and multi-operator 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, module, or standalone organism.
• How to publish a CoalitionConfig that references citizens run by other operators.
• What cross-operator agreements a multi-operator coalition requires.
• How to rotate a confluence’s committee without breaking its 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 coalition.

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 coalition-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 modules.
• Invariants a confluence must hold and where they are enforced.
• Interaction of coalition-level derivation with existing LatticeConfig or organism Config fingerprints.
• Behaviour when a citizen referenced by a coalition 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 coalitions 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 coalition shape, a confluence’s public surface, a basic service’s specification, the ticket-issuance shape, 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 coalition, lattice, citizen, confluence, organism, universe mid-page.
• Minimise ornament. No epigraphs, no literary or sci-fi name-drops, no rhetorical flourishes.