Get started

Federation

Your registry.Your choice of peers.

Keep control of your catalog while exchanging records with registries you choose. Explicit agreements, signed traffic, and bounded sync make the relationship inspectable.

  • Off by default
  • Pinned peer identities
  • Scoped agreements
A closer lookIndependent registries. Deliberate connections.

Operators configure peers and opt in to federation. Sequence-ordered batches carry changes between independent registries.

  1. 01Configure the peers
  2. 02Request an ordered batch
  3. 03Continue from the sequence

01 / agreements

Connection starts with intent.

Federation begins with operator configuration. Choose the peer, the direction of exchange, and the records that belong in the agreement.

  • Choose the identity

    Configure a registry peer and its pinned signing key. Verify the sender and intended recipient on each message.

  • Choose the scope

    Agreements identify namespaces and entry types, with an explicit sync direction and effective date.

  • Keep operational control

    Inspect durable cursors, lag, breaker state, and quarantine status through protected operator endpoints.

02 / signed sync

Small batches. Complete context.

A sync payload requests changes after a registry sequence. The sender wraps it in a signed federation envelope before sending it to the peer.

SyncRequest · inner payload only
{
  "fromSequence": 420,
  "maxEntries": 100,
  "entryTypes": ["AgentDefinition"],
  "namespaces": ["example"]
}

POST /v1/federation/sync accepts SignedFederationEnvelope<SyncRequest>. The envelope binds the sender, recipient, key, timestamp, nonce, request digest, and payload under an Ed25519 signature.

The receiver verifies the signature, replay protection, and active agreement before returning a signed response. Its inner payload provides entries, nextSequence, and hasMore.

Continue from the returned sequence after verified records are durably accepted. A bare payload copied from this exhibit is not a complete federation request.

03 / conflict policy

A deterministic way forward.

  1. 01

    Verify first

    A valid publisher signature is a prerequisite. Unverified remote data does not win a conflict.

  2. 02

    Check confirmed anchors

    Prefer the candidate matching a locally confirmed anchor when that authority is available. Shadow anchor state does not activate external authority.

  3. 03

    Compare sequence

    Among otherwise eligible candidates, the higher sequence takes precedence.

  4. 04

    Break a remaining tie

    Use the lexically lower canonical digest to produce a deterministic result.

04 / federated discovery

Know what your search reached.

Federated discovery can merge local entries with accepted responses from configured peers. Partial results carry an explicit account of the attempted search.

The route is mounted when federated discovery is enabled and requires the FederatedDiscovery capability. Fanout is bounded, and merged records pass local policy.

The response distinguishes peers attempted, succeeded, and failed. A timed-out peer does not disappear behind an unexplained empty result.

The example shows only the response’s federation metadata. It is illustrative, not a live network reading.

federation metadata · example
{
  "federated": true,
  "partial": true,
  "peersAttempted": 3,
  "peersSucceeded": 2,
  "peersFailed": 1
}

05 / operate

Run the registry you need.

The Rust reference service runs against your PostgreSQL database. Authentication, signing keys, trust pins, cursor secrets, and peer policy belong in your deployment configuration.

reference server · configured deployment
# Use your reviewed production configuration and database.
cargo run --bin mars-server -- \
  --config /path/to/mars.toml \
  --listen-addr 127.0.0.1:7780 \
  --database-url "$MARS_DATABASE_URL"

The command uses the reference server’s actual flags and assumes the required production configuration already exists. The optional memory store is for development. Enabling a server does not automatically join a global mesh.