Opening a Peer Relationship

Series: raising-an-island · Part 2

The federation branch has AFP/1 framing, identity, peer persistence, trust-policy evaluation, loopback-tested links, and border-signal propagation. The production QUIC listener still defers the actual quicer bind, and outbound peer registration does not yet establish a network link by itself. This guide is for developers exercising the federation subsystem, not for opening a public sea route.

Enable the listener configuration

config :archipelago_federation, Archipelago.Federation.Listener,
  enabled: true,
  port: 4433

The current listener reports the configured port but contains a pending bind step. Use the loopback transport or a directly started Link process for integration work.

Register trust

In a capability-enabled admin connection:

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

peer add creates a pending_outbound row with a placeholder key. A real handshake must replace it with the certificate identity. Inbound requests remain pending unless an operator or explicit local rule accepts them.

Border propagation

BorderRegistry maps local room IDs to active peers. A local signal from a registered border room is signed, wrapped in propagate, and sent to the peer link. The receiver verifies, deduplicates, enforces its hop cap, and dispatches in witness-only mode.

This carries perception, not authority. It does not move the speaker, their inventory, or a vessel.

Severing the record

watch> peer defederate realm:ironholt.4f2a91c0 operator-request

The command tombstones the local peer row. Sending the remote defederation envelope and closing the live QUIC connection remain TODOs in the handler.

Do not call a peer link a lane yet. Lanes, border CRDTs, transfer, customs, sea weather, and travel belong to later phases.