Basic services

audience: contributors

Atlas, Almanac, Chronicle, Compute, Randomness.

A basic service (also called a module) is a coalition-scoped organism whose shape is specified once in the blueprint so every instance means the same thing across coalitions. Each is derived under COALITION_ROOT.derive("module").derive(name) and exposes only mosaik primitives — Stream, Group, and Collection variants (see docs.mosaik.rs). The blueprint adds no types for a module beyond its OrganismConfig.

None of the five is mandatory. A coalition may ship any subset. If a coalition ships a service named “Atlas”, it must have the shape on this page; a service named “Atlas” with a different shape is a bug, not a variant.

Two of the five — Compute and Randomness — have an additional market-for-supply structure: the module’s committee schedules and commits, but the work is discharged off-module by separate providers that compete to register. Atlas, Almanac, and Chronicle do their own work inside the committee.

Fix the shapes. Leave the catalogues open.

Atlas

Directory of the coalition’s members. Every coalition bigger than a single member benefits from one; cheapest module to operate.

Public surface: Map<MemberId, MemberCard> where MemberCard carries the member’s role, stable id, endpoint hints, ticket-issuance root, and any TDX Measurements pins.

OrganismConfig folds the coalition root (via .derive("module").derive("atlas")), the ordered list of members it catalogues, and the Atlas committee’s ACL.

Trust shape: majority-honest, typically non-TDX.

When to ship: almost always. When to skip: single-member coalitions.

Almanac

Shared clock beacon. Composite organisms correlating facts across members need one.

Public surface: Stream<AlmanacTick> where each tick carries a monotonic seq: u64 and a per-member timestamp vector as an advisory correlation hint.

OrganismConfig folds the coalition root under "almanac", the tick cadence, and the committee’s ACL.

Trust shape: majority-honest. Ticks are ordering markers; the timestamp vector is not a cryptographic timestamp.

When to ship: more than one cross-member correlator. When to skip: members that correlate on their own clocks only.

Chronicle

Tamper-evident audit log of coalition actions: publications, rotations, retirements, membership changes, module upgrades.

Public surface: Stream<ChronicleEntry> where each entry carries a monotonic seq, a ChronicleKind, the coalition fingerprint at commit time, a structured payload, and per-member signatures in addition to the committee’s quorum signature. The committee also periodically commits a blake3 digest of the stream to an external settlement contract.

OrganismConfig folds the coalition root under "chronicle", the committee ACL, the entry schema version, and the external anchor contract address.

Trust shape: tamper-evidence holds while either the on-chain anchor path is uncompromised, or at least one honest ex-member’s signed archive survives. Retroactive rewriting requires compromising both.

When to ship: multi-operator coalitions; coalitions with contested lineage; coalitions needing externally verifiable provenance.

Compute

Scheduler and registry for compute grants. Coalition members submit requests; the committee matches them to registered providers; providers run the workloads and commit usage logs.

Compute is the book’s reference case for a market-for-supply basic service. The module commits the match. The compute itself runs on a separate provider. The split is deliberate: the coalition’s trust boundary ends at the scheduling commit; the provider is bonded separately through mosaik’s normal ACL.

Public surface:

• Stream<ComputeRequest> — write-side; coalition members submit here.
• Collection<RequestId, ComputeGrant> — the committee’s scheduled allocations.
• Collection<ProviderId, ProviderCard> — registered providers.
• Stream<ComputeLog> — provider-committed usage after a workload runs.

The data types:

pub struct ComputeRequest<'a> {
    pub requester:   MemberId,
    /// Stable id of the workload organism the
    /// requester wants run. The organism's
    /// Config.content already pins everything the
    /// provider needs to run it — no separate
    /// manifest.
    pub workload:    UniqueId,
    /// Optional content-hash pin, when the requester
    /// wants one specific build.
    pub pin:         Option<UniqueId>,
    pub duration_sec: u32,
    /// Opaque settlement evidence the requester
    /// chose. The module stores the hash and
    /// verifies nothing about it; settlement rails
    /// live off-module.
    pub settlement:  UniqueId,
    pub deadline:    AlmanacTick,
}

pub struct ComputeGrant<'a> {
    pub request_id:    UniqueId,
    pub provider:      MemberId,
    pub endpoint_hint: EndpointHint<'a>,
    pub bearer_pointer: UniqueId,
    pub content_hash:  UniqueId,
    pub valid_from:    AlmanacTick,
    pub valid_to:      AlmanacTick,
    pub expected_mrtd: Option<Mrtd>,
}

pub struct ComputeLog<'a> {
    pub grant_id: UniqueId,
    pub provider: MemberId,
    pub window:   AlmanacRange,
    pub usage:    UsageMetrics,
    pub evidence: Option<EvidencePointer<'a>>,
}

OrganismConfig folds the coalition root under "compute", the committee ACL, and an optional provider_reputation: OrganismRef the module consults at clearing.

State machine: three commands — SubmitRequest, CommitGrant, AppendLog.

Trust shape: majority-honest committee for scheduling. Provider-level trust is the provider’s own TicketValidator; the module does not vouch. A malicious provider that accepts a grant and never runs the image is detectable by the requester’s outputs never appearing; a reputation organism orthogonal to the module scores it.

When to ship: coalitions with members — AI agents in particular — that need programmatic compute acquisition. When to skip: coalitions whose members bring their own compute out of band.

Not a compute provider. Not a payment rail. Not a guarantee of provider honesty. Not a cross-coalition marketplace.

Randomness

Scheduler and commit authority for a coalition’s randomness beacon. Like Compute, the module commits the values but does not produce them; the actual randomness comes from a registered beacon provider whose identity the module publishes with each round.

Public surface:

• Stream<BeaconTick> — the authoritative beacon sequence.
• Collection<ProviderId, ProviderCard> — registered providers (reuses the Compute ProviderCard shape; the card’s content declares which beacon scheme the provider runs).

pub struct BeaconTick {
    pub round:        u64,
    pub provider:     MemberId,
    pub value:        [u8; 32],
    /// Scheme-specific proof (BLS signature, VRF
    /// proof, external-anchor inclusion proof, TDX
    /// quote). The committee verifies the proof
    /// against the provider card's declared scheme
    /// before committing the tick.
    pub proof:        Vec<u8>,
    pub committed_at: AlmanacTick,
}

Consumers that want a per-round targeted draw derive it locally:

  draw = blake3(beacon_value || domain_separator)

No BeaconRequest, no BeaconGrant, no challenge-stream surface: a consumer who suspects a round was biased files a ChronicleEntry and unpins the provider from their own validator.

OrganismConfig folds the coalition root under "randomness", the committee ACL, and the set of beacon-scheme families the module admits (threshold-bls, vrf, external, tdx-attested as operator-declared tags).

State machine: two commands — RegisterProvider and CommitBeacon.

Trust shape: the module’s scheduling and commit integrity is majority-honest committee. The beacon’s unbiasability is inherited from the provider’s declared scheme; the module verifies the proof at commit time but does not add cryptographic guarantees beyond what the scheme itself provides. Consumers admitting weak schemes get weak randomness.

When to ship: members need verifiable randomness (coordination markets, agent experiment allocators, commit-reveal auctions, leader-election committees). When to skip: randomness needs are cosmetic, or satisfied by an external beacon consumers bond to directly.

Not a beacon producer. Not a proof of unbiasability. Not a payment rail. Not a cross-coalition beacon.

Retirement markers

A cross-cutting primitive every composite organism, module, and coalition supports. Before committee shutdown, the component commits a RetirementMarker on its own public stream so consumers upgrade cleanly rather than receiving ConnectTimeout.

pub struct RetirementMarker<'a> {
    pub effective_at: RetirementInstant,
    pub replacement:  Option<ComponentRef<'a>>,
}

A retirement marker is the last commit on the stream. A Chronicle entry records it at the coalition level as ChronicleKind::OrganismRetired or ChronicleKind::ModuleRetired.

Deriving a module’s identity

Every module is an organism; the derivation folds the coalition root under a "module" segment:

  ATLAS_ROOT      = COALITION_ROOT.derive("module").derive("atlas")
  ALMANAC_ROOT    = COALITION_ROOT.derive("module").derive("almanac")
  CHRONICLE_ROOT  = COALITION_ROOT.derive("module").derive("chronicle")
  COMPUTE_ROOT    = COALITION_ROOT.derive("module").derive("compute")
  RANDOMNESS_ROOT = COALITION_ROOT.derive("module").derive("randomness")

  <module>_committee = blake3(
      <module>_root
      || ordered member references (if any)
      || module_content_fingerprint
      || module_acl_fingerprint
  ).derive("committee")

The "module" segment distinguishes coalition- scoped components from commissioned composite organisms (which derive without a coalition root).

CoalitionConfig helpers

A coalition’s OrganismRef for each shipped module is stored in a dedicated field on CoalitionConfig, not a typed container. The coalition meta-crate exposes direct accessors:

impl CoalitionConfig<'_> {
    pub const fn atlas(&self)      -> Option<&OrganismRef<'_>>;
    pub const fn almanac(&self)    -> Option<&OrganismRef<'_>>;
    pub const fn chronicle(&self)  -> Option<&OrganismRef<'_>>;
    pub const fn compute(&self)    -> Option<&OrganismRef<'_>>;
    pub const fn randomness(&self) -> Option<&OrganismRef<'_>>;
}

A coalition that does not ship a module leaves the field None; a later version can ship it without breaking integrators that did not consult the field before.

Deliberately unspecified

• Chronicle retention policy, storage layout, and anchor cadence — operator-configured.
• Almanac tick cadence.
• Atlas metadata schema beyond the required fields.
• The set of scheme-family tags a Randomness module admits.
• Whether a module is required for any downstream composite organism. Composite organisms that need a module declare the dependency in their own OrganismConfig.
• Compute settlement evidence format. The module stores a hash; how it is verified lives with whichever rail the coalition uses (on-chain payment contract, reputation card, credit token).
• Deferred-primitives-space extensions — out of scope. See deferred-primitives pressure.

Cross-references

• Topology-intro — the coalition rung.
• Architecture — a coalition worked through.
• Ticket issuance.
• Composite organisms.
• Composition.
• Threat model.
• Deferred-primitives pressure.