jschoubben
3c6c16abdf
A session for the mesh itself, addressed as the mesh, differing from a node's in exactly three things: the context it starts in, its engram, and its licence binding. Not a new kind of agent — the same mechanism pointed at a different root. Two implementations of one mechanism drift, and the vocabulary collision 0001 exists to undo began exactly that way. It runs on the control-plane node, and the reasoning is easy to get backwards: not "the important agent on the important machine", but that this node is already the one place excepted from "compromise of a node is compromise of that node". Placed anywhere else it would create a second such place. It is an addition to per-node messaging and never a replacement. 0001 holds that losing the control plane costs change, not operation — and a mesh whose only conversational surface lived there would lose the ability to ask anything while every machine kept running perfectly. Writing it up exposed that the node session's setup was never designed at all. 0004 gives behaviour and stops: nothing said how a session starts, where its context lives, or how a broker message becomes a prompt. That gap was invisible until something had to be built *like* a node session. 15-the-agent-session.md covers both as one mechanism. It also makes "a consumer that is not a machine" undeferrable. The control-plane node now hosts two sessions that must hold different licences, and a per-machine binding cannot express that at all. Noted in 14-model-access.md against the gap it was already recorded as. Also completes the to-be index, which stopped at 10 and omitted four documents. Pre-existing broken ADR references in the older rows are left alone rather than guessed at.
131 lines
7.4 KiB
Markdown
131 lines
7.4 KiB
Markdown
---
|
|
topic: what runs on it
|
|
status: accepted
|
|
date: 2026-08-31
|
|
deciders: jochen
|
|
reconstructed: false
|
|
extends: 02-DECISIONS/0004-a-node-and-how-it-joins.md
|
|
---
|
|
|
|
# 26. The mesh has a session of its own, and it is the node session's mechanism
|
|
|
|
## Context
|
|
|
|
[ADR 0004](0004-a-node-and-how-it-joins.md) gives every node a session: one per node, permanent,
|
|
remembering across callers, its system prompt the node's engram, reachable over the broker like
|
|
everything else. **Any node can message any node**, and that is called the one part of the system
|
|
that is genuinely a mesh — symmetric, with no centre.
|
|
|
|
**There is no way to address the mesh itself.** A question that spans machines — *what is running
|
|
across all of this*, *which nodes are behind*, *why is it built this way* — has to be put to some
|
|
node, which then asks the others. That works, and it makes a mesh-wide question **nobody's
|
|
question**: every node answers it as a foreigner, from a position where the whole is not in view.
|
|
|
|
**Three things independently arrived at the same missing piece.**
|
|
|
|
[ADR 0025](0025-the-design-record-is-read-not-copied.md), taken hours before this one, commits to
|
|
an agent that reads the design repository directly and answers into search. That agent has to
|
|
exist, run somewhere, and be askable — and nothing in the record says what it is or where it
|
|
lives.
|
|
|
|
[`14-model-access.md`](../03-DESIGN/01-to-be/14-model-access.md) records, as a gap deliberately
|
|
not half-built: *this worker uses that licence is a binding to an agent, not to a node* — and the
|
|
provisions model has no consumer identity other than a node. A session that must be assigned a
|
|
licence is exactly that consumer, and node sessions are already one.
|
|
|
|
**And ADR 0004 never said how a session is set up.** It describes behaviour and stops: nothing
|
|
states how a session starts, where its context lives, how the engram reaches it, or how a message
|
|
off the broker becomes a prompt. There is no design document for it. That gap was invisible until
|
|
something had to be built *like* a node session, because describing a second instance of a
|
|
mechanism requires the mechanism to have been described once.
|
|
|
|
## Considered Options
|
|
|
|
1. **No mesh session; keep relaying through a node.** Costs nothing and works today. **Rejected.**
|
|
It leaves mesh-wide questions belonging to nobody, and it does not survive contact with
|
|
ADR 0025 — that agent still needs a home, so the thing gets built anyway, unnamed, as an
|
|
attachment to whichever node happened to host it.
|
|
|
|
2. **A new kind of agent, built separately.** Purpose-built for the whole mesh. **Rejected.** It
|
|
would hold a session, a memory, a licence and broker plumbing — every one of which the node
|
|
session already has. Two implementations of one mechanism drift, and the vocabulary collision
|
|
that [ADR 0001](0001-mesh-brokers-nodes-host-agents-think.md) exists to undo began exactly this
|
|
way: two things that were nearly the same, built twice, until neither word meant one thing.
|
|
|
|
3. **The same mechanism, started in a different context.** **Adopted.**
|
|
|
|
## Decision
|
|
|
|
**The mesh has one session, addressed as the mesh, and it is a node session in every respect but
|
|
three.**
|
|
|
|
| | |
|
|
|---|---|
|
|
| **the context it starts in** | the mesh's, not a machine's — this is the whole of what makes it different |
|
|
| **its engram** | the mesh's system prompt, as a node's engram is that node's |
|
|
| **its licence binding** | assigned in its own right, not inherited from the machine it runs on |
|
|
|
|
Everything else is unchanged and deliberately so: it is permanent, it remembers, it is reachable
|
|
over the broker, it holds its own tools, and switched off it still answers *I am switched off*
|
|
rather than falling silent.
|
|
|
|
**It runs on the node that holds the control plane** — not for convenience, but because that node
|
|
is already the one place excepted from *compromise of a node is compromise of that node*
|
|
(ADR 0004). An agent able to reach everything, placed anywhere else, creates a **second** such
|
|
place. Putting it where the authority already sits concentrates nothing new.
|
|
|
|
**It is an addition to per-node messaging and never a replacement.** Every node remains directly
|
|
addressable. This is not a preference: ADR 0001 holds that losing the control plane costs *change,
|
|
not operation*, and a mesh whose only conversational surface lives on that node would lose the
|
|
ability to ask anything while every machine kept running perfectly. **The front door may not be
|
|
the single point.**
|
|
|
|
**It is not an employee** ([ADR 0003](0003-agents-are-persistent-employees.md)). Nobody hires it,
|
|
it holds no task queue, it is never drained or reassigned. What it does with work that belongs
|
|
somewhere else is **dispatch it** — to node sessions, or to workers — which is what a node session
|
|
already does when asked something it does not have.
|
|
|
|
**It is ADR 0025's reader.** The agent that reads the design repository and answers into search is
|
|
this session, not a second one. One agent, one memory, one place to reach; two would both need
|
|
that repository and would eventually disagree about what it says.
|
|
|
|
**"One per node" is about address, not about process count.** ADR 0004's rule — *two and nothing
|
|
decides which replies* — forbids ambiguity in who answers when a **node** is addressed. The mesh
|
|
session answers when the **mesh** is addressed. The control-plane node therefore hosts two
|
|
sessions and no ambiguity, and stating this here is what stops it reading as a contradiction
|
|
later.
|
|
|
|
## Consequences
|
|
|
|
**The node session's setup must now be designed, and it never was.** This decision is expressed as
|
|
*the same as a node session, elsewhere*, which is only meaningful once that mechanism is written
|
|
down. The design document covering both is the immediate consequence of this record, not a
|
|
follow-up to it.
|
|
|
|
**A consumer that is not a machine stops being deferrable.** The licence binding above is the gap
|
|
`14-model-access.md` names, and it now has two consumers rather than a hypothetical one. Until it
|
|
exists, a session's model access can only be expressed as *this module on this machine*, which
|
|
cannot say *this node's session uses the personal licence and the mesh's uses the company one* —
|
|
the thing the binding is for.
|
|
|
|
**Symmetry is preserved, and it is worth being precise about why.** ADR 0004's claim is about what
|
|
a node can reach, and it is untouched: node-to-node messaging is unchanged, nothing is routed
|
|
through the mesh session, and it is a participant rather than a hop. What arrives is a
|
|
participant that happens to be the one a person usually addresses.
|
|
|
|
**Availability degrades to inconvenience rather than to silence** — but only because of the
|
|
addition rule above. If that rule is ever relaxed, this consequence inverts, and it inverts
|
|
quietly: everything keeps working and nobody can ask about it.
|
|
|
|
**The surface a person uses is not decided here.** That a board is a good place to talk to it is
|
|
likely and is not this record's business; the session is reachable over the broker like everything
|
|
else, and what puts a text box in front of it is a separate choice.
|
|
|
|
## References
|
|
|
|
- [ADR 0004](0004-a-node-and-how-it-joins.md) — the node session this extends
|
|
- [ADR 0025](0025-the-design-record-is-read-not-copied.md) — the reader this session is
|
|
- [ADR 0003](0003-agents-are-persistent-employees.md) — the vocabulary this is not
|
|
- [`03-DESIGN/01-to-be/14-model-access.md`](../03-DESIGN/01-to-be/14-model-access.md) — *a
|
|
consumer that is not a machine*, the gap this makes concrete
|