ADR 0153 and ADR 0154: the record is read by a module, and the mesh's verbs are its seat's tools
Design 33 in progress against ADR 0154 (the twelve verbs, the prerequisites built); design 35 for the records module under ADR 0153, extending 0025; as-is 07 rewritten to a mesh that keeps no store; as-is 12 and 13 updated; issue 006 built and waiting on its live check.
This commit is contained in:
@@ -1,78 +1,58 @@
|
||||
---
|
||||
layer: as-is
|
||||
status: implemented
|
||||
code: [hal]
|
||||
updated: 2026-08-23
|
||||
decisions: []
|
||||
code: [mesh-catalog modules/records, mesh-catalog modules/mesh-console]
|
||||
updated: 2026-09-30
|
||||
decisions:
|
||||
- 02-DECISIONS/0025-the-design-record-is-read-not-copied.md
|
||||
- 02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md
|
||||
- 02-DECISIONS/0152-the-operators-surface-is-a-module-the-console.md
|
||||
---
|
||||
|
||||
# Knowledge
|
||||
|
||||
The mesh keeps two knowledge stores. They are not redundant, and knowing which is which is the
|
||||
difference between finding an answer in one search and rediscovering it over several hours.
|
||||
**The mesh keeps no knowledge store.** What it knows is what its modules answer, and the way a person
|
||||
or an agent asks is the console's tool list on the machine they sit at
|
||||
([13 — The console](13-the-console.md)). This document used to describe two stores; it is rewritten
|
||||
because neither exists from the mesh's side, and an as-is document that describes what is gone is a
|
||||
brochure.
|
||||
|
||||
## The operational memory
|
||||
## What was here, and where it went
|
||||
|
||||
A store of operational notes, written and read by whoever — human or agent — is working. Each
|
||||
note is a slug and a body: how something works, what went wrong, what the fix was, what
|
||||
assumption turned out to be false.
|
||||
Until the cut-over of 2026-09-28 the predecessor ran two stores: an operational memory of notes
|
||||
indexed on symptoms, and a structured archive of governed documents with a librarian approving
|
||||
promotion. Both were reached through the predecessor's tool server over the bus the mesh removed
|
||||
([issue 147](../../04-ISSUES/147-the-operators-tools-still-dial-the-bus-that-was-removed/00-report.md)).
|
||||
Nothing in the mesh reaches them now, and nothing in the mesh has replaced them: there is no note
|
||||
store, no archive, no librarian, and the lessons of the last days were written into this repository by
|
||||
hand. That is a gap, and it is stated here rather than papered over. What replaces a symptom-indexed
|
||||
memory, if anything does, is undecided.
|
||||
|
||||
It is indexed on **symptoms**. The entry someone needs is usually titled after the error they
|
||||
are staring at, which is why the standing instruction is to search the literal error text
|
||||
before forming a hypothesis rather than after one fails.
|
||||
## The record
|
||||
|
||||
Its content is overwhelmingly the record of previous debugging: a large body of
|
||||
troubleshooting entries, module conventions, and standing notes about work that is open. It is
|
||||
the mesh's institutional memory of *what has already gone wrong*.
|
||||
**The design record is read where it is written.** Since 2026-09-30 a module, `records`, keeps a
|
||||
checkout of this repository from the forge — cloned from the `git` seat, reset to the origin on every
|
||||
merge the forge announces and every ten minutes — and answers over the bus: where a phrase appears as
|
||||
written, one document whole, what a folder holds, and where the checkout stands, each naming the
|
||||
commit it read. Which repository it reads is a setting on its assignment; the module names no mesh.
|
||||
|
||||
The cost of skipping it is documented in the mesh's own record: entries have been rediscovered
|
||||
from scratch, over hours, in sessions where the search was skipped because the trail felt
|
||||
confident. It fires hardest on familiar ground, not unfamiliar ground.
|
||||
It is listed by the console beside every other tool, with a description that says to search the
|
||||
literal words of a symptom before forming a hypothesis. That is what
|
||||
[ADR 0025](../../02-DECISIONS/0025-the-design-record-is-read-not-copied.md) meant by *beside
|
||||
everything else*, in a mesh with no store to be beside
|
||||
([ADR 0153](../../02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md)).
|
||||
|
||||
## The structured archive
|
||||
Nothing is copied. A checkout lags the source by seconds after an announced merge and by minutes
|
||||
otherwise, and says so.
|
||||
|
||||
A second store, structured rather than flat: spaces, pages, revisions, tiers, and full-text
|
||||
search. Where the operational memory is a note, this is a document with an owner and a
|
||||
lifecycle.
|
||||
## The constitution
|
||||
|
||||
Content is promoted through tiers — private, then team, then platform — with a librarian agent
|
||||
owning approval and promotion at the boundary. Proposals to edit are reviewed rather than
|
||||
applied.
|
||||
|
||||
This is where the mesh's **governed** documents live, including the constitution injected into
|
||||
design sessions ([ADR 0020](../../02-DECISIONS/0020-the-mesh-is-governed-by-a-constitution.md)).
|
||||
|
||||
## Why both
|
||||
|
||||
The distinction is by lifecycle, not by subject.
|
||||
|
||||
| Operational memory | Structured archive |
|
||||
|---|---|
|
||||
| Written the moment something is learned | Written deliberately, reviewed |
|
||||
| Flat, symptom-indexed | Structured, tiered, owned |
|
||||
| Anyone writes; nothing approves | Promotion is approved |
|
||||
| Truth is "this happened" | Truth is "this is agreed" |
|
||||
|
||||
Collapsing them would cost one of the two properties: either every hard-won note waits for
|
||||
review, or governed documents can be changed by anyone mid-incident.
|
||||
[`00-META/how-we-build.md`](../../00-META/how-we-build.md) is the source of the mesh constitution
|
||||
([ADR 0021](../../02-DECISIONS/0021-hq-is-the-source-of-the-constitution.md)). The page it used to be
|
||||
synchronised into lived in the predecessor's archive and is unreachable; the constitution today is
|
||||
read from this repository, through the same module, and playbook 05's sync has nothing to write to.
|
||||
|
||||
## Where this repository sits
|
||||
|
||||
This repository is a third thing, and the objection was raised when it was created: a fourth
|
||||
knowledge system repeats the mistake the split was made to fix.
|
||||
|
||||
The answer given was **indexing, not location** — that these documents are indexed into the
|
||||
knowledge base so that a symptom search returns them alongside everything else. One source,
|
||||
many surfaces.
|
||||
|
||||
**That indexing does not currently exist.** A search for this repository's content returns
|
||||
nothing. The claim is load-bearing for the decision to separate the repository at all, and
|
||||
until it is true, this repository is exactly the fourth knowledge system the objection
|
||||
described. Recorded here because it is a statement about how the mesh's knowledge actually
|
||||
works today, and as [`04-ISSUES/006`](../../04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md).
|
||||
|
||||
## The librarian
|
||||
|
||||
A single agent owns the archive's approvals and promotions. Its approval capabilities have at
|
||||
times not been reachable as tools, which does not affect the operational memory but does mean
|
||||
promotion stops silently — the store keeps accepting proposals that nothing can approve.
|
||||
A third thing beside two that are gone, which makes it the first: the one governed record the mesh
|
||||
has, public, read by a module the mesh assigns, and edited nowhere else.
|
||||
|
||||
@@ -82,6 +82,22 @@ to clone.
|
||||
The schema column added for this defaults to empty rather than null, because "not on a seat" is a
|
||||
real answer, so every row recorded before the change keeps exactly the meaning it had.
|
||||
|
||||
## A seat's protocol is on its row, and the controller serves its own
|
||||
|
||||
*Since 2026-09-30 ([ADR 0154](../../02-DECISIONS/0154-the-meshs-own-verbs-are-the-controller-seats-tools.md)).*
|
||||
The `seat` table carries `accepts`, `emits` and `serves`; `serves` holds each verb with its description
|
||||
and input schema. The rows were seeded from the compiled defaults the first time a controller with the
|
||||
columns migrated, and each later migration adds any verb the defaults name that a row lacks, never
|
||||
removing one. `UseSeats` still falls back to the compiled protocol for a row with none, which after the
|
||||
first seeding is no row.
|
||||
|
||||
The `mesh-controller` seat serves twelve verbs — `tools`, `status`, `nodes`, `node`, `modules`, `seats`,
|
||||
`builds`, `plan`, `assign`, `unassign`, `push`, `build` — on `mesh.seat.mesh-controller.tool.<verb>`,
|
||||
each answered by the controller running that command in its own binary and returning what it printed.
|
||||
A module claiming a mesh seat with verbs must list them under `tools` or registration refuses it by
|
||||
name. A node-scoped seat's tool is `mesh.seat.<seat>.tool.<verb>.<node>`; no node-scoped seat declares
|
||||
one yet.
|
||||
|
||||
## Where this differs from the design
|
||||
|
||||
**Capacity is not implemented.** The design's vocabulary has a seat with a capacity, and a
|
||||
|
||||
@@ -1,12 +1,13 @@
|
||||
---
|
||||
layer: as-is
|
||||
status: implemented
|
||||
code: [mesh-catalog modules/mesh-console, mesh-tools src/mesh.ts, mesh-tools src/http.ts, mesh-tools src/runtime.ts, mesh-controller internal/broker, mesh-controller cmd/mesh-controller/check.go]
|
||||
code: [mesh-catalog modules/mesh-console, mesh-tools src/mesh.ts, mesh-tools src/http.ts, mesh-tools src/runtime.ts, mesh-controller internal/broker, mesh-controller cmd/mesh-controller/check.go, mesh-controller cmd/mesh-controller/seatverbs.go]
|
||||
updated: 2026-09-30
|
||||
decisions:
|
||||
- 02-DECISIONS/0152-the-operators-surface-is-a-module-the-console.md
|
||||
- 02-DECISIONS/0095-the-control-plane-is-the-way-to-ask-a-module.md
|
||||
- 02-DECISIONS/0037-where-a-module-lives.md
|
||||
- 02-DECISIONS/0154-the-meshs-own-verbs-are-the-controller-seats-tools.md
|
||||
---
|
||||
|
||||
# The console, as it runs
|
||||
@@ -30,11 +31,14 @@ mesh records rather than rolls out — and 62 tools from the rest.
|
||||
`tools/call` reaches any tool by `<module>.<tool>`, listed or not. The console's grant is `*`, so what it
|
||||
may call is every tool on the mesh; its account may publish nothing else and subscribes nothing.
|
||||
|
||||
## What it does not answer
|
||||
## The mesh's own verbs
|
||||
|
||||
The mesh's own verbs. `status`, `push`, `assign` and the rest are not served on the bus — they are the
|
||||
`mesh-controller` seat's tools under ADR 0132, whose three prerequisites are not built — so a person
|
||||
still opens a shell on the control node for them. The console's handshake says so.
|
||||
*Since 2026-09-30 evening ([ADR 0154](../../02-DECISIONS/0154-the-meshs-own-verbs-are-the-controller-seats-tools.md)).*
|
||||
The console asks the `mesh-controller` seat's `tools` verb beside the modules and lists every role's
|
||||
tools as `<seat>.<verb>` — `mesh-controller.status`, `mesh-controller.push` and the other ten. A call
|
||||
to `<prefix>.<name>` reaches the seat when the prefix is a seat declaring that verb, and the module
|
||||
otherwise; `seat:<seat>.<verb>` says so outright. When the control plane does not answer, the list
|
||||
names `mesh-controller (seat)` as not answering and carries the modules' tools regardless.
|
||||
|
||||
## Around it
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ Where the two disagree, the implementation wins and the disagreement is stated.
|
||||
| [`04-delivery.md`](04-delivery.md) | Push to running: the three silos, levels, and what a green pipeline proves |
|
||||
| [`05-runtime-and-installation.md`](05-runtime-and-installation.md) | The node runtime, its modes, and how a node comes into being |
|
||||
| [`06-configuration-and-secrets.md`](06-configuration-and-secrets.md) | Managed files, value resolution, and where secrets live |
|
||||
| [`07-knowledge.md`](07-knowledge.md) | The two knowledge stores, and what each is for |
|
||||
| [`07-knowledge.md`](07-knowledge.md) | The mesh keeps no store: what it knows is what modules answer, and the record is read by one |
|
||||
| [`08-agents-and-work.md`](08-agents-and-work.md) | Agents as employees, tasks, workflows, and the meeting model |
|
||||
| [`09-interfaces-and-observability.md`](09-interfaces-and-observability.md) | How the mesh is reached and watched — tools, board, proxy, health, thoughts |
|
||||
| [`10-module-catalogue.md`](10-module-catalogue.md) | The catalogue's shape, and what its shape says |
|
||||
|
||||
@@ -148,6 +148,10 @@ than reproduced from a declaration — because there is nothing to reproduce 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.
|
||||
|
||||
*2026-09-30:* the reading is a module's — `records`, [35 — Reading the record](35-reading-the-record.md),
|
||||
[ADR 0153](../../02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md). The
|
||||
session, when built, asks it rather than reading for itself; what it adds is judgement, not text.
|
||||
|
||||
**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
|
||||
|
||||
@@ -1,9 +1,10 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: designed
|
||||
code: []
|
||||
updated: 2026-09-28
|
||||
status: in-progress
|
||||
code: [mesh-controller, mesh-tools]
|
||||
updated: 2026-09-30
|
||||
decisions:
|
||||
- 02-DECISIONS/0154-the-meshs-own-verbs-are-the-controller-seats-tools.md
|
||||
- 02-DECISIONS/0132-a-seat-carries-the-tools-its-holder-must-serve.md
|
||||
- 02-DECISIONS/0129-a-seat-carries-the-protocol-of-its-role.md
|
||||
- 02-DECISIONS/0095-the-control-plane-is-the-way-to-ask-a-module.md
|
||||
@@ -126,6 +127,18 @@ by side until nothing is bound to the old one.
|
||||
- **Two nodes holding one node-scoped seat derive two addresses.** Checked by the same test as the rest
|
||||
of the subject table.
|
||||
|
||||
## What is built, 2026-09-30
|
||||
|
||||
Under [ADR 0154](../../02-DECISIONS/0154-the-meshs-own-verbs-are-the-controller-seats-tools.md): §2's
|
||||
two constraints (the protocol in the store's row, seeded additively; a verb with description and
|
||||
schema, a bare name still accepted), §3 for the mesh's seats (holding refused by naming the missing
|
||||
verbs), §4 (a node-scoped seat's tool carries the node as its last subject token; a user publishes
|
||||
`*`), and the third family — twelve verbs on the `mesh-controller` seat, each running the command it
|
||||
names in the controller's own binary. §5's first half is served rather than read: the seat's `tools`
|
||||
verb answers every seat's tools from the records, because the console cannot read the store; the
|
||||
console lists a role's tools beside the modules' own and resolves `<seat>.<verb>` to the seat when the
|
||||
seat declares that verb. Which verbs each *other* seat serves stays a decision per seat, still untaken.
|
||||
|
||||
## What this does not settle
|
||||
|
||||
- Which verbs each seat should serve. That is a decision per seat, and the reason to do it slowly: a
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
code: [mesh-catalog modules/records]
|
||||
updated: 2026-09-30
|
||||
decisions:
|
||||
- 02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md
|
||||
- 02-DECISIONS/0025-the-design-record-is-read-not-copied.md
|
||||
- 02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md
|
||||
---
|
||||
|
||||
# 35 — Reading the record
|
||||
|
||||
**The design record, answered from a checkout the mesh keeps, at the commit it read.** A module,
|
||||
`records`, holds a working copy of a repository of markdown — this one, for this mesh — and answers
|
||||
where a phrase appears, what a document says, what a folder holds and where the copy stands. The
|
||||
console lists those answers beside every other tool
|
||||
([ADR 0153](../../02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md)).
|
||||
|
||||
## 1. What it keeps, and why that is not a copy
|
||||
|
||||
A git checkout, cloned from the forge that holds the `git` seat, brought up to date on every merge the
|
||||
forge announces and every ten minutes besides. The bytes are the repository's; nothing is derived
|
||||
from them and stored. What [ADR 0025](../../02-DECISIONS/0025-the-design-record-is-read-not-copied.md)
|
||||
refused was a second store that is *searched* while the first is *edited*, drifting silently. A
|
||||
checkout cannot drift; it can lag, and the lag is in every answer as the commit it was read at and
|
||||
in `records_status` as when it was last brought up to date.
|
||||
|
||||
The checkout is reset to the origin on every sync, never merged: it is the mesh's, so a local change
|
||||
is nobody's.
|
||||
|
||||
## 2. What it answers
|
||||
|
||||
| tool | answers |
|
||||
|---|---|
|
||||
| `records_search` | every place a phrase appears, as written and case-insensitively: document, line, the nearest heading above it; bounded, and says when it was |
|
||||
| `records_read` | one document, whole, or its first part with a note when very long |
|
||||
| `records_list` | what a folder holds: sub-folders and documents |
|
||||
| `records_status` | repository, forge, commit and its date, last sync, document count, last error |
|
||||
| `records_sync` | bring the checkout up to date now |
|
||||
|
||||
No ranking and no summary, on purpose: a record is found by its own words, and the reasoning is in
|
||||
the document, not in the tool.
|
||||
|
||||
## 3. What it is told, and what it refuses to guess
|
||||
|
||||
Three things, none from a manifest ([ADR 0112](../../02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md)):
|
||||
the directory its checkout lives in (a resource the mesh gives it), the forge's address (the `git`
|
||||
provision's binding, written into a file as `scheme://host:port`), and the repository's path on the
|
||||
forge (a **setting**, `{"repository": "<owner>/<name>"}`). Without the third it serves no tools and its
|
||||
log says so. Public repositories only; it holds no credential.
|
||||
|
||||
## 4. How it is found
|
||||
|
||||
The console asks every module what it serves and lists `records_search` with a description that says
|
||||
when to call it — *search the literal words of a symptom or a term before forming a hypothesis*. That
|
||||
is 0025's second half in today's mesh: there is no store to be beside, and an agent choosing from a
|
||||
tool list is the search.
|
||||
|
||||
## 5. Where it runs
|
||||
|
||||
Anywhere a node has the forge in reach; one assignment is enough, and a second on another machine is
|
||||
harmless. The mesh session of design 15, when it exists, calls this rather than reading for itself.
|
||||
|
||||
## How it is checked
|
||||
|
||||
| Check | Defends |
|
||||
|---|---|
|
||||
| a phrase in one document of a repository the test makes comes back from that document, with the commit; a second commit on the origin is pulled and the next answer names it | ADR 0025's check, ADR 0153 |
|
||||
| a path outside the checkout is refused; an empty search is refused | the reader reads the repository and nothing else |
|
||||
| a sync against an unreachable origin leaves the checkout standing and says why | silence and success never look alike |
|
||||
| live: through the console, `records_search` for a phrase that appears only in a design document here returns it | issue 006's closing check |
|
||||
|
||||
## What this does not settle
|
||||
|
||||
- Ranking or meaning. A search that understands a question is the session's job, not the reader's.
|
||||
- A private repository. That is a credential the module would have to hold, and a decision about
|
||||
what may read what.
|
||||
|
||||
## References
|
||||
|
||||
- [ADR 0153](../../02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md)
|
||||
- [ADR 0025](../../02-DECISIONS/0025-the-design-record-is-read-not-copied.md)
|
||||
- [34 — The console](34-the-console.md) — what lists it
|
||||
- [issue 006](../../04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md)
|
||||
Reference in New Issue
Block a user