The mesh has a session of its own, and it is the node session's mechanism
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.
This commit is contained in:
@@ -81,6 +81,13 @@ to a node. What is delivered still lands on a machine; what is **chosen** is cho
|
||||
the provisions model has no consumer identity other than a node. What exists today is per module
|
||||
per machine, which is a step toward it and is not it.
|
||||
|
||||
*2026-08-31: this gap now has named consumers rather than hypothetical ones.*
|
||||
[ADR 0026](../../02-DECISIONS/0026-the-mesh-has-a-session-of-its-own.md) puts two sessions on the
|
||||
control-plane node — the node's own and the mesh's — each bound in its own right. **A per-machine
|
||||
binding cannot express that at all**, not merely awkwardly: the two sessions share a machine and
|
||||
must be able to hold different licences. See
|
||||
[`15-the-agent-session.md`](15-the-agent-session.md).
|
||||
|
||||
**Switching is a reaction, not a declaration.** A licence that hits its limit and must be swapped is
|
||||
a response to something observed. Expressing it as a declaration would make the declaration mean
|
||||
*whatever is working right now*, which is not a thing anybody declared. It belongs with
|
||||
|
||||
@@ -0,0 +1,192 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: designed
|
||||
code: [mesh-control, mesh-host]
|
||||
updated: 2026-08-31
|
||||
decisions:
|
||||
- 02-DECISIONS/0004-a-node-and-how-it-joins.md
|
||||
- 02-DECISIONS/0026-the-mesh-has-a-session-of-its-own.md
|
||||
- 02-DECISIONS/0024-model-access-is-a-provision.md
|
||||
- 02-DECISIONS/0025-the-design-record-is-read-not-copied.md
|
||||
---
|
||||
|
||||
# The agent session
|
||||
|
||||
**One mechanism, started twice.** A node's session and the mesh's session are the same thing
|
||||
pointed at different context. This document describes the mechanism; where the two differ it says
|
||||
so, and the differences are few enough to list here:
|
||||
|
||||
| | node session | mesh session |
|
||||
|---|---|---|
|
||||
| **address** | the node's name | the mesh |
|
||||
| **context root** | the node's | the mesh's |
|
||||
| **engram** | that node's | the mesh's |
|
||||
| **licence** | bound in its own right | bound in its own right |
|
||||
| **runs on** | that node | the node holding the control plane |
|
||||
| **how many** | one per node | one |
|
||||
|
||||
Everything below applies to both unless it says otherwise.
|
||||
|
||||
## What a session is, restated for what is being built
|
||||
|
||||
[ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md) settled the behaviour: permanent,
|
||||
remembering across callers, its own tools, reachable over the broker, and — switched off — still
|
||||
answering *I am switched off* rather than falling silent.
|
||||
|
||||
**Nothing said how one is set up**, and that gap is what this document closes. It was invisible
|
||||
until [ADR 0026](../../02-DECISIONS/0026-the-mesh-has-a-session-of-its-own.md) needed to describe
|
||||
a second instance, because *the same as that one, elsewhere* means nothing until the first has
|
||||
been written down.
|
||||
|
||||
## The context root is the whole of the difference
|
||||
|
||||
**A session is defined by the directory it starts in.** That directory holds the engram, the
|
||||
session's tools, and whatever standing instruction it works under. Two sessions differing only in
|
||||
their root are two different agents, and nothing else has to differ to make them so.
|
||||
|
||||
This is deliberately a **small** definition. The alternative — a session type, with the mesh
|
||||
session as a distinct kind — would mean two implementations of one mechanism, and
|
||||
[ADR 0001](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md) records what that
|
||||
costs: two things nearly the same, built twice, until neither word means one thing.
|
||||
|
||||
**The root is delivered as declared state, not carried by the session.** It is files on a machine,
|
||||
which is precisely what the host applies
|
||||
([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)). A session's context therefore changes the
|
||||
way anything else changes — the mesh declares it, the host writes it — and there is no second
|
||||
mechanism for shipping an engram.
|
||||
|
||||
**Changing the engram is changing a file.** So it is versioned, reviewable, and rolled back like
|
||||
any other declared state; and a node whose engram was changed reports having applied it, the same
|
||||
as it reports anything else.
|
||||
|
||||
## Where each one runs
|
||||
|
||||
**A node's session runs on that node**, and cannot be moved. Moved, one machine is answering as
|
||||
another (ADR 0004).
|
||||
|
||||
**The mesh's session runs on the node holding the control plane.** The reasoning is in ADR 0026
|
||||
and is worth carrying here because it is easy to get backwards: this is not *the important agent
|
||||
goes on the important machine*. It is that the control-plane node is already the one place
|
||||
excepted from *compromise of a node is compromise of that node*, and an agent able to reach
|
||||
everything, placed anywhere else, would create a second such place.
|
||||
|
||||
## Messages
|
||||
|
||||
**A session is reached over the broker**
|
||||
([ADR 0002](../../02-DECISIONS/0002-nodes-communicate-over-a-broker.md)). There is no second
|
||||
transport, nothing is dialled at a session, and the mesh session is not a hop: node-to-node
|
||||
messages continue to travel directly, and nothing is routed through it.
|
||||
|
||||
**A message becomes a prompt; a reply travels back the same way.** Whoever asked — a person at a
|
||||
surface, another session, a worker — is a caller, and the session remembers what each of them
|
||||
asked, together, over time.
|
||||
|
||||
**Being asked something it does not have, a session may ask another.** How it does so is its own
|
||||
business and follows from its engram rather than from a message format: it may say who wants to
|
||||
know, or simply ask. A person relaying a question makes the same choice.
|
||||
|
||||
**A switched-off session answers.** The queue is still read and the state is the reply, with no
|
||||
model involved. This is the same rule the host follows about a service that does not exist, and
|
||||
it is the rule this repository has now paid for three times: **absence must never be
|
||||
indistinguishable from a failure to answer**
|
||||
([005](../../04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md),
|
||||
[008](../../04-ISSUES/008-the-documented-node-rescue-does-not-exist/00-report.md)).
|
||||
|
||||
## Model access is bound to the session, not to the machine
|
||||
|
||||
**A session is a consumer in its own right.** This is the gap
|
||||
[`14-model-access.md`](14-model-access.md) records as *a consumer that is not a machine*, and it
|
||||
is the one part of this design that cannot be built from what exists: the provisions model has no
|
||||
consumer identity other than a node, so today a binding can only say *this module on this
|
||||
machine*.
|
||||
|
||||
That is not sufficient here, and the shortfall is concrete rather than theoretical:
|
||||
|
||||
- the control-plane node hosts **two** sessions, which must be able to hold **different**
|
||||
licences — a per-machine binding cannot express it at all;
|
||||
- *this node's session uses the personal licence, the mesh's uses the company one* is the ordinary
|
||||
case, not an exotic one.
|
||||
|
||||
**What is delivered still lands on a machine. What is chosen is chosen per session.** Delivery
|
||||
follows the session's context root, which is where its credentials belong — the same rule ADR 0001
|
||||
states for an agent's config directory, with the root standing in for it.
|
||||
|
||||
**Switching a licence remains a reaction, not a declaration** (ADR 0024). A session that exhausts
|
||||
a licence is observed and its binding changed; the binding is then declared as usual. Nothing here
|
||||
grows a conditional in the declaration language.
|
||||
|
||||
## What the mesh session knows
|
||||
|
||||
**It holds the design record by reading it**
|
||||
([ADR 0025](../../02-DECISIONS/0025-the-design-record-is-read-not-copied.md)), not by holding a
|
||||
copy. It is that reader; there is not a second agent for it.
|
||||
|
||||
**It answers into a symptom search**, so what it knows appears beside ordinary results rather than
|
||||
only when it is asked. **And when it cannot be reached, the search says so.** A result set that
|
||||
silently omits this material looks identical to one where nothing matched — the same rule as the
|
||||
switched-off session above, at a different layer.
|
||||
|
||||
**Reading is one-way.** It reads the repository and answers from it; nothing flows back. The
|
||||
repository is public and the mesh is not, and a return path is how installation-specific detail
|
||||
arrives into documents that must not carry it.
|
||||
|
||||
## What it does with work
|
||||
|
||||
**It dispatches; it does not hold a queue.** Asked for something that belongs elsewhere, it asks a
|
||||
node session or hands the work to a worker. It is not an employee
|
||||
([ADR 0003](../../02-DECISIONS/0003-agents-are-persistent-employees.md)): nobody hires it, it is
|
||||
never drained, and it is not reassigned.
|
||||
|
||||
The distinction is the one ADR 0001 was written to keep: a session comes with the thing it belongs
|
||||
to and goes when that thing goes; a worker is hired, holds tasks, and moves. Built from the same
|
||||
parts, run on entirely different terms.
|
||||
|
||||
## The surface is separate
|
||||
|
||||
That a person usually reaches the mesh session through a board is likely and is not settled here.
|
||||
The session is reachable over the broker like everything else; what puts a text box in front of it
|
||||
is a different design, and the session does not know which surface asked.
|
||||
|
||||
## Consequences
|
||||
|
||||
**Two sessions on one node, and no ambiguity.** The control-plane node hosts its own node session
|
||||
and the mesh session. ADR 0004's *one per node* forbids ambiguity about who answers when a **node**
|
||||
is addressed; these answer to different addresses.
|
||||
|
||||
**A new node gets a session by being declared, not by being set up.** The context root is declared
|
||||
state, so a joining node's session arrives the way its packages and services do.
|
||||
|
||||
**The mesh session is a single point of convenience, and must never become one of reach.** Every
|
||||
node stays directly addressable. If that ever stops being true, the failure is quiet in the worst
|
||||
way: every machine keeps working and nobody can ask about it.
|
||||
|
||||
## How it is checked
|
||||
|
||||
**A test names the decision it defends** ([ADR 0017](../../02-DECISIONS/0017-a-test-defends-a-decision.md)),
|
||||
and these run in the lab on real machines:
|
||||
|
||||
| Check | Defends |
|
||||
|---|---|
|
||||
| a node is asked something and its session answers | ADR 0004 |
|
||||
| the mesh is asked something and the mesh session answers, on the control-plane node | ADR 0026 |
|
||||
| both sessions on that node answer, to their own addresses, without ambiguity | ADR 0026 |
|
||||
| a session switched off replies saying so, rather than timing out | ADR 0004 |
|
||||
| a session whose engram was changed reports having applied it, like any declared file | ADR 0005 |
|
||||
| the two sessions on one node hold different licences, and each uses its own | ADR 0024 |
|
||||
| a node is messaged directly while the mesh session is stopped, and answers | ADR 0001 |
|
||||
| a search consulting an unreachable mesh session says it was not consulted | ADR 0025 |
|
||||
|
||||
The last two are the ones worth writing first. Both defend properties that are invisible while
|
||||
everything works, and both describe a mesh that looks entirely healthy at the moment it has
|
||||
stopped telling the truth.
|
||||
|
||||
## Deliberately not decided
|
||||
|
||||
**Whether the mesh session's memory is its own or assembled from the node sessions each time.**
|
||||
It remembers what it has been asked, which is settled. Whether *what the mesh knows* is a thing it
|
||||
holds or a thing it gathers on demand is a real question with a cost either way, and nothing here
|
||||
depends on the answer yet.
|
||||
|
||||
**How a person's identity reaches a session.** Callers are distinguished, but who a caller *is*,
|
||||
and whether a session should act differently for different people, is the human-agent question
|
||||
ADR 0001 leaves open and this does not close.
|
||||
@@ -20,6 +20,11 @@ document is written and this one's status becomes `implemented`.
|
||||
| [`08-connectivity.md`](08-connectivity.md) | One context in full — overlay, resolution, exposure, filtering, certificates | [ADR 0007](../../02-DECISIONS/0007-connectivity.md), [0050](../../02-DECISIONS/0007-connectivity.md), [0051](../../02-DECISIONS/0004-a-node-and-how-it-joins.md), [0055](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md) |
|
||||
| [`09-the-node-lifecycle.md`](09-the-node-lifecycle.md) | How a machine becomes a node, stays one, and stops being one | [ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md), [0051](../../02-DECISIONS/0004-a-node-and-how-it-joins.md) |
|
||||
| [`10-delivery.md`](10-delivery.md) | Modules, the three edges, and how a change becomes a running thing | [ADR 0010](../../02-DECISIONS/0010-delivery.md), [0064](../../02-DECISIONS/0009-modules-and-the-graph.md), [0065](../../02-DECISIONS/0009-modules-and-the-graph.md) |
|
||||
| [`11-a-board.md`](11-a-board.md) | What a person sees of the mesh, and why it is read from what runs | [ADR 0008](../../02-DECISIONS/0008-a-context-owns-its-store.md), [ADR 0001](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md) |
|
||||
| [`12-a-module-repository.md`](12-a-module-repository.md) | A module repository, and what builds it | [ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md), [ADR 0010](../../02-DECISIONS/0010-delivery.md), [ADR 0005](../../02-DECISIONS/0005-the-node-host.md) |
|
||||
| [`13-credentials-and-their-rotation.md`](13-credentials-and-their-rotation.md) | Credentials, and moving them without a consumer holding one the provider does not know about | [ADR 0001](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md), [ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md) |
|
||||
| [`14-model-access.md`](14-model-access.md) | Model access as a provision, and what a licence is bound to | [ADR 0024](../../02-DECISIONS/0024-model-access-is-a-provision.md), [ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md) |
|
||||
| [`15-the-agent-session.md`](15-the-agent-session.md) | One mechanism started twice — a node's session and the mesh's | [ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md), [ADR 0026](../../02-DECISIONS/0026-the-mesh-has-a-session-of-its-own.md) |
|
||||
|
||||
## Not yet written
|
||||
|
||||
|
||||
Reference in New Issue
Block a user