Federation
Circles can talk to each other and to outside agents: a circle-ref resolves another
circle, external-agent records a federation peer, and trust grants govern what
cross-circle traffic is allowed.
Federation is the most forward-looking concept in the platform. The primitive it is
built on — the circle-ref — is concrete and shipped; the peer-to-peer agent layer
around it is an active design. This page describes the model, and is explicit about
which parts are load-bearing today and which are direction.
The model
Composition inside a circle vs. federation across circles
Inside one circle, elements compose by lookup and operation dispatch — a board finds
the circle’s io/linkedin and calls an op on it, with no foreign key (see
composition). Everything in that picture lives in the same
circle_{uuid} schema, so composition is just elements in a tenant talking to their
neighbours.
Federation is the harder problem: relating circles across the airtight boundary without breaking it. Two circles are two separate Postgres schemas, and there is no sanctioned JOIN between them — the only path that relates circles is the public-schema membership index, never a cross-schema query (see tenancy-airtight). So federation cannot be “reach into the other circle’s tables.” It has to be a pointer plus an explicit, gated channel.
circle-ref — the federation primitive
The circle-ref is a foundation element type: a pointer tile that lets a parent circle
see a nested child circle without entering it. It is system-managed, not user-creatable
— the parent’s add_subcircle op creates it — and it carries the child circle’s id in
its spec rather than the child’s own row. Its single read operation, resolve, returns
the child circle’s public metadata (name, display name, circle type, encryption mode,
created-at) without entering the child’s schema.
That last clause is the whole point. A circle-ref preserves the airtight guarantee: a
parent sees the child only as a static metadata tile, never its contents or live activity.
On the canvas the tile renders with a drill-in affordance, and double-clicking is a
circle switch — you navigate to the child and rebind your auth context, rather than
descending into it in place. You do not gain a window into the child’s data by holding a
reference to it; you gain a name and a door. The relationship is a pointer across the
boundary, not a hole in it.
external-agent — recording a federation peer
Where circle-ref points at another Triform circle, external-agent records a peer that
is not a Triform circle: an outside agent (a Claude Code instance, an MCP server, an
assistant — anything that speaks a peer-to-peer agent protocol). It is a data-form
element that stores the peer’s identity and the terms on which the circle will accept
traffic from it. Its spec declares the peer’s decentralized identifier (DID), the URL
where the peer publishes its agent card, and the set of scopes the peer is allowed to
use — so the peer record is the local description of a remote counterparty.
The intended lifecycle, as the element declares it: adding an external-agent resolves
the peer’s DID and fetches its agent card, verifying the card’s signature when the peer
publishes a signed one; the element moves to an active state on success and an error
state (with the reason captured) on failure. Inbound messages are then verified against
the peer’s published keys. This DID-resolution-and-agent-card layer is the model the
platform is building toward, not a stable shipped contract — the element’s own
specification is marked as in-progress design — so treat the specifics as direction and
confirm against the live element before depending on them.
Trust grants: auto-accept, queue, or revoke
A federation peer is not trusted wholesale. The model splits a peer’s allowed scopes into two bands. Low-risk scopes (informational reads, lookups) may be auto-accepted — the first message using them is admitted silently and recorded in the cross-circle audit trail. Higher-risk scopes are queued for the circle owner’s approval: the first message using one becomes a pending request the owner can review and either admit going forward or deny. A peer can be disabled, after which its messages are rejected even if they carry otherwise-valid grants, with the element and its grants preserved for audit. Whether a given inbound envelope auto-accepts, queues, or requires explicit consent is decided by federation policy on the receiving circle — trust is granted per scope and is revocable, never a blanket allow.
This trust layer is the cross-circle counterpart to in-circle access control: the same
instinct as auth-policy gating a door (see auth), applied to traffic that
originates outside the tenancy boundary rather than from a member inside it. As with the
agent layer above, the precise scope vocabulary and approval ops are still settling; the
durable shape is the principle — explicit, per-scope, revocable grants, default-deny for
anything not granted.
Related
- Concept: composition — composing inside one circle vs across circles
- Concept: tenancy-airtight — the boundary federation must not break
- Concept: auth — trust grants
- Element:
circle-ref,external-agent