Designs 25, 26, 20, playbook 06, glossary: follow ADR 0625 to 0627 for the registry milestone

Design 25 § 12.3 now says how the bus module's process really receives a person's
request (its own state requests, the warrant verified by the process itself), the
process account with keeps it holds beside the snapshot account, and that
mesh-broker's events go on the shared stream like every seat's, with the 30-day
history its own stream. Design 26 gains where a seat's code goes: a package per seat,
the seat-set package in mesh-contracts, the seven client packages and the
seat-neutral parts transfer; design 20 and playbook 06 tell a module's author the
same, and the glossary gains client package and seat-set package. mesh-developer
stops at two thirds of its context, as the milestone's agents learned.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
This commit is contained in:
2026-11-04 13:19:57 +01:00
parent 273d608d9f
commit da1c7f30a9
6 changed files with 250 additions and 61 deletions
+5
View File
@@ -28,5 +28,10 @@ rows or subtests in existing tests where the repository is over the test budget
sleeping. Run `go vet ./...`, `go vet -tags integration ./...` and `go test ./...` in every touched module as
the running checker places siblings (playbook 07). Use a temporary directory under `/var/tmp` (TMPDIR).
**Stop at about two thirds of your context.** Commit what is done, write a section under your agent label at the
end of the handover file the caller named (the subtasks done by label, the head of each worktree, what is left in
order, the findings), and report. A fresh agent continues from that section; work past that point is lost when the
context runs out.
Report in under 20 lines: per clause or subtask the change (file:line) and its test, that each test failed
first, the full commit ids, anything the prepare got wrong, and what is left. Glossary words only.
+21 -5
View File
@@ -98,14 +98,26 @@ and repair).
- **tool** — one capability a module serves through the tool runner, addressed `<module>.<tool>`. A
seat's **verb** is the same thing carried by a seat rather than a module.
- **mesh-sdk** — the library a module's own code is written against, including the SDK harness that serves a
tools bundle to the tool runner. The SDK harness is part of it, not a library of its own. It keeps the shared
runtime, and its seat contracts move into `mesh-contracts` (ADR 0608 §5).
tools bundle to the tool runner. The SDK harness is part of it, not a library of its own. It keeps the runtime
every module uses, and the seat-neutral parts two or more seats' clients or holders share; its seat contracts and
the logic it held over seats move into the contracts modules, and its seat list into the seat-set package
(ADR 0608 §5, ADR 0625 §2, §9, ADR 0627 §2).
*Not:* ~~tools-sdk~~
- **contracts module** — a module whose work is to publish the contract packages of seats (their verbs, events,
the layouts of their states, their messages) in every language the seats' users are written in, and never logic:
`mesh-contracts` for the seat contracts mesh-sdk held, `mesh-<area>-contracts` for an area's. A seat's holder
implements the contract; the contracts module holds no seat (ADR 0608 §5).
the layouts of their states, their messages), one per seat defined whole and per language, the seat-set package,
and the seats' client packages; every file but a client's is generated. `mesh-contracts` for the Core domain's
seats and every domain that has none yet, `mesh-<domain>-contracts` for a domain's, named after its heading on
this page; a seat defined outside the mesh's own contracts has one of its own. A seat's holder implements the
contract; the contracts module holds no seat (ADR 0608 §5, ADR 0625 §1, §5 to §7).
*Not:* ~~SDK module~~, ~~domain package~~
- **client package** — the one hand-written package a seat may carry beside its contract, in the seat's contracts
module and never in a holder: the logic two or more callers would otherwise each write over that seat. It uses
only its own seat's contract and mesh-sdk's runtime, never another seat's client, and names no holder, no module's
tool and no module's subject (ADR 0625 §4, ADR 0627 §1, §3). Bare "client" only where the sense is plain (see
[Homonyms](#homonyms)).
- **seat-set package** — the generated package in `mesh-contracts` holding every seat not yet defined whole at the
seat list's grain (its name, scope, verbs and provision); mesh-sdk's `catalogue` is its one importer in mesh-sdk
(ADR 0625 §2, §3).
- **contracts marker** — the field `generated-from` of a contracts module's package artifact, naming the directory
of the seat definitions its files are generated from; the judge refuses a module carrying it that claims a seat,
and the build modules' test step regenerates and compares every module carrying it (design 26).
@@ -1186,6 +1198,10 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
| harness | the part of `mesh-sdk` that serves a tools bundle | **SDK harness** | Module |
| | the program that runs an agent's sessions | **agent harness** | Operator and conversation |
| | the TypeScript `provisioner` helper for database providers | **`provisioner`**, renamed by design 57 | Provisioning |
| client | the hand-written logic beside a seat's contract | **client package** | Module |
| | mesh-provisioner's part on one node | **provisioner client** | Provisioning |
| | a module fetching a media release | **download client** | Media |
| | the operator's mail in a browser | **mail web client** | Mail |
| series | the first two numbers of a package's versions | **package series** | Module |
| | a kind of content told in episodes | the kind **series** | Media |
| role | what a seat names, at a scope | **seat**; the bare word in older designs is tracked by issue 872 | Module |
+16
View File
@@ -83,6 +83,22 @@ Three questions, answered from the machine:
thing works: the credential authenticates, a wrong one is refused, the containers reach each
other, the data survives a restart.
## A module that calls or holds a seat
*Added 2026-11-04* (ADR 0625, ADR 0627). Where each piece of a seat's code goes is
[design 20](../../03-DESIGN/01-to-be/20-writing-a-module.md) *Where a seat's code goes*; in short:
- **Import the seat's contract and, where it has one, its client package**, from the seat's contracts module
(`mesh-contracts` today), never the holder module and never a copy of the seat's types in your own code.
- **Logic you would write over a seat that another caller would write too** belongs in that seat's client package,
through a change of the contracts module; it never goes into mesh-sdk, and never into the holder.
- **Holding a seat** means implementing its contract in your module. A seat you define yourself gets a contracts
module of its own (it may share your repository); a role no other module could ever take over is your module's
own tools and events, not a seat.
The review of the pull request checks this; the checks design 26 lists refuse a stray file in a contracts module,
a seat named in mesh-sdk and a client reaching another seat's client.
## What the first port actually cost
Six attempts, one real bug. Recorded because the ratio is the lesson: **the mesh was right every
+29 -1
View File
@@ -5,8 +5,11 @@ code:
- mesh-catalog modules/showcase
- mesh-controller internal/builder
- mesh-sdk src
updated: 2026-10-02
- mesh-contracts
updated: 2026-11-04
decisions:
- "ADR 0625"
- "ADR 0627"
- "ADR 0150"
- "ADR 0099"
- "ADR 0053"
@@ -47,11 +50,36 @@ Split the way the protocol is split:
mesh set. Reading a file is not a thing an SDK needs to teach.
- **No API clients.** A Plex client belongs in the Plex module. It changes when Plex changes,
which has nothing to do with any other module — *frequent **and** cascading is the disease.*
Logic over a *seat* is not such a client: it is the seat's client package, in the seat's contracts
module (below), never in the SDK and never in a holder.
- **No storage, no HTTP framework, no logging library.** Use the language's.
If you find yourself wanting to add something to the SDK, the test is ADR 0039's: **does editing it
recompile unrelated modules, and does it change often?** Both, and it does not belong.
## Where a seat's code goes
*Added 2026-11-04* (ADR 0625, ADR 0627; [design 26](26-the-seats.md) *Where a seat's code goes* is the
whole rule). A module that calls or holds a seat meets three places, and each piece of code has one:
| the code | lives in | written |
|---|---|---|
| a seat's types, subjects and a typed call per verb or accept | the seat's **contract**: a package of its own per language in the seat's contracts module (`mesh-contracts`, or `mesh-<domain>-contracts` once its domain moves), or the seat-set package while the seat is not yet defined whole | generated from the seat's definition, never by hand |
| logic two or more callers would otherwise each write over that seat (an ask and its awaited answer, publishing a file in parts to a registry) | the seat's **client package**, beside its contract, owned by the contracts module | by hand; it uses only its own seat's contract and mesh-sdk's runtime, never another seat's client, and names no holder, no module's tool and no module's subject |
| what every module needs whatever the seat (the bus connection, the tools bundle's runtime, state), and a part several seats' clients or holders share that names no seat, verb or seat's type (moving a file in parts) | **mesh-sdk** | by hand; it takes no seat-specific type |
| the seat's implementation | the **holder** module | by hand, against the contract; never the place of the contract or a client |
**So a module imports the contracts and clients of the seats it uses, and mesh-sdk.** Its users rebuild when a
seat they use changes, not when any seat does. A seat you define yourself, outside the mesh's own contracts, gets a
contracts module of its own, which may share your holder module's repository (ADR 0625 §7): a second holder then
imports only the contract, never your holder. And a role no other module could ever take over is no seat at all:
it is your module's own tools and events (ADR 0625 §8).
*How it is checked:* by the checks design 26 lists: the generators' tests, mesh-sdk's import and package-list tests,
the build modules' regenerate-and-compare step, the catalog check of a client and the judge's refusal of a
contracts module that claims a seat; a role made a seat, or a seat left as one module's tools, by the review of the
pull request that adds it.
## A module with four capabilities, in four languages
A module is **one piece of software** (ADR 0040) and
+73 -37
View File
@@ -13,6 +13,9 @@ code:
updated: 2026-11-04
decisions:
- "ADR 0595"
- "ADR 0626"
- "ADR 0627"
- "ADR 0436"
- "ADR 0619"
- "ADR 0615"
- "ADR 0621"
@@ -210,6 +213,9 @@ holding `mesh-broker` — has an account of its own whose only grant is the snap
names, a stream's information, the snapshot request and its acknowledgements, and its own inbox. The
night's backup takes every stream through it ([to-be 43](43-backups-against-mistakes.md)). The
controller stays the only writer of stream definitions; the writers table holds that at composition.
*Amended 2026-11-04, ADR 0626 §2:* that account keeps exactly this grant; beside it, the bus module's process holds
a process account of its own for the bus state it creates (§ 12.2), so the module holding `mesh-broker` holds two
accounts, each doing only what its record grants.
### The store window, and what moving it into the server changes
@@ -732,16 +738,25 @@ modules' names meet.
creates streams and buckets under modules' names only, and deletes only through `drop` and `recreate`. Its health
turns unhealthy, naming the cause, when an accepted verdict has waited on its durable consumer, unanswered, for
more than three minutes, or when its last pass over fill, which runs every minute, is more than three minutes old, so the only guard against a store filling never stops without a sound; another module's entry past the raise mark
raises that module's condition and leaves the bus module healthy. **Its process has a bus account of its own**,
composed by the grants part for the holder of the seat `mesh-broker` (a seat, never a module's name), minted by the
vault as an own secret: JetStream create and update under modules' names only (streams, buckets and object stores
`<module>_*`), their delete subjects, and the seat's subjects for `create`, the seat's `apply`, `recreate` and
`drop`, which no other account holds, the tool runner's included.
raises that module's condition and leaves the bus module healthy. **Its process has a process account of its own,
granted more than any other process's** (ADR 0626 §1; ADR 0436 §1, §2). The process declares `bus` as any process
may, with one key more, `keeps`, which is allowed on this process alone; the grants part composes the account from
that declaration as it composes every process account, and the vault mints it as the module's own secret. Beyond
what a process's `bus` grants, `keeps` grants the bus's create and update subjects for streams, buckets and object
stores under modules' names only (`<module>_*`), the snapshot request for an entry before `recreate` or `drop` with
its chunks' acknowledgement subjects and its own inbox, and the delete subjects for those two acts. It is granted
no subject on which a tool or a seat's verb is answered (ADR 0436 §3), and no subscription to any restricted
stream's own subjects: the snapshot is the one way a restricted stream's data reaches it, kept only in the bus's
snapshot store, and the process reads no message of it. No other account holds those subjects, the tool runner's
included. **The snapshot account stays as it is** (ADR 0626 §2, § 3 above). **The judge refuses any other bus
declaration of the bus module** (ADR 0626 §3): anything it would say or hear on the bus beyond its process's `bus`
and the bus state the foundation keeps on the old sections (ADR 0595 §10), `keeps` on any other process or module,
and a `bus` of its process that names a subject on which a tool or a verb is answered.
- **The binding travels on the bus module's events** (ADR 0595 §1, §7, as their progressive insight of 2026-11-03
has it, waiting for the operator's Approve). The grants part, which issues every membership, hears them on a durable
consumer: it writes the **binding** (the names on the bus) into the module's membership on `created`, on every
machine the module is assigned, rewrites it on `recreated` and removes it on `dropped`, kept in its own state
`memberships`, so no part writes another's state and a binding outlives the 30 days its event is kept.
`memberships`, so no part writes another's state and a binding outlives the 7 days its event is kept on the shared stream (§ 12.3).
A module whose binding is missing at start fails loudly, naming the entry; it never starts blind. A `refused`
create hands no binding. **A refused or overdue creation is loud**: overdue means no `created` or `refused` within
five minutes of an accepted verdict that asks for the entry. The condition is raised by the watchman, which today raises the judge's
@@ -843,9 +858,9 @@ vault as an own secret: JetStream create and update under modules' names only (s
### 12.3 The seat's verbs, events and fill
The seat `mesh-broker`, until now a seat with no verbs, gains these (ADR 0595 §5, §6). It is one of the nine seats
defined whole in the milestone of ADR 0612, its contract in `mesh-contracts` (ADR 0613 §1; design 26 *A seat's
definition*), which settles where its definition lives (ADR 0595 §12). An entry's arguments are the module, its local
The seat `mesh-broker`, until now a seat with no verbs, gains these (ADR 0595 §5, §6). It is one of the ten seats
defined whole in the milestone of ADR 0612, its contract a package of its own in `mesh-contracts` (ADR 0613 §1,
ADR 0627 §1, ADR 0625 §1; design 26 *A seat's definition*), which settles where its definition lives (ADR 0595 §12). An entry's arguments are the module, its local
name, its storage type, its template, its options and its configuration; what is held answers the settings held and
the fill (count, bytes, the cap); `drop` and `recreate` carry the warrant and why.
@@ -855,27 +870,35 @@ the fill (count, bytes, the cap); `drop` and `recreate` carry the warrant and wh
| `show` | one entry, the same | the same |
| `check` | compares what the bus holds with what was asked, entry by entry | the same |
| `orphans` | entries the bus holds that no manifest asks for; never one whose manifest the judge refused or outgrew, nor one of the foundation's old sections | the same |
| `create` | creates one entry now | the bus module's own process only |
| `apply` | applies a difference that only grows: a larger cap, a longer age | the bus module's own process only |
| `recreate` | rebuilds an entry whose settings differ in a way that cannot grow, from its data where the storage type allows | the bus module's process, on the operator's warrant |
| `drop` | removes one orphan | the bus module's process, on the operator's warrant |
| `create` | creates one entry now, for an entry an accepted manifest asks for | an act of the bus module's process alone, answered on no subject |
| `apply` | applies a difference that only grows: a larger cap, a longer age | the same |
| `recreate` | rebuilds an entry whose settings differ in a way that cannot grow, from its data where the storage type allows | the same, on the operator's warrant, which the process verifies itself |
| `drop` | removes one orphan | the same, on the operator's warrant, which the process verifies itself |
`create`, `apply`, `recreate` and `drop` are granted to the bus module's own credential alone, so a module calling
them is refused by the bus. A person asks for them through the bus module's tools, and `recreate` and `drop` act
only on the operator's warrant (ADR 0259 §6), asked through the operator channel. Before `recreate` or `drop` acts,
the bus module takes a stream snapshot of the entry. A drifted entry is said, never quietly fixed: only a difference
that grows is applied without a person.
`create`, `apply`, `recreate` and `drop` stay in the seat's definition as acts its holder's process alone performs,
answered on no subject (ADR 0626 §4, ADR 0436 §3): they are not verbs whose subjects a credential is granted, but
acts on the bus's own create, update and delete subjects, which only the process's account holds, so no module can
ask the bus for them. A person asks for them through the bus module's tools, which hand the request to the process
through its own state (below); `recreate` and `drop` act only on the operator's warrant (ADR 0259 §6), asked
through the operator channel. Before `recreate` or `drop` acts, the process takes a stream snapshot of the entry
(ADR 0595 §5), and it acts only once the snapshot is whole. A drifted entry is said, never quietly fixed: only a
difference that grows is applied without a person.
**Events**: `created`, `refused` (with why), `drifted` and `drift-cleared`, `full` and `full-cleared`, `orphaned`
(cleared by a `drop`, or by a manifest asking for the entry again, which emits `created` for it), `recreated` and
`dropped` (ADR 0595 §6, as its progressive insight of 2026-11-03 has it, waiting for the operator's Approve);
each carries the module, the local name, the bus name, the template, and the settings asked against those held. The
bus module's own kept data stays on the old sections (ADR 0595 §10), because it cannot wait for its own process to
create it: it declares this stream in its `streams` section, kept 30 days (ADR 0363's bound), created by the grants
part as today, with a cap of 256 MiB; it drops its oldest when full, which loses no live state, because every drift,
orphan and fill stands as a condition until it clears. Thirty days, because a drift or an orphan is read back days later by a person; the conditions hold the
live state. The tool `history` of one entry reads them back: every event the bus module said of it, in order. This
settles where they are kept, which ADR 0595 §12 left to the design.
each carries the module, the local name, the bus name, the template, and the settings asked against those held.
**They follow every seat's events**: each is said on `mesh.seat.mesh-broker.event.<event>`, on the shared stream
`EVENTS` (§ 3), kept 7 days, and heard through `consumes` `mesh-broker.<event>` like any seat's event. **The bus
module keeps their history apart**, because a drift or an orphan is read back days later by a person: a stream of
its own in its old `streams` section, on its module subjects, kept 30 days (ADR 0363's bound), created by the grants
part as today, with a cap of 256 MiB, to which the process appends every event it says. Its own kept data stays on
the old sections (ADR 0595 §10), because it cannot wait for its own process to create it. That stream drops its
oldest when full, which loses no live state, because every drift, orphan and fill stands as a condition until it
clears; the conditions hold the live state. The tool `history` of one entry reads it back: every event the bus
module said of the entry, in order. This settles where they are kept, which ADR 0595 §12 left to the design, and
needs no new manifest form: a module's stream never takes a seat's subjects, and every seat keeps one form for its
events.
**Fill is the bus module's one periodic read** (ADR 0595 §6): every minute, for every entry that refuses when full,
because the bus says nothing as a store fills. The condition `full` is raised at a raise mark and cleared below a
@@ -890,15 +913,21 @@ clear mark), `drifted` (cleared by `drift-cleared`), `orphaned` (cleared by a
**Its tools** (tools-are-how-a-module-is-spoken-to): the four reading verbs, marked reads, answer every entry the
bus module created and its fill, and `history` its events for one entry; `create` and `apply`, marked acts, and
`recreate` and `drop`, marked dangerous and so granted only by name (ADR 0386 §6, ADR 0387), are its tools for a
person. Such a tool, in the bus module's bundle, holds no grant of those verbs' subjects, and neither does the tool
runner's account: it hands the request to the process on the process's own tool subject. The caller travels as the
token the identity seat signs (ADR 0386 §8), whose signature the process checks, so no account granted that subject
can name another caller. **Until that token exists** (design 58 builds the identity seat), the process's tool subject
may be published on by tool runners' accounts alone, and the process trusts the caller the tool runner proved and
stamped (ADR 0386 §7), never a name in the request's body; `recreate` and `drop` act only on the operator's warrant,
which is the guard that holds either way. The process acts only for a caller whose role grants that tool, for
`recreate` and `drop` only once the operator's warrant is held, records each as a hand act (`mesh-hand-acts`), and
answers what it did. **The mesh deletes kept data only through `drop` and `recreate`** (ADR 0595 §4, as its
person. **A person's request reaches the process through the process's own state** (ADR 0626 §4), because a process
account answers no tool call (ADR 0436 §3). Such a tool, in the bus module's bundle, holds no grant of the bus's
create, update or delete subjects, and neither does the tool runner's account: it writes the request into the bus
module's state `requests` (an old `state` section, as `asked` is, ADR 0595 §10), stamped with the caller the tool
runner proved and recorded (ADR 0386 §8), and reads the process's answer back from the same key. The stamp names
who asked, for the record; it is no boundary, because every session on a machine reaches the bus as the tool
runner's account (ADR 0436 §9). **So the process verifies the operator's warrant itself**: for `recreate` and `drop`
it trusts nothing in the request, reads the operator channel's record of the ask under its own account and checks
that the warrant binds exactly this act on this entry (ADR 0259 §6), as the mail sender does (ADR 0436 §9); a request
without a valid warrant it refuses, deleting nothing and writing why into its answer; with one, it takes the entry's
stream snapshot first. `create` and `apply` need no warrant, since they only make or grow what an accepted manifest
asks for, and the process refuses either for an entry no accepted manifest asks for. A tool acts only for a caller
whose role grants it; the process records each act as a hand act (`mesh-hand-acts`) and answers what it did. What
stands between the tool runner's account and the process's delete power is that check of the warrant, so its tests
are this section's central check (§ 12.7). **The mesh deletes kept data only through `drop` and `recreate`** (ADR 0595 §4, as its
progressive insight of 2026-11-03 has it): the bus module's older remove tools (its stream, bucket and consumer
removals, ADR 0564) refuse an entry of the new form, naming `drop`'s tool, and keep working for the old sections. The bus seat's `apply` (a difference that grows) and the
ledger's `apply` (§ 12.4) are two verbs on two subjects, granted apart; this design writes them qualified. Its health
@@ -1010,7 +1039,7 @@ issue 1966.
|---|---|
| A manifest's bus state is valid, once | the judge's unit tests, each refusal naming the field: an unknown template, an option outside its bound, past values 0, "when full" given, a fixed setting given, a name used twice across storage types, two modules' bus names alike, a `reads` in the new form, an effect outside the fixed set (ADR 0595 §8, ADR 0596 §2, ADR 0597 §2) |
| The bus module creates, and the binding follows | live, by tool call: a module asking for a state, a log, objects and a ledger in `requires` receives each binding in its membership, written after `created`, never before; `show` gives each entry's template, settings and fill; a module calling `create` is refused |
| The bus module runs whole | one integration test in the nats module's repository that starts the bus module whole against the real bus server: a verdict, then `created`, then the binding in the membership; a restart that catches up a verdict given while it was down; a bucket whose settings differ raises `drifted`, the seat's `apply` of a larger cap clears it with `drift-cleared`; a refused create raises its condition and hands no binding; `recreate` and `drop` without the operator's warrant are refused, and with it act after a stream snapshot; an orphan is listed, raises `orphaned`, and goes only by `drop`; each template at a small cap refuses, events drop the oldest, and `full` is raised at the raise mark and cleared only below the clear mark; `recreated` rewrites the binding and `dropped` removes it; at start the first view from `indexer_bus_state` creates what a verdict given while it was down asked; the older remove tools refuse a new-form entry, naming `drop`'s tool |
| The bus module runs whole | one integration test in the nats module's repository that starts the bus module whole against the real bus server: a verdict, then `created`, then the binding in the membership; a restart that catches up a verdict given while it was down; a bucket whose settings differ raises `drifted`, the seat's `apply` of a larger cap clears it with `drift-cleared`; a refused create raises its condition and hands no binding; the process connects on its own process account; a `create` handed through `requests` is answered on the same key; `recreate` and `drop` without the operator's warrant are refused, and a warranted `drop` takes the entry's stream snapshot before it deletes; each event said is on `mesh.seat.mesh-broker.event.<event>` and appended to the bus module's history stream, and `history` reads it back; an orphan is listed, raises `orphaned`, and goes only by `drop`; each template at a small cap refuses, events drop the oldest, and `full` is raised at the raise mark and cleared only below the clear mark; `recreated` rewrites the binding and `dropped` removes it; at start the first view from `indexer_bus_state` creates what a verdict given while it was down asked; the older remove tools refuse a new-form entry, naming `drop`'s tool |
| A module asking bus state waits for the bus module | the module graph's table test: a manifest with a ledger entry has a requirement edge to the module providing `bus-state`, one without has none (ADR 0614 §5) |
| A foundation part's first view | unit tests of each owner and reader (ADR 0615's How it is checked), as table cases, and these cases of the whole-module integration tests that exist today (mesh-delivery is over its integration budget, so no new test function): the indexer's (`modules/mesh-delivery-indexer`, its one whole-module test, which the milestone's packages test merges into), the assigner's (`modules/mesh-delivery-assigner`) and the grants part's (`modules/mesh-grants`), and the tool runner's in mesh-tools: the owner answers its verb at once from what it holds, with its revision, before its own first view; the reader asks once at start, then only on a gap in revisions; a reader whose owner is down raises its condition only past the bound and never reads the owner's state, and the owner's answer clears it; an empty answer at revision 0 drops no login; an owner's event carries the changed value whole, and a reader applies a put and a delete from the events alone and never asks the verb; a revision lower than the one held makes the reader ask its first view again; an existing waiter on `manifest-accepted` or on the assigner's `put` does not wake on the new families; for the indexer's `verdicts` (ADR 0622), called by the grants part while the node's tool runner is stopped, it answers, and from any other account, the indexer's own included, it is refused; a missed revision on `manifest-refused` makes the grants part ask `verdicts` once more; the grants part and the indexer started at the same moment, `verdicts` answers within the bound with its revision; with the indexer down past the bound the grants part raises the condition naming the indexer and `verdicts` and never reads the indexer's state, and the answer clears it; the read tool shows the revision each reader holds, and the re-read tool asks once and records the hand act; in the
| The owners' first views are their own tools, in a runtime of their own (ADR 0621) | cases of the indexer's and the assigner's whole-module integration tests: each first-view tool, called from a reader's account while the node's tool runner is stopped, answers (§1); each answers its granted readers and refuses every other account, the owner's own included (§2); the two runtimes started at the same moment, each asking the other's first view at start, both answer within the first-view bound with their revisions (§3); and the milestone's group passes its merge check with no change to the judge's known fields for these verbs (§4) |
@@ -1019,10 +1048,11 @@ module, and the indexer, the grants part and the tool runner each get their firs
| A foundation part's first view comes within its bound | live, after the delivery: each reader's read tool (`grants_first_views`, the mesh MCP server's `mesh_first_views`, `indexer_first_views`, `assigner_first_views`) shows, for the indexer's and the assigner's verbs, the time from its ask to the owner's answer under the two-minute bound, and no first-view condition raised by the delivery |
| The bus module's first view | cases in the nats module's one integration test: a replayed verdict older than the first view is not applied; an `indexer_bus_state` that does not answer turns the health unhealthy naming it and is asked again on the backoff; a set-aside manifest missing from the first view keeps its `asked` key, an empty `manifest-accepted` removes it; a deleted module's entry, after its empty `manifest-accepted`, is listed by `orphans` and raises `orphaned`, and a set-aside module's entry is neither; `nats_first_view_again` asks at once and records the hand act |
| `manifest-accepted` is never lost silently | unit tests of the indexer: a failed publish is published again, and one still failing writes the finding; `indexer_say_accepted` says it again for one module from the verdict held, and refuses a module with no accepted verdict |
| Until the identity seat, the caller is the one the tool runner proved | a unit test of the bus module's process: a request on its tool subject naming another caller in its body acts for the proved caller; `drop` without the warrant is refused |
| A person's request goes through `requests`, and the process verifies the warrant itself (ADR 0626 §4) | the process's unit tests: a `recreate` and a `drop` written to `requests` with no warrant, with a warrant for another act or entry, and with a warrant the operator channel's record does not hold are each refused, delete nothing and say why; a `create` or the seat's `apply` for an entry no accepted manifest asks for is refused; the stamp is the caller the tool runner proved, whatever the request's body names |
| The process's account, and the bus module's only bus declaration (ADR 0626 §1 to §3) | the judge's unit test: the bus module's manifest with its process's `bus` and `keeps` is accepted; `keeps` on any other process or module, any other bus declaration of the bus module, and a subject of its process on which a tool is answered are refused; the composition test: the process is granted the create, update, delete and snapshot subjects under modules' names, nothing on which a tool or a verb is answered, and no subscription to a restricted stream's subjects beyond the snapshot request, its acknowledgements and its inbox; the snapshot account is granted the same subjects as before; no tool runner and no tool of the bus module holds the bus's create, update or delete subjects |
| Drift and orphans, live | live, made only by a manifest change: a manifest that shrinks a setting raises `drifted`; the conditions clear as above. Nothing is filled on the live bus, and no orphan is made there |
| Overdue and stopped are loud | live, carried by the change of the first module that moves in step 5, never by a merge made for the test alone: with the bus module's process stopped, an accepted manifest asking for an entry raises the overdue condition within five minutes, from the watchman, and a later `created` clears it; the bus module's health turns unhealthy when its pass is more than three minutes old |
| A person's tools reach the process, and only by role | live: a role without the dangerous grant is refused `drop`'s tool; the tool runner's account holds no grant of `create`, the seat's `apply`, `recreate` or `drop` |
| A person's tools reach the process, and only by role | live: a role without the dangerous grant is refused `drop`'s tool; the tool runner's account holds no grant of the bus's create, update or delete subjects |
| The author is the proven caller | the ledger's integration test: an `apply` naming another module's tool call is refused; the author stamped is the caller the tool runner proved, whatever the module passed |
| Only the owner reaches its data | live: another module's account reading an entry in the new form, a ledger's history, snapshot or state among them, is refused; a raw publish on a ledger's history is refused |
| The ledger keeps its promises | one integration test against the real bus (ADR 0597's How it is checked): two writers race and one is refused; two interleaved applies leave the state at the higher sequence; a write cut between history and state is repaired; a full state bucket answers taken with its sequence and catches up; an idle instance whose operations expired rebuilds from its snapshot; `rebuild`, `reindex` and `lag` repair by hand; a forged author is refused; every `apply` leaves the snapshot equal to the state; an index behind raises its condition and `reindex` clears it |
@@ -1057,6 +1087,12 @@ ruled on every finding. What was found, and what answers it:
| upgrade | the build order lacked the grants part's binding and two undo steps | design 25 § 12.6 |
| tools | the ledger's repairs had no tool for the next owner; the bus module's events had no read tool | design 25 § 12.5 (served for every ledger owner), § 12.3 |
**Answered since, 2026-11-04** (ADR 0626, and the registry milestone's ruling on where the seat's events go): the
process's own tool subject of the security and seams rows is gone, since a process account answers no tool call; a
person's request travels through the process's state `requests` and the process verifies the warrant itself
(§ 12.3); the process holds a process account of its own beside the snapshot account (§ 12.2); and the seat's
events are on the shared stream like every seat's, with the bus module's 30-day history its own stream (§ 12.3).
**Answered since**: the margin of `full` and the events of `drop` and `recreate` were the operator's answers of
2026-11-03 and are now ADR 0595 §6's progressive insight, with the correction of fact for ADR 0595 §4 (the bus
module deletes through `recreate` as well as `drop`); both wait for the operator's Approve and are written in § 12.2
+106 -18
View File
@@ -17,6 +17,8 @@ code:
- mesh-controller internal/inventory/migrations/0064-the-resolver-file-is-the-uplinks.sql
updated: 2026-11-04
decisions:
- "ADR 0625"
- "ADR 0627"
- "ADR 0608"
- "ADR 0613"
- "ADR 0620"
@@ -176,12 +178,13 @@ merges.
## A seat's definition (from 2026-11-03)
**A seat is defined once, in one language-neutral file, and every part learns it from the bus** (ADR 0608, from
research 081). The registry seats (design 51), `mesh-broker` (design 25 § 12.3) and the four seats the milestone
adds verbs or events to are the first defined whole this way, in the milestone of ADR 0612 (ADR 0613 §1,
ADR 0620).
research 081). The registry seats (design 51), `mesh-broker` (design 25 § 12.3), the four seats the milestone
adds verbs or events to, and `node-engine` are the first ten defined whole this way, in the milestone of ADR 0612
(ADR 0613 §1, ADR 0620, ADR 0627 §1).
- **The file** is a schema with conformance fixtures: the seat's verbs and their messages, its events and their
bodies, its state and the forms of its provisions. It lives in the contracts module of its area. Its Go and
bodies, its state and the forms of its provisions. It lives in the contracts module of its domain (*Where a seat's
code goes*, below). Its Go and
TypeScript types are generated from it and committed beside it; nobody writes them by hand. The format is JSON, its
messages and bodies JSON Schema, as the seat set's verb inputs already are, with the format's own schema checked in;
the fixtures are data, never functions.
@@ -212,6 +215,9 @@ ADR 0620).
`ask`, `cancel`, `condition` and `decided`; and `records` `asks`, as the holder's seat entry has them. The
holder's own, beside it: `refused`, and `offered` and `closed`, new, on its restricted stream (design 55 § 11).
mesh-sdk's seat list holds no entry for it today, so its definition is written from the holder's seat entry.
- `node-engine` (held by the node-engine on every node): the verb `manifest-reads` and its seat event
`manifest-reads-changed`, which the milestone gives it (ADR 0618 §3, §4; design 51), so it is defined whole too
(ADR 0627 §1).
**How it is checked**: each of these definitions' conformance fixtures names every event's subject, the seat's and
the holder's own, and a case of the holder's whole-module test takes a fixture from the running holder (an event
@@ -222,10 +228,11 @@ ADR 0620).
at once (ADR 0608 §2), holding the seat list's grain: its name, whether it is held once or on every node, its verbs
with their inputs and its provision, generated from the seat list mesh-sdk compiles today, so the move changes
nothing a reader sees (ADR 0613 §2). Its messages, events and state layouts are added to
a seat's definition when its area's contract next changes, which moves that area's seats whole into its contracts
module in that change (ADR 0613 §3); which area moves when is tracked by issue 167 (ADR 0613 §4).
a seat's definition when its domain's contract next changes, which moves that domain's seats whole into its contracts
module in that change (ADR 0613 §3); which domain moves when is tracked by issue 167 (ADR 0613 §4).
- **The seat set has one source.** The judge, the node-engine, the tool runner and claude-code each compile a copy of
the seat list today; all four import the set generated in `mesh-contracts` instead. The tool runner's descriptions
the seat list today; all four import the seat-set package generated in `mesh-contracts` instead, which is where
mesh-sdk's seat list moves (ADR 0625 §2), and mesh-sdk's `catalogue` reads the seat set from there. The tool runner's descriptions
and claude-code keep that compiled set, equal to the trunk's definition, in this milestone, so neither depends on
the indexer at its start; they move to `indexer_seat_definition` and its event when their next change moves them,
tracked on issue 1966.
@@ -256,15 +263,16 @@ ADR 0620).
`generated-types-out-of-step`, cleared only by a clean build end of the same contracts module. **Tools** of the indexer: `indexer_seat_definition`
(read one), `indexer_seat_definitions_again` (read a trunk's or a pull request's again now) and `indexer_out_of_step`
(the generated types out of step).
- **Contracts modules.** A seat's contract is published by a contracts module, which holds contracts only (every file
generated from a seat definition) and no seat; the seat's holder implements it. **The contracts marker**: a contracts
- **Contracts modules.** A seat's contract is published by a contracts module, which holds the seats' contracts and
their client packages and no seat (ADR 0625 §4, §5); the seat's holder implements the contract. **The contracts marker**: a contracts
module's package artifact names the directory of its definitions in the field `generated-from`, and the judge
refuses a module carrying it that claims a seat, naming the seat. `mesh-contracts` declares two packages, Go and
TypeScript, in package series `0.1`, published through the two package seats (design 51) and taken by its users by
version, or inside one delivery group by the group's head. No `mesh-<area>-contracts` is created in this milestone:
an area's contracts module is created by the change that next moves its area. mesh-sdk keeps its name and the
shared runtime, and takes no new seat-specific type (ADR 0613 §5): a unit test of mesh-sdk refuses an exported
identifier or string constant naming a seat the definitions define. The two checks every change already runs, the
refuses a module carrying it that claims a seat, naming the seat. `mesh-contracts` declares its packages in Go and
TypeScript, cut per seat as *Where a seat's code goes* says, in package series `0.1`, published through the two
package seats (design 51) and taken by its users by version, or inside one delivery group by the group's head. No
`mesh-<domain>-contracts` is created in this milestone: a domain's contracts module is created by the change that
next moves its domain (ADR 0625 §6). mesh-sdk keeps its name and the shared runtime, and takes no new seat-specific
type (ADR 0613 §5): a unit test of mesh-sdk refuses an exported identifier or string constant naming a seat the
definitions define. The two checks every change already runs, the
build modules' compare step and that test, are where a stray file and a stray type are refused; mesh-catalog's own
checks cannot see another repository.
- **A contracts cycle holds nothing.** `mesh-contracts` is published through the forge module's package seats and
@@ -277,6 +285,84 @@ ADR 0620).
like any package; a later holder of the seat may publish its own the same way. A seat's definition stays
vendor-neutral, which the seams review checks.
### Where a seat's code goes
*Added 2026-11-04* (ADR 0625, ADR 0627; the operator, 2026-11-04: "many small sdk's instead of 1 large sdk"). A
module is rebuilt only for the seats it uses, so a seat's code is cut per seat, in the contracts module of its
domain; mesh-sdk keeps what every module shares.
```
contracts module (mesh-contracts, or mesh-<domain>-contracts)
├── definitions and fixtures written by hand, the generation's source, outside the published packages
├── one package per seat defined whole, per language generated: types, subjects, a typed call per verb
│ └── its client package (where callers share logic over the seat) written by hand
└── the seat-set package generated: every seat not yet defined whole, at the seat list's grain
mesh-sdk the runtime every module uses, and seat-neutral parts that several seats' clients or holders share
imports of a contracts module: only `catalogue`'s, of the seat-set package
```
- **Each seat defined whole has a package of its own, per language** (ADR 0625 §1, ADR 0627 §1): its generated
contract, and a module imports only the packages of the seats it uses, so a change of that seat rebuilds only its
users. Where the fingerprint counts a language's module rather than its package, each such package is a module of
its own in the same repository. In the milestone of ADR 0612 these are the ten seats above.
- **Every other seat is in one seat-set package** in `mesh-contracts` (ADR 0625 §2), holding each seat's name, scope,
verbs and provision at the seat list's grain. A change of any of them rebuilds every importer of that package,
mesh-sdk's importers included, until its domain moves and it is defined whole.
- **The imports run one way per package** (ADR 0625 §3): a generated package imports nothing of mesh-sdk; mesh-sdk's
only import of a contracts module is `catalogue`'s, of the seat-set package; a client imports its own seat's
contract and mesh-sdk's runtime. Where a language's module is the unit of import, the clients are a module of
their own in the repository, so the two never form a cycle.
- **A client package** (ADR 0625 §4) is the one hand-written package a seat may carry beside its contract, owned by
the seat's contracts module, never by a holder. It holds the logic two or more callers would otherwise each write
over that seat, and only where such logic exists; it uses only its own seat's contract and mesh-sdk's runtime,
never another seat's client, and never names a holder, a module's tool or a module's subject. A seat's types and
typed calls are its contract's, never its client's.
- **Seven clients come in the milestone of ADR 0612** (ADR 0627 §1), for the seats whose shared logic mesh-sdk holds
today, each moved out of mesh-sdk with every importer in the same group, mesh-sdk keeping no copy and no alias:
`operator-channel` (an ask and its awaited answer, mesh-sdk's `asks` today); `mesh-vault` (the calls its callers
share; mesh-sdk's hand-written vault types are replaced by the vault contract's, not moved into the client);
`node-engine` (the checks of its compose-candidate ask and answer); and `npm-package-registry`,
`go-package-registry`, `container-image-registry` and `oci-artifact-registry` (publishing a file in parts, one
client per seat, each binding mesh-sdk's seat-neutral parts transfer to its own seat's verbs and types).
- **Moving a file in parts stays seat-neutral in mesh-sdk, on both sides** (ADR 0627 §2): the sending side and the
going on from what a holder already holds, and the holder's side (taking the parts into the holder's own objects,
checking their hashes, dropping an upload left idle, saying when its objects fill), name no seat, verb or seat's
type and take subjects, shapes and checks from their caller. Each registry seat's client binds the sending side,
and each holder (the distribution module, the forge's two package seats) binds the receiving side to the seat it
holds, so no holder copies another's transfer.
- **In a contracts module's published packages every file outside a client is generated** (ADR 0625 §5): the build
modules' regenerate-and-compare step fails any other hand-written file there, naming it. The definitions and their
fixtures sit outside the published packages and are not judged by that step.
- **The contracts modules follow the glossary's domains** (ADR 0625 §6): a domain's seats move into
`mesh-<domain>-contracts`, named after the domain's heading in the glossary, when that domain's seats move; a seat
of the Core domain, or of a domain with no contracts module yet, is in `mesh-contracts`. The order of the domains
stays issue 167's (ADR 0613 §4).
- **A seat defined outside the mesh's own contracts has a contracts module of its own** (ADR 0625 §7), which may
share a repository with its first holder; its definition, contract and client never live in the holder module, so
another module can hold the seat by importing only the contract, and the holder can be retired while the contract
stays.
- **A role only one module could ever play is no seat** (ADR 0625 §8): it is that module's own tools and events,
reached by the module's name (ADR 0596 §2). The test is whether another module could take the role over, not how
many hold it today, so every seat in force stays a seat, `mesh-broker`, `node-engine` and `route-proxy` included.
- **mesh-sdk takes only the runtime every module uses** (ADR 0625 §9, as ADR 0627 §2 widens it): the bus connection,
the tools bundle's runtime, state and its helpers, and a seat-neutral part two or more seats' clients or holders
share, as long as it names no seat, verb or seat's type. After the milestone it holds no package, type or function
over the seven seats above (ADR 0627 §4); the value layouts of seats not defined whole stay in it until their domain
moves, as ADR 0613 §3 has it.
**How it is checked** (ADR 0625 §11, ADR 0627 §3, both built in the milestone of ADR 0612):
| Rule | Checked by |
|---|---|
| One package per seat defined whole, one seat-set package | a unit test of each generator (the Go and the Node build modules') emitting one package per seat defined whole and one seat-set package; the generator refuses a seat marked whole in the seat set without its own package; the judge refuses a contracts module whose package holds the generated files of two seats defined whole, naming them |
| The imports run one way | a mesh-sdk unit test that no package but `catalogue` imports a contracts module, and `catalogue` only the seat-set package; the generator tests check no generated package imports mesh-sdk |
| mesh-sdk holds no logic over the seven seats | mesh-sdk's package-list test refuses by name `asks`, the vault's types and its shared calls, the compose-candidate checks and any seat-named publish code, and refuses the seven seats' names in mesh-sdk outside `catalogue`, so a copy kept without importing a contract fails too |
| A client uses only its own seat's contract | the catalog check of a client: its own test refuses a client importing another seat's client and one naming a module's tool or subject, and passes the seven clients |
| The parts transfer is seat-neutral | its unit test runs both sides against two different subjects and shapes the caller gives, and the seat-name check holds it seat-neutral; the review refuses a holder that takes parts in without it |
| Only a client is written by hand in a published package | each build module's regenerate-and-compare test fails on a hand-written file outside a client package and passes a contracts module holding its definitions and fixtures |
| A contracts module holds no seat; a role only one module could ever play has none | the judge's refusal of a contracts module that claims a seat; review both ways: a new seat definition's pull request is asked whether another module could take the role over, and a module's pull request is asked the same of each new tool or event family other modules call |
Acceptance tests: research 081's 14, 21, 25 and 26; a unit test that the generated seat set equals the seat list
mesh-sdk compiled before the move, entry for entry; mesh-sdk's seat-naming test; each build module's compare step
failing on a differing, a missing and an unwritten file, naming each; the checker's `verdict` naming out-of-step
@@ -478,6 +564,8 @@ and 32 by the four reviewers by architectural domain; the findings and what answ
indexer learns out-of-step types from the check's verdict event and runs no generator (seams), findings go to the
condition keeper (health), a pull request's entries are removed when it closes (running qualities).
The milestone's amendment (ADR 0612, ADR 0613, ADR 0614: nine seats defined whole, the rest at the seat list's grain,
the contracts marker, out of step learned from the checker's `verdict` and the builder's build end, the seat set's one
source) awaits its own review by architectural domain, which rewrites this section.
The milestone's amendment (ADR 0612, ADR 0613, ADR 0614, ADR 0620: the seats defined whole, the rest at the seat
list's grain, the contracts marker, out of step learned from the checker's `verdict` and the builder's build end, the
seat set's one source), with the amendment of 2026-11-04 (ADR 0625, ADR 0627: ten seats defined whole, a package per
seat, the seat-set package in `mesh-contracts`, the seven clients and the seat-neutral parts transfer, *Where a
seat's code goes*), awaits its own review by architectural domain, which rewrites this section.