Joining the fabric

Adding capacity to an estate is admitting a new identity into a trust fabric, not registering a hostname. Two flows sit behind "a new cell comes online," and they differ in one decisive way, whether a trust root already exists:

• A new node in a new organization, the genesis case. There is no prior signer, so the organization and node are minted from nothing and the trust root is established.
• A new node or cell in an existing organization, the common case. The organization already holds a certificate authority, and the newcomer is admitted under it by presenting a signed join authorization.

The identity chain at join

Whichever flow brings a cell online, the certificate chain it ends up holding is the same shape: organization root → node → cell. The organization root is the trust anchor; the node is the durable system identity that survives cell replacement; and each cell certificate is anchored to its node, so a cell inherits its place in the fabric through the node rather than standing on its own.

Figure: the two join flows over one identity chain. The green chain (organization root → node → cell) is the trust structure both flows produce. Flow A (cyan) is genesis: it mints the organization and node and establishes the root, with no prior signer. Flow B admits a newcomer under the existing organization CA, it presents a signed, single-use join authorization to a discovered seed cell, is graded against a required attestation level, and is refused fail-closed (red) on a bad, expired, or revoked authorization or an attestation below the bar. Ceiling: the cell's private key is generated on the cell and never leaves it; the organization CA signs a certificate-signing request, it does not mint the cell's key.

Table equivalent

	Flow A: new organization	Flow B: existing organization
Precondition	No trust root exists	Organization CA already exists
Trigger	Genesis mint of organization + node	Signed join authorization presented to a seed
Trust root	Established here	Already present; newcomer admitted under it
Admission check	N/A (genesis)	Signature + expiry + revocation + attestation grade
Result	Organization root → node → cell chain provisioned	Cell certificate issued, anchored to the node
Refusal		Fail-closed on bad/expired/revoked authorization or low attestation

Flow A: a new node in a new organization

Genesis has no one to ask for permission, so it creates the authority it will run under. The organization and node entities are minted, and the certificate chain is provisioned outward (organization root, then node, then cell) with the genesis actor being the organization itself. From this point on, the node is the identity peers recognize, and every later cell under it chains back to this root.

This is the first-boot "fresh with license" branch from Initialization & setup: the signed license carries the organization identity, and genesis turns it into a running estate with its own PKI.

Flow B: a new node in an existing organization

The common case adds capacity to an organization that already exists. It turns on a signed join authorization:

1. Mint. An operator with authority in the organization mints a join authorization, an Ed25519-signed JWS bundle naming the issuer, the subject, the scope, discovery seeds, and metering terms. It is single-use (tracked in a consumption ledger) and revocable.
2. Discover. The joining cell finds a seed to talk to, first from an explicit endpoint list, then via DNS SRV records, so a fabric is reachable by naming rather than by hand-configured addresses.
3. Present and verify. The newcomer presents its bundle to the seed. The seed verifies the signature, expiry, and revocation against the key the bundle's key id resolves to, and grades the joiner's attestation against a required trust level. Any failure refuses fail-closed.
4. Admit. On success the cell is created, assigned to its service groups, its endpoints are registered, and it receives the fabric state it needs, with a rollback path if any step fails.

Because verification is a signature check against an anchor the seed already holds, Flow B works air-gapped: the join authorization travels on physical media, and admission needs no call to an external authority.

Cell peering and attested reachability

Being admitted is not the same as being reachable. Which cells may reach which is cell peering, a first-class part of the topology:

• Peer discovery and topology. Each cell publishes its endpoints into the Cell Network Fabric; peers discover each other through it, and a topology generator reconciles connections, classifies each path's replication scope, and chooses a transport per link.
• Reachability algebra and relays. A reachability resolver classifies each remote node as directly reachable, outbound-only, or relay-only, and a relay planner selects a route when two cells cannot reach each other directly, so a cell behind a bastion or on a constrained link still participates.
• Attested reachability. Inter-cell calls run over mutual TLS, so a cell's identity rides the handshake and every call is authenticated by certificate rather than by network position; a cross-organization peer is identified by the first trust edge whose anchor validates its certificate, fail-closed and revocation-checked.

Attested reachability is composed, not one call

"Reachability is proven by the mutual-TLS identity on every inter-cell call" is assembled from the fabric channel layer, the peer-endpoint store, and the cross-org identity resolver rather than a single named verifier on the core inter-cell path. The tightest single-symbol expression is on the Edge Agent gateway, where a connection is refused unless it proves a certificate attesting the claimed cell. Describe attested reachability as a composition today, not one unified check.

Admitting the workload, not just the cell

A cell being present does not mean a given workload belongs on it. When work is placed, an admission gate decides can_place against the workload's kind, tier, classification, compartment, deployment posture, and connectivity; a group-quota gate and capacity contracts decide whether the target service group has room; and a home-cell resolver picks the cell (and replicas) for a workspace, filtered by residency. This is why "which cell runs this" has one governed answer rather than a scheduler's guess, and why adding a cell does not, by itself, widen what may run where.

The fabric that holds it together

Once cells are peered, the Cell Network Fabric keeps the estate coherent as members come and go:

• Endpoint registration publishes each cell's HTTP and gRPC endpoints into a fabric table reconciled at boot and on certificate rotation.
• Leases and heartbeats track liveness; a cell whose heartbeat goes stale is marked disconnected.
• Lease-based leader election elects cross-cell singletons (including the cross-node replication publish-leader) through short-TTL leadership leases, so leadership survives a cell going away.
• Split-brain zone fencing isolates a minority partition: a minority without quorum drops to read-only until it reconnects and catches up, rather than serving divergent writes.

Bringing an edge device online

An Edge Agent joins by s9 enroll, which is Flow B's shape scaled to a device that holds a delegated identity rather than a full cell:

• The device generates its keypair locally and persists the private key (owner-only) before any network call, so a partial enrollment never strands a device without its own key. The private key never leaves the device, the service sees only a certificate-signing request, a hardware fingerprint, and the enrollment token.
• The returned delegation is validated against the scope kind the device expects (a mismatched scope is rejected), and the leaf certificate, chain, and CA bundle are stored.

Where the edge leaf is minted

The authoritative issuer that signs an edge device's leaf and delegation is the core admin enrollment path; the Edge Agent presents a certificate-signing request and stores what it is issued. The edge gateway itself does not mint the certificate.

Across the deployment matrix

Corner	How joining behaves
Single-cell	Genesis (Flow A) only: one cell is a complete estate; there is nothing to join
Multi-cell, cloud	Flow B under the organization CA; seeds discovered by list then DNS SRV; peering and admission as above
Air-gapped	Flow B with the signed join authorization carried on physical media and verified locally: no external authority in the loop
Edge	s9 enroll for a delegated device identity; the core admin path issues the leaf

Related topics

• Initialization & setup, the first-boot state detection that routes a cell into genesis or join.
• The estate hierarchy, organization, node, and cell, and why the node is the durable identity.
• Deployment topology, cell peering, failure domains, and the topology reachability resolves against.
• Replication, DR & federation, the scopes and cross-organization cryptography peering feeds.