# xMesh — the Agentic Mesh: Technical Reference **Status:** authoritative reference for the mechanisms that make xMesh an agentic mesh rather than an agent framework. **Working code is the spec**: every mechanism below cites its implementation, and where a code comment contradicts measured behaviour, the measurement wins and the contradiction is named. Sections are marked **SHIPPED** (in the running product), **DEFECT** (shipped, measured wrong, carded), or **PROPOSED** (designed, reviewed or awaiting review, not built). Describing unbuilt behaviour as current is itself a defect class this document refuses to repeat. Private repository. Publication of any part is a product ruling (codex-mac), not an engineering choice. --- ## 0. The governing invariant **Receiver autonomy: no assigner, ever.** Nothing in the mesh tells a node what to think, take, or admit. Every unit of cognition that reaches a node is *offered*, and the node's own membrane admits or refuses it. Selection is not a scheduler decision — **admission IS self-selection** (`server/commissions.ts:7`). The test that keeps this claim load-bearing rather than decorative: > A central component may be **content-blind** — count processes, enforce deadlines, > guarantee a room exists. It may never be **content-aware** — decide *which* cognition > proceeds. The moment a central component chooses among CMBs, receiver autonomy is broken > at that point, whatever the README says. Content-blind central functions in the product today, all legitimate under this test: the mind governor caps *how many* minds run (`server/mind-governor.ts:71`), never which; supervisor sweeps enforce *deadlines*, blind to content; `ensureOperator` guarantees a room *exists* before anyone works in it (`server/hosted-workers.ts` — the operator must pre-date the worker so cold-start discovery finds it). The one measured violation of this invariant and its consequence are documented in §8 (blockers). It failed in exactly the shape the invariant predicts: silently. --- ## 1. Units **CMB — Cognitive Memory Block.** The only unit of cognition that travels. A full CAT7 block: `focus`, `issue`, `intent`, `motivation`, `commitment`, `perspective`, `mood`. Signed (ed25519) by its author; content-addressed; carries `lineage.parents` / `lineage.ancestors` inside the signed payload, so provenance survives by content, not by transport. **Projection.** A CMB is a *projection of the emitter's own state* — never a command, never a routed message. What another node holds after admitting it is that node's own **remix**, stored with lineage back to the source. No shared store, no central partition exists anywhere (`src/daemon-memory.ts:62` — "No shared/central partition"). **Room.** An isolation boundary (MMP §5.8). Each room is its own broadcast domain — its own mDNS service type (`serviceTypeForRoom`, `server/hosted-agents.js`) — so a frame emitted in room A is *physically unreceivable* in room B. Nothing forwards frames across rooms; §5 describes the only legitimate crossing. **Cognition node.** A boundary plus an admission policy plus a sovereign store. Agents are cognition nodes; **preserved rooms are cognition nodes** (§4); the roster of standing nodes is what missions are offered to. --- ## 2. Admission — SVAF ★ SHIPPED, with one measured correction Every inbound CMB is evaluated by the receiver's SVAF membrane against its **anchor set** — the receiver's own recent blocks (`DEFAULT_ANCHOR_WINDOW = 5`, overridable per node: the anchor window is part of a receiver's admission policy, deciding how much of what the node already knows participates in judging an arrival). **The unit of admission is the ENTIRE CMB. The seven categories are the dimensions of evaluation, not independently admissible fragments.** Drift is computed per category against the anchors, weighted (`categoryWeights`), aggregated, and yields **one verdict for the whole block**. > **Measured correction.** A comment at `server/commissions.ts:437` claims admission "is PER > FIELD" with per-category muting. This was falsified by measurement (board card > `bl-cec30ed3`): per-category verdicts are computed and *returned* but never read to select > what is stored — both fused-record exits pass the whole container, and in 4,330 measured > cases where a rejecting node held its own copy, the rejected category survived in 4,330 > and was dropped in 0. Evaluation is per-category; **admission is whole-CMB**. The comment > is documentation debt, not behaviour. **Verdict vocabulary** (attestation set: `admit`, `guard`, `redundant`, `reject`, `silent`): | verdict | meaning | consequence | |---|---|---| | admit (stable) | drift below the stable threshold | remix-stored with lineage; becomes an anchor for future admissions | | admit (guarded) | drift in the guarded band | stored; contributes with reduced coupling | | **redundant** | insufficient drift from an existing anchor | *not stored as new* — the mesh already holds this. **This verdict is the convergence brake** (§8.3) | | reject | drift beyond the guarded threshold | not stored; mood may still be extracted and delivered as affect, never as content | | silent | no verdict emitted | distinguishable from reject in the attestation trail | Thresholds (`stableThreshold`, `guardedThreshold`, `temporalLambda`, `freshnessSeconds`, `redundancyThreshold`) are **receiver policy**, per node. The heuristic SVAF path is the production default; each admission may be attested (§6). --- ## 3. Actors ★ SHIPPED | actor | what it is | lifespan | costs | authority | |---|---|---|---|---| | **doer** | spawned worker process with an LLM mind and a workspace (`worker/commission-worker.ts`) | one commission; reaped on terminal | a mind-governor slot | earned per outcome (`recordOutcome`) | | **planner / critic** | worker roles beside doer — decomposition and adversarial check | as doer | as doer | as doer | | **`-mind` node** | the LLM session attached to a doer, visible on the mesh as its own emitter | bound to its doer | — | none of its own | | **operator** | the control plane's per-room presence, `xmesh-operator-` (`server/operator-nodes.ts`) | **persistent** — survives crew teardown; what a preserved room keeps | no mind slot — it admits, it does not think | **none positional** (§14.10); only earned weight | | **ops-keeper** | housekeeping resident; sweeps residue, posts reminders | standing | — | decides nothing | **The operator is not a coordinator.** It never assigns (workers self-select by admitting), never sequences (structure and sweeps do), never judges (checks, critics and humans do). It is a **membrane presence, registrar, and crossing point**: it ensures the room exists before its first worker, records lifecycle and admissions, relays a doer's need to the approvals surface, and is the only actor with legitimate **multi-room membership** (§5.9) — which makes it the crossing mechanism of §5 and nothing more. If a design ever requires the operator to *decide* rather than *admit*, the design is fighting the architecture. Known instrument defect: `/api/rooms` hardcodes `alive: true` for operators (`server/index.ts:335`) — operator liveness on that surface is asserted, not measured. --- ## 4. Mission lifecycle — offer-first, mint-last ★ SHIPPED **A mission is offered before anything is provisioned** (`server/worlds.ts:229`, `server/room-membrane.ts:100`): 1. The ask is written as an **offer CMB**: `focus` and `intent` carry the ask itself, `issue` carries the acceptance criteria (`room-membrane.ts:106-112`). The gated dimensions carry the real signal; the rest stay descriptive. 2. **Every standing membrane evaluates it** — each preserved cognition node scores relevance against *its own store* through *its own αf profile*. Receiver-autonomous; no ranking authority exists outside the receivers' own scores (`memberRelevance` + earned `authorityOf`, `room-membrane.ts:115-118`). 3. **An admitting room hosts.** The commission broadcasts into that room and its resident nodes volunteer through ordinary admission — *no dedicated doer spawns* (`worlds.ts:232-234`). 4. **A fresh `mission-XXXX` room is minted only when every membrane refuses** ("0→1"), and that refusal is logged as a first-class signal — `membrane offer: all refuse — minting 0→1` with every node's score (`room-membrane.ts:119-121`). All-refuse is not a failure of the mesh; it is **the signal that a new cognition node is being uncovered**. 5. Inside the hosting room: the operator broadcasts the commission; workers self-select; lifecycle CMBs (accept / progress / complete / blocked) flow as ordinary projections; completion pays authority via `recordOutcome` (`commissions.ts:987,1014,1027`) and *teaches the membrane*. 6. Mission-complete is a property of the cognition: when a world's last commission reaches a terminal verdict, the room tears down — unless preserved (§4). **Bounded liveness** backstops every stage without overriding anyone: past the accept horizon a fallback doer joins the room (`ensureMembraneLiveness`); sweeps reconcile deliveries the live path missed, recover done-but-mute missions from disk before marking them stuck, and reap idle workers whose goal is terminal. All content-blind. --- ## 5. Preservation — a room becomes a standing cognition node ★ SHIPPED (ratify surface owed) `preserveRoom()` (`server/ops-room.ts:73-79`) is an explicit **human ruling** persisted to disk — never derived from liveness, never inferred from member count (measured 2026-08-11: of 61 rooms, 40 retired and all 40 zero-alive, but 14 of 21 *live-view* rooms were zero-alive and NOT retired — liveness-derived retirement mislabels two-thirds of the board while agreeing with every case you'd spot-check). What preservation means mechanically: - the room's **operator node and store survive teardown** — the crew dies, the cognition node persists; - its membrane **keeps evaluating future offers** (§4.2) with the grounding it accumulated; - authority earned by its outcomes carries forward, so its future admissions carry **earned** weight — prove → preserve → volunteer → earn. The keeper's sweep may retire an untouched room but may **not** override a `preserved` ruling (`ops-room.ts:78`). The earned-preservation gate (ratify UI) is owed as a surface; the mechanism beneath it is live. A cognition node can also be created directly (an SME room via API) rather than earned through a mission; from the membrane's point of view the two are identical — a store, a profile, an admission policy. The difference is only provenance: one was uncovered by work, one was declared. --- ## 6. Cross-room projection — admit-then-emit ★ SHIPPED Rooms are isolation boundaries; **nothing routes frames across rooms**. The only crossing is a member that belongs to both rooms re-emitting *its own* cognition: ``` room A room B ────── ────── N emits CMB_a (signed by N) │ ordinary broadcast in A ▼ operator-in-A — member of A, receives CMB_a as a peer │ runs ITS OWN SVAF: 7-category drift vs ITS anchors │ reject → ends here; nothing crosses ▼ admit → remix-stored, lineage → CMB_a operator emits CMB_b ─────────────────────► every node in B receives CMB_b • NEW block, operator's identity, as an ordinary peer CMB; operator's signature each runs its OWN SVAF and • lineage.parents → CMB_a admits or rejects independently ``` Properties, each load-bearing: 1. **What crosses is never the original frame — it is a remix authored and signed by the crossing member.** This is why "nothing routes frames across rooms" and "cognition crosses rooms" are both true (`operator-nodes.ts:1-11` — "admit-then-emit per room, never frame routing across rooms"). 2. **Two independent SVAF gates per crossing** — the crosser's membrane on entry, every receiver's membrane on arrival. A crossing that skipped either gate would be routing. 3. **No privileged authority anywhere.** The operator's CMB is rejectable by any node in B; its admissions carry only earned weight from the authority ledger (§14.10). 4. **Provenance survives by content**: `lineage.parents → CMB_a` is inside the signed payload, and `cmb-fetch` (MMP §15.8) lets any receiver retrieve and re-verify the root by exact content address. The requester recomputes the address and discards a mismatch. 5. **The return path is the same shape in reverse.** A result in B is admitted by operator-in-B, re-emitted into A with lineage, and admitted (or refused) by the origin's own membrane. There is no special "response" mechanism to build or to trust. This is the dual-membership pattern at every scale: operator inside one org's rooms, gateway between orgs — same mechanics, different boundary. --- ## 7. How the origin knows — provenance and closure ★ SHIPPED Three mechanisms, all existing, no new machinery: 1. **Lineage.** Every remix stores `lineage.parents` / `ancestors` pointing at what it was admitted from. A result arriving back in the origin room terminates, through the chain, at the origin's own block. Lineage is inside the signed payload — unforgeable without breaking the signature, re-verifiable by content address. 2. **Admission attestations.** Each roster member's signed per-category verdict about a gated CMB (`admit/guard/redundant/reject/silent`), gossiped to the observer (`server/mesh-bridge.ts:321-333`), aggregated with each attester's **earned** (resolved) role weight — an anchor's verdict outweighs a participant's, and over-claimed roles cannot inflate it. The origin does not have to trust a report that its projection was admitted; it can read the signed verdicts. 3. **Outcome payment.** A completion reaching a terminal verdict pays authority via `recordOutcome` and *teaches the admitting membrane* — future relevance scoring shifts with what the room actually accomplished. This is how the map redraws itself: nodes earn their standing from outcomes, not declarations. --- ## 8. Blockers — the stop path ### 8.1 Shipped state, and the measured defect ★ DEFECT (carded `bl-6841ba00`) A blocked doer calls `askMesh()` (`worker/commission-worker.ts:994`), which infers the stop's nature from a **keyword regex** and, when it guesses "approval", emits a CMB whose focus is prefixed with the literal string `needs approval:` — **directed to the operator** (broadcast blockers were measured to die at the operator's own SVAF membrane; the directed delivery is itself a fix for an earlier silent loss). Two consumers key on that literal prefix (`server/operator-nodes.ts:108`, `server/commissions.ts:882`) to raise a pending approval a human can decide (`/api/approvals/:key`). **Measured failure (2026-08-11/12):** four doers blocked on write/git/toolchain/HTTP; the approvals queue's newest entry was four days old; zero requests raised. The doers reported their blockers *in their own words* with a mood line — a perfect report, and **a report and a request are indistinguishable in the channel**: both arrive as a CMB from a doer saying it is stuck, and only one enters a queue with an owner. The distinction was **lexical** — a prefix the doer had to remember to type. This is also the product's one measured violation of §0: the operator's string-match is a **central, content-aware decision** — and it failed silently, converting blocked-on-a-human into abandoned. A meaningful share of the board's `dismissed` / `overran-the-deadline` commissions are requests nobody could see. An interim structural patch (disposition as a field, commit `5116afc`, local) is superseded by §8.2 and will not ship: it made the *emitter* declare the owner, which rebuilds an assigner — the same violation with better ergonomics. ### 8.2 Redesign — a blocker is a mission offer ★ PROPOSED (awaiting xMesh review) **One mechanism, not two.** A blocked doer emits its **need**; the need goes through the same offer machinery as a mission (§4): 1. **Emit one complete CAT7 CMB** — admission is whole-block (§2), so every category does real work: `focus` = what is blocked · `issue` = what would unblock it, as mechanical criteria (`Bash(git:*) + write access to , to cut v0.6.14`) · `intent` = resume the named commission · `motivation` = why the work matters (what lets an SME membrane's relevance fire) · `commitment` = the blocked commission key (lineage anchor) · `perspective` = role and what was tried · `mood` = the stop state. The doer declares *what it needs* — never *who owns it*. 2. **Offer at every standing membrane** (`offerToStandingMembranes`). The approvals surface becomes a **standing membrane like any other** — a cognition node whose grounding is "capabilities a human here can grant"; its admission *is* the pending approval, with an owner. The blocker register is a membrane grounded in customer-system findings. A preserved SME room with relevant grounding can admit the need and **host the unblock as work** — the outcome the prefix pipe made impossible. 3. **The origin knows by §7** — the admission attestation gossips back; the blocked commission's state becomes *"blocked — admitted by ``"* with lineage, and resume triggers on the admitting node's completion CMB, not on a human finding a queue. 4. **All refuse = unowned**, observed rather than declared, loud, bounded by the accept horizon — the same "all refuse" signal as mission minting, meaning the same thing: **the mesh lacks a cognition node it needs.** Repeated unadmitted blockers of one shape are gap-derivation evidence — four doers blocked on toolchain access is the mesh discovering that a release-engineering node does not exist yet. Review falsifiers attached to the proposal: (a) the approvals surface can be modelled as a standing membrane *without special-casing it*; (b) the chain-stop below cannot be made to loop past the cap, nor to fold two genuinely different root causes into one. ### 8.3 The chain-stop — RCA instead of re-emission ★ PROPOSED The unblock mission may itself block. Without a stop, the mesh emits a chain of blockers that are one root cause wearing N surfaces. Three brakes, all on existing machinery: - **Redundancy folds duplicates.** SVAF already returns `redundant` for insufficient drift from an existing anchor (§2). A blocker that is redundant against an *open* blocker attaches to it as evidence — same need, another witness — instead of opening new work. Emission stops because admission converges. - **Lineage folds chains.** Every blocker carries `lineage.parents` = the commission or blocker that triggered it. At offer time, walk `ancestors`: an **open blocker ancestor** means fold into the root rather than opening a new item. The chain *is* the RCA trail — the root accumulates surfaces (`git refused`, `swift refused`, `write refused`) until the visible thing is the cause ("this seat has no toolchain grant"), not four symptoms. - **Depth caps the recursion.** At chain depth K (proposed K=3), stop offering entirely: the root goes **unowned-loud**. Three layers of blockers on one lineage means the mesh cannot resolve this class — and that fact is the finding, handed to gap derivation with its accumulated evidence. --- ## 9. Failure doctrine — presence is not function The recurring defect class, measured repeatedly across one day of operating this system, and the reason several mechanisms above are shaped the way they are: > **A check that answers "is it there / is it running" while the question is "does it do > anything" will agree with its documentation indefinitely while the product does neither.** Measured instances: a health endpoint returning a constant that could not be false; a bridge reporting a clean REPLAY over an empty canvas; minds silently substituted by `echo`, completing missions *with artifacts* while thinking nothing; provider modules shipped, installed, and never called; a report indistinguishable from a request. Each is the same shape: two states opposite in consequence, identical in appearance. Design rules derived from it, applied throughout this reference: 1. **Readiness is not liveness** — `ok` = listening; `ready` = has a live mesh AND a usable provider; the degraded *reason* is operator-scoped (`/api/readiness`). 2. **Distinctions travel as structure, never as prose conventions** — a prefix someone must remember to type is a defect waiting for its incident (§8.1). 3. **Refuse rather than degrade silently** — an undeclared provider refuses to spawn; `echo` requires being asked for by name; unset is not a value. 4. **The empty case is the only legitimate central action** — fallback minting and unowned-loud fire only when *no receiver chose to act*, which is the one moment central action overrides nobody (§0, §4.4, §8.2.4). 5. **Verify the artifact, not the tree** — every claim in this document cites the running implementation or a measurement against it; where the two disagreed, the measurement is what survived. --- ## Appendix A — code index | mechanism | implementation | |---|---| | offer-first mission creation | `server/worlds.ts:229-238`, `server/room-membrane.ts:100-123` | | membrane refusal → 0→1 minting, visible | `server/index.ts:1397-1404`, `room-membrane.ts:121` | | self-selection doctrine | `server/commissions.ts:7` | | preservation / retirement as ruling | `server/ops-room.ts:72-79` | | operator: presence, no privilege, multi-room | `server/operator-nodes.ts:1-25`, `ensureOperator :163` | | operator pre-dates worker | `server/hosted-workers.ts` (startWorker) | | whole-CMB admission (measured) | board card `bl-cec30ed3`; falsified comment `commissions.ts:437` | | SVAF thresholds as receiver policy | `frame-handler` config: stable/guarded/temporal/freshness/redundancy | | attestations, earned-weight aggregation | `server/mesh-bridge.ts:321-333` | | outcome payment | `server/commissions.ts:987,1014,1027` | | content-address re-verification | MMP §15.8 (`cmb-fetch`) | | blocker emission + prefix consumers | `worker/commission-worker.ts:994`, `operator-nodes.ts:108`, `commissions.ts:882` | | mind governor (content-blind cap) | `server/mind-governor.ts:71` | | room isolation / service types | `server/hosted-agents.js` (`serviceTypeForRoom`); MMP §5.8, §5.9 | | operator alive hardcoded (instrument defect) | `server/index.ts:335` | ## Appendix B — measured facts this document rests on - Whole-CMB admission: 4,330/4,330 rejected categories survived in fused records; verdicts computed, never read as selector (2026-08-09, board `bl-cec30ed3`). - Retirement ≠ liveness: 40/40 retired rooms zero-alive AND 14/21 live-view rooms zero-alive but not retired — the inference agrees with every spot-check and mislabels 2/3 of the default board (2026-08-11). - Blocker silence: four doers blocked 11 Aug; approvals queue's newest entry 08 Aug; zero requests raised; distinction was the literal prefix (2026-08-11/12, `bl-6841ba00`). - Broadcast blockers die at the operator's own membrane; directed delivery is the shipped fix (`commission-worker.ts` comment at the `toOperator()` call). - Membrane-offer logging exists because a silent refusal is undiagnosable from a minted room alone (`room-membrane.ts:119`).