Federation — cross-deployment query (roadmap)#

⚠️ Status: design accepted, NOT yet shipped#

This is a design document for a roadmap feature, not a working capability. Federated cross-deployment query is an accepted design direction, but no parser, planner, or wire support exists in the codebase yet (FEDERATED ACROSS (...) is not parsed; FederationAgreement is not wired). We surface the design here so multi-agency / multi-region teams can plan around it. Do not write code against this page today — check the release notes or open an issue before relying on any of it.

The problem it solves#

One agency's lead is another agency's known entity. Today every cross-agency lookup is an email or a phone call, and the answer is "no idea, ask them." Federation is the unification multiplier: each department, agency, or region runs Relata on its own data, behind its own ACL and jurisdiction policy, and a single query can pull in what peers permit — with zero data movement and zero sovereignty loss.

The design (when it ships)#

A query carrying FEDERATED ACROSS (eu_relate, us_relate, apac_relate) will be parsed and planned locally, then fanned out to each named peer deployment over Arrow Flight with mutual TLS + a signed query envelope. Each peer enforces its own ACL, jurisdiction-routing policy, purpose check, and compartment labels. Per-peer result batches are stitched at the originator, with the source deployment tagged on every returned row's provenance (provenance.via_deployment).

The originator does not receive raw rows the peer refuses to release — it receives a typed release receipt (count, classes, redaction summary, deny reason). Identity operators (LOOKUP_IDENTITY, RESOLVE_IDENTITY, IDENTITY_CLUSTER) federate the same way: each peer returns its slice of the cluster with confidences, and the originator computes the union cluster with per-edge provenance tagged to the contributing deployment.

-- Illustrative — does NOT parse today. Captured here so the shape is stable when it lands.
PURPOSE 'cross-border-finance'
SELECT id, name, risk_score
FROM Person
FEDERATED ACROSS (eu_relate, us_relate, apac_relate)
WHERE LOOKUP_IDENTITY('+44 7700 900123');

What makes it different from existing federation tools#

Constraints (per the design)#

• Read-only in v0.1. Cross-deployment writes happen via typed CDS export with dual control, not via federation.
• No federated joins below the object level. A peer either returns object rows or refuses. Cross-deployment stitching happens via identity, not via raw column-level joins.
• Version compatibility. Every peer must run a semver-minor-compatible Relata version; the planner refuses federation against incompatible peers.
• Peers may legitimately return zero rows for security reasons. The originator cannot distinguish "no match" from "refused" beyond the typed release receipt.

Alternatives Relata rejected (and why)#

• Push everyone onto one shared deployment — rejected: sovereignty, jurisdiction, and clearance compartments make a single shared instance impossible for multi-agency cooperation.
• Sync-via-export (each peer exports a snapshot daily) — rejected: stale, expensive, and the snapshot itself is a CDS event every time, with no live identity resolution.
• Generic FDW-style federation — rejected: FDWs don't carry typed purpose / compartment / routing-policy, so peer enforcement degenerates to "trust the client."

When this matters to you#

• Multi-agency law enforcement / intelligence — each agency keeps its data, but a sanctioned identity or a phone number resolves across all cooperating peers with per-row provenance.
• Multi-region enterprise (bank, telco) — data residency rules keep each region's customer data local; federation lets a global investigator query across regions without copying data.
• Federated KYC / AML — one entity known to peer X under case Y surfaces as a pointer, without either side exposing its underlying records.

Track the implementation#

• No code yet. If you need this capability, open an issue describing your topology so it informs the implementation sequencing.
• Dependencies: MLS compartments, CDS sanitisation, jurisdiction routing, and purpose all need to be in place before federation can ship.

See also#

• Identity — the operators federation will carry peer-to-peer
• Governance — Cedar ACL, purpose, jurisdiction routing (the machinery each peer enforces)
• Provenance — the per-row lineage federation extends with via_deployment
• Limits & Caveats — what honestly ships today vs. roadmap