Federation Protocol

Archipelago Federation Protocol v1 is AFP/1, advertised on the wire as archipelago-federation/1. The current branch implements the transport, authenticated envelope, peering state machine, trust-policy gate, and witness-only propagation of border signals. It does not yet move players or items between realms.

What is implemented

• a quicer transport adapter and loopback transport for tests
• certificate, channel-binding, and TLS identity machinery for realm Ed25519 keys
• deterministic CBOR framing and signed envelopes
• signed link_hello and link_ready negotiation
• persistent peer records and explicit operator approval
• replay, sequence, expiry, channel-binding, signature, and trust-policy checks
• watch> peer add|list|requests|approve|reject|inspect|defederate
• best-effort propagation from registered border rooms
• duplicate suppression, hop limits, and witness-only delivery on receipt

The implementation lives in apps/archipelago_federation. The normative protocol is .kiro/specs/federated-text-world-engine/federation-protocol.md in the Archipelago repository. The supervised listener still contains a deferred quicer bind TODO, so these pieces do not yet constitute a reachable production federation endpoint.

Frame and envelope

Every frame begins with two big-endian unsigned integers:

+----------------+----------------+------------------+
| length: u32    | stream_id: u32 | CBOR envelope    |
+----------------+----------------+------------------+

The envelope carries protocol version, message type, IDs, sequence, sender and receiver DIDs, timestamps, channel binding, body, and Ed25519 signature. Signatures cover canonical CBOR with the sig field omitted.

Receipt verification runs metadata checks before cryptography: negotiated version, known type, stream match, sender and receiver, channel binding, time window, replay cache, sequence window, signature, then local trust policy. A cryptographically valid message can still be refused by the receiving realm.

Peering

Discovery does not create trust. An unknown realm sends peer_request; the receiving realm records a pending request unless a local rule explicitly accepts it. The operator approves or rejects it from admin mode. Active peers reconnect through the known-peer handshake.

watch> peer add quic://ironholt.example:4433 ironholt
watch> peer requests
watch> peer approve realm:ironholt.4f2a91c0
watch> peer list

Peer state is persisted in PostgreSQL. The in-memory directory and link registry are rebuilt around that durable record.

Signal propagation

Signals originating in a registered border room are signed and sent on low-latency stream class 1. The receiver verifies the AFP envelope and the origin signature, enforces its hop cap, drops duplicates, then dispatches the signal through dispatch_witness_only/1.

Witness-only means the foreign signal may be perceived locally but cannot run local act/react phases or produce effects. A peer can carry a voice across the boundary; it cannot reach through the boundary and mutate the realm.

Propagation is asynchronous and best-effort. It does not block the local command path. The current implementation does not yet render a complete player-facing cross-realm experience, and multi-hop origin-key resolution remains provisional.

Not implemented yet

AFP/1 specifies more than the engine currently ships. The following remain roadmap work:

• gossip and well-known discovery
• complete defederation workflow and lane consequences
• player and entity transfer
• border CRDT convergence
• customs enforcement and provenance verification
• sealed mail and federated ledger transfer
• confederation governance
• sea lanes, vessels in transit, and cross-realm travel

Do not build integrations against those message families as if their handlers exist. The wire catalog reserves them; the realm does not yet execute them.