0008: Distinguish Rete, Mesh, and Cluster

Status

Accepted

Establishes the vocabulary that ADR-0005, ADR-0006, and ADR-0007 (and the C0/C1 implementation docs) were updated in place to use.

Florete originally called the trust domain — one Florete deployment, one CA, one identity namespace — a cluster (ADR-0005/0006, identity.mdx). Implementing C0 mTLS made the overload untenable: "cluster" collides with Kubernetes clusters, and Florete's own service-mesh product will manage Kubernetes clusters, so the collision is operational, not hypothetical. Today's "cluster-scoped" (meaning deployment-wide) would even mean the opposite of a future "cluster-scoped" (pinned to one cluster).

We first renamed cluster → mesh, which exposed a deeper, three-way collision on mesh:

the trust domain (the just-renamed deployment),
the C1 overlay-routing layer — kind: mesh, the mesh-vertex, mesh-flor, "mesh layer", mesh-transit,
the conventional name of the intra-domain overlay vertex (was cluster; renaming gave the absurd kind: mesh, name: mesh).

Florete is also a service mesh (the product category) — a fourth pull on the word. Three distinct concepts were fighting over two words; we need one word per concept: the identity boundary, the overlay layer, and the node-group concept Florete will eventually expose.

Decision

Three distinct terms, one per concept:

rete — the trust domain / identity boundary: one Florete deployment, one CA, one principal namespace. The SPIFFE trust-domain value is the rete's name (spiffe://<rete>/…); .rete is its convenience-hostname TLD. Multiple deployments are multiple retes; bridging two of them is inter-rete.
mesh — the overlay-routing data-plane layer: kind: mesh vertices, the mesh-vertex, mesh-flor, "the mesh layer", mesh-transit. (Also the product category — Florete is "a service mesh".)
cluster — reserved for a future grouping of nodes (a Kubernetes cluster, or a locality group within a rete). Not yet a Florete concept; deliberately left free.

Vertex naming (resolving the name: mesh problem). Vertices have a structural kind — link (terminates a wire transport) or mesh (overlay routing) — and a name. The kind: mesh instances are named by the scope they bridge: rete (the rete-spanning mesh-vertex, C1) ‖ interrete (the inter-rete one, future) — a parallel, name-based convention, with mesh as the structural kind. The flor instances running them are link-flor and mesh-flor.

This vocabulary was applied across the whole corpus — Rust identifiers (build_id_in_rete, Scope::Rete, …), ADR-0005/0006/0007, and every C0 and C1 implementation doc — amending those records in place.

Rationale

Why "rete" for the trust domain. The inherited term interrete (inter-rete) already presupposes a deployment is a "rete"; the .rete TLD is already user-facing; and "rete" is the Florete brand root (Latin rete, "net"). It is distinct from both "cluster" (Kubernetes) and "mesh" (overlay/product), so it cleanly carries the identity-boundary meaning the other two cannot. The cluster→mesh rename had simply reached for the wrong word; the concept already had a name.
Why "mesh" stays the overlay layer. C1 already used kind: mesh / "mesh layer" / "mesh-vertex" for the overlay-routing layer, and "service mesh" is the product category and industry term (Istio, Linkerd). Keeping "mesh" there matches existing design and outside usage.
Why reserve "cluster". The product will manage real Kubernetes clusters; reusing the word for the trust domain is a head-on collision. Reserved, it keeps the meaning operators expect for the eventual node-grouping concept.
Why rete / interrete vertex names. They are parallel and meaningful (each names the scope its mesh-vertex bridges), and they keep kind: mesh as the structural axis while the name is the role — see C1's "Why kind: mesh rather than kind: rete" note. Naming the kind after behaviour and the instance after scope keeps the two axes orthogonal.

Consequences

Benefits

One word per concept; no overload. The identity boundary, the overlay layer, the product, and the future node-group never get confused for one another.
.rete, interrete, and "rete" reinforce each other and the brand.
"cluster" stays free for the node-grouping concept, with its natural meaning intact for when Florete manages real clusters.

Transparent load balancing is not limited by naming the rete in the hostname

This is worth stating outright, because the user-facing form is <service>.<rete>.rete and one might worry the rete-in-the-name pins location:

Within a rete, the name is not location-pinned. A rete-scoped service name resolves to instances on any node in the rete (and, once node-clusters exist, any cluster). Every instance presents the rete-wide service SAN (spiffe://<rete>/service/<svc>), so the outbound verifier's exact SAN match holds regardless of where the instance runs. Transparent, locality-aware load balancing across the rete is therefore unaffected by the rete being in the name. (Node-scope is an addressing/placement detail, never the client-facing SAN — see ADR-0007 > Exact SAN match remains the gate.)
Cross-rete transparent load balancing is not a goal. Different retes are different trust domains — different administrative and security boundaries. One does not transparently balance a single service across two retes; that boundary is explicit federation (shared/federated trust bundles per ADR-0005, and explicit cross-rete addressing <service>.<other-rete>.rete), exactly as Istio treats multi-mesh — explicit and non-transparent — rather than as one flat balanced pool.¹
Net: putting the rete in the user-facing hostname costs nothing in load-balancing terms. The only place balancing happens (within a rete) is unaffected, and the only place the name would constrain it (across retes) is a boundary we keep explicit by design.

Trade-offs

A one-time corpus-wide rename (code, ADRs, C0/C1 docs) was paid. "rete" is less industry-standard than "cluster"/"mesh" — a small learning cost, offset by the .rete/interrete reinforcement already in the design.

Evolution

When node-clusters land, "cluster" takes its reserved meaning. Node names may become cluster-scoped (alpha.cluster1.<rete>.rete) — additive, resolved by context per ADR-0007, with the cluster as a locality/addressing axis rather than a separate identity.

Istio: Deployment Models — multiple meshes (federation) expose services explicitly across the boundary, with separate trust domains. ↩