Federation

Federation turns a fleet of independent Railbase instances into one coordinated business without merging their databases. A NAT'd on-prem node and a public cloud node exchange signed domain facts — shop.order.paid, inventory.stock.changed, warehouse.fulfillment.updated, gl.journal.posted and your own contracts — over a durable outbox/inbox protocol. Every message is ed25519-signed, deduplicated, ordered per business key, and tenant/entity-mapped before it ever touches local state. Each fact has exactly one writer; everyone else holds a projection.

Federation is a licensed core module, not a plugin: it ships inside the Railbase binary and activates the moment you bind your licence in Settings → Federation. There is no separate service to run, no port to open inbound, and no shared datastore.

What you get

• Signed transactional exchange. Domain events are staged into a durable outbox in the same transaction as the business write (transactional outbox — nothing is federated that wasn't committed, and nothing is committed that isn't federated). Each envelope is ed25519-signed over a canonical string binding method, path, body, timestamp and identity; the receiver verifies against a pinned peer key by version. Replay, tamper and cross-endpoint reuse are rejected.
• Works through NAT, no inbound holes. The reachable side (cloud) holds a passive receive endpoint; the NAT'd side drives both directions — pushing its outbox and pulling the peer's. One origin, TLS, a peer allowlist. No VPN, no reverse proxy, no mDNS beacons.
• Single-writer, never silent divergence. Every contract declares its owner and its ordering key. A consumer applies facts idempotently and in order; a gap holds the stream rather than applying out of sequence. Duplicate-with-different-content is quarantined for review, never blindly overwritten.
• Tenant- and entity-safe by construction. Inbound tenant, SKU, warehouse and account references resolve through per-peer maps before the handler runs — an unmapped reference is rejected, never guessed. Your handlers only ever see your own local ids.
• Redaction by default. Fields are classified (identifier / business / PII / sensitive); anything not explicitly shareable is dropped at the wire boundary, and the signature is computed over the redacted form. A newly-added field can never silently leak — it stays redacted until re-reviewed.
• Governed operations. Pairing needs an out-of-band fingerprint confirmation on both sides. High-risk actions — activate a peer, enable a PII-sharing contract, rotate keys, revoke — require two operators and a step-up factor. Every action is audited.
• Backup-safe. A restored .vault freezes federation and reconciles with each peer before resuming, so a rollback can't silently replay or drop cross-system events. Signing keys are sealed and node-bound, so a copied vault can't impersonate the original.
• Your own contracts. Ship federated contracts from any plugin by declaring them in manifest.events — schema, ordering, idempotency, field classes and entity refs. The core validates them at install and runs them through the same signed, ordered, tenant-mapped path as the built-ins.

How it works

1. Pair two instances: one mints a one-time invite, the other redeems it; both operators confirm the key fingerprint out-of-band before the peer goes active.
2. Enable contracts per peer. Enabling negotiates a compatible version against the peer's advertised capabilities and fails closed if there's no intersection.
3. Emit federated events from your plugins with $app.federation.emit(tx, contract, payload) inside your business transaction. The core fans them out to every enabled peer, signs, delivers, retries and dead-letters durably.
4. Apply happens automatically on the receiver: verify → dedupe → schema → tenant/entity map → sanity → ordering-hold → your handler → advance cursor. Consumers react through the ordinary event bus, so existing plugins amplify each other across instances.

Who it's for

Multi-site retailers and wholesalers (cloud shop ⇄ on-prem inventory ⇄ warehouse), groups running head-office plus branch instances, and any operator who needs two Railbase deployments to share business facts without sharing a database or trusting a third party with their data.

Public beta. The core protocol, durable queues, signed transport, apply-gate, licensing and admin console are production-wired and test-pinned. Long-poll latency tuning, fleet-wide key-revocation propagation and KMS-backed key sealing are on the near-term roadmap.