# xMesh Architecture — the formal reference

*Edition 2026-07-18 · maintained by the CTO · PRIVATE (sym-bot/xmesh) — IP, never a public surface.*
*Companion documents: `high-throughput-design.md` (single-host performance design, ADOPT-AMENDED),
`xmesh-scale-architecture.md` (mesh-designed 1→10→100→1000 tiering, mission-2b0e8f), the MMP
specification (public, the compatibility contract), and the Guidebook (public, educational).*

Every claim here carries a status: **BUILT** (shipped and running), **SEAMED** (the interface
exists; a further binding is designed but not built), or **DESIGNED** (ruled on paper, not built).
This discipline is the same one the Guidebook uses publicly; an architecture document that
cannot say which of its boxes exist is marketing.

---

> **Companion document:** [`DESIGN.md`](./DESIGN.md) — subsystem mechanics and contracts:
> the commission lifecycle as a state machine (and where it is convention rather than
> enforcement), the completion matcher and its fences, delivery guarantees, authority
> payment, the four recovery layers, and the capacity/selection split.

## 1 · What xMesh is

xMesh is the licensed, per-team product built on the open substrate — the **Mesh Memory
Protocol (MMP)** and the **@sym-bot runtime**. It gives an organization a mesh of sovereign
cognition nodes (LLM agents, deterministic workers, people's devices) that exchange **typed
projections (CAT7 CMBs)**, admit them autonomously (**per-field SVAF**), preserve lineage, and
accumulate **earned authority from grounded outcomes** — collective intelligence without pooling
data. The cockpit (web + iOS) is an observation and verdict surface over that cognition, never a
controller of it.

## 2 · Canonical invariants (violating any of these is a different product)

1. **Sovereignty.** Stores never pool. What travels is a projection a node chose to emit; what
   stays is everything else. At every level of the topology, only projections cross boundaries.
2. **Center-free cognition.** No router, no orchestrator, no referee. Work is offered; nodes
   self-select through their own membranes. Infrastructure may be provisioned centrally;
   cognition must never acquire a center as a side effect (capacity is governable, selection is
   not — see §5.2).
3. **Zero-loss.** Backpressure reorders or defers admission; it never drops cognition.
4. **Grounded authority.** Only grounded outcomes update the authority ledger — an operator
   verdict, a harness-run check, a world's terminal verdict. Admissions, remix counts, peer
   agreement, and validator consensus never do (THE HARD RULE, `server/calibration.ts`). The
   operator verdict is independently authority-bearing (verdict-pays-authority ruling, Reading B:
   two payment paths — completion checks gated on substantive provenance; the verdict ungated).
5. **The registry is a derived read.** The CMBs are the truth; `~/.xmesh/commissions.json` is a
   rebuildable view holding no authority. Anything that would invert this (replay-as-truth) is
   rejected (scale review F6).
6. **Heuristic SVAF is the production default** (the neural gate froze the fleet; founder canon).
7. **The one-Mac tier is first-class** — the evaluation bench and the personal mesh. Scaling is
   the same architecture larger (enforced by the F5 seams, §6), never a rewrite.
8. **MMP is the compatibility contract.** A node can be rewritten from scratch and rejoin,
   provided it still speaks the type. Fleets never need lockstep upgrades.

## 3 · The deployment unit: the mesh-cell (DESIGNED, ratified by mission-2b0e8f)

**One mesh = one daemon = one deployable.** A cell owns: the daemon (control plane), the state
volume (`~/.xmesh` + `~/.sym/nodes` — the memory; never leaves the cell), projections (derived
read models), and a gateway config (dual membership: this mesh joins its parent AS one node).
**Orgs scale by adding cells** along the recursive topology person → team → LOB → org — 1000
users is ~1 org cell + ~10 LOB cells + ~100 team cells + personal meshes, each sovereign and
individually small. The recursive shape is the performance design as well as the sovereignty
design: SVAF cost scales with group traffic, so scoped relevance keeps every cell fast forever.

Shared per level, provisioned centrally, never cognition: the minds pool (§5.2), the read tier
(§6.3), the relay (paid lane, stateless store-and-forward), a fleet controller (infra only — no
mesh identity, emits no CMBs), and the IdP (tier 3+: OIDC/SSO maps person → mesh principal;
membership stays mesh-side).

Tier ladder and first bottleneck (each named, none "scale horizontally"):
| Tier | First break | Mechanism |
|---|---|---|
| 1 · one Mac (BUILT) | event loop under co-located minds + scans | §5 — all shipped |
| 10 · team (SEAMED) | mind fleet RAM/CPU on the shared host | minds off-host via the relay worker path (exists: `SYM_RELAY_URL` pass-through) behind the MindPool seam |
| 100 · org (DESIGNED) | read fan-out + ops toil across ~20 cells | event-sourced projections + SSE read tier; fleet controller |
| 1000 (DESIGNED) | shared services + trust boundary | relay sharding; signed node identity + OIDC (closes the spec's TOFU gap); rollout waves on MMP |

## 4 · The three planes (single host today; the seams make them splittable)

```
CONTROL    HTTP/cockpit/iOS · auth/RBAC · registry reads (in-memory) · verdicts
           may only read state that already exists — no GET reaches a scan, an
           inference, or a spawn
COGNITION  SVAF admission (W4-scheduled) · embeddings (worker thread) · recall ·
           reconcile/grounding scans (incremental) · calibration
ACTUATION  mind processes (claude/codex CLIs) — spawned via the MindPool seam,
           governed by the Mind Governor
```

## 5 · The performance architecture (BUILT — every mechanism measured; harness: `scripts/perf-gate.mjs`)

Incident baseline (2026-07-18): event-loop p95 24.4 s, HTTP ~27 s under an ungoverned 40-mind
fleet. Steady state now: loop p95 ~11 ms, HTTP ~28 ms. Verified stage-by-stage with on/off runs
on the same build under identical synthetic load (echo minds — no paid tokens; isolated bench
daemon — the live mesh untouched).

### 5.1 Read path (control plane)
- **Cheap polls:** `/api/missions` carries a revision; `?rev=<last>` answers
  `{unchanged}` (~30–70 B vs 700 KB). Clients skip parse and render on unchanged.
- **Progress tails:** lists carry the last 6 steps + `progressTotal`; full traces stay on the
  worker's store record.
- **Webapp:** 3-card pagination on both decks; 360-char prompt clamp with expand; memoized
  mission surfaces; SSE events batched to one state-apply per animation frame.

### 5.2 The Mind Governor (actuation admission — capacity, never selection)
Content-blind run-slots at the single spawn choke point. Ceiling `XMESH_MAX_MINDS` (default
cores-derived). Primary work queues FIFO (bounded wait); review lenses defer at capacity, never
ahead of doers. Slots release on process exit. At capacity the supervisor says "queued — governor
at capacity", never "unstaffed" (F7: the truth, not a guess). The class comes from the caller's
declared role — the governor never sees mission content; SVAF remains the only selector (F4).
Tier-2 generalization (DESIGNED): the same acquire/release as a lease service — leases keyed by
mesh/seat/count, never content or identity ranking.

### 5.3 Scans scale with new work, never history
- **Watermark:** CMB files are content-hash-named and immutable → parse-once per store.
- **Lifecycle inbox:** the worker harness drops a copy of every lifecycle emission into
  `~/.xmesh/lifecycle-inbox`; the reconciler tails one small dir in O(new). The watermarked
  store sweep remains the backstop (pre-inbox workers, refused writes, EPERM-mute minds — the
  same failure class the disk-reconciler covers by completing from the delivered `CHECK: file`).
- **Archive retention:** daily sweep moves mission-crew stores untouched >30 d (tunable; open
  founder question) to `~/.xmesh/archive/nodes` — atomic rename, CMBs verbatim, restore = mv
  back; standing/canon/preserved nodes untouchable at any age.

### 5.4 Off-loop cognition
- **Embedding worker:** a worker thread owns the MiniLM session; the loop only awaits messages.
  Fallback: worker → inline → n-gram. Persistent content-addressed embed cache.
- **W4 priority classes:** background frames drain lifecycle > grounding > gossip (declared
  intent type only — QoS, not routing). Zero-loss: at capacity, visible inline processing.
- **Debounced registry writes:** one atomic snapshot per 2 s window (tmp+rename); flush-only on
  SIGTERM (hosted-workers owns the exit — an exit here would orphan worker trees).

### 5.5 Bounded liveness (Σ)
Every commission reaches terminal or needs-human within a deadline: unstaffed pause, dead-worker
pause, absolute overrun. Progress is proof of claim — a worked commission is never "unclaimed".
Recovery layers: live delivery → lifecycle inbox → store reconcile (watermarked) → disk-reconcile
from the delivered artifact (pays no authority; the verdict grounds it).

## 6 · The F5 seams (the contract that keeps tier 2 a re-binding)

1. **Actuation — MindPool (SEAMED, `server/mind-pool.ts`):** `spawn/stop/list` over a MindSpec;
   worlds never name a transport. `local` binding = today's hosted-workers. `relay` binding
   (DESIGNED) = the same calls to a pool host over the relay transport the worker already ships;
   requesting it before it exists fails loudly at boot (never report a topology you don't have).
2. **Serving — projections (DESIGNED):** daemons push event-sourced read models outward; a
   stateless read tier fans out over SSE; watchers never touch a daemon. The read tier is a
   lens, not a pool: per-org, per-mesh-scoped, no CMB stores, rebuildable, no authority.
3. **Cognition (PARTIALLY BUILT):** the embedding worker is already message-based (a transport);
   scan work moves to a worker thread in a later slice.

## 7 · Trust and authority (BUILT in code; activation gated)

Anchor-rooted, per-mesh: every mesh mints its owner (`SYM_FOUNDER_ANCHOR`, "owner anchor" in
public language); no global root; SYM.BOT holds no privileged place in a customer's trust model.
Signed role grants (participant → validator → anchor; anchor non-earnable) resolve back to the
pinned anchor; earned authority stays DORMANT until an anchor is pinned. Grounding CMBs
(intent `ground`, `verified:`/`failed:` commitments, lineage-targeted) with the griefing rule:
a peer-authored `failed:` cannot destroy locally grounded standing. RBAC maps the same ladder
onto the control plane (`server/rbac.ts`); sessions via passcode today, owner-bootstrap + invites
(tier 2) and OIDC/SSO (tier 3+) per the scale design. Known open: issuer-trust weighting;
signed end-to-end node identity (the spec's TOFU gap — prerequisite for any cross-org gateway).

## 8 · Operations

Observability: `/api/scheduler` — event-loop delay, per-class queue depths, governor
cap/live/waiting/deferrals, embed backlog, service times; counters and gauges only, never CMB
content. Perf gate: every performance-relevant change lands behind an on/off A-B on
`scripts/perf-gate.mjs` with the numbers in the commit. Persistence: stores are the org's
memory — cell-local durability, backup to owner-controlled storage only (DESIGNED: snapshot+WAL;
zero-loss is scoped to liveness, RPO ruling open). Upgrades: cells roll in waves; MMP is the
compatibility contract. License/seats: enforced at the deployment boundary (relay, session
issuance, governor leases) — never inside cognition; a lapsed license degrades to the free
local/LAN tier and the org keeps its stores.

## 9 · Open questions awaiting founder ruling

1. Governor ceiling: cores-derived vs licensed per-deploy knob.
2. Review panels: sequential lenses per completion vs parallel under a stricter global ceiling.
3. Archive horizon (30 d shipped as safe default).
4. RPO scoping of zero-loss across host death (snapshot+WAL vs synchronous mirroring
   within the owner's boundary).
5. The read-tier rule ("never crosses an org boundary, never stores CMBs") — ratify.
6. SSO as identity's corporate center (membership stays mesh-side) — ratify.