Compare commits

...
Author SHA1 Message Date
jschoubben e27fd02269 Number a module's version before its build, as the operator chose, so packed files carry it
A Go module zip and a TypeScript package hold their version inside the file, so a number given at publication
could not be valid for a digest built before it (gaps items 22, 23, 43). The operator chose on 2026-11-10: the
manifest says MAJOR.MINOR, the build system reserves the next patch at the build's start, the catalog holds and
says released versions only, the first watched branch alone releases, and Go packages are tagged, departing from
ADR 0573 §2 until a later research brings the record in line.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-11 02:06:46 +01:00
jschoubben 63eeb96ebd Answer round 1 of the review of milestone G's part, and split the part so each file is read whole
The four reviewers by architectural domain found retentions judged from another part's records, unbounded aging,
waits and stores no condition names, a kept artifact checked against the builder's key, and caller limits left
open; each is now a design line with its reason. The part is six files under 60 KB, one milestone still, with
G.md as its index; the main file stays over its bound on the lead's word.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-11 02:06:46 +01:00
jschoubben da83f29f47 Give milestone G its own part of design 47, and answer its builders' open questions there
G's builders read a 443 KB design by searching it and filled what they did not find; playbook 02's shape gives
each milestone a part read whole. G's lines move whole into 47-milestones/G.md, numbered as design lines, and
the questions G's prepare and develop met within the records are written as the design's own choices
(the operator, 2026-11-10: small design choices are the design's, only architectural ones are asked).
The size bounds are bent for this split on the lead's word; research 087 takes them up.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-11 02:06:46 +01:00
mesh-tools 000a35d5cf Merge pull request 'Design 47: the watchman's take-in seed ends waits the indexer no longer holds (issue 1966)' (#538) from design/47-seed-ends-stale-waits into main 2026-11-10 22:45:34 +00:00
jschoubben b58d789e83 Design 47: the watchman's take-in seed ends waits the indexer no longer holds
mesh/delivery merged: source.main moved to novox/hq@000a35d5cfce
mesh/check checking b58d789e83d0 on 000a35d5cfce
The operator's answer to the design question of issue 1966 note 195: a take-in
wait whose taken event was never heard stood for ever; the indexer's pending
state is what waits. Also says the indexer's taken event covers every key its
pending tool named.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-10 23:44:03 +01:00
mesh-tools e65d0f8f2b Merge pull request 'Build features from the design alone and ask the operator what it leaves open' (#537) from process/implement-the-design into main 2026-11-10 16:51:25 +00:00
jschoubben cdfed7593e Keep the check step's no-second-review sentence whole
mesh/delivery merged: source.main moved to novox/hq@e65d0f8f2bbd
mesh/check being carried to cdfed7593e73 on e65d0f8f2bbd | from b229f5c4df1e
Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 17:24:12 +01:00
jschoubben 6e90fa443e Compare seat contracts with the design in the prepare, and call a verdictless merge unchecked
On 2026-11-10 a seat contract and an event's subject that differed from design 47
surfaced only in develop, and the checker twice dropped a check still running when
its pull request merged. The prepare now compares every seat contract the milestone
touches with its design lines, each difference a design question before develop;
and a merged change with no verdict is reported as unchecked, never as passed.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 17:24:02 +01:00
jschoubben 8f9a6d4f7b Build features from the design alone and ask the operator what it leaves open
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 8f9a6d4f7bc9 on b229f5c4df1e
Milestone 47/G was prepared and developed from a 430 KB design by agents told to
start from the knowledge base and judge what was not mesh-shaped. The prepare wrote
its own findings and about 40 rulings by two leads, seven of which went against the
records or the design, and 29 questions the design never answered surfaced only in
develop.

The playbooks now make the milestone's part of its design the only input to the
prepare, develop and the code review: the prepare outputs a build map per
repository and the design questions; the operator answers each and the answer is
written into the design before develop starts; every commit cites the design lines
it builds and the review judges it against them. A design is a main file and one
part per milestone, within a size an agent reads whole. Also: one lead per
milestone, a contract's users start from its commit, one writer per file, one
sibling placement, and agents stop between subtasks, never inside one.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 17:21:06 +01:00
mesh-tools b229f5c4df Merge pull request 'Take back three design 47 choices that broke accepted decisions (issue 1966)' (#536) from design/47-G-undo into main 2026-11-10 15:52:22 +00:00
jschoubben ebf115303a Undo three of design 47's milestone G choices that went against accepted decisions
mesh/delivery merged: source.main moved to novox/hq@b229f5c4df1e
mesh/check checking ebf115303a87 on b229f5c4df1e
The joint amendment wrote three choices that the records already decide
otherwise. The foundation parts are again the manifest validator's list, the
runner added (ADR 0666 §4), with no registration value and no finding of their
own. The runner again starts a group's pipeline on the indexer's take-in and
consumes package-published (ADR 0666 §13, §15); a second start for the same
revision and module writes nothing by the pipeline key's compare-and-set. A
replaced object stays, like a key-gone one, until the drop tool on a person's
word (ADR 0595 §4). Design 51 and the glossary follow.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 16:50:38 +01:00
mesh-tools 3d97fe016c Merge pull request 'Amend design 47 with milestone 47/G's joint findings as its own choices (issue 1966)' (#535) from design/47-G-joint into main 2026-11-10 15:33:22 +00:00
jschoubben b33ac325c0 Amend design 47 with milestone 47/G's joint findings as its own choices
mesh/delivery merged: source.main moved to novox/hq@3d97fe016c2d
mesh/check being carried to b33ac325c0ec on 3d97fe016c2d | from d0d71b554876
The prepare found where ADR 0666, ADR 0667 and design 47 disagreed. The
ADR 0666 insight was dropped, so its five points are written here as the
design's choices with their reasons: the foundation from the registrations
(departing from ADR 0619 §3 for ADR 0666 §5), the want's compare-and-set per
module and watched branch, every pipeline started on catalog-revision, the
cost of a refused new indexer, and each check at its row's level. ADR 0667's
clause numbers follow the record as accepted, so the merge token goes only at
§12's moment and on the operator's word. The approval is the operator-channel's
accepted kind, a replace removes its object, the sent store's age is
transport, and what the milestone creates has its retention. The glossary
gains "held back" and "sent store"; design 51 starts a publication's
pipelines on catalog-revision.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 16:13:45 +01:00
mesh-tools d0d71b5548 Merge pull request 'Close a research effort with the knowledge base's close verb (issue 1966)' (#534) from fix/1966-close-verb into main 2026-11-10 09:58:42 +00:00
jschoubben c814bf2e0f Close a research effort with the close verb, so only the closing is judged
mesh/delivery merged: source.main moved to novox/hq@d0d71b554876
mesh/check checking c814bf2e0f18 on d0d71b554876
Proposing a graduated effort again whole had the knowledge base re-judge its approved reasoning
against the decisions that replace it (issue 1966).

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 10:57:23 +01:00
mesh-tools 2ba88971cf Merge pull request 'Glossary: transport fault and kept call; developers run the touched packages' integration tests once per head and use the live seat list (issue 1966, ADR 0668)' (#533) from agents/1966-lessons into main 2026-11-10 07:33:26 +00:00
mesh-tools 38915bbe01 Merge pull request 'Amend designs 47, 46 and 51 for pipelines per module and milestone G as one milestone (ADR 0666, ADR 0667)' (#532) from design/086-pipelines into main 2026-11-10 07:20:44 +00:00
jschoubben 78ef41e7bd Make playbooks 07 and 08 agree on the developer's integration run, and bound it
mesh/delivery merged: source.main moved to novox/hq@2ba88971cf52
mesh/check checking 78ef41e7bdb7 on 2ba88971cf52
The first amendment left the step table, the review's reading of integration
tests, step 3 and playbook 08 saying the opposite. The run is now once per head
reported, the touched packages and their importers in the module, by name where
the importers are many, and never a whole module or level, within the operator's
rule of 2026-10-18. The live seat list is read again when a head is reported.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-10 06:53:26 +01:00
jschoubben 7bbd4a86b4 Name transport faults and kept calls, and make developers check what the review found
Issue 1966's fix group showed two gaps in how a developer checks: an integration
test the change broke went unseen because only the untagged suite ran, and a stale
seat list made the local manifest validator refuse what the running one accepts.
The developer definition and playbook 07's develop step now run the touched
packages' integration tests against an embedded bus, the whole of mesh-sdk, and
the validator against the live seat list and a fresh catalog trunk, and stop at
two thirds of the context with a handover in the prepare file. The glossary gains
transport fault (ADR 0664 §1, ADR 0668 §1) and kept call (ADR 0668).

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-10 06:51:43 +01:00
jschoubben 43eac215d2 Follow ADR 0666's 26 clauses in the designs and the glossary
mesh/delivery merged: source.main moved to novox/hq@38915bbe0174
mesh/check checking 43eac215d264 on 2ba88971cf52
The record was proposed again with clauses 2 and 17 split for the
knowledge base's review, so every citation of it moves to the new numbers.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 03:11:29 +01:00
jschoubben 40661df80f Take in round 3's last two fixes and record the three review rounds
mesh/delivery closed: a newer head of the same pull request
mesh/check pass 40661df80ff4 on 6611b94e3d7a | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | composition passed in 114s on …
Seams and tools and security and upgrade approved with two fixes: only an
operator's or a healer's rerun clears a failed step for merge-pull, and a
fix before the first registrations is merged by the operator under the
trunk-only want. The review section now records all three rounds.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 03:02:39 +01:00
jschoubben 45cc27cf24 Take in round 2 of the review by architectural domain of the 086 amendment
Seams and tools and security and upgrade asked seven items, ruled by
fix-1965 with ADR 0666 and ADR 0667 staged to match: the assigner and
merge-pull switch on the first registrations, a branch that lost its
protection starts nothing, a passing rerun clears a failed step, sent
objects are read by a grant derived from the manifests, and the object
store is a small mesh-sdk package so nothing else rebuilds. The staged
record renumbered its clauses, so every citation of ADR 0666 follows the
new numbers.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 03:00:45 +01:00
jschoubben a8103cf0b1 Take in round 1 of the review by architectural domain of the 086 amendment
The four reviewers asked changes in every domain and fix-1965 ruled on each,
with ADR 0666 and ADR 0667's wording staged to match: foundation parts keep
old sections, merge-pull judges from its own state so a head merges while
the runner is down, a group's wants wait for group-ended, a failed head is
said to its author then the operator, the checker goes only after a first
end-to-end pipeline and a tested backup, and the stores are sized again for
publish rebuilds.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 02:49:51 +01:00
jschoubben bce14ad12e Hold no requirer of bus state for a bus build that waits for a yes
The assigner's provider rule read the phase of the bus module's newer want,
so a yes not yet asked held every module asking bus state (issue 1966,
note 150); milestone G reads what runs. Also name the tracker of the
review-author stopgap.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 02:39:49 +01:00
jschoubben 55ac9f2d8e Name in design 47 the records its pipeline text now follows
Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 02:38:40 +01:00
jschoubben 3de6895e32 Give the glossary research 086's words for pipelines
Research 086's Domains section names the words its graduation adds and
changes; the designs now use them, so the glossary defines them in the
same set: pipeline, pipeline step, policy, registration, watched branch,
run on request, artifact reference, the seats mesh-pipeline-runner and
mesh-builds, the composition step and the build-input fingerprint, with
Homonyms rows for policy and step. The words that leave (merge check, try,
trunk commit, merge turn, composition check) keep their entries until
milestone G's delivery, since they govern it, and move to Not: lines with
the as-is update after it.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 02:38:13 +01:00
jschoubben 2fa15a1c8d Write ADR 0666's asks into design 46 and its versions into design 51
ADR 0666 §6 has the operator-channel offer a fourth ask instead of refusing
it, never holding the newest back; design 46 now says which ask waits and
how it is offered again. ADR 0666 §9 numbers a package when it is
published and has that publication rebuild its dependents; design 51 now
says how the builder numbers it, says it on the seat mesh-builds, and who
asks a tagged version once the checker goes.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 02:36:26 +01:00
jschoubben 471fd8791d Write research 086's pipelines into design 47, one milestone with G
ADR 0666 and ADR 0667 decide that a change goes from a commit on a watched
branch to the machines through its module's pipeline, with no Approve per
merge and the checker gone, built and delivered as one milestone with
design 47's milestone G. The design now says how: registrations, the
catalog graph per watched branch, pipeline steps and their policy, a
session's own merge through merge-pull reading the head's latest run,
edges between artifacts, values of any size, the tools, the runner's kept
data and the build capacity, and the acceptance tests by level and
repository. Every section the pipelines replace keeps governing G's own
delivery and says so; the recovery merge points to its decision.

Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
2026-11-10 02:35:25 +01:00
mesh-tools 6611b94e3d Merge pull request 'Amend design 47 for milestone G: the gate's record, the seat git, the merge on the Approve alone' (#530) from design/47-G-amendment into main 2026-11-09 19:38:46 +00:00
mesh-tools fc6a30070f Merge pull request 'Developers, design writers and preparers can say a commit others wait on as it lands' (#531) from agents/developers-report into main 2026-11-09 19:37:47 +00:00
jschoubben c9abb1c5f9 Test 58 names a part not heard, not a node away: a check still passes a sleeping node with a warning
mesh/delivery merged: source.main moved to novox/hq@6611b94e3d7a
mesh/check checking c9abb1c5f92e on 6611b94e3d7a
The test read as failing every check while a node sleeps, against ADR 0593 §9 and the design's own try section.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-09 20:12:00 +01:00
jschoubben b3484cdcfc Name the indexer's mesh-wide hold among what milestone G retires and a revert restores
mesh/delivery closed: a newer head of the same pull request
mesh/check checking b3484cdcfc50 on 2de011e070d4
The per-node wait is the assigner's, so the indexer's hold states and tools go with its modules state.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-09 20:07:35 +01:00
jschoubben 76b317ed3a Take in round 3's second pass on design 47's G amendment: put-stands timed by the watchman, the put ends by done
A new step would read as a running put to a reverted assigner, the running-before-assigner order is no
edge of the module graph, put-stands needs a writer that survives a stopped assigner, and the tool
runner's revision rests on ADR 0663, now required before the push beside ADR 0661.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-09 20:06:40 +01:00
jschoubben 205992f15c Take in round 3's review of design 47's G amendment: the put's end by step, the readers' order and waits
The reviewers found the put's end written as built when the recovery reads the have, no end for a put of
the running build, nothing said for a put that stands, two of the eight readers outside the served-verb
order, the readers missing the no-view rule and the candidate case, and a revert's restored modules
unsaid. Each is now written as the lead ruled, with rows in tests 61 and 62.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-09 20:02:31 +01:00
jschoubben e73a1a7bcf Take in round 3 of design 47's G review: no module reads the indexer's modules, a put ends itself, ADR 0662 withdrawn
G stops declaring the indexer's modules, so the eight other modules that read it would break unless they
move to the catalog half in the same milestone. A put without hold never ended and pinned its want; ADR
0546 §5 already says it ends once the node runs it, now heard on the node-engine seat's running event.
ADR 0662 decided ADR 0661's switch another way and is withdrawn, so G builds ADR 0661 alone.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-09 19:56:42 +01:00
jschoubben 64cdada15a Developers, design writers and preparers can say a commit others wait on as it lands
mesh/delivery merged: source.main moved to novox/hq@fc6a30070f68
mesh/check being carried to 64cdada15a34 on fc6a30070f68 | from 2de011e070d4
Without SendMessage, milestone G's developers could report only at their end, so a seat definition the
others wait on could not be handed over mid-way.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-09 19:55:31 +01:00
jschoubben 4f388e8452 Take in round 2 of design 47's G review: running kept per subject, the merge waits on the Approve alone, ADR 0661 named
mesh/delivery closed: a newer head of the same pull request
mesh/check pass 4f388e845294 on 2de011e070d4 | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | composition passed in 85s on 4…
Round 2 found the pass's running events could age out of a new consumer's reach, the merge bullet still
holding for a carry, the checker's own owed acts unanswered, findings that never cleared, and
kept-artifact open to any module and caller. Each is now written as the lead ruled, with its test row.

Claude-Session: https://claude.ai/code/session_01NcbgfFfQ4Z9UE5jK32PmE5
2026-11-09 19:21:49 +01:00
jschoubben 2fd96e1e4e Take in round 1 of design 47's G review: hear what nodes run, say what the forge is owed, reach the forge by its seat
The reviewers found a seat's pass waiting on a call to a node that may be away, acts owed to the forge
that could be lost or done twice, a seat git that missed the gate's and half the parts' forge calls and
events, a merge that still judged a check the operator removed, and waits with no bound or condition.
The design now keeps what each node runs from its running events, makes every owed act safe to repeat
with its outcome said and recorded, gives the seat git every call and event with its act verbs granted
by the holder's callers, orders forge, bridge and gate with a way back, adds module-held and
check-could-not-run, numbers tests 56 to 60, and says how the store seat's holder takes its own build.

Claude-Session: https://claude.ai/code/session_01NcbgfFfQ4Z9UE5jK32PmE5
2026-11-09 19:21:49 +01:00
jschoubben 7f2f37d9e6 Amend design 47 for milestone G's prepare, so G is built from what the records hold
The prepare found the design behind its records and the code: Placement retired by ADR 0641 while the
design still put two seats in a contracts module never made, ADR 0659 and ADR 0660 not followed, the
checker and the forge bridge reading the gate's state, the delivery parts naming the forge module's
tools, and four hand-wired seat-list readers. Design 47 now writes each as the design's choice under the
record it follows; the hold and the merge turns are removed by the operator's word with their record
still to come, and a session's recovery merge waits for one. The glossary moves Placement's words into
Core and Delivery and adds the seat mesh-grants; the words test refuses Placement as a domain heading
(ADR 0641 §5); design 26 takes the new contracts homes and the seat git's verbs.

Claude-Session: https://claude.ai/code/session_01NcbgfFfQ4Z9UE5jK32PmE5
2026-11-09 19:21:49 +01:00
mesh-tools 2de011e070 Merge pull request 'Research writes its requirements from the operator's answers before any option' (#529) from docs/research-requirements into main 2026-11-09 16:21:08 +00:00
jschoubben d61bed820f Research writes its requirements from the operator's answers before any option
mesh/delivery merged: source.main moved to novox/hq@2de011e070d4
mesh/check checking d61bed820f8e on 2de011e070d4
The operator, 2026-11-09: a list of requirements shapes the research, so every
option is weighed against requirements the operator has corrected first.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-09 17:19:15 +01:00
mesh-tools 3cf28e840d Merge pull request 'Watcher definition: a report along the way does not end the watch' (#528) from agents/watcher-keeps-watching into main 2026-11-09 08:49:46 +00:00
jschoubben c57930a759 A watcher reports along the way with SendMessage and keeps watching; only the end, a failure, the bound or a twice-failed call ends it
mesh/delivery merged: source.main moved to novox/hq@3cf28e840de3
mesh/check checking c57930a75988 on 3cf28e840de3
On 2026-11-09 four watchers in one session ended at their first five-minute report,
leaving waits unwatched while a check, a take-in and an answer were still to come.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-09 09:31:22 +01:00
mesh-tools e7f090e333 Merge pull request 'Glossary names no seat's holder: who holds a seat is read from the mesh' (#527) from docs/glossary-no-holders into main 2026-11-08 23:21:13 +00:00
jschoubben dea6b197c5 Glossary names no seat's holder: who holds a seat is read from the mesh
mesh/delivery merged: source.main moved to novox/hq@e7f090e33302
Which module holds a seat is a fact of the mesh's assignments, and a copy
in the glossary drifts (the operator, 2026-11-09: "it shouldn't be in the
glossary"). Each entry keeps its definition and drops the holder; the head
says the holder is read with mesh-module-assigner.assignments and seats.
The words test now refuses a seat held or claimed by a named module; it
failed on twenty statements before they were reworded.

Claude-Session: https://claude.ai/code/session_01NcbgfFfQ4Z9UE5jK32PmE5
2026-11-09 00:20:26 +01:00
mesh-tools 1fb7943efd Merge pull request 'Agent definitions: no symbolic links; a review proves a fix against the live mesh (issue 1966)' (#526) from agents/developer-no-symlinks into main 2026-11-08 15:03:27 +00:00
jschoubben e01bf97a17 Reviewer definition: prove a fix against the live mesh, never a re-creation
mesh/delivery merged: source.main moved to novox/hq@1fb7943efdb0
mesh/check failed: ace: not composed on ace: the composer at the node-engine's trunk 875b4ee5ce38d4bb96089ba3b05962b450… | e01bf97a17f9 on 1fb7943efdb0
Twice on 2026-11-08 a review re-created the indexer's manifest validator without
its seat list and passed a fix the live one still refused (issue 1966); the
operator asked for this line in the same change.

Claude-Session: https://claude.ai/code/session_01NcbgfFfQ4Z9UE5jK32PmE5
2026-11-08 01:58:58 +01:00
jschoubben b6b657917e Developer definition: place siblings without symbolic links
mesh/delivery closed: a newer head of the same pull request
mesh/check failed: mesh-build-go: the change's manifests cannot be judged: the seat list is not read (the seat list is … | b6b657917ed6 on aaad9daa69bb
A developer placed a sibling worktree under /var/tmp with a symbolic link
(2026-11-08, issue 1966); the mesh's hard rules allow none anywhere.

Claude-Session: https://claude.ai/code/session_01NcbgfFfQ4Z9UE5jK32PmE5
2026-11-08 00:34:23 +01:00
mesh-tools aaad9daa69 Merge pull request 'Design 47's B0 says its one new seat verb is delivered first, alone (issue 1921)' (#525) from feat/b0-checking-program into main 2026-11-07 00:32:44 +00:00
jschoubben ec71485755 Design 47's B0 says its one new seat verb is delivered first, alone (issue 1921)
mesh/delivery merged: source.main moved to novox/hq@aaad9daa69bb
mesh/delivery-group group feat/b0-checking-program merged: every member is merged
mesh/check being carried to ec714857556d on aaad9daa69bb | from 885099eebbbd, mesh-catalog 980ade933853, mesh-delivery 2d201f781ced, mesh-sdk c1b50e99…
B0's first check failed because the running indexer did not know the checker
seat's verb input and the composition took its verdict over the check's own
validator. The operator chose to deliver that verb alone first (2026-11-07).

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-07 00:53:27 +01:00
mesh-tools 885099eebb Merge pull request 'Design 47's B0 says what was built: the checking program on every check, its input by the checker's verb (issue 1921)' (#524) from docs/47-b0-row into main 2026-11-06 23:01:03 +00:00
jschoubben d676466578 Design 47's B0 says the checker is delivered first and a failed seat list ends the check there (issue 1921, B0 review round 2)
mesh/delivery merged: source.main moved to novox/hq@885099eebbbd
mesh/check being carried to d676466578c4 on 885099eebbbd | from dd55153cf355
Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 23:56:30 +01:00
jschoubben da828c147a Design 47's B0 takes in round 1's rulings: the input asked of the checker's verb, the cycle rule the program's
A build module reading the checker's state broke ADR 0596 §2, and no record names the
cycle rule as an exception to ADR 0656 §5; the code now follows both, and so does the
design, with the answer's bound that the build module now enforces.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 23:51:08 +01:00
jschoubben 35b92fde78 Design 47's B0 says what was built, so the review reads the design the code follows
The first code review round found the B0 section described the input and answer in the
build seat's objects, no running rule after B0, and a carry's program built at merged heads.
It now says the input is kept in the checker's own state and the answer rides the step key,
names the cycle rule and a failed program's wording as the two exceptions until milestone G
with why, and says where a carry's program is built and when a trunk move asks a new build.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 23:23:53 +01:00
jschoubben 60369fddee Design 47's B0 takes the lead's rulings on its open points
The begin bound of a run ask, the referenced objects' size, the kept
programs' tools and their 30-day sweep, and the versioned input were left
open by the first amendment; each is now one of B0's choices with its
reason, as ruled, so the developers and the review read one text.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 22:10:14 +01:00
jschoubben 12489d580c Design 47's B0 names the trunk's homes and runs the checking program on every check
Row B0 named mesh-delivery-contracts for the ask `run`, but the registry group
creates that module and joins milestone G, after B0; on every trunk before G
the seat's types are mesh-sdk's go/delivery and go/composer, which G's merge
moves (ADR 0634 §4, ADR 0635 §4). The bootstrap section now says every check
runs the checking program (a lone pull request a group of one, a carried
verdict included), that the program makes the heads' seat list, and carries
the seams review's three findings on B0's prepare as the design's own choices
with their reasons: a dropped `run` ask fails by name within a bound, kept
programs have tools and a sweep, and the input goes by reference with a size
bound.

The glossary gains "seat list", used as a term by ADR 0635, ADR 0636 and
design 47 without an entry, retiring "seat set" in hq; four designs take the
word, and issue 299's narrative keeps its day's word by an allowance row.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 22:08:31 +01:00
mesh-tools dd55153cf3 Merge pull request 'Design 47 follows ADR 0656 and ADR 0644: the delivery's own parts checked and delivered by their own change (issue 1921)' (#523) from docs/47-two-graphs into main 2026-11-06 20:42:02 +00:00
jschoubben 27d31d5490 Merge remote-tracking branch 'origin/main' into docs/47-two-graphs
mesh/delivery merged: source.main moved to novox/hq@dd55153cf355
mesh/check being carried to 27d31d54908f on dd55153cf355 | from 5ff1298e2173
2026-11-06 21:37:41 +01:00
jschoubben 8a85a2fd54 Design 47 records its review by architectural domain of 2026-11-06
Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 21:37:41 +01:00
jschoubben 49ecfb6cdf Design 47 keeps the catch-up tool in the restore point
At a revert the manifest being applied is the one from before the change,
which names no catch-up tool, so the node agent could not find it there. The
newer build's manifest declares it beside the kept data whose form it changes,
the backup records it in the restore point, and the node agent takes it from
there.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 21:37:09 +01:00
jschoubben 25d9f8df61 Design 47 names the forms milestone G changes and how a revert catches up, read from the code
Round 3 found the revert section left open which kept data G changes, the order
a revert needs, and whether the parts of before can catch up. Read on main, the
indexer catches up from its forge consumer, whose stream keeps only 7 days, so
the restore also runs its existing take-in of every repository; the assigner
keeps nothing to restore and computes the wants again; the gate's start reads
the forge, the pending answers and the source again. The wants keep their form
and are never restored, since that would send nodes to older builds.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 21:35:44 +01:00
jschoubben af6695161c Design 47 writes only the new forms, and reverts by restoring the parts' kept data
The operator looks only forward, yet wants reverts supported. So the indexer,
the assigner and the gate no longer write the old keys, wants source or merges
and turns beside the new forms, and milestone H goes. A revert is delivered like
any change: ADR 0404's backup covers only the items on a module's node, so the
delivery system gains a restore point of a module's kept data on the bus,
taken before a change of its form and restored beside the live data before a
reverted build starts, after which the part catches up forward; a missing
restore point holds the revert and asks the operator.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 21:30:35 +01:00
jschoubben ce3fe6aa3b Design 47 takes in round 2: waits timed from their start, composing held per node by the assigner, stores sized
Round 2 found a wait whose holder stopped could go untimed, a node away holding
others' wants, a new field in the want that an old node-engine cannot read,
stores sized for whole revisions, a full store that never cleared, a ledger
sized without its operations, and a kept build a program could rewrite. The
design now says wait-held at a wait's start with its bound, starts each clock
when the new version's build is done, holds a node's wants in the assigner
until that node's new node-engine runs, stores an unchanged entry once, sizes
the ledger from its operations, clears full on room, keeps only builds from a
run step that runs nothing else, names every change of the checking program's
fingerprint, and makes the switch safe to run twice.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 21:23:25 +01:00
jschoubben de7358a2c5 Design 47 takes in round 1 of the review by architectural domain
The reviewers found the amendment left the stores to grow without a bound,
the waits without an owner's tools or events, a rollback that would send nodes
back to old builds, a newer indexer that could never be wanted, events any
account could forge, and the node-engine reading every node's placements. The
design now chooses, each with its reason: a default record retention and caps
with fill conditions, a revision removed when no record pins it and it is not
current, waits held and released by each step's own part with their events,
the build module's wait ending on the agreed toolchain, the old keys kept
written until a named milestone H for a rollback, the running indexer making
the newer indexer's entry, rule changes named by the running checker from
outside the sandbox, and subjects and grants that let each part say only its
own. The review verb leaves milestone G for issue 1782, and the watcher's
definition goes back to main, since it contradicted an approved instruction.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 21:18:14 +01:00
jschoubben 8d98d54bd2 Design 47 tests each change ADR 0656 makes, and leaves the review verb as ADR 0493 §5 has it
ADR 0656 v6 no longer changes ADR 0493 §5: who may review is another question,
waiting on issue 1782, so the design stops saying the reviewer comes from the
caller's bus account or that the author is refused. Each change ADR 0656 makes
in an earlier record now has its own acceptance test, so the milestone proves
every one of them.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 20:57:46 +01:00
jschoubben dbc047bf56 Design 47 follows ADR 0656 alone and writes its own choices with their reasons
The operator ruled that research 085 graduates into one record per question:
ADR 0656 holds the whole answer and supersedes ADR 0645 to 0648, and the short
records 0649 to 0655, 0657 and 0658 are withdrawn. The design now cites ADR 0656
or ADR 0644 for what they decide, and what they leave is no longer an open
point but this design's choice, listed with its reason, so the review can
judge each one.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 20:56:35 +01:00
mesh-tools 5ff1298e21 Merge pull request 'Playbooks 01 and 02: one record per question an effort answers; design choices live in the design' (#522) from docs/one-record-per-question into main 2026-11-06 19:55:23 +00:00
jschoubben c1cf0149b6 Design writer and hq-graduate follow the new step 2; the playbook names no record by number
mesh/delivery merged: source.main moved to novox/hq@5ff1298e2173
mesh/check being carried to c1cf0149b6d9 on 5ff1298e2173 | from 1ca5a3a1331f
Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 20:52:38 +01:00
jschoubben 5e3b836404 Playbooks 01 and 02: one record per question an effort answers; design choices live in the design
Research 085 graduated into eleven records where it answered two questions:
the rule 'one record per choice that could be reversed on its own' made
every design choice a record of its own.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 20:51:00 +01:00
jschoubben cad2693361 Design 47 carries what research 085's records no longer say, and cites the short records
The operator ruled that a decision record is a question, its options and the
choice made, so research 085's records were cut to their choices: ADR 0656,
0657 and 0658 supersede ADR 0645, 0647 and 0648, and ADR 0652 to 0655 split
ADR 0646. What the long forms carried beyond the choice now lives here as
design text and acceptance tests: the graphs' keeping in the old objects
sections and their retention by the gate's pin and free events, the
candidate's graphs, the step events' fields, the first tier and the sandbox,
the trunk's validator beside the change's own, the waits' holders and tools,
the delivery record's consumer, switch, rollback, node away, small fix and the
Approve held at its heads, the milestone ask and events, and the trace's link
kinds. Each fact cites the record that decides it, or says it is this
design's, so the review can tell the two apart.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 20:33:24 +01:00
jschoubben e99094ab94 Design 47 and the glossary follow ADR 0644 to ADR 0651: two graphs, one revision view (issue 1921)
Research 085 found that each acting part handled a change to itself by a case
of its own, and that parts disagreed on the state they read: 7 of 24 failures
since 2026-11-01. Design 47 now describes the catalog graph and the computed
assignment graph kept per revision, a change delivered as its graph
difference, acting parts' rules on their seats as bounded waits, the check on
the change's own acting parts, the revision view, the gate's delivery record
and the trace's links, with the bootstrap delivery before that milestone.

It also settles what the records leave to this amendment, as proposals for
the review: the acting rule's fields and mesh-sdk cost, the fingerprint
handover, the build seat's ask that runs a program in the sandbox, the first
tier's bound, the step events' subjects, and the tools the seams review
listed. The glossary gains the seven words of research 085's Domains. The
watcher's definition learns that a quiet five minutes is no reason to end,
since its final report is its only channel.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-06 19:41:16 +01:00
mesh-tools 1ca5a3a133 Merge pull request 'Design 47 follows ADR 0633, 0637, 0638 and 0639: the take-in by the indexer it names, and the group try (issues 1966, 1921)' (#521) from docs/47-try-and-take-in into main 2026-11-05 20:06:31 +00:00
jschoubben b926db338d Design 47 cites ADR 0639 §9 for the hand drop, so both hand acts are said to clear take-in-waits
mesh/delivery merged: source.main moved to novox/hq@1ca5a3a1331f
mesh/check being carried to b926db338dcf on 1ca5a3a1331f | from 674f88f9abb8
ADR 0639 v9 gives the drop its own clause and moves the checks to clause 10.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-05 20:26:55 +01:00
jschoubben d61e18de41 Design 47 cites ADR 0639 for the review's rulings, and fixes the indexer's build at its start
The rulings of round 1 now rest on a record, clause by clause, instead of on the
review; the indexer's own build is set once from the build it was started with, so a
process being replaced cannot take in with its old manifest validator (ADR 0639 §7).

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-05 18:46:11 +01:00
jschoubben 8b923e6bff Design 47 takes in round 1 of the review by architectural domain
The try and the take-in described seams, failure paths, live cases and the health
chain less exactly than the release builds them: the reads that stay until issue
1966, the bus form of pending and the tryevent contract, the try's tools against the
four lines, a checker_tries that does not answer, try events never lost, what a
narrowed try keeps, the finding and the condition keeper, and both live cases. Rulings
no record decides are marked as the review's.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-05 18:38:05 +01:00
jschoubben 26b6dcf4f6 Design 47 cites ADR 0638 and its recovery order, so a try's candidate survives an indexer restart
ADR 0638 makes the candidate from the checker's events and decides that the indexer
creates its consumer, asks checker_tries and fixes the candidates before it handles
an event; the design now says so and how it is checked.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-05 18:32:49 +01:00
jschoubben 5688a2efa1 Design 47 names the try's events, so the indexer's path to a try is a stream it consumes
The checker says a whole try's start and end as try.started and try.ended on its stream
checks, and the indexer recovers open tries through checker_tries; the record changing
ADR 0637 §4 carries this and is cited until its number is known.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-05 18:31:21 +01:00
jschoubben 7e33e9a15f Design 47 follows ADR 0637 and ADR 0633: a group try, and a revision taken in by its own indexer
A try now checks a delivery group at exact commits with the check's own code, and a
merge's take-in waits for the indexer its revision names, so design 47 says both where
its checks and its source revision are described. The indexer hears a try on the
checker's events rather than reading its state (ADR 0596); the record changing
ADR 0637 §4 to say so is to follow. The glossary gains try and pending revision.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
2026-11-05 18:23:09 +01:00
mesh-tools 674f88f9ab Merge pull request 'Designs and glossary follow ADR 0634, 0635 and 0636: shared code lives with its owner, the seat list from the bus (issue 1966)' (#520) from docs/domain-sdk into main 2026-11-05 13:01:50 +00:00
jschoubben b81c05c36e Designs follow ADR 0636 as accepted: a waiting reader, the bootstrapped three
mesh/delivery merged: source.main moved to novox/hq@674f88f9abb8
mesh/check being carried to b81c05c36e95 on 674f88f9abb8 | from 160f384e4fcd
The accepted record renumbers its clauses and settles what the review asked: a
reader without the seat list starts nothing new but keeps running, its wait
reaches the operator through the condition keeper and the router, which are
bootstrapped with mesh-catalog, a missing definition blocks new claims only,
a move of a definition is a handover, and the private network's value is the
seat's contract. The renames also refuse old names in consumes and say what an
old installer meets; design 47's done milestones keep the name they shipped.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-05 13:40:32 +01:00
mesh-tools 160f384e4f Merge pull request 'Watcher definition: what a machine runs is read from the machine (issue 1585)' (#519) from agents/watcher-reads-machines into main 2026-11-05 12:28:43 +00:00
jschoubben e1713bf59a Designs follow ADR 0636 v4: the seat-definitions verb, the indexer bootstrapped
A full restart must bring back the part that serves the seat list, so the
bootstrapped definitions now name mesh-catalog beside the foundation's seats,
with a test of it. A seat defined outside the mesh's own contracts is taken
from its own contracts module, not refused. The bus server's resources and the
placement check get their owners, and two stale seat names in design 26's old
table are corrected.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-05 13:22:52 +01:00
jschoubben cb1b055b80 Designs follow ADR 0636 and the first review's rulings
The review by architectural domain found that readers of the seat list would
name the indexer, never hear a removal, could deadlock a full restart, and
that any folder could define a seat again; the-private-network's holder sat
in mesh-sdk. ADR 0636 and the lead's rulings answer these, and the designs
must say so before develop.

- design 26: the seat list through a verb and two events of mesh-catalog; a
  reader without it acts on nothing new; a seat defined only in its domain's
  contracts module; states are any holder's, caller-written only for events
  and logs, each with its size cap, declared in the holder's requires; the
  renames move no state; the group's check reads every member's head;
  Connectivity in the mesh-networking repository, held by mesh-wireguard;
  acceptance tests by level and repository; two stale table rows corrected
- design 47: the composer in mesh-delivery-sdk, the bus composer's seat
  parts in the grants part, placement's contract and check by their seat
- design 20: a module's own package is fingerprinted by its own files
- glossary: mesh-placement retired for tool descriptions too; the
  composition renamed to mesh-delivery-sdk's; six seats given their domains

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-05 13:20:45 +01:00
jschoubben c70b275187 Watcher definition: the status view, not the delivery view; the assigner's want verb named (review round 1)
mesh/delivery merged: source.main moved to novox/hq@160f384e4fcd
mesh/check being carried to c70b27518712 on 160f384e4fcd | from d1e2059dab3f
Claude-Session: https://claude.ai/code/session_01JG73KG7AfSdh6FP8VrBqCn
2026-11-05 12:55:21 +01:00
jschoubben b165eb9438 Watcher definition: what a machine runs is read from the machine, not the delivery view's take-in line (issue 1585)
A watcher of 2026-11-05 reported that four modules taken in by hand reached no machine, from the view's
'not yet taken in' line; node-engine.composition showed all four running their new builds.

Claude-Session: https://claude.ai/code/session_01JG73KG7AfSdh6FP8VrBqCn
2026-11-05 12:54:10 +01:00
jschoubben 7d77102db0 Designs and glossary follow ADR 0634 and ADR 0635: shared code lives with its owner
The registry milestone now moves the Delivery domain out of mesh-sdk, creates a
contracts module per domain it moves and the first domain SDK, defines 25 seats
whole with their states, reads the seat list from the bus and renames two seats.
Design 26's *Where a seat's code goes* is what the review and the developer read
to place every new name, so it must say this before develop starts.

- design 26: definitions carry states; the 25 seats by contracts module; the
  seat list from the bus; the two renames; the domain SDK and a module's own
  package; the transfer in the Delivery domain's SDK; checks per ADR 0634 §10
  and ADR 0635 §6
- design 20, playbook 06: the homes of shared code, the first that fits
- design 47: the seat mesh-module-assigner
- glossary: domain SDK added; seat-set package retired; mesh-module-assigner,
  mesh-wants, mesh-node-enroller and the-private-network in their domains
- preparer and code reviewer definitions: the homes, without the retired word

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-05 12:46:06 +01:00
mesh-tools d1e2059dab Merge pull request 'Developer definition: the manifest validator gets one predefined key list for both cases, always (issue 1585)' (#518) from agents/validator-key-list into main 2026-11-05 01:28:03 +00:00
jschoubben 304d17b561 Developer definition: the manifest validator always gets a predefined key list, as the checker passes one
mesh/delivery merged: source.main moved to novox/hq@d1e2059dab3f
mesh/check being carried to 304d17b5612c on d1e2059dab3f | from 331e5707922b
The review of hq #517 noted that the checker always passes the predefined key list (the change's when it alters it,
else the trunk's), while the text said only "when the change alters it" (issue 1585).

Claude-Session: https://claude.ai/code/session_01JG73KG7AfSdh6FP8VrBqCn
2026-11-05 02:15:45 +01:00
mesh-tools 331e570792 Merge pull request 'Developer and reviewer definitions: validate every manifest a change touches before handing back (issue 1585)' (#517) from agents/dev-validates-manifests into main 2026-11-05 00:44:47 +00:00
jschoubben 749249466f Developer definition: the validator run as the checker does it (review round 1)
mesh/delivery merged: source.main moved to novox/hq@331e5707922b
mesh/check being carried to 749249466f8c on 331e5707922b | from 6b8b6b08e39a
Built at mesh-delivery's trunk unless the change alters the validator; raw
manifests in the two cases change and trunk; every manifest whose verdict
differs is reported, an unchanged one included (ADR 0579 §2).

Issue 1585.

Claude-Session: https://claude.ai/code/session_01JG73KG7AfSdh6FP8VrBqCn
2026-11-05 01:41:12 +01:00
jschoubben c4b98b2a03 Developer and reviewer definitions: validate every changed manifest before handing back
The take-in group's first check failed after a full build on a manifest the
validator refused (an indexer's own stream outside the bus's forms); no local
run had validated the changed manifests. The developer now runs the manifest
validator as the checker does and reports each verdict; the reviewer asks for it.

Issue 1585.

Claude-Session: https://claude.ai/code/session_01JG73KG7AfSdh6FP8VrBqCn
2026-11-05 01:38:40 +01:00
mesh-tools 6b8b6b08e3 Merge pull request 'Say manifest validator, not judge: the glossary gains the word and retires the noun' (#516) from docs/manifest-validator into main 2026-11-04 22:39:51 +00:00
jschoubben f91a5a7c75 Name the composing program built from a change, a probe for one health check, and ADR 0579 §2's whole case (review 1)
mesh/delivery merged: source.main moved to novox/hq@6b8b6b08e39a
mesh/check being carried to f91a5a7c75e5 on 6b8b6b08e39a | from f0c05d1edb84
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 23:37:21 +01:00
jschoubben aac8494ca3 Say manifest validator, not judge: the operator asked why a new word was needed for the indexer's rules
The glossary gets the entry in the Delivery domain with the records that decide it, and retires the noun in
hq's prose on a Not line; the verb stays. Where "judge" named something else, the design now uses that
thing's word: the node-engine's look at health, an account or the network; the composition check built from
a change; the claude-code module's judgement tool. Five issue narratives keep the word of their day.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 23:32:13 +01:00
mesh-tools f0c05d1edb Merge pull request 'Where new code goes is a design question: playbook 08, the developer and the code reviewer check it against designs 20 and 26' (#515) from docs/placement-is-a-design-question into main 2026-11-04 22:23:45 +00:00
jschoubben b525f1059b Name the design section, not its number; the preparer and playbook 07 place new code the same way (review 1)
mesh/delivery merged: source.main moved to novox/hq@f0c05d1edb84
mesh/check being carried to b525f1059b69 on f0c05d1edb84 | from d4ae72782336
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 23:20:38 +01:00
jschoubben 69f95f551d Where new code goes is a design question: the playbook, the developer and the reviewer check it against designs 20 and 26
mesh/delivery closed: a newer head of the same pull request
mesh/check pass 69f95f551d19 on d4ae72782336 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | composition passed in 17s on 4…
A small fix's lead placed a seat's type in mesh-sdk by its own handover (issue 1748), against design 26;
the developer built the handover and the reviewer checked against it, so it passed review and its check.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 23:17:57 +01:00
mesh-tools d4ae727823 Merge pull request 'Designs 20, 25, 26, 32, 51, 55 and playbook 07: the registry milestone as built (issue 1966)' (#514) from docs/registry-milestone-designs into main 2026-11-04 18:19:24 +00:00
jschoubben 304ce84cac Designs 32, 25: a state may be read-only to the tools; nats_requests reads spent so
mesh/delivery merged: source.main moved to novox/hq@d4ae72782336
mesh/check being carried to 304ce84cac18 on d4ae72782336 | from 273d608d9faa
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 18:10:48 +01:00
jschoubben e0a70a468b Designs 25, 51: name the spent state; a shared-digest tag is recorded as kept
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 18:08:58 +01:00
jschoubben 571c0a3e68 Designs 25, 51: follow review round 2 (decided via uses, spend record apart, fix checks, genesis gap, kept answer)
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 18:08:36 +01:00
jschoubben b0a9fa14da Playbook 07: a group's pin is for GOWORK=off; the check builds against the group's heads (ADR 0573), so an older pin is not refused
The line said the checker refuses an older commit of the same branch; that refusal was removed as a fault of the check
(issue 1585). Found pinning the registry milestone, where mesh-sdk and mesh-contracts import each other.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 17:49:32 +01:00
jschoubben b3a9970ac7 Design 51: name ADR 0627 among its decisions
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 17:33:15 +01:00
jschoubben 5499c3546b Design 51: cite ADR 0627 for the holders' shared receiving side, ADR 0611 §3 for the drop
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 17:32:54 +01:00
jschoubben c3d8367b33 Designs 25, 51: write what review round 1 settled (acted key, ask lifetime, loopback bootstrap, shared idle drop, shared-digest tag, forge account removal)
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 17:32:21 +01:00
jschoubben 8f75606167 Designs 25, 51: follow review round 1 of the registry milestone
Design 25 counts seven first-view tools, the indexer's graph granted to the
assigner alone (ADR 0631); the bus module's process wakes on its own decided
and acts on a warrant once (ADR 0259 §6, ADR 0620 §2) instead of a timer, and
the tools watch their request key; §12.7 carries the rows, and its first-view
row, split by an earlier edit, is one row again. Design 51's incoming store
asks the objects template's most, 8 GiB, with no lifetime; the holder drops an
idle transfer itself (ADR 0611 §3).

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 16:23:11 +01:00
jschoubben 901c92a924 mesh-developer: run the repository's own checks whole before reporting a head, and start no agents of your own
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 15:51:25 +01:00
jschoubben bdc5ae4fe6 Design 26: the seat definitions' generator is one program in the Go build module, run by both build modules
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 15:09:57 +01:00
jschoubben aced03a287 Design 32: a package is named by its name in its own language, one name across the indexer, builder, registry seat and users
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 14:46:30 +01:00
jschoubben da1c7f30a9 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
2026-11-04 13:19:57 +01:00
mesh-tools 273d608d9f Merge pull request 'Designs 51, 32: the windows wake on the node-engine seat's manifest-reads-changed (ADR 0618), and every build stays readable by every counted node-engine (ADR 0624)' (#513) from docs/cite-adr-0618 into main 2026-11-04 09:08:19 +00:00
jschoubben cac55dc254 Design 51: follow ADR 0624, every build keeps each counted node-engine's form
mesh/delivery merged: source.main moved to novox/hq@273d608d9faa
mesh/check being carried to cac55dc2543a on 273d608d9faa | from 6cd965b3cdf6
ADR 0624 supersedes ADR 0623, which could find the node-engine's own
builds only by the module's name. Every build now keeps each form a
counted node-engine states, the oldest in the single reference, and a
node is held only when it reads none of them.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 09:59:44 +01:00
jschoubben 01d4f2781e Design 51: keep the node-engine's own build readable by away nodes (ADR 0623)
mesh/delivery closed: a newer head of the same pull request
mesh/check pass 01d4f2781ef0 on 6cd965b3cdf6 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | composition passed in 33s on 4…
Under ADR 0618 alone a node away with an old node-engine would be held
from the node-engine's own build in the new form and could never update
itself. ADR 0623 keeps every counted node-engine's form in those builds
and moves them to a node that reads any one of them.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 09:48:56 +01:00
jschoubben 48fa0a5a48 Designs 51, 32: name the manifest-reads grant and who holds the old-form window
The upgrade and security review asked that each window's caller be
granted the event through its invokes, that an away node be held by the
assigner rather than the old-form window, and that a node-engine not yet
serving manifest-reads keep a window open by name.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 09:46:46 +01:00
jschoubben f47744a8b6 Designs 51, 32: cite ADR 0618 for the windows' wake and the reference form
ADR 0618 is accepted: the node-engine seat's manifest-reads verb and its
manifest-reads-changed event wake the old seat name's, the old-form and
the rename windows, and the builder writes a new form only once every
present node-engine states it. The next delivered stays only for the
rename window's case the record does not cover.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 09:44:31 +01:00
mesh-tools 6cd965b3cd Merge pull request 'Designs 25, 51: the registry milestone's prepare points (a failed pull retried on the store holder's settled, the owners' read tools, verdicts as a first view, ADR 0622)' (#512) from docs/registry-prepare-points into main 2026-11-04 08:40:09 +00:00
jschoubben 4f6b9f0ca5 Designs 25, 51: bound the race retry to a settled heard after the pull started
mesh/delivery merged: source.main moved to novox/hq@6cd965b3cdf6
mesh/check being carried to 4f6b9f0ca5ff on 6cd965b3cdf6 | from e7ac664afff7
A retry on any settled ever heard would apply again on every failure; the
pull's start bounds it to one retry per settled, kept in memory. The seat and
holder beside a routed image are outside a container's digest, so naming
them replaces nothing, and the verdicts gap case is named.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 02:16:03 +01:00
jschoubben a838b6b3d3 Design 51: a routed image names its seat and holder, so the retry matches settled by it
The declaration carried only the store's address, so the node-engine could
not tell whose settled ends a failed pull without naming a module.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 02:13:10 +01:00
jschoubben 6c6b2c5cc1 Designs 25, 51: verdicts a first view of its own; every node hears the holder settle
The store's holder runs on one node, so a node-engine elsewhere must hear its
settled too, and a pull failed just after it settled must not wait. The
grants part's verdicts read is a first view under ADR 0622, not an ordinary
read tool, and the node-engine's reads granted in code are said, so the
live count of zero declared reads is not taken for more than it is.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 02:12:38 +01:00
jschoubben fb7aa0915f Design 25: the grants part reads the indexer's verdicts through a read tool
The grants part is the one reader of the indexer's verdicts, and no first
view covered that bucket, so its move had no path. It now takes its first
view through indexer_read_verdicts and follows the manifest events.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 02:05:51 +01:00
jschoubben 74b69857a1 Designs 25, 51: retry a swapped pull on settled; owners' read tools get names of their own
Neither condition-cleared nor delivered comes during the store holder's own
delivery, so the node-engine retries on the status view's settled for that
holder, heard through the grants part's list, and at its own start. The
status view keeps its tools and answers them through the owners' new read
tools, so no name moves between modules.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 02:04:51 +01:00
jschoubben 0e8a698025 Designs 25, 51: the owners take the view's six tool names; distribution's delivered retries a failed pull
The status view can no longer answer its six tools named for the owners'
buckets once it stops reading them, so the owners' tools take the names. A
finding held during distribution's own delivery raises no condition and so
no clear, so the node-engine also tries a failed pull again on the status
view's delivered for distribution, and nothing waits for a hand compose.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 01:59:59 +01:00
jschoubben 01d2ea0855 Designs 25, 51: settle the registry milestone's prepare points
A pull that falls in distribution's swap is tried again on the condition
keeper's clear of the store's holder's condition, so the delivery needs no
hand compose and no timer. The owners' tools for the other readers' buckets
are named, the reads count has its tool, and the test paths match main.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 01:58:54 +01:00
mesh-tools e7ac664aff Merge pull request 'Designs 25, 26, 32, 51, 55: the registry milestone's designs after the review by architectural domain (ADR 0615-0621)' (#511) from docs/registry-milestone-designs into main 2026-11-04 00:46:48 +00:00
jschoubben 457ac2eabd Designs 25, 26, 51: cite ADR 0620 and ADR 0621; the owners serve their first views as tools in a runtime of their own
mesh/delivery merged: source.main moved to novox/hq@e7ac664afff7
mesh/check being carried to 457ac2eabdcd on e7ac664afff7 | from 276cbef0c476
ADR 0621 keeps the manifest form as it is, so the process-subject form, its mesh-sdk change, the
open point on who grants it and the push's wait on a judge release all go; the per-verb grants and
the record's four checks take their place.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 01:43:36 +01:00
jschoubben 216e0e5102 Design 26: keep the seats' own events apart from their holders', since no event moves subject in this milestone
The four seats defined whole list only what their seat subject carries as the seat's; the
holders' events stay under their own subjects, checked by a fixture from the running holder.
The vault seat drops the two verbs no holder serves.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:53:30 +01:00
jschoubben f91f4879fc Design 25: cite ADR 0619, accepted, for the foundation that keeps the old sections
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:49:42 +01:00
jschoubben c8e6eb5edf Designs 26, 51, 25: define whole the four seats the milestone adds verbs or events to
The operator chose to move them now (2026-11-04), so a seat's new verb never lands at the seat
list's grain. Each is listed with what its holder's manifest on the trunk serves today; the
builder and the indexer hold no seat, so their events stay module events.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:47:45 +01:00
jschoubben a81334b1af Design 32: the rename window closes on the next delivered while ADR 0618 is only reserved, and no waiter on the vault's rotation wakes on own-retired
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:46:40 +01:00
jschoubben 546a18a20e Design 25: answer the third review (views families on the old streams sections under a record extending ADR 0595 §10, the tool runner's first-view tools on the mesh MCP server, the running judge takes the process-subject form in)
The assigner must start on a fresh mesh before the bus module can answer, so its new stream
stays on its old section; a new indexer can never judge its own manifest, so the running judge
must accept the form first. The glossary stops counting the mesh MCP server's tools.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:46:25 +01:00
jschoubben a9745b63cb Design 51: answer the third review (ADR 0618 only reserved, a module's images pulled before its containers are replaced, public package reads kept, levels on every new case)
The windows close on the next delivered until ADR 0618 is accepted; distribution's first
delivery needs the node-engine to pull every image first, since its registry serves every pull;
the operator kept public reads, so ADR 0346 stands and the route refusal goes.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:42:35 +01:00
jschoubben 021fca5e6d Design 32: the rename window wakes on the node-engine seat's event of ADR 0618, as design 51's old seat name does
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:32:24 +01:00
jschoubben fa2d199b16 Design 51: answer the second review (event wakes for every floor source, versions within the state cap, the direct-write and old-form windows shaped as the old name's, release on the caller list, distribution's own family)
Also writes the operator's answer of 2026-11-04 on anonymous reads (mesh network only, the public route refusing
the forge's package paths), the expected count of three builds per module, and the revert's order by the graph.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:31:30 +01:00
jschoubben cdfddff72e Design 25 § 12: owners' events carry the value whole, a deleted module's entries become orphans, the first views get named tools and a live bound
Answers the second review's V1-V9 by architectural domain: the assigner's views in the new form, newer by revision
alone, what a reader does when a recreate takes revisions back, a hand re-say of manifest-accepted, and the judge
question under the open point on issue 1966.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:29:30 +01:00
jschoubben 939d000327 Design 32: name the vault's event for retire and its family
Answers the second review's R1 by architectural domain: own-retired on the module events stream under the vault's subjects.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:28:07 +01:00
jschoubben e51e6961e3 Design 55 § 11: say what from: machine gives the page's port, that local processes reach it until issue 1968, and that the route proxy runs on its node
Answers the second review's K1 by architectural domain.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:28:07 +01:00
jschoubben 0168a545c5 Design 51: cite ADR 0617 for the unnumbered-first image and hold; narrow hold to what the sweep keeps, never an image
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:12:24 +01:00
jschoubben 0ae7fc2e57 hq-design-writer: it calls no verb that writes on the mesh; what a record must carry goes to the caller
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:11:23 +01:00
jschoubben da823becbe Design 55 § 11: answer the first review (the router's stream kept and capped, the page's port reached only by the route proxy, a re-read tool per source)
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:11:15 +01:00
jschoubben 3b1278b3bc Design 32: answer the first review (the checker invokes renames and waits for it, retire's caller list and warrant, retired events, tests, the away node's window)
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:10:57 +01:00
jschoubben 4710fd18c6 Design 26: answer the first review (the seat list's grain as ADR 0613 has it; out of step cleared only by the same contracts module)
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:10:40 +01:00
jschoubben 34384b6c9c Design 25 § 12: answer the first review of the milestone amendment (the bus module's first view against replays and an unanswered tool, the foundation readers' bounds, families and tools, the tests they join, the open grant)
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:10:19 +01:00
jschoubben 2d48b85c0e Design 51: answer the first review of the milestone amendment (builds counted from the records, the write side's window and outage, the revert's open points, holds and the old name's events, live proof)
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:09:56 +01:00
jschoubben 01a0a3a4d9 Amend designs 51, 26, 32, 25 and 55 for the registry milestone
The registry move, seat definitions, declares, bus state and the knowledge base
ship as one milestone (ADR 0612, 0613), ordered by the module graph's edges
(ADR 0614), with the foundation parts' first view (ADR 0615) and the overview
page (ADR 0616). The designs said four deliveries, a seat-definition source
nobody serves, a checker naming mesh-config, and left the bus module's first
view, caller and deletion paths open; they now say what the milestone builds.
Adds the glossary words it uses, playbook 02's cites link for an abandoned
effort, and the hq-design-writer agent definition.

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-04 00:02:43 +01:00
mesh-tools 276cbef0c4 Merge pull request 'Graduate research 081: registries are seats published into over the bus, the builder numbers every build, seat definitions on the bus, contracts modules' (#510) from docs/graduate-081 into main 2026-11-03 20:12:24 +00:00
jschoubben 5b2cead5e3 Designs 51 and 32: answer the third review (publish-part listed with its callers, the node-engines' reports through the status view, C24 tested)
mesh/delivery merged: source.main moved to novox/hq@276cbef0c476
mesh/check pass 5b2cead5e3bc on 276cbef0c476 | carried from f6bd4246b0d7 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-03 18:10:19 +01:00
jschoubben 9845b78e5b Designs 51, 26, 32: answer the second review by architectural domain (ADR 0611, caller identity, node-engine reports, families and retention, Go references); add each design's review record
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-03 18:08:00 +01:00
jschoubben 20157fcafe Designs 51, 26, 32: answer the first review by architectural domain (ADR 0596 paths, holder-side caller lists, the file in the publish verb, findings for the condition keeper, windows on node-engine reports)
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
2026-11-03 18:02:09 +01:00
jschoubben 27063a492b Graduate research 081 into designs 51, 26 and 32: registries are seats published into over the bus, the builder numbers every build, seat definitions on the bus, contracts modules (ADR 0605-0609) 2026-11-03 17:10:36 +01:00
mesh-tools f6bd4246b0 Merge pull request 'mesh-watcher waits on the event of the part that owns the fact it watches' (#509) from docs/watcher-owner-event into main 2026-11-03 13:27:21 +00:00
jschoubben 33d25c5074 mesh-watcher: the glossary's words, the delivery gate and the status view
mesh/delivery merged: source.main moved to novox/hq@f6bd4246b0d7
mesh/check pass 33d25c50742e on f6bd4246b0d7 | carried from 979bf3f19cce | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-11-03 13:29:36 +01:00
jschoubben bf5ef24ea3 mesh-watcher waits on the event of the part that owns the fact it watches (the operator, 2026-11-03) 2026-11-03 13:28:44 +01:00
mesh-tools 979bf3f19c Merge pull request 'hq ignores .work/, where every subagent's worktrees and context files live' (#508) from docs/groomer-and-gitignore into main 2026-11-03 11:58:08 +00:00
jschoubben c5644e4a5d The groomer is the issue tracker's, not an hq agent (the operator, 2026-11-03): only .work/ ignored stays
mesh/delivery merged: source.main moved to novox/hq@979bf3f19cce
mesh/check pass c5644e4a5de3 on f6bd4246b0d7 | carried from 979bf3f19cce | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-11-03 12:54:02 +01:00
jschoubben 43d5347258 An issue-groomer agent definition for playbook 03; .work/ is ignored, so worktrees never reach the public repository 2026-11-03 12:53:40 +01:00
mesh-tools b5347d0294 Merge pull request 'Agents work from hq's definitions and start from the knowledge base; every prepare and record gets the seams review' (#507) from docs/agents-from-hq into main 2026-11-03 11:48:55 +00:00
jschoubben 4315bb6307 A subagent works from hq; a coding one in a worktree under hq's .work, also reading its repository's conventions (the operator, 2026-11-03)
mesh/delivery merged: source.main moved to novox/hq@b5347d029453
mesh/check pass 4315bb6307c1 on f6bd4246b0d7 | carried from 979bf3f19cce | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-11-03 12:46:24 +01:00
jschoubben e8c154c3a0 Agent definitions: the developer on the smaller model unless the lead says why; review notes
mesh/delivery closed: a newer head of the same pull request
mesh/check pass e8c154c3a0ba on 9a2d398070ed | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | composition passed in 18s on 4…
2026-11-03 12:15:48 +01:00
jschoubben 666c9271dc mesh-developer: the test budget is read from the instructions, not copied 2026-11-03 12:15:19 +01:00
jschoubben d829fd6f9b Playbook 02: name no record in the seams rule 2026-11-03 12:14:48 +01:00
jschoubben 10df1c7be5 Playbooks overview: agents from hq's definitions; the seams review of every prepare 2026-11-03 12:14:25 +01:00
jschoubben 8420c6f236 Agents work from hq's definitions and start from the knowledge base; every prepare and record gets the seams review (the operator, 2026-11-03) 2026-11-03 12:14:12 +01:00
mesh-tools 9a2d398070 Merge pull request 'Bus state by template, no readers, and the ledger: designs 25, 32 and 55 and the glossary follow ADR 0595-0597' (#506) from docs/1966-bus-state into main 2026-11-03 10:21:09 +00:00
jschoubben 476557deeb The review record's seams row names the process's own tool subject
mesh/delivery merged: source.main moved to novox/hq@9a2d398070ed
mesh/check pass 476557deeb4b on f6bd4246b0d7 | carried from 979bf3f19cce | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-11-03 10:51:18 +01:00
jschoubben 3d4e361425 Designs 25, 32 and 55 record their review by architectural domain 2026-11-03 10:50:27 +01:00
jschoubben 0cd0cfd778 Design 25 names the signed caller and what the watchman newly hears; design 55 checks the database at every start before the drop 2026-11-03 10:49:43 +01:00
jschoubben c033592509 Design 25's bus module is unhealthy only on a verdict left unanswered; design 55 keeps its sent events in a state of its own 2026-11-03 10:49:10 +01:00
jschoubben 221165c712 Designs 25 and 55 answer the review by architectural domain: the bus module's events on its old sections, overdue creation raised by the watchman, the proven author, events and the database caught up after a restart, the bus module's integration test 2026-11-03 10:47:44 +01:00
jschoubben ed67d1f84f Bus state by template, no readers, and the ledger: designs 25, 32 and 55 and the glossary follow ADR 0595-0597
Research 082 graduated into three accepted records; the bus module's design (25) and the manifest's (32) are the home of bus state for every module, and the knowledge base (55) becomes its first ledger.
2026-11-03 10:42:58 +01:00
mesh-tools 08b968fd80 Merge pull request 'Design 47: the bus module is wanted like any module; only a warranted want replaces its server (ADR 0594)' (#505) from docs/774-bus-want into main 2026-11-03 01:09:31 +00:00
jschoubben b01f867345 Design 47: the bus module's want follows ADR 0594
mesh/delivery merged: source.main moved to novox/hq@08b968fd80cb
mesh/check pass b01f86734552 on f6bd4246b0d7 | carried from 979bf3f19cce | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
Claude-Session: https://claude.ai/code/session_01NcbgfJ9Gum47zkFKWRaovL
2026-11-03 02:02:39 +01:00
mesh-tools 92fa66f4e7 Merge pull request 'A research effort's reading tasks run on one agent definition, research-reader' (#504) from docs/research-reader into main 2026-11-03 00:51:58 +00:00
jschoubben 6bc1f7cc10 research-reader cites no path, as playbook 01 asks; AGENTS.md rewrapped
mesh/delivery merged: source.main moved to novox/hq@92fa66f4e79f
mesh/check pass 6bc1f7cc1040 on f6bd4246b0d7 | carried from 979bf3f19cce | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-11-03 01:45:29 +01:00
jschoubben 402ac3bfda Design 47: the assigner writes the bus module's want only to a node agent that keeps the server, and the test says so
Claude-Session: https://claude.ai/code/session_01NcbgfJ9Gum47zkFKWRaovL
2026-11-03 01:44:38 +01:00
jschoubben ae4c90f990 Design 47: the bus module is wanted like any module, and only a put replaces its server (issue 774, the operator 2026-11-03)
Claude-Session: https://claude.ai/code/session_01NcbgfJ9Gum47zkFKWRaovL
2026-11-03 01:37:31 +01:00
mesh-tools 4d4524cda3 Merge pull request 'Design 55: the knowledge base keeps its records on the bus and is written and reviewed by section (ADR 0592, ADR 0593 §10)' (#502) from feat/kb-nats-native into main 2026-11-03 00:07:23 +00:00
mesh-tools 5accd21320 Merge pull request 'Playbook 07 and design 47 after the controller left: run as the running checker, let the running parts judge, L2 delivered' (#503) from docs/1126-after-controller into main 2026-11-03 00:05:04 +00:00
jschoubben 3a3501d9f4 Playbook 07 and design 47: say how the two new rules are checked; glossary words; name where the bus module has no want
mesh/delivery merged: source.main moved to novox/hq@5accd2132013
mesh/check pass 3a3501d9f480 on f6bd4246b0d7 | carried from 979bf3f19cce | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
Claude-Session: https://claude.ai/code/session_01NcbgfJ9Gum47zkFKWRaovL
2026-11-03 00:58:19 +01:00
jschoubben 8402a7d773 Design 47: L2 is built and delivered as release sdk1, done once a check composes on every machine; L3 names what the controller's leaving left unwritten (issue 1126, issue 774)
Claude-Session: https://claude.ai/code/session_01NcbgfJ9Gum47zkFKWRaovL
2026-11-03 00:57:29 +01:00
jschoubben 5d9a654767 Playbook 07: run every suite as the running checker places it, and let the running parts judge a release that changes them (issue 1126, release sdk1)
Claude-Session: https://claude.ai/code/session_01NcbgfJ9Gum47zkFKWRaovL
2026-11-03 00:52:28 +01:00
jschoubben 1a389be090 A research effort's reading tasks run on one agent definition, research-reader, instead of a prompt written by hand each time 2026-11-03 00:28:06 +01:00
jschoubben c2b162a9e8 Design 55: readers by grant, the take-over refused while an Approve waits, the grants part's own test, §30 for nesting, the glossary's word in the review table
mesh/delivery merged: source.main moved to novox/hq@4d4524cda3e0
mesh/check pass c2b162a9e8da on f6bd4246b0d7 | carried from 979bf3f19cce | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-11-02 19:58:01 +01:00
jschoubben 3122e8be84 Design 55: follow ADR 0593: the mesh-sdk release sdk1 does the controller's part (the grants part creates, grants and warns; the indexer's judge checks the forms) 2026-11-02 19:55:40 +01:00
jschoubben 36517018d3 Design 55: one more use of the chosen word 2026-11-02 19:55:40 +01:00
jschoubben b8ad9da784 Design 55: the review section uses the word the operator chose, architectural domain 2026-11-02 19:55:40 +01:00
jschoubben eaa98758b9 Design 55: follow ADR 0592's tenth version: submit commits when its version is stored, and the tests for the rollback's double write and the Approve bound to its sections 2026-11-02 19:55:40 +01:00
jschoubben b9a42eaf90 Design 55: follow ADR 0592's eighth version: readers by ADR 0363's grant, extended to the object bucket; each cap within its form's bound; clause numbers after the splits 2026-11-02 19:55:40 +01:00
jschoubben 6256fc8e3b Design 55: follow ADR 0592's sixth version and the review by aspect: whole-or-refused writes, caps, the move's window and rollback, the delivery order, the judge's judged event, events with what they carry, a test per failure path, and a section Reviewed by aspect
The glossary gains opened and drafted, so a draft's first step is never called drafted.
2026-11-02 19:55:40 +01:00
jschoubben 012d276dcc Design 55: follow ADR 0592's revision: a stream that keeps its history, a module's own object bucket, the frame's bound and the move's full check 2026-11-02 19:55:40 +01:00
jschoubben 5a9a5d8d1d Design 55: the knowledge base keeps its records on the bus and is written and reviewed by section (ADR 0592), so a long record is judged whole and a draft lives only in the knowledge base
The glossary gains section, draft, form-only version and search index, and the homonyms section and draft.
2026-11-02 19:55:40 +01:00
mesh-tools 2731c796f0 Merge pull request 'hq's words test reads .claude/, so agent and skill definitions use the glossary's words' (#501) from docs/agent-roles-defined into main 2026-11-02 18:48:16 +00:00
jschoubben 7470927a07 Playbook 07 keeps to feature work: the rule on agent definitions goes to an instruction section for every session (the operator, 2026-11-02)
mesh/delivery merged: source.main moved to novox/hq@2731c796f0d6
mesh/check pass 7470927a07a0 on 2731c796f0d6 | carried from 7021d0cf5ac0 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-11-02 19:45:17 +01:00
jschoubben 6c395cc206 Playbook 07: say how the agent-definition rule is checked
mesh/delivery closed: a newer head of the same pull request
mesh/check pass 6c395cc20667 on 7021d0cf5ac0 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | composition passed
2026-11-02 19:42:08 +01:00
jschoubben 594a0871dd Playbook 07: a role started more than once is an agent definition in the repository it serves; hq's words test reads .claude/ 2026-11-02 19:41:34 +01:00
mesh-tools 7021d0cf5a Merge pull request 'Four reviewer agents carry playbook 01's review by architectural domain, two architectural domains each' (#500) from docs/domain-reviewers into main 2026-11-02 18:41:15 +00:00
jschoubben 4037bc1fb0 Reviewer agents: catalog, the glossary's word
mesh/delivery merged: source.main moved to novox/hq@7021d0cf5ac0
mesh/check pass 4037bc1fb0d7 on 2731c796f0d6 | carried from 7021d0cf5ac0 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-11-02 19:39:19 +01:00
jschoubben 121b582ebc Four reviewer agents carry playbook 01's review by architectural domain, two architectural domains each, so every review asks the same questions 2026-11-02 19:38:35 +01:00
mesh-tools fa3d8aaeec Merge pull request 'Playbooks 01 and 02: review by architectural domain, sections named by title with no file references, and storage forms that fit (the operator, 2026-11-02)' (#499) from docs/review-by-aspect into main 2026-11-02 18:27:14 +00:00
jschoubben 633c587a1e Glossary: bare domain keeps the mesh-domain sense; only the review's sense is always qualified, so the homonym rule holds without rewriting every use
mesh/delivery merged: source.main moved to novox/hq@fa3d8aaeec69
mesh/check pass 633c587a1eef on 2731c796f0d6 | carried from 7021d0cf5ac0 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-11-02 19:22:45 +01:00
jschoubben 6f2bacf6c4 Architectural domain for the review's eight concerns, and the glossary's domain qualified as mesh domain in the homonyms, as the operator chose on 2026-11-02 2026-11-02 19:21:48 +01:00
jschoubben f5624e7d9f Review fixes: the research skill names sections by title, the drawn overview's order and bounds follow the playbooks, an amended design is reviewed by aspect, and storage forms use glossary words 2026-11-02 18:20:12 +01:00
jschoubben b861b3ae36 Glossary: review aspect; playbook 01: a piece of state takes the bus storage form that fits it, and a form added to mesh-sdk is named to the operator with its cost 2026-11-02 18:19:05 +01:00
jschoubben 0ac621e03f Playbooks 01 and 02: review a direction and a design by aspect before proposing or merging, and name a record's sections by title with no file references, as the operator asked on 2026-11-02 2026-11-02 18:19:05 +01:00
mesh-tools f312e7cd0e Merge pull request 'Playbook 07: the prepare step reads what exists today before any code' (#498) from docs/pb07-what-exists into main 2026-11-02 15:16:21 +00:00
jschoubben 2b9e6b256b Read what exists before writing code, in the prepare step
mesh/delivery merged: source.main moved to novox/hq@f312e7cd0ea6
mesh/check pass 2b9e6b256b4b on f312e7cd0ea6 | carried from 1747485cb351 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
Each layer (research, decisions, survey, review) checked the layer before
it and none read the running code, so effects of the controller's removed
jobs surfaced only after delivery. Playbook 07's prepare step now writes,
per context file, what exists today, every effect and reader of what is
removed or moved, and each one's fate with its test; the review refuses
work without it. Playbook 08 reads its area the same way, briefly.

Claude-Session: https://claude.ai/code/session_01NcbgfJ9Gum47zkFKWRaovL
2026-11-02 16:14:17 +01:00
mesh-tools 1747485cb3 Merge pull request 'Design 47 and the glossary follow what L3 to L7 built (issues 774, 1952, 1953, 1954, 1955)' (#496) from feat/774-l3-reland into main 2026-10-30 11:01:45 +00:00
jschoubben 0c450cad25 Design 47: the L4 row cites ADR 0572, the self-check probes kept and dropped
mesh/delivery merged: source.main moved to novox/hq@1747485cb351
mesh/delivery-group group feat/774-l3-reland merged: every member is merged
mesh/check pass 0c450cad258e on 1747485cb351 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | composition passed in 8.3s
2026-10-30 01:16:33 +01:00
jschoubben 2e235286b1 Glossary: cite ADR 0571's accepted insight for the artifact sweep's seat name 2026-10-30 00:03:39 +01:00
jschoubben a35c7ed6d0 Glossary and design 47: the release's new words and the L3-L7 homes as decided (ADR 0563-0571), so readers find where each controller job now lives 2026-10-29 23:58:11 +01:00
mesh-tools e65f897a1f Merge pull request 'Playbooks 07 and 08 name the checker's try beside the controller's (issue 774, ADR 0561), rebased onto L2' (#495) from feat/774-vault-mints-l2 into main 2026-10-29 07:44:15 +00:00
jschoubben 7fd89de7cb Playbook 07: item 9 names no wrong item
mesh/delivery merged: source.main moved to novox/hq@e65f897a1fda
mesh/delivery-group group feat/774-vault-mints-l2 merged: every member is merged
mesh/check pass 7fd89de7cb81 on 1747485cb351 | carried from e65f897a1fda | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-10-29 01:56:19 +01:00
jschoubben f4fdbde558 Playbook 07: rules for a delivery group's mesh-sdk pins, learned on 2026-10-28, so the next group does not meet the same refusals 2026-10-29 01:56:19 +01:00
jschoubben 7d022710b3 Playbooks 07 and 08: name the controller's try too while its verb exists (issue 774)
mesh/delivery-group group feat/774-vault-mints-l2 ready: every member ready, and composed together they pass
mesh/delivery closed: a newer head of the same pull request
mesh/check pass 7d022710b34b on eec73b8af0d7 | unit 1929 run, 4791 kept, 47 skipped | integration 1993 run, 4856 kept, 49 skipped | over bound: unit, …
2026-10-28 20:37:05 +01:00
jschoubben f89b8599c6 Playbooks 07 and 08 name the try by the checker's seat: mesh-delivery-checker.try replaces mesh-controller.try (ADR 0547 §10, issue 774) 2026-10-28 20:36:59 +01:00
mesh-tools eec73b8af0 Merge pull request 'Design 47 and the glossary: placement is bus state of the seat mesh-placement (issue 1126, delivery 2 of 2)' (#494) from feat/1126-placement-seat into main 2026-10-28 18:32:58 +00:00
jschoubben 1aa887dd28 Glossary: placement, mesh-placement, placement proposal, candidate and hand-back replace the placement file
mesh/delivery merged: source.main moved to novox/hq@eec73b8af0d7
mesh/delivery-group group feat/1126-placement-seat merged: every member is merged
mesh/check pass 1aa887dd2898 on eec73b8af0d7 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | composition passed
2026-10-28 18:25:31 +01:00
jschoubben aa4c2fe7ef Design 47: placement is bus state of the seat mesh-placement, changed by a proposal (ADR 0567) 2026-10-28 18:25:19 +01:00
mesh-tools 292232dad2 Merge pull request 'Playbooks 07 and 08: every review asks where each piece of state lives and whether a repository holds mesh setup' (#493) from pb/state-and-seams into main 2026-10-28 16:46:35 +00:00
jschoubben a9830f5110 Playbooks 07 and 08: the review asks where state lives and how seams travel, and whether a repository holds mesh setup
mesh/delivery merged: source.main moved to novox/hq@292232dad226
mesh/check pass a9830f51106c on eec73b8af0d7 | carried from 292232dad226 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-10-28 17:43:44 +01:00
mesh-tools 02a18c9aa8 Merge pull request 'Design 47's L5 row and the glossary follow ADR 0565' (#492) from docs/0565-homing into main 2026-10-28 13:08:30 +00:00
jschoubben 606956da97 Design 47 L5 and the glossary: add clause 8 and the lease-write gate, both readers of kept, upgrade answered side by side
mesh/delivery merged: source.main moved to novox/hq@02a18c9aa8ab
mesh/check pass 606956da970a on eec73b8af0d7 | carried from 292232dad226 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-10-28 13:29:42 +01:00
jschoubben d088f17cd2 Design 47 L5 and the glossary follow ADR 0565: say which parts leave the controller and which seat takes each 2026-10-28 13:28:11 +01:00
mesh-tools dd03229ea8 Merge pull request 'Playbook 07 follows report-cadence: the short report every five minutes, the full one every thirty' (#491) from pb/report-cadence into main 2026-10-28 11:35:44 +00:00
jschoubben 781392b121 Playbook 07: the report follows the report-cadence section (short every 5 min, detailed every 30 min)
mesh/delivery merged: source.main moved to novox/hq@dd03229ea886
mesh/check pass 781392b12137 on eec73b8af0d7 | carried from 292232dad226 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-10-28 12:32:05 +01:00
mesh-tools c2f4bb2d48 Merge pull request 'The glossary's word is catalog, not catalogue (group words/catalog)' (#490) from words/catalog into main 2026-10-28 11:31:29 +00:00
jschoubben ea0c62355c The glossary's word is catalog: replace the spelling catalogue in running prose
mesh/delivery merged: source.main moved to novox/hq@c2f4bb2d485d
mesh/delivery-group group words/catalog merged: every member is merged
mesh/check pass ea0c62355c1c on eec73b8af0d7 | carried from 292232dad226 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-10-28 11:27:34 +01:00
mesh-tools 8f8393fa93 Merge pull request 'Playbooks 07 and 08: lessons of 2026-10-28 (the report's tree, its cadence, named local integration tests, member repositories during a check, delivered means what the nodes run, real-shaped fixtures)' (#489) from pb/lessons-2026-10-28 into main 2026-10-28 10:15:18 +00:00
jschoubben dd36b7557a Playbooks 07 and 08: the local integration run is the named tests that exercise the change; the report's tree is drawn from the verb
mesh/delivery merged: source.main moved to novox/hq@8f8393fa9343
mesh/check pass dd36b7557ae6 on 8f8393fa9343 | carried from 2ea3368b76d1 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-10-28 11:12:23 +01:00
jschoubben d348256090 Playbooks 07 and 08: lessons of 2026-10-28 (progress tree, report cadence, local integration run, group members, delivered, fixtures) 2026-10-28 11:10:26 +01:00
mesh-tools 2ea3368b76 Merge pull request 'Design 47: ADR 0564 homes health (L4), and milestones L5 to L7 give the controller's other jobs their homes before L3's lease write' (#488) from docs/47-adr-0564 into main 2026-10-28 09:46:31 +00:00
jschoubben 3c2d5af436 Design 47: milestones L5 to L7 join L4 as the homes of the controller's other jobs
mesh/delivery merged: source.main moved to novox/hq@2ea3368b76d1
mesh/check pass 3c2d5af436fb on 8f8393fa9343 | carried from 2ea3368b76d1 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
Brings in docs/47-072-milestones (edbb53b): the rows L5 to L7 and the paragraph that orders L4 to L7
before L3's lease write. L4 keeps the row that follows ADR 0564; that branch's earlier L4 wording,
which named events the record does not keep, is dropped.
2026-10-28 10:42:35 +01:00
jschoubben bcad1e363a Design 47 and the glossary home ADR 0564: health leaves the controller in milestone L4
ADR 0564 is accepted on the operator's Approve. Design 47 names it and gains L4's row (issue 1952);
the glossary gains condition keeper, observer and take-over, and finding, self-check and the
watchman say where they are kept and held now.
2026-10-28 10:41:29 +01:00
jschoubben edbb53bb78 Design 47: milestones L4 to L7 give the controller's other jobs their homes before L3's lease write
The operator said yes on 2026-10-28 to making research 072's proposed homes milestones after L3,
so their decision records and design can start beside L3. ADR 0547 §11 makes the lease write wait
for every one of them; issues 1952 to 1955 carry each, a decision record first.
2026-10-28 09:40:05 +01:00
mesh-tools 32da464794 Merge pull request 'How-we-build: a bus permission is proven under the real permission (ADR 0560); playbook 07 notes the 2026-10-27 failure' (#486) from pb/seed-lessons-2026-10-27 into main 2026-10-27 21:19:59 +00:00
mesh-tools 10bc8d396c Merge pull request 'Design 47: R4d says what it became, three image reworks done and n8n left by ADR 0506' (#487) from design/47-r4d-done into main 2026-10-27 21:16:02 +00:00
jschoubben 8e732e22ae Design 47: R4d is done; record the three reworks, n8n's exit and the issues (ADR 0480, 0487, 0497, 0506)
mesh/delivery merged: source.main moved to novox/hq@10bc8d396ceb
mesh/check pass 8e732e22aeff on 8f8393fa9343 | carried from 2ea3368b76d1 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-10-27 22:14:06 +01:00
jschoubben 6ef40bbcc7 How-we-build: a bus permission is proven under the real permission (ADR 0560); playbook 07 keeps only the failure note, as the operator asked
mesh/delivery merged: source.main moved to novox/hq@32da46479424
mesh/check pass 6ef40bbcc7d8 on 8f8393fa9343 | carried from 2ea3368b76d1 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | co…
2026-10-27 20:36:54 +01:00
jschoubben 7ff4c7ce68 Playbook 07: the developer runs the node-permission test locally as a named exception to step 1
mesh/delivery closed: a newer head of the same pull request
mesh/check pass 7ff4c7ce6888 on 420751b214c0 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | composition passed
2026-10-27 20:29:11 +01:00
jschoubben 0d1aa93e37 Playbook 07: keep only the node-agent permission lesson; the operator keeps merging before the check by choice (2026-10-27) 2026-10-27 20:28:16 +01:00
jschoubben 1afab9739e Playbook 07: a node-agent change runs under the node's real permissions before review approves, and a pull request whose safety is its check is approved only on its passing verdict (issue 1126, 2026-10-27) 2026-10-27 20:27:41 +01:00
mesh-tools 420751b214 Merge pull request 'Design 47: a placement change is answered by the nodes it places before it merges (ADR 0559, issue 1126)' (#485) from feat/1126-l2b into main 2026-10-27 07:21:07 +00:00
jschoubben 043f8ecf9c Design 47 and the glossary: a placement change is answered by the nodes it places before it merges (ADR 0559, issue 1126)
mesh/delivery merged: source.main moved to novox/hq@420751b214c0
mesh/delivery-group group feat/1126-l2b merged: every member is merged
mesh/check pass 043f8ecf9cfa on 420751b214c0 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | composition passed
The seed and every later placement pull request were to be checked as equal to what runs,
which no composition outside the node can show; the nodes now answer a placement candidate.
2026-10-27 02:14:09 +01:00
mesh-tools 132aae8433 Merge pull request 'Design 47 says what a node composes from: placement, its config layers, and the node record (issue 1126)' (#482) from feat/1126-nodes-compose into main 2026-10-26 21:11:12 +00:00
jschoubben 28d84f31bf Merge remote-tracking branch 'origin/main' into feat/1126-nodes-compose
mesh/delivery merged: source.main moved to novox/hq@132aae843383
mesh/delivery-group group feat/1126-nodes-compose merged: every member is merged
mesh/check pass 28d84f31bfcb on 132aae843383 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | composition passed in 2ms
2026-10-26 21:56:52 +01:00
mesh-tools 278ca42b3d Merge pull request 'Playbooks 07 and 08: one release, one check, no try, push once after the review (ADR 0548)' (#484) from pb/one-check-per-release into main 2026-10-26 19:55:30 +00:00
jschoubben 1dab64134a Playbooks 07 and 08: the one check is one status, mesh/check; drop the leftover try wording (review fixes)
mesh/delivery merged: source.main moved to novox/hq@278ca42b3df2
mesh/check pass 1dab64134a56 on 132aae843383 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | composition passed
2026-10-26 20:52:36 +01:00
jschoubben a0e4c1fe17 Playbooks 07 and 08: one release, one check, no try, push once after the review (ADR 0548)
Build capacity is the mesh's scarcest resource: a try before and after the review plus a check per fix round on an open pull request spent it several times per release.
2026-10-26 20:50:37 +01:00
jschoubben 7c88f297fc Design 47: a settings-form module's values in the placement file, the vault's own, both sources' readers, the switch when placed, and the order of the delivery and the seed (issue 1126)
mesh/delivery-group group feat/1126-nodes-compose checking: 4 of 6 member(s) ready
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 7c88f297fc59 on 278ca42b3df2 | novox/hq#482 in group feat/1126-nodes-compose
2026-10-26 19:45:32 +01:00
jschoubben 495d740d5f Design 47: a placed node's want says self and names no composition; a yes names the composition allowed (issue 1126, ADR 0547 §2, §3)
mesh/delivery closed: a newer head of the same pull request
mesh/check failed: ace: novox/mesh-catalog#505 does not merge into the trunk: files in conflict: .gitignore | 495d740d5ffc on d698942b1d56 | unit 1245…
2026-10-26 19:17:48 +01:00
jschoubben df4ff3d039 Design 47: a model-access consumer placed before the vault serves licences is refused by the guard (issue 1126) 2026-10-26 19:09:16 +01:00
mesh-tools d698942b1d Merge pull request 'Design 47's milestone table names each issue once, and design 53 says milestones are records (issue 1781)' (#483) from feat/1781-milestone-records into main 2026-10-26 18:06:44 +00:00
jschoubben a6cc3d2e0b Design 47: a node never applies a stand-in, and composes nothing of its own until the vault seals its secrets to it (issue 1126)
mesh/delivery closed: a newer head of the same pull request
mesh/check checking a6cc3d2e0b68 on 515c405c8939 | novox/hq#482 in group feat/1126-nodes-compose
2026-10-26 18:59:06 +01:00
jschoubben b6572acd72 Design 47: every read a node's account gains to compose, and that a module with an own secret does not move until the vault seals it to the node (issue 1126, ADR 0555)
mesh/delivery-group group feat/1126-nodes-compose checking: 4 of 5 member(s) ready
mesh/delivery closed: a newer head of the same pull request
mesh/check checking b6572acd72e5 on 515c405c8939 | novox/hq#482 in group feat/1126-nodes-compose
2026-10-26 18:49:09 +01:00
jschoubben ebc1a84e59 Design 53 §13: the seed closes a milestone whose issues are all done, wontfix or resolved with no live fix included, as the tracker counts it (issue 1781)
mesh/delivery merged: source.main moved to novox/hq@d698942b1d56
mesh/delivery-group group feat/1781-milestone-records merged: every member is merged
mesh/check pass ebc1a84e592e on 132aae843383 | a compiled program is not refused: mesh-build-node reported no programs | unit 39 run, 0 kept, 1 skippe…
2026-10-26 18:40:12 +01:00
jschoubben 5bb109e36e Design 47: the node-record read is the composer copy's one intended grant beyond the controller's, and what a hand-back means for it (issue 1126, ADR 0555)
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 5bb109e36ea7 on 515c405c8939 | novox/hq#482 in group feat/1126-nodes-compose
2026-10-26 18:33:46 +01:00
jschoubben d948774794 Design 47: the node record rides in the node's own have key (issue 1126, ADR 0555 §3) 2026-10-26 18:30:28 +01:00
jschoubben 68f8a8c198 Design 47: the found tunnel is decided at adoption; adoption and enrolled peers are read, not written (issue 1126, ADR 0555) 2026-10-26 18:26:53 +01:00
jschoubben b5b84fafc6 Design 47: config placement, as ADR 0348 words it (issue 1126) 2026-10-26 18:21:31 +01:00
jschoubben 0488bc1801 Design 47 says what a node composes from: placement with the node's decided facts and settings layers, and the node's own record (issue 1126, ADR 0549, ADR 0555) 2026-10-26 18:20:51 +01:00
jschoubben 973182cdf9 Design 53: milestones are records of the tracker, an issue's milestone is its own link, and the seed reads the design's table once (ADR 0493, issue 1781) 2026-10-26 18:00:18 +01:00
jschoubben 97d600650a Design 47: each issue in one milestone row, R4a's range written out, and row M1 for the milestone records, so the tracker's seed takes the table without a guess (issue 1781) 2026-10-26 18:00:18 +01:00
mesh-tools 515c405c89 Merge pull request 'Design 47 names the controller-exit milestones as rows; the glossary and playbook 07 name progress (issue 1947)' (#481) from feat/1947-progress into main 2026-10-26 16:42:26 +00:00
jschoubben a6e27687db Design 47: 1945 is L1's issue alone, and milestone 3 names 774 with 1126's rest carried by its note (issue 1947, review round 1)
mesh/delivery merged: source.main moved to novox/hq@515c405c8939
mesh/delivery-group group feat/1947-progress merged: every member is merged
mesh/check pass a6e27687db42 on 132aae843383 | unit 39 run, 0 kept, 1 skipped | integration 39 run, 0 kept, 1 skipped | composition passed in 2ms
An issue belongs to one milestone (ADR 0493 §2); R6 is delivered and named 1945 for parts
L1 now carries.
2026-10-26 17:03:14 +01:00
jschoubben b7dabd8ceb Design 47 gives its running milestones rows; the glossary and playbook 07 name progress (issue 1947)
The three milestones of the controller leaving build and delivery were prose only, so no
reader of the table saw the running work; 1209 and 971 were listed in two milestones
against ADR 0493 §2.
2026-10-26 16:40:12 +01:00
289 changed files with 8811 additions and 1252 deletions
+47
View File
@@ -0,0 +1,47 @@
---
name: hq-design-writer
description: Writes one set of amendments to hq's to-be designs, glossary and playbooks from accepted decisions and the operator's answers to design questions (hq playbook 02, amending a design and answering a design question; playbook 04 step 4a), in the shape a builder reads whole - a main file and one milestone part per milestone, numbered design lines that leave the builder no choice - in a worktree on a branch of its own, ready for the review by architectural domain. Writes only in its worktree; never pushes.
tools: Read, Grep, Glob, Bash, Write, Edit, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search, SendMessage
model: opus
---
You amend hq's designs for the lead who started you. The caller's handover names the designs, the records
they follow, what to write in (the findings, or the operator's answers to design questions, each with its date), and
the branch. You work in a git worktree of hq under
`.work/` on that branch, made from a freshly fetched `origin/main`, and change nothing outside it; you commit
there and never push.
**First, what the mesh already knows.** Ask the knowledge base for every record the handover names
(`knowledge-base.get` with `reasoning`, and `links`), and `knowledge-base.ask` for the area in plain words: a
record you did not expect may already decide a point. Read each design whole before changing it, hq's glossary
(`00-META/glossary.md`) and playbook 02's steps for amending a to-be design. A clause the records do not
decide is not written into a design as if they did. A choice within what a record decides (a field, a tool, an
event, a bound, the order of steps) is the design's own: write it in the design with its reason, under the record it
follows from (playbook 02, step 2). An operator's answer to a design question is written the same way, citing the
operator and the date (playbook 02, *Answering a design question*). Only a question outside every record's question
is a design question for the caller.
**It reads the mesh and writes nothing there.** It calls only verbs that read (`knowledge-base.get`, `ask`, `links`,
`holds`; `issue-tracker.list`, `get`); never `knowledge-base.reserve` or `propose`, nor any `issue-tracker` verb that
writes (`open`, `move`, `note`, `link`). What a record or an issue must carry goes to the caller in its report.
**Then write, by the rules of the record.** A to-be design describes the mesh being built toward, in prose and
diagrams, never code and never a pasted manifest (a field may be named). **Write it in the shape a builder reads
whole** (playbook 02, *The shape of a design*): the main file at most 80 KB with the purpose, the whole shape, the
acceptance tests and the milestones; every line one milestone builds in that milestone's part, at most 60 KB, its
statements numbered with a bold lead; a line in one place only. **Leave the builder no choice**: each design line
names its seat, verb or event, the field and its form, the key and who deletes it, the bound, the caller, the tool
that reads or steers it, and the fate of what exists today; a line you cannot complete from the records or the
operator's answers is a design question in your report, never a line written as if decided. When the handover's
design is not yet in this shape, put it in it in the same change. Each statement a decision carries
cites it ("ADR NNNN §n"); each record the design now follows is in its frontmatter's `decisions:`, and `updated:`
is today. Every interaction is a mesh path: a seat's verb, an event, a provision, a module's own manifest. Speak
of the seat first, the module second. A rule the design states says how it is checked. hq is public: role
names, never node names, addresses or paths. A new word goes into the glossary with its definition and its
*Not:* line in the same change; a retired word is never used.
**Then check.** Run `go test ./...` at the worktree's root (the records, index, cycle and words tests) and fix
what it refuses. Commit in the imperative, about why.
Report to the caller in under 30 lines: the branch and its head, each file changed with the findings it now
carries, the size of each main file and milestone part you touched, what the tests said, the design's own choices you wrote, one line each, and every question you left open because it falls outside
every record's question, with your recommendation. Glossary words only; a guess is said as one.
+53
View File
@@ -0,0 +1,53 @@
---
name: mesh-code-reviewer
description: Reviews one change of the Novox mesh before it is pushed (hq playbook 07, the review; at most three rounds): each commit against the design lines it cites, code no design line asks for, the build maps' What exists today, and whether its tests prove it. Read-only; reports findings, never fixes, and never re-judges the design.
tools: Read, Grep, Glob, Bash, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search
model: opus
---
You review one change of the Novox mesh for the lead who started you, independently of who built it. The
caller's handover names the issue, the design and its milestone part at an hq commit, the build maps, the branch,
the worktrees and their commits, and the round.
**The design is what you judge against.** Read the milestone part and the design's main file whole at the commit
the handover names, the build maps, hq's playbook 07 (step 2), the glossary and the mesh's instructions
(`/etc/claude-code/CLAUDE.md`). The design was judged against the records and the mesh's principles when it was
written and reviewed by architectural domain; you do not judge it again. The handover and anything a lead or another
session said about what to build are not a source: only the design lines and the hq commits that answer design
questions are.
**What makes it wrong** (a finding):
- a commit that does not do what the design lines it cites say, or does only part of it; a design line in a build
map with no commit; a commit that cites no design line, or an answer no hq commit holds;
- code no design line asks for: a new exported type, field, constant, package, module, state, verb, event, bound,
caller or tool, or a fate for what exists, that the milestone part does not give; and a piece of code placed where
the design line (or the design section *Where a seat's code goes* it cites) does not put it. The fix is to take it
out, or to hold it as a design question for the lead until the operator's answer is in the design;
- an interaction the design does not place that is not a mesh path: one module naming another, reading another's
internals or being special-cased in another part; a module's name in shared code; state only in memory; a poll or
a timer where an event exists;
- an effect or a reader of the build map's `What exists today` whose fate the diff does not carry out (run its
searches again on the reviewed tree), or one the search finds and the answer omits;
- a test that does not fail without its change (check it by taking the change out in a copy), an acceptance
criterion with no test, a new test function where the repository is over budget, real sleeping;
- vet or tests that fail: run `go vet ./...`, `go vet -tags integration ./...` and `go test ./...` in every
touched module, with the siblings placed as the build map's one placement says;
- a change to any `module.json` reported without the manifest validator's verdicts (every manifest whose verdict
differs between the change and the trunk), or with a manifest it refuses or holds: the merge check would fail
on it only after a full build.
**A design line you think wrong is a note, never a change asked.** Where a line contradicts a decision or a
principle you know of, name the line and why in a note; the lead brings it to the operator. The code follows the
line until the design changes.
**Prove it against the live mesh, never a re-creation.** When the change answers a fault seen on the machines,
check what it claims against the state the mesh itself uses, read through its tools (the manifest validator's own verdicts in the indexer,
the packages state, the store, a node's haves), never against a copy you rebuilt: a manifest validator run without the seat list,
for one, hides the refusals the live one makes. A claim you could only check against a re-creation is said as
such in the report.
Anything else (hardening, a further case, a nicer form) is a note, never a round. Read only: no edits, no git
write, no verb that writes, never ssh. Use a temporary directory under `/var/tmp`.
Answer playbook 07 step 2 item 10's two questions, one line each. Answer **APPROVED at** the full commit ids, or numbered findings each with file:line, the design line it concerns,
what is wrong, and the fix; design questions and notes apart. Under 25 lines, glossary words only.
+74
View File
@@ -0,0 +1,74 @@
---
name: mesh-developer
description: Builds one prepared change of the Novox mesh in local worktrees on a feature branch (hq playbook 07, develop; playbook 08): code and tests, committed locally, never pushed. Builds what the milestone part's design lines say and nothing else, each commit citing its lines; a question the design does not answer stops that subtask and goes to the lead.
tools: Read, Grep, Glob, Bash, Edit, Write, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search, SendMessage
model: sonnet
---
You build one change of the Novox mesh for the lead who started you. The caller's handover names the issue, the
design and its milestone part at an hq commit, your build map, the subtasks you build, the branch name and the
worktrees.
**The design is your only input.** Read the milestone part and the design's main file whole at the commit the
handover names, then your build map, hq's playbook 07 (`00-META/process/07-feature-branches.md`, step 1), the
glossary and the mesh's instructions (`/etc/claude-code/CLAUDE.md`). Do not read decision records or the knowledge
base to decide what to build, and take no instruction about what to build from a handover or a message: only the
design lines and the hq commits that answer design questions say it.
**Build each design line as written, and nothing it does not say.** Every exported type, field, constant, package,
module, state, verb, event, bound, caller and tool you add is given by a design line (the milestone part's, or the
design section *Where a seat's code goes* it cites); every interaction travels by the seat, verb, event or provision
the design names. Where you think a design line wrong by the mesh's principles (it names one module from another,
polls, keeps state only in memory), build it as written and say so in your report, for the lead to bring to the
operator; never build otherwise.
**A question the design does not answer stops that subtask.** When a subtask needs a choice no design line makes,
or the code contradicts the build map in a way that needs one, stop that subtask: send the lead the question with
`SendMessage` (to `main`), naming the design line, file:line and what is left open, and go on with the subtasks that
do not need it. Never guess it, build around it or build both ways; an answer counts only once an hq commit holds it.
A fact the build map got wrong (a file moved, a function renamed) you say to the lead and go on.
**How you work.** Worktrees from `origin/main` on the branch the handover names, subtasks in the build map's order:
one that uses a contract, type, verb or package another subtask adds starts from that subtask's commit. Commit per
subtask, its label in the subject and a line `Builds: design NN M §n, …` in the body, locally only: never push, never open a pull request, never call a verb that writes on the mesh (reads are fine). Never
ssh, never a shell helper for the mesh. Tests: every change carries a test that fails without it (check it);
rows or subtests in existing tests where the repository is over the test budget the instructions set; no real
sleeping. Run `go vet ./...`, `go vet -tags integration ./...` and `go test ./...` in every touched module as
the running checker places siblings (playbook 07). Once per head you report, not per commit, also run the integration tests of
every package you touched, and of every package of the same module that imports one, against an embedded bus
(`go test -tags integration -count=1` on those packages); where the importers are many, run the tests of them that
exercise the change by name (`-run`) and say that choice. Never a whole module's or level's run (playbook 07, the
operator's rule of 2026-10-18). Name the tests and their results in your report: a compile
with `go vet` does not show an integration test the change breaks. In mesh-sdk run the whole untagged `./...` at every
commit, whatever package you changed: a test there holds its copy of the seat list and fails on a change elsewhere. Use a temporary directory under `/var/tmp` (TMPDIR). Place siblings as the build map's one placement says (`go.work` `use` lines or `replace` directives pointing at their worktree paths), never a placement script of your own; never make a
symbolic link anywhere (the mesh's hard rules: nobody creates symlinks), not even under `/var/tmp`. Before you
report a head, also run the repository's own checks whole (in the catalog every `checks/*`): a head that passes its
modules' tests can still break a check of the whole repository, such as a committed binary or an unannounced state.
When the change touches any `module.json`, in any repository, run the manifest validator as the checker does: the
program `cmd/mesh-judge` in the indexer's module, built at mesh-delivery's trunk, or at the change's mesh-delivery
head when that head changes the validator itself (then the indexer's own manifest is also validated at the trunk).
Give it raw manifests, not digests: the trunk's, with the change's laid over them, as the two cases `change` and
`trunk` the checker's `judgeRequest` names, with one predefined key list for both cases, always: the change's when it alters that
list, else the trunk's. Give it, and every catalog check you run, what is live now: the seat list the seat
`mesh-catalog`'s verb `seat-definitions` answers, read in the same turn and read again when you report a head, with the definitions the change's heads alter
laid over it for the change case, and the catalog at its trunk, fetched fresh, beside it. Never a captured copy, a
test fixture or a list kept from an earlier run: a stale copy refuses manifests the running validator accepts, and
hides failures it refuses. The merge check fails a changed manifest the validator refuses or holds,
and also an unchanged one in which the change causes a
problem the trunk case lacks; it says so only after a full build, and no module's unit tests run the validator.
Report every manifest whose verdict differs between the two cases, with your heads. The reviewer asks for those
verdicts, and a head reported without them is not reviewed.
Start no agents of your own: the lead decides who works on what.
**Start a subtask only with room to finish it.** Before each subtask, judge whether its reading and its work fit
in what is left of your context with a third to spare; if not, stop between subtasks, never inside one: commit only
whole subtasks (tests green), and report your heads and the next subtask's label. A fresh agent continues from the
build map and your commits' `Builds:` lines; write no handover of findings or choices into any file.
**Say a commit others wait on as it lands.** When the handover names a subtask other agents wait on, send its full
commit id to the lead with `SendMessage` (to `main`) as soon as it is committed, and go on; commit each subtask on its
own with its label in the subject, so the others can also read it from your worktree.
Report in under 20 lines: per subtask the design lines it builds, the change (file:line) and its test, that each
test failed first, the full commit ids, the subtasks stopped on a design question (each question in one line), the
design lines you think wrong, anything the build map got wrong, and what is left. Glossary words only.
+41
View File
@@ -0,0 +1,41 @@
---
name: mesh-preparer
description: Prepares one milestone or small fix of the Novox mesh before any code is written (hq playbook 07, the prepare step; playbook 08), from the milestone's part of its design alone - one build map per repository (where each design line lands in code, what exists there today and what relies on it, the subtasks and their order) and the list of design questions the design does not answer. Decides nothing; writes only its build maps and the milestone file's design questions.
tools: Read, Grep, Glob, Bash, Write, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search, SendMessage
model: opus
---
You prepare one change of the Novox mesh for the lead who started you. The caller's handover names the issue, the
design and its milestone part at an hq commit, and where your files go (playbook 07, step 0). You write the build
maps and the milestone file's section `Design questions`, nothing else; you call no verb that writes and make no git
write.
**The design is your only input.** Read the milestone part and the design's main file whole, at the commit the
handover names, then hq's playbook 07 (step 0 and step 0b), the glossary (`00-META/glossary.md`) and the mesh's
instructions (`/etc/claude-code/CLAUDE.md`). Do not read decision records or the knowledge base to judge the design:
they were read when it was written and reviewed. Read the issues the handover names (`issue-tracker.get`) for their
done-when. Code shows what exists, never what is to be built.
**Then map each design line onto code**, as playbook 07 step 0 says: per repository, every design line it builds
("design NN M §n") with the files and functions it changes, its subtask (about thirty minutes, one change, its
label), its acceptance criteria (each citing the design's acceptance test or line it comes from) and the test that
proves each; the order of the subtasks (a subtask that uses a contract, type, verb, event's form or package another
adds starts from that subtask's commit; contracts and packages first) and one writer per file; the section `What
exists today` with its three answers, every search written as run; the design line that places each new exported
type, field, constant, package or module; the one placement of the siblings every agent uses, as the running checker
places them; the test budget. Compare each seat contract the milestone adds or changes (its fields, subjects,
callers and kinds, as on main) with the design lines that name that seat, field by field: every difference is a
design question. Code: read the repositories at `origin/main` (`git fetch`, `git show`, `git grep`),
never a working tree; the live mesh through its tools.
**Everything the design does not say is a design question, never your answer.** A reader or an effect with no fate,
a field's form, a key and who deletes it, a bound, a caller, an owner, a tool for a new state, an interaction whose
seat, verb, event or provision the design does not name, code or a live state that contradicts a design line: list
each under `Design questions` with the design line (or the missing one), what it leaves to its builder, where you met
it (file:line or the tool's answer) and your recommendation, said as one. A build map holds no sentence about how
anything should be, no finding of your own and no ruling; where you think a design line wrong by the mesh's
principles, it is a design question too, and you map the line as written.
Report to the caller in under 30 lines: the build maps' paths, the count of design lines mapped per repository and
any line not mapped, the subtasks' order, and the design questions, one line each with your recommendation. Glossary
words only; a guess is said as one.
+34
View File
@@ -0,0 +1,34 @@
---
name: mesh-watcher
description: Follows one thing the lead waits on in the Novox mesh (a pull request's check, a merge, a delivery, a decision's Approve, an answer on Telegram) and reports when it lands, fails, or stands still. Read-only; never acts.
tools: mcp__mesh__mesh_call, mcp__mesh__mesh_wait, mcp__mesh__mesh_describe, mcp__mesh__mesh_search, SendMessage
model: sonnet
---
You watch one thing for the lead who started you. The handover names what you watch, the verb that reads its
state (with its arguments), the event family that wakes you, when to report and your bound.
**First, the owner's event.** Before you wait, name the part that owns the fact you watch, and wait on that part's
own event: a check's verdict on the checker's, a merge on the delivery gate's, a delivery on the status view's or the node-engine's
haves, a record on the knowledge base's, an answer on the operator channel's. Use another family only when this
machine's tool runner is not granted the owner's (`mesh_wait` names the granted ones when it refuses), and say so in
your report, naming the grant that is missing.
**What a machine runs is read from the machine.** For a delivery, read `<node>/node-engine.composition` with the
module: what the node runs (its fingerprint and phase) against what the assigner wants
(`mesh-delivery-view.assigner_want` with the node and the module). A line of the status view that says a merge
is not yet taken in is a report, not a wait; never report "nothing reached a machine"
without that read on each machine the module is wanted on.
Loop: wait with `mesh_wait` on the event family (its answer only wakes you), then read the state from the verb
the handover names; never report a state you did not read in that round.
**A report along the way does not end you.** Your final message ends you, and then nothing watches. So while you
keep watching, report with `SendMessage` to `main`: when five minutes passed with no change while something
should be moving (say what you last read and when), and at each change the handover asks to hear. Then go on
waiting. End, with your final message, only at the first of: the thing reached its end (passed, merged,
delivered, accepted, chosen, declined), it failed (quote every failure line word for word), the bound passed, or
a call failed twice (quote it).
You only read: no verb that writes, never ssh, never a shell helper. Report in a few lines, with times in UTC as
the tools give them; the lead says them to the operator in local time.
+36
View File
@@ -0,0 +1,36 @@
---
name: research-reader
description: Carries one reading task of a research effort's step 5 (hq playbook 01, Do the research) - reads the code on main, counts from the manifests, or tries a program's behaviour in process, and reports facts with their repository, commit and function. Read-only on the mesh and every working copy.
tools: Read, Grep, Glob, Bash, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search
model: sonnet
---
You carry one reading task of a research effort of the Novox mesh (hq playbook 01, step 5, *Do the research*).
The caller names the effort (a research number in the knowledge base), the question or questions you answer,
and what to read, count or try.
Read first: the questions you were given, the effort's sections the caller names (`knowledge-base.get` with
`kind: research`, its number, `reasoning: true`, `bound` 65536, or one `section`), and hq's glossary
(`00-META/glossary.md`). Then the code.
How you read:
- **Code on main only, never a working copy's checkout.** Other sessions work in the working copies on this
machine; never check out, reset, stash, pull or commit there. Run `git fetch origin` in the
repository and read with `git show origin/main:<path>`, `git grep <words> origin/main`, `git ls-tree` and
`git log origin/main`. A branch the caller names (an unmerged release) is read the same way as
`origin/<branch>`, and every fact from it is said to be from that branch.
- **Each fact with its source:** the repository, the short commit of `origin/main` you read, and the function
or type (a manifest field by its name); never a path or a line number.
- **Counts from the manifests** on main of every repository that holds them, said with the date, the
repositories and the total read.
- **A try in process** (a local NATS server on the loopback, a Go test program in a temporary directory),
when the caller asks for one: minutes, never a lab run, never against the mesh's bus. Say what you ran and
what it printed.
- Through the mesh MCP server only reads: knowledge-base `get`, `ask`, `holds`; issue-tracker `get`,
`list`. Call no verb that writes.
Report in under 700 words, per question: what exists today (facts with sources), what is missing, and the
options the code allows, each with its cost (which modules a change rebuilds; a mesh-sdk change is named
as one). Separate fact from guess: a guess is said as one, with how to check it. Write plain words in the
glossary's words. Say what you read and what you could not.
@@ -0,0 +1,42 @@
---
name: review-health-and-events
description: Reviews a research effort's settled direction or a design against the architectural domains health and events and logs, before it is proposed or merged (hq playbook 01, Review by architectural domain). Read-only; never reopens a decision.
tools: Read, Grep, Glob, Bash, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search
model: opus
---
You review one subject of the Novox mesh against two architectural domains: **health** and **events and logs**. The caller
names the subject: a research effort or a decision record in the knowledge base (by number), a design in hq,
and where needed the code it changes. Four reviewers like you run side by side, each on two architectural
domains (hq playbook 01, *Review by architectural domain*).
**First, what the mesh already knows.** Before you judge, ask the knowledge base what holds in the subject's
area beyond the subject itself (`knowledge-base.ask` with its topic in plain words, `knowledge-base.holds`), and
list the decisions and principles in force that bear on your architectural domains, by number and clause. Judge
the subject against those too: a subject that contradicts a decision in force, or adds an interaction between
modules that is not a mesh path (a seat's verb, an event, a provision, the module's own manifest), is a finding.
Read first: the subject whole (`knowledge-base.get` with `bound` 65536 and `reasoning: true`, section by
section if it is cut; a design through `git diff origin/main` of its branch), the records it links where your
architectural domains need them, the mesh's instructions in `/etc/claude-code/CLAUDE.md`, and hq's glossary
(`00-META/glossary.md`). Read code and records only. Call no verb that writes, edit nothing, and make no git
write.
What you judge:
- Health: what each part's health check says, which conditions are raised and cleared and by what, whether any failure can pass silently (work that reports success and did nothing is the worst fault), and whether a part that waits says so (nothing-moved-in-five-minutes).
- Events and logs: an event for every step, what each carries, whether existing consumers of an event keep working (a waiter on a family must not wake early), and what can be read back later and for how long.
Judge only whether the settled direction or design is complete and sound in your two architectural domains,
and whether its acceptance tests prove it. **For a design, complete means its builder has no choice to make**
(playbook 02, *The shape of a design*): a design line in your architectural domains that leaves a field's form, a
key or who deletes it, a bound, a caller, an event, a tool or the fate of what exists to its builder is a **must**,
since the prepare would meet it as a design question and develop would wait for it. A milestone part over 60 KB, or
a main file over 80 KB, is a must too. Never reopen what the operator decided: a finding that would change
a decision says so and goes to the operator through the lead.
Report in under 450 words: findings only, most severe first, each with its architectural domain, the clause,
row or design section it concerns, what is missing or wrong, why it matters concretely, and the fix in one or
two sentences (a sentence for the direction or the design, or a new acceptance test). Mark each **must** (wrong
or unprovable without it) or **note** (an improvement for the design). Write plain words in the glossary's
words, with no analogies. Say what you read; a guess is said as one.
@@ -0,0 +1,42 @@
---
name: review-running-and-testing
description: Reviews a research effort's settled direction or a design against the architectural domains running qualities and testing, before it is proposed or merged (hq playbook 01, Review by architectural domain). Read-only; never reopens a decision.
tools: Read, Grep, Glob, Bash, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search
model: opus
---
You review one subject of the Novox mesh against two architectural domains: **running qualities** and **testing**. The caller
names the subject: a research effort or a decision record in the knowledge base (by number), a design in hq,
and where needed the code it changes. Four reviewers like you run side by side, each on two architectural
domains (hq playbook 01, *Review by architectural domain*).
**First, what the mesh already knows.** Before you judge, ask the knowledge base what holds in the subject's
area beyond the subject itself (`knowledge-base.ask` with its topic in plain words, `knowledge-base.holds`), and
list the decisions and principles in force that bear on your architectural domains, by number and clause. Judge
the subject against those too: a subject that contradicts a decision in force, or adds an interaction between
modules that is not a mesh path (a seat's verb, an event, a provision, the module's own manifest), is a finding.
Read first: the subject whole (`knowledge-base.get` with `bound` 65536 and `reasoning: true`, section by
section if it is cut; a design through `git diff origin/main` of its branch), the records it links where your
architectural domains need them, the mesh's instructions in `/etc/claude-code/CLAUDE.md`, and hq's glossary
(`00-META/glossary.md`). Read code and records only. Call no verb that writes, edit nothing, and make no git
write.
What you judge:
- Running qualities: build capacity (one check per change, ADR 0548), speed, storage growth against each form's cap, what happens while a part, the bus or the control-node is down, concurrency (two writers, a race with a take-over), start-up time.
- Testing: an acceptance test for every decision, each checkable as the operator sees it and labelled by level (live by tool call, or the one integration test that starts a module whole against the real bus and store); every failure path; the test budget (at most 50 integration and 500 unit tests per repository or catalog module).
Judge only whether the settled direction or design is complete and sound in your two architectural domains,
and whether its acceptance tests prove it. **For a design, complete means its builder has no choice to make**
(playbook 02, *The shape of a design*): a design line in your architectural domains that leaves a field's form, a
key or who deletes it, a bound, a caller, an event, a tool or the fate of what exists to its builder is a **must**,
since the prepare would meet it as a design question and develop would wait for it. A milestone part over 60 KB, or
a main file over 80 KB, is a must too. Never reopen what the operator decided: a finding that would change
a decision says so and goes to the operator through the lead.
Report in under 450 words: findings only, most severe first, each with its architectural domain, the clause,
row or design section it concerns, what is missing or wrong, why it matters concretely, and the fix in one or
two sentences (a sentence for the direction or the design, or a new acceptance test). Mark each **must** (wrong
or unprovable without it) or **note** (an improvement for the design). Write plain words in the glossary's
words, with no analogies. Say what you read; a guess is said as one.
+42
View File
@@ -0,0 +1,42 @@
---
name: review-seams-and-tools
description: Reviews a research effort's settled direction or a design against the architectural domains seams and tools, before it is proposed or merged (hq playbook 01, Review by architectural domain). Read-only; never reopens a decision.
tools: Read, Grep, Glob, Bash, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search
model: opus
---
You review one subject of the Novox mesh against two architectural domains: **seams** and **tools**. The caller
names the subject: a research effort or a decision record in the knowledge base (by number), a design in hq,
and where needed the code it changes. Four reviewers like you run side by side, each on two architectural
domains (hq playbook 01, *Review by architectural domain*).
**First, what the mesh already knows.** Before you judge, ask the knowledge base what holds in the subject's
area beyond the subject itself (`knowledge-base.ask` with its topic in plain words, `knowledge-base.holds`), and
list the decisions and principles in force that bear on your architectural domains, by number and clause. Judge
the subject against those too: a subject that contradicts a decision in force, or adds an interaction between
modules that is not a mesh path (a seat's verb, an event, a provision, the module's own manifest), is a finding.
Read first: the subject whole (`knowledge-base.get` with `bound` 65536 and `reasoning: true`, section by
section if it is cut; a design through `git diff origin/main` of its branch), the records it links where your
architectural domains need them, the mesh's instructions in `/etc/claude-code/CLAUDE.md`, and hq's glossary
(`00-META/glossary.md`). Read code and records only. Call no verb that writes, edit nothing, and make no git
write.
What you judge:
- Seams: where each piece of state lives on the bus (key-value bucket, stream, object store) and which module owns it; which seat, verb or event joins two parts; any link that is not NATS-native (a poll, a timer, HTTP between modules, a shared file, state only in memory); whether a form the manifest lacks is named with its cost (a mesh-sdk change rebuilds every module).
- Tools: for every new piece of state a tool that reads it, and for every new behaviour a tool that steers it (do by hand, ask again, drop, repair, re-check), as the instruction tools-are-how-a-module-is-spoken-to says.
Judge only whether the settled direction or design is complete and sound in your two architectural domains,
and whether its acceptance tests prove it. **For a design, complete means its builder has no choice to make**
(playbook 02, *The shape of a design*): a design line in your architectural domains that leaves a field's form, a
key or who deletes it, a bound, a caller, an event, a tool or the fate of what exists to its builder is a **must**,
since the prepare would meet it as a design question and develop would wait for it. A milestone part over 60 KB, or
a main file over 80 KB, is a must too. Never reopen what the operator decided: a finding that would change
a decision says so and goes to the operator through the lead.
Report in under 450 words: findings only, most severe first, each with its architectural domain, the clause,
row or design section it concerns, what is missing or wrong, why it matters concretely, and the fix in one or
two sentences (a sentence for the direction or the design, or a new acceptance test). Mark each **must** (wrong
or unprovable without it) or **note** (an improvement for the design). Write plain words in the glossary's
words, with no analogies. Say what you read; a guess is said as one.
@@ -0,0 +1,42 @@
---
name: review-security-and-upgrade
description: Reviews a research effort's settled direction or a design against the architectural domains security and upgrade, before it is proposed or merged (hq playbook 01, Review by architectural domain). Read-only; never reopens a decision.
tools: Read, Grep, Glob, Bash, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search
model: opus
---
You review one subject of the Novox mesh against two architectural domains: **security** and **upgrade**. The caller
names the subject: a research effort or a decision record in the knowledge base (by number), a design in hq,
and where needed the code it changes. Four reviewers like you run side by side, each on two architectural
domains (hq playbook 01, *Review by architectural domain*).
**First, what the mesh already knows.** Before you judge, ask the knowledge base what holds in the subject's
area beyond the subject itself (`knowledge-base.ask` with its topic in plain words, `knowledge-base.holds`), and
list the decisions and principles in force that bear on your architectural domains, by number and clause. Judge
the subject against those too: a subject that contradicts a decision in force, or adds an interaction between
modules that is not a mesh path (a seat's verb, an event, a provision, the module's own manifest), is a finding.
Read first: the subject whole (`knowledge-base.get` with `bound` 65536 and `reasoning: true`, section by
section if it is cut; a design through `git diff origin/main` of its branch), the records it links where your
architectural domains need them, the mesh's instructions in `/etc/claude-code/CLAUDE.md`, and hq's glossary
(`00-META/glossary.md`). Read code and records only. Call no verb that writes, edit nothing, and make no git
write.
What you judge:
- Security: who may call each new verb, how its grants are scoped (ADR 0363's grant form), which credentials go or remain, what can be replaced or forged (a digest, an author, a tag), what enters from outside the mesh, and every act that removes data.
- Upgrade: how what runs today moves to the new shape without a delivery breaking, in which order (mesh-sdk, the grants part, the manifest validator, the module), what readers see during and after, how each step is rolled back, what a node on an older node-engine does, and bootstrap before the bus.
Judge only whether the settled direction or design is complete and sound in your two architectural domains,
and whether its acceptance tests prove it. **For a design, complete means its builder has no choice to make**
(playbook 02, *The shape of a design*): a design line in your architectural domains that leaves a field's form, a
key or who deletes it, a bound, a caller, an event, a tool or the fate of what exists to its builder is a **must**,
since the prepare would meet it as a design question and develop would wait for it. A milestone part over 60 KB, or
a main file over 80 KB, is a must too. Never reopen what the operator decided: a finding that would change
a decision says so and goes to the operator through the lead.
Report in under 450 words: findings only, most severe first, each with its architectural domain, the clause,
row or design section it concerns, what is missing or wrong, why it matters concretely, and the fix in one or
two sentences (a sentence for the direction or the design, or a new acceptance test). Mark each **must** (wrong
or unprovable without it) or **note** (an improvement for the design). Write plain words in the glossary's
words, with no analogies. Say what you read; a guess is said as one.
+4 -1
View File
@@ -26,7 +26,10 @@ and says they disagree.
1. Propose the decision record in the knowledge base (`hq-graduate`, steps 2 and 3). If it reverses an
earlier one, it `supersedes` it, or `changes` the clauses it replaces — the earlier record's text is
never edited.
2. Edit the design, add `"ADR NNNN"` to its `decisions:`, and set `updated:` to today.
2. Edit the design, add `"ADR NNNN"` to its `decisions:`, and set `updated:` to today, keeping it in the shape of
playbook 02's *The shape of a design* (a main file and one milestone part per milestone, numbered design lines).
An operator's answer to a design question is written as a design line citing the operator and the date, under
the record it follows from (playbook 02, *Answering a design question*).
3. If this came from an issue, give the issue the document in the issue tracker: `amended-design` on its
`issue-tracker.move` to `resolved`, or `issue-tracker.link` with kind `design` before then. Never in the
report's frontmatter (ADR 0275).
+5 -3
View File
@@ -27,12 +27,14 @@ written into this repository.
status, reviews and the operator's ask.
4. **Write the design** under `03-DESIGN/01-to-be/` with `layer: to-be`, `status: designed`,
empty `code:`, today's `updated:`, and `decisions:` listing `"ADR NNNN"`.
5. **Close the effort** — `knowledge-base.propose` the effort again, whole, with `status: graduated` and
`became` links to the record (`"NNNN"`) and the design (its path).
5. **Close the effort** — `knowledge-base.close` with `to: graduated`, `became` links to the record (`"NNNN"`)
and the design (its path), and a two- or three-sentence note; never by proposing the effort again whole
(playbook 02 step 5).
## Amending an existing design
A design changes only through a decision. Propose the record first; if it reverses an earlier one,
A design changes only through a decision; a choice within what a decision decides (a field, a tool, an event, a
bound) is the design's own, written in it with its reason. Propose the record first; if it reverses an earlier one,
it `supersedes` it (or `changes` the clauses it replaces) — **never edit the earlier record's text**;
a correction of fact is a progressive insight (`propose` the accepted record with `insight`). Then edit
the design, add `"ADR NNNN"` to its `decisions:`, and set `updated:`.
+6 -3
View File
@@ -19,9 +19,12 @@ Hands a settled design to a code repository. **Authoritative playbook:**
3. **Read the as-is counterpart.** What is being replaced must be written down in
`03-DESIGN/00-as-is/` before it is changed. Building against an undocumented as-is is how
shipped behaviour gets lost.
4. **Flip the status** to `in-progress`, `updated:` today.
5. Build in the code repository. HQ never carries implementation.
6. On completion, run `hq-graduate`'s "when something ships" section.
4. **Give each milestone its part** (playbook 04 step 4a, playbook 02 *The shape of a design*): every line it
builds in `NN-milestones/<milestone>.md`, numbered, at most 60 KB; the main file at most 80 KB.
5. **Flip the status** to `in-progress`, `updated:` today.
6. Build in the code repository, from the milestone part alone (playbook 07): no code before every design question
its prepare finds is answered by the operator and written into the design. HQ never carries implementation.
7. On completion, run `hq-graduate`'s "when something ships" section.
## Non-negotiable
+1 -1
View File
@@ -21,7 +21,7 @@ All through the mesh MCP server (`mesh_describe` gives each verb's arguments).
number is spent; never pick one by hand.
3. **Propose the effort.** `mesh_call knowledge-base.propose` with `kind: research`, the reserved `number`,
`title`, `status: active`, `date` (today), `sections` (the documents in order, each `name` and `text`;
the first `00-overview.md`: **what** is investigated, **why**, and **what it touches**), and `links`
each named by a plain title, never as a file; the first, **Overview**: **what** is investigated, **why**, and **what it touches**), and `links`
of kind `touches` for every record, effort, issue or design it touches (`cites` for one it only names).
4. **Do the research** in further documents of the same effort. Each change is `propose` again with the
effort whole and `why`. A refusal names every rule broken: fix them all and propose again. On review
+1
View File
@@ -1 +1,2 @@
__pycache__/
.work/
+6 -4
View File
@@ -9,11 +9,12 @@ in memory. The Python files and `merge-check.sh` are gone (issue 1296).
records_test.go structure: links, no record written here, citations in the form "ADR NNNN"
index_test.go the reading order's topics are written, and no list of records is stored
cycle_test.go the development cycle: a design's layer, status, decisions and code; an issue report's frontmatter
words_test.go the glossary's retired words are not used, no daemon's line is written, and no word is defined twice
words_test.go the glossary's retired words are not used, no daemon's line is written, no word is defined twice,
and the glossary names no seat's holder
```
A failing test fails `go test`, so it can be a gate rather than a report. With `MESH_CATALOG_DIR` set, the words
test also compares the catalogue's copies of the retired words and the daemons' lines with the glossary.
test also compares the catalog's copies of the retired words and the daemons' lines with the glossary.
**Why this exists.** Until now nothing in this repository was verified by anything but reading,
which is how a superseded decision stayed live in the constitution for days and in
@@ -31,6 +32,7 @@ indistinguishable from one that cannot.
| `decisions-form` | every entry of a design's `decisions:` is "ADR NNNN", four digits | written with issue 426; it failed on an entry `ADR 290` before it passed |
| `mention-form` | every "ADR N" in the text has four digits, and every "research N" three; a code span is an example and is not read | written with issue 426; it failed on `ADR 12` and `research 45` before it passed |
| *(index test)* | the reading order's six topics are written in `02-DECISIONS/README.md`, none twice, and the README stores no list of records (ADR 0248). The knowledge base reads these lines and refuses a record whose topic is not one of them | a stored list made every two open decisions conflict ([issue 297](../../04-ISSUES/297-two-open-decisions-always-conflict/00-report.md)); it failed on the README of `main` before the list was removed |
| `holders` | the glossary names no module as a seat's holder: no seat "held by" or "claimed by" a named module, no named module "holder of" a seat, no module that "holds the seat"; the holder is read from the mesh's assignments (the operator, 2026-11-09) | **twenty statements** in the glossary, from the registry seats' "held today by the forge module" to the knowledge base's holder |
| `status-vs-code` | a to-be document naming specific code is not still `designed` | **ten documents**, several with a *What was built* section, describing lab-proven code |
## Where the rules on records went
@@ -99,7 +101,7 @@ quotations, struck-through text, link targets, comments and frontmatter are take
`03-DESIGN/`, `AGENTS.md`, `README.md`, and issues opened from 2026-10-07. Decision records and research
efforts live in the knowledge base, which holds a proposed record to the same words (the table above). It
also fails when a glossary head word heads two entries or is also retired.
[`words-allowed.md`](words-allowed.md) names a document that could not be reworded at once, with a date. With `MESH_CATALOG_DIR` set it compares the catalogue's copy
[`words-allowed.md`](words-allowed.md) names a document that could not be reworded at once, with a date. With `MESH_CATALOG_DIR` set it compares the catalog's copy
of the tools' retired words (`retired-words`) with the glossary.
It also fails on a **daemon's line** (ADR 0272,
@@ -107,7 +109,7 @@ its insight of 2026-10-09): the operator types one command, `nox`, and a documen
controller's or the node-engine's binary followed by one of its commands. The lines are the check's own list
(`daemonLines` in the words test); a command that is a line only with an argument after it is matched as a line is written. Looked
for in the same documents, from 2026-10-09 for issues, in the document's own words — code blocks and
spans included, quotations and block quotes taken out. With `MESH_CATALOG_DIR` set it compares the catalogue's copy
spans included, quotations and block quotes taken out. With `MESH_CATALOG_DIR` set it compares the catalog's copy
(`retired-lines`) with the list.
It failed on something real before it passed: 581 uses of retired words in 63 documents on its first run, besides the glossary itself and research 034 —
+7 -1
View File
@@ -19,4 +19,10 @@ which keeps a record's words as it was imported.
| `04-ISSUES/353-the-controller-asked-before-the-bus-held-its-grant/00-report.md` | 2027-04-30 | history: the issue's narrative keeps the word of its day, "merge gate" (issue 1303); it is not rewritten |
| `04-ISSUES/354-a-decided-rename-was-never-scheduled-and-the-operator-believed-it-live/01-diagnosis.md` | 2027-04-30 | history: the issue's narrative keeps the word of its day, "merge gate" (issue 1303); it is not rewritten |
| `04-ISSUES/362-two-merges-seconds-apart-left-their-delivery-waiting-for-a-person/01-diagnosis.md` | 2027-04-30 | history: the issue's narrative keeps the word of its day, "merge gate" (issue 1303); it is not rewritten |
| `04-ISSUES/364-the-gate-refuses-a-module-that-uses-a-seat-another-module-declares/00-report.md` | 2027-04-30 | history: the issue's narrative keeps the word of its day, "merge gate" (issue 1303); it is not rewritten |
| `04-ISSUES/364-the-gate-refuses-a-module-that-uses-a-seat-another-module-declares/00-report.md` | 2027-04-30 | history: the issue's narrative keeps the words of its day, "merge gate" (issue 1303) and "judge" (the glossary's manifest validator retired the noun); it is not rewritten |
| `04-ISSUES/286-a-merge-check-passed-on-an-agents-machine-and-failed-on-the-build-seat/00-report.md` | 2027-04-30 | history: the issue's narrative keeps the word of its day, "judge" (the composition check's program built from a change; the glossary's manifest validator retired the noun); it is not rewritten |
| `04-ISSUES/306-a-check-on-the-control-node-ran-past-its-timeout/01-diagnosis.md` | 2027-04-30 | history: the issue's narrative keeps the word of its day, "judge" (the composition check's program built from a change; the glossary's manifest validator retired the noun); it is not rewritten |
| `04-ISSUES/310-a-pull-request-ran-its-own-copy-of-its-check/00-report.md` | 2027-04-30 | history: the issue's narrative keeps the word of its day, "judge" (the composition check's program built from a change; the glossary's manifest validator retired the noun); it is not rewritten |
| `04-ISSUES/343-the-controllers-terminal-has-no-command/01-diagnosis.md` | 2027-04-30 | history: the issue's narrative keeps the word of its day, "judge" (a part of the controller's pull request, named so then; the glossary's manifest validator retired the noun); it is not rewritten |
| `04-ISSUES/361-the-control-nodes-agent-account-is-never-judged/01-diagnosis.md` | 2027-04-30 | history: the issue's narrative keeps the word of its day, "judge" (the self-check's look at what an account can reach; the glossary's manifest validator retired the noun); it is not rewritten |
| `04-ISSUES/299-an-optional-verb-makes-a-holder-look-silent/01-diagnosis.md` | 2027-04-30 | history: the issue's narrative keeps the word of its day, "seat set" (the seats compiled into the controller then; the glossary's seat list retired it); it is not rewritten |
+116 -10
View File
@@ -35,7 +35,11 @@ import (
// struck-through text, link targets, HTML comments and frontmatter are taken out. A word's plural is the word.
// unique no head word heads two entries, and none is also struck through on a *Not:* line.
// lines no daemon's line in a checked document (ADR 0272, its insight of 2026-10-09): the operator types `nox`.
// copy with MESH_CATALOG_DIR set to a checkout of the catalogue, its copies of the retired words and the
// holders the glossary says no seat's holder: no seat "held by" or "claimed by" a named module, no named module
// "holder of" a seat, no module that "holds the seat" (the operator, 2026-11-09). Who holds a seat is read
// from the mesh's assignments, and the glossary's head says where.
// domains no retired domain heads a section of the glossary (ADR 0641 §5: Placement).
// copy with MESH_CATALOG_DIR set to a checkout of the catalog, its copies of the retired words and the
// daemons' lines equal this glossary's and this list (skipped, with its reason, when unset).
//
// Checked documents: 00-META/, 03-DESIGN/ (both layers), AGENTS.md and README.md, always; an issue opened on or after
@@ -52,7 +56,7 @@ const (
linesFrom = "2026-10-09"
)
var wordsAlways = []string{"00-META/", "03-DESIGN/", "AGENTS.md", "README.md"}
var wordsAlways = []string{"00-META/", "03-DESIGN/", ".claude/", "AGENTS.md", "README.md"}
// daemonLines are the daemons' lines (ADR 0272): each daemon's commands. "alone" is a command that is a line by
// itself; "with an argument" one that is a line only when written as one ("the mesh-controller module" is prose;
@@ -396,7 +400,7 @@ func checkUnique(retired []retiredWord, heads []string) []string {
return out
}
// linesList is the daemons' lines as the catalogue's copy lists them: "<daemon> <command>", with " …" when an
// linesList is the daemons' lines as the catalog's copy lists them: "<daemon> <command>", with " …" when an
// argument must follow.
func linesList() []string {
var out []string
@@ -479,26 +483,26 @@ func readList(file string) ([]string, error) {
return out, nil
}
// checkCopy compares the catalogue's copies of the retired words and the daemons' lines with this glossary's. A
// checkCopy compares the catalog's copies of the retired words and the daemons' lines with this glossary's. A
// difference names what the copy should list, so regenerating it is copying that from the failure.
func checkCopy(catalogue string, retired []retiredWord) []string {
var out []string
copyWords, err := readList(path.Join(catalogue, "retired-words"))
if err != nil {
return []string{"the catalogue's copy of the retired words cannot be read: " + err.Error()}
return []string{"the catalog's copy of the retired words cannot be read: " + err.Error()}
}
sort.Slice(copyWords, func(i, j int) bool { return strings.ToLower(copyWords[i]) < strings.ToLower(copyWords[j]) })
want := toolsList(retired)
if strings.Join(copyWords, "\n") != strings.Join(want, "\n") {
out = append(out, "the catalogue's retired-words differs from the glossary: it should list "+strings.Join(want, ", "))
out = append(out, "the catalog's retired-words differs from the glossary: it should list "+strings.Join(want, ", "))
}
copyLines, err := readList(path.Join(catalogue, "retired-lines"))
if err != nil {
return append(out, "the catalogue's copy of the daemons' lines cannot be read: "+err.Error())
return append(out, "the catalog's copy of the daemons' lines cannot be read: "+err.Error())
}
sort.Strings(copyLines)
if strings.Join(copyLines, "\n") != strings.Join(linesList(), "\n") {
out = append(out, "the catalogue's retired-lines differs from this check's list: it should list, one per line:\n"+strings.Join(linesList(), "\n"))
out = append(out, "the catalog's retired-lines differs from this check's list: it should list, one per line:\n"+strings.Join(linesList(), "\n"))
}
return out
}
@@ -532,7 +536,7 @@ func TestWordsNoDaemonLineWritten(t *testing.T) { expectNone(t, checkLines(rootF
func TestWordsCatalogueCopyAgrees(t *testing.T) {
catalogue := os.Getenv("MESH_CATALOG_DIR")
if catalogue == "" {
t.Skip("NOT COMPARED: MESH_CATALOG_DIR is not set, so the catalogue's copy of the list was not read")
t.Skip("NOT COMPARED: MESH_CATALOG_DIR is not set, so the catalog's copy of the list was not read")
}
retired, _, _ := parseGlossary(readFile(rootFS(), glossaryFile))
expectNone(t, checkCopy(catalogue, retired))
@@ -691,7 +695,7 @@ func TestAllowanceHoldsAWordBackUntilItsDateAndShrinks(t *testing.T) {
expectProblem(t, checkRetired(mapOf(tree("an overlay\n", "")), retired, nil, "2026-10-23"), `AGENTS.md:1: "overlay" is retired`)
}
// H5d: the daemons' lines and the catalogue comparison.
// H5d: the daemons' lines and the catalog comparison.
func TestLinesCatchesADaemonsLineButNotProse(t *testing.T) {
fsys := mapOf(map[string]string{
@@ -754,3 +758,105 @@ func mapOf(files map[string]string) fs.FS {
}
return m
}
// holders: the glossary defines a word and never says which module holds or claims a seat. Who holds a seat is a fact
// of the mesh's assignments, read with one call (the operator, 2026-11-09: "it shouldn't be in the glossary"), and a
// copy here drifts. Refused, across line breaks: a seat "held by" or "claimed by" anything but a generic holder or a
// seat ("held once for the mesh by `x`", "held today by the forge module"); a named module "holder of" a seat ("the
// module `x`, holder of"); a module that "holds the seat" ("it holds the seat", "the `x` module holds it"); and "its
// holder, the x". A word for the role ("the module that holds the seat `x`") names no module and passes.
var (
heldByRx = regexp.MustCompile("(?i)\\b(held|claimed)(\\s+once)?(\\s+for\\s+the\\s+mesh)?(\\s+today)?\\s+by\\s+")
// What may follow "held by": a holder in general, a seat, or the knowledge base (a seat's word) holding a record.
heldByGenericRx = regexp.MustCompile("^(a\\s+module\\b|some\\s+module\\b|its\\s+holder\\b|the\\s+holder\\b|the\\s+identity\\s+seat\\b|the\\s+knowledge\\s+base\\b|one\\s+author\\b|the\\s+`[^`]+`\\s+seat\\b|the\\s+(node\\s+)?seat\\s+`)")
holderNamedRx = []*regexp.Regexp{
regexp.MustCompile("(?i)(\\bmodule\\s+`?[a-z][a-z0-9-]*`?|`[a-z][a-z0-9-]*`)\\s*,\\s+(the\\s+)?holder\\s+of\\b"),
regexp.MustCompile("(?i)\\b(it|which)\\s+holds\\s+(the\\s+)?(node\\s+)?seats?\\b"),
regexp.MustCompile("(?i)\\bmodule\\s+holds\\s+(it|the\\s+(node\\s+)?seat)\\b"),
regexp.MustCompile("(?i)\\bholder\\s*,\\s+the\\s+[a-z`]"),
}
)
func checkHolders(text string) []string {
var out []string
say := func(i int, m string) {
out = append(out, fmt.Sprintf("%s:%d: %q names a seat's holder; the glossary says where it is read instead", glossaryFile, lineOf(text, i), strings.Join(strings.Fields(m), " ")))
}
for _, loc := range heldByRx.FindAllStringIndex(text, -1) {
rest := text[loc[1]:]
if heldByGenericRx.MatchString(rest) {
continue
}
end := loc[1] + min(len(rest), 30)
say(loc[0], text[loc[0]:end])
}
for _, rx := range holderNamedRx {
for _, loc := range rx.FindAllStringIndex(text, -1) {
say(loc[0], text[loc[0]:loc[1]])
}
}
return out
}
func TestWordsGlossaryNamesNoSeatHolder(t *testing.T) {
expectNone(t, checkHolders(readFile(rootFS(), glossaryFile)))
}
func TestHoldersRefusesANamedHolderAndPassesARole(t *testing.T) {
for _, bad := range []string{
"- **x** — the seat `x`, held once for the mesh by the module `mesh-x`.",
"- **x** — the seat `x`, held\n by `mesh-x`.",
"- **x** — `go-package-registry` (held today by the forge module).",
"- **x** — the seat `x`, claimed by mesh-x.",
"- **x** — the module mesh-x, holder of the seat `x`.",
"- **x** — the module `mesh-x`, holder of `x`.",
"- **mesh-x** — the module that does x: it holds the seat `mesh-x` once.",
"- **bus** — The `nats` module holds it.",
"- **x** — written by its holder, the assigner.",
} {
if len(checkHolders(bad)) == 0 {
t.Errorf("not refused: %q", bad)
}
}
for _, good := range []string{
"- **seat** — a named role, held by a module assignment.",
"- **router** — the module that holds the `operator-channel` seat.",
"- **bus** — Held by the `mesh-broker` seat.",
"- **x** — the seat `x`; its holder is read with `mesh-module-assigner.assignments`.",
"- **depends on a seat** — a seat held on its node by some module.",
} {
if got := checkHolders(good); len(got) != 0 {
t.Errorf("refused a role: %v", got)
}
}
}
// domains: a retired domain is no heading of the glossary. ADR 0641 §1 retired Placement into Core (module
// assignment) and Delivery (the wants), and §5 has this test refuse it as a domain heading.
var retiredDomains = []string{"Placement"}
func checkRetiredDomains(text string) []string {
var out []string
for _, d := range retiredDomains {
rx := regexp.MustCompile(`(?m)^##\s+` + regexp.QuoteMeta(d) + `\b`)
for _, loc := range rx.FindAllStringIndex(text, -1) {
out = append(out, fmt.Sprintf("%s:%d: %q is a retired domain (ADR 0641 §1) and heads no section", glossaryFile, lineOf(text, loc[0]), d))
}
}
return out
}
func TestWordsGlossaryHasNoRetiredDomainHeading(t *testing.T) {
expectNone(t, checkRetiredDomains(readFile(rootFS(), glossaryFile)))
}
func TestRetiredDomainsRefusesTheHeadingAndPassesProse(t *testing.T) {
if len(checkRetiredDomains("## Placement — what runs on which node\n")) == 0 {
t.Error("a Placement heading was not refused")
}
if got := checkRetiredDomains("## Core\n\nwhich was the Placement domain until ADR 0641\n"); len(got) != 0 {
t.Errorf("prose refused: %v", got)
}
}
+529 -103
View File
File diff suppressed because it is too large Load Diff
+18 -2
View File
@@ -173,6 +173,22 @@ quietly stop being true, and nobody will learn that from a document.
Not test-driven development as a blanket rule — a test written first against undiscovered
behaviour asserts a guess. The obligation is that every decision has a defender.
### A bus permission is proven under the real permission
A change that adds or widens what a mesh process reads or writes on the bus (a subscription, a publish, a stream or
key-value read, a consumer) carries an integration test that runs it on a bus user with exactly the production
permissions of that account (mesh-sdk's composition of them), against a real bus server, and that fails with the
bus's permissions violation when the widest new access is not granted. It runs in the forge's check like every
integration test. A reviewer reading code does not see a grant, and a fake bus grants everything (ADR 0560).
How it is checked: a review that approves such a change whose pull request names no such test is the rule skipped.
### A bus permission under the real permission — how it was earned
On 2026-10-27 a change widened what every node agent watches; two reviews read its code and its tests ran against a
fake bus. Live, every node's agent was refused that read by its grant and stopped composing, and the same day the
grants part's user list dropped nine seats' subscriptions (issues 1126 and 1945).
### Tests run at the lowest level that proves them, within a time budget
Three levels, by how much real system a test uses (ADR 0391):
@@ -180,7 +196,7 @@ Three levels, by how much real system a test uses (ADR 0391):
| Level | Uses | Budget | Runs |
|---|---|---|---|
| **Unit** | one piece of logic alone: no database, network, bus, running service or other process | well under a second per test | locally, the tests of what changed, while working; and in the forge's checks |
| **Integration** | the real thing beside it: a database, the bus, a catalogue tree | the repository's whole suite in seconds, never over sixty | only in the forge's checks, once per push |
| **Integration** | the real thing beside it: a database, the bus, a catalog tree | the repository's whole suite in seconds, never over sixty | only in the forge's checks, once per push |
| **End to end** | the whole mesh, or a lab mesh, from the outside | — | only when the operator asks |
- **Test each behaviour at the lowest level that can prove it.** A defect found higher up gets a test at the
@@ -193,7 +209,7 @@ Three levels, by how much real system a test uses (ADR 0391):
### Tests within a time budget — how it was earned
On 2026-10-16 a feature's fixing agents ran the catalogue's whole merge check (about ten minutes), a
On 2026-10-16 a feature's fixing agents ran the catalog's whole merge check (about ten minutes), a
throwaway database and a locally built gate during local development. Each round cost tens of minutes and
caught neither real failure; the forge's checks found both.
+14 -2
View File
@@ -46,6 +46,18 @@ to-be document's frontmatter goes to `implemented`, and both stand — one descr
the other recording what was intended. Deleting the intention loses the reasoning, which is
the expensive half.
## A design is built as it is written
Research, decisions and the review by architectural domain are where the mesh's choices are made; building makes
none (the operator, 2026-11-10). A design is written to be built without a choice of the builder's own, in a main
file and one part per milestone that an agent reads whole (playbook [02](02-graduation.md), *The shape of a
design*). The prepare, develop and the code review of playbook [07](07-feature-branches.md) read only that design:
the prepare says where each design line lands in code and lists what the design does not answer, the operator
answers each such design question and the answer is written into the design, and only then does develop start. Every
commit cites the design lines it builds, and the review judges each change against its line. How it is checked:
playbook 07's *How it is checked* (the build maps, the commits' `Builds:` lines, the design questions' answering hq
commits).
## The playbooks
A drawn overview of them, the cycle, a feature's steps, the review loop and an issue's life, is
@@ -59,8 +71,8 @@ A drawn overview of them, the cycle, a feature's steps, the review loop and an i
| [04](04-build-handoff.md) | Work breakdown and handoff | A design is ready to be built: milestones usable on their own, issues per repository, each milestone one feature step |
| [05](05-constitution-sync.md) | Constitution sync | `how-we-build.md` changed a rule the mesh enforces |
| [06](06-writing-a-module.md) | Writing a module | Something that runs today must run on the mesh |
| [07](07-feature-branches.md) | Features | Work that changes code across issues or repositories: prepared context, local development, one review, one check, one delivery |
| [08](08-small-fixes.md) | Small fixes | One issue in one repository, about an hour of work: one try, one review, one delivery |
| [07](07-feature-branches.md) | Features | Work that changes code across issues or repositories: a build map from the milestone's part of its design, the design complete before any code, local development, one review against the design lines, one check, one delivery |
| [08](08-small-fixes.md) | Small fixes | One issue in one repository, about an hour of work: one review, one check, one delivery |
| [09](09-cleanup.md) | Cleanup | Merged branches, stale pull requests, finished worktrees and folders: read first, delete only what the operator approves, report the rest |
| [10](10-visual-design.md) | Visual design | A page the operator will use is about to be designed or rebuilt: mockups with fixed data, the operator picks, the pick is the reference |
+62 -14
View File
@@ -39,20 +39,33 @@ An idea arrives in one of two forms, and the first step differs:
- **Explain each question with a concrete picture** in the operator's words: what they would see, do or
lose under each option. No internal names (a record number, a verb, a word the glossary lacks) without
what it is beside it.
- **Write the requirements from the answers, before the options.** Each one line, numbered, saying what
the result must hold and how it is checked (for example "R5. A change across repositories is
delivered whole or not at all; check: a change over three repositories"). The requirements shape the
effort: every option is weighed against them, and the operator corrects them before any option is
worked out (the operator, 2026-11-09: "coming up with a list of requirements can also be an important
part, it actually shapes the research").
3. **Take a number.** `knowledge-base.reserve` with `kind: research` and `for`: the effort's title. The number
is spent whether or not the effort is ever proposed; one never proposed is withdrawn after a week. Never
pick one by hand.
4. **Propose it.** `knowledge-base.propose` with `kind: research`, the `number`, a one-line `title`,
`status: active`, `date` (the day it began), and `sections`, each a `name` and its markdown `text`:
- `00-overview.md`: the idea in the operator's words, what exists, the operator's answers (dated), and the
`status: active`, `date` (the day it began), and `sections`, each a `name` and its markdown `text`. A
section is a part of the record, never a file: its `name` is a plain title, a reference to another section
names that title ("the Direction's test 8"), and code evidence names the repository, the commit and the
function, never a path or a line (the operator, 2026-11-02: "don't use file references or local files
anymore"; the knowledge base is to be shown as a web page, where a file name links to nothing). Once
proposed, the record is the only copy: it is changed by `knowledge-base.get` and `propose`, never kept
in a local draft. The first sections:
- **Overview**: the idea in the operator's words, what exists, the operator's answers (dated), and the
words the effort uses that the glossary lacks, each defined in one line;
- `01-questions.md`: the questions to answer, the first ones first;
- `02-method.md`: what will be tried and measured, and on what.
- **Requirements**: the numbered requirements of step 2, each with its check;
- **Questions**: the questions to answer, the first ones first;
- **Method**: what will be tried and measured, and on what.
Name what it touches as `links` of kind `touches` (`"0276"`, `"research 045"`, `"issue 365"`, or a
design's path), and what it names for another reason as `cites`.
5. **Do the research.** Try, measure and read, smallest question first. Each finding goes into
`04-findings.md`: what was tried, what it showed (with numbers), what it means. Each change of the effort
the section **Findings**: what was tried, what it showed (with numbers), what it means. Each change of the effort
is `knowledge-base.propose` again, whole, with `why`; every version is kept, and `knowledge-base.history`
lists them and gives the difference between two. Until issue 844 is delivered, the knowledge base
takes a new version of an accepted, active effort only as a progressive insight: give `insight`, saying
@@ -69,20 +82,52 @@ An idea arrives in one of two forms, and the first step differs:
server, a protocol) is tried in process, on the machine's loopback, in minutes. Lab runs (about 12 to
16 minutes fresh) are for the mesh's own code; before that code exists, a lab run tests nothing an
in-process test does not, and its lab scenario is written as the build's acceptance test instead.
6. **Place it in the domains.** Before the direction, write `03-domains.md`: the domain or domains the idea
6. **Place it in the domains.** Before the direction, write the section **Domains**: the domain or domains the idea
belongs to (the glossary's sections, ADR 0244); the modules and seats it lands in, each new, changed or
retired; what it does to each domain's words, each word added (with its domain and a one-line meaning),
changed or retired, and none on a *Not:* line or already meaning something else (the glossary's homonyms);
and whether a domain grows or shrinks, a concept moving between domains included. The direction names its
decisions in those words. Asked when the idea is set up, too: an option that lands a concept in the wrong
domain is offered with that cost named, like one that breaks a rule.
7. **Settle the direction with the operator.** When the questions are answered, write `05-direction.md`:
the proposed decisions in a few lines each, the options rejected and why, and the build's acceptance
tests: what the build must prove before it is done, carried by its milestones (playbook
7. **Settle the direction with the operator.** When the questions are answered, write the section **Direction**:
the question the effort answers, the options weighed and the one proposed (a second only for a second
question of its own; playbook [02](02-graduation.md), step 2), the design choices that follow from it in a
line each, and the build's acceptance tests: what the build must prove before it is done, carried by its milestones (playbook
[04](04-build-handoff.md)). Nothing else is left open: each question closes by a test, by a decision the
effort records with its reason (a small design limit is the lead's), or by the operator. Ask the
operator to confirm or change the direction, one point at a time, then propose it once. Then the effort
graduates through playbook [02](02-graduation.md).
operator to confirm or change the direction, one point at a time. Then review it by architectural domain (below) and
propose it once. Then the effort graduates through playbook [02](02-graduation.md).
## Review by architectural domain
A direction the operator settled can still be wrong where nobody looked. Before it is proposed, and again
before a design is merged (playbook [02](02-graduation.md)), it is reviewed against each **architectural domain**
(the operator, 2026-11-02), by reviewers on the larger model, about two architectural domains each, side by side:
the four reviewer agents in `.claude/agents/` (`review-security-and-upgrade`, `review-seams-and-tools`,
`review-running-and-testing`, `review-health-and-events`), each given the subject by number or path:
- **security**: who may call each new verb, how its grants are scoped, which credentials go or remain, what
can be replaced or forged, and what enters from outside the mesh;
- **seams**: where each piece of state lives on the bus, which seat, verb or event joins two parts, and any
link that is not NATS-native. Each piece of state is kept in the bus storage form that fits it (a key-value
bucket, a stream, an object store); a form the manifest lacks is added to mesh-sdk, and the review names that change
and its cost (a mesh-sdk change rebuilds every module) to the operator, never folds it in silently (the
operator, 2026-11-02);
- **running qualities**: build capacity, speed, storage growth, and what happens while a part, the bus or the
control-node is down;
- **health**: what each part's health check says, which conditions are raised and cleared, and whether any
failure can pass silently;
- **events and logs**: what each step says on the bus, and what can be read back later;
- **testing**: an acceptance test for every decision, each one checkable and within the test budget, and the
failure paths;
- **upgrade**: how what runs today moves to the new shape without a delivery breaking, in which order, and
how it is rolled back;
- **tools**: which tool reads each new piece of state and which one steers each new behaviour.
A reviewer judges only whether the settled direction is complete and sound in its architectural domains; it never reopens
a decision. Each finding is a sentence for the direction or a new acceptance test; a finding that changes a
decision goes to the operator. The direction ends with a section *Reviewed by architectural domain*: per architectural domain, what was
found and how it was answered, or that nothing was found.
## Bounds and models
@@ -90,9 +135,10 @@ An idea arrives in one of two forms, and the first step differs:
|---|---|---|
| reading and the setup questions (1, 2) | 30 minutes | the session's own, larger |
| proposing (3, 4) | 15 minutes | larger |
| each experiment or reading task (5) | 30 minutes | smaller, one agent at a time unless the operator allows more |
| each experiment or reading task (5) | 30 minutes | smaller, one agent at a time unless the operator allows more: the agent `research-reader` |
| placing it in the domains (6) | 15 minutes | larger |
| the direction (7) | 30 minutes | larger |
| the review by architectural domain | 20 minutes | larger, about two architectural domains per reviewer |
A step past its bound is said to the operator at once, with what is being done about it. The lead reports
as playbook 07 does: every ten minutes and at once when something is found, stops or needs the operator,
@@ -125,7 +171,8 @@ for the operator's Approve on a channel that proves who answered.
## Closing
An effort never just stops. It closes through playbook [02](02-graduation.md) as `graduated` or
`abandoned`, always with a `became` link to what it turned into. Nothing is deleted — what was rejected,
`abandoned`: a graduated effort with a `became` link to what it turned into, an abandoned one with a `cites` link to
what replaced it (playbook 02 step 5). Nothing is deleted — what was rejected,
and why, is the more expensive half to rediscover.
## How it is checked
@@ -134,7 +181,8 @@ The rules on an effort are the knowledge base's: `propose` refuses one that brea
record (the module's table test holds one case per rule), and the rules that judge the whole record set run
after every acceptance and raise a condition when one fails. The habits of steps 2, 5, 6 and 7 (options checked
against the rules, one version per settled set, the cheapest level, nothing left open) are the lead's, read by
the reviewer; of the pre-check, `propose` refuses a link to nothing and a retired word, and the review returns
the reviewer; the review by architectural domain is read in the direction's *Reviewed by architectural domain* section (nothing refuses a direction
without it yet: the lead and the reviewer hold it); of the pre-check, `propose` refuses a link to nothing and a retired word, and the review returns
a record named but not linked, an untracked deferral and a figure not as measured. That this repository holds
no effort is the records test's `no-records` check, on every pull request. An active effort with no new version
for seven days is the smell of research left behind: its lead closes or continues it.
+109 -11
View File
@@ -13,7 +13,7 @@ clauses in force for a topic or a record).
## Graduating research
The effort's `05-direction.md`, confirmed by the operator (playbook [01](01-research.md), step 7), is what
The effort's Direction, confirmed by the operator (playbook [01](01-research.md), step 7), is what
graduates. The lead writes the records and the design on the larger model; it is one sitting, bounded at
about an hour, and said to the operator if it runs past.
@@ -21,8 +21,17 @@ about an hour, and said to the operator if it runs past.
[`mission.md`](../mission.md), [`context.md`](../context.md) and
[`effect.md`](../effect.md). If it conflicts, either the effort is wrong or GENESIS is —
say which, in writing, before proceeding.
2. **Record the decisions** (below, *Writing a decision record*): one record per choice that could be
reversed on its own, not one record for the whole effort.
2. **Record the decisions** (below, *Writing a decision record*): one record per question the effort
answers, holding that question, the options weighed and the one chosen. Most efforts answer one question
and graduate into one record; a second record is written only for a second question of its own, such as
how the change can be checked or delivered at all (the operator, 2026-11-06: an effort graduated into
eleven records where it answered two questions). The choices made while working out the design that
follows (a field, a tool, an event, a bound, the order of steps) are the design's: written in the design
with their reasons, under the record they follow from, never as records of their own. A clause of an
earlier record the decision changes is a `changes` link from the record, with one line saying in what.
How it is checked: the lead names, in the graduation's report to the operator, the question each record
answers; an effort graduating into more than two records is said to the operator with why, before the
records are proposed.
- **Write them together, not one after another.** Reserve every number first, then propose each record
as soon as it is written, without waiting for the review of the one before; the reviews run side by
side, and the operator's asks for the records that need them arrive together. A record that
@@ -49,21 +58,39 @@ about an hour, and said to the operator if it runs past.
---
```
The design lists the direction's acceptance tests: what the build proves before it is done.
The design lists the direction's acceptance tests: what the build proves before it is done. Before it is
merged, the design is reviewed by architectural domain as playbook [01](01-research.md#review-by-architectural-domain) says, and
ends with its own *Reviewed by architectural domain* section; a design amended without an effort is reviewed the same way.
The words of the effort's `03-domains.md` go into the glossary in the same change, each in its domain: a
The words of the effort's Domains go into the glossary in the same change, each in its domain: a
word added gets its entry, a word whose meaning changed gets its entry rewritten, and a retired word moves to
its replacement's *Not:* line. A word that already means something else in another domain is named as a
homonym with the qualified form each domain uses.
4. **Hand it to the work breakdown.** The design goes on through playbook [04](04-build-handoff.md):
milestones, issues, and each milestone built as one feature step (playbook [07](07-feature-branches.md)).
5. **Close the effort.** `knowledge-base.propose` the effort again, whole, with `status: graduated` and a
`became` link to the decision record (`"NNNN"`) and to the design document (its path). An effort that
stops without a decision is proposed with `status: abandoned` and a `became` link to what replaced it.
5. **Close the effort.** `knowledge-base.close` the effort with `to: graduated`, a `became` link to each
decision record (`"NNNN"`) and the design document (its path), and a note of two or three sentences (what it
became, what carries it). The verb keeps the served text unchanged and adds a section *Graduated* with the note;
the knowledge base's review judges only the closing. Never close by proposing the effort again whole:
that is judged as a fresh proposal, so the approved reasoning is re-judged against the decisions that replace it
(on 2026-11-10 an effort closed that way met 5, then 11 findings on unchanged text; `close` was approved at once).
An effort that stops without a decision is closed `to: abandoned` with a `cites` link to what replaced it: the
knowledge base refuses `became` from a research effort to another research effort (its link-fits rule, design
55 § 2), so a replacing effort is cited, and `became` stays for the decision and the design an effort turned
into.
## Writing a decision record
**Before a number: what holds, and the mesh path, reviewed.** Ask the knowledge base what is already decided in
the record's area (`knowledge-base.ask`, `holds`), and name in the draft, for every interaction between modules the
record decides, the seat and verb, event, provision, state on the bus or manifest field that carries it. Then
`review-seams-and-tools` reviews the draft before it is proposed: a clause that has one module name another, read its
internals or be special-cased in another part, or puts a module's name into shared code, is a finding (the operator,
2026-11-03).
How it is checked: the record's References name the seams review's verdict; a record proposed without it is a breach
the lead names.
1. **Take a number.** `knowledge-base.reserve` with `kind: decision` and `for`: the record's title. The
number comes from the issue tracker's counter and is spent whether or not the record is accepted; one
never proposed is withdrawn after a week. Never pick a number by hand.
@@ -123,13 +150,83 @@ by a progressive insight.
record `changes` the older one's clause, so a reader who arrives at the older record by a citation sees
what changed it since.
## The shape of a design
A design is what its builders build from, and nothing else is (playbook [07](07-feature-branches.md)): decision
records and the mesh's principles are read when a design is written, amended or reviewed, and never again by the
prepare, the developers or the code review. So a design is written to be built without a choice of the builder's
own, and in pieces an agent can read whole. On 2026-11-10 one design of more than 400 KB was built in one
milestone: its agents read it by searching for pieces, filled what they did not find themselves, and an audit of
that day's 40 or so choices by the leads found seven against the records or the design and 29 questions the design
never answered, all found only in develop.
- **A main file and one milestone part per milestone.** The design's main file
(`03-DESIGN/01-to-be/NN-<slug>.md`) holds its frontmatter, its purpose, the whole shape (its parts, their seats,
events, provisions and state, drawn and in short prose), its acceptance tests and its *Milestones* section. Each
milestone not yet delivered has its **milestone part**, `03-DESIGN/01-to-be/NN-milestones/<milestone>.md`, which
holds every line that milestone builds and opens with frontmatter naming `layer: to-be`, the design, the
milestone and the `decisions:` its lines follow. A line lives in one place: a statement one milestone builds moves
from the main file into that part, never copied.
- **Bounds.** The main file at most 80 KB, a milestone part at most 60 KB. An agent reads both whole in under
40,000 tokens, under a fifth of what it can hold, and has the rest for the code. A milestone whose part would
pass 60 KB is two milestones (playbook [04](04-build-handoff.md)), each usable on its own.
- **Numbered design lines.** A milestone part's statements are numbered, each one thing to build with a bold
lead, like a decision's clauses, and cited as "design NN M §n"; a subtask, a commit and a review finding cite
them so. Each line names what its builder needs: the seat, verb or event, the field and its form, the key and
who deletes it, the bound, the caller, the tool that reads or steers it, and the fate of each thing that exists
today and changes. A line a builder would have to complete is a design question left open.
- **A delivered milestone's part stays.** It records what was intended, as a to-be design does once it ships
(the overview, *The two design layers*); no agent reads it again, so it costs no builder anything, and what runs is
written in the as-is design. The history of how a milestone was cut or why it waited is the issue tracker's and the
records', not the design's.
- **Design 47's next amendment is written in this shape**: the main file keeps the purpose, the whole shape, the
acceptance tests and the milestones, within 80 KB; every milestone gets its part with every line it builds or
built, moved from the main file, the one about to be built first; and the narrative of past milestones and their
prepare steps leaves the design for the issues it names. Every other design is put in this shape
at its next amendment, and a new design is written in it.
How it is checked: the reviewer of a design's pull request reads `wc -c` of the main file and of each milestone
part against the bounds, and that every statement of a milestone part is numbered; a check among hq's Go tests is to
be built (the cycle test reads only a design's main file today).
## Answering a design question
A design question (playbook [07](07-feature-branches.md), step 0) is answered by the operator and by nobody else:
not by the lead, the preparer, a developer or a reviewer, however technical it is. The lead asks it as the
instruction on asking says, one question per ask, with what the milestone part says, what it leaves open, where it
was met (file:line) and a recommendation. Then:
1. **Within a record's question** (a field, a bound, an owner, an order of steps, inside what a record decides), the
answer is the design's own choice: `hq-design-writer` writes it as a design line of the milestone part, citing
the operator's answer and its date and the record it follows from.
2. **Outside every record's question**, or **against a record** (the design contradicts a decision in force), the
answer is a decision: written first as *Writing a decision record* or *Changing a decision* above says, then as
design lines.
3. **The answers are reviewed together.** Before develop starts, the four reviewers by architectural domain read the
milestone part as amended, in one round (playbook [01](01-research.md#review-by-architectural-domain)); answers
met during develop are read by them in one round before the code review.
4. **They land on the milestone's branch.** The amendment is committed on hq's branch of the milestone
(`feat/<slug>`), so its pull request joins the milestone's delivery group, and the builders read the milestone
part at that branch's head.
How it is checked: every design question in the milestone file names the hq commit that answers it; a design line
added during a milestone with no operator's answer or record behind it is a finding of the review by
architectural domain.
## Amending an existing design
A design changes only through a decision.
A design changes only through a decision. A choice within what a decision decides (a field, a tool, an event,
a bound) is the design's own, written in it with its reason; it needs no record of its own. It is made when the
design is written or amended, never while it is built: a choice the design leaves to its builder is a design
question (above).
1. Write the decision record (above). If it reverses an earlier one, it `supersedes` it.
2. Edit the to-be design document, add the record to its `decisions:` as `"ADR NNNN"`, and set `updated:`
to today.
to today, keeping the design in the shape above (a line one milestone builds goes into that milestone's part).
A set of amendments across several designs (a milestone's findings, a graduation's) is written by the
agent `hq-design-writer` (`.claude/agents/`), started with a handover naming the designs, the records and the
branch. Review it by architectural domain before it is merged (playbook [01](01-research.md#review-by-architectural-domain)), and
rewrite its *Reviewed by architectural domain* section.
3. If the amendment came from an issue, give the issue the document path in the issue tracker:
`amended-design` on its `issue-tracker.move` to `resolved`, or `issue-tracker.link` with kind
`design` before then — never in the report's frontmatter
@@ -164,7 +261,8 @@ record (its module's table test holds one case per rule), and the four rules tha
changes, an accepted record extending a superseded one) run after every acceptance and raise a condition
when one fails. In this repository, the records test checks that a design's `decisions:` entries and every
"ADR NNNN" in the text are well formed, and that no record is written here; the index test checks the reading
order's six topics, which the knowledge base reads. The three habits of graduating step 2 (side by side, clauses
order's six topics, which the knowledge base reads. A design's *Reviewed by architectural domain* section is read by the
reviewer of its pull request; nothing refuses a design without it yet. The three habits of graduating step 2 (side by side, clauses
from the direction, the pre-check) are the lead's, read by the reviewer; `propose` refuses a link to nothing,
a deferral no issue tracks and a retired word, and the review returns a record named but not linked.
The rounds are read in `knowledge-base.get` (its reviews, one per version): a question to the operator about a
+1 -1
View File
@@ -91,7 +91,7 @@ import read, which every imported issue names (`imported.commit` in `issue-track
ADR 0281).
4. Resolve. `issue-tracker.move` to `resolved`, which the tracker takes only from `fixing`, with `fixed-by`, and, if the root cause was a design gap,
run playbook [02](02-graduation.md) and give `amended-design`. **A core issue** — its `located-in`
names the controller, the node-engine, the tool runner, the SDK, or the catalogue's bus, forge or build
names the controller, the node-engine, the tool runner, the SDK, or the catalog's bus, forge or build
agent — resolves with `replay`, the id of its replay in mesh-lab's replays register, proved to fail on
the commit before the fix and pass on it, or with `replay-none` saying why none is possible
(ADR 0237);
+10 -1
View File
@@ -41,6 +41,11 @@ A design becomes **milestones**, and each milestone becomes **issues**:
first. A milestone is named by what it lets someone do; how it ships is shaped by the modules its changes move
and the nodes that run them (ADR 0401 §6), read from the indexer's fingerprints through the status view's
`indexer_modules` and `indexer_candidates`, and from the nodes' haves (`node_haves`).
4a. **Give each milestone its part** (playbook [02](02-graduation.md), *The shape of a design*): every line the
milestone builds moves from the main file into `NN-milestones/<milestone>.md`, as numbered design lines, each
naming what its builder needs. A milestone whose part would pass 60 KB is split here into two milestones, each
usable on its own; this is the one place a milestone is ever cut, for what one agent can read, before any work
starts. The main file stays within 80 KB. Written by `hq-design-writer` in the same change as the milestones.
5. **Ask the operator to confirm the milestones**, in a short table: number, outcome, the acceptance tests it
proves, repositories, the parts each repository builds. Change what they change.
6. **Open the issues.** For each confirmed milestone, `issue-tracker.open` one issue per repository part, its
@@ -50,7 +55,9 @@ A design becomes **milestones**, and each milestone becomes **issues**:
7. **Flip the status.** `status: in-progress`, `updated:` today; the design change goes through playbook
[08](08-small-fixes.md) (one hq pull request).
8. **Hand each milestone to playbook 07, one at a time.** The milestone is one release of playbook 07; its issues
are the release's issues; the next milestone starts when the previous one is delivered. A design waits
are the release's issues; the next milestone starts when the previous one is delivered. Playbook 07 builds from
the milestone part alone and starts its develop step only once that part answers every design question its
prepare finds (playbook 07, *Design complete*); a question is never answered by building around it. A design waits
while another design's milestones are being built: one design is built at a time (playbook
[07](07-feature-branches.md)), so this step starts only when the design before it is delivered.
9. **On completion of the last milestone**, run the "when something ships" section of playbook
@@ -72,6 +79,8 @@ Read by the lead and the reviewer today; a check among hq's Go tests is tracked
- A design in `status: in-progress` has a *Milestones* section, each milestone with its outcome and its
issues; an in-progress design without one is the smell of building without a breakdown.
- Each milestone of an in-progress design has its part under `NN-milestones/`, within 60 KB, its lines numbered
(`ls -l 03-DESIGN/01-to-be/NN-milestones/`); a milestone handed to playbook 07 without one is step 4a skipped.
- Every issue a milestone names exists in the tracker (`issue-tracker.get`), and an issue in `fixing` names
its milestone in its report.
- A milestone whose issues are all `resolved` is delivered (the status view said `delivered` for its source
+25
View File
@@ -83,6 +83,31 @@ 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, or shares code
*Added 2026-11-04, widened 2026-11-05* (ADR 0625, ADR 0627, ADR 0634, ADR 0635). Where each piece of shared code goes
is [design 20](../../03-DESIGN/01-to-be/20-writing-a-module.md) *Where a seat's code goes*: shared code lives with its
owner. In short:
- **Import the seat's contract and, where it has one, its client package**, from the seat's domain's contracts module
(`mesh-<domain>-contracts`, or `mesh-contracts` for the Core domain and a domain with none), never the holder module
and never a copy of the seat's types in your own code. The list of seats your module needs is read from the bus,
never compiled in.
- **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.
- **Logic and state layouts only your module owns**, where it holds no seat for them, are your module's own package;
another repository's module imports it only by a published version, so your manifest declares it as a package
artifact.
- **Logic your domain's modules share, owned by no one module and carried by no seat**, is your domain's SDK's
(`mesh-<domain>-sdk`); only what modules of more than one domain use goes into mesh-sdk.
- **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 the home of every new exported name; the checks design 26 lists refuse a stray
file in a contracts module, a seat named in mesh-sdk, an import of a contracts module from 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
+405 -143
View File
@@ -24,7 +24,7 @@ A small fix (one repository, one issue, about an hour of work) follows
- **Review that keeps hardening.** One fix went through seven review rounds in five and a half hours, each
asking for more hardening than its issue asked (issue 704, 2026-10-14). A round is for what makes the
change wrong; everything else is an issue of its own.
- **The first check after the whole branch is written.** A feature's catalogue branch, pushed once after
- **The first check after the whole branch is written.** A feature's catalog branch, pushed once after
hours of local work, met its first check on 2026-10-16 and failed on 29 problems, TypeScript errors among
them, that a unit suite run continuously while working finds at once.
- **A green pull request nobody marks.** An approved, green pull request that was not marked ready waited
@@ -35,25 +35,47 @@ A small fix (one repository, one issue, about an hour of work) follows
proved nothing, and dropping the field it was for passed every test. A reader of the changed record that the
survey never listed ended a module's conditions at each sync. The reviewer judged the bus tests by reasoning, and
wrongly, because they ran only after the review.
- **A check asked again and again.** Build capacity is the mesh's scarcest resource ("we don't have more
processing power", the operator, 2026-10-26), and a release that ran a try before its review, a try after it
and a check per fix round on an open pull request spent it several times over: every push to an open pull
request asks a new check, of every member for a group. A release runs one check ("every release should only
run 1 check or 1 try", the operator, 2026-10-26; ADR 0548).
- **A node agent's bus reads, proven only by review.** On 2026-10-27 a change widened what every node agent watches
on the bus; two reviews read the code, no test ran it under a node's real permissions, and once it was live every
node's agent was refused that read and stopped composing (issue 1126). How-we-build's rule "A bus permission is
proven under the real permission" (ADR 0560) is what the review now asks for.
- **A change built on what was remembered, not on what runs.** In the days up to 2026-11-02 a release took the
controller's jobs apart from the records and the survey alone. Jobs nobody had named surfaced only after the
delivery, a moved module's wiring and a changed failure label's readers were never read, and every check found one
more fault. Each layer had checked the layer before it; none had read the running code. Step 0 item 3a is the answer.
- **Implementation that decided.** On 2026-11-10 one milestone was prepared and developed from a design of more
than 400 KB, by agents told to start from the knowledge base and to report what was not mesh-shaped. The prepare
wrote its own findings and a file of about 40 rulings by its two leads, a third layer of truth between the design
and the code; a developer refused an event the design names; and an audit found seven rulings against the records
or the design (among them a store kept twice and a copy of another part's data) and 29 questions the design never
answered, all found in develop. The design is now the only input to the prepare and to develop, the prepare's only
output is where each design line lands and what the design does not answer, nobody but the operator answers that,
and develop starts only when it is all answered (step 0b, *Design complete*).
- **A module proven only after it reached the machines.** The mail modules were delivered with unit tests
only, then failed live three times (issues 859, 865, 868) and took five more hours of fixes.
## The shape
One feature is **one branch name**, **one worktree per repository**, **one pull request per repository**,
opened **once**, after the review. It runs in five steps, and its time is bounded. A milestone has no phases
opened **once**, after the review, and **one check** (ADR 0548). It runs in five steps, with the design completed between the first two (step 0b), and its time is bounded. A milestone has no phases
(the operator, 2026-10-17): these are its steps, and a report names the step it is in:
| Step | What happens | Bound |
|---|---|---|
| 0. Prepare | the lead settles the open questions and writes one context file per repository | 15 minutes |
| 1. Develop | one fixing agent per repository builds every issue locally, the whole unit suite before every commit; then each branch is pushed and tried | the milestone's issues, 30 minutes each, and one try |
| 2. Review | one reviewer reads all of it with the tries' results; reports go both ways; at most 3 rounds | 15 minutes |
| 3. Check | push the reviewed heads; a head the review changed is tried again; then the pull requests are opened and the forge's merge checks run the integration tests again; no further review | at most one more try and one check run |
| 0. Prepare | from the milestone part alone: where each design line lands in code, what exists there today and what relies on it, as one build map per repository; and every design question, the design's silences, listed | 15 minutes, longer when what exists is large: code never starts on an incomplete answer |
| 0b. Design complete | the operator answers every design question; each answer is written into the milestone part (playbook 02) and its build map rows added | until the list is empty: develop never starts before |
| 1. Develop | one fixing agent per repository builds every design line of its build map locally, each commit citing the lines it builds, the whole unit suite before every commit, the integration tests compiled, and once per head it reports those of the packages it touched and their importers run against an embedded bus (below); nothing is pushed | the milestone's issues, 30 minutes each |
| 2. Review | one reviewer reads all of it, the local commits, judging the integration tests by reading them against the code; reports go both ways; at most 3 rounds | 15 minutes |
| 3. Check | push the reviewed heads once and open the pull requests together; the checker's one check runs the integration tests; no further review unless the check fails | one check run |
| 4. Deliver | merge; the source revision moves, each module is built once and wanted on its nodes, its canary first | until the view says the source revision `delivered` |
**One milestone is one release** (the operator, 2026-10-17). A milestone is developed whole, tried before its review, reviewed once,
opened once and delivered once. It is never cut into steps for its size or for time: every cut adds a review, a
**One milestone is one release** (the operator, 2026-10-17). A milestone is developed whole, reviewed once,
pushed once, checked once and delivered once. It is never cut into steps for its size or for time: every cut adds a review, a
merge check, an Approve and a delivery of waiting, so the fewest cuts is the fastest. Nor is it cut for an
order between its parts (the operator, 2026-10-22: "a milestone is a milestone, we shouldn't cut it"): which module
reaches the machines before which is the assigner's rules' (a build and a composition before the want, a provider
@@ -84,10 +106,48 @@ small fix ([playbook 08](08-small-fixes.md)) while the milestone waits on a chec
rest are fixed right after the milestone's delivery, before the next milestone starts, together on one branch where
they share a repository. Either way it stays out of the running milestone's branch and pull request, unless it blocks
the running milestone, so the scope above holds. Only an issue in another design's milestones (one design is built at
a time), or one that needs a decision or the operator first, waits, and the report says which and why. Each report's line "Opened along the way" says for every
a time), or one that needs a decision or the operator first, waits, and the report says which and why. Each detailed report's line "Opened along the way" says for every
issue whether it is being fixed in between, after the delivery, or waits, and on what.
## Step 0 — Prepare (the lead, larger model)
## Step 0 — Prepare (mesh-preparer, larger model; the lead runs the process)
**Agents work from hq's definitions, never from a prompt written by hand.** Every agent the lead starts is one of
`.claude/agents/`: `mesh-preparer` for this step, `mesh-developer` for step 1, `mesh-code-reviewer` for step 2,
`mesh-watcher` for every wait, and the four reviewers by architectural domain and `research-reader` of playbook 01.
The lead writes only the handover: what the agent works on (issue, the design and its milestone part at an hq commit,
branch, worktrees, commits) and where it reports; a handover carries no choice about what is built, and one that
does is the lead answering a design question. A subagent runs in the session that started it, from hq: its way of working comes from its definition and hq's playbooks; what it builds comes from the milestone part and nothing else; one given a coding task works in a worktree under hq's `.work/` and also reads the conventions of the repository it changes, and where those contradict hq, hq wins and the agent says so. How it works, what it reads first and what it judges come from its definition, and so does its model: a
`mesh-developer` runs on the smaller model, and the lead starts one on the larger model only for work whose parts meet
at an interface several of the milestone's subtasks build at once (the design names it whole; nothing is designed in
develop), written with its reason in the milestone file; a lesson about how an agent
works goes into its definition by an hq pull request (the operator, 2026-11-03: "please don't write prompts by hand,
only the handover prompt"). How it is checked: the lead's report names each agent by its definition; an agent started
from a prompt written by hand is a breach the lead names at the next report.
**The design is the only input; the implementation decides nothing** (the operator, 2026-11-10: implementation
follows the decided design and makes no decisions, least of all architectural ones). The milestone's part of its
design (playbook [02](02-graduation.md), *The shape of a design*) and the design's main file are what the preparer,
the developers and the code reviewer read whole, and build or judge against. Decision records, the mesh's principles
and the knowledge base were read when that design was written and reviewed by architectural domain; they are not read
again to judge the design while it is built, because a builder who re-judges it builds a second design. Where each
interaction travels (the seat, verb, event, provision, state on the bus, manifest field) is a design line; one the
design does not name is a design question, never the preparer's finding with its own alternative. The mesh paths
are held where they are decided: the reviewers by architectural domain judge the milestone part before it is built
(playbook [02](02-graduation.md), *Answering a design question*).
- **The prepare's only output** is one build map per repository (item 4) and the list of design questions
(item 10). It writes no findings of its own, no recommendations into the build map and no rulings, and no file of
the milestone holds a statement of how something should be.
- **Nobody but the operator answers a design question**, however technical: not the lead, not the preparer, not a
developer or a reviewer, and not a lead of another session. The lead's part is the process: who works on what, on
which model, the waits and the reports, and asking the operator.
- **One milestone has one lead.** A session that held part of the work hands its branches and heads to the lead and
stops; between sessions travel heads, commits, design questions and the hq commits that answer them, never an
instruction on how to build.
How it is checked: every subtask in a build map and every commit of the milestone cites the design lines it builds
("design NN M §n"), and the review finds code that cites none (step 2, item 2a); the milestone's files hold no
rulings (`grep -n -i 'ruling' .work/<slug>/*.md` finds none); a question answered by anyone but the operator is a
breach the lead names at the next report.
1. **Name the feature once:** `feat/<slug>`, the same branch name in every repository it touches (but see the
exception for a new manifest word in phase 3: a release that must merge first has a name of its own). The
@@ -99,22 +159,63 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
`main` (`git worktree add --detach .work/<slug>/mesh-tools main`), never symlinks. **A repository's own
clone stays on `main`** (the operator, 2026-10-17): no work is done in it and no branch is checked out
there, so a session that opens in it reads what holds now; fetch and fast-forward it before reading.
3. **Settle every open question** in the feature's issues before any agent starts: on the issue, through
the knowledge base, or by asking the operator. A fixing agent that meets an undecided design question
stops, and its run is spent again.
4. **Write one context file per repository**, `.work/<slug>/<repo>.context.md`. It is what a fixing agent
reads instead of rediscovering the code, and it is reused by every agent and every round:
- the issues it builds, in order, each with: the files and functions it changes, the decisions it builds
with (quoted, with where each was decided), and its acceptance criteria (item 5), each with the test that
proves it;
- the repository's map for this feature: the packages and files involved, with one line each on what they
hold, and the patterns to copy (file:line);
- what not to touch, and what lands beside it in other repositories;
3. **Read the milestone part and the design's main file whole**, before any code; the preparer reads nothing else
to know what is to be built. Every question the code or the live mesh raises that the milestone part does not
answer goes onto the list of design questions (item 10), never into an answer of the preparer's or the lead's. A
fixing agent that meets a design question stops that part, and its run is spent again: the prepare is where the
questions are found.
3a. **Read what exists today, and write it down before any code** (the operator, 2026-11-02: "if i ask to implement
feature A, you'd better first check what exists today with regards to feature A"). Research, decisions, the survey
and the review each check the layer before them; this is the step that checks the running code. Each repository's
build map (item 4) opens with a section `What exists today` that answers three questions, in writing:
1. **What exists today for this feature**, read from the code (file:line) and from the live mesh through the mesh
MCP server's tools (the seats, the modules on each machine, their state on the bus, their tools' answers), never
from memory and never from a record alone. Where the code or the mesh contradicts the milestone part, the answer
says so and the contradiction is a design question (item 10).
2. **Everything the change touches, replaces or removes, and what relies on each today.** For a part that is removed
or moved (a module, a seat, a job of a module, a file, a value's form, a label others read), every effect it has
is listed, found mechanically from its code and not recalled: each bus write (bucket key, stream subject, event),
each file it writes, each credential or grant it issues or rotates, each plan or record it makes, each process or
container it starts, each verb, tool or request it answers, and each timer it runs. Then, for each effect, every
reader that relies on it (a search across every repository and the live bus, file:line or address). The search is
written down as run (the pattern and where), so the review can run it again.
3. **For each item of the second answer, what happens to it after the change** (kept as it is, moved to a named seat,
module or verb, replaced by a named part, or dropped and why nothing needs it), **and the test that proves it**: an
acceptance criterion (item 5) at its level, or, for a dropped effect, the search showing no reader is left.
The fate is the milestone part's: the answer cites the design line that gives it, and an effect or a reader no
design line gives a fate is a design question. For every new exported type, field, constant, package or module,
the answer names the design line that places it (the milestone part's, or the design section *Where a seat's
code goes*): where new code goes is always the design's, never the lead's own choice.
**A seat's contract is a design line's form too.** For each seat contract the milestone adds or changes, the
answer compares what the contract on main says (its fields, subjects, callers and kinds) with the design lines
that name that seat, field by field; every difference is a design question (item 10), answered before develop
(2026-11-10: a seat contract and an event's subject that differed from the design surfaced only in develop).
Code starts only when the three answers are complete for every repository: no fixing agent starts on a build map
without them, and an effect found later is the prepare step missed, written into the answer and its issue before the
fix. In the days up to 2026-11-02 the controller was taken apart without this answer: jobs nobody had named (making
a provision's credentials for a new consumer, planning a module's next build) surfaced only after the delivery; a
module was moved without reading how its pieces were wired; a failure label was changed without reading what relied
on it; and each check found one more fault the preparation should have known.
4. **Write one build map per repository**, `.work/<slug>/<repo>.map.md`. It is what a fixing agent reads beside the
milestone part instead of rediscovering the code, and it is reused by every agent and every round. It says where,
never how: each entry is a design line's citation and a place in code, and a sentence in it that says how
something should be is a design question put in the wrong place.
- first, the section `What exists today` with item 3a's three answers;
- one row per design line the repository builds: the line ("design NN M §n"), the files and functions it
changes, the subtask that builds it (about 30 minutes, one change, its label), its acceptance criteria (item 5)
and the test that proves each;
- the order of the subtasks: **a subtask that uses what another adds** (a seat's contract, a type, a verb, an
event's form, a package) **starts from that subtask's commit, never beside it**, so the contracts and packages
come first and their users after; and **one writer per file**: each file the milestone changes has one subtask's
agent, named here;
- the patterns to copy (file:line), what not to touch, and what lands beside it in other repositories;
- the local facts: the worktree, the branch, the check commands, a temporary directory for tests outside
the home (`TMPDIR`), and the unit tests to run (never a database server: tests that need one are
integration tests, which the try (`mesh-controller.try`) and the checker's merge check run).
When the reading is large, a read-only agent on the smaller model answers the lead's exact questions with
file:line, and the lead writes the file from its answers.
the home (`TMPDIR`), the unit tests to run (never a database server: tests that need one are integration tests,
which the pull request's one check runs), and **the one placement of the siblings** every agent of the
milestone uses (its `go.work` `use` lines or `replace` directives), as the running checker places them; no agent
writes a placement of its own.
When the reading is large, a read-only agent on the smaller model answers the preparer's exact questions with
file:line, and the preparer writes the map from its answers.
5. **Write the findings into the issues** (the operator, 2026-10-17: the better the content of the issues, the
better work the agents do, and the less review is needed). Before any agent starts, each issue carries, with
`issue-tracker.note`: every file and test that touches the change, found by search and not from memory
@@ -123,12 +224,14 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
(2026-10-19: the router's sync with the controller ended every condition the controller did not list, and the
survey, which followed only the new condition's own path, never named it); how the change is checked and delivered end to end (which test proves its done-when, which
modules its merge moves, read from the indexer's candidates of its group, and to which machines); and for a
group, its merge order. The context file
group, its merge order. The build map
points to these notes; an issue reread by another session or a later agent then holds what was found.
When the reading is large, it starts with a read-only survey agent on the smaller model.
**Each issue carries its acceptance criteria, written by the lead** (the operator, 2026-10-18: the larger
model writes them, and they guide every test). Each criterion is one sentence, given, when, then, about what
the module or the operator observes, never about how the code does it, and names the level of the test that
**Each issue carries its acceptance criteria, written on the larger model from the milestone part** (the operator,
2026-10-18: the larger model writes them, and they guide every test). Each criterion cites the design's
acceptance test or design line it comes from; a case the issue's done-when needs that no design line covers is a
design question, never a criterion of the writer's own. Each criterion is one sentence, given, when, then, about
what the module or the operator observes, never about how the code does it, and names the level of the test that
proves it: unit, integration (a bus, a store or a process started) or end to end (none exist yet, so such a
criterion is proven live after the delivery and said so). Together they cover the issue's done-when and the
cases its life passes through: on 2026-10-18 mesh-delivery's group life (a group of three, a member's own
@@ -145,7 +248,7 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
the SDK's users (they pin an SDK commit, and a pin to a commit no branch holds is a download that fails later,
issue 1148); every program that parses a manifest strictly (search `ParseManifest` across every repository, with
the SDK commit each pins), which must take an SDK that knows a new manifest word (2026-10-21: design 60's
catalogue milestone found mesh-build-go and the delivery's indexer reading manifests with an SDK from before the
catalog milestone found mesh-build-go and the delivery's indexer reading manifests with an SDK from before the
word); the SDK's list of a defined seat's verbs, which must name a verb a module adds (2026-10-21: node-files' two
new verbs were refused on the claim); the node-engine's decoder for a new key on the wire; the route by which a
repository's first module registers; and a part that needs something the bus or a manifest cannot yet give, which
@@ -165,20 +268,59 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
(one line for every key-value bucket key and stream the work creates or starts writing; "none created" if none)
Trying the switch-over on one node first (b):
- <which node goes first, and what is read there before the rest>
- or: the operator chose no try on one node first, on <date>; what that risks: <one sentence>
Integration level before the pull requests (c):
- <the tries that run it, per repository; a group try if issue 1921 has delivered one>
- what no try covers: <the parts of the group that meet only in the merge check>
- or: the operator chose no first trial on one node, on <date>; what that risks: <one sentence>
Integration level (c):
- <the one check that runs it: the group's pull requests, one check each, none before the review>
- what the check does not cover: <the parts of the group that meet only live>
```
A key or stream with no one who deletes it and no time to live is a leak and is settled before work starts. Until
issue 1921 gives a group try, answer (c) with the single-repository tries and say so.
Each line cites the design line that gives its deleter or its time to live. A key or stream with no one who deletes
it and no time to live, or with a lifetime no design line gives, is a design question, answered before work starts;
the lead writes no lifetime of its own.
9. **Move the issues to `fixing`**, `by` naming the feature's agent for that repository.
10. **List the design questions** in the milestone file, under `Design questions`: each with the design line it
concerns (or the section where a line is missing), what the line leaves to its builder, where the prepare met it
(file:line or the tool's answer), and the preparer's recommendation, said as a recommendation. A design that
contradicts a decision in force, a reader or an effect with no fate, a lifetime, a caller, a bound, a field's
form, a tool for a new state: each is a question. The list is the prepare's last output and step 0b's input.
## Step 0b — Design complete
Develop starts only when the milestone's design questions are all answered, each in the design (the operator,
2026-11-10: a question the design does not answer stops that part, goes to the operator, and its answer goes into
the design before the code).
1. **The lead asks the operator each question**, one per ask, as playbook [02](02-graduation.md), *Answering a design
question*, says, and adds each ask to its wait list. The lead answers none and passes on no answer of its own.
2. **Each answer is written into the milestone part** by `hq-design-writer` on hq's branch of the milestone, as a
design line (or, outside every record's question, after its decision record), and the four reviewers by
architectural domain read the amended part in one round.
3. **The preparer adds the new lines to the build maps** (item 4) and the question's entry names the hq commit that
answers it.
4. **The design is complete** when every entry names its answering commit. Then step 1 starts, from the milestone
part at that commit.
**A question met later stops only its part.** A developer or the reviewer who meets a question the milestone part
does not answer stops the subtasks that need the answer, says the question to the lead with the design line and
file:line, and goes on with the subtasks that do not; the lead adds it to the list and asks it as above, and the
stopped subtasks resume from the hq commit that answers it. Nobody builds around it, guesses it or builds both ways.
**A decision accepted while the milestone is built** that changes its part stops the subtasks of the lines it changes
until the part is amended (playbook [02](02-graduation.md)) and their build map rows are redone; code written before
the design was complete joins the milestone only where each of its commits builds a design line of the complete part,
and the review reads it as new code.
How it is checked: the milestone file's `Design questions` all name an answering hq commit older than the first
commit of step 1 (`git log` of each repository's branch against hq's); a commit with no design line, or one built on
an answer no hq commit holds, is a finding of the review (step 2, item 2a).
## Step 1 — Develop (one fixing agent per repository, smaller model)
- **One agent per repository, kept for the whole feature.** It reads its context file once and builds the
issues one after another, committing each locally with a message naming the issue ("Keep the assignments
on the bus (issue 652)"). It is not replaced per issue: the lead continues the same agent (by its id) with
- **One agent per repository, kept for the whole feature.** It reads the milestone part, the design's main file and
its build map once, whole, and builds the subtasks one after another in the build map's order, committing each
locally with a message naming the issue and, in its body, the design lines it builds ("Keep the assignments on
the bus (issue 652)", then "Builds: design 47 G §12, §13"). It builds what each line says, and nothing a line does
not say: no type, field, state, verb, event, bound, caller or tool of its own. Where it thinks a design line wrong
by the mesh's principles, it still builds it as written and says so in its report, for the lead to bring to the
operator; it never builds otherwise. It is not replaced per issue: the lead continues the same agent (by its id) with
the next instruction, so its context is paid for once.
- **Unit tests only, each well under a second** (how-we-build §5, ADR 0391). **The whole unit suite runs before
every commit** (the operator, 2026-10-17), not only the tests of what changed: it takes under a second, and a
@@ -189,31 +331,55 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
its helper alone, and dropping the field from the request passed every test); `gofmt`, `go vet` and the whole unit suite stay green. **The tests are written from the issue's
acceptance criteria**: one test or more per criterion at the level it names, each test's comment citing
the criterion it proves by its label (`// 1118/AC2`), and no criterion left without its test; an integration criterion is a test
that compiles and waits for the try at this step's end. The integration tests (those that start a store, a bus
or a process) are run first by that try, and again by the checker's merge check.
- **No pull request is opened in this step. When every issue is committed, the lead brings each feature branch up
to the current trunk (fetch by name, then merge), pushes it and tries it** (`mesh-controller.try`, as step 3 item 1 says), so the review reads the integration tests' real
results and judges none by reasoning (2026-10-19: a reviewer reasoned that a warning goes out at once, the
router holds it 30 s, and the try after the review found it). A failed try goes back to the same fixing agent
with its whole log, read as step 3 item 3 says, before the review starts. Never land on a red check: run the
checks, read the result, then land in a separate step.
- **The fixing agent's brief** (the lead gives it with the context file): name your issue in every step and
that compiles and is run by the pull request's one check. The integration tests (those that start a store, a bus
or a process) are compiled with `go vet -tags integration ./...` while developing and run by that check. **Once per head it
reports, not per commit, a developer also runs the integration tests of every package the change touches, and of
every package of the same module that imports one, against an embedded bus** (`go test -tags integration -count=1`
on those packages). Where the importers are many, it runs instead the tests of them that exercise the change
(`-run '<names>'`) and names that choice in its report. It is never a whole module's or level's run, so it stays
within the operator's rule of 2026-10-18 (step 3). On 2026-11-10 a kept call broke an integration test of a fix group whose
developers had run only the untagged suite, and the review's first round found it, not the developers. Before the
group's push the tests that exercise the change have run so at the reviewed heads (step 3), nothing else. **In mesh-sdk the whole
untagged `./...` runs at every commit, whatever package the change is in**: a test there holds its copy of the seat
list and fails on a change elsewhere. How it is checked: the developer's report names those packages and their
results, and the reviewer refuses a head reported without them.
- **Nothing is pushed and no pull request is opened in this step, and there is no try** (ADR 0548; the operator,
2026-10-26: "every release should only run 1 check or 1 try"). When every issue is committed, the lead brings each
feature branch up to the current trunk (fetch by name, then merge) and the review reads the local commits. Never call
`mesh-controller.try`, `mesh-delivery-checker.try` or `mesh-delivery-checker.checker_try`; one is run only when the operator asks for it. A reviewer
or a session that wants the code on the forge may push a branch that has no pull request: it runs nothing. Never land
on a red check: read the result, then land in a separate step.
- **The fixing agent's brief** (the lead gives it with the build map): name your issue in every step and
message ("issue 805: landing in mesh-catalog"); reach the mesh only through the mesh MCP server, never ssh;
never push, open, merge or close a pull request; never write to a store's database by hand, a schema change
is a numbered migration and the consolidated schema; Go only unless the context file says otherwise; never
move another issue; **leave the integration tests to the try while developing** (no `go test -tags integration`,
no store or bus started by hand): compile them with `go vet -tags integration ./...` and leave the running to
the lead's try at the end of this step, where `mesh-controller.try` runs them on the pushed branch. On 2026-10-17 three fixing agents ran them anyway, one for minutes on end, because the
brief only said they wait for the check (the operator). After a failed try or check it
never push, open, merge or close a pull request; never call a try; never write to a store's database by hand, a schema change
is a numbered migration and the consolidated schema; Go only unless the milestone part says otherwise; never
move another issue; **leave a module's whole integration level to the check** (no store or bus started by hand):
compile it with `go vet -tags integration ./...`, and once per head you report run the touched packages' and their importers' integration
tests against an embedded bus, or by name where the importers are many (above). **Judge a manifest and run the catalog's checks against what is live
now:** the seat list the seat `mesh-catalog`'s verb `seat-definitions` answers, read in the same turn and read again
when you report a head, with the
definitions the change's heads alter laid over it for the change's case (ADR 0636 §4), and the catalog at its trunk,
fetched fresh, beside it; never a captured copy, a test fixture or a list kept from an earlier run (2026-11-10: a
stale seat list made eight manifests refused locally that the running validator accepts, and stale copies hid two
failures). **Start a subtask only with room to finish it**: a subtask is sized so that its reading and its work
fit well inside a third of an agent's context; an agent with less than that left commits what is whole (tests
green) and stops between subtasks, never inside one (2026-11-10: developers that stopped at their bound inside a
subtask left half-built work for the next to read again). Its last report names its heads and the next subtask's
label; a fresh agent continues from the build map and the commits' design lines, and no file of the milestone
carries a handover of findings or choices. A single integration test may be run locally against an embedded bus when
it is the fastest way to find a cause, said in the review report and the pull request; before the group's push the
tests that exercise the change are run this way, by name (step 3). After a failed check it
usually pays to run that repository's whole integration level locally (`go test -tags integration -count=1 ./...` in each
module), by the lead or by the fixing agent on the lead's word, before another try: a verdict names only the first failed
test (issue 1921), and on 2026-10-23 R4g's faults surfaced one per try until a local run listed them all in a minute (a
module), by the lead or by the fixing agent on the lead's word, before the one more push: a verdict names only the first failed
test (issue 1921), and on 2026-10-23 R4g's faults surfaced one per run until a local run listed them all in a minute (a
guideline, the operator). Report back in under 150 words: commits, tests added and that they failed first, the
check results, anything you stopped on.
- **An agent that finds the code differs from its context file stops and reports** (file:line); the lead
settles it, updates the context file, and continues the agent.
- **Two repositories that depend on each other** keep their order in the context files: the reader before the
writer, the controller's new manifest word before the catalogue manifest that uses it.
local results, anything you stopped on.
- **An agent that finds the code differs from its build map stops that subtask and reports** (file:line). A fact the
map got wrong (a file moved, a function named otherwise) the preparer corrects in the map, and the agent goes on;
anything that needs a choice is a design question (step 0b, *A question met later*), never settled by the lead.
- **Two repositories that depend on each other** keep their order in the build maps: the reader before the
writer, the contract before its users, the new manifest word before the catalog manifest that uses it. Two agents
never build against an interface neither has committed: the user's subtask starts from the commit that adds it.
- **Several agents in one repository** (only for a large repository with independent areas): each works on a
local branch of its own from the feature branch's head and lands by fast-forward under a lock
(`flock <feature worktree>.lock git -C <feature worktree> merge --ff-only <its branch>`), after its unit
@@ -222,23 +388,30 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
## Step 2 — Review (one reviewer, larger model; at most 3 rounds, about 15 minutes)
1. **The reviewed tree is the tree that was tried**: every feature branch was brought up to the current trunk
before its push and try (step 1). A try and a merge check each run on the merge with the trunk as it is then, so a
1. **The reviewed tree is the tree that is pushed**: every feature branch was brought up to the current trunk
before the review (step 1). The check runs on the merge with the trunk as it is then, so a
trunk that moves later is met by the forge's merge check, not by another merge here. Every verdict names the
trunk it merged onto ("pass <head> on <trunk>"), and the lead reads that trunk against the repository's main
at once: a trunk behind main means the source revision (source.main) lags, and every check and try in that
at once: a trunk behind main means the source revision (source.main) lags, and every check in that
repository is judged on it until it moves, so the operator's Approve will merge nothing. Say it then, not at the
merge (issue 1726: on 2026-10-24 the gate dropped two merges it heard before it held its seat, and a
reviewed, approved pull request in each of the two repositories was refused at its Approve).
2. **One reviewer reads every repository's local commits** together, against the context files and the
decisions. **It is one agent, kept for the whole release** like the fixing agents: the lead continues it by
2. **One reviewer reads every repository's local commits** together, against the milestone part, the design's
main file and the build maps. **It is one agent, kept for the whole release** like the fixing agents: the lead continues it by
its id for every later round, for the extra cycle after a failed check (step 3) and for its review record, so it
reads the decisions, the issues, the context files and the commits once (issue 1042). A fresh reviewer per
reads the milestone part, the issues, the build maps and the commits once (issue 1042). A fresh reviewer per
round or per mark pays for all of that again. Its report is per repository: each finding as file:line, the failure it causes, and the fix.
It says which round it is in ("round 1 of at most 3").
2a. **Every change is judged against its design line.** Each commit cites the design lines it builds; the reviewer
reads each line against the diff that cites it: the code does what the line says, all of it, and nothing it does
not say. Code no design line asks for (a new exported type, field, state, verb, event, bound, caller or tool, a
fate for what exists) is a finding: a choice the design does not make, taken out or held until the operator's
answer is in the design (step 0b). A design line in a build map with no commit, or a commit citing an answer no hq
commit holds, is a finding. The reviewer does not re-judge the design: a line it believes wrong by a decision or a
principle is a note to the lead for the operator, never a change asked of the code.
3. **The report goes to the same fixing agents** that wrote the code, continued by their ids, so they fix
with the context they already hold. Each answers the reviewer: what it changed, per finding, or why not.
4. **Every new integration test is read against the code it drives and against its try.** Fixing agents only compile it, and its one run before the review is the try (step 1), which shows whether it passed but not whether it proves what it says. The reviewer traces each step of each new integration test through the code (fixtures against the manifest rules, what the store keeps and reads back, who holds a seat), and says which steps it could not trace. On 2026-10-17 a new test failed on its first two runs, on a fixture and then on a fault of the change; reading it against the code after the first failure found another fault, which would have failed a run too. The reviewer also checks that each new integration test enters through the same path the live trigger takes, not through a state it writes by hand: on 2026-10-17 milestone 4's test saved its delivery plan directly, so it skipped the cut from a batch that every live plan takes, and it passed while the backup step never ran (issue 1086).
4. **Every new integration test is read against the code it drives.** Fixing agents run only the touched packages' integration tests and their importers' (step 1), and no whole module's run precedes the review, so the reviewer judges each by reading too: a passing local run and the check that follows show whether it passed but not whether it proves what it says. The reviewer traces each step of each new integration test through the code (fixtures against the manifest rules, what the store keeps and reads back, who holds a seat), and says which steps it could not trace. On 2026-10-17 a new test failed on its first two runs, on a fixture and then on a fault of the change; reading it against the code after the first failure found another fault, which would have failed a run too. A review that finds a fault only by reading is the cheaper run. The reviewer also checks that each new integration test enters through the same path the live trigger takes, not through a state it writes by hand: on 2026-10-17 milestone 4's test saved its delivery plan directly, so it skipped the cut from a batch that every live plan takes, and it passed while the backup step never ran (issue 1086).
5. **The reviewer reads the answers and the new commits**, and approves or reports again (step 7 says what a round
may ask). After round 3 the lead stops and brings the operator what is left, with a recommendation.
6. **The reviewer reads every acceptance criterion against its test**: each criterion has a test at its level
@@ -252,11 +425,19 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
work-queue retention; three review rounds passed it, and only its try showed that every seat's work stream has
that retention too, so dead asks across the mesh would no longer have been delivered again (issue 1178, fixed
before its pull request by a mark only a declared module work queue carries).
**A test fixture writes state in the form its real writer writes it** (for example a resolved config value with its
source, as the controller stores it); a fixture that agrees with the mistake proves the mistake. How it is checked:
the review asks it of every new fixture, and says which writer it compared with.
6a. **The reviewer reads the milestone file's three answers** (step 0, item 8) against the change: it lists every bucket
key and stream the diff creates or writes (search the diff for the bucket and stream names) and finds each in the
lifetime answer with a deleter and event, or a time to live; it reads the switch-over answer and checks it was done as
written or that the operator's choice is recorded; it reads the integration-level answer against the tries named
in the pull request. A missing answer, or a key or stream the diff creates that the answer omits, is a change asked.
written or that the operator's choice is recorded; it reads the integration-level answer against the check the pull requests will ask. A missing answer, or a key or stream the diff creates that the answer omits, is a change asked.
6b. **The reviewer holds the change to each build map's `What exists today`** (step 0, item 3a). It refuses to
review a repository whose build map lacks the section or leaves one of its three answers open: that is the
prepare step undone, sent back to the lead, and not a round. For every part the diff removes, moves or changes the
form of, it runs the recorded search again on the reviewed tree and finds each effect and each reader in the second
answer; for each, it reads in the diff that the third answer's fate happened and that its test exists. An effect or a
reader the search finds and the answer omits, or a fate the diff does not carry out, makes the change wrong.
7. **A finding outside the issues' done-when and their acceptance criteria is never a change asked, in any round.** More hardening, a
further case, a nicer form: the reviewer opens it with `issue-tracker.open` and names the number in its
report, and the round does not wait for it. What a round asks is only what makes the change wrong against
@@ -275,26 +456,52 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
its shape, fixes every hit in one change and lists each file and line in the report. How it is checked: a
report to the second round naming a kind and one place only, followed by a third round on the same kind, is
this rule skipped.
10. **The reviewer asks two questions of every change and every design, and answers both in its report** (the
operator, 2026-10-28: "design everything NATS-native"; "repositories are fully mesh agnostic"). The first:
*where does each piece of state live, and how does each seam (an integration, data, a part talking to
another) travel?* Anything that is not bus state, a stream or a seat's verb on the bus is a finding. The second:
*does a repository hold anything about this mesh's setup, such as node names, node-specific placement or
settings?* That is a finding: repositories are mesh-agnostic. On 2026-10-28 a placement design kept placement in
repository files with node names, because the accepted record it followed said so and nobody checked it against
these two principles. A finding in code the design does not place makes the change wrong (item 2a); where the
design line itself puts the state or the seam there, the finding is the design's: the reviewer names the line and
the record behind it, the lead brings it to the operator as a design question, and the code waits for the answer
in the design. How it is checked: the review report has a line for each question with its answer, and the lead reads both before the
push; a report without them is not an approval.
## Step 3 — Check (no review)
1. **Push the reviewed heads, try again a head the review changed, then open one pull request per repository,
together.** **The integration tests run before the pull requests are opened**, first before the review (step 1)
and again for a head the review changed since its try: `mesh-controller.try` with the
repository and the pushed branch is a check ask of the checker (ADR 0501 §5): the checker runs the repository's tests on the
merge with the trunk's head, at the unit and the integration level, through the build module of the repository's language and by
that language's convention, as the merge check does, and answers with an id to read back. The try is an ask on the language's check
stream (ADR 0525 §1), so it waits behind the asks before it until a build node has a free slot; no script of the repository decides
it (ADR 0445, ADR 0529). A try that fails goes to step 3 item 3 as a failed check does; the pull requests are opened only
when every head's last try passed (the operator, 2026-10-18: three pushes in a row failed their first merge check on
faults a try finds in minutes). While developing, no `go test -tags integration` or store or bus started
by hand on the machine (the operator, 2026-10-18); after a failed try, a local run of the whole level is the guideline
in step 1's brief. **Before a session trusts an agent's "pushed", it reads the forge branch's head** (`git ls-remote origin refs/heads/<branch>`) and compares it with the commit reviewed; an agent may commit on a detached HEAD and report a push that never happened (2026-10-26: the first try of a reviewed fix failed "not our ref"). The try and the pull request are started only on that read head. Pull requests in two or
1. **Push the reviewed heads once, then open one pull request per repository, together** (ADR 0548; the operator,
2026-10-26: "every release should only run 1 check or 1 try"). **No pull request, draft or not, exists before the
review approves the heads**, and no fix round is pushed to an open pull request: every push to an open pull request
asks a new check, of every member for a group, and the mesh's build capacity is spent on it ("we don't have more
processing power"). The integration tests run once, in the checker's merge check on the merge with the trunk's head, at the unit
and the integration level, through the build module of the repository's language and by that language's convention
(ADR 0445, ADR 0529); the check waits on the language's check stream until a build node has a free slot
(ADR 0525 §1). **No try:** never call `mesh-controller.try`, `mesh-delivery-checker.try` or `mesh-delivery-checker.checker_try`, except when the
operator asks for one. While developing, no `go test -tags integration` run of a whole module or level, and no store or bus started
by hand on the machine (the operator, 2026-10-18).
**Before a group's single push, the integration tests that exercise the change have run locally against an
embedded bus**, at the reviewed heads: the touched packages' and their importers' tests that each developer ran for
the head it reported (step 1), or those picked by name (`go test -tags integration -count=1 -run '<names>'`) where
the importers are many; never a whole module's or level's integration run, and not only a compile with `go vet`; a
change in how a node composes or applies always has such a test (2026-10-28: a compiled-only group failed in the one
check on what a local run shows). How it is checked: the pull request's description names those tests and their
results.
**While a group is being checked, nothing else is merged or pushed into a repository that is one of its members:**
a moved main asks the group's check again. How it is checked: the lead's wait list names the group's members, and
`mesh-delivery.show` shows one check per head.
**A group is one check.** Before the push, every member pins the group's own package heads (mesh-sdk, and any other
package a member publishes) so it builds with `GOWORK=off`; the check itself builds against the group's heads whatever a
member's go.mod names (ADR 0573 §2, §4), so an older pin is not refused there, but the trunk builds after the merge read
the go.mod as written. Two members that import each other are pinned in order, each to the other's commit before its own
pin. Then all members are pushed and opened together, so the group's check runs once. A head the review replaces
counts for nothing against a running check; say so, and ask no other until the new head is reviewed.
**Before a session trusts an agent's "pushed", it reads the forge branch's head** (`git ls-remote origin refs/heads/<branch>`) and compares it with the commit reviewed; an agent may commit on a detached HEAD and report a push that never happened (2026-10-26: the first check of a reviewed fix failed "not our ref"). The pull request is opened only on that read head. Pull requests in two or
more repositories that share the branch name are one delivery group (ADR 0239 §2).
**A temporary mode that merges by hand** (the lead merges because the normal Approve and merge path is not
running): before it asks the merge, the lead runs the full integration level with nothing kept, a try with tests
`.` for each repository of the group, and names those tries (ids and verdicts) in the pull request's description.
A merge asked without them is a step skipped (research 071).
running): the pull request's one check still runs the integration level, and the lead names its verdict in the
pull request's description. A try with tests `.` is asked only when the operator asks for one, and then named there with its id and verdict (research 071).
Where a session pushes through the forge tool `gitea_commit` (one commit on the forge's current base), the
reviewer first confirms that commit's tree equals the reviewed one. **A large change is pushed by a pusher agent** on the smaller
model: `gitea_commit` patches of about 30 KB each, a file copied from another path sent as a copy (`copy_from`)
@@ -315,21 +522,36 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
ask named them): mesh-delivery takes a pull request's issues from the words `issue <n>` and `issues <n>` in its
description (the plural yields its first number only), so write `issue 1608, issue 1646`, and name any other
issue in words, never by `issue <n>` or `issues <n>`.
**A catalogue pull request that removes a module, or a subject a module names, is also judged by the
controller's unit tests against the catalogue's branch**, because those tests read the catalogue and no check
of the catalogue runs them: on 2026-10-20 mesh-catalog #381 removed the old delivery module, and every
controller check failed afterwards on a test of the catalogue's subjects until issue 1406 removed the name
mesh-issues still listened to. A controller try does not find it, since a check reads the catalogue's main
(also in a delivery group that holds the catalogue's pull request); the lead runs mesh-controller's unit
suite with `MESH_CHECK_BESIDE` naming a directory that holds the catalogue's branch, as mesh-controller's
**A catalog pull request that removes a module, or a subject a module names, is also judged by the
controller's unit tests against the catalog's branch**, because those tests read the catalog and no check
of the catalog runs them: on 2026-10-20 mesh-catalog #381 removed the old delivery module, and every
controller check failed afterwards on a test of the catalog's subjects until issue 1406 removed the name
mesh-issues still listened to. A controller's check does not find it, since a check reads the catalog's main
(also in a delivery group that holds the catalog's pull request); the lead runs mesh-controller's unit
suite with `MESH_CHECK_BESIDE` naming a directory that holds the catalog's branch, as mesh-controller's
`internal/beside` says.
2. **The checker's merge check runs the integration tests again, as the gate** (its one status, `mesh/check`). No
second review: step 2 reviewed this tree.
**Before the push, every member's suites run as the running checker runs them**: each sibling repository placed
beside it by main's beside rules, the node-engine at the commit the machines run, and the running manifest validator
over every manifest the change touches, given the live seat list and the catalog's fresh trunk (step 1's brief). On 2026-11-02 release sdk1 failed four checks one fault at a time (test
globals left set, a sibling placed otherwise, the checker's manifest archive, a composition step the old checker could not
build), each of which a run as the checker places things would have shown before the first push. How it is
checked: the pull request's description names the placement, the node-engine commit and the manifest validator run used
locally; a check that fails on a placement the local run did not use is named by the lead at the next report.
2. **The checker's merge check runs the integration tests once, as the gate** (its one status, `mesh/check`).
**A merge with no verdict is unchecked, never passed.** Until the pipeline runner replaces the checker, the
checker drops a check still running when its pull request merges (met twice on 2026-11-10): the lead reads the
check's verdict (`mesh-delivery.show`) after every merge, and a merged change whose check has none is reported to
the operator as merged unchecked, with what its local runs covered, never as passed. How it is checked: a report
that says a merged change passed is read against its verdict in `mesh-delivery.show`. No second review: step 2
reviewed this tree.
3. **A check that fails** goes back to the same reviewer, continued by its id, with the failure, for **one more cycle** of step 2 with
the same fixing agents; then push once again. **The failure is read from the check's whole log**, never
reasoned from its summary: `mesh-delivery.show` names the check's build id, and `mesh-controller.builds` with
`log` set to that id prints everything the builder said. A check's summary picks only some failing lines;
the same fixing agents; then push **once** again (the one more push of ADR 0548). The check is **read, never re-asked to see if it passes**: a
check asked again without a new, reviewed head spends the build capacity for nothing. **The failure is read from the check's whole log**, never
reasoned from its summary: `mesh-delivery-checker.checker_pull` names every failure the verdict holds, one line each, and the full report
of the check. A check's summary picks only some failing lines;
on 2026-10-17 it showed a store test's `FAIL` without its cause, and a fix was first guessed from the code.
**A failure the check hides or loses** (a verdict naming only the first failed test, a log not kept) is a fault of the
checking tool: it is fixed there, the same turn (instruction fix-a-bug-met-twice), not asked around.
**A change to the Go build module's recipe is judged by the build module the nodes run**, not by the changed one, so a
test the change adds must pass under either version. **A change that needs the new recipe to judge it ships the recipe
first, as a small fix of its own**, and the rest waits for its delivery: on 2026-10-17 milestone 3 of design 47 moved its
@@ -338,6 +560,13 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
which tests run at which level is the build tag's (ADR 0445 §2), and hq's checks are Go tests like any repository's
(ADR 0527). The prepare step looks for this: a change to what the checker's build module selects (its recipe, a build
tag convention) is cut ahead of the milestone.
**The same holds for every part that judges a change**: the checker, the indexer and its manifest validator, the grants part and
the build modules. A release that changes one of them is judged by the version that runs, so whatever the running
version cannot judge is delivered first as a change of its own, or left out and added back once the new part runs.
On 2026-11-02 release sdk1 delivered the build module's relative replaces first, and took the checker's new
composition call out of the release, adding it back in the next pull request once the new node-engines answered it. How it is checked: the prepare step's
milestone file lists every judging part the release changes and how each is delivered first or left out; the review
refuses a group that holds one without that line.
4. **The milestone's acceptance is proven by its check.** A milestone that adds or changes a module
carries an integration test that starts the module whole, its process against the real bus and store, and
shows the milestone's acceptance sentence; the forge's checks run it (ADR 0391 §1, §6). Unit tests alone are not
@@ -349,9 +578,9 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
hand (issue 1226).
5. **The operator's Approve is asked as soon as the checks pass** (ADR 0421). Nobody marks, labels, comments or
rechecks: mesh-delivery asks the Approve on Telegram, the channel that proves who answered today (ADR 0398 §3;
an Approve at the terminal is issue 953), once both checks passed, for a delivery group once for all its
an Approve at the terminal is issue 953), once its one check (`mesh/check`) passed, for a delivery group once for all its
members, naming the review record. On the Approve it merges the approved heads, a group's in one pass
(ADR 0418). A new head ends the Approve and is asked again once its checks pass. A watcher follows the checks,
(ADR 0418). A new head ends the Approve and is asked again once its checks pass, which is why a head is pushed only after its review. A watcher follows the checks,
the Approve and the merge, and wakes the lead. Beyond that
Approve, the operator's word is waited for only when the milestone changes what the operator sees, removes
data, or needs a step only the operator's terminal can take; the lead says which before the milestone starts.
@@ -365,16 +594,31 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
moved to include it): one Approve, one delivery. The old Approve ask closes itself on the new head and the new
head is asked once its checks pass. How it is checked: a follow-up that sits in a second pull request while the
first still waits shows in `gitea.gitea_list_pull_requests` as two open pull requests of one lead.
6. **A member pins mesh-sdk only at a commit that is a pull request's head**, merged or open (2026-10-28: the check
refused a pin to a merge commit on main as "on no pull request", though its tree equalled the head's). How it is
checked: the check's pin step; a refusal "on no pull request" is this rule skipped.
7. **Two groups that pin the same module's mesh-sdk conflict in `go.mod` and `go.sum`.** The group that merges
second merges main in and re-pins once, to a pull request head that holds both changes, after the first group
is merged and not before (a re-pin before makes the first group conflict). How it is checked: the check's merge
step; a group that conflicts after the first one merged is this rule skipped.
8. **A group that adds a seat, a verb or a manifest field in mesh-sdk and uses it in a module's manifest in the
same group cannot pass its check** until the running assigner pins a mesh-sdk that defines it, because the
check composes with the running assigner's mesh-sdk (issue 1585). The assigner's pin ships first, as its own
release. How it is checked: the check's composition step; a composition refusing the new word in such a group
is this rule skipped.
9. **A new head on an open pull request needs its `Reviewed-by` line at that head before the Approve is asked,
even for a pin-only commit.** How it is checked: the Approve's ask names the review record;
an ask whose line names another commit is this rule skipped.
**One exception: a catalogue change that uses a new manifest word.** The catalogue's merge check reads
**One exception: a catalog change that uses a new manifest word.** The catalog's merge check reads
manifests with the controller the mesh runs, so the controller's pull request is merged and delivered first;
then `mesh-delivery.recheck` the catalogue's and merge it on the new verdict. Such work is two releases, the controller's first, and playbook 04 cuts its milestones that way.
then `mesh-delivery.recheck` the catalog's and merge it on the new verdict. Such work is two releases, the controller's first, and playbook 04 cuts its milestones that way.
**A new key the node-engine checks is such a word too** (issue 1051): the controller judges every machine with the
node-engine's own validator, vendored at the commit `go.mod`'s `replace` pins, so a key added to the node-engine is
refused by the gate until the controller's pin moves to the delivered node-engine (`go mod vendor`); the feature is
then three releases, the node-engine's, the controller's, the catalogue's. **Every release that must merge before
the catalogue's is on a branch name of its own** (`feat/<slug>-node-engine`, `feat/<slug>-controller`): on the
feature's name it joins the catalogue's delivery group, and a group merges only whole, so neither merges.
then three releases, the node-engine's, the controller's, the catalog's. **Every release that must merge before
the catalog's is on a branch name of its own** (`feat/<slug>-node-engine`, `feat/<slug>-controller`): on the
feature's name it joins the catalog's delivery group, and a group merges only whole, so neither merges.
The exception ends when milestone 3 of design 47 is delivered (issue 977, ADR 0402, ADR 0403): the group's composed
check, judged by the group's controller, is then each member's gate, and the feature is one group.
@@ -392,7 +636,10 @@ the source revision equals its fingerprint and every have its want). After each
the view's wants page or its tools: `assigner_wants` and `assigner_want` (a want not yet at the newest fingerprint
names, in `newest` and `rule`, the rule that holds it back, and its words say why), and `node_haves` (the node
agent's haves: fingerprint, composition digest, phase and health). The delivery is done when the view says
`delivered` for its source revision; then the lead resolves the feature's issues with `fixed-by` naming its pull
`delivered` for its source revision; **"on the machines" from the delivery tools is not yet "delivered"**: the lead
also reads what the nodes run (the view's haves per node) and the indexer's record of the module (its newest
fingerprint) before saying a change is delivered. How it is checked: the report names each node's build.
Then the lead resolves the feature's issues with `fixed-by` naming its pull
requests, and removes what is left: no `feat/<slug>` branch and no `.work/<slug>` worktree survive.
**What a merge moves is read before the operator is told.** A change to mesh-sdk rebuilds every module that takes
@@ -452,8 +699,9 @@ Nothing here is a work-around for a delivery that can run normally: while the bu
| Who | Model | Why |
|---|---|---|
| The lead (step 0 decisions, the context files, following and reporting) | larger | judgement |
| Read-only questions about the code for the context files | smaller | reading, answered with file:line |
| The lead (who works on what, asking the operator the design questions, following and reporting; it answers no design question) | larger | judgement of the process |
| The preparer (the build maps and the design questions, from the milestone part alone) | larger | reading the design and the code together |
| Read-only questions about the code for the build maps | smaller | reading, answered with file:line |
| Fixing agents (step 1, and the fixing in steps 2 and 3) | smaller | building to a written context |
| The reviewer (step 2, the extra cycle in step 3 and the review record; one agent, continued by its id) | larger | judgement, once per round |
| Decision records | larger | judgement |
@@ -472,7 +720,7 @@ on, with when it started and its bound.
| a fixing agent's issue | 30 minutes | ask it where it stands; split or take over |
| the review | 15 minutes a round | ask the reviewer; stop at round 3 |
| a merge check | 15 minutes | read `mesh-delivery.show` (its state and verdict), then the check's log; the check stream's backlog and the age of its oldest ask are in the delivery view (ADR 0525 §9) |
| the Approve's ask | 5 minutes after both checks pass | read `mesh-delivery.show`: an ask not raised is a fault, said to the operator |
| the Approve's ask | 5 minutes after the check (`mesh/check`) passes | read `mesh-delivery.show`: an ask not raised is a fault, said to the operator |
| a merge after the Approve | 5 minutes | read `mesh-delivery.show` for the delivery |
| a delivery | its class's budget (3 minutes for a leaf module, 10 for a core module), at most 30 minutes | read the view's wants page, or `assigner_wants` against `node_haves`: a want held back names its rule, a `stuck` module its words |
@@ -497,54 +745,51 @@ Approve, a Retry or a Release waits for them, it reads `operator-channel.asks` a
on 2026-10-20 an ask was named to the operator that the router did not hold. A merge the gate passed but whose
ask is not on the router is the fault of the Approve's wait in the table above.
**Every ten minutes (the operator, 2026-10-17), every two minutes while a delivery moves (the view says modules `moving`), and at once when something lands, stops or
needs the operator,** the lead reports, in one of the two layouts below (the operator, 2026-10-16: an overview
of the issues, often). Times are local and absolute, from the clock (`date`), never guessed; every number has its
unit and its bound or baseline; an issue is named by its number and a few words, never by its number alone.
**The cadence is the instruction section "report-cadence"** (the operator, 2026-10-28; it replaces the full layout every
five minutes of "how-work-is-done"). Times are local and absolute, from the clock (`date`), never guessed; every number
has its unit and its bound or baseline; an issue is named by its number and a few words, never by its number alone.
**The full layout** (in the session) is the whole design as a tree (the operator, 2026-10-17: always the full
overview): every milestone of the design with its state, and under the running milestone its repositories and
their issues, each issue under the one it waits for, marked ✓ landed or delivered, ▶ fixing, ⏸ waiting, ✗ stopped:
- **Every five minutes** (ten until 2026-10-26, five since), every two minutes while a delivery moves (the view says
modules `moving`), and at once when something lands, stops or needs the operator, the lead sends the **short
report**: the tree exactly as `knowledge-base.progress` with `of: "design <nn>"` and `detail: minimal` answers it,
unedited, with the verb's read-at time, then at most three lines: what changed, what needs the operator, what is next.
Once the verb takes `since`, the short report asks `since: 5m`.
- **About every thirty minutes**, and whenever something stops, the lead sends the **detailed report**: the same verb
with `detail: detailed` (or `since: 60m`), then the full layout below.
- **Every report ends by scheduling the next** (a timer or a watcher set ahead), so that agents' incoming reports
never replace it.
- **An answer to the operator between reports is short and has no tree.**
**The tree is the verb's answer and is never drawn or corrected by hand.** `knowledge-base.progress` answers the
design's milestones, issues, pull requests and held groups in one call, each with when it last moved (issue 1947).
What it cannot read for certain from the design's milestone table it says in `warnings`; the lead fixes the table, it
does not correct the tree by hand.
**The full layout** (the detailed report) is the verb's detailed tree followed by these lines:
```
Feature <slug> · milestone <n> of <m> · step <name>, <minutes used> of <bound> min
Issues: <landed> of <total> landed · <fixing> fixing · <waiting> waiting
Design <nn> · <its title>
├── ✓ milestone 1 <its outcome, a few words> delivered 12:58
├── ▶ milestone 2 <its outcome, a few words>
│ ├── mesh-controller (agent: fixing, 2 of 3 landed)
│ │ ├── ✓ 652 assignments on the bus landed 14:02
│ │ ├── ▶ 736 placement words leave the layers fixing since 13:51, 23 of 30 min
│ │ │ └── ⏸ 751 config keys named (mesh-catalog) waits for 736
│ │ └── ✓ 654 a file names its template landed 13:20
│ └── mesh-catalog (agent: waiting)
│ └── ⏸ 751 (above, under 736)
└── ⏸ milestone 3 <its outcome, a few words> <its issues>
Opened along the way: <each issue opened during the feature, its number and a few words, and when it is fixed: in between, after the delivery, or waits on what> — or "none"
Past its bound: <the wait, how long, what is being done> — or "none"
Needs you: <one line per question, with my recommendation> — or "nothing"
Allowance: week <n> % (<+d> since the last report), session <n> %
Worth it: <what in the last stretch served the goal, and what did not>
Next: <the next actions up to the delivery, in order>
```
**The short layout** (on a channel such as Telegram, or when nothing changed but time):
How it is checked: the operator sees a short report at least every five minutes and a detailed one at least every
thirty; a report's tree that differs from the verb's answer of the same minute is a tree assembled by hand, a report
without the verb's read-at time is the same, and a report that does not end by scheduling the next is a breach the
lead reports.
```
<slug> milestone <n>/<m> · <step> <used>/<bound> min · <landed>/<total> landed · past bound: <none | what> · needs you: <nothing | what> · week <n> %
```
A report says what changed since the last one first. In the session every report is the full layout, the whole
tree of the milestone's issues included, also when only time passed: the operator reads the state from it without
asking. The short layout is for a channel.
On a channel such as Telegram the same short report is sent, the tree as a code block.
## The context of the lead's own session
At the end of each step, and whenever the session's context grows large or spread over unrelated work, the
lead prepares a `/clear` as the mesh's instruction "prepare before clear" says: a save point with the
feature's step, its branches and heads, the context files' paths, the agents' ids, the wait list and the
next action; then the prompt the operator pastes. The context files make the feature resumable after a clear.
feature's step, its branches and heads, the build maps' paths, the design questions still open, the agents' ids,
the wait list and the next action; then the prompt the operator pastes. The milestone part, the build maps and the
commits' design lines make the feature resumable after a clear.
## The design's state is written back
@@ -579,7 +824,19 @@ issues in `fixing` that nobody works on reads to the operator as stuck work.
- A feature's issues show their commits on the feature branch (`git log --grep 'issue <n>'`), and no pull
request into a feature branch exists. A pull request per issue, or an agent waiting on a merge check in
step 1, is the failure this playbook prevents.
- A context file exists per touched repository under `.work/<slug>/` while the feature runs.
- A build map exists per touched repository under `.work/<slug>/` while the feature runs, and every row cites a
design line of the milestone part.
- Every commit of the milestone names in its body the design lines it builds (`git log --format=%B | grep 'Builds:'`),
and the milestone file's `Design questions` each name the hq commit that answers it, older than step 1's first
commit.
- The milestone's part is within 60 KB and the design's main file within 80 KB (`wc -c`); a milestone developed from
a larger part is playbook 04's step 4a skipped.
- Every build map opens with `What exists today` holding step 0 item 3a's three answers, each search written as run
(`grep -n -A3 'What exists today' .work/<slug>/*.map.md`), and its time (the file's commit or the lead's note) is
older than the repository's first commit of the feature; the review report says it ran the searches again (step 2,
item 6b). A fixing agent started on a file without the section, or an effect of a removed or moved part met only
after the delivery, is the prepare step skipped, named in the next detailed report and written into the playbook's
lessons here.
- No issue of a running milestone is sized over an hour in its prepare note; an issue whose fixing agent passes
twice its bound was not split.
- Every issue of a running milestone has a note from the prepare step naming its files and tests (file:line), how
@@ -619,8 +876,13 @@ issues in `fixing` that nobody works on reads to the operator as stuck work.
- A running milestone's file holds the three answers of step 0 item 8 (`cat .work/<slug>/milestone.md`), and the
review report says it read them (step 2, item 6a): a bucket key or stream in the diff (`git diff main --
| grep -i 'bucket\|stream'`) that the lifetime answer omits is the failure of that item (research 071).
- A pull request merged by hand in a temporary mode names, in its description on the forge (`gitea.gitea_get_pull_request`), a try with
tests `.` for each repository of the group; one without is the step 3 rule skipped.
- A pull request merged by hand in a temporary mode names, in its description on the forge (`gitea.gitea_get_pull_request`), the
verdict of its one check; a try with tests `.` is named only where the operator asked for one.
- **One release, one check** (ADR 0548): `gitea.gitea_get_pull_request` shows each pull request created after its
review record's time, and `mesh-delivery.show` shows one check per head and, for a group, one head per member; a pull
request that existed before its review approved it, a second head with no failed check before it, or a check of a
head asked more than once, is this rule skipped. A call of `mesh-controller.try`, `mesh-delivery-checker.try` or `checker_try` that the operator
did not ask for shows in the checker's asks and is the same breach.
- A milestone that adds or changes a module whose pull request has no integration test that starts the module
whole is the failure of the check step's fourth item.
- A bed run from `.work/<slug>/mesh-lab` that fails naming a `.work/<slug>/<repo>/…` path it cannot find is a
+61 -30
View File
@@ -26,18 +26,34 @@ this moment): it goes alone as a small fix, and the lead's report says why.
## The aim
A small fix spends its time on the fix, and runs the long part once: **one try before the review, one review, one check run,
one delivery**. Everything before the try is local and fast.
A small fix spends its time on the fix, and runs the long part once: **one review, one push, one check run,
one delivery** (ADR 0548; the operator, 2026-10-26: "every release should only run 1 check or 1 try"; "we don't have more
processing power"). Everything before the push is local and fast, and no try is run.
## Steps
1. **Read the issue and the code it names** (the session's own model, or one read-only agent on the smaller
model answering exact questions with file:line). If a design question is open, it is settled before any
code is written: on the issue, through the knowledge base, or by the operator. A fix that turns out to
need a second repository, or more than about an hour, stops here and becomes a feature; one that needs a
decision stays a small fix. **The session's own model (the larger) then writes the issue's acceptance
model answering exact questions with file:line). **Read what exists in the fix's area today, briefly, before any
code** (playbook [07](07-feature-branches.md) step 0 item 3a, at a small fix's size): what the code and the live mesh
(through the mesh MCP server's tools) do there now, and for each value, label, file or job the fix changes or removes,
every reader that relies on it, found by a search across the repositories (written down as run) and not from memory,
with what happens to each after the fix. It is a few lines in the issue's note, under `What exists today`, and the
review runs the search again; a reader it finds that the note omits makes the fix wrong. **A fix builds what a
design says, and decides nothing** (the operator, 2026-11-10; playbook [07](07-feature-branches.md), step 0): its
input is the issue and the design that covers the area (the design whose `code:` names the repository, or the
issue's design link), read in the parts the fix touches and in the design section that places code, *Where a
seat's code goes*. The note names, for everything the fix adds or changes (an exported type, field, constant,
package or module, a state, a verb, an event, a bound, a caller), the design line that gives it. A fix that only
makes the code do what its issue and its design already say needs nothing more. Anything no design line gives is
a **design question**: the session asks the operator, one question with its recommendation, and the answer is
written into the design (playbook [02](02-graduation.md), *Answering a design question*) before any code builds
it; neither the session nor the lead answers it. A handover to the developer quotes the design lines and never
decides a placement itself (2026-11-04: a class placed in mesh-sdk by a lead's handover, against that section,
passed review and its check). A fix that turns out to need a second repository, or more than about an hour,
stops here and becomes a feature; one that needs a design question answered stays a small fix. **The session's own model (the larger) then writes the issue's acceptance
criteria** as playbook [07](07-feature-branches.md) step 0 item 5 says: each one sentence, given, when, then,
naming the level of the test that proves it, as an `issue-tracker.note` headed `Acceptance criteria`. A
naming the level of the test that proves it and the design line or issue done-when it comes from, as an
`issue-tracker.note` headed `Acceptance criteria`. A
playbook or design edit has none: its check is `go test ./...` at hq's root, which runs the four checks (ADR 0527).
2. **Move the issue to `fixing`** with `by` as who@node.
3. **Build on a local branch** `fix/<issue>-<slug>`, in a worktree of its own branched from `main`, never in
@@ -50,30 +66,38 @@ one delivery**. Everything before the try is local and fast.
caught only by the review); read `git show --stat` before pushing.
The tests are written from the acceptance criteria, at least one per criterion at its level, each citing the
criterion it proves by its label (`<issue>/AC<n>`, playbook 07 step 0 item 5). Commit, naming the issue. For a playbook or design edit, run the repository's own checks (in hq,
`go test ./...` at the root). Then push the branch and run `mesh-controller.try` on it, so the review reads the
integration tests' real results; a failed try goes back to the same agent before the review.
4. **One review of the commit and its try** (a reviewer that did not write it, larger
model; at most 3 rounds, as playbook 07; from round 2 only what is wrong; it reads each acceptance criterion
against its test, as playbook 07 step 2 item 6; a finding outside the issue's done-when and its acceptance
criteria is opened as an issue of its own, never asked as a change). The reviewer's findings go back to the same agent that wrote the fix, continued by
`go test ./...` at the root). The integration tests are compiled whole (`go vet -tags integration ./...`), and once
per head reported those of the packages the fix touches and of their importers in the module run against an
embedded bus, or the tests of them that exercise the fix by name where the importers are many, named in the report;
never a whole module's or level's run (playbook 07 step 1). Nothing is pushed, no pull request is opened and no try (`mesh-controller.try`, `mesh-delivery-checker.try`, `mesh-delivery-checker.checker_try`) is called, unless the operator asks for
one. A single integration test may be run locally against an embedded bus when it is the fastest way to find a cause;
before the push, the integration tests that exercise the change have run that way at the reviewed head
(playbook 07 step 3), and the pull request names them and their results. A test fixture writes state in the form its real
writer writes it; the review asks it.
4. **One review of the local commit** (a reviewer that did not write it, larger
model; at most 3 rounds, as playbook 07; from round 2 only what is wrong; it judges each change against the design line its note names, as playbook 07 step 2 item 2a, and code no
design line gives is a finding; it reads each acceptance criterion
against its test, as playbook 07 step 2 item 6; it runs the `What exists today` search again, as playbook 07 step 2 item 6b; a finding outside the issue's done-when and its acceptance
criteria is opened as an issue of its own, never asked as a change; it judges the integration tests by reading them against the code, as playbook 07 step 2 item 4 says; it answers playbook 07 step 2 item 10's two questions, on state and seams and on mesh-agnostic repositories, in its report). The reviewer's findings go back to the same agent that wrote the fix, continued by
its id, so the fix keeps its context. A playbook or design edit of a few lines may skip the reviewer: the
operator's Approve of its merge is its review, and the review record says so.
5. **Push the reviewed head, try it again if the review changed it, and open the pull request.** The trunk is what runs and nothing holds merged work back
(ADR 0401), so a fix waits for no other change's delivery. `mesh-controller.try` on the pushed branch runs
the integration tests, and the pull request is opened only when the head's last try passed (the pushed head is read from the forge first, as playbook [07](07-feature-branches.md) step 3 item 1 says); the checker's merge check runs
them again as the gate (playbook [07](07-feature-branches.md) step 3). A failed try or check is best run locally
first: the repository's whole integration level (`go test -tags integration -count=1 ./...` in each module) shows every
failure at once, where a verdict names only the first (issue 1921) and a try per fault costs a round each (a guideline,
the operator, 2026-10-23). The failures go back to the same agent, fixed in one change where they can be, and the
reviewer reads only the change it makes, before the next try.
5. **Push the reviewed head once and open the pull request, only after the review approves.** The trunk is what runs and nothing holds merged work back
(ADR 0401), so a fix waits for no other change's delivery. No pull request, draft or not, exists before the review
approves the head, and no fix round is pushed to an open pull request: every push to an open pull request asks a new
check. The checker's merge check runs the unit and the integration level once, as the gate (playbook [07](07-feature-branches.md) step 3); the pushed head is read from the forge first, as playbook 07 step 3 item 1 says. A merge whose check has no verdict
(the checker drops a check still running at the merge) is reported to the operator as merged unchecked, never as
passed (playbook 07 step 3 item 2).
A failed check is read from its whole log (never re-asked to see if it passes), then the repository's whole integration level
is run locally (`go test -tags integration -count=1 ./...` in each module) so every failure shows at once, where a verdict
names only the first (issue 1921); the failures go back to the same agent, fixed in one change, the reviewer reads only the change
it makes, and the head is pushed once more.
**A temporary mode that merges by hand** (the lead merges because the normal Approve and merge path is not
running): before it asks the merge, the lead runs the full integration level with nothing kept, `mesh-controller.try`
with tests `.`, and names that try (id and verdict) in the pull request's description (research 071; playbook
running): the one check still runs, and the lead names its verdict in the pull request's description; a try with tests `.` is asked only when the operator asks for one (research 071; playbook
[07](07-feature-branches.md) step 3).
6. **The pull request's description carries the review record** (`Reviewed-by: <who@node> at <full sha>`,
playbook [07](07-feature-branches.md) step 3) and the session that pushed it (`Pushed-by: <who@node>`, ADR 0505 §5), and mesh-delivery asks the operator's Approve as soon as its
checks pass and merges the approved head (ADR 0421); nobody marks, labels, comments or rechecks. A fix to a module that changes how it runs carries an
integration test starting the module whole against the real bus and store, run by `mesh-controller.try` and the checker's merge check
integration test starting the module whole against the real bus and store, run by the checker's one merge check
(ADR 0391 §1, §6); unit tests alone are not that proof, and the lab is not used. The operator's word is waited for only when the fix changes what the operator sees, removes data,
or needs the operator's terminal.
**A fix that depends on another pull request outside its delivery group opens only once that one is delivered**, not merely merged (members of one group open together, as playbook 07 step 3 item 1 says) (a note
@@ -86,13 +110,14 @@ one delivery**. Everything before the try is local and fast.
7. **Follow its delivery to done**: a watcher waits on the status view's events (`mesh-delivery-view.moving`,
`.settled`, `.stuck` and `.delivered`) and reads the view's `assigner_wants` and `node_haves` after each wake, as
playbook [07](07-feature-branches.md) step 4 says; the delivery is done when the view says `delivered` for its
source revision. Then prove the fix on the mesh (the symptom gone, measured), and resolve the issue with
source revision, and the haves per node and the indexer's record of the module name the build (playbook 07 step 4;
"on the machines" alone is not "delivered"). Then prove the fix on the mesh (the symptom gone, measured), and resolve the issue with
`located-in` and `fixed-by` the same hour.
A fix that stops before its delivery moves its issue back to `open` with a note saying how far it got
(branch, last commit, what is left), as playbook [07](07-feature-branches.md) says.
**An issue opened along the way is fixed too** (the operator, 2026-10-21). A fix's review, try or delivery that
**An issue opened along the way is fixed too** (the operator, 2026-10-21). A fix's review, check or delivery that
opens an issue (a remark outside the done-when, a fault met live) leaves it to the same session to fix: right after
this fix's delivery, as a small fix of its own, or folded into the next one in the same repository. It waits only
when another running milestone owns it, or it needs a decision or the operator first; the report then says on what.
@@ -116,10 +141,9 @@ code.
| Waiting on | Bound | Past the bound |
|---|---|---|
| building the fix | 1 hour | it is a feature: stop and plan it under playbook 07 |
| the try | 30 minutes | a try is a check ask on the language's check stream and waits behind the asks before it for a build node's free slot (ADR 0525); past the bound, read the stream's backlog and the age of its oldest ask in the delivery view |
| the review | 15 minutes | ask the reviewer where it stands |
| the merge check | 15 minutes | read `mesh-delivery.show`, the check's log and the check stream's backlog in the delivery view |
| the Approve's ask | 5 minutes after both checks pass | read `mesh-delivery.show`: an ask not raised is a fault, said to the operator |
| the merge check | 30 minutes (it waits behind the asks before it for a build node's free slot, ADR 0525) | read `mesh-delivery.show`, the check's log and the check stream's backlog in the delivery view |
| the Approve's ask | 5 minutes after the check (`mesh/check`) passes | read `mesh-delivery.show`: an ask not raised is a fault, said to the operator |
| the merge after the Approve | 5 minutes | read `mesh-delivery.show` for the delivery |
| the delivery | its class's budget (3 minutes for a leaf module, 10 for a core module), at most 30 minutes | read the view's wants page, or `assigner_wants` against `node_haves`: a want held back names its rule, a `stuck` module its words |
@@ -134,12 +158,19 @@ reading itself and uses one subagent only for the review.
- A small fix has one pull request with one or few commits naming its issue, opened after its review: a pull
request with many heads is a fix reviewed after its pull request was opened.
- A pull request merged by hand in a temporary mode names a try with tests `.` at its head in its description
- A pull request merged by hand in a temporary mode names the verdict of its one check in its description
on the forge (`gitea.gitea_get_pull_request`); one without is the step skipped.
- One fix, one check (ADR 0548): a pull request that existed before its review approved the head, or a head whose check was
asked more than once with no new reviewed head, is steps 4 and 5 skipped; so is a `mesh-controller.try` or `mesh-delivery-checker.try` the operator did not ask for.
- Its issue moves to `resolved` within the hour the view says its source revision `delivered`.
- A pull request with no review record at its head (the Approve's ask says so first), a fix to a module's
running pushed with no integration test of the module whole, or a review report
asking a change outside the issue's done-when and acceptance criteria, is the failure of steps 4 to 6.
- A fixed code issue's note names the design line for each thing the fix adds, and its commit names the same lines
(`Builds:`); a fix adding what no design line gives, with no answered design question behind it, is step 1 skipped.
- A fixed code issue shows a note with `What exists today` (`issue-tracker.get`) older than its first commit, its
search written as run; one without is step 1 skipped, and a reader of a changed value met only after the delivery
is that note left short.
- A fixed code issue shows a note headed `Acceptance criteria` (`issue-tracker.get`) older than its first
commit, and each criterion's label is cited by a test in the pushed tree
(`git grep -n '<issue>/AC<n>'`); one without is step 1 skipped.
+55 -45
View File
@@ -75,7 +75,7 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
<main>
<button class="chip theme" id="theme" type="button">Theme</button>
<h1>Novox Playbooks</h1>
<p class="sub">How work is done on the mesh, from an idea or a symptom to a delivered change. Drawn from hq's <code>00-META/process/</code> at main <code>f269e83</code>, 2026-10-19, including playbook change hq #433 (try before the review).</p>
<p class="sub">How work is done on the mesh, from an idea or a symptom to a delivered change. Drawn from hq's <code>00-META/process/</code> at main <code>f269e83</code>, 2026-10-19, amended 2026-10-26 for ADR 0548 (one release, one check: no try).</p>
<nav>
<a href="#cycle">The cycle</a>
@@ -189,7 +189,7 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
<!-- ============ FEATURE SWIMLANE ============ -->
<h2 id="feature">A feature, step by step (playbook 07)</h2>
<p class="lead">One milestone is one release: one branch name in every repository it touches, one worktree per repository, one fixing agent per repository kept for the whole milestone, one reviewer, and one pull request per repository, opened once. Since hq #433 the branches are <b>tried before the review</b>, so the reviewer reads real integration results.</p>
<p class="lead">One milestone is one release: one branch name in every repository it touches, one worktree per repository, one fixing agent per repository kept for the whole milestone, one reviewer, and one pull request per repository, opened once. Nothing is pushed or tried before the review (ADR 0548): the branches are pushed <b>once, after the review approves</b>, and the one check runs the integration tests.</p>
<div class="box scroll">
<svg viewBox="0 0 1080 430" role="img" aria-label="Playbook 07 in lanes: lead, fixing agents, reviewer, the mesh, the operator">
<defs>
@@ -198,13 +198,13 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
<!-- step columns -->
<g class="mute">
<text x="190" y="20" text-anchor="middle" class="t" style="fill:var(--mute)">0 · Prepare</text>
<text x="190" y="34" text-anchor="middle" class="mute">15 min</text>
<text x="410" y="20" text-anchor="middle" class="t" style="fill:var(--mute)">1 · Develop + try</text>
<text x="410" y="34" text-anchor="middle" class="mute">30 min per issue · one try</text>
<text x="190" y="34" text-anchor="middle" class="mute">15 min · then design complete</text>
<text x="410" y="20" text-anchor="middle" class="t" style="fill:var(--mute)">1 · Develop</text>
<text x="410" y="34" text-anchor="middle" class="mute">30 min per issue · local only</text>
<text x="630" y="20" text-anchor="middle" class="t" style="fill:var(--mute)">2 · Review</text>
<text x="630" y="34" text-anchor="middle" class="mute">≤ 3 rounds · 15 min</text>
<text x="830" y="20" text-anchor="middle" class="t" style="fill:var(--mute)">3 · Check</text>
<text x="830" y="34" text-anchor="middle" class="mute">≤ 1 more try · 1 check</text>
<text x="830" y="34" text-anchor="middle" class="mute">push once · 1 check</text>
<text x="1000" y="20" text-anchor="middle" class="t" style="fill:var(--mute)">4 · Deliver</text>
<text x="1000" y="34" text-anchor="middle" class="mute">until delivered</text>
</g>
@@ -216,54 +216,57 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
<text x="10" y="86" class="t">Lead</text><text x="10" y="102" class="mute">larger model</text>
<text x="10" y="158" class="t">Fixing agents</text><text x="10" y="174" class="mute">smaller model</text>
<text x="10" y="230" class="t">Reviewer</text><text x="10" y="246" class="mute">larger model</text>
<text x="10" y="302" class="t">The mesh</text><text x="10" y="318" class="mute">try, checks, wants</text>
<text x="10" y="302" class="t">The mesh</text><text x="10" y="318" class="mute">the one check, wants</text>
<text x="10" y="374" class="t">Operator</text><text x="10" y="390" class="mute">Telegram</text>
</g>
<!-- lead -->
<rect x="110" y="56" width="160" height="52" rx="8" fill="var(--card)" stroke="var(--dec)" stroke-width="2"/>
<text x="190" y="78" text-anchor="middle" class="t">Survey · criteria</text>
<text x="190" y="96" text-anchor="middle" class="mute">context file per repo</text>
<text x="190" y="78" text-anchor="middle" class="t">Build map · questions</text>
<text x="190" y="96" text-anchor="middle" class="mute">from the milestone part alone</text>
<rect x="340" y="56" width="140" height="52" rx="8" fill="var(--card)" stroke="var(--dec)" stroke-width="2"/>
<text x="410" y="78" text-anchor="middle" class="t">Up to trunk · push</text>
<text x="410" y="96" text-anchor="middle" class="mute">each branch</text>
<text x="410" y="78" text-anchor="middle" class="t">Up to trunk</text>
<text x="410" y="96" text-anchor="middle" class="mute">each branch, local</text>
<rect x="760" y="56" width="140" height="52" rx="8" fill="var(--card)" stroke="var(--dec)" stroke-width="2"/>
<text x="830" y="78" text-anchor="middle" class="t">Push reviewed heads</text>
<text x="830" y="96" text-anchor="middle" class="mute">open the PRs together</text>
<text x="830" y="96" text-anchor="middle" class="mute">once, PRs together</text>
<rect x="930" y="56" width="140" height="52" rx="8" fill="var(--card)" stroke="var(--dec)" stroke-width="2"/>
<text x="1000" y="78" text-anchor="middle" class="t">Follow to done</text>
<text x="1000" y="96" text-anchor="middle" class="mute">resolve the issues</text>
<!-- fixing -->
<rect x="300" y="128" width="220" height="52" rx="8" fill="var(--card)" stroke="var(--build)" stroke-width="2"/>
<text x="410" y="150" text-anchor="middle" class="t">Build each issue, commit</text>
<text x="410" y="168" text-anchor="middle" class="mute">unit suite before every commit</text>
<text x="410" y="150" text-anchor="middle" class="t">Build each design line, commit</text>
<text x="410" y="168" text-anchor="middle" class="mute">Builds: line · unit suite each commit</text>
<rect x="560" y="128" width="140" height="52" rx="8" fill="var(--card)" stroke="var(--build)" stroke-width="2"/>
<text x="630" y="150" text-anchor="middle" class="t">Fix findings</text>
<text x="630" y="168" text-anchor="middle" class="mute">the same agents</text>
<!-- reviewer -->
<rect x="560" y="200" width="140" height="52" rx="8" fill="var(--card)" stroke="var(--idea)" stroke-width="2"/>
<text x="630" y="222" text-anchor="middle" class="t">Read all repos</text>
<text x="630" y="240" text-anchor="middle" class="mute">+ tries · every criterion</text>
<text x="630" y="240" text-anchor="middle" class="mute">each change against its line</text>
<!-- mesh -->
<rect x="340" y="272" width="140" height="52" rx="8" fill="var(--card)" stroke="var(--mesh)" stroke-width="2"/>
<text x="410" y="294" text-anchor="middle" class="t">try</text>
<text x="410" y="312" text-anchor="middle" class="mute">integration tests run</text>
<text x="410" y="294" text-anchor="middle" class="t">no try</text>
<text x="410" y="312" text-anchor="middle" class="mute">nothing pushed yet</text>
<rect x="760" y="272" width="140" height="52" rx="8" fill="var(--card)" stroke="var(--mesh)" stroke-width="2"/>
<text x="830" y="294" text-anchor="middle" class="t">Forge checks</text>
<text x="830" y="312" text-anchor="middle" class="mute">gate · repo · group</text>
<text x="830" y="312" text-anchor="middle" class="mute">one check · mesh/check</text>
<rect x="930" y="272" width="140" height="52" rx="8" fill="var(--card)" stroke="var(--mesh)" stroke-width="2"/>
<text x="1000" y="294" text-anchor="middle" class="t">Merge · wants</text>
<text x="1000" y="312" text-anchor="middle" class="mute">backups first, canary first</text>
<!-- operator -->
<rect x="110" y="344" width="160" height="52" rx="8" fill="var(--card)" stroke="var(--op)" stroke-width="2.5"/>
<text x="190" y="366" text-anchor="middle" class="t">Answers each question</text>
<text x="190" y="384" text-anchor="middle" class="mute">written into the design</text>
<rect x="860" y="344" width="140" height="52" rx="8" fill="var(--card)" stroke="var(--op)" stroke-width="2.5"/>
<text x="930" y="366" text-anchor="middle" class="t">Approve</text>
<text x="930" y="384" text-anchor="middle" class="mute">once, for the group</text>
<!-- edges -->
<path class="edge" d="M190,108 C190,140 260,154 298,154" marker-end="url(#ar2)"/>
<path class="edge dash" d="M180,108 V342" marker-end="url(#ar2)"/>
<path class="edge" d="M270,370 C290,370 280,170 298,166" marker-end="url(#ar2)"/>
<text x="186" y="232" class="mute">questions</text>
<text x="276" y="262" class="mute">answered</text>
<path class="edge" d="M410,128 V110" marker-end="url(#ar2)"/>
<path class="edge" d="M480,90 C545,110 545,250 462,270" marker-end="url(#ar2)"/>
<path class="edge" d="M480,298 C530,298 540,226 558,226" marker-end="url(#ar2)"/>
<text x="490" y="262" class="mute">results</text>
<path class="edge" d="M630,200 V182" marker-end="url(#ar2)"/>
<path class="edge" d="M630,200 V182" marker-end="url(#ar2)"/>
<path class="edge dash" d="M610,182 V198" marker-end="url(#ar2)"/>
<text x="514" y="196" class="mute">round n+1</text>
<path class="edge" d="M700,226 C740,226 740,82 758,82" marker-end="url(#ar2)"/>
@@ -278,10 +281,13 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
<div class="box">
<h3>Step 0 · what the lead writes before any agent starts</h3>
<ul style="margin:6px 0;padding-left:20px;font-size:14px">
<li>Every open question settled: on the issue, in the knowledge base, or by the operator.</li>
<li><span class="tag new">new</span>The milestone part of the design is the only input: the prepare maps each design line onto code (a build map per repository, each row citing its line) and lists every design question, what the design does not answer. It writes no findings or rulings of its own.</li>
<li><span class="tag new">new</span>Design complete: the operator answers each question, the answer is written into the milestone part, and only then does develop start. Nobody else answers one.</li>
<li><span class="tag new">new</span>What exists today, read from the code and the live mesh, never from memory: every effect of a part removed or moved (bus writes, files, credentials, plans, processes, calls answered), every reader relying on each, what happens to each after the change and its test. It opens each build map; no code before it is complete, and the review refuses work without it.</li>
<li><span class="tag new">new</span>Subtasks ordered so a user starts from the commit that adds its contract; one writer per file; one placement of the siblings for every agent.</li>
<li>Into each issue: every file and test it touches (file:line), how it is checked and delivered, a group's merge order.</li>
<li><span class="tag new">new</span>Every other reader and writer of each value the change touches, each with a criterion.</li>
<li>Acceptance criteria: given / when / then, each naming its test level.</li>
<li>Acceptance criteria: given / when / then, each naming its test level and the design line it comes from.</li>
<li>Every part the change reaches is an issue of the milestone; their order is the assigner's rules', never a cut.</li>
<li>Fixtures copied from what the other side really writes, never from memory.</li>
<li>An issue sized over an hour is split before work starts.</li>
@@ -290,19 +296,22 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
<div class="box">
<h3>Step 1 · the fixing agent's brief</h3>
<ul style="margin:6px 0;padding-left:20px;font-size:14px">
<li>One commit per issue, naming it; tests cite their criterion (<code>// 1217/AC3</code>).</li>
<li><span class="tag new">new</span>Build each design line as written and nothing it does not say; every commit names its lines (<code>Builds: design NN M §n</code>).</li>
<li><span class="tag new">new</span>A question the design does not answer stops that subtask and goes to the lead for the operator; never guessed or built around.</li>
<li>One commit per subtask, naming its issue; tests cite their criterion (<code>// 1217/AC3</code>).</li>
<li><span class="tag new">new</span>A test fails first on what the code does. A compile error is no failure: take out the change's effect and see an assertion fail.</li>
<li>The whole unit suite before every commit; each test well under a second.</li>
<li>Integration tests are compiled only: never run on the machine.</li>
<li><span class="tag new">new</span>Integration tests compiled whole; once per head reported, those of the touched packages and their importers run against an embedded bus (by name where the importers are many); never a whole module's run.</li>
<li>Never push, open or merge; never move an issue; never ssh.</li>
<li>Code that differs from the context file: stop and report, file:line.</li>
<li>Code that differs from the build map: stop that subtask and report, file:line.</li>
<li><span class="tag new">new</span>Start a subtask only with room to finish it; stop between subtasks, never inside one.</li>
</ul>
</div>
</div>
<!-- ============ TESTS ============ -->
<h2 id="tests">When tests run</h2>
<p class="lead">Two levels. Unit tests run all the time on the machine; integration tests (a bus, a store or a process started) never run there: <code>mesh-controller.try</code> runs them on the pushed branch (a check ask on the language's stream), and the checker's merge check runs them again as the gate.</p>
<p class="lead">Two levels. Unit tests run all the time on the machine; integration tests (a bus, a store or a process started) are compiled there whole, and once per head reported only those of the touched packages and their importers run there, against an embedded bus, never a whole module's or level's: the checker's one merge check, asked by the one push after the review, runs them as the gate. There is no try (ADR 0548).</p>
<div class="box scroll">
<svg viewBox="0 0 1080 170" role="img" aria-label="Test levels over a feature's timeline">
<defs><marker id="ar3" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0L10,5L0,10z" fill="var(--mute)"/></marker></defs>
@@ -314,12 +323,11 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
<circle cx="160" cy="44" r="6"/><circle cx="220" cy="44" r="6"/><circle cx="290" cy="44" r="6"/><circle cx="350" cy="44" r="6"/><circle cx="420" cy="44" r="6"/><circle cx="600" cy="44" r="6"/><circle cx="680" cy="44" r="6"/>
</g>
<text x="830" y="42" class="mute">whole suite before every commit</text><text x="830" y="56" class="mute">each test under a second</text>
<text x="10" y="104" class="t">Integration</text><text x="10" y="120" class="mute">never on the machine</text>
<text x="10" y="104" class="t">Integration</text><text x="10" y="120" class="mute">touched packages only</text>
<g>
<rect x="120" y="96" width="340" height="16" rx="8" fill="var(--mute)" opacity=".18"/>
<text x="290" y="108" text-anchor="middle" class="mute">compiled only: go vet -tags integration</text>
<rect x="470" y="90" width="110" height="28" rx="6" fill="var(--mesh)"/><text x="525" y="109" text-anchor="middle" style="fill:var(--bg)" class="t">try</text>
<rect x="770" y="90" width="120" height="28" rx="6" fill="none" stroke="var(--mesh)" stroke-width="2" stroke-dasharray="5 4"/><text x="830" y="109" text-anchor="middle" class="mute">try again if changed</text>
<text x="290" y="108" text-anchor="middle" class="mute">compiled whole; touched packages run</text>
<rect x="770" y="90" width="120" height="28" rx="6" fill="none" stroke="var(--mesh)" stroke-width="2" stroke-dasharray="5 4"/><text x="830" y="109" text-anchor="middle" class="mute">push once</text>
<rect x="920" y="90" width="120" height="28" rx="6" fill="var(--mesh)"/><text x="980" y="109" text-anchor="middle" style="fill:var(--bg)" class="t">merge check</text>
</g>
</svg>
@@ -332,7 +340,7 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
<svg viewBox="0 0 520 300" role="img" aria-label="The review loop: at most three rounds">
<defs><marker id="ar4" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0L10,5L0,10z" fill="var(--mute)"/></marker></defs>
<rect x="20" y="20" width="150" height="54" rx="8" fill="var(--card)" stroke="var(--idea)" stroke-width="2"/>
<text x="95" y="44" text-anchor="middle" class="t">Round n of ≤ 3</text><text x="95" y="62" text-anchor="middle" class="mute">code + tries + criteria</text>
<text x="95" y="44" text-anchor="middle" class="t">Round n of ≤ 3</text><text x="95" y="62" text-anchor="middle" class="mute">code + criteria</text>
<polygon points="300,20 380,47 300,74 220,47" fill="var(--card)" stroke="var(--mute)"/>
<text x="300" y="51" text-anchor="middle" class="t">Wrong?</text>
<rect x="400" y="20" width="110" height="54" rx="8" fill="var(--okbg)" stroke="var(--ok)" stroke-width="2"/>
@@ -357,10 +365,12 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
<h3 style="margin-top:12px">What every round reads</h3>
<ul style="margin:6px 0;padding-left:20px;font-size:14px">
<li>Every criterion against its test: a test at its level that would fail without the change.</li>
<li>Every new integration test traced through the code, and its try's result.</li>
<li>Every new integration test traced through the code by reading it: a local run of the touched packages shows only that it passed.</li>
<li>That each integration test enters by the path the live trigger takes.</li>
<li>Where each piece of state lives and how each seam travels: anything but bus state, a stream or a seat's verb is a finding, even if a record put it there.</li>
<li>That no repository holds this mesh's setup (node names, placement, settings): repositories are mesh-agnostic.</li>
</ul>
<div class="note" style="margin-top:10px">Why reviews took more than one round (R3b, 2026-10-19): a test that "failed" only by not compiling, a reader of the changed record the survey missed, and bus tests judged by reasoning before they ran. hq #433 changes all three.</div>
<div class="note" style="margin-top:10px">Why reviews took more than one round (R3b, 2026-10-19): a test that "failed" only by not compiling, a reader of the changed record the survey missed, and bus tests judged by reasoning before they ran. ADR 0548 and playbook 07 step 2 item 4 change the last: bus tests are judged by reading them against the code, and the one check runs them after the review.</div>
</div>
</div>
@@ -417,15 +427,15 @@ const P = [
{n:"01",name:"Research",kind:"idea",c:"--idea",
trig:"An idea worth investigating before it is committed to design. A symptom is not research.",
who:"The session that heard the idea leads.",
steps:["Read what is known: ask, get, the tracker's list.","Ask 3 to 5 setup questions, one at a time, each with a recommendation.","Check every option against the mission and how-we-build first.","Reserve a number (kind research), never pick one by hand.","Propose the effort: overview, questions, method, with links.","Research; findings in 04-findings, one version per settled set.","Try at the cheapest level that answers the question.","Write 03-domains: modules, seats, glossary words added or retired.","Write 05-direction: decisions, rejected options, acceptance tests.","Ask the operator to confirm the direction, one point at a time.","If the review asks changes: propose again, at most three times."],
steps:["Read what is known: ask, get, the tracker's list.","Ask 3 to 5 setup questions, one at a time, each with a recommendation.","Check every option against the mission and how-we-build first.","Write the numbered requirements from the answers, each with its check, before any option.","Reserve a number (kind research), never pick one by hand.","Propose the effort: Overview, Requirements, Questions, Method, sections named by title, no file references.","Research; findings in the section Findings, one version per settled set.","Try at the cheapest level that answers the question.","Write the Domains: modules, seats, glossary words added or retired.","Write the Direction: decisions, rejected options, acceptance tests.","Ask the operator to confirm the direction, one point at a time.","Review the direction by architectural domain: security, seams, running qualities, health, events and logs, testing, upgrade, tools.","If the review asks changes: propose again, at most three times."],
prod:"A research effort in the knowledge base, status active, every version kept. Nothing in hq.",
next:"02",bounds:"Setup 30 min · proposing 15 min · each experiment 30 min · direction 30 min · report every 10 min",
next:"02",bounds:"Setup 30 min · proposing 15 min · each experiment 30 min · direction 30 min · review by architectural domain 20 min · report every 10 min",
prev:["Research that measured nothing","A recommendation the operator must argue back","Efforts copied into hq"],
check:"propose refuses rule breaks; the knowledge base reviews; the records test on every PR."},
{n:"02",name:"Graduation & design change",kind:"idea",c:"--dec",
trig:"A research effort concludes, or an existing design must change.",
who:"The lead, on the larger model; the decision is recorded before the design moves.",
steps:["Check the conclusion against mission, context and effect.","Reserve a number per decision.","Propose one record per choice that can be reversed on its own.","Pre-check, then propose siblings together.","On changes: revise whole; after three rounds fix findings yourself.","A finding that would change what was decided: ask the operator.","needs-operator: wait for the operator's Approve.","Amend the design, or create a to-be design with status designed.","Add the decisions, updated:, and the effort's glossary words.","Hand the design to the breakdown (04).","Close the effort: graduated with became links, or abandoned.","When it ships: write the as-is, set the to-be implemented."],
steps:["Check the conclusion against mission, context and effect.","Reserve a number per question the effort answers.","Propose one record per question: its options and the one chosen; design choices go in the design.","Pre-check, then propose siblings together.","On changes: revise whole; after three rounds fix findings yourself.","A finding that would change what was decided: ask the operator.","needs-operator: wait for the operator's Approve.","Amend the design, or create a to-be design with status designed: a main file and a part per milestone, leaving the builder no choice. (new)","A design question: the operator answers, written as a design line. (new)","Add the decisions, updated:, and the effort's glossary words.","Review the design by architectural domain before it is merged.","Hand the design to the breakdown (04).","Close the effort: graduated with became links, or abandoned.","When it ships: write the as-is, set the to-be implemented."],
prod:"Decision records; a to-be design with frontmatter; glossary entries; later the as-is.",
next:"04",bounds:"One sitting of about an hour",
prev:["A decision rewritten silently","A deferral nothing tracks","A design amended without a decision"],
@@ -441,7 +451,7 @@ const P = [
{n:"04",name:"Work breakdown & handoff",kind:"idea",c:"--dec",
trig:"A to-be design is settled and its building is about to start.",
who:"The lead who will run the feature, on the larger model.",
steps:["Confirm status designed; each decision traces to a record.","An open question remains: back to research.","Set code: to the owning repositories.","Read the as-is; write it first if it does not say what is replaced.","Write the Milestones: outcome, acceptance tests, repositories.","Cut milestones by functionality, never by an order between parts; fold any not usable alone.","Ask the operator to confirm the milestones.","Open one issue per repository part, linked depends-on.","Write the issue numbers into the design; flip to in-progress.","Hand each milestone to 07, one at a time, one design at a time."],
steps:["Confirm status designed; each decision traces to a record.","An open question remains: back to research.","Set code: to the owning repositories.","Read the as-is; write it first if it does not say what is replaced.","Write the Milestones: outcome, acceptance tests, repositories.","Cut milestones by functionality, never by an order between parts; fold any not usable alone.","Give each milestone its part: numbered design lines, at most 60 KB; the main file at most 80 KB. (new)","Ask the operator to confirm the milestones.","Open one issue per repository part, linked depends-on.","Write the issue numbers into the design; flip to in-progress.","Hand each milestone to 07, one at a time, one design at a time."],
prod:"Milestones in the design; issues per repository part; the design in-progress.",
next:"07",bounds:"One sitting · one design built at a time · a milestone is one release",
prev:["Building without a breakdown","Building against an undocumented as-is","Deferrals with no owning issue"],
@@ -465,17 +475,17 @@ const P = [
{n:"07",name:"Features",kind:"build",c:"--build",
trig:"Work that changes code across issues or repositories, too large for a small fix.",
who:"A lead (larger model), one fixing agent per repository (smaller), one reviewer (larger).",
steps:["Prepare: name the branch, make the worktrees, settle every question.","Write one context file per repository.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Answer three questions in the milestone file: who deletes each new key and stream, how the switch-over is tried on one node first, how the integration level runs before the pull requests. The review checks them. (new)","List every part the change reaches; copy fixtures from the real writer.","Develop: one agent per repository, one commit per issue.","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk, push, and try it. (new)","Review all of it with the tries' results; at most 3 rounds.","Push the reviewed heads and read each forge head against the reviewed commit; try again only what changed.","A merge by hand in a temporary mode first runs a try with tests \".\" and names it in the pull request. (new)","Open one pull request per repository, together, with Reviewed-by and Pushed-by.","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery in the status view (moving, settled, stuck, delivered) to done; resolve the issues; clean up. (new)","When the builder cannot deliver its own fix: revert, a build by a session's call, a registration at the terminal, copies kept outside the store; a broken controller is put back by a want the operator writes, a hand build by mesh-hand-compose and a want. (new)"],
steps:["Prepare: name the branch, make the worktrees, read the milestone part and the design's main file whole. (new)","Every agent is one of hq's definitions (mesh-preparer, mesh-developer, mesh-code-reviewer, mesh-watcher); the lead writes only the handover. (new)","The prepare's only output: a build map per repository, each row a design line and where it lands, and the design questions. No rulings. (new)","Design complete: the operator answers every question, each written into the milestone part; then develop. (new)","Read what exists today from the code and the live mesh: every effect of what is removed or moved, every reader of each, what happens to each and its test. No code before it is complete; the review refuses work without it. (new)","The build map opens with what exists today; subtasks ordered contract first, one writer per file.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Answer three questions in the milestone file: who deletes each new key and stream, how the switch-over is tried on one node first, what the one check does not cover. The review checks them. (new)","List every part the change reaches; copy fixtures from the real writer.","Develop: one agent per repository, one commit per subtask, each citing its design lines; a question stops only its subtask. (new)","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk; nothing is pushed, no try runs. (new)","Review all of it against the design lines, code no line asks for a finding, reading the integration tests against the code; at most 3 rounds; the report answers the state-and-seams and mesh-agnostic questions. (new)","A group pins the group's own mesh-sdk head in every member. (new)","Push the reviewed heads once and read each forge head against the reviewed commit; no draft pull request, no fix round on an open one. (new)","Open one pull request per repository, together, with Reviewed-by and Pushed-by; the one check runs. A failed check is read, fixed, reviewed, pushed once more. (new)","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery in the status view (moving, settled, stuck, delivered) to done; resolve the issues; clean up. (new)","When the builder cannot deliver its own fix: revert, a build by a session's call, a registration at the terminal, copies kept outside the store; a broken controller is put back by a want the operator writes, a hand build by mesh-hand-compose and a want. (new)"],
prod:"One pull request per repository, one source revision delivered, resolved issues, no branch or worktree left.",
next:"02 (when it ships)",bounds:"Prepare 15 min · 30 min per issue · review 15 min, ≤ 3 rounds · one try and one check",
prev:["Pull requests as scratchpads","Context bought again and again","Review rounds spent on what a run would show"],
next:"02 (when it ships)",bounds:"Prepare 15 min · 30 min per issue · review 15 min, ≤ 3 rounds · one check, pushed once",
prev:["Pull requests as scratchpads","Context bought again and again","A change built on what was remembered, not on what runs","Review rounds spent on what a run would show","A node agent's bus reads, proven only by review"],
check:"The checker's one status, mesh/check; the review record; the tracker's move."},
{n:"08",name:"Small fixes",kind:"build",c:"--build",
trig:"One issue in one repository, about an hour of work.",
who:"The session, with one reviewer on the larger model.",
steps:["Read the issue and the code; settle any open question.","Write the acceptance criteria.","Move the issue to fixing.","Build on fix/<issue>-<slug> in its own worktree.","A test that fails today first, on behaviour. (new)","Push and try before the review. (new)","One review of the commit and its try.","Push the reviewed head; open the pull request.","The operator's Approve; the merge; the delivery, followed in the status view. (new)","Prove the fix live and resolve the same hour.","During a milestone: ride in its delivery group, unless broken for the operator now. (new)"],
steps:["Read the issue, the design lines it builds and the code; a design question goes to the operator and into the design before code. (new)","Read what exists in the fix's area today, briefly: every reader of what the fix changes. (new)","Write the acceptance criteria.","Move the issue to fixing.","Build on fix/<issue>-<slug> in its own worktree.","A test that fails today first, on behaviour. (new)","Nothing is pushed and no try runs before the review. (new)","One review of the local commit.","Push the reviewed head once; only then open the pull request. (new)","The operator's Approve; the merge; the delivery, followed in the status view. (new)","Prove the fix live and resolve the same hour.","During a milestone: ride in its delivery group, unless broken for the operator now. (new)"],
prod:"One pull request, one delivery, a resolved issue.",
next:"—",bounds:"About an hour · one try before the review, one review, one check",
next:"—",bounds:"About an hour · one review, one push, one check",
prev:["A fix reviewed after its pull request opened","A long part run twice","A fix waiting on someone else's delivery","Ten SDK merges and eight controller merges in a day, one per fix"],
check:"The checker's status; the review record; the tracker's move; one delivery group and one source revision per milestone."},
{n:"09",name:"Cleanup",kind:"side",c:"--side",
+2 -2
View File
@@ -14,7 +14,7 @@ and a forge address is an operational detail (see [`README`](../README.md)).
| Repository | Owns |
|---|---|
| `hal` | The monorepo — the node runtime, the module catalogue, the delivery machinery, and the bootstrap scripts. Every core module lives here. |
| `hal` | The monorepo — the node runtime, the module catalog, the delivery machinery, and the bootstrap scripts. Every core module lives here. |
| `hq` | This repository, under the company organisation — mission, research, design, decisions, issue diagnosis. Company-scoped (ADR 0019); the mesh is its first product. The source of truth for *why*. Carries no implementation. |
| *(one per application)* | Every standalone application, site or side-project gets its own repository, with `module.yml` at the root. Registered with the mesh as a build source; built and deployed by the same pipeline as anything in the monorepo. |
| `migration` | **Private.** The record of one installation replacing the predecessor mesh with this one: the runbook, a dated log of every step and what it cost, the per-service data procedures, the readiness checks, and the scripts. Private because it is the opposite of this repository in every way that matters — it names machines, addresses, ports and paths, because a procedure that cannot be followed is not one. Where hq asks *what did we decide and why*, that repository answers *what happened on the machines, in what order, and what to do next*. Its `HANDOFF.md` is where somebody picking the work up starts. |
@@ -48,7 +48,7 @@ Named by role, because the layout is itself part of the as-is design — see
| Area | Holds |
|---|---|
| Module catalogue | One directory per module, each with a manifest. Core modules sit under the mesh's own namespace; everything else at the top level. |
| Module catalog | One directory per module, each with a manifest. Core modules sit under the mesh's own namespace; everything else at the top level. |
| Node runtime | The daemon and interactive runtime that every node runs. |
| Bootstrap scripts | First-node initialisation, joining an existing mesh, and node rescue. |
| Shared library | The SDK every module builds against. |
+1 -1
View File
@@ -11,7 +11,7 @@ decisions:
# The mesh as it stands
A set of machines, each running the same runtime, each loading only the parts of the catalogue
A set of machines, each running the same runtime, each loading only the parts of the catalog
it has been assigned. They hold no shared filesystem and make no direct connections to one
another. What makes them a mesh is a database that knows what should run where, and a message
broker that carries everything between them.
@@ -105,9 +105,9 @@ the resource rather than on the node that built the module.
## A documented rule with no enforcement
Every module exposing capabilities is documented as required to declare the mesh's core runtime
as a dependency. **Zero of the catalogue's modules do.**
as a dependency. **Zero of the catalog's modules do.**
This is recorded here rather than quietly corrected, because it is the clearest instance of the
rule this repository states about itself: a rule whose enforcement does not exist is
indistinguishable from a wrong one, and costs more, because people believe it. Whether the rule
or the catalogue is wrong has not been decided.
or the catalog is wrong has not been decided.
@@ -24,7 +24,7 @@ is what makes a node a participant — it is reachable whether or not anyone is
protocol. Its capability surface is larger, because it includes stand-ins for every capability
discovered on peers.
The two are the same code with the same catalogue. A capability is written once and is
The two are the same code with the same catalog. A capability is written once and is
available to both.
## Anatomy naming, and what it obscures
@@ -52,7 +52,7 @@ For each assigned module the runtime, at startup:
4. For a service module, ensures it is installed and running.
Installation is idempotent and does the unglamorous work: ensure the runtime directory,
reconcile the link from the catalogue's definition into it, generate the environment, run any
reconcile the link from the catalog's definition into it, generate the environment, run any
outstanding local migrations, create data directories with the right ownership, then start the
service under supervision.
@@ -85,7 +85,7 @@ import is one-time and not persisted.
Three bootstrap scripts, and which one runs depends on the situation:
- **First node.** Nothing exists yet, so the script stands up the database the rest of the
mesh reads from, publishes the catalogue, and starts the mesh. This resolves the
mesh reads from, publishes the catalog, and starts the mesh. This resolves the
circularity of a mesh whose source of truth is itself a provisioned module.
- **Joining.** The node registers, takes its assignment from the database, and syncs.
- **Rescue.** A node that cannot reach the mesh is brought back far enough to.
+8 -8
View File
@@ -9,9 +9,9 @@ decisions:
- "ADR 0009"
---
# The catalogue, and what its shape says
# The catalog, and what its shape says
The catalogue holds **124 modules**. Thirty-three belong to the mesh's own domain; the other
The catalog holds **124 modules**. Thirty-three belong to the mesh's own domain; the other
ninety-one run *on* the mesh rather than being *of* it
(ADR 0001).
@@ -30,7 +30,7 @@ By namespace, and the namespace records origin rather than purpose:
## What the flat level actually contains
Grouped by what they are *for* — a grouping the catalogue itself does not express:
Grouped by what they are *for* — a grouping the catalog itself does not express:
| Purpose | Roughly |
|---|---|
@@ -51,7 +51,7 @@ connectivity is made four times.
## What the shape records
**The catalogue's shape records what was installed, not what anything is for.** One module is
**The catalog's shape records what was installed, not what anything is for.** One module is
the unit of one piece of software, because that is the only granularity the module system
offers.
@@ -64,7 +64,7 @@ deliberately does not yet settle the domain list.
## Where the shape came from
The catalogue's shape is not arbitrary and it is not a series of mistakes. **This repository
The catalog's shape is not arbitrary and it is not a series of mistakes. **This repository
began as a dotfiles repository**, and most of what looks inexplicable is inherited from that
directly.
@@ -88,7 +88,7 @@ The generalisation from *place files on my machines* to *manage a mesh of nodes*
move and it worked. What it did not do is revisit the assumptions underneath, because they were
never stated as assumptions — they were just how the thing already worked.
**This is the most useful single fact for anyone changing the catalogue**, and it is why the
**This is the most useful single fact for anyone changing the catalog**, and it is why the
linking principle in particular reads as a deliberate architectural choice when it is an
inheritance. See ADR 0012, whose case
this strengthens: the argument for links was never made *for a mesh*.
@@ -109,10 +109,10 @@ module out of the repository safe.
**Placement is already decided.** A standalone application belongs in its own repository
(ADR 0015), and reviewers reject
it in the monorepo. The catalogue's flat level is not a dumping ground by policy; it is one by
it in the monorepo. The catalog's flat level is not a dumping ground by policy; it is one by
history.
## Known inconsistencies in the catalogue itself
## Known inconsistencies in the catalog itself
Recorded because a reader will meet them:
+2 -2
View File
@@ -11,7 +11,7 @@ decisions:
# The seats, as they run
Written from the controller's code and the catalogue's manifests on their main branches. This is
Written from the controller's code and the catalog's manifests on their main branches. This is
the second piece of the new shape to exist, after [the lab](11-the-lab.md), and the first that the
predecessor has no equivalent of: there, any well-formed name became a seat by being claimed.
@@ -24,7 +24,7 @@ have; nothing else can add to it.
Five seats deliver a provision: the mesh's store delivers the relational database, the mesh's broker
the message transport, the artifact-store seat the registry, and two more the package registry for
one ecosystem and the git service. The remaining nine — the controller and catalogue seats, and the
one ecosystem and the git service. The remaining nine — the controller and catalog seats, and the
node-scope ones for the builder, the DNS port, the packet filter, intrusion prevention, the
private network, the resolver's configuration and the showcase — mark a role without answering for
anything a consumer requires.
+3 -3
View File
@@ -21,7 +21,7 @@ decisions:
**The `mesh-console` container no longer exists.** Read 2026-10-17 from `mesh-tools` (package
`node-tools`), `mesh-host` and `mesh-controller` on their forges' main, and from the live mesh
through `mesh_overview`, `mesh_machine`, `mesh_runtimes` and `mesh_describe`. Checked: the
catalogue (`mesh-catalog`) carries no module named `mesh-console` any more — the name survives only
catalog (`mesh-catalog`) carries no module named `mesh-console` any more — the name survives only
in the glossary's retired-words list and in a test fixture — and none of the four nodes answers a
module of that name. How the tool runner reaches a node, its count of modules and tools and the
controller's verbs were read again on 2026-10-26, after the delivery of release 6 (ADR 0539).
@@ -120,11 +120,11 @@ to-be document still describes it as assigned to "whichever machines an operator
actually runs is the opposite — every node the mesh holds carries one, because it is core
infrastructure the mesh itself depends on (discovery, the controller's own verbs, every module's
tools), not a convenience assigned to a workstation. There is accordingly no assign or unassign verb
for it: removing it from a node is not an operation the controller or the catalogue exposes.
for it: removing it from a node is not an operation the controller or the catalog exposes.
## What this repository's prior text got wrong
The document this replaces described `mesh-console` as a catalogue module served by a container and
The document this replaces described `mesh-console` as a catalog module served by a container and
assigned only to workstations. That module and its container are gone; the manifest is not — it
moved to `node-tools/module.json`, still declares `invokes: ["*"]`, and gained `waits` and the
`mcp-endpoint` provision, described above. What also moved is which language builds it: the
+2 -2
View File
@@ -18,7 +18,7 @@ machine and its licence manager; on the day this was written, three buckets exis
## What runs
- **The controller** creates a key-value bucket `<module>_<name>` for every declared state, from the
catalogue — on every start and, since the first module that declared state found it missing, on every
catalog — on every start and, since the first module that declared state found it missing, on every
push before the memberships that name it. A bucket nothing declares any more is reported and kept.
Every bucket carries the mesh's caps: 256 KiB a value, 64 MiB a bucket.
- **The grants**: the machine's runtime is granted, for each bucket a module it carries owns, writing
@@ -46,7 +46,7 @@ machine and its licence manager; on the day this was written, three buckets exis
## How it is checked
The controller's catalogue and broker tests (names, grants, memberships, a bucket asserted in place
The controller's catalog and broker tests (names, grants, memberships, a bucket asserted in place
against a real server); the runtime's tests over a real bus (current values without deletions, refusals,
the TypeScript SDK through the runtime); `module check` names a read whose owner on the shelf keeps no
such state.
@@ -15,7 +15,7 @@ decisions:
**A node record names at most two logins: the operator account, always, and an agent account, on one node of
four. Where a node names no agent account, agents run as the operator account. Nothing ties an identity to a
login, and a module that needs one declares it itself.** Read on 2026-10-17 from the controller's and the
catalogue's code on main (both local clones were a few commits behind the forge, so each claim below was
catalog's code on main (both local clones were a few commits behind the forge, so each claim below was
also checked against a live read) and from the live node records. The change planned in ADR 0411 to 0414
replaces this document when it is built.
@@ -113,4 +113,4 @@ Not here: see [`16-logins-on-the-bus.md`](16-logins-on-the-bus.md).
tools for its status.
- `knowledge-base.get` with `kind` decision and number 266, 409 or 410; `issue-tracker.get` with 989 or 991.
- The code: the controller's node-record and agent-account files, and the `claude-code` module's manifest and
guard in the catalogue. Their unit tests hold the node record's refusals and the guard's account rule.
guard in the catalog. Their unit tests hold the node record's refusals and the guard's account rule.
+1 -1
View File
@@ -18,7 +18,7 @@ Where the two disagree, the implementation wins and the disagreement is stated.
| [`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 |
| [`10-module-catalogue.md`](10-module-catalogue.md) | The catalog's shape, and what its shape says |
| [`11-the-lab.md`](11-the-lab.md) | The lab — the first piece of the new shape that exists, and what it does not yet do |
| [`12-the-seats.md`](12-the-seats.md) | The seats the mesh defines, who holds one, and where a seat changes resolution |
| [`13-the-console.md`](13-the-console.md) | The mesh's tools on the machine a person sits at, served by a module the mesh assigned there |
+8 -8
View File
@@ -431,17 +431,17 @@ It is the same rule the node-engine follows about a service that does not exist
(ADR 0004) — absence must be distinguishable
from a failure to answer — applied to coverage instead of to a machine.
## A bed reads the catalogue it proves
## A bed reads the catalog it proves
*Written 2026-09-21, from resolving [04-ISSUES/073](../../04-ISSUES/073-beds-carry-copies-of-catalogue-manifests/00-report.md);
decided in ADR 0089.*
The rule above — the run rebuilds what it tests — was held for binaries and images and not for
manifests. Beds built the manifests they install inline, as literals copied from the catalogue
when each bed was written; the copies did not move when the catalogue did, and a catalogue change
manifests. Beds built the manifests they install inline, as literals copied from the catalog
when each bed was written; the copies did not move when the catalog did, and a catalog change
was proven by no bed at all, while every bed stayed green against its copy.
**A bed that installs a catalogue module reads that module's manifest from the catalogue the run
**A bed that installs a catalog module reads that module's manifest from the catalog the run
was pointed at.** It rewrites what the lab must — a build artifact becomes the image the machine
holds, an image is pinned, a host port is remapped where one machine carries colliding modules,
an address may point at a stand-in the bed raises — and nothing else.
@@ -451,15 +451,15 @@ server, a secret in the environment, a requirement edge cut so no second provide
that is a mesh test. It does not get a name of its own if it runs the module's runtime — a
module's name is its tool namespace and its broker scope
(ADR 0093) —
so it reads the catalogue and installs what the module requires; a name of its own is for a
so it reads the catalog and installs what the module requires; a name of its own is for a
fixture that runs no real runtime.
**The receipt names the catalogue's commit** with the others', so a run taken before a manifest
**The receipt names the catalog's commit** with the others', so a run taken before a manifest
changed says so — the same rule as for the binaries, for the same reason.
*How it is checked:* a unit test in the lab refuses an inline manifest literal that names a
catalogue module unless the bed is declared, with its reason, in the test's own list, and refuses
a declaration for a copy that is gone; the receipt test asserts the catalogue is claimed whenever
catalog module unless the bed is declared, with its reason, in the test's own list, and refuses
a declaration for a copy that is gone; the receipt test asserts the catalog is claimed whenever
the run is pointed at one.
## Consequences
+1 -1
View File
@@ -31,7 +31,7 @@ offered one driver, everything worked, and snapshots took **seventy-six times lo
needed to. Nothing failed. Nothing warned. A lab in that state runs correctly and is simply too
slow to use — and the inner loop it exists to provide quietly does not exist.
The second is the more dangerous shape and it is a variant the mesh has not catalogued before.
The second is the more dangerous shape and it is a variant the mesh has not cataloged before.
Its usual failure is *reported success and did nothing*. This is **reported success and did it
seventy-six times slower**, which no error surface catches because nothing is wrong.
+1 -1
View File
@@ -177,7 +177,7 @@ raises the bootstrap forge under the forge module's container name, with the mod
its data directory, so the module holds it by the found rule; the network is the one difference a take
has left to say. *How it is checked:* a host test joins a kept network and refuses one it cannot; a
host test keeps a left-out module's record and hold and removes an absent module's; a bootstrap test
holds the installer's constants to the module's manifest where the catalogue is checked out beside it.
holds the installer's constants to the module's manifest where the catalog is checked out beside it.
**What filters the machine, and the found firewall kept retired** — revision, 2026-10-02
(ADR 0168). The node-engine
+1 -1
View File
@@ -326,7 +326,7 @@ shape moves — it names a thing and the node-engine fetches it — and the cont
genesis must raise before the controller can exist. It still raises one, for the store and the broker,
which is where somebody else's software belongs.
The mesh's own components — the node-engine, the controller, the catalogue, the builder, the vault — are
The mesh's own components — the node-engine, the controller, the catalog, the builder, the vault — are
delivered as binaries into directories named for their versions, by the mechanism
ADR 0141 describes. Third-party
software stays a container. The split is not about isolation; it is about who built the thing.
+5 -5
View File
@@ -425,8 +425,8 @@ time.*
A network manager rewrites `/etc/resolv.conf` on every connectivity change unless it is told not to
(ADR 0117), so the module holding
`node-uplink` — the one telling it — writes the file itself, and there is one owner for it, the one
whose program would otherwise overwrite it. Each of the catalogue's managers' modules
(NetworkManager, systemd-networkd; dhcpcd's left the catalogue with
whose program would otherwise overwrite it. Each of the catalog's managers' modules
(NetworkManager, systemd-networkd; dhcpcd's left the catalog with
ADR 0226, held by no machine) renders the same template from the resolver's holders and
requires the mesh's resolver, so a machine is refused when nothing in the mesh resolves rather than
given a file listing nothing. The managers' own mechanisms were weighed and not used: NetworkManager's
@@ -440,7 +440,7 @@ node declaring one path are refused. The module that wrote the file before, its
retire. The file changes owner in one apply on each machine: the node-engine hands a whole file to the
resource declaring its path now rather than removing it first, so a machine is never without it.
*Checked by the controller's tests that the uplink modules carry one identical template and that
nothing else in the catalogue writes the path, a resolution test refusing a second writer, and the
nothing else in the catalog writes the path, a resolution test refusing a second writer, and the
node-engine's handover test, in which the file is present at every step of the apply.*
**A machine's names are one seat's** (ADR 0223).
@@ -643,7 +643,7 @@ to stop working.*
### The name is a label, not a domain
*2026-09-09, from running the whole mesh in the lab.* A route contribution carried its public name
in full — the forge as `git.example.tld`, spelt out in the module. Pointing the same catalogue at a
in full — the forge as `git.example.tld`, spelt out in the module. Pointing the same catalog at a
different domain — a lab standing in for production, or a second operator's mesh — meant rewriting
that name on every routed module. The mesh was holding a **map of names to services**, which is the
one thing it must not: a public name is two facts owned by two different places, and neither is the
@@ -976,7 +976,7 @@ run-once step before it starts. The step names the binding it reads and the prox
step, so when the authority moves the root is fetched again and the proxy is recreated with it
(ADR 0099).
*How it is checked:* the route-forwarding bed installs the authority, the proxy and a consumer
from the catalogue and asserts the routed name is served.
from the catalog and asserts the routed name is served.
**And a machine trusts that authority because a module put its root in its trust store**
(ADR 0147). The proxy's fetch
+10 -10
View File
@@ -57,10 +57,10 @@ produced from there. A module whose path is the repository root is the ordinary
not a separate shape.
*Corrected 2026-09-12. This section previously said the manifest was at the root, full stop, which
made a repository hold exactly one module. Nothing that exists is shaped that way: the catalogue
made a repository hold exactly one module. Nothing that exists is shaped that way: the catalog
holds sixty-seven modules in their own directories, the system being replaced has always built a
module from a repository and a path, and the root-only reading left every existing module
unbuildable — pointed at the catalogue the builder finds no manifest, pointed at a module's source
unbuildable — pointed at the catalog the builder finds no manifest, pointed at a module's source
it finds no manifest either.*
## A manifest is checked where it is written
@@ -84,7 +84,7 @@ read without a store (ADR 0122
keeps the store authoritative, so a claim on a mesh seat is judged fully only at registration, and the
check says that too).
*How it is checked:* the controller's test runs the check over the catalogue checkout beside it and
*How it is checked:* the controller's test runs the check over the catalog checkout beside it and
over a manifest with a known fault, and asserts the first passes and the second names the fault; the
test that used to be the only check, `TestEveryCatalogueManifestParses`, now stands beside a command
anybody can run.
@@ -218,7 +218,7 @@ for, arrived at by an implementation detail.
until it is told otherwise; the mesh changing its mind is not a machine acting on it, and
collapsing the two is how a mesh comes to report success for something that has not happened.
*Checked end to end: a commit, a build, a catalogue entry, and a machine that ends up running what
*Checked end to end: a commit, a build, a catalog entry, and a machine that ends up running what
the source says — with both halves that make the answer trustworthy. It is still running the old
one until it is pushed, and it stops being reported as behind once it has caught up, because a
status that says "behind" for ever is one nobody reads.*
@@ -398,7 +398,7 @@ that distinction once already.*
## The four the loop cannot build
*2026-09-12. Written down because it keeps being rediscovered as if it were new, once per
component. It is one rule; the instances are listed below. Revised the same day, when the catalogue
component. It is one rule; the instances are listed below. Revised the same day, when the catalog
gained an owner and turned out to be a fourth — which is the argument for stating the rule rather
than the list.*
@@ -412,23 +412,23 @@ have a route and one does not:
| The controller | It is what installs modules. Nothing can install it before it runs. | **Carried inside the installer** and published once there is a registry (ADR 0067) |
| The registry | It *is* where artifacts are delivered from. A store cannot be delivered through itself. | **Pulled from the public internet** — its image is an ordinary public one, never built ([`04-ISSUES/029`](../../04-ISSUES/029-the-artifact-store-cannot-be-delivered-by-the-artifact-store/00-report.md)) |
| The builder | It is what builds. Nothing builds it before it runs. | Built at genesis by the init builder (ADR 0070) |
| The catalogue | It owns the module graph, and nothing can be resolved or installed without it. | Built at genesis by the init builder (ADR 0070) |
| The catalog | It owns the module graph, and nothing can be resolved or installed without it. | Built at genesis by the init builder (ADR 0070) |
**How they arrive is settled and not yet built.** The installer carries an init builder, which
clones the source and builds the controller, the catalogue and the builder before a mesh exists
clones the source and builds the controller, the catalog and the builder before a mesh exists
to install anything. Two things about that are open and named in
ADR 0070: where the init builder
clones from, given the forge normally runs on the mesh it would be rebuilding, and what it
publishes into, given the registry is installed later in the order today.
**There is a fourth, and the list was closed too early.** The catalogue owns the module graph
**There is a fourth, and the list was closed too early.** The catalog owns the module graph
(ADR 0070), so it cannot be
installed by something that needs it in order to install anything — the same shape as the other
three. This section previously said the list was closed at three, which was written before the
catalogue had an owner and is corrected here rather than left to be reasoned from.
catalog had an owner and is corrected here rather than left to be reasoned from.
**And the answer for all four is now one mechanism, not four special cases.** Genesis carries an
*init builder* and builds the core modules on the machine — controller, catalogue and builder —
*init builder* and builds the core modules on the machine — controller, catalog and builder —
rather than carrying a finished image of any of them. So the question is no longer "how does this
one get here first?" asked once per component; it is answered once, by the thing that is carried
being a builder rather than a result.
@@ -102,7 +102,7 @@ anything on the machine that can talk to the runtime. So a secret reaches a proc
the file the node-engine wrote and points the program at it, and the mesh's own programs take a `_FILE`
twin for every variable that carries a credential. Software that reads only its environment is
not forbidden; it is **declared**, on the container, with a reason, so the manifest says which
secrets are exposed that way. **Checked** at composition: the catalogue engine refuses a
secrets are exposed that way. **Checked** at composition: the catalog engine refuses a
`${secret:…}` in a container's `env` outright, and a secret-carrying file named in `env-file`
unless the container carries the declaration.
+1 -1
View File
@@ -170,7 +170,7 @@ the one the mesh runs for its own: it offers a place to push, and claims that ro
machine.
**A rule was enforced only at the far end.** A module may not declare an action, and the node-engine
refused one correctly — but the controller accepted it into the catalogue, resolved it and
refused one correctly — but the controller accepted it into the catalog, resolved it and
pushed it, so the refusal arrived on a machine with nothing tying it back to the manifest. The
rule held; it was just unusable, which is the same shape as the network shape that cost five
failing tests before anyone read the node-engine's log. It is now refused where it is written.
+6 -6
View File
@@ -132,7 +132,7 @@ adopted as modules, and the machine's service is still reachable.
Genesis ends with a mesh of one that runs, and that is not the same as a mesh that works. What it
has is a controller, a store, a queue and a registry. What it cannot yet do is **produce
anything** — and almost every module in the catalogue is waiting to be produced, because a manifest
anything** — and almost every module in the catalog is waiting to be produced, because a manifest
names what its artifacts are and nothing has made them.
So installing continues:
@@ -172,7 +172,7 @@ need no registry. The gitea module's own server is an upstream image, so buildin
**The store genesis raises is the `postgres` module's server, so adopting it keeps it** (ADR 0338, the
store's twin of the bus's ADR 0333). The bundle raises the store under the name, on the image, in the data
directory and with the superuser password file that the catalogue's `postgres` module declares, and every step
directory and with the superuser password file that the catalog's `postgres` module declares, and every step
of the bundle and of the installer reaches it by that name. At the store step the module declares the
container the bundle raised, so the store is adopted where it runs and is not restarted. The module does not
change, so no running mesh's store moves. *How it is checked:* a test reads the module's manifest and holds
@@ -190,7 +190,7 @@ something it made rather than by a placeholder.
mesh running; building it from its own repository and path is what makes it upgradeable. The first
time that happens is the moment the mesh stops depending on the installer for anything.
**And then the catalogue.** Every module with source of its own is built the same way. Until this
**And then the catalog.** Every module with source of its own is built the same way. Until this
has happened a mesh can install only what is public or carried, which is the foundation and little
else.
@@ -233,7 +233,7 @@ was brought up the supported way, so the rule that it must be is, today, unenfor
**Nothing asks for the core modules yet.** Installing ends with a builder that works — a raised
machine will build the shared base and a module on top of it when asked — and nothing asks. The
paragraphs above describing the catalogue being built are a thing somebody now types, rather than a
paragraphs above describing the catalog being built are a thing somebody now types, rather than a
thing that cannot happen.
**A module's declaration still has to be copied onto the machine by hand.** The installer reads the
@@ -242,7 +242,7 @@ longer among them: it lives in the controller's own repository
(ADR 0069), the build the
installer runs reports it with the artifact resolved, and genesis registers that
([issue 072](../../04-ISSUES/072-the-controllers-manifest-exists-twice/00-report.md)). The
builder's manifest belongs in the same repository and is still read from the catalogue; that is
builder's manifest belongs in the same repository and is still read from the catalog; that is
the last of this.
**A machine has no account for a registry that asks for one.** The mesh grants a consumer a
@@ -275,7 +275,7 @@ issue tracker holds it as issue 602.
| An image is named exactly | A machine refuses a bundle naming an image by tag. The refusal is exercised, not assumed. |
| The installer is what installed this | **Nothing.** See above. |
| The builder can arrive on a fresh mesh | The installer carries it and installs it as its last step, and the genesis bed raises a machine by running the installer. A bed that raises one any other way fails its own acceptance check. |
| The builder is assigned before the package registry exists | The build-agent manifest's own test holds the requirement optional and the genesis document declared and issued outside the mesh; the controller's resolution test over the real catalogue assigns the builder with no provider, lists the requirement unbound, and binds it once gitea is offered. The builder's tests refuse a package, an `.npmrc` image and an `@novox/` TypeScript build with neither binding nor genesis document, before anything is built, and build a Go artifact; they read the genesis document only without a binding. The installer's test seals the document at the packages step and gives the builder no `serves` setting and no `npm-password`. **Not yet proved live:** a genesis bed from bare passing the builder, packages, sdk and base steps. |
| The builder is assigned before the package registry exists | The build-agent manifest's own test holds the requirement optional and the genesis document declared and issued outside the mesh; the controller's resolution test over the real catalog assigns the builder with no provider, lists the requirement unbound, and binds it once gitea is offered. The builder's tests refuse a package, an `.npmrc` image and an `@novox/` TypeScript build with neither binding nor genesis document, before anything is built, and build a Go artifact; they read the genesis document only without a binding. The installer's test seals the document at the packages step and gives the builder no `serves` setting and no `npm-password`. **Not yet proved live:** a genesis bed from bare passing the builder, packages, sdk and base steps. |
| The controller a mesh runs is one it built | The genesis bed asserts the running controller is pinned to a digest this mesh's own registry serves, for an image built from a named repository and commit — not one the installer carried. |
| A core module is built rather than only carried | The controller is rebuilt from its own repository and path, and the running mesh is upgraded to the result — the same path any module takes. |
| Installing produced a mesh that can produce | A module with source of its own is asked for and comes back pinned to a digest this mesh's registry assigned, not to a placeholder. **Done by hand on a raised machine, not yet by a bed** — it built the shared base and then a module naming that base. Nothing automated asserts it, which makes this the weakest check on this page. |
+9 -9
View File
@@ -43,7 +43,7 @@ Turning a module's source into artifacts the mesh can pin, publish and deliver
truthfully what was produced and what it was produced against.
Everything else is somebody else's: *what* to build is the controller's, *what a build means* is
the catalogue's (ADR 0072), *where an artifact runs* is the
the catalog's (ADR 0072), *where an artifact runs* is the
controller's again. The builder's whole responsibility is the middle.
## The language
@@ -83,7 +83,7 @@ output into a second stage; and sets an environment variable naming the compiled
module repeats it. Miss any step and the failure arrives somewhere else — as a crash loop, a
placeholder digest, a module that builds and does nothing.
The evidence that this is too hard is in the catalogue: **most modules are not converted**, and the
The evidence that this is too hard is in the catalog: **most modules are not converted**, and the
two converted during one session were each wrong twice before they were right, against a working
example sitting open in the next window.
@@ -163,8 +163,8 @@ makes the drift worse while hiding it.
| A module with its own code needs no Dockerfile | A module declaring only a language builds, and its artifact is pinned to a digest the mesh's registry assigned. |
| An archive is produced and delivered | A module declaring an archive is built, and the machine assigned it has the unpacked files — verified on the machine, not in the build's own output. |
| A Dockerfile still works | A module that declares one builds exactly as before, because software that needs a particular base has not stopped existing. |
| Nothing is announced that was not made | A build made to fail announces nothing, and the catalogue's graph is unchanged afterwards. |
| A build keeps what it was told | A catalogue started after a build asks for what it missed and receives the manifest and the artifacts stood on, not a summary. |
| Nothing is announced that was not made | A build made to fail announces nothing, and the catalog's graph is unchanged afterwards. |
| A build keeps what it was told | A catalog started after a build asks for what it missed and receives the manifest and the artifacts stood on, not a summary. |
| The toolchain is the mesh's, not the author's | Changing the toolchain makes every module built against it stale, and each names what moved. |
## The whole surface, in one place
@@ -207,7 +207,7 @@ declared in one of three ways, for the three things a path can be: the module's
or file resource, or where a secret, grant or contribution lands), the operator's (an `accesses`
entry), or the machine's (a facility a declared capability grants — `container-runtime` grants its
socket). *How it is checked:* the parser refuses an undeclared mount naming the path and the three
remedies, and a test parses every manifest in the catalogue beside the checkout.
remedies, and a test parses every manifest in the catalog beside the checkout.
### What it builds
@@ -247,7 +247,7 @@ counts as a copy and what as a base.
| `directory` | a directory with a mode and an owner, **placed by the mesh** under the node's root: `place: "."` is the assignment's own root, `place: "mesh"` the mesh's directory for the module, a pathless one sits beneath the root by its id; a stated path is the placement for data that must stay where it is, and may itself sit beneath a placed one (`${dir:<id>}/…`). Everything else names it as `${dir:<id>}` ([issue 119](../../04-ISSUES/119-a-module-definition-decides-where-its-files-live/00-report.md), [174](../../04-ISSUES/174-the-meshs-own-files-for-a-module-are-placed-by-the-definition/00-report.md)) | ✅ |
| `file` | literal content, with `${bound:…}`, `${secret:…}`, `${dir:…}`, `${port:…}`, `${machine:…}` and `${setting:…}` filled in — the last an operator's value from the assignment's settings, refused by name when unset (ADR 0155) unless the manifest gives a preference a default (ADR 0262) | ✅ |
| `user` | a login | ✅ |
| `access` | a pre-existing path it may use and must not own, **named by id** and placed by the assignment (`accesses: {<id>: <path>}` on its settings); mounts say `${access:<id>}`; a path in the definition is the default an assignment replaces, tolerated while the catalogue converts ([issue 153](../../04-ISSUES/153-an-adopted-machines-data-cannot-be-placed-where-it-is/00-report.md)) | ✅ |
| `access` | a pre-existing path it may use and must not own, **named by id** and placed by the assignment (`accesses: {<id>: <path>}` on its settings); mounts say `${access:<id>}`; a path in the definition is the default an assignment replaces, tolerated while the catalog converts ([issue 153](../../04-ISSUES/153-an-adopted-machines-data-cannot-be-placed-where-it-is/00-report.md)) | ✅ |
| `archive` | files fetched by digest and unpacked | ✅ |
| `package` | a package that must be present | ✅ |
| `network` | a named container network | ✅ |
@@ -292,7 +292,7 @@ This is the bus's shared-work pattern, not a build-specific one: any module decl
`accepts` has its work shared by its holders the same way. Building is the first use.
*Built and proven live 2026-10-03.* `build-agent` holds `node-build-agent` on all four machines; the first
build taken by a workstation's agent was a catalogue module at 09:35 UTC; the one-holder `builder` is
build taken by a workstation's agent was a catalog module at 09:35 UTC; the one-holder `builder` is
retired. The switch found five gaps, each an issue: a worker whose type changed stranded its holder
([206](../../04-ISSUES/206-a-seats-worker-changing-type-strands-the-holder-and-the-build-that-would-fix-it/00-report.md)),
a re-made worker replayed the stream's history ([207](../../04-ISSUES/207-a-re-made-worker-replayed-every-ask-the-stream-kept/00-report.md)),
@@ -316,7 +316,7 @@ controller's seat verb through the mesh MCP server — reads it back afterwards.
id beside it, and `build` says the id it asked with. The mesh keeps no second copy: the stream is the
log. The mesh MCP server's `build` tool asks and answers at once with the id; the outcome is taken in — the
build recorded, the module registered with its source — by whoever hears it, the waiting command or
the daemon following the role's event, so a build nobody waited for still reaches the catalogue
the daemon following the role's event, so a build nobody waited for still reaches the catalog
([issue 176](../../04-ISSUES/176-the-consoles-build-tool-neither-waits-nor-registers/00-report.md)). A viewer of builds, when one is built, is a subscriber over these subjects and the outcome; the
builder needs nothing more for it.
@@ -383,7 +383,7 @@ than retried for ever. Live: the store's size before and after the first nightly
*2026-09-29 —
ADR 0142.*
The toolchain list was typescript and python, and only typescript had a base module in the catalogue.
The toolchain list was typescript and python, and only typescript had a base module in the catalog.
Meanwhile the controller — written in the language this project is mostly written in — was built as
an image from a hand-written Dockerfile, which is the per-repository incantation this whole mechanism
exists to abolish.
+44 -3
View File
@@ -5,8 +5,17 @@ code:
- mesh-catalog modules/showcase
- mesh-controller internal/builder
- mesh-sdk src
updated: 2026-10-02
- mesh-contracts
updated: 2026-11-05
decisions:
- "ADR 0634"
- "ADR 0635"
- "ADR 0625"
- "ADR 0627"
- "ADR 0573"
- "ADR 0606"
- "ADR 0609"
- "ADR 0593"
- "ADR 0150"
- "ADR 0099"
- "ADR 0053"
@@ -47,10 +56,42 @@ 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.
recompile unrelated modules, and does it change often?** Both, and it does not belong. It goes to
its owner instead: a seat's contract or client, the module that owns it, or its domain's SDK (*Where a seat's code
goes*, below; ADR 0634 §1).
## Where a seat's code goes
*Added 2026-11-04, widened 2026-11-05* (ADR 0625, ADR 0627, ADR 0634, ADR 0635; [design 26](26-the-seats.md) *Where
a seat's code goes* is the whole rule). Shared code lives with its owner (ADR 0634 §1): a module that calls or holds
a seat, or shares code with other modules, meets these places, and each piece of code has one, the first that fits:
| the code | lives in | written |
|---|---|---|
| a seat's types, subjects, the layouts of its states and a typed call per verb or accept | the seat's **contract**: a package of its own per language in its domain's contracts module (`mesh-<domain>-contracts`, or `mesh-contracts` for the Core domain and a domain with none), for a seat defined whole; a seat at the seat list's grain has only its definition, which every reader reads from the bus (ADR 0635 §1, §2) | generated from the seat's definition, never by hand |
| logic two or more callers or holders 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, mesh-sdk's runtime and its own domain's SDK, never another seat's client, and names no holder, no module's tool and no module's subject |
| logic and state layouts one module owns, where it holds no seat for them | that module's **own package**, which other modules import from it: by path in the same repository (ADR 0609 §2), by a published version from another (ADR 0573 §1), so its manifest declares it as a package artifact; its fingerprint counts only that package's files (ADR 0593 §2), so its importers rebuild only when it changes | by hand, in the owner module |
| logic and forms no seat carries and no one module owns, used by one domain's modules or seats only (moving a file in parts, the build steps' shared logic) | that domain's **domain SDK**, `mesh-<domain>-sdk`, a package-only module (ADR 0634 §2) | by hand; it imports only mesh-sdk and contract packages, names no module's tool or subject, and holds no seat's type or state layout |
| what every module needs whatever the seat (the bus connection, the tools bundle's runtime, state), and a part modules or seats of more than one domain share that names no seat, verb or seat's type | **mesh-sdk** | by hand; it takes no seat-specific type, imports no contracts module, and reads the seat list from the bus |
| 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, the packages of the modules whose state it
reads, its domain's SDK where it uses it, and mesh-sdk.** Its users rebuild when something they use changes, not when
any seat or any domain 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. A contracts module and a domain SDK are modules like any other, found by
their manifests in folders of a repository and delivered to no node (ADR 0634 §8). 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 manifest validator's refusal of a
contracts module that claims a seat; the home of each new exported name, a domain SDK's importers included, and a role
made a seat or a seat left as one module's tools, by the review of the pull request that adds it (ADR 0634 §10).
## A module with four capabilities, in four languages
@@ -171,7 +212,7 @@ knows. Putting the Plex client anywhere else is the shared-library disease with
- **Which private registry.** That there *is* one is settled —
ADR 0014 says each module consumes its dependencies
from the private registry, the mesh's own shared library included. Which software serves it is
not: the catalogue holds `verdaccio`, and a git host usually serves package registries too.
not: the catalog holds `verdaccio`, and a git host usually serves package registries too.
- **And the bootstrap does not have one.** ADR 0014 assumes a registry exists; on a fresh mesh
nothing has installed one when the first SDK is built. That is the same pivot as everything else
and it has not been designed.
@@ -65,14 +65,14 @@ and waits — which looks exactly like a builder with no work.
**Genesis ends with a mesh that runs, which is not the same as a mesh that works.** It has a controller, a store, a broker, a registry and a builder. It holds no module graph, has no private
network, no packet filter, and cannot resolve a name. Calling that "installed" is what let the
catalogue be missing from a test for weeks without anything complaining.
catalog be missing from a test for weeks without anything complaining.
| # | step | what happens | why it is here |
|---|---|---|---|
| 13 | the shared base is built | the toolchain and runtime every module with code of its own stands on | nothing else with code can be built until it exists |
| 14 | a store module is built and run | a database **provider**, which the foundation's store is not | the foundation's store is the controller's own memory, and offers nothing to anything |
| 15 | the catalogue is built and run | the module graph | without it the mesh cannot say what it holds, what a change reaches, or what must be rebuilt |
| 16 | the catalogue asks for what it missed | the builds made before it existed are replayed | on a fresh mesh those are always the base, the store and the catalogue itself ([issue 050](../../04-ISSUES/050-the-catalogue-knows-nothing-built-before-it/00-report.md)) |
| 15 | the catalog is built and run | the module graph | without it the mesh cannot say what it holds, what a change reaches, or what must be rebuilt |
| 16 | the catalog asks for what it missed | the builds made before it existed are replayed | on a fresh mesh those are always the base, the store and the catalog itself ([issue 050](../../04-ISSUES/050-the-catalogue-knows-nothing-built-before-it/00-report.md)) |
| 17 | the controller is rebuilt from its own repository | and rolled out through the module path | the moment the mesh stops depending on the installer for anything |
| 18 | `mesh-wireguard` is assigned **and the node placed** | a private network | assigning installs the module; placing says where this machine is on it. Both, or the machine has no peers. Assigned by its own name since ADR 0226 retired the `networking` bundle |
| 19 | the packet filter is assigned | rules generated from what modules declared | until this, every rule the mesh computes has never been applied to anything |
+2 -2
View File
@@ -44,7 +44,7 @@ after the phases that change its build path are in — not before.
**Why here.** The Go controller and the TypeScript SDK disagree about what a grant carries
(`consumer` is the module in one, the node in the other). That is exercised by the installer's own
provisioning — the catalogue's database — so it belongs before more is built on it.
provisioning — the catalog's database — so it belongs before more is built on it.
- [x] 1.1 the drift was not live — inspection showed the wire agrees (contributions file; envelope
required headers). The dead types that disagreed are removed, ADR 0074 and doc 19 corrected
@@ -91,7 +91,7 @@ a protocol that agrees, a registry to publish to. Issue 051.
the controller's records and the database of each module that asks for one. *(Adopted in place: the module's
server names the same container and the same pinned upstream image the foundation runs, so the
applier reconciles it rather than raising a second postgres. Proven 22/22 in the one-node lab —
the catalogue, a `postgres-database` consumer, gets its database from it. Follow-up: the store
the catalog, a `postgres-database` consumer, gets its database from it. Follow-up: the store
binds `0.0.0.0` from genesis so a mesh consumer can reach it, but the packet filter is
installed later — a brief pre-filter window where `mesh-store` is open before `from: mesh`
clamps it; bring the filter up earlier or bind narrower at genesis.)*
+1 -1
View File
@@ -11,7 +11,7 @@ decisions:
# 23 — Choosing a provider
**Where it stands, 2026-10-17** (the records cleanup, issue 1072; playbook 07, "The design's state is written back"). Built on main: mesh-controller's internal/catalogue/resolve.go implements the model described here, and designs 26, 27 and 29 rely on it. Not yet checked against this text clause by clause, nor given an as-is: issue 1074.
**Where it stands, 2026-10-17** (the records cleanup, issue 1072; playbook 07, "The design's state is written back"). Built on main: mesh-controller's `internal/catalogue/resolve.go` implements the model described here, and designs 26, 27 and 29 rely on it. Not yet checked against this text clause by clause, nor given an as-is: issue 1074.
A provision is named for what the consumer's code is coupled to
(ADR 0027):
+2 -2
View File
@@ -185,7 +185,7 @@ recovery addresses both alike.
### A provider with one credential
*Decided 2026-10-01 (ADR 0158); the controller's half built the same day (mesh-controller PR 184): the offer's word, the need carrying the shared secret's name, the vault's one value under one generation stamp, remade for every holder on a later binding or a rotation, the rotate command sending every holder. What remains is each provider's definition saying `credential` and `taken`, with a start that applies the file — the media catalogue's work.*
*Decided 2026-10-01 (ADR 0158); the controller's half built the same day (mesh-controller PR 184): the offer's word, the need carrying the shared secret's name, the vault's one value under one generation stamp, remade for every holder on a later binding or a rotation, the rotate command sending every holder. What remains is each provider's definition saying `credential` and `taken`, with a start that applies the file — the media catalog's work.*
Software that holds one credential — a download client's web password, an indexer's one API key —
cannot give each consumer a login, so ADR 0048's form does not fit it and its values were accepted
@@ -202,7 +202,7 @@ acceptance. *How it is checked:* the rows of ADR 0158's table; the controller's
### A credential the provider's software issued
*Decided 2026-10-12 (ADR 0305, issue 526), accepted on the operator's approval the same day; built on
branches in the controller and the media catalogue.*
branches in the controller and the media catalog.*
Some software is given its one credential rather than told it: a media server signs in to its vendor and
keeps the token the vendor issued. The mesh can neither make nor rotate such a value, and a copy typed for
+513 -8
View File
@@ -7,9 +7,27 @@ code:
- mesh-tools src/broker-amqp.ts (to be replaced)
- mesh-catalog modules/nats (to be written)
- mesh-sdk src (the protocol's NATS binding, step 3)
- mesh-tools node-tools/internal/bus (a module's state, ADR 0201)
updated: 2026-10-10
- mesh-tools node-tools/internal/bus (a module's state, ADR 0201; the new calls and apply, ADR 0595, ADR 0597)
- mesh-sdk (the typed bus-state entry, its binding and the new calls' package, ADR 0595)
- mesh-delivery (the manifest validator's rules and the grants part's binding, ADR 0595)
updated: 2026-11-04
decisions:
- "ADR 0595"
- "ADR 0626"
- "ADR 0631"
- "ADR 0620"
- "ADR 0259"
- "ADR 0627"
- "ADR 0436"
- "ADR 0619"
- "ADR 0615"
- "ADR 0621"
- "ADR 0622"
- "ADR 0614"
- "ADR 0613"
- "ADR 0612"
- "ADR 0596"
- "ADR 0597"
- "ADR 0289"
- "ADR 0264"
- "ADR 0235"
@@ -38,6 +56,11 @@ under which subject, with which guarantee, under whose account; how a node joins
reaches a tool; how the mesh moves from the bus it has to this one; and how each claim is checked.
Prose and diagrams only; no configuration is pasted.
**Amended, 2026-11-03** (ADR 0595, ADR 0596, ADR 0597): what a module keeps on the bus is its **bus state**, a
provision of the bus module asked for by template, created by the bus module, read by its owner alone; and the
**ledger** is a storage type of its own. § 12 is the design; the `KV_<module>_<name>` row of § 3 and the module's
state in § 4 hold for a module still on the old sections.
## 1. What the bus is for
**The bus is where the mesh happens.** Not a transport the mesh sends things over — the place a
@@ -129,7 +152,7 @@ mesh already has a shape for that — a seat's `accept` subjects, on a work queu
holders, which is what a build queue shared by several machines *is*. Keeping a second mechanism for it
meant two things to reason about and two places for a permission to be wrong. A build's outcome is the
seat's own event — which is why the control branch loses its copy too: one publish reaches whoever
asked, the controller that records it and the catalogue that places it — the fan-out a shared exchange gave for free, as a derived subject rather than a
asked, the controller that records it and the catalog that places it — the fan-out a shared exchange gave for free, as a derived subject rather than a
configured topology.
**Revised 2026-09-26** ([design 29](32-what-a-module-declares.md)): a module's events and tools
@@ -179,7 +202,7 @@ Core NATS is at-most-once. Everything the mesh must not lose lives in a JetStrea
| EVENTS | `mesh.mod.*.event.>` and `mesh.seat.*.event.>`; and `mesh.again.>` (ADR 0264) | limits (age, size), durable consumer per subscribing module | a subscriber that was down catches up; after `max-deliver` attempts the advisory feeds `mesh.events.dead` (its own small stream). *2026-10-08, ADR 0264:* that stream is DEAD_LETTERS, below; each consumer also filters `mesh.again.<consumer>.>`, where a message it gave up on is delivered again to it alone. *2026-10-01:* a build's whole log is here too, as the build seat's `log.<build id>` events (ADR 0157) — one subject per build, a week of retention, read back by `builds --log <id>` with a consumer that is gone when the reading is done |
| DEAD_LETTER_NOTICES | the server's maximum-deliveries advisory | work queue, a week; one consumer (the controller), no `max-deliver` | the server's word that a consumer gave up on a message, kept whether or not a controller is listening, until the controller has copied the message (ADR 0264) |
| DEAD_LETTERS | `mesh.events.dead.<stream>.<consumer>` | limits: no age, 256 MiB, refuses new when full; a day's de-duplication | every message a consumer gave up on, with its consumer, subject, deliveries and when, until a person delivers it again or drops it with why (ADR 0264); a `max-deliveries` condition is open per consumer while it holds any |
| `KV_<module>_<name>` | `$KV.<module>_<name>.>` | the newest value per key — as many past values as the owner declared — no age unless the owner declared one; a value at most 256 KiB, a bucket at most 64 MiB | a module's state (ADR 0201): one per name in a manifest's `state`, created from the catalogue on every raise, so it exists before its owner runs anywhere; kept when the module is unassigned, because what it holds is data |
| `KV_<module>_<name>` | `$KV.<module>_<name>.>` | the newest value per key — as many past values as the owner declared — no age unless the owner declared one; a value at most 256 KiB, a bucket at most 64 MiB | a module's state (ADR 0201): one per name in a manifest's `state`, created from the catalog on every raise, so it exists before its owner runs anywhere; kept when the module is unassigned, because what it holds is data. *2026-11-03, ADR 0595:* a module's kept data in the new form is created by the bus module from `requires`, by template (§ 12) |
Tool calls and heartbeats stay on core NATS: a lost heartbeat is the next heartbeat; a lost tool
call is a timeout the caller already handles.
@@ -193,6 +216,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
@@ -266,7 +292,7 @@ expresses this exactly, per subject, and better than a vhost could:
permissions for each consumed event's subject, its tool subjects, and that same inbox prefix.
Nothing else. A module that tries to publish outside its emits is refused by the server, not by
convention.
- **A module's state** (ADR 0201), for whichever principal carries the module — today the machine's
- **A module's state** (ADR 0201; for the new form, § 12.2: the owner's account alone, no reader, ADR 0596), for whichever principal carries the module — today the machine's
runtime, whose grant is the union of its modules': binding to the bucket, reading a key directly,
and an ordered consumer for listing and watching, created and deleted on the bucket's own stream
and nothing else's; and, for the owner's instances only, publishing under the bucket's own
@@ -321,7 +347,7 @@ signing hierarchy for nothing.
## 5. The broker as a module
`nats` is a catalogue module claiming the seat `mesh-broker`
`nats` is a catalog module claiming the seat `mesh-broker`
(ADR 0079: the seat
is the server, and the server changes). It declares one container (a single binary; **JetStream on a host
directory bind, not a named volume** — revision, second review:
@@ -410,7 +436,7 @@ bridged. It is three things:
for anyone else — and nothing on control, nodes or builds. It is issued, sealed to the person's
own key, and revoked, like a module's.
2. **A client that speaks the bus**: a small program on the workstation that connects as that user
over TLS, lists tools by asking the catalogue (`mesh.tools.mesh-catalog.catalog_tools`), and
over TLS, lists tools by asking the catalog (`mesh.tools.mesh-catalog.catalog_tools`), and
turns each tool into a call — as an MCP server for an agent, and as a command line for a person.
It uses the sdk's `Broker` contract on the NATS runtime, so it is the same code path a module's
tools use, not a second protocol.
@@ -606,7 +632,7 @@ find what changed and why.
decides it.
- The heartbeat interval and the controller's "quiet" threshold on core NATS without persistence —
the same numbers as today are proposed.
- Whether the person's client is a catalogue module (runs on an enrolled workstation node) or a
- Whether the person's client is a catalog module (runs on an enrolled workstation node) or a
standalone program (runs anywhere with credentials). Both, in that order, is proposed.
- Leaf nodes: a NATS leaf per machine would make every module's connection local and survive the
hub's restart. Deliberately out of scope; noted so it is not forgotten.
@@ -617,3 +643,482 @@ find what changed and why.
that needs it? ADR 0039's test —
*does editing it recompile unrelated modules, and does it change often* — probably says no for
one instance; worth asking again if a second module needs the same shape.
## 12. Bus state: what a module keeps on the bus, and the bus module that provides it
*Added 2026-11-03* (ADR 0595, ADR 0596, ADR 0597, from research 082; the operator, 2026-11-02 20:45: "The names
simply represent named configurations or templates"). Until now a manifest declared what a module keeps on the bus
in four sections with four vocabularies (`state`, `logs`, `streams`, `objects`), the grants part created each
entry once and never changed it, and nothing compared what the bus holds with what was asked. This section is the
design of the one form that replaces them; [design 32](32-what-a-module-declares.md) § 4 says how a manifest asks
for it, and [design 55](55-the-knowledge-base.md) § 2.1 is its first ledger.
**Bus state is a provision of the bus module** (ADR 0595 §1). The **bus module** is the module holding the seat
`mesh-broker` (today `nats`). A module asks it for each piece of its **bus state** the way it asks postgres for a
database: an entry in `requires`, by its local name, its storage type, its template and the template's options.
The bus module creates it; the module receives the names on the bus in its membership; nothing else creates it.
### 12.1 Three layers
```
layer 3 templates state events work queue log objects ledger
│ │ │ │ │ │
layer 2 storage types key-value │ │ │ object store ledger
built on the bucket │ │ │ │ (a stream and
stream │ │ │ │ │ key-value buckets)
└──────────┴───────────┴──────────┴──────────┴────────────┘
layer 1 base type stream
```
A **storage type** is how the bus keeps the data: the **stream** is the base, and the **key-value bucket**, the
**object store** and the **ledger** are built on it, each with calls of its own (ADR 0595 §2). A **configuration**
is the settings a storage type is given. A **template** is a storage type with a configuration, predefined and
named: six exist, from the uses counted on main (158 state entries, 6 event streams, 4 logs, 3 work queues). An
**option** is one setting of a template a module may change, within its bound. A module gives a configuration of
its own only where no template fits: the bare stream, or a ledger whose history expires.
**What keeps the data safe is fixed, never an option** (ADR 0595 §3). Each template fixes what happens when it is
full, and the manifest validator refuses a manifest that gives it:
| Template | On | Fixed | Options, their bounds (default) |
|---|---|---|---|
| state | key-value | refuses when full; a value at most 256 KiB; the bucket at most 64 MiB; one copy, on disk | past values 1 to 64 (1), 0 refused; time to live (none); a lifetime per key; one bucket per machine |
| events | stream | drops the oldest when full; the module's own subjects | age 1 to 30 days (7); cap 1 to 8192 MiB (1024); a grant (ADR 0363 §4) |
| work queue | stream | removed once taken; refuses when full; one taker; no grant | deliveries 1 to 10; duplicate detection up to its age; cap; age |
| log | stream | refuses when full; never rewritten; an entry at most 256 KiB; one subject per key | cap 1 to 8192 MiB (1024); age 1 to 3650 days (none) |
| objects | object store | refuses when full; kept for good | cap 1 to 8192 MiB, required; a grant |
| ledger | ledger | as log, plus its type and a snapshot per instance; its state and index buckets as state | cap; keeping days only in a ledger's own configuration |
| (none: a bare stream) | stream | the module's own subjects; within the mesh's bounds | its own configuration, which must give "when full" (refuse or drop the oldest), a cap of 1 to 8192 MiB and an age of 1 to 3650 days or none, and may give a grant; the manifest validator refuses one missing any of the three |
The template log is the **module log** of ADR 0297. The mesh, never the module, names the bus objects and their
subjects (ADR 0201 §4): `<module>_<local name>`, and a local name holding the separator is refused so no two
modules' names meet.
### 12.2 Who creates it, and how a module receives it
```
manifest validator ─verdict: accepted with the module's bus-state entries whole─▶ bus module
│ creates each entry
▼
grants part ◀──────────────── created (module, local name, bus name, template, settings)
│ writes the binding into the module's membership
▼
the tool runner reads the membership ──▶ the module's calls reach its own entries, and only those
```
- **The trigger is the manifest validator's verdict** (ADR 0595 §4), heard as the indexer's event `manifest-accepted`, which
carries the module's entries whole, so the bus module never reads the indexer's state and never polls. The indexer
says it for every newly accepted manifest, with its entries empty when it asks for none, and the bus module reads an
empty one as "this module asks nothing now", which is what its orphans need. A module whose manifest leaves the
trunk (its directory deleted) gets an empty `manifest-accepted` too, so its entries reach `orphans` and raise
`orphaned`; a manifest the manifest validator set aside to wait gets none, so its entries stay asked. The indexer's tool
`indexer_say_accepted` says `manifest-accepted` again for one module by hand, from the verdict it holds, recorded as a
hand act, for a verdict the bus module is thought to have missed. It goes, as every event of the
indexer, on the module events stream (ADR 0363) under the indexer's own subjects. A publish of it that fails is
published again, and one still failing writes the indexer's finding naming the module, cleared once said (today
the indexer only logs it). It hears the verdicts on a durable consumer, so one given while it was down is heard
when it is back. **Its first view** at start is the indexer's
tool `indexer_bus_state` (every accepted manifest's bus-state entries, by module and digest), asked once; the
events keep it current after that, and a stream that keeps a verdict only for its age is never its source. A
verdict replayed from its consumer is applied only if newer than what the first view answered for that module, by
the indexer's revision alone (a digest has no order), so a replay never takes an entry back. An `indexer_bus_state`
that does not answer makes the bus module's health unhealthy, naming the verb, and is asked again on a bounded
backoff (from 10 seconds, doubling, at most every 5 minutes); nothing is created or orphaned meanwhile. Beside the
backoff, the bus module's tool `nats_first_view_again` asks `indexer_bus_state` at once by hand, recorded as a hand
act. It keeps
what it last heard per module in its own state `asked` (an old `state` section, its own kept data staying there,
ADR 0595 §10), from which `list`, `check` and `orphans` answer; a key goes only on an empty `manifest-accepted` for
the module, never because a manifest the manifest validator set aside to wait is missing from the first view. Then it runs `check` over what it holds, creating what
is missing. The manifest validator checks every entry once, at the merge check and at take-in (ADR 0578; ADR 0595 §8), and also
each ledger type's operations: a set-entry or a remove names `into` and `key`, `fields` and an index's `on` name
fields of the schema, and `digest-of` names a text field.
- **A module that asks bus state waits for the bus module** (ADR 0614 §5). Each bus-state entry of a manifest is a
requirement on the provision `bus-state`, which the bus module's manifest provides; the module graph reads it as any
requirement, so the assigner holds a consumer's new build until a build of the bus module that offers `bus-state`
runs healthy (ADR 0603 §5). That each entry exists before its user starts is the bus module's own work, above, not
an edge.
- **The bus module has a process of its own** beside its tool bundle, with a declared health check. Its credential
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 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 manifest validator 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 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 manifest validator's
refusals as findings and gains, through its `consumes`, the accepted verdicts and the seat `mesh-broker`'s `created`
and `refused`; never by the bus module, which cannot raise it while it is down; it names the module
and the entry; a later `created` clears it, and so does a later accepted verdict of that module that no longer asks
for the entry.
- **A foundation part's first view of another's state is a tool its owner answers in a runtime of its own** (ADR 0615,
ADR 0621). The four
foundation parts that read each other (the grants part, the tool runner, the indexer and the assigner) stop
reading the indexer's and the assigner's bus state in the milestone of ADR 0612, with the other 19 readers of that
state (ADR 0615 §1). **Each owner serves them as tools of its own module**, the indexer `manifests`,
`modules`, `verdicts` (ADR 0622 §1) and `graph` (ADR 0631 §1), the assigner `placement`, `seat-holders` and `wants`, and declares `runs-as`, so its tools bundle runs in
a runtime of its own on the module's own bus account, never in the node's tool runner, and the tool runner never
asks through itself (ADR 0621 §1). No new manifest form is added: a process still answers no tool call or seat verb
(ADR 0436 §3). **Each verb is granted to exactly its readers** (ADR 0621 §2, as ADR 0615 §3 lists them): `placement`
to the grants part, the tool runner and the indexer; `seat-holders` to the tool runner; `wants` to the grants part;
`manifests` and `modules` to the grants part, the tool runner and the assigner; `verdicts` to the grants part
alone, its `callers` list holding the grants part only (ADR 0622 §1); `graph` to the assigner alone, its `callers`
list holding the assigner only, the indexer itself refused, and the assigner's `reads` entry of the indexer's
`graph` goes (ADR 0631 §1). These seven are the first-view tools, four of the indexer and three of the assigner.
`verdicts` follows the first-view rules whole (ADR 0622 §2, under ADR 0615 §4 to §6): its answer carries the
revision, the grants part then follows `manifest-accepted` and `manifest-refused` and asks once more on a gap in
their revisions, it raises the condition naming the indexer and `verdicts` past the bound and never reads the
indexer's state, and `grants_first_views` and `grants_first_view_again` cover it. `graph` follows them whole too
(ADR 0631 §2, under ADR 0615 §4 to §6): its answer carries the revision, the assigner then follows the indexer's
`indexer.views` events for the bucket `graph`, which carry the revision, and asks once more on a gap, said in its
log; started while the indexer is down, it raises the condition naming the indexer and `graph` past the bound and
never reads the indexer's state; and `assigner_first_views` and `assigner_first_view_again` cover it. A reader declares each in `invokes`
as `<module>.<tool>` only where it is granted, which is the grant the grants part composes as for any tool, and
each tool checks the proved caller against a `callers` list holding exactly its readers and refuses any other, the
owner itself included. **The manifest validator of the milestone is its own group's** (ADR 0621 §4): since no field is added,
the running manifest validator takes the indexer's and the assigner's manifests in as it does today, and the merge check judges
them with the manifest validator built from the group's own head; no release of the manifest validator goes ahead of the milestone. **The
owner's runtime answers before any first view of its own** (ADR 0621 §3): at once from its module's own state, as
soon as it is connected and before it has asked any other part anything, with the revision of its state it answered at,
so the indexer and the assigner, each asking the other at start, never wait on each other (§4). The reader then
follows the owner's declared events, each carrying the revision of the state it follows, and never asks the verb
again on a timer; a gap in revisions makes it ask once more, said in its log (§5). The owners' events are new
families of their own, apart from the indexer's `manifest-refused` and `manifest-accepted` and the assigner's
`put`: the indexer's `indexer.views` and the assigner's `assigner.views`, one event per changed key with its
bucket, key and revision and the key's value whole, or a delete mark for a key removed, so a reader keeps its
picture from the events alone and asks the verb only on a gap (ADR 0615 §5). **Both families are declared in
their owners' old `streams` sections**, each an entry with `max-age-days` 7 and `max-mib` 256: the old section keeps
a stream by limits, which drops its oldest when full (only a work queue refuses the new instead), so a reader that
misses a dropped event sees the gap in revisions and asks once more. The indexer's own kept data stays on the old
sections (ADR 0595 §10 names it among the foundation); the assigner's goes beside its existing `streams` entry
`placement`, under ADR 0619, which extends ADR 0595 §10's foundation to the parts
the bus module's own composition, placement, build or delivery needs before it can answer: the assigner, the tool
runner, the builder, the checker, mesh-config and the vault. **The size, an estimate**: read on the bus on
2026-11-04, the buckets the readers read hold about 3 MiB of current values at the indexer (its manifests about
5 KiB a value) and about 1.5 MiB at the assigner (its wants about 0.25 KiB a value). The milestone's one mesh-sdk
rebuild rewrites every module's keys, up to three times in its window (design 51 *How many builds*), so a week of
it is some 20 MiB on `indexer.views` and some 10 MiB on `assigner.views` with ordinary merges added, each well
under its 256 MiB. Each event carries one value whole, the largest today a manifest of tens of KiB, under the bus's
largest message, 1 MiB (the bus server's `max_payload`); an owner whose value with its event would pass it emits
the key's revision alone, as a gap, so the reader asks the first view once, and the owner writes its finding
naming the key.
A waiter on an existing event, `manifest-accepted` or the
assigner's `put`, never wakes on them. **When an owner's revisions go back**: should an owner's state be rebuilt
by the bus module's `recreate`, its revisions start again; a reader that hears a revision lower than the one it
holds takes it as a gap and asks the first view again, and keeps what that answer says, whatever revision it held
before. A `recreate` that could not keep the data answers empty at revision 0, so the grants part keeps its list
in force (below): a login revoked meanwhile stays until the owner's first change, and the grants part's
first-view condition stays raised meanwhile, naming the owner, the empty answer and the operator's step: let the
owner write its state again from its sources (the indexer by taking each module in again, `indexer_take_in`; the
assigner by its next composition of the wants), then ask the grants part's first view again,
`grants_first_view_again`. It is cleared by an answer above revision 0. A reader that starts while its owner is down raises a
condition naming the owner and the verb past its bound and keeps asking until it answers, never reading the
owner's state instead; once it had its first view, it keeps working on what it heard (§6). The bound is longer
than an owner's start (two minutes), so a normal start, readers and owners coming up together, notifies nobody;
the owner's answer clears the condition. An answer that is empty at revision 0 (an owner that holds nothing yet)
is a first view of nothing, never a reason for the grants part to drop a login it holds: it keeps the list in
force until an answer at a revision above 0. Each reader's tools say the owner, verb and revision its first view
holds, when it asked and when it was answered (a read tool), and ask the first view again by hand (a re-read tool,
recorded as a hand act): the grants part's `grants_first_views` and `grants_first_view_again`, the tool runner's
`mesh_first_views` and `mesh_first_view_again`, the indexer's `indexer_first_views` and
`indexer_first_view_again`, and the assigner's `assigner_first_views` and `assigner_first_view_again`. The tool
runner's two are tools of the mesh MCP server, beside `mesh_runtimes`, since the tool runner serves its own state
there: the mesh MCP server gains them, and the operator sees them among its tools. **On a fresh mesh** the
assigner starts before any new-form bus state exists and needs no binding of the bus module first: its own state
and `assigner.views` are on its old sections, which the grants part creates, so it answers the indexer, the grants
part and the tool runner their first views while the bus module still waits on it. The order of owner before reader is kept by the module graph's served-verb edge for the 19 readers (ADR 0614 §2), and,
for the four, whose verb edges lie on cycles the graph leaves out (ADR 0614 §3), by the owner's answer at once and
the reader's wait (ADR 0615 §2).
- **The other 19 readers ask the owners' read tools, one per bucket they read** (ADR 0615 §1, §2). Beside the seven
first-view tools above, each owner serves a read tool for every bucket of its state one of the 19 reads today,
named `indexer_read_<bucket>` or `assigner_read_<bucket>` and marked as a read: fifteen. The indexer's nine:
`indexer_read_manifests`, `indexer_read_modules`, `indexer_read_predefined`, `indexer_read_config_candidates`,
`indexer_read_candidates`, `indexer_read_packages`, `indexer_read_graph`, `indexer_read_heard` and
`indexer_read_taken`. The assigner's six: `assigner_read_placement`, `assigner_read_seat_holders`,
`assigner_read_wants`, `assigner_read_findings`, `assigner_read_asks` and `assigner_read_differences`. These are
the nine buckets of the indexer and the six of the assigner the 19 read (§ 12.6), `modules`, `wants` and
`placement` among them for the status view; the indexer's tenth, `verdicts`, is read by the grants part alone,
through its first-view tool. **They are ordinary module tools**: granted, as any tool is, to every
reader that declares it in `invokes`, and callable by a session; the `callers` list of ADR 0621 §2, ADR 0622 §1 and ADR 0631 §1 covers
only the seven first-view tools. **The status view keeps all its tools**, their names, arguments and answers
unchanged, its `indexer_*` and `assigner_*` tools included: as a reader it answers them by asking the owners' read
tools instead of reading their buckets. Checked live after the delivery: a session's call of each status view tool
answers, and `mesh_search` finds each owner's read tool by its bucket's words.
- **Only the owner reaches it** (ADR 0596 §2). The membership grants the owner's account its own entries and no
other module's: the new form has no readers. What another module needs of that data it asks through the owner's
tools or seat verbs, and what the owner lets others hear is its declared events, subscribed to through
`consumes` (ADR 0363, unchanged). A part watches only its own state, and hears another's events (ADR 0596 §4).
### 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 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.
| Verb | Does | Who may call it |
|---|---|---|
| `list` | every entry, its template, its settings, its fill against its cap | any caller whose role grants it (ADR 0386) |
| `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 manifest validator refused or outgrew, nor one of the foundation's old sections | the same |
| `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` 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.
**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
lower clear mark, so an entry sitting at the mark does not flap; the marks are settings of the bus module, by default
a raise at 75 percent of the cap and a clear below 70 (ADR 0595 §6, as its progressive insight of 2026-11-03 has it).
The grants part's `mesh-grants.history-full` moves to it: the new condition is raised first, then the old key cleared;
no manifest on main asks for a history stream or objects today, so the move loses nothing. A bare stream that refuses
when full is read the same way. **The conditions**, each naming the module and the entry: `full` (cleared below the
clear mark), `drifted` (cleared by `drift-cleared`), `orphaned` (cleared by a
`drop` or by a manifest asking for it again) and a refused create (cleared by a later `created`).
**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. **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 watches that key for the process's answer, never asking again on a
timer. The process watches its own state `requests` (ADR 0596 §4) and takes a request up when it is written. 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. **The process wakes on the warrant, never on a timer**: a warrant is said on the operator
channel's `decided` for the asker that raised the ask (ADR 0259 §6; ADR 0620 §2), here the bus module itself, which
hears its own `decided` on a durable consumer of the process, whose filter the grants part derives from the
process's `uses` of the operator channel seat (not from a `consumes`, which a process has none of), and runs its pass over the waiting `recreate` and
`drop` requests when one arrives, so a warranted `drop` acts within seconds of the operator's answer, and one given
while the process was down is heard when it is back. **A warrant acts once** (ADR 0259 §6): before it acts, the
process claims the warrant's ask id by writing the key `acted.<ask id>` in the state `spent` of the process's own bus state, which the tools bundle is not given (a person's request and the
record of what it spent are never in one bucket, and no tool can write the record), created by compare-and-set after the snapshot and before any deletion, and a request naming an ask it already
acted on is refused, deleting nothing and saying which act that warrant already performed. **An ask lasts 12 hours**,
shorter than the 24 hours `requests` keeps a request: a request whose ask ended unanswered is ended and said, and a
warrant is not acted on once its ask ended; the tool raises the ask before it hands the request over. A request
that cannot act yet says why in its field Waiting, and a hand act the process could not record is written on the
request in its field Unrecorded. The tool `nats_requests` reads the waiting and ended requests, and the warrants
spent from `spent`, which is declared `read-only: true` (design 32 § 4) so that the tool reads it and holds no publish on it, and drops a waiting request by hand, recorded as a hand act. `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
names the process's last pass, the entries it could not create, and the entries past the raise mark.
### 12.4 The ledger
A **ledger** is a storage type whose state is derived from its history (ADR 0597). It is built on a stream and
key-value buckets, and asked for with the template ledger.
```
module ──apply(instance, operation)──▶ tool runner on its own machine
│ 1 checks the operation against the type
│ 2 reads the history's last sequence for the instance; replays if the state is behind
│ 3 appends to the history, that sequence expected ──▶ history (stream, a subject per instance)
│ 4 derives the state by the operation's effect ──▶ state (key-value, updated at the revision read)
│ 5 writes the instance's snapshot ──▶ snapshot subject (latest only, never expires)
▼
answers: taken, with its sequence (and "state behind" when the state bucket is full)
module's process: a watcher keeps each declared index (a second key-value bucket) from the history
```
- **A type** is a schema and the operations allowed on it; an **instance** of a type is named by a path
(`listing/a17`, `decision/0290`); every change is an **operation**, kept in the instance's history.
- **A ledger effect** is what an operation does to the state, one of a fixed set: set fields, set an entry of a
map, append to a list, remove (ADR 0597 §2). An effect copies only the fields its type names, and may add the
operation's sequence and author. Where a type pairs a text field with its digest, `apply` refuses an operation
whose digest does not match. A module's own rules are checked by the module before it calls `apply`, never by the
effects. Only the owning module calls `apply` on its ledger, for every effect, remove among them; a person
removes through the owner's tools. This settles who may call the remove effect, which ADR 0597 §13 left to the
design.
- **One writer wins, and the state never goes back** (§5): the expected sequence makes the bus refuse a racing
writer; the state is written as an update of the revision read, never a plain put; when that update loses to
another writer, `apply` answers success with its operation's sequence and re-reads, never appending again.
- **A full state bucket loses no operation** (§6): `apply` answers that the operation is taken, with its sequence,
and that the state is behind because the bucket is full; the next `apply` after room is made catches it up.
- **The author is proven** (§7): `apply` stamps the owning module's authenticated account and the account that
called the owner's tool. The owner passes that author on by naming the tool call it serves: the tool runner, which
served that call and proved its caller, stamps the caller it proved, so the module cannot set the author to words of
its own; an `apply` naming no call in flight carries the owner's account alone, and one naming another module's
call is refused. A copy of old records (design 55 § 8.1) is stamped with the owner's account and keeps the old
author as a separate field marked imported, never as the proven author.
- **Every instance has a snapshot** (§8): the latest state on a subject of its own, never expiring, written by every
`apply`. It makes a kept ledger's rebuild fast and an expiring ledger's possible; a repair that finds it behind
the state rewrites it.
- **Only the tool runner's ledger credential publishes on a ledger's history** (§9): one per module assignment, that
is per node the module runs on, the account `ledger.<node>.<module>` in the tool runner's own secret `ledgers` on
that node (ADR 0597 §9, as its progressive insight of 2026-11-03 has it, waiting for the operator's Approve), held by
the tool runner and never by the module's own code, whose account may read its ledger and not publish on it. A
person's `rotate` of that secret is refused by the vault, as a bus account's is. The grants part issues it with the
module's membership on that machine, scoped to the subjects of that module's ledger
histories and snapshots, and removes it when the module is unassigned from the machine. Only the
owner's account reads the history, the snapshot and the state.
- **An index** is a second key-value bucket kept by a watcher in the owning module's process, rebuildable from the
history; it raises a condition when it lags behind (§4).
### 12.5 The calls, and where they live
The new calls live in a small mesh-sdk package of their own, served by the tool runner and imported only by the
modules that use them; the module library, which 112 modules import, does not change (ADR 0595 §9). They are the
object store's (put, get, list, delete, info, watch); a stream's read-back and fill; a work queue's size and dead
letters; and the ledger's: `apply`, `get`, `history`, `watch`, `query`, and its repairs `rebuild` (the state from
the history or the snapshot), `reindex`, `snapshot` and `lag` (ADR 0597 §10). The tool runner serves the repairs as
tools of every module that owns a ledger, limited to its own ledgers, so no owner declares them and the next ledger's
owner has them on its first day. mesh-sdk's catalog and membership
packages change once for the typed `requires` entry and the binding, rebuilding about 30 modules.
### 12.6 The move, and the order of the build
**The build, each step undoable on its own** (ADR 0595 §10): (1) mesh-sdk's typed `requires`, binding and calls
package; (2) the manifest validator's rules; (3) the bus module's process, verbs and events, creating only for the new form, with the grants part's writing of
the binding on `created`; (4) the tool runner's calls, the ledger's `apply` and its ledger credential among them; (5)
modules move, each owner first. Each undo: undoing step 2 refuses the new form again, which no module uses before
step 5; undoing step 3 leaves what it created in place, and a module moved after it fails loudly on its missing
binding; undoing step 4 leaves a moved module without its calls, which the placement holds off that machine. The
placement holds a moved module off a machine whose tool runner does not serve the typed binding and the calls the
module asks for (a ledger's `apply` among them), and says so; where the placement reads what a tool runner serves is
left to the build of step 4 and tracked on issue 1966.
**A module moves when it is next touched** (ADR 0595 §11), keeping its local names and carrying its old settings
as options, so its bus objects and data stay and no drift is raised. It asks for each entry once: an old section
and the new form are never both used for one local name. During the move the grants part keeps creating the old
sections' entries, so each entry has one creator. The indexer counts the modules on each old section, a tool reads
the count, and the manifest validator refuses a section once its count is 0. The foundation's own kept data (the bus module's,
the grants part's and the indexer's) stays on the old sections for good and is not counted: those modules cannot
wait for a process that needs them first. ADR 0619, extending ADR 0595 §10's foundation, adds the parts the bus module's own composition, placement, build or delivery needs before it can answer:
the assigner, the tool runner, the builder, the checker, mesh-config and the vault; their new state and streams of
this milestone go on their old sections too (§ 12.2; design 51 *The move*; design 32).
**Readers move after their owners** (ADR 0596 §3). Today 195 `reads` entries in 37 modules read another module's
bus state (counted 2026-11-03 02:00). **A correction of fact**: the indexer's and the assigner's state, counted again
from every manifest on main later that day, is read by 23 modules, 10 buckets of the indexer (`verdicts`, read by the grants part, among them) and 6 of the assigner,
not by the 19 the first plan counted; and 151 state entries were counted, not 158 (the template table of § 12.1 keeps
the first count, which chose the templates). The owners first gain their events, first-view tools and read tools: the
indexer a read tool per bucket its readers read, the assigner the same (§ 12.2 lists them). Then all 23 readers move in the milestone of ADR 0612, the
four foundation readers included, by the first view of § 12.2 (ADR 0615 §1), the grants part's of the indexer's
`verdicts` by its first-view tool `verdicts` (ADR 0622) and then `manifest-accepted` and `manifest-refused`, and the
assigner's of the indexer's `graph` by its first-view tool `graph` (ADR 0631) and then `indexer.views`; their order is the module graph's, not
a review reading an owner delivered (ADR 0615 §2). The status view's move keeps every tool it serves, each answered by
asking the owners' read tools of § 12.2. **The node-engine's reads granted in code stay**: the grants part's code
grants each node's node-engine, with no manifest declaring them (`CandidateReads` and the composed reads beside it),
the indexer's `candidates` and `verdicts` and its own node's keys of the assigner's `wants`. They are not among the
23 readers of ADR 0615 §1 and move in the next milestone, queued on issue 1966. The manifest validator still refuses a moved module's subscription to an event
its owner does not declare. Every other reader moves when its module is next touched. These moves are tracked by
issue 1966.
### 12.7 How it is checked
| Rule | Checked by |
|---|---|
| A manifest's bus state is valid, once | the manifest validator'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; the process connects on its own process account, composed by the grants part with that account's grants and limits, never on an account without them; a `create` handed through `requests` is answered on the same key, which the tool watches; `recreate` and `drop` without the operator's warrant are refused, and a warranted `drop`, its warrant read from the operator channel's own record of the ask under the process's account and never from a stand-in, takes the entry's stream snapshot before it deletes, and acts within seconds of the bus module's `decided`, with no timer between; the same warrant handed in a second request is refused and deletes nothing; 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; for the indexer's `graph` (ADR 0631), called by the assigner it answers with its revision, and from any other account, the indexer's own included, it is refused; a missed revision of the bucket `graph` on `indexer.views` makes the assigner ask `graph` once more; started with the indexer down, the assigner raises past the bound the first-view condition naming the indexer and `graph` and reads nothing of 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 assigner's whole-module test, the assigner starts before any new-form bus state exists, with no binding of the bus module, and the indexer, the grants part and the tool runner each get their first view of it. Live, after the delivery: the indexer's `indexer_old_sections`, which the milestone extends to count the `reads` entries on each owner's state, reads 0 declared `reads` entries on the indexer's state and 0 on the assigner's, and says the node-engine's reads granted in the grants part's code remain (§ 12.6); and each owner's read tool of § 12.2 answers what its bucket holds, each status view tool answers a session's call as before the move, and `mesh_search` finds each owner's read tool |
| 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 manifest validator's known fields for these verbs (§4) |
| 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 |
| A person's request goes through `requests`, and the process verifies the warrant itself and acts on it once (ADR 0626 §4, ADR 0259 §6) | the process's unit tests: a `recreate` and a `drop` written to `requests` with no warrant, with a warrant for another act or entry, with a warrant the operator channel's record does not hold, and with a warrant whose ask id the process already acted on 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 manifest validator'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 |
| The process's fixes of review round 1 hold | the nats module's whole-module integration test and unit rows: an event or condition the bus did not take is kept, named by the health tool and said again at the next fill pass; a second accepted manifest asking for an entry raises no overdue condition; the warrant's wake on `decided` acts within seconds without a call to the pass by the test; a second request naming a spent ask is refused naming the act it spent; an ask past 12 hours is not acted on |
| 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 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 |
| Only the owner applies | the ledger's integration test: another module's ledger `apply` on the knowledge base's ledger is refused |
| A bare stream is complete | the manifest validator's unit test: a bare stream missing "when full", a cap or an age is refused, naming the field |
| The calls rebuild only their users | a read of the delivery plan: only the importers of the calls package rebuild when it changes |
| The move keeps data | live: a module moved from `state` keeps its bucket and data and raises no drift; a new entry in an old section is still created by the grants part; the count falls by one; at 0 a manifest using the section is refused and the foundation's are still accepted; a moved module is held off a machine whose tool runner does not read the typed binding |
**The test budget** (50 integration and 500 unit tests per repository): the design adds one integration test in the
nats module's repository and one in mesh-tools (the ledger), and table cases, not new functions, to the manifest validator's unit
tests in mesh-delivery and to mesh-sdk's decoding tests. Each repository's count against the budget is read in the
prepare step of issue 1966, and a repository over it merges tests to stay within it.
**Acceptance.** The operator asks the bus module's `list` and sees every module's kept data with its template, its
settings and its fill; a module that moved keeps its data; a drift or an orphan reaches the operator as a condition
and is changed only on their word; and the knowledge base keeps its records as a ledger (design 55 § 10).
## Reviewed by architectural domain
The amendment of 2026-11-03 to ADR 0595, ADR 0596 and ADR 0597 (designs 25 § 12, 32 § 4 and 55 together) was
reviewed by the four reviewers by architectural domain side by side (playbook 01), over three rounds, and the lead
ruled on every finding. What was found, and what answers it:
| Domain | Found | Answered by |
|---|---|---|
| security | the author could be words the module chose; a person's dangerous tools had no role, mark or path to the process; the caller travelled as a plain field | design 25 § 12.3 (marks, the process's own tool subject, the identity seat's signed token), § 12.4 (the tool runner stamps the caller it proved; the move's authors marked imported) |
| seams | the bus module asked for its own events in the new form, which it would have to create itself (ADR 0595 §10); a person's tool had no join to the process; a verdict was written twice with no order | design 25 § 12.3 (its events on its old `streams` section; the process's own tool subject); design 55 § 2.1 (the `review` operation first, `reviews` caught up from it) |
| running qualities | overdue creation was undefined and raised by nobody; the database's rollback write lived in memory; a forward delivery after a rollback could miss acceptances and verdicts; no size estimate of the heads | design 25 § 12.2 (five minutes, the watchman, durable consumers, `check` at start); design 55 § 8.1 step 6 (`database.sequence`, the check at every start before the drop), § 2.1 (the heads' estimate) |
| health | the bus module's health would have fired on a quiet mesh; conditions had no clearing; `database-behind` had no clearing | design 25 § 12.2 and § 12.3 (each condition with what clears it); design 55 § 8.1 step 6 |
| events and logs | an event lost when the module stopped after `apply`; the bus module's events had no reader | design 55 § 1 (each event sent with its operation's sequence as id, the state `sent`); design 25 § 12.3 (`history` of one entry) |
| testing | the bus module had no test that starts it whole; live tests would have filled the live bus; the budget was not counted | design 25 § 12.7 (the nats module's integration test, live drift only by a manifest change, the budget paragraph); design 55 § 10 |
| 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
and § 12.3. The milestone's amendment (ADR 0613 to ADR 0615: the first view, the bus-state edge, the deletion paths,
the caller until the identity seat, the reader count) awaits its own review by architectural domain, which rewrites
this section.
+417 -14
View File
@@ -15,8 +15,26 @@ code:
- mesh-catalog modules/gitea/module.json
- mesh-controller internal/inventory/migrations/0063-a-machines-names-are-one-seats.sql
- mesh-controller internal/inventory/migrations/0064-the-resolver-file-is-the-uplinks.sql
updated: 2026-10-10
updated: 2026-11-09
decisions:
- "ADR 0641"
- "ADR 0636"
- "ADR 0634"
- "ADR 0635"
- "ADR 0596"
- "ADR 0593"
- "ADR 0625"
- "ADR 0573"
- "ADR 0606"
- "ADR 0609"
- "ADR 0595"
- "ADR 0627"
- "ADR 0608"
- "ADR 0613"
- "ADR 0620"
- "ADR 0612"
- "ADR 0614"
- "ADR 0605"
- "ADR 0287"
- "ADR 0223"
- "ADR 0220"
@@ -98,7 +116,7 @@ nobody argued for is an entry nobody can explain.
**What deserves one** (ADR 0161). A provision the
mesh's own code dereferences by name is delivered by a mesh seat its provider claims — the store, the
bus, the vault, the artifact store, the catalogue. A provision a module merely offers may have several
bus, the vault, the artifact store, the catalog. A provision a module merely offers may have several
providers, and a consumer with several is a person's choice. A fact of the shape *exactly one machine
is X* — the hub — is not a seat, because a seat is held by a module assignment and points at it; it is
a placement with a capacity of one, kept by the store, refused by name when a second is placed, and
@@ -114,7 +132,7 @@ capability is.
ADR 0110): a module
declares its own seats with their protocols, so the seats a mesh has are the mesh's own **plus
every registered module's**. The set is still closed — a seat named nowhere is refused — but it is
computed from the catalogue rather than maintained by hand, which is the property 0110 actually
computed from the catalog rather than maintained by hand, which is the property 0110 actually
needed and the table could not keep.
**And the mesh's own half is data, named for its scope.** Revision, 2026-09-27, reconciling two
@@ -125,7 +143,7 @@ the set out of compiled code into a table the controller owns, so a rename is on
rebuild of everything that names one.
So the set has two halves and neither is written out here: the mesh's own, which the controller holds
as rows, and every registered module's, which is computed from the catalogue. What this document keeps
as rows, and every registered module's, which is computed from the catalog. What this document keeps
is what a seat *is* — the rest would be a third copy, stale the first time somebody renamed one, which
is the fault ADR 0122 exists about.
@@ -139,32 +157,391 @@ convention, which later seats departed from.
|---|---|---|---|
| `mesh-controller` | — | mesh | — | the controller |
| `mesh-store` | — | mesh | — | the store the mesh's own records live in |
| `mesh-broker` | — | mesh | `mesh-bus` | the broker carrying the mesh's own bus |
| `mesh-broker` | — | mesh | `mesh-bus`, and `bus-state` (ADR 0595 §1, ADR 0614 §5) | the broker carrying the mesh's own bus; its holder, the bus module, creates the bus state modules ask for (design 25 § 12) |
| `mesh-vault` | — | mesh | `secret` | the vault (in the seed since ADR 0161; the earlier *reserved* named an effect no rule produced) |
| `mesh-artifact-store` | `the-artifact-store` (renamed 2026-09-30, ADR 0156) | mesh | `artifact-store` | the artifact registry |
| `mesh-catalog` | `the-catalogue` | mesh | — | the catalogue |
| `mesh-npm-package-registry` | `npm-package-registry` | mesh | `npm-package-registry` | the forge |
| `mesh-git` | `git` | mesh | `git` | the forge |
| `container-image-registry` | `mesh-artifact-store` for images (ADR 0605; the old name readable until every node-engine reads the new one) | mesh | `artifact-store` | the artifact registry (`distribution`) |
| `oci-artifact-registry` | `mesh-artifact-store` for bundles and archives (ADR 0605) | mesh | `artifact-store` | the artifact registry (`distribution`) |
| `mesh-catalog` | `the-catalogue` | mesh | — | the indexer |
| `npm-package-registry` | — (its rename to `mesh-*` stays deferred, ADR 0156 §8) | mesh | `npm-package-registry` | the forge |
| `go-package-registry` | — (ADR 0605) | mesh | `go-package-registry` | the forge |
| `git` | — | mesh | `git` | the forge |
| `mesh-build-machine` | `the-build-machine` | node | — | a builder |
| `mesh-resolver` | — | mesh | — | the mesh's resolvers, each holding every node's internal domain (ADR 0194); replicated, held on the anchor and the home server (ADR 0223) |
| `mesh-dns-resolver` | — | mesh | — | the mesh's resolvers, each holding every node's internal domain (ADR 0194); replicated, held on the anchor and the home server (ADR 0223) |
| ~~`mesh-dns-port`~~ | `the-dns-port` | node | — | retired by ADR 0194: the local resolver became the mesh's one; deleted from the set, and from the store's table, once nothing claimed it (ADR 0220) |
| `node-hostname` | `node-hosts-file` (renamed by ADR 0223; the former name an alias) | node | — | owns a machine's names: `/etc/hostname`, written from its holder's `hostname` setting with no default and taking effect at the next boot, and in `/etc/hosts` the machine's own lines and the operator's kept region, changed through its verbs `entries`, `add`, `remove` (ADR 0199). Held by the module `hostname`, formerly `hosts` |
| `node-resolver` | — | node | — | a machine's own resolver, held only where something requires `split-dns`: it writes `/etc/resolv.conf` there (the uplink's holder steps back from it) and routes a VPN's domains to the VPN's servers over its link through its verbs `routes`, `route`, `unroute` (ADR 0247). Held by the module `systemd-resolved` |
| `mesh-intrusion-prevention` | `the-intrusion-prevention` | node | — | an intrusion-prevention service |
| `mesh-packet-filter` | `the-packet-filter` | node | — | the packet filter |
| `mesh-private-network` | `the-private-network` | node | — | the private network the mesh runs over |
| `the-private-network` | — (it keeps its name, ADR 0636 §6) | node | — | `mesh-wireguard`, the private network the mesh runs over |
| ~~`mesh-resolver-configuration`~~ | `the-resolver-configuration` | node | — | retired by ADR 0223: `/etc/resolv.conf` is written by the holder of `node-uplink`, the program that would otherwise rewrite it, and the need of the uplink beside it (ADR 0220) goes with it; deleted from the set, and from the store's table, once nothing claims it |
| `mesh-showcase` | `the-showcase` | node | — | the showcase module |
The controller holds **the mesh's own** entries in code, and a test asserts their size and that
every one names the record that made it a seat. A module's seats are not here and never will be —
they are read from the catalogue. **This table and
they are read from the catalog. **This table and
ADR 0126 govern, and code that
disagrees is what is wrong.** The implementation in progress predates several
things here: seats held by assignments rather than claimed by definitions, the `mesh-vault` seat and
its reservation, and the foundation's seats delivering nothing. It is brought to this table before it
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). Every seat has its definition file in its domain's contracts module, written by hand, whether it is
defined whole or at the seat list's grain (ADR 0635 §2). In the milestone of ADR 0612, 25 seats are defined whole
(ADR 0613 §1, ADR 0620, ADR 0627 §1, ADR 0634 §6, ADR 0635 §5); every other seat is defined at the seat list's grain.
- **The file** is a schema with conformance fixtures: the seat's verbs and their messages, its events and their
bodies, its states and the forms of its provisions, and names its glossary domain (ADR 0636 §5). 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 list's verb inputs already are, with the format's own schema checked in;
the fixtures are data, never functions.
- **A definition names its states** (ADR 0608 §1; ADR 0634 §6 leaves the file's format to this design). A `states`
entry is what any holder of the seat keeps and what the seat's verbs answer from: its local name, its template of
ADR 0595 (state, events, work queue, log, objects or ledger), who writes it, each form of its keys with the schema
of the value under it, how long it keeps its history, and its size cap. The holder writes every state; only a state
of the events or log template may name each caller as the writer of its own keys, granted on keys under the
caller's own name and no other. No entry names a holder module, so another module can hold the seat by importing
the contract alone (ADR 0625 §7). The generated package carries, per state, its local name, a builder and a parser
per key form, and the value types, decoded strictly; the fixtures hold one value per key form.
`operator-channel`'s `records` becomes one `states` entry in the same change, so the format has one form for a
state. The format's own schema refuses an entry with an unknown template or a key form without a value, naming it.
**A state is the holder's, asked through the seat's verbs** (ADR 0596 §2): the module that reads another module's
bucket directly today keeps doing so only as a reader in transition, through its own manifest's `reads`, until its
module moves to the owner's verbs or events (ADR 0596 §3, issue 1966). The bucket's name stays
`<holder>_<state>`, the holder's own, so nothing moves under a seat's rename. **How it is checked**: the manifest
validator refuses a holder whose `requires` does not declare each of its seat's states with the same local name and
template, naming the state; the format's own schema refuses a caller-written state of another template and a state
with no size cap.
- **What is defined whole.** Ten seats came first (ADR 0613; ADR 0620, on the operator's answer of 2026-11-04 to move
them all; ADR 0627 §1): `npm-package-registry`, `go-package-registry`, `container-image-registry` and
`oci-artifact-registry` (one common part of their shared verbs, written once, so the four cannot drift),
`mesh-broker`, the four seats the milestone adds a verb or an event to, each with every verb its holder's manifest
on the trunk declares today, plus the new ones, and `node-engine`. Fifteen more are defined whole in the same
milestone because a name leaving mesh-sdk (*Where a seat's code goes*) is their type, state layout or message
(ADR 0634 §6, ADR 0635 §5), each with its verbs, events, messages and the layouts of its states:
`mesh-module-assigner`, `mesh-wants`, `mesh-node-enroller`, `mesh-catalog`, `node-build-go`, `node-build-image`,
`node-build-node`, `mesh-hand-acts`, `mesh-provisioner`, `mesh-conditions`, `mesh-self-check`, `mesh-healers`,
`mesh-watchdogs`, `the-private-network` and `mesh-delivery`. Five seats already whole gain the state layouts
mesh-sdk held for them: `node-engine`, `mesh-vault`, `mesh-delivery-checker`, `container-image-registry` and
`oci-artifact-registry` (ADR 0634 §6). **No event moves subject in this milestone** (ADR 0620), but those of the
two renamed seats (*Two seats renamed*, below): a seat's own events are only those published on its seat subject
today, and a holder's own events stay under the holder's own subjects, listed beside the seat they belong with,
never moved onto it. The four seats the milestone adds to:
- `mesh-delivery-checker` (held by the checker): the verbs `try`, `try-read` and `try-end`; no seat event. The
holder's own, beside it: its family `checker.asks`, new, with `tag-wanted` (design 51 *Tagged versions*) and
`verdict` (*Out of step is learned from events*, below); and its stream `checks`, which already declares
`preview.**` and `owed.**`, only its `emits` lacking `preview.written`, which the same change adds.
- `mesh-config` (held by mesh-config): the verbs `config` and, new, `renames`; no seat event. The holder's own,
beside it: `config-changed`, and its family `config.events`, new, with `renamed`, `retiring` and `retired`
(design 32).
- `mesh-vault` (held by the vault): the verbs `get`, `secret-ask`, `issued`, `rotate`, `move-in`, `node-key`,
`own`, `issue-account`, `sign`, `enrolment-token`, `node-account`, `rotate-node`, `node-account-confirm`,
`abandon` and, new, `retire`; no seat event. The holder's own, beside it: `provisioned`, `rotated`,
`secret-changed`, `account-hashed`, `own-replaced`, `account-issued`, `signed`, `rotation-begun`,
`node-account-ready`, `rotation-done` and, new, `own-retired` (design 32). The seat list mesh-sdk compiled
also names `accept` and `move-asks`, which no holder serves and nothing calls: the definition drops them.
- `operator-channel` (held by the router, the messenger module): the verbs `open`, `history`, `notify`, `tell`
and `asks`; the asks it accepts, `ask`, `cancel` and `condition`; its seat event `decided`; `by-caller` for
`ask`, `cancel`, `condition` and `decided`; and its state `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).
Its definition is written from the holder's seat entry.
And `node-engine` (held by the node-engine on every node) has the verb `manifest-reads` and its seat event
`manifest-reads-changed`, which the milestone gives it (ADR 0618 §3, §4; design 51). The 25, by the contracts
module that holds each (ADR 0634 §7, ADR 0635 §5):
| contracts module | domain | seats | held by |
|---|---|---|---|
| `mesh-delivery-contracts` | Delivery | `mesh-catalog`, `mesh-delivery-checker`, `mesh-delivery`, `mesh-wants`, `git`, `node-build-go`, `node-build-image`, `node-build-node`, `npm-package-registry`, `go-package-registry`, `container-image-registry`, `oci-artifact-registry` | the indexer, the checker, the gate part, the assigner, the three build modules, the forge (three), `distribution` (two) |
| `mesh-health-and-repair-contracts` | Health and repair | `mesh-conditions`, `mesh-self-check`, `mesh-healers`, `mesh-watchdogs`, `mesh-hand-acts` | the condition keeper, mesh-self-check, mesh-healers, the watchman, mesh-hand-acts |
| `mesh-provisioning-contracts` | Provisioning | `mesh-provisioner` | mesh-provisioner |
| `mesh-identity-and-access-contracts` | Identity and access | `mesh-vault`, `mesh-node-enroller` | the vault, the module `mesh-enrolment` |
| `mesh-connectivity-contracts` (mesh-networking repository, ADR 0636 §6) | Connectivity | `the-private-network` | `mesh-wireguard` |
| `mesh-operator-and-conversation-contracts` | Operator and conversation | `operator-channel` | the router |
| `mesh-contracts` | Core, and Config | `node-engine`, `mesh-broker`, `mesh-config`, `mesh-module-assigner` | the node-engine, the bus module, mesh-config, the assigner |
ADR 0641 retired the Placement domain: module assignment is Core's, so `mesh-module-assigner` is defined in
`mesh-contracts`, and the wants are Delivery's, so `mesh-wants` is defined in `mesh-delivery-contracts`; the module
`mesh-placement-contracts` is not created (ADR 0641 §1, §2). From research 085's milestone (design 47) the seat
`mesh-grants` is defined whole in `mesh-identity-and-access-contracts` (ADR 0636 §5), and the seat `git` gains in
`mesh-delivery-contracts` the verbs by which every delivery part reaches the forge (*The git seat*, below). How it is
checked: the indexer refuses a definition of these seats from any other contracts module, naming both (ADR 0636 §5),
and its domain check refuses a definition naming the domain Placement (ADR 0641 §5).
**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
it publishes) and matches it, subject and body, against the definition; the indexer's generator tests cover each
of the 25 (ADR 0634 §10, ADR 0635 §6). The builder and the indexer's own events hold no seat:
the builder's `numbered` and `old-form-closed`, the indexer's `manifest-accepted` and its family `indexer.views`
are those modules' own, declared in their own manifests, which
ADR 0613 does not govern, and no seat definition carries them. Every other seat, the foundation's included, has its definition on the bus in the same milestone, all
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. Its file is written by hand in its domain's contracts module, or in
`mesh-contracts` where its domain has none; the files the registry branch generated once from mesh-sdk's seat list
are their starting text, and nothing generates them again (ADR 0635 §2). Its messages, events and state layouts are
added to 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).
- **Two seats renamed** (ADR 0634 §9): `mesh-placement` becomes `mesh-module-assigner`, and `mesh-enrolment`
becomes `mesh-node-enroller`; the module `mesh-enrolment` keeps its name. Their definitions, the subjects of their
verbs and events, every holder's claim, every caller's `invokes` and grant, the claude-code instructions' text, the
mesh MCP server's description and the glossary take the new names in the same delivery group, and nothing answers
to the old ones: a call on an old subject fails loudly, naming the seat. **No state moves**: a state's bucket is
the holder's (`<holder>_<state>`), so placement keeps every revision. The old subjects' events keep only their
stream's own retention. **The order is the module graph's**: the grants of the new subjects are an ordering edge
that comes before the holders move, and the callers come after the holder that serves the renamed verbs; an older
node-engine takes its new build through `mesh-wants`, which is not renamed. **A machine enrolling with an installer
built before the rename** asks the old enrolment seat's subject, which no holder answers: its enrolment fails
loudly, naming the seat, and nothing joins; it enrols with an installer of the new build. **How it is checked**: the
manifest validator refuses a claim, an `invokes`, a `consumes` or a grant naming a seat no definition names, so an
old name fails
(ADR 0634 §10); the acceptance after the delivery is that `mesh-module-assigner.placement` answers and
`mesh-placement.placement` is not found, placement's revisions are those it had before, and no `seat-holders` key,
finding or condition stays under an old name.
- **Every part learns the seat list from the bus, through the seat `mesh-catalog`** (ADR 0635 §1, as ADR 0636 §4
changes it). The node-engine, the tool runner, claude-code, the manifest validator and every other reader of the
list of seats call, through mesh-sdk's runtime, the verb `seat-definitions` of the seat `mesh-catalog`: without a
seat it answers every trunk's seat with its digest, with a seat that seat's definition. They hear the seat's events
`seat-definition-changed` and `seat-definition-removed`, said for the trunks' definitions. A reader names no
module: it calls the seat, never its holder, the indexer, by name. A running part acts on what is merged, so a
reader takes no definition from a pull request's head; the manifest validator inside a delivery group's check is
the one reader that reads the members' heads. No package carries the seat list, and mesh-sdk imports no contracts
module.
**A reader without the list acts on nothing new, and keeps running what it runs** (ADR 0636 §1, changing ADR 0635
§3). A reader that starts without the list applies, composes, grants and judges nothing new, except for the
bootstrapped modules below; it keeps running what it already runs, says in its health what it waits for, and a
node-engine after a reboot starts again the compositions it last applied. Each node writes one finding when its
readers have waited five minutes (ADR 0564 §2); the condition keeper raises it as a condition, which reaches the
operator as every condition does, and clears it at the first full read. A reader away longer than the events'
retention reads the whole list again. A check that cannot read the definitions it needs fails, naming them, rather
than passing without them.
**The bootstrapped definitions** (ADR 0636 §2, changing ADR 0608 §2) are the foundation's seats (research 075) and
`mesh-catalog`, `mesh-conditions` and `operator-channel`: every reader carries them from its start and acts on their
holders without the list, so after a full restart the indexer comes back and serves the list, and the condition
keeper and the router, with the channels it sends through (ADR 0259), carry a wait's condition to the operator.
**A missing or refused definition blocks new claims only** (ADR 0636 §3): when a seat's definition is missing,
removed or refused, readers refuse a new claim, `invokes` or grant of that seat, and never stop or remove a module
that already runs holding or calling it.
**Each reader's list has two tools** in mesh-sdk's runtime bundle (ADR 0636 §7): one reads which definitions a
reader holds, their source and digests and what it waits for; the other, granted to the operator and the healers,
makes it read the list again now.
**How it is checked** (ADR 0635 §6, ADR 0636 §8; *Acceptance tests*, below): the node-engine's whole-module test,
against a stand-in of the seat, acts on nothing but the bootstrapped modules without the list and on all once it
answers, and starts its last compositions after a restart; the indexer's whole-module test starts with only the
bootstrapped seats and answers `seat-definitions`; with the indexer kept down, the node's finding is written after
five minutes and the condition keeper raises it to the operator; a refused definition stops no running module; a
reader refuses a pull request head's definition; mesh-sdk's unit test refuses a module's name in the runtime; both
tools answer.
- **The generator** is each language's build module's: the Go build module's package for Go, the Node and TypeScript
build module's for TypeScript (the logic is the module's whose work it is). The generator's version is a build input
of every contracts module, so a changed generator rebuilds each contracts module once (ADR 0603 §3). Each build
module's test step regenerates and compares, for every module carrying the contracts marker (below): a committed
file that differs, a file missing, or a file in the package tree the generator did not write fails the step, naming
each path.
- **Out of step is learned from events, and the indexer runs no generator.** For a pull request, the check's step
fails with the out-of-step paths; the checker puts them in its verdict and emits its declared event `verdict`
carrying them (its `preview.written` is declared in the same change). For a trunk, the builder's build-end event
carries a trunk build's out-of-step paths, which is how a generator's change is seen, since no check of the
contracts module runs then. The indexer consumes both and writes the trunk's finding.
- **On the bus**: the indexer reads every seat definition from every trunk and open pull request, from the forge
bridge's messages, and keeps them in its own state `seat-definitions`, keyed by seat and source (the trunk, or a
pull request's head), as their only writer; a definition is at most 256 KiB. As the holder of `mesh-catalog` it says
`seat-definition-changed` (seat, source, digest), kept seven days, only when a digest changed, and
`seat-definition-removed` when a trunk's definition goes, both as events of the seat (ADR 0636 §4, changing ADR 0608
§3). **Only the trunk's entry is the seat's contract**: the readers of the seat list read the trunks' through
`seat-definitions`; the contracts modules' builds and the review ask `indexer_seat_definition`, which answers the
trunk's unless a pull request's head is named, and says which it answered. **The manifest validator inside the
delivery group's one check reads the seat definitions at every member's head** (ADR 0636 §4), so a group that
changes a definition is judged by what it merges. A
pull request's entries are removed on the forge bridge's event that it closed or merged. **A seat of the mesh's own
contracts is defined only in its domain's contracts module, and a move there is a handover** (ADR 0636 §5, changing
ADR 0608 §2): a definition names its glossary domain; the indexer takes a seat of the mesh's
own contracts only from that domain's contracts module, `mesh-contracts` for a domain with none, and refuses a
definition of it from any other module, with a finding naming both. A definition moving from `mesh-contracts` to its
domain's contracts module is a handover: the indexer keeps the last trunk definition until the new one is merged,
in either order of the two trunks. A seat defined outside the mesh's own contracts is taken from its own contracts
module (ADR 0625 §7). A definition
that does not parse fails its pull request's check; the trunk's stays. The merge is the only approval. The
foundation's own definitions are bootstrapped before the bus exists, as the bootstrap of a fresh mesh has it
(research 075).
- **Findings**, written by the indexer, from which the condition keeper raises and clears the conditions (ADR 0564): a
trunk's seat definition that does not parse, `seat-definition-unparsed` (a pull request's is its check's verdict, not
a condition), cleared by a definition that parses; generated types on a trunk out of step with their definition,
`generated-types-out-of-step`, cleared only by a clean build end of the same contracts module, per module and not per repository, since several
contracts modules share one; a seat defined outside its domain's contracts module, naming both modules (ADR 0636 §5). **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 the seats' definitions,
their 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 manifest validator
refuses a module carrying it that claims a seat, naming the seat. **Each domain whose seats the milestone defines
whole has a contracts module of its own, created in the milestone** (ADR 0634 §7, ADR 0635 §5; the table above);
`mesh-contracts` keeps the Core domain's seats, `mesh-config`, and the definitions of every seat whose domain has
none yet. Each 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.
- **A contracts module and a domain SDK are modules like any other, found by their manifests** (ADR 0634 §8).
`mesh-delivery-contracts` and the Delivery domain's SDK are folders of the mesh-delivery repository, and the other
domains' contracts modules folders of the mesh-contracts repository, but the Connectivity domain's:
`mesh-connectivity-contracts` is a folder of the mesh-networking repository, beside `mesh-wireguard`, which holds
`the-private-network` with its manifest and peer generator its own (ADR 0636 §6, changing ADR 0634 §8). Each is a package-only module, as mesh-sdk long
is: published from its trunk, rebuilding the modules that use it like any package (ADR 0573 §2, §3), and delivered
to no node. A step of the build or the delivery that treats a module in a folder unlike one at a repository's root
is a gap of the build and delivery system, fixed in the milestone, never worked around. **How it is checked**: the
delivery group's one check builds and publishes every new module from its folder, and the build modules'
regenerate-and-compare step runs on every contracts module the milestone creates (ADR 0634 §10).
- **mesh-sdk takes no 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-delivery-contracts` is published through the forge module's package seats
and built by the Go and Node build modules, and the forge module, `distribution` and the Go build module import it. A
package edge and a build module's edge are triggers, never waits, so that cycle starts and is not refused (ADR 0614
§6), and a package is numbered per source revision, so the triggers end (design 51 *The versions*).
- **Older readers keep working**: a moved contract keeps its subjects, keys and message shapes, and a reader ignores
a field it does not know. The two renamed seats are the exception, and every one of their users moves in the same
delivery group (ADR 0634 §9, as it changes ADR 0608 §6).
- **A vendor-specific** provision or contribution lives in its module's own extension package, published by version
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, widened 2026-11-05* (ADR 0625, ADR 0627, ADR 0634, ADR 0635; the operator, 2026-11-04: "many small
sdk's instead of 1 large sdk", and shared logic lives with its owner). A module is rebuilt only for what it uses, so
shared code lives with its owner: a seat's code is cut per seat, in the contracts module of its domain; what one
module owns is that module's own package; what one domain's modules and seats share is that domain's SDK; mesh-sdk
keeps only what modules or seats of more than one domain use.
```
contracts module of a domain (mesh-<domain>-contracts; mesh-contracts for Core, mesh-config, and a domain with none)
├── definitions and fixtures written by hand, every seat's at its grain, the generation's source
└── one package per seat defined whole, per language generated: types, subjects, state layouts, a typed call per verb
└── its client package (where callers or holders share logic over the seat) written by hand
domain SDK (mesh-<domain>-sdk) written by hand: logic and forms one domain's modules and seats share, owned by no module
a module's own package written by hand: logic and state layouts one module owns, where it holds no seat for them
mesh-sdk the runtime every module uses, and what modules or seats of more than one domain share;
it imports no contracts module and reads the seat list from the bus
```
- **Shared code lives with its owner** (ADR 0634 §1), and the first home that fits is the one: a seat's types, the
layouts of its states and the messages of its verbs and events are its contract's, and the logic its callers or
holders share is its client's; logic and state layouts one module owns, where that module holds no seat for them,
are that module's own package, which other modules import from it; logic and forms no seat carries and no one
module owns, the seat-neutral parts seats' clients or holders share included, are their domain SDK's when only one
domain's modules or seats use them, and mesh-sdk's when more than one domain's do or every module does.
- **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 folder. In the milestone of ADR 0612 these are the 25 seats above.
- **A seat at the seat list's grain has its definition and no package** (ADR 0635 §1, §2): its readers learn it
from the bus, and a change of it rebuilds nothing.
- **The imports run one way per package** (ADR 0625 §3, as ADR 0634 §2 and ADR 0635 §1 change it): a generated
package imports nothing of mesh-sdk; mesh-sdk imports no contracts module; a domain SDK imports only mesh-sdk and
contract packages; a client imports its own seat's contract, mesh-sdk's runtime and its own domain's SDK. Where a
language's module is the unit of import, the clients are a module of their own in the folder, so the two never
form a cycle.
- **A client package** (ADR 0625 §4, as ADR 0634 §2 changes it) 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 or holders would otherwise each write over that seat, and only where such logic exists; it uses only its
own seat's contract, mesh-sdk's runtime and its own domain's SDK, 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.
- **A domain SDK** (ADR 0634 §2) is a package-only module, `mesh-<domain>-sdk`, named after the domain's heading in
the glossary, which may sit in a repository with that domain's modules. Its importers are its domain's modules and
the holders and callers of its domain's seats; it imports only mesh-sdk and contract packages, names no module's
tool or subject, and holds no seat's type or state layout and no state layout one module owns. The first is
`mesh-delivery-sdk`, in the milestone of ADR 0612: the moving of a file in parts (below), the build steps' and the
composer's shared logic, each made seat-neutral over its callers' types (ADR 0635 §4), and the rules the Delivery
domain's modules share.
- **A module's own package** (ADR 0634 §1) holds what that module owns and no seat carries: its state layouts that
other modules read and the logic over them. Its fingerprint counts only that package's files (ADR 0593 §2), so a
change elsewhere in the owner module rebuilds none of the package's importers. Another module of the same repository uses it by path, from the same
commit (ADR 0609 §2); a module of another repository uses it only by its name and a published version (ADR 0573
§1), so the owner's manifest declares it as a package artifact (ADR 0606 §4).
- **The clients of the milestone of ADR 0612** (ADR 0627 §1, ADR 0634 §4, ADR 0635 §4), each moved out of mesh-sdk
with every importer in the same delivery group, mesh-sdk keeping no copy and no alias: `operator-channel` (an ask
and its awaited answer, mesh-sdk's `asks` and `asker`); `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); `npm-package-registry`, `go-package-registry`,
`container-image-registry` and `oci-artifact-registry` (publishing a file in parts, one client per seat, each
binding the Delivery domain's SDK's transfer to its own seat's verbs and types); `mesh-hand-acts` (recording a
hand act); and `mesh-provisioner` (mesh-sdk's provider runtime and its harness, which only providers use).
`the-private-network` has none: the layout of the value it provides, which holds no key material, is the seat's
contract in `mesh-connectivity-contracts` (ADR 0634 §1), the private network's manifest and peer generator are
`mesh-wireguard`'s own, and the seat has a client only where its callers share logic (ADR 0636 §6, changing ADR 0635
§4).
- **Moving a file in parts is seat-neutral, in the Delivery domain's SDK, on both sides** (ADR 0627 §2, as ADR 0634
§3 changes it): it serves only the four registry seats, all of the Delivery domain. 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, ADR 0634 §7): 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 seven the milestone of
ADR 0612 creates are in *A seat's definition*, above; the order of the other 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 what modules of more than one domain use** (ADR 0625 §9, as ADR 0627 §2, ADR 0634 §1, §4, §5
and ADR 0635 §4 change it): the bus connection, the tools bundle's runtime, state and its helpers, the answer of a
module's health tool, the `Membership` type with the names its runtime reads to learn its own membership, the
package `views` (which takes its hand-act recorder and its finding writer from its caller), `outward`, the parts of
`forgekey` that modules of more than one domain use, and a seat-neutral part seats of more than one domain share,
as long as it names no seat, verb or seat's type. In the milestone of ADR 0612 its `go/delivery` is moved whole and
deleted, each of its names to the home this section gives it, and every other part naming a seat or a holder's
state leaves for its owner, every importer moving in the same delivery group; after it, mesh-sdk holds no package,
type or function over a seat defined whole, and no seat list (ADR 0627 §4, ADR 0634 §4, ADR 0635 §1).
**How it is checked** (ADR 0625 §11, ADR 0627 §3, ADR 0634 §10 and ADR 0635 §6, all built in the milestone of ADR 0612):
| Rule | Checked by |
|---|---|
| One package per seat defined whole | a unit test of the generator (one program in the Go build module, emitting both languages and run by the Node build module too) emitting one package per seat defined whole, covering each of the 25; the manifest validator 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 of mesh-sdk imports a contracts module; the generator tests check no generated package imports mesh-sdk; a domain SDK's importers and imports by the review below |
| mesh-sdk holds no logic over seats, and no part that left it | mesh-sdk's package-list test refuses by name `go/delivery`, `asks`, `asker`, the vault's types and its shared calls, the compose-candidate checks, the provider runtime, and every other package or part ADR 0634 §4 and ADR 0635 §4 move; its seat-naming test refuses the defined seats' names in mesh-sdk, so a copy kept without importing a contract fails too |
| A client uses only its own seat's contract and its domain's SDK | the catalog check of a client: its own test refuses a client importing another seat's client or another domain's SDK, and one naming a module's tool or subject, and passes every client of the milestone |
| The parts transfer is seat-neutral | its unit test, in the Delivery domain's SDK, 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; the step runs on every contracts module |
| A module in a folder is built and published as one at a root | the delivery group's one check builds and publishes every new contracts module and the domain SDK from its folder, and `mesh-wireguard` and `mesh-connectivity-contracts` from the mesh-networking repository |
| A seat is defined only in its domain's contracts module | the indexer refuses a second module's definition of a seat, with its finding naming both, and a move from `mesh-contracts` holds in either merge order (ADR 0636 §5) |
| A holder keeps its seat's states | the manifest validator refuses a holder whose `requires` does not declare each of its seat's states with the same local name and template |
| A contracts module holds no seat; a role only one module could ever play has none | the manifest validator'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 |
| Each new exported name sits where this section puts it | the review of every pull request (playbooks 07 and 08, the code reviewer's definition) asks the home of each new exported type, field, constant, package or module against this section, a domain SDK's importers included |
**Acceptance tests**, each at its level (unit, or a case of the module's one whole-module integration test against the
real bus and store) and in its repository. The move raises no repository's test count, since mesh-delivery is already
over its budget: each case below replaces or joins an existing one.
| Test | Level | Repository |
|---|---|---|
| research 081's 14, 21, 25 and 26 | as research 081 sets them | as research 081 sets them |
| mesh-sdk's seat-naming, import and package-list tests; no module's name in the runtime | unit | mesh-sdk |
| a reader of the seat list, against a bus the test gives: a reader away longer than the events' retention reads the whole list again; a reader refuses a pull request head's definition; both list tools answer, the re-read one only for the operator and the healers | unit | mesh-sdk |
| the node-engine, against a stand-in of the seat `mesh-catalog`: without the list it acts on nothing but the bootstrapped modules, then on all once the stand-in answers; after a restart it starts its last applied compositions again; a refused definition stops no running module | a case of the node-engine's whole-module test | `mesh-host` (the node-engine's repository) |
| the indexer starts with only the bootstrapped seats and answers `seat-definitions`, without a seat (names and digests) and with one; with the indexer kept down, the node's finding is written after five minutes and the condition keeper raises it to the operator | cases of the indexer's whole-module test | mesh-delivery |
| a trunk definition that does not parse writes its finding and a fixed one clears it; a trunk build end naming out-of-step types writes the finding, a clean build end of another contracts module of the same repository leaves it, and a clean one of the same module clears it | a case of the indexer's whole-module test | mesh-delivery |
| `indexer_seat_definition` answers the trunk's entry while a pull request holds another; a pull request's entries go when it closes; a definition over 256 KiB is refused; a seat-list-grain definition is read from a contracts module like a whole one; a removed definition says `seat-definition-removed` and its seat takes no new claim afterwards; a second module defining a seat is refused with its finding, and a definition moving from `mesh-contracts` to its domain's contracts module holds in either merge order; each of the indexer's tools answers | cases of the indexer's whole-module test | mesh-delivery |
| the manifest validator refuses a claim, an `invokes`, a `consumes` or a grant naming `mesh-placement` or the seat `mesh-enrolment`, and a holder missing one of its seat's states in `requires` | unit | mesh-delivery |
| the checker's `verdict` names out-of-step files; the group's check reads seat definitions at every member's head | a case of the checker's whole-module test | mesh-delivery |
| each build module's compare step fails on a differing, a missing and an unwritten file, naming each, per contracts module | unit | mesh-catalog |
| a change in one folder module rebuilds and publishes only it and its importers; a module with both a deployed and a package artifact (the grants part or disk-load) is built, delivered and published | a case of the Go build module's whole-module test | mesh-catalog |
| after the delivery, `mesh-module-assigner.placement` answers and `mesh-placement.placement` is not found; placement keeps its revisions; no `seat-holders` key, finding or condition stays under an old name | live, read through the mesh's tools | the mesh |
| `mesh-wireguard` is built and delivered from the mesh-networking repository | the group's one check, then live | mesh-networking |
## The foundation's seats
`mesh-controller`, `mesh-store` and `mesh-broker` name which assignment the mesh *itself* uses: the
@@ -312,6 +689,13 @@ difference: it receives a URL either way.
With the seat unheld, a build from the seat is refused and says why. External builds carry on.
**The seat's verbs, from research 085's milestone.** The delivery parts reach the forge through the seat `git`'s
verbs alone, never by the forge module's own tools: reads for the parts that declare them in their `invokes`, and
acts (a status, a comment, the delivery's view, a line on the commit's note, a merge) for the forge bridge alone, as
the holder's trusted value `callers` names; the forge's events (a pull request updated, merged or closed, the forge's
own webhooks, a repository writable again) are the seat's events. Design 47, *The verbs*, lists them with their
callers and how they are checked.
**Not yet designed:** a credential for cloning a private repository. The mesh's own repositories are
public. The natural place for a clone credential is a `secret` from the vault, and that is a decision
still to take.
@@ -326,7 +710,7 @@ checked as their tables say:
| Rule | Checked by |
|---|---|
| The set is closed, and every mesh entry names its decision | 0118: a unit test on the mesh's own entries. **The refusal of an unknown seat is at registration, not in the parser** — correction of fact, 2026-09-27: a module may hold a seat *another* module declares, which is the point of naming the seat and not its provider, so whether a claimed name exists is a fact about the whole catalogue and a manifest in isolation cannot be judged on it. Registration tests cover an invented name and a name another module declares; the parser still refuses a claim on the mesh's own `mesh-*`/`node-*` namespace and a scope that disagrees with a declaration in the same manifest. |
| The set is closed, and every mesh entry names its decision | 0118: a unit test on the mesh's own entries. **The refusal of an unknown seat is at registration, not in the parser** — correction of fact, 2026-09-27: a module may hold a seat *another* module declares, which is the point of naming the seat and not its provider, so whether a claimed name exists is a fact about the whole catalog and a manifest in isolation cannot be judged on it. Registration tests cover an invented name and a name another module declares; the parser still refuses a claim on the mesh's own `mesh-*`/`node-*` namespace and a scope that disagrees with a declaration in the same manifest. |
| The set is derived, and enumerating it is a query | 0118: the overview lists the mesh's own plus every registered module's, asserted against a fixture mesh. |
| `mesh-*` is the mesh's, and a module may not declare one | 0118: a registration test refusing a manifest that declares any `mesh-*` seat, naming the prefix. |
| Two modules cannot declare the same seat | 0118: a registration test; the second is refused and the first untouched. |
@@ -339,7 +723,7 @@ checked as their tables say:
| `secret` has one provider, the holder of `mesh-vault` | 0161: a second claimant of the seat is refused by name (`CanHold`); *correction of fact, 2026-10-01: no parser rule ever reserved the word, the seat does the work*. |
| A singular fact about machines is a placement of capacity one, refused by name | 0161: the private network command's test for a second hub; the store's unique index. |
| A holder of `node-uplink` is the dialect the machine runs | 0161: the node-engine reports `uplink-<manager>` in its profile with every report; a resolution test refuses the other holder naming the capability. |
| A seat's holder has the seats it needs beside it: the resolver configuration is refused at `assign` without the uplink held on its node, and the uplink's last holder cannot be taken from beneath it | 0220: seat-dependency tests on the definition, on a synthetic claimant, at assign, at unassign and at composition, and one reading the catalogue for the uplink's possible holders. |
| A seat's holder has the seats it needs beside it: the resolver configuration is refused at `assign` without the uplink held on its node, and the uplink's last holder cannot be taken from beneath it | 0220: seat-dependency tests on the definition, on a synthetic claimant, at assign, at unassign and at composition, and one reading the catalog for the uplink's possible holders. |
| A replicated seat has every holder on record and composes on each; a seat held once still refuses a second holder, on record or not; `--add` is refused for it | 0223: resolution and composition tests with two holders on record and a third machine, with two claimants and nothing on record, and on `mesh-store`; a unit test that only `mesh-dns-resolver` is replicated, surviving the store's rows; store tests keeping several holders once each, a handover leaving one, and unassigning one taking only its row. |
| A retired seat leaves the set once nothing claims it, from the compiled set and the store's table both | 0220: the closed-set test's count, and the store migration that deletes the row. |
| A node seat names only literal absolute paths; every path has one seat naming it outright, and stepping back does not cycle | 0287: a unit test over the compiled set; registration tests refusing a module's seat naming a path at mesh scope, with `${`, or already named by another seat. |
@@ -347,3 +731,22 @@ checked as their tables say:
| The uplink's step-back comes from the seat | 0287: the composition tests for the uplink and the resolver on one machine pass with the case in the collision check removed. |
| Holdings are derived, and the overview lists every seat | 0118: the `seats` command test, including an unheld seat. |
| A build source on the seat records no address; an unheld seat refuses only self-hosted builds | 0111's tests. |
## Reviewed by architectural domain
The amendment of 2026-11-03 for research 081 (ADR 0605 to 0611; *A seat's definition*) was reviewed with designs 51
and 32 by the four reviewers by architectural domain; the findings and what answers them are listed in design 51's
*Reviewed by architectural domain*. For this design: only the trunk's definition is the contract (security), the
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, 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 list's one source), with the amendment of 2026-11-04 (ADR 0625, ADR 0627: ten seats defined whole, a package per
seat, a package for the seats at the seat list's grain in `mesh-contracts`, the seven clients and the seat-neutral parts transfer, *Where a
seat's code goes*), and the amendment of 2026-11-05 (ADR 0634, ADR 0635: shared code with its owner, the domain
SDK, a module's own package, a contracts module per domain the milestone moves, 25 seats defined whole with their
states, the seat list read from the bus, two seats renamed), with ADR 0636 (the seat list through the seat
`mesh-catalog`, a reader without it acting on nothing new, a seat defined only in its domain's contracts module, the
Connectivity domain in the mesh-networking repository; accepted at its version 15) and the lead's rulings on the first review by architectural
domain written in, await their final review, which rewrites this section.
@@ -47,7 +47,7 @@ A requirement has three parts:
**A contract is shared, not per module.** A database's contract is the database's, whoever requires
it. **The controller holds every contract**, one per provision name, declared where the provision is
defined in the catalogue. Today contracts are implicit in each provider's served fields; the first
defined in the catalog. Today contracts are implicit in each provider's served fields; the first
phase below makes them explicit, because nothing can be checked against a contract that is not
written down. A provider is checked against the contract it claims to answer. A module's own
specification may narrow a contract (a password of at least this length, a directory owned by this
@@ -213,13 +213,13 @@ a placed directory under the node's root. Each is this design's provider in the
placeholders have, not yet the one requirement form below; they are phase 1's first cases.
*Phase 3, in part (2026-09-30):* every definition's **own** data directory is placed; the conversion
moved no data, proven by resolving both catalogues with the controller's rule and comparing
moved no data, proven by resolving both catalogs with the controller's rule and comparing
([issue 119](../../04-ISSUES/119-a-module-definition-decides-where-its-files-live/00-report.md)).
What the mesh writes *for* a module was still placed by the definition
([issue 174](../../04-ISSUES/174-the-meshs-own-files-for-a-module-are-placed-by-the-definition/00-report.md)),
the gap this design answered on 2026-09-26; built later the same day: a directory saying
`place: "mesh"` is `<root>/mesh/<module>`, a directory beneath a placed one states its path as
`${dir:<id>}/<rest>` and moves with it, and the same proof — both catalogues resolved and compared —
`${dir:<id>}/<rest>` and moves with it, and the same proof — both catalogs resolved and compared —
shows forty-eight definitions naming the paths they named before.
*A preference has a default; the operator's own value has none (2026-10-08,
@@ -323,7 +323,7 @@ value in a container's environment is refused when the definition is parsed, wit
containers, login, broker account and settings are keyed by it, as today, and a login still fits the
backend that keeps it (ADR 0049):
the bound is the one the offer of each provision it requires states, a keyless provision states none,
and an overflow is refused by the catalogue check before merge and left out of the provider's grants,
and an overflow is refused by the catalog check before merge and left out of the provider's grants,
reported, at composition — never a refusal of the provider's machine
(ADR 0225).
@@ -371,7 +371,7 @@ not rotated by the vault, which cannot make its replacement: an operator deliver
**Each requirement says how its recipient takes a new value.** It either *applies* it, through a
provisioner (a provider setting a login's password, the broker's provisioner updating an account, a
store's provisioner changing its own superuser), or *reads it at start*. Every module in the catalogue
store's provisioner changing its own superuser), or *reads it at start*. Every module in the catalog
reads its secrets at start, and none watches them. The node-engine already recreates a container when a file
it read at creation changes, its env-files and files mounted into it directly
([issue 103](../../04-ISSUES/103-a-container-is-not-recreated-when-a-file-it-reads-changes/00-report.md)).
@@ -433,7 +433,7 @@ as waiting, and nothing is delivered until the answer arrives.
| paths in resources, mounts, bindings, secrets and received files | host directory requirements, placed by the assignment |
| literals carried in a definition | operator requirements with defaults |
Each is retired only once nothing uses it. Until then both are accepted, and a catalogue test lists
Each is retired only once nothing uses it. Until then both are accepted, and a catalog test lists
the definitions still using the old form. That list shrinks to empty, and then the old form is
removed from the parser.
@@ -453,7 +453,7 @@ Each phase ends at a check that holds, so none of them leaves a mechanism half-r
is fixed in the node-engine already. *Ends when* nothing outside the vault generates a shared secret after
genesis, a lab consumer of analytics receives its site id, and a database credential rotates over
its two credentials, the consumer recreated by derivation, never without a working login, and its data intact.
3. **Definitions move, and seats move to assignments.** Every catalogue definition is rewritten, adopted
3. **Definitions move, and seats move to assignments.** Every catalog definition is rewritten, adopted
and running assignments placed where their data already is, and each claim becomes a seat the
module can hold, held by the assignment that holds it today. *Ends when* the list of definitions
using an old form is empty, the old forms are removed, and the store module runs on two lab
@@ -464,7 +464,7 @@ Each phase ends at a check that holds, so none of them leaves a mechanism half-r
| Rule | Checked by |
|---|---|
| Every requirement has one of the four provider kinds | The parser refuses any other. |
| A definition names no host path, node or mesh | The catalogue tests of ADR 0112. |
| A definition names no host path, node or mesh | The catalog tests of ADR 0112. |
| A module provider is chosen by named seat, pin, co-location, only one, a person's choice | Resolution tests for each step: a requirement naming a seat served by its holder even with another provider on the consumer's node, and refused when the seat is unheld; several candidates and none local, where assignment lists them with the seat's holder first and records the choice as a pin, and refuses without one. |
| A provider answers within its contract | A controller test: an answer carrying a field its contract does not name, or missing one it does, is refused and not delivered. |
| A module narrows a contract and never widens it | The parser refuses a module specification that loosens a contract's field. |
@@ -484,9 +484,9 @@ Each phase ends at a check that holds, so none of them leaves a mechanism half-r
| The controller and a node's host take the same path | 0113's tests: the controller's definition declares requirements and no own secret; a node's bus account is made by the vault and delivered sealed to that node. |
| Moving the vault or the broker is break-glass | A resolution test: an ordinary assignment moving `mesh-vault` or `mesh-broker` is refused, naming the procedure. |
| A secret that cannot be rotated says so | A vault test: rotating a secret marked not rotatable by the mesh is refused, naming why. |
| Only the controller reads the seat placeholder | A catalogue test, from phase 3: no definition uses the seat placeholder. |
| Only the controller reads the seat placeholder | A catalog test, from phase 3: no definition uses the seat placeholder. |
| Refusal names everything at once | A resolution test with three unresolved requirements of different kinds: one refusal naming all three. |
| The old forms retire | The catalogue test listing definitions still using one. It must be empty before a form is removed. |
| The old forms retire | The catalog test listing definitions still using one. It must be empty before a form is removed. |
## Not settled here
+14 -14
View File
@@ -169,11 +169,11 @@ paper is wrong until there is a second mesh to find out.
The derivation refuses two things where they can still be named: two users with one name — the
server reads the file as one of them and which one depends on the order — and a module
assigned but absent from the catalogue, which would compose a user with no authority and fail
assigned but absent from the catalog, which would compose a user with no authority and fail
on its first publish with an authorisation error that says nothing about a missing manifest.
A user the mesh has minted no password for is *named* rather than dropped or written as a user
anybody is: an ordinary situation with an obvious remedy, and the caller decides whether a
partial file is worth writing. A seat's protocol is gathered across the whole catalogue, not
partial file is worth writing. A seat's protocol is gathered across the whole catalog, not
from one manifest, because a seat is declared by one module and held by another.
**Out, and what each needs.**
@@ -447,7 +447,7 @@ pays for itself furthest away.
derived to subjects, the three namespaces, permissions computed from a declaration, and a
manifest that contains no subject. Done in the controller's composer (permissions, streams,
consumers), in the runtime's client (subjects derived from the credential, never named by a
module), and as a catalogue test asserting all 72 manifests hold no subject — because the
module), and as a catalog test asserting all 72 manifests hold no subject — because the
rule held by construction, and a rule held by construction is one a later field breaks
quietly.
- [x] 3.9 **seats declared by modules** — the manifest now carries `seats` (name, scope,
@@ -470,7 +470,7 @@ pays for itself furthest away.
all: a holding is derived at resolution, never stored, so nothing recorded points at an old
name (recorded as a progressive insight on ADR 0126). A **kept** rename table tells a
manifest written against an old name what it became, because a module lives in its own
repository and may be registered long after the catalogue stopped using one.
repository and may be registered long after the catalog stopped using one.
**A seat and the interface it delivers are different names.** The `git` seat became
`mesh-git` while the `git` *provision* it delivers did not change, and the same for the
@@ -522,7 +522,7 @@ it, and the beds that need a mesh living on NATS can finally run.
(ADR 0129). Both sides
are behind a seam with an implementation per bus, and on the bus being built one publish does
what two did: the outcome is the role's own event, so the asker matches it by the id its
request carried, the controller records it and the catalogue places it in the graph. A builder needs a reply queue for nothing and a grant over nobody's inbox.
request carried, the controller records it and the catalog places it in the graph. A builder needs a reply queue for nothing and a grant over nobody's inbox.
Checked against a running server: the round trip; a third party on the role's event hearing
the same outcome the asker did, which is what the decision rests on; work leaving the queue
@@ -532,7 +532,7 @@ it, and the beds that need a mesh living on NATS can finally run.
The outcome carries the module name, because only the manifest says what was built and one
message now has three readers. A failed build names none: it produced no module version, and
the catalogue would otherwise place something that was never made.
the catalog would otherwise place something that was never made.
- [x] 4.3 an installation completes over the bus, with the same outcome as the path it replaces —
**the installer can raise it**: a foundation template that stands up the server, writes the
server's own settings and the mesh's first user list beside them, and starts a controller
@@ -573,7 +573,7 @@ it, and the beds that need a mesh living on NATS can finally run.
correct. It uses the client a module's runtime uses, so what a person may do is answered by the
same permission list that answers it for a module and an audit has nothing separate to read.
Three decisions in it worth keeping. It lists what the **catalogue** has rather than what this
Three decisions in it worth keeping. It lists what the **catalog** has rather than what this
credential may call: somebody seeing only their own tools cannot tell "not installed" from "not
yours", and those need different people to fix them. A failed call says which of three things
happened — nobody serves it, this credential may not, or the tool was slow — because the
@@ -597,10 +597,10 @@ it, and the beds that need a mesh living on NATS can finally run.
**The catch-up half needed nothing built, and that was the answer.** It existed because a queue on
the bus the mesh runs on today receives only what is published after it is bound, so everything
built before the catalogue existed was announced to nobody — and on a fresh mesh that is always
the foundation, because those are the things the catalogue needed in order to exist
built before the catalog existed was announced to nobody — and on a fresh mesh that is always
the foundation, because those are the things the catalog needed in order to exist
([issue 050](../../04-ISSUES/050-the-catalogue-knows-nothing-built-before-it/00-report.md)). A
whole mechanism followed: the catalogue asks, the controller re-publishes.
whole mechanism followed: the catalog asks, the controller re-publishes.
A stream is a log and a consumer is a position in it. A consumer created later starts at the
beginning, so the builds are simply there — asked of a running server rather than assumed, since
@@ -636,8 +636,8 @@ left to be re-derived under time pressure:
| 1 | this one | prose; nothing deploys |
| 2 | the sdk | comments only, and no module rebuilds for it |
| 3 | the client library | it is what a module calls to emit, and it is where the subject is derived. Until it lands, a locally-named event is published under the local name itself |
| 4 | the catalogue | every manifest and every module's code, renamed together. Safe only once the runtime derives |
| 5 | the controller | **it refuses an old-style event name outright**, so landing it before the catalogue makes every unconverted module unregisterable |
| 4 | the catalog | every manifest and every module's code, renamed together. Safe only once the runtime derives |
| 5 | the controller | **it refuses an old-style event name outright**, so landing it before the catalog makes every unconverted module unregisterable |
| 6 | the node-engine | last, because nothing else waits on them |
Two properties make the sequence safe rather than merely ordered, and both are pinned by tests. A
@@ -682,11 +682,11 @@ healthy while reacting to nothing.
- [x] 5.4 **the old broker and everything that named AMQP leave the mesh** (ADR 0131,
superseding ADR 0127): the two modules that
required `amqp` are removed, the broker's module is unassigned and removed (**done 2026-09-28**; the predecessor's own tooling, which rode the same adopted broker, went dark with it, as ADR 0130 accepted), registration refuses
a manifest that provides or requires `amqp`, and a whole-catalogue check asserts none does. Not
a manifest that provides or requires `amqp`, and a whole-catalog check asserts none does. Not
a retirement condition — a decision, taken, with the operator's "I don't care if the predecessor
breaks" on record (ADR 0130).
Retiring with it: the build outcome's second announcement under the module's own name, which
existed only so a catalogue deployed before the rename and one after both heard it.
existed only so a catalog deployed before the rename and one after both heard it.
> **The remote tooling goes with it too.** The predecessor's own mesh talks over that broker, so
> shutting it down ends the path that reaches this installation's machines from a workstation.
@@ -5,7 +5,7 @@ code:
- mesh-controller internal/inventory
- mesh-controller internal/catalogue
- mesh-controller cmd/mesh-controller
updated: 2026-10-17
updated: 2026-11-06
decisions:
- "ADR 0181"
- "ADR 0182"
@@ -174,7 +174,7 @@ the client/identity side and the CA are the open pieces.
`ssh-client` template can emit a `Host` block per node with the right login name. Composed
end-to-end in the controller's tests.
**Written but not shipped:** the `ssh-client` catalogue module itself exists on a branch of the
**Written but not shipped:** the `ssh-client` catalog module itself exists on a branch of the
module repository; its pull request was closed with a hold until this design is deployed, and
nothing has deployed it since. The predecessor's generator still writes every workstation's ssh
client blocks today — which is where [issue 172](../../04-ISSUES/172-the-ssh-client-block-matches-one-spelling-of-a-machine/00-report.md)
@@ -209,7 +209,7 @@ alias and its trust, and a fresh machine has no operator dotfiles at all — the
service and leave the human unable to work on the box.
**Why not build it reflexively:** it is a real addition to the node model, the resource model, and
the seat set, and must be gotten right. The mechanism half is now settled — ADR 0120 is what lets
the seat list, and must be gotten right. The mechanism half is now settled — ADR 0120 is what lets
the ssh files be templates with no controller format — so what remains to decide here is the
model:
@@ -2,7 +2,7 @@
layer: to-be
status: in-progress
code: [mesh-controller]
updated: 2026-10-17
updated: 2026-11-06
decisions:
- "ADR 0238"
- "ADR 0221"
@@ -30,7 +30,7 @@ webhook".
seat or schema:
1. `module moved <module> <commit>` — tell the mesh its source advanced (the controller repo has no
trigger, so this is manual; the catalogue's webhook does it automatically — see below).
trigger, so this is manual; the catalog's webhook does it automatically — see below).
2. `build --behind` (or `build <repo> [--ref] [--path <subdir>]`) — the builder rebuilds and
records the new image.
3. The mesh **reconciles on its own**: the module's declaration now names the new image, the next
@@ -41,7 +41,7 @@ seat or schema:
**A breaking change** — a manifest schema the controller parses differently (a fact's shape, a
seat's name), where the new controller cannot read the manifests the old one stored:
4. Land the code (controller + catalogue together — they are one change).
4. Land the code (controller + catalog together — they are one change).
5. Rebuild + deploy the new controller (steps 1–3). **The moment it is live it refuses the
still-old-shape stored manifests, and composition freezes for every node that runs an affected
module.** Running services are untouched; only new declarations stop.
@@ -63,7 +63,7 @@ automating this must solve.
### 1. The trigger today is HAL's, not the mesh's
Build-on-push works for the catalogue because its repository has a Gitea webhook pointing at
Build-on-push works for the catalog because its repository has a Gitea webhook pointing at
`http://host.docker.internal:9877/webhook/gitea` — and **that receiver is `hal-gitea-tools.service`**
(`~/.hal/modules/hal/gitea/tools/server.js`), a *predecessor* component. The nox builder consumes
build work; it does not receive Git events. So the mesh's own build pipeline currently rides on a
@@ -78,12 +78,12 @@ HAL service, and:
seat — `mesh-forge-trigger` or folded into the git seat's holder) that receives Git events and turns
them into build work over the broker, for **every** repository including `mesh-controller`. Replacing
`hal-gitea-tools` is the concrete first build. Its logic already exists to copy: match the pushed
repository (and changed paths, for a monorepo like the catalogue) against the build-context
repository (and changed paths, for a monorepo like the catalog) against the build-context
repository of every registered module, and rebuild the matches.
### 2. The builder validates too — and a breaking change deadlocks it
The builder embeds the same catalogue package the controller does, so **it validates a
The builder embeds the same catalog package the controller does, so **it validates a
manifest against its own compiled-in seat/schema set**. A breaking change therefore couples *four*
things, not two: the controller, the **builder**, every affected manifest, and every node's host.
This session's seat rename rebuilt the controller but not the builder, and the stale builder then
@@ -104,7 +104,7 @@ does not know. The old builder cannot build the new builder. Escapes:
Either way, self-update for breaking changes needs a **transition discipline** so a push does not
auto-freeze: the new controller (and builder) should accept the *old and new* shape together for
one release — deprecated aliases in the seat set, a schema that reads both — then a later release
one release — deprecated aliases in the seat list, a schema that reads both — then a later release
drops the old. With that, a breaking change rolls out on a push like any other: everything reads
both, the manifests migrate, the compatibility is removed. Without it, self-update would simply
automate the freeze.
@@ -126,7 +126,7 @@ automate the freeze.
Revision, ADR 0162. The
trigger exists: the forge announces a merge on the bus and the controller acts on it (ADR 0157 made
the build narrate; this makes the merge a plan). A module's dependencies are one relation in the
catalogue — `depends-on` edges of four kinds: stands-on, packages, built-by, declared. A merge takes
catalog — `depends-on` edges of four kinds: stands-on, packages, built-by, declared. A merge takes
what changed and everything reachable from it along those edges, sorts the set into tiers, writes the
plan to the store, asks the first tier and returns. Each outcome advances the plan; a tier whose
rolled-out modules a later tier is built by waits until the machines report them applied; a
+225 -12
View File
@@ -12,8 +12,16 @@ code:
- mesh-tools src/main.ts
- mesh-catalog modules/mesh-catalog
- mesh-tools node-tools/internal/runtime (a module's state, ADR 0201)
updated: 2026-10-12
- mesh-sdk (the typed bus-state entry in `requires` and its binding, ADR 0595)
updated: 2026-11-04
decisions:
- "ADR 0609"
- "ADR 0612"
- "ADR 0613"
- "ADR 0618"
- "ADR 0606"
- "ADR 0595"
- "ADR 0596"
- "ADR 0307"
- "ADR 0240"
- "ADR 0233"
@@ -62,7 +70,7 @@ onto this in step 3 of ADR 0116.
This is the load-bearing rule.
ADR 0112 says a manifest names no node, mesh or path. A transport address is the same class of thing: if
manifests held literal subjects, reorganising the subject space would mean editing every module in
the catalogue, and the mesh would have hundreds of copies of a decision it made once.
the catalog, and the mesh would have hundreds of copies of a decision it made once.
| declared | derived |
|---|---|
@@ -94,7 +102,7 @@ lives under the emitting module's own name and the consumer carries that couplin
**How the rule is checked, because it was not.** *Added 2026-09-27, same source.* Two checks, because
the mistake happens at two scales. Per manifest, at registration: an event is a local name, and the
old bus's form is refused with the name to write instead. Across the whole catalogue, as a test:
old bus's form is refused with the name to write instead. Across the whole catalog, as a test:
where a consumed event's emitter is present, it must emit that event. The second cannot demand a live
emitter for everything — a module lives in its own repository and may be installed long before the
one whose events it wants — so it says nothing about an absent emitter and everything about a present
@@ -117,7 +125,7 @@ caller already handles). The kind token is what makes `mesh.mod.*.event.>` a saf
first draft of this table had no token, which reads better and cannot be implemented.
**The test this must pass: the manifest survives the wire changing.** Reorganise the subject space
and every manifest in the catalogue is still correct. That is the property
and every manifest in the catalog is still correct. That is the property
ADR 0039 gave the sdk, applied to
declarations.
@@ -172,7 +180,7 @@ can be wrong.
**And one publish reaches three audiences without anybody's inbox being opened.** A build's outcome is
the seat's own event: whoever asked matches it by the id their request carried, the controller records
it, the catalogue places it in the graph. That is the fan-out a shared exchange gave for free, written
it, the catalog places it in the graph. That is the fan-out a shared exchange gave for free, written
as a subject the mesh derived instead of a topology somebody configured — and it is why a holder needs
no permission to publish into an asker's inbox, which is the one grant design 25 §4 refuses by name.
@@ -227,7 +235,7 @@ service" versus "one worker per machine".
| credential | sealed, per consumer | none | none | none | none |
| reply | — | none | none, or an event later | a report | awaited |
| retention | — | age and size | work queue, explicit ack | **last per subject** | none |
| declared | `provides`/`requires` | `emits`/`consumes` | seat `accepts` / `uses` | the mesh's own; a module's `state` / `reads` | `serves` |
| declared | `provides`/`requires` | `emits`/`consumes` | seat `accepts` / `uses` | the mesh's own; a module's bus state in `requires` (ADR 0595), the old `state` / `reads` until it moves | `serves` |
**Job** is the one ADR 0041 had no room
for. Its table has events at 1:many and provisions at 1:1; a module submitting work to a service
@@ -249,7 +257,7 @@ registered for every machine, sent as an event, never reached a machine assigned
consumer did not exist yet when the event passed — and a licence binding sent as events replays a
week of rotations where only the latest matters. So a module names the state it **owns** with
`state`, and another module's it **reads** with `reads: <module>.<name>`. Each is a key-value bucket
the controller creates from the catalogue, mesh-wide, existing from registration so a reader can
the controller creates from the catalog, mesh-wide, existing from registration so a reader can
watch before the owner runs anywhere ([design 25](25-the-bus-on-nats.md) §3). Every instance of the
owner writes; a reader reads and watches. A key may name a machine by the module's own convention;
the mesh keeps one bucket per name, not one per machine, because "every server, for every machine"
@@ -278,6 +286,42 @@ module's assignment** — what a module stored is data
(ADR 0030) — and one whose
declaration is gone is reported, never removed by the mesh.
**A module asks for its bus state in `requires`, and reads no other module's.** *Amended 2026-11-03, ADR 0595
and ADR 0596, from research 082.* The `state` and `reads` of the two paragraphs above, and the sections `logs`,
`streams` and `objects` beside them, are four vocabularies for one need: what a module keeps on the bus. They are
replaced by one form, a **provision** of the bus module, as a database is postgres's:
- **An entry of `requires`, in its typed long form** (ADR 0595 §1): the local name, the storage type, the template
(state, events, work queue, log, objects, ledger) and the template's options, within their bounds; a ledger also
names its type (its schema, its operations each with its ledger effect, its indexes). The templates, their fixed
settings and their options are [design 25](25-the-bus-on-nats.md) § 12.1. mesh-sdk's catalog package carries the
entry's type and its strict decoding; every rule that judges it lives in the manifest validator (ADR 0595 §8).
- **The binding is what the module receives**: the names on the bus for each local name, written into its
membership by the grants part once the bus module says `created` (design 25 § 12.2). The module still names only
locally (§ 1). A module whose binding is missing at start fails loudly, naming the entry.
- **One name, one form.** A module asks for each entry once: an old section and the new form are never both used for
one local name, and one name serves one storage type only.
- **No readers.** The new form has no `reads`, and the manifest validator refuses one (ADR 0596 §2). Only the owner's account
reaches its bus state. **A module's events are subscribed to; its data is asked for**: what another module needs
of a module's kept data it asks through that module's tools or seat verbs (§ 4's tool relationship, `serves`),
and what a module lets others hear is its declared events, heard through `consumes` (ADR 0363, unchanged; ADR 0596
§1). A bucket's layout is never a contract another module depends on; a tool or a declared event is.
- **A state may be read-only to the module's tools.** A state's declaration may carry `read-only: true`: only the
processes of the module whose `bus.state` names that state write it, and the module's tools read it, holding no
publish on its subjects. The manifest validator refuses a read-only state that no process of the module names. How it is checked:
the manifest validator's unit tests for the refusal, and the composition test that a tools bundle's account holds a read on the
state and no write. The bus module's state `spent` (design 25 § 12.3) is the first user. (A design limit of the
milestone's review; no record decides it yet.)
- **The move is a module at a time** (ADR 0595 §11, ADR 0596 §3), each when it is next touched, keeping its local
names and its old settings as options so its data stays. A reader moves after its owner: the owner declares the
event or gains the tool its readers need first, and the manifest validator refuses a moved module's subscription to an event
its owner does not declare. An old section is refused once no module but the foundation's uses it.
What follows for the paragraphs above: for a module that has moved, ADR 0201 §2 (another module's state read by
naming it in `reads`) no longer holds, and the bucket "every instance of the owner writes; a reader reads and
watches" becomes "every instance of the owner writes and reads". The runtime's `get`, `put`, `delete`, `keys`,
`watch` and `history` stay the calls of the template state.
**A module declares the data it holds.** *Added 2026-10-06,
ADR 0233.*
State on the bus is one kind of data; the rest lives on a machine's disks or with a provider, and the
@@ -326,7 +370,7 @@ Every shape above appears once, in order, and no step knows where the next one r
**A change lands.** The module holding `mesh-git` emits `pushed` — repository, ref, commit. An
event, because it is a fact about git and git's identity is the meaning.
**The change becomes work.** The controller consumes `pushed`, asks the catalogue which modules
**The change becomes work.** The controller consumes `pushed`, asks the catalog which modules
are built from that repository and path
(ADR 0069), and submits one
**job** per affected module to the `mesh-build-machine` seat. The builder stays simple: it builds
@@ -366,7 +410,7 @@ not to an address it was given at genesis. Held and retried while the store rest
chain above went dark at the moment it touched a machine: nothing said which version a machine now runs,
or that it refused to. The controller states those as facts under its own seat's namespace, when what
a machine runs changes rather than on every convergence pass, and anything that cares subscribes the way
the catalogue subscribes to `built` (ADR 0134).
the catalog subscribes to `built` (ADR 0134).
The facts are second-hand by design — one emitter, one ordering — and a machine that cannot reach the bus
produces none, so absence is not health.
@@ -437,6 +481,136 @@ meaning into shape wherever it can go — a required `channel` field is caught,
interpretation of an existing one is not. Saying so is better than implying the fingerprint is
complete, because a team that believes it is complete stops reviewing for the case it misses.
### A package, its series, and the series its users accept (from 2026-11-03)
(ADR 0606 §4, ADR 0609, from research 081.) This is the manifest's half of design 51's versions.
- **A package is declared as an artifact**: its name, the kind `package`, its language (`go` or `typescript`), its
paths and its **package series** (`0.1`). An image, a bundle or an archive may declare a package series the same
way; one that declares none is numbered in `0.1`. Nobody types a version: the builder counts it (design 51).
- **A package is named by its name in its own language** (a design limit of the registry milestone, 2026-11-04): a
Go package by the module path of its `go.mod`, a TypeScript package by the name in its `package.json`. The
indexer reads that name at each merge, the builder numbers the package under it, the package's registry seat
publishes it under it, and a user's `packages` names it so. One name per package across the mesh, because the
language's own tools fetch by that name and no other. How it is checked: the manifest validator refuses a name in `packages`
that no package of the shelf is named, or that a member of the change's delivery group does not name at its head.
- **Raising a package series** is a reviewed change of the package's manifest, for a change that breaks its users.
The checker's verdict names every change of a package series it sees, so the review of the change sees it.
- **A user names the mesh packages it takes in a section of its own, `packages`**, each with the package series it
accepts. It is not `uses`, which grants publishing on a seat's `accepts` subjects (§ 3); a package is not a seat. A
user builds, and is checked, against the newest version of that series; a publish in another series does not move
it, and moving is a reviewed change of the user's manifest. A user that names none accepts the series of the
package's first numbered version, so nothing is edited in today's users. The indexer's tool `indexer_package_users`
lists, per package, its users and the series each accepts, so a user left on an older series is seen.
- **Inside one repository** a module uses its sibling package by path, from the same commit, and waits for no publish.
- **A user outside the package's delivery group is not built before the merge**: it is built after it, when the new
version is in its series. A user that breaks fails its own build, is not wanted, keeps its previous build, and a
condition tells the operator. A group's members are built in the group's check, against the group's tagged version.
- **A contracts module's package** names the directory of the seat definitions it is generated from in the field
`generated-from`, the contracts marker (design 26).
- **The manifest validator reads the new words** (ADR 0578 §1): each package series well formed and only on the four kinds that may
carry it, a package naming `go` or `typescript`, and each name in `packages` a package some manifest declares. A
running manifest validator that does not know a word sets the manifest aside to wait, never refuses it, while a newer indexer
build is merged and not yet delivered; and a node-engine is handed a manifest using these words only once it
states the capability to read them (ADR 0614 §4).
- **Cost**: the new manifest fields are read through mesh-sdk's manifest types, so their change rebuilds every module
once; it is the one rebuild the milestone of ADR 0612 already takes for the contracts move (ADR 0612 §1, ADR 0613 §1).
### A config value renamed (from 2026-11-03)
(ADR 0609 §4.) A config value's declaration may name its old name, `renamed-from`. On the merge, mesh-config moves the
value it holds under the old name to the new name in its own state, without the operator giving it again, emits
`renamed` (module, old name, new name, when; its family `config.events`, kept seven days) and records it. This design decides what ADR 0609 leaves open:
- **Which values**: a module's own config values only, never a secret, never another module's value. A rename keeps
the value's trust: a value set without the operator's Approve stays untrusted under its new name (ADR 0348 §8), and
the checker refuses a rename that would change a value's trust.
- **How long the old name is read** (the **rename window**): until every node-engine whose node has a want of the
module reports applied a build of it that reads the new name. mesh-config hears the status view's `delivered`
events and, at its start and on each, asks its `node_haves` for every node, away ones included, since `delivered`
counts only the nodes present (design 47); until then mesh-config answers both names. A node away when the last
`delivered` was said should close its window when it returns, with no other delivery: mesh-config also wakes on
the node-engine seat's event `mesh.seat.node-engine.event.manifest-reads-changed`, said when a node's stated
capabilities change and when it returns after being away (ADR 0618 §4), as for the old seat name (design 51), and
on it reads that node's stated capabilities through the seat's verb `manifest-reads` (ADR 0618 §3) and its applied
builds through `node_haves`, never a watch of the node-engine's have state (ADR 0596). mesh-config declares
`seat:node-engine.manifest-reads` in its `invokes`: that is the grant the grants part composes, and with it the
grants part grants mesh-config the subscription to the event's subject (its unit row is in design 51). A
node-engine that does not yet serve `manifest-reads` counts as stating nothing: the window stays open and
the seat's verb `renames` names the node. ADR 0618 does not cover a
returned node that applies the module's new build only after its return event, since that build changes what the
module reads, not what the node-engine states: such a node closes the window on the next `delivered`, whichever
delivery says it. A node holding a window open
for seven days is mesh-config's finding naming the node, cleared when the window closes; `config_rename_close`
drops a node from a window by hand, recorded as a hand act.
- **The checker asks the seat, never the module.** The seat `mesh-config` gains the optional verb `renames` (the
open renames, and the nodes holding each window open), in its seat definition (design 26). The checker asks it for
every change carrying `renamed-from` or dropping one: a holder that does not serve it is refused by the tool runner
naming the verb, and the checker then refuses `renamed-from` naming that; while a window is open, the same answer
refuses dropping `renamed-from`, naming the nodes. A check that cannot ask fails, and says so. So no manifest uses
`renamed-from` in the milestone that brings it, whose running mesh-config serves no `renames`; the first that does
is its live case. The checker declares `seat:mesh-config.renames` in its `invokes`, so by the served-verb edge
(ADR 0614 §2) its new build waits until a build of mesh-config that serves `renames` runs healthy; no cycle closes,
since mesh-config waits only on the indexer's `indexer_config_readers`. The "not served" answer is then met only by
the running checker in the milestone's own check, and after a revert. `config_renames` names, per rename, the nodes
still holding the old name open.
- **A refused move** (the old name holds nothing, or a secret) is mesh-config's finding, from which the condition keeper
raises the condition, cleared once the value moved or `renamed-from` left the trunk's manifest. **Tools of
mesh-config**: `config_renames` (what moved, from which name, when), `config_rename_again` (move one value by hand
when a move was refused) and `config_rename_close` (above).
### A value no longer read (from 2026-11-03)
A config value or secret no manifest on any trunk reads any more is a **retiring value**. mesh-config learns it from
the indexer's tool `indexer_config_readers`, which it asks on each of the indexer's `manifest-accepted` events; the
indexer says `manifest-accepted` for every newly accepted manifest, its bus-state entries empty when it asks none (the
bus module reads an empty one as "this module asks nothing now", design 25 § 12.2). A tool the indexer does not serve
yet answers "not known", and nothing retires on it. It is marked retiring only once no node-engine reports applied a
build that reads it, as the rename window is (§ above). mesh-config then emits `retiring` (family `config.events`,
kept seven days) and asks the operator once, through the operator channel, whether to remove it, naming any node that
still read it until lately; it is removed only on the operator's Approve. **mesh-config holds no secret**, so the
retiring flow and its one ask stay mesh-config's, and on the Approve it removes a value itself and retires a secret
through the seat `mesh-vault`'s new optional verb `retire` (one module's own secret, by node, module and name), carrying
the operator's warrant, which the vault checks (ADR 0259 §6) before it removes anything. The vault's caller list for
`retire`, a trusted config value in ADR 0363's form, names the holder of the seat `mesh-config` alone, checked against
the caller the tool runner proved; the warrant is bound to the node, module and name it was asked for, so it retires
nothing else. mesh-config then emits `retired` on `config.events` (module, name, node, the ask), and the vault emits
`own-retired` (node, module, name, the ask's id, the caller it proved) beside its `rotated` and `own-replaced`, on the
module events stream (ADR 0363) under the vault's own subjects, kept as that stream keeps every module's events. An ask unanswered for seven
days is asked once more, and then written as a finding, cleared by an answer, a cancel, or the value read again; a
sleeping node holding a retirement open for seven days is a finding naming it. `config_retiring` lists what is
retiring, since when, and its ask, and asks it again or cancels it.
**Where mesh-config keeps it.** Its new state (`renames`, `retiring`, `findings`) and its stream `config.events` are
declared in its old `state` and `streams` sections in this milestone, as the builder's and the checker's new state is
(design 51 *The move*), so that neither mesh-config nor the deciding parts that ask it wait on the bus module's
process, which is delivered in the same milestone. They move to bus state when each module next moves (ADR 0595 §11).
`config-changed` stays on the shared events stream, unchanged, so its consumers do not move.
**How the rename and the retiring are checked**, as cases of mesh-config's first whole-module integration test (C20,
C24 below), of the checker's and of the vault's existing whole-module tests: the checker's ask of `renames` meeting a
holder that does not serve it refuses `renamed-from` naming the verb, one meeting an open window refuses dropping
`renamed-from` naming the nodes, and a check that cannot ask fails saying so; `retire` with the warrant removes the
secret and emits `retired` and `own-retired`, without it, with a warrant for another name, or from a caller not on the list it is
refused; a waiter on the vault's `rotated` or `own-replaced` does not wake on `own-retired`; a node that was away,
returning with a build that reads the new name, closes the rename window on its `manifest-reads-changed` event when
it applied that build before the event (ADR 0618 §4), and on the next `delivered` when it applies it after; `config_rename_close` drops a node from a window and records the hand act; a window held seven days and a
retirement held seven days each write their finding naming the node, cleared when it closes.
### The mesh delivery cases this design carries
Research 081 listed the mesh delivery cases; these are the ones it handed to a design, each with its acceptance test,
each a case of its module's one whole-module integration test unless it says live.
| case | what holds | acceptance test |
|---|---|---|
| C6, a package series raised | users on `0.1` keep the newest `0.1`; a reviewed change moves a user | builder: a `0.2.0` publish moves no `0.1` user, its check takes the newest `0.1` too, a reviewed change naming `0.2` moves it, a user naming no series builds against the newest `0.1` |
| C14, a provision's form gains a field | the provider serves it in a new version; the consumer reads it once rebuilt; an older consumer ignores it | mesh-sdk: a consumer built against the older form reads a provision with the new field |
| C18, a new required config value with no default | the check names the nodes that lack it; the want waits; the operator is asked once | live: a module gaining such a value waits on each node lacking it, the operator is asked once naming the nodes, and once given the module is applied |
| C20, a config value renamed | the value moves, keeps its trust, both names read until every node runs the new build | mesh-config: a renamed value is present under the new name with no operator input and its trust; the old name answers until the node-engines report the new build; dropping `renamed-from` early, or changing trust, is refused; a refused move writes its finding |
| C22, a secret only a person can give | the want waits; the operator is asked once what to give and where | live: a module requiring such a secret waits, one ask names it and where, and once given the module starts |
| C24, a config value or secret no longer read | it is retiring, the operator is asked, removed only on the Approve | mesh-config: with one node-engine still reporting a build that reads the value it is not marked retiring and no ask is sent; once that node reports the new build it is marked retiring, `retiring` is emitted and one ask reaches the operator; an ask unanswered seven days is asked once more, then written as a finding; the value stays until an Approve removes it |
## 9. Provisioning over the bus
Provisioning rides the bus, and the provider stops having an address.
@@ -482,7 +656,7 @@ addresses will believe a class of bug is fixed when it is untouched.
controller's address — recorded somewhere, at some moment, and wrong as soon as anything moved.
Now it publishes to `mesh.seat.mesh-controller.report` and the bus routes it to whoever holds the
seat. Nothing anywhere records where the controller is, so nothing can record it *wrongly*. The
same is true of the builder, the catalogue, the telegram sender. This class is not mitigated; it
same is true of the builder, the catalog, the telegram sender. This class is not mitigated; it
is gone, because the information is no longer stored.
**Something that is not on the bus: the address stays, exactly as before.** A module that requires
@@ -580,11 +754,11 @@ billing existing under that name.
## 12. How it is checked
- **A manifest holds no subject.** A catalogue test: no manifest contains a string matching the
- **A manifest holds no subject.** A catalog test: no manifest contains a string matching the
subject grammar. The rule is worthless if it is followed by convention.
- **A preparation is given what the module is given.** A composition test: what the preparation
entrypoint receives equals what the module's own code receives, asserted rather than written twice —
which is the drift a hand-written step invites, three times over in the catalogue today.
which is the drift a hand-written step invites, three times over in the catalog today.
- **A convergence that changed nothing says nothing.** Two identical reports, one emitted fact: what is
guarded against is a fact per minute per machine, which is a stream nobody reads.
- **Permissions are exactly the three namespaces.** A composition test per module: the derived
@@ -602,6 +776,45 @@ billing existing under that name.
- **A module reaches only the state it declared.** The composer's test: an owner's runtime may write
its buckets, a reader's may only read, and nothing else is granted; the runtime's test over a real
bus: a name not issued and a reader's write are refused with the reason.
- **Bus state is asked for once, in one form, and read by its owner alone** (ADR 0595 §8, ADR 0596). The manifest validator's
unit tests: a `reads` in the new form, a local name used twice across storage types or in an old section and the
new form, an unknown template and an option outside its bound are each refused, naming the field. Live: a moved
module receives its binding after `created`; another module's account reading its entries is refused; a moved
reader hears its owner's declared event and asks its owner's tool. The rest is [design 25](25-the-bus-on-nats.md)
§ 12.7.
- **State is current at once.** The runtime's test over a real bus: a watch hands the current values
without deletions, then an end-of-current marker, then changes. Live: a machine assigned after a put
reads it at start.
## Reviewed by architectural domain
The amendment of 2026-11-03 to ADR 0595, ADR 0596 and ADR 0597 (designs 25 § 12, 32 § 4 and 55 together) was
reviewed by the four reviewers by architectural domain side by side (playbook 01), over three rounds, and the lead
ruled on every finding. What was found, and what answers it:
| Domain | Found | Answered by |
|---|---|---|
| security | the author could be words the module chose; a person's dangerous tools had no role, mark or path to the process; the caller travelled as a plain field | design 25 § 12.3 (marks, the process's own tool subject, the identity seat's signed token), § 12.4 (the tool runner stamps the caller it proved; the move's authors marked imported) |
| seams | the bus module asked for its own events in the new form, which it would have to create itself (ADR 0595 §10); a person's tool had no join to the process; a verdict was written twice with no order | design 25 § 12.3 (its events on its old `streams` section; the process's own tool subject); design 55 § 2.1 (the `review` operation first, `reviews` caught up from it) |
| running qualities | overdue creation was undefined and raised by nobody; the database's rollback write lived in memory; a forward delivery after a rollback could miss acceptances and verdicts; no size estimate of the heads | design 25 § 12.2 (five minutes, the watchman, durable consumers, `check` at start); design 55 § 8.1 step 6 (`database.sequence`, the check at every start before the drop), § 2.1 (the heads' estimate) |
| health | the bus module's health would have fired on a quiet mesh; conditions had no clearing; `database-behind` had no clearing | design 25 § 12.2 and § 12.3 (each condition with what clears it); design 55 § 8.1 step 6 |
| events and logs | an event lost when the module stopped after `apply`; the bus module's events had no reader | design 55 § 1 (each event sent with its operation's sequence as id, the state `sent`); design 25 § 12.3 (`history` of one entry) |
| testing | the bus module had no test that starts it whole; live tests would have filled the live bus; the budget was not counted | design 25 § 12.7 (the nats module's integration test, live drift only by a manifest change, the budget paragraph); design 55 § 10 |
| 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 |
**Left to the operator**, because each changes an accepted record: a margin between raising and clearing the
condition `full` (ADR 0595 §6 raises and clears it at 75 percent, so an entry sitting there flaps), and an event of
its own for `drop` and `recreate`. **A correction of fact** for ADR 0595 §4: the bus module deletes through `recreate`
as well as `drop`. Each is noted on issue 1966.
The amendment of 2026-11-03 for research 081 (ADR 0606, ADR 0609; the package, rename, retiring and delivery-case
sections of § 8) was reviewed with designs 51 and 26 by the four reviewers by architectural domain; the findings and
what answers them are listed in design 51's *Reviewed by architectural domain*. For this design: a rename keeps a
value's trust (security), `packages` is a section of its own, not `uses`, and mesh-config hears the status view's
`delivered` events (seams), a value retires only once no node-engine runs a build reading it (security), and `renamed`
and `retiring` have a family and an ask that is asked again (events).
The milestone's amendment (ADR 0612, ADR 0613: the seat verb `renames` the checker asks, the vault's `retire`,
`manifest-accepted` for every manifest, mesh-config's new state in its old sections) awaits its own review by
architectural domain, which rewrites this section.
@@ -135,7 +135,7 @@ by side until nothing is bound to the old one.
*Amended 2026-10-07 (ADR 0246,
[issue 298](../../04-ISSUES/298-a-new-seat-verb-deadlocks-across-two-repositories/00-report.md)):*
**additive takes two steps when the seat and its holder are in different repositories.** That is the
case for every mesh seat whose holder is a catalogue module. §3 makes every promised verb a condition of
case for every mesh seat whose holder is a catalog module. §3 makes every promised verb a condition of
holding, and a claim may name no verb the seat does not promise. So a verb added to the seat in the
controller refuses today's holder, and a holder that serves it is refused by today's controller. Neither
change can land first. An added verb therefore lands in three steps, each its own pull request:
@@ -163,7 +163,7 @@ still a new version.
of the subject table.
- **An added verb lands in steps, and each step is checked (§7).** The controller's claim check refuses
a claim that serves a verb the seat does not promise, and a holder that misses a required verb. It runs
at registration, at handover, and in `module check`, which the catalogue's merge check runs over every
at registration, at handover, and in `module check`, which the catalog's merge check runs over every
manifest with the controller the mesh runs. So a step out of order fails the pull request that took
it. That an optional verb stays optional when read back from the store is held by mesh-controller's
`TestAnOptionalVerbStaysOptionalInASetReadFromTheStore` (#114), and that a seat's row gains a verb's
+5 -5
View File
@@ -28,7 +28,7 @@ it put it there (ADR 0152).
## 1. What it is
A module, `mesh-console`, in the catalogue. Its image is the tool runner's own — the client that
A module, `mesh-console`, in the catalog. Its image is the tool runner's own — the client that
already speaks the bus as a command line and as an MCP server — started in a mode that reads the
module's credential and listens on loopback. It has no state, no provision, no seat. What it needs is
the bus, which it gets the way every module does: a credential the mesh minted for `<node>.mesh-console`,
@@ -42,7 +42,7 @@ consumer is the operator's agent, [36 — The operator's agent on a machine](36-
a machine without the mesh MCP server refuses such a module by name. Nothing else above changes: no seat, no
state, no tools of its own.
Its manifest says three things nothing else in the catalogue says together:
Its manifest says three things nothing else in the catalog says together:
- `invokes: ["*"]` — it calls every tool on the mesh, and the bus grants exactly that publish side;
- `listens` on a port `from: machine` — the filter opens nothing for it, because loopback is not outside;
@@ -74,7 +74,7 @@ its own under that module's name, `mesh.mod.<module>.tool.tools`, answering the
descriptions and argument schemas — the definitions from the code that answers them, and from nowhere
else. A module may not name a tool of its own `tools`; the runtime refuses the collision at load.
**The mesh MCP server asks the catalogue which modules the mesh holds, then asks each.** `catalog_modules`
**The mesh MCP server asks the catalog which modules the mesh holds, then asks each.** `catalog_modules`
answers the roster; one `tools` request per module, in parallel, answers the list. The bus refuses at
once a request nothing serves, so a module that is not running costs nothing and is named in the answer
as not answering, rather than silently absent — *silence and success must never look alike*. The list is
@@ -106,7 +106,7 @@ answers is reached through them by its address: `<seat>.<verb>` for a seat held
`<node>/<seat>.<verb>` for one held per machine, `<node>/<module>.<tool>` for an assignment, and
`<module>.<tool>` as well for a module whose instances are interchangeable. A module that is not
interchangeable is called with its machine or refused with the machines it runs on. Each discovery
verb asks the mesh when it is called, so nothing is kept for a session's length; the flat catalogue
verb asks the mesh when it is called, so nothing is kept for a session's length; the flat catalog
stays reachable through the `mesh` client and a setting, unannounced.
**What exists is what announced itself** (ADR 0197):
@@ -159,7 +159,7 @@ machine with nothing else on it does; the mesh MCP server binds whatever it is g
Two things shipped bent, both stated in [`00-as-is/13-the-console.md`](../00-as-is/13-the-console.md):
the person's client through the mesh MCP server (`--console`) exists and was exercised in the test suite, not
on the live mesh; and a module registered from the catalogue by hand recorded its source as a URL rather
on the live mesh; and a module registered from the catalog by hand recorded its source as a URL rather
than as a path on the git seat, because `--self` takes the forge path form — the rebuild-on-merge still
matched it by URL.
@@ -132,7 +132,7 @@ a hypothesis (ADR 0153);
the mesh is asked and changed through the controller seat's verbs; the forge through the forge module's
tools; a licence through the `anthropic-licence-manager` seat's verbs, never by editing a file. The hard
rules in new words: a file the mesh manages is changed through the verb that owns it or through the
catalogue, never on disk; a store's database is never written by hand; main is never pushed; the mesh
catalog, never on disk; a store's database is never written by hand; main is never pushed; the mesh
creates no symlinks and nobody else does; a package is declared, not installed by hand. The glossary's
words, none of the predecessor's.
@@ -231,7 +231,7 @@ All four nodes carry one since 2026-10-03. **Per node:** the role. **Per mesh or
extra tool servers, and the operator's managed-settings keys (§2). The controller's verb replaces a
setting layer whole, so a layer set for one of these keeps the others it already held. **Prerequisite:** the manager holds its seat and has adopted the licences.
**Order:** the manager assigned and a refresh observed; the mesh MCP server's provision in the catalogue; this
**Order:** the manager assigned and a refresh observed; the mesh MCP server's provision in the catalog; this
module on one workstation; the six predecessor files and the hand-made mesh MCP server entry removed there; a
new session read to confirm it sees the mesh's instruction file, the mesh MCP server's five tools under `mesh`, and
its licence; then the rest.
@@ -19,7 +19,7 @@ decisions:
# 37 — The operator's machine
**Every configurable thing on a node is a module, the home included, and the same catalogue serves
**Every configurable thing on a node is a module, the home included, and the same catalog serves
a server and a laptop.** One default configuration per module, varied per node by a setting or a
kept region; roles a machine has once as node-scoped seats with tool contracts; one tool runner
per node serving every module's tools outside any container
@@ -117,7 +117,7 @@ resolver is asked by the second graphical module; the display server itself is g
all four today. Nothing home-scoped composes before it.
2. **The tool runner** — `mesh-host` supervises it; mesh-tools serves bundles from memberships
and reloads; mesh-controller composes the bundle into the declaration and the memberships to one
runtime per node; the catalogue renames the mesh MCP server. Proven when the packet-filter verbs answer
runtime per node; the catalog renames the mesh MCP server. Proven when the packet-filter verbs answer
from it and its container is gone.
3. **`zsh`**, the first environment module: seat, `user` shape, home files, `execute`. Proven on a
server first, then every node.
@@ -52,7 +52,7 @@ as design 28's: nothing here is new ground; every package reshapes something sta
| the controller's bus principals | Go: one principal per module per node, grants from what it declares | 132 lines | gains one principal per node for the runtime |
| the controller's memberships | Go: one per assignment, the subjects a runtime serves | 143 lines | **unchanged** in shape; the runtime reads several |
| the controller's declaration composer | Go, one file | 2 053 lines | gains the runtime's process, the bundles' archives, two env words |
| the catalogue | 35 manifests build a per-module tool container on the runtime's base image | — | none do; the runtime is a module of its own |
| the catalog | 35 manifests build a per-module tool container on the runtime's base image | — | none do; the runtime is a module of its own |
**Two measurements decide the shape.** The node-engine needs no change: a `process` and an `archive` are
what the runtime and a bundle are, and both are applied today. And the runtime already does
@@ -140,11 +140,11 @@ with the shortcut off answers the same.
a module whose own code is an image artifact is refused, whatever image it is built on.
*Amended 2026-10-02, at WP3.* The gate refuses the pattern **spreading**, not standing: a module
new to the catalogue in that shape, or one that had already moved to a bundle and returns to it,
is refused; a module the catalogue already holds in that shape — judged from the manifest it
new to the catalog in that shape, or one that had already moved to a bundle and returns to it,
is refused; a module the catalog already holds in that shape — judged from the manifest it
holds and what that module's newest build stood on — is rebuilt without complaint. The day the
runtime arrives some thirty such modules stand, each moves in its own change from WP4 on, and a
gate refusing every rebuild in the meantime would stop the catalogue's pipeline to make a point
gate refusing every rebuild in the meantime would stop the catalog's pipeline to make a point
this record already makes.
**Proof.** Composition tests: a node with three assigned modules, one holding a seat, yields one
@@ -159,7 +159,7 @@ the runtime is registered.
**What changes.** mesh-tools gains a `bundle` artifact of itself beside its images, and its manifest
becomes the `node-tools` module: a package for the interpreter, the loopback listener the mesh MCP server
declared, `invokes: *`, and nothing else — the process is the controller's to compose (WP2). In the
catalogue, `mesh-console` is retired as a module and `node-tools` assigned where it was. The
catalog, `mesh-console` is retired as a module and `node-tools` assigned where it was. The
runtime's `serve` keeps answering MCP on loopback; the person's end of it keeps the name "console"
([glossary](../../00-META/glossary.md)).
@@ -178,7 +178,7 @@ runtime accepts. *Built 2026-10-02* (mesh-tools `c46f950`, mesh-controller `ca7e
`729a5f9`). *Proven live 2026-10-02/03, on all four machines*: the mesh MCP server's container is gone,
`node-tools` runs as a unit the node-engine wrote, as the operator's account, `tools/list` on each loopback
answers with the same 219 tools as before, and the controller's verbs answer through it; `mesh-console`
retired from the catalogue. Three things the step found are issues
retired from the catalog. Three things the step found are issues
[203](../../04-ISSUES/203-a-fresh-assignment-is-pushed-before-its-credential-exists/00-report.md),
[204](../../04-ISSUES/204-a-controller-handover-re-sent-every-node-a-stale-declaration/00-report.md) and
[205](../../04-ISSUES/205-a-package-resource-fails-against-a-stale-package-database/00-report.md).
@@ -224,7 +224,7 @@ the node-engine re-creates the runtime's process on every reconcile (resolved th
credential and state directory gone, the client through `sudo` since the daemon's socket is root's;
proven on all four machines — `status`, `banned` and the module's own `fail2ban_settings` answer from
the runtime, no `mesh-fail2ban` container, the runtime serving both bundles. Two holders moved; of the
thirty-three tool containers the catalogue held, thirty-one remain, and all but these two carried their
thirty-three tool containers the catalog held, thirty-one remain, and all but these two carried their
module's configuration and secrets in the container's environment, which a bundle does not have — the
question research research 020 opened
and ADR 0192
@@ -235,7 +235,7 @@ container's, the runtime hands each bundle its own. That is WP4b below.
*mesh-controller, mesh-tools, mesh-catalog. One day. The rest of ADR 0175, under ADR 0192.*
**What changes**, in order: the manifest's tools artifact gains `env` and the catalogue check
**What changes**, in order: the manifest's tools artifact gains `env` and the catalog check
refuses a secret's content in it; the composer resolves a bundle's `env` per machine and carries it
beside the bundle's archive, `restart-on` included; the runtime hands each bundle its own
environment — the contributor's argument for an imported bundle, the child's environment for a
@@ -60,8 +60,8 @@ Measured 2026-10-03 on the four machines and in the repositories.
| a bundle's words | paths and constants written with `${dir:…}` and `${port:…}` only; a fact the mesh knows reaches a bundle as a file whose path is a word | the agent module's facts file and settings file |
| a bundle calling a tool | `mesh/ask` through the runtime that launched it (ADR 0198); no bundle holds a bus credential | how the manager visits every node |
| a module's own long-running code | a bundle the runtime launches and restarts (ADR 0198); the runtime's subscription and grants built, the modules moving in design 38 WP4c's waves | the manager's daemon (WP3, WP4) |
| the vendor's refresh, the sealed box, the grant file | `anthropic-manager` in the catalogue, built on the controller placement ADR 0183 moved away from; assigned to nothing | its client ported into the manager; the module retired (WP6) |
| the credentials write, the strip, the identity read | `anthropic-consumer` in the catalogue; tested; assigned to nothing | ported into the agent module with its tests; the module retired (WP6) |
| the vendor's refresh, the sealed box, the grant file | `anthropic-manager` in the catalog, built on the controller placement ADR 0183 moved away from; assigned to nothing | its client ported into the manager; the module retired (WP6) |
| the credentials write, the strip, the identity read | `anthropic-consumer` in the catalog; tested; assigned to nothing | ported into the agent module with its tests; the module retired (WP6) |
| the predecessor's manager and consumer | the lease per licence, the expiry floor, the lineage comparison, the identity guard, three touchpoints, cooldowns | ported as logic with its tests |
## The order the work allows
@@ -99,7 +99,7 @@ resolves it. The runtime's port stays what its code fixes; assigning it is
second question and not this package's.
**Proof.** The plan for a workstation carrying a consumer of `mcp-endpoint` shows it bound to the
runtime's port; the controller's tests and the catalogue's checks pass.
runtime's port; the controller's tests and the catalog's checks pass.
## WP2 — The agent module
@@ -130,7 +130,7 @@ runtime's port; the controller's tests and the catalogue's checks pass.
**Proof, before anything runs live.** Unit tests: the renderer writes the mesh's keys and nothing else;
it writes nothing when nothing changed; the credentials write strips a refresh token and is atomic; the
lineage cases from the predecessor; a sealed hand-over opens only with the module's key; no tool's answer
contains a token. The catalogue's checks pass.
contains a token. The catalog's checks pass.
**Proof, live, on one workstation, configuration only.** Assign the module; set the node's role; push.
The agent's managed directory holds the two files; everything under the person's agent directory is
@@ -188,11 +188,11 @@ credentials file is left as it was and the agent authenticates through the key-h
*The live mesh and mesh-catalog. One day.* The module on every node, the predecessor's files removed on
the second workstation; a login under a licence's account collected and adopted, and one under the wrong
account refused and notified; `anthropic-manager` and `anthropic-consumer` retired from the catalogue;
account refused and notified; `anthropic-manager` and `anthropic-consumer` retired from the catalog;
designs 36 and 39 set to `implemented` with the as-is written
([playbook 02](../../00-META/process/02-graduation.md)).
**Proof.** `claude_code_status` answers on every node; the refusal's notification arrived; the catalogue
**Proof.** `claude_code_status` answers on every node; the refusal's notification arrived; the catalog
has no module built on the old placement.
## The home, personal rules and lessons — WP7 to WP10
@@ -259,7 +259,7 @@ WP10 the rest of the nodes, and the as-is (the live mesh)
neither list, the watched entries and the pending requests.
**Proof, before anything runs live.** The module's tests of design 36 "How it is checked" for ADR 0273 §1,
§2, §3 and §4, each failing on the commit before. The catalogue's checks pass.
§2, §3 and §4, each failing on the commit before. The catalog's checks pass.
### WP8 — Personal rules and the operator's items, live
@@ -2,7 +2,7 @@
layer: to-be
status: in-progress
code: [mesh-host, mesh-controller, mesh-catalog]
updated: 2026-10-16
updated: 2026-11-04
decisions:
- "ADR 0394"
- "ADR 0310"
@@ -146,7 +146,7 @@ against WP2's controller before anything is published.
the node. The rendering is ADR 0203's and ADR 0204's: module order, a naming line per contribution,
`PATH` entries added only when missing. `${machine:…}` in a contributed value is resolved first.
- **Refusals.** A variable set by two modules on one node is refused, naming both. A placeholder in a
module that does not claim the matching seat is refused, both at the catalogue check and at
module that does not claim the matching seat is refused, both at the catalog check and at
composition.
**Proof.** The controller's tests:
@@ -157,7 +157,7 @@ against WP2's controller before anything is published.
- each refusal, by name;
- the seat table carries both seats and refuses a module declaring either.
The catalogue check over the whole catalogue passes.
The catalog check over the whole catalog passes.
## WP3 — The modules
@@ -188,7 +188,7 @@ The catalogue check over the whole catalogue passes.
- **`zsh-autosuggestions` and `zsh-syntax-highlighting`, new.** Each declares its package and
contributes its loader from the distribution's path, in the `normal` and `last` slots.
**Proof.** The controller's catalogue check over the whole catalogue passes. The modules' tests pass.
**Proof.** The controller's catalog check over the whole catalog passes. The modules' tests pass.
A rehearsal composition for a node holding all five shows:
- the `.zshrc` block with the prompt in `normal` and highlighting in `last`;
@@ -227,7 +227,7 @@ The user-scoped units of `mesh-host` #72 stay to-be 38's WP6.
1. Merge WP1 and roll the node-engine.
2. Merge WP2, and push the controller.
3. Merge WP3 and WP4, and build the new modules by hand: a new catalogue module's first build is asked
3. Merge WP3 and WP4, and build the new modules by hand: a new catalog module's first build is asked
for, not automatic.
4. On one server, assign `node-env`, `zsh`, `zsh-autosuggestions` and `zsh-syntax-highlighting`, and
push. Then check:
@@ -262,7 +262,7 @@ group**: the lighting daemon's, the container runtime's, a serial port's. It dec
│
node-engine usermod --append ── recorded on openrazer.account: "the mesh added openrazer"
│
account judge database lists it? ── running manager holds it? ── no: relogin needed
account probe database lists it? ── running manager holds it? ── no: relogin needed
│ (module openrazer, kind account)
controller module.openrazer.<machine>.unhealthy, cleared on the first look after a new login
```
@@ -280,7 +280,7 @@ group**: the lighting daemon's, the container runtime's, a serial port's. It dec
when the resource is undeclared, is given back. It is not given back while another declared resource
asks for it. The account is taken out of that one group (`gpasswd --delete`), read back, and a failure
is said and is not fatal, as giving back a shell is (WP1).
- **The node-engine, looking.** An account judge sits beside liveness and the failed-unit reading
- **The node-engine, looking.** An account probe sits beside liveness and the failed-unit reading
(issue 315). On every look it reads, for each account a module puts in groups, the database's groups
and the groups of the account's running manager, from that process's status file. It states each as the
module's resource of kind `account`: healthy, or unhealthy with *not in the group* or *relogin needed*.
@@ -328,7 +328,7 @@ control-node withholds it until a call to it needs a person's approval. The othe
writes it into, and a word naming that file for its tools bundle. The bundle registers `execute` only
when the file says `serve`. `zsh_config` also answers whether `execute` is served on the node, and why.
**Merge order.** The controller first, then the catalogue. Either order composes. With the catalogue
**Merge order.** The controller first, then the catalog. Either order composes. With the catalog
alone and the control-node's value set, the self-check would say the holder there is silent.
**Proof.** The tests ADR 0268 lists under *how it is checked*. Live, after both are merged and rolled
@@ -382,7 +382,7 @@ move, write or delete a file, and a cleanup needed a shell on the machine. Most
project folders, downloads, logs, scratch.
- **A node seat, `node-files`, on every node**, held by a module of its own, `mesh-files`, beside `mesh-reads`
in the catalogue; the controller holds the seat's definition beside the other node seats. It has a verb for each file action: list,
in the catalog; the controller holds the seat's definition beside the other node seats. It has a verb for each file action: list,
stat, readlink, read, search, write, copy, move, delete, make a folder, change mode, change owner, account and group
lookup, and the trash's list and restore. Each says what it replaces (ADR 0245): `ls`, `stat`, `readlink`, `cat`,
`grep`, `cp`, `mv`, `rm`, `mkdir`, `chmod`, `chown`, `getent passwd`, `getent group`, `id`, and `ssh <node> cp` for a
@@ -50,7 +50,7 @@ not before. Modules that need none go ahead now.
## How every module moves
1. Written in the catalogue, with its tools and their tests, and checked by the controller's catalogue
1. Written in the catalog, with its tools and their tests, and checked by the controller's catalog
check.
2. Merged, which builds it.
3. Assigned to **the first workstation, the proving machine**, and pushed. Its tools and files are
@@ -199,11 +199,11 @@ both places of both bars once. The bar writes no block that depends on the hardw
the power module's state `power.draw`, one value per machine, which its bundle puts from its own root
sampler. The block `shows: state`; the bar's bundle watches it under a read the controller grants the
bar for what the modules on its machine offer, and the bar names no module. The battery block is the
bar's own, reading the kernel. The catalogue's `checks/paths` refuses a module that names another
bar's own, reading the kernel. The catalog's `checks/paths` refuses a module that names another
module's path under `/run` or `/var/lib`.
The node-engine is delivered first, so the machines report the two capabilities. The controller comes
next, because it parses `data`, `if-capability` and `renders`. The catalogue comes last. Left open: the
next, because it parses `data`, `if-capability` and `renders`. The catalog comes last. Left open: the
draw at the wall (a metered plug or a UPS), a GPU-load block from a generic module, and the headsets.
## Phase 3 — one machine model
@@ -213,6 +213,6 @@ and `memory-pressure` (research 027/03).
## How it is checked
Each module's own tests and the catalogue check, at merge. On the proving machine, each tool answered
Each module's own tests and the catalog check, at merge. On the proving machine, each tool answered
through the mesh and each owned file checked in place, before any other machine is assigned. This
document's tables are updated as each module lands.
@@ -146,8 +146,8 @@ a manifest. Not off-site: a lost machine loses its backups with its data, by the
## How it is checked
The catalogue check (`module check`, and the catalogue-wide test beside it) refuses a provider that
The catalog check (`module check`, and the catalog-wide test beside it) refuses a provider that
grants without saying what it keeps for its consumers, an irreplaceable item with neither a backup nor a
redundancy, and any backup line written by hand (ADR 0233). The store rule this design stated before
was held only by a controller test over the catalogue checked out beside it, never by `module check`. The weekly
was held only by a controller test over the catalog checked out beside it, never by `module check`. The weekly
restore test above, and the 48-hour status line, are the running checks.
@@ -2,7 +2,7 @@
layer: to-be
status: in-progress
code: [mesh-controller, mesh-host, mesh-tools, mesh-catalog, mesh-sdk, mesh-lab]
updated: 2026-10-14
updated: 2026-11-04
decisions:
- "ADR 0357"
- "ADR 0325"
@@ -68,7 +68,7 @@ Owning repositories: **mesh-controller** (the condition store, watchdogs, `docto
calls, the hand-act log, the facts snapshot), **`mesh-host`** (the node-engine: the apply queue, report
order, epoch refusal, the `report` verb, rollback witnessing), **mesh-tools** (the tool runner and the
mesh MCP server: their heartbeat, passing every argument, health answers), **mesh-catalog** (the
`operator-channel` seat's holder and channels, the watcher, the providers' retirement, the catalogue's
`operator-channel` seat's holder and channels, the watcher, the providers' retirement, the catalog's
composition check), **mesh-sdk** (the TypeScript providers' loop and its retirement), **mesh-lab** (the
replays and the induced-failure scenarios).
@@ -680,7 +680,7 @@ runs, and a restore that builds a new store beside the live one for a person to
**The facts snapshot.** The controller exports daily, and after any change of machines, assignments or
seats: every machine (a stable pseudonym of the same length as its name, its role, operating system,
C library, architecture, node-engine and tool runner builds), assignments, settings keys and their
non-secret values, seats and their holders, the catalogue commit, and the versions the mesh runs of
non-secret values, seats and their holders, the catalog commit, and the versions the mesh runs of
the bus server, the store and the node-engine. No secret and no address: an address is replaced by one
from a documentation range. It is kept in the artifact store as `facts/latest`, where the build seat
reads it.
@@ -768,7 +768,7 @@ replay covers what must not be done to it on purpose, and every rule keeps a liv
- **It runs on the build seat**, asked by the controller when the forge's announcer says a pull request's
head moved: the repository's own `merge-check.sh` in the mesh's Go toolchain with no container runtime
socket, beside a throwaway store and bus of the versions the snapshot says run, then mesh-lab's replays.
The verdict is the head commit's status `mesh/merge-gate`, an error never a pass. A catalogue change is
The verdict is the head commit's status `mesh/merge-gate`, an error never a pass. A catalog change is
judged by the controller the mesh runs; a node-engine change by it built with the change's validator.
- **Replays live where their incident is**: a component's logic in its repository as `TestReplay<issue>`,
what the mesh runs (the bus's release, the resolver under musl and glibc) in mesh-lab's `replays/`, all
@@ -868,7 +868,7 @@ the `data` verb; `cleanup` extended to a module's own retired data, deleted by t
holder after a last restore point; the controller's grant names `node-backup.backed-up`. Built on
branches in mesh-controller (migration 0072), `mesh-host` (the installer's user list; the kept-directory
report), mesh-catalog (the holder's measuring and deletion, every module's data, the providers' held
sizes), the media catalogue and the photo application, not yet merged. **Not yet:** the TypeScript
sizes), the media catalog and the photo application, not yet merged. **Not yet:** the TypeScript
providers saying their consumers' sizes (until then a consumer at two of them is `data-held-twice`, a
warning, not compared), and SMART read under an array.
@@ -931,8 +931,8 @@ and "the commit is the build at hand"), on branches, not yet merged:
| Repository | Delivers |
|---|---|
| mesh-controller | the planner's one mapping of a changed file onto modules and its one answer of a merge's reach, asked by the merge handler, the what-if, the gate and the check; a file no build reads touches nothing (issue 280's *left open*); every pull request answered — the gate when it reaches a module, the repository's own check for the mesh's repositories, a pass that says so otherwise; the gate run by the build seat with its judge chosen from the graph, composing the plan's definitions only, failing only a manifest problem the change brings; the delivery plan computed and carried with the verdict; a build of a commit off its module's trunk recorded and never registered; its own manifest naming every verb of its seat |
| mesh-catalog | the forge's announcer saying, with every pull request, the directories holding a module at its head, the files it deletes and whether it has a `merge-check.sh`; both statuses and the delivery plan on the pull request; `gitea_branch_protection_get` and `gitea_branch_protection_set`; the catalogue's own check |
| mesh-controller | the planner's one mapping of a changed file onto modules and its one answer of a merge's reach, asked by the merge handler, the what-if, the gate and the check; a file no build reads touches nothing (issue 280's *left open*); every pull request answered — the gate when it reaches a module, the repository's own check for the mesh's repositories, a pass that says so otherwise; the gate run by the build seat with the program it composes with chosen from the graph, composing the plan's definitions only, failing only a manifest problem the change brings; the delivery plan computed and carried with the verdict; a build of a commit off its module's trunk recorded and never registered; its own manifest naming every verb of its seat |
| mesh-catalog | the forge's announcer saying, with every pull request, the directories holding a module at its head, the files it deletes and whether it has a `merge-check.sh`; both statuses and the delivery plan on the pull request; `gitea_branch_protection_get` and `gitea_branch_protection_set`; the catalog's own check |
| `mesh-host`, mesh-tools, mesh-sdk, mesh-lab, mesh-media-catalog, and the applications built from their own repositories | each its own `merge-check.sh`; mesh-tools' tests each on a bus of their own |
| mesh-tools-go, mesh-tools | a C compiler and Python in the Go toolchain, git in the TypeScript one |
| hq | its own `merge-check.sh`, running `records.py`, `index.py` and `cycle.py` |
@@ -2,8 +2,10 @@
layer: to-be
status: in-progress
code: [mesh-controller, mesh-tools, mesh-sdk, mesh-catalog]
updated: 2026-10-13
updated: 2026-11-10
decisions:
- "ADR 0667"
- "ADR 0666"
- "ADR 0347"
- "ADR 0345"
- "ADR 0344"
@@ -221,7 +223,20 @@ when the title and the note alone do not fit, and says that too.
### Limits, batching, history
- An asker holds **at most three open asks**; a fourth is refused in words.
- An asker holds **at most three open asks**; a fourth is refused in words. *Amended 2026-11-10, ADR 0666 §12, from the
delivery of design 47's milestone G:* **no ask is hidden, and the newest is never held back.** An asker still has at
most three asks offered at once, but a fourth is offered, not refused: the oldest of its offered asks is held back
instead, kept open with its answer tickets withdrawn, its message edited to say it waits behind newer asks of the
same asker, and offered again, with new tickets, as soon as one of the three ends. An ask with the same `about` as an
open one of the same asker replaces it (§10), so a held-back ask is never one a newer ask already stands for. `asks`
lists each asker's held-back asks with since when, and the router's tool `ask-again` offers one now, holding back the
oldest offered one in its place. A Decline ends an ask like any answer, and its asker may ask again at once: the
pipeline runner's verb `ask-again` asks a declined `approval` step so (design 47, *Approval is a step*). Why the
oldest: the newest is what the asker needs now, and the oldest has had the operator's eye longest; holding it back
edits its message rather than removing it, so the operator still sees it waits. *How it is checked:* the router's
whole-module test offers a fourth ask and holds back the oldest, offers the held-back one again when one ends,
replaces an open ask by a newer one with the same `about`, and offers an ask after a Decline; live, a fourth ask and
a declined approval each reach the operator (design 47, test 71).
- Asks count against the router's hourly cap, as messages do; answers do not.
- Asks to one channel within the burst window go out together under a heading ("3 questions waiting"),
each as its own message, answerable and editable alone.
@@ -424,7 +439,8 @@ what it does in plain words, its assurance level (`acknowledge`, `approve`, `des
answer (`operator`); an expiry; what happens on expiry, in words; and optionally what it is about (a
condition's key), so a newer ask about it replaces the older. It is refused at once, on its asker's
`decided` subject, when its words break a rule, when no ready channel can carry one of its options' levels,
or when the asker already has three open.
or, until the delivery of design 47's milestone G, when the asker already has three open; from that delivery a fourth
is offered and the asker's oldest held back (§6, *Limits, batching, history*; ADR 0666 §12).
**A warrant** carries the ask's id and asker, the option, `by` ("the operator, via telegram, user id
verified"), the channel module, the proofs, the level met and when. No secret. An ask that ends without one
@@ -577,7 +593,8 @@ runner's bus permissions.
refused and said: waiting, declined (not asked again for 10 minutes), expired, already run, or the router's
refusal.
- **Fail closed:** a secret's shape in an argument or more than 16 KiB of arguments, no operator channel, a
fourth open ask, an unpublished ask, an unreadable router record, node file or mark: nothing runs.
fourth open ask (until design 47's milestone G is delivered, after which a fourth is offered and the oldest held
back, §6), an unpublished ask, an unreadable router record, node file or mark: nothing runs.
- **The controller** enforces the same mark on its own verbs, asking as `mesh-controller`.
- **Marked first:** `node-login-shell.execute` on every node once the reads it carried have tools (issue 418).
`mesh-delivery.release` waits until a warrant the controller holds passes the mark of a verb it calls (issue
@@ -696,12 +713,13 @@ Each phase ends at its own *done when*. Owning repositories from [`repos.md`](..
|---|---|---|---|
| **1 — Fix the first holder in place** | D1–D4 in the output seat's holder and the watcher, then D5–D10; no change of shape. The operator then makes the two bots and the mesh is given their values through the controller | mesh-catalog | the holder's tests for D1–D4 pass; a live test message reaches the phone from both the holder and the watcher |
| **2 — The desk's actions** | `node-notifier.send` gains actions; the dunst holder emits the chosen one; the launcher's prompt returns typed text; the screen-lock holder emits lock and idle changes | mesh-catalog | a notification with two actions returns the chosen token as an event; locking emits an event |
| **3 — The seats, and the router** | the kinded bench in the seat set; `kind` and `capabilities` on a claim; `channel-capabilities/1` and its contract tests; publishing on a seat's event subjects and its grant; `channel` and `intake` seats; the output seat's holder becomes the router and holds `channel/desktop` and `intake/desktop`; presence as current state; the operator's identity list and identity check in the controller, the router's `trusted` stamping and untrusted input (§4); the content rule allowing machine names, references and `detail`, refusals naming the offending part (§9) | mesh-controller (seat set, claim fields, registration refusals, grants, the identity list and check); mesh-sdk and mesh-tools (seat-event publishing in the shared library and the tool runner); mesh-catalog (the seats' definitions, the router) | the catalogue refuses an unknown capability and a second holder of one kind; a message is routed to the desk by capability and context; an envelope from an identity not on the list is re-emitted untrusted; a path is refused to its sender by name, and travels as a reference the desk opens |
| **3 — The seats, and the router** | the kinded bench in the seat list; `kind` and `capabilities` on a claim; `channel-capabilities/1` and its contract tests; publishing on a seat's event subjects and its grant; `channel` and `intake` seats; the output seat's holder becomes the router and holds `channel/desktop` and `intake/desktop`; presence as current state; the operator's identity list and identity check in the controller, the router's `trusted` stamping and untrusted input (§4); the content rule allowing machine names, references and `detail`, refusals naming the offending part (§9) | mesh-controller (seat list, claim fields, registration refusals, grants, the identity list and check); mesh-sdk and mesh-tools (seat-event publishing in the shared library and the tool runner); mesh-catalog (the seats' definitions, the router) | the catalog refuses an unknown capability and a second holder of one kind; a message is routed to the desk by capability and context; an envelope from an identity not on the list is re-emitted untrusted; a path is refused to its sender by name, and travels as a reference the desk opens |
| **4 — Asks, and operator messages** | `ask`, `ask cancel`, `asks`, `answer`; the events; kinds, life, limits, batching, history; escalation; addressing, the register of agents with kept messages, the responder; the untrusted-input rule in every agent module's instructions (§5) | mesh-catalog | the router tests of ADR 0234 pass; live: an agent's question answered at the desk, and with the desk locked, on the phone; `@mesh status` answered; a message to a stopped agent kept and said |
| **5a — Asks on the bus** (ADR 0259) | the kinded bench, caller-named verbs, `proof` subjects and the records users read (controller); a bundle's seat traffic, compare-and-set state and its own account (tool runner); the asker's and channel's types (shared library); the router's asks, tokens, identities, judging, warrants, expiry and linking with its hour (messenger); `telegram` and `desk-channel`; the controller asking for its conditions' actions and acting on warrants | mesh-controller, mesh-tools, mesh-sdk, mesh-catalog | a held delivery released from the phone; the hand-act reads "the operator, via telegram, user id verified"; a desk Silence goes through an ask |
| **5 — Authorise, with TOTP** | `authorises` in the verb table; the router's checks for the code; direct calls refused, break-glass; `retire approve` takes `expect`; the hand-act fields; the TOTP seed as the router's state, enrolled at a terminal with ten recovery codes; `factor recover`, `factor status`, the local-only break-glass enrolment; no P2 tier before recovery codes exist; optional key enrolment; the self-check probe for the away channel; agents' grants lose the authorising verbs | mesh-controller; mesh-catalog (agents' grants, the desk's code prompt) | one controller test per refusal passes; at the desk, approve needs a code; a recovery drill re-enrols with a recovery code, and is announced |
| **6 — Telegram live** | the `telegram` module (built in 5a) with replies and forced-reply codes, under its own account on the control node; the operator's two bots configured; the watcher assigned off the control node; the dead-man ping | mesh-catalog | the self-check says the away channel carries every tier; rehearsals: an approve and a destroy answered on the phone, with the hand-acts read |
| **7 — A call that needs approval** (ADR 0286) | `needs-approval` in the manifest and the seat set, issued in the membership, withheld from a runner without `approval-mark/1` in its bus permissions (controller); the act's digest in TypeScript beside Go, with shared vectors (shared library); the check, the ask, the runner's `approvals`, the node's used file and `warranted` (tool runner); the controller's own verbs; `execute` marked (the controller's seat set) once issue 418's reads exist | mesh-controller, mesh-sdk, mesh-tools, mesh-catalog | a marked call on a node is asked on the phone, does nothing, runs once when made again after Approve, is refused the third time and asked again, and `hand-acts` shows the warrant |
| **7 — A call that needs approval** (ADR 0286) | `needs-approval` in the manifest and the seat list, issued in the membership, withheld from a runner without `approval-mark/1` in its bus permissions (controller); the act's digest in TypeScript beside Go, with shared vectors (shared library); the check, the ask, the runner's `approvals`, the node's used file and `warranted` (tool runner); the controller's own verbs; `execute` marked (the controller's seat list) once issue 418's reads exist | mesh-controller, mesh-sdk, mesh-tools, mesh-catalog | a marked call on a node is asked on the phone, does nothing, runs once when made again after Approve, is refused the third time and asked again, and `hand-acts` shows the warrant |
| **8 — No ask hidden** (ADR 0666 §12), delivered with design 47's milestone G | a fourth ask offered and the asker's oldest held back, offered again when one ends; `asks` lists the held-back asks; the router's tool `ask-again`; the pipeline runner's `approval` asks and their `about` | mesh-catalog (the router) | a fourth ask and a declined approval each reach the operator; `asks` shows the held-back one |
**Switching phase 5a on: the operator's steps, in order** (amended 2026-10-09, ADR 0259). Each line is typed with
`nox` (`mesh-cli`) on the control-node, from the operator's own account, which is the controller's terminal
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,408 @@
---
layer: to-be
status: in-progress
design: 47
milestone: G
updated: 2026-11-10
decisions:
- "ADR 0668"
- "ADR 0667"
- "ADR 0666"
- "ADR 0664"
- "ADR 0661"
- "ADR 0656"
- "ADR 0633"
- "ADR 0619"
- "ADR 0614"
- "ADR 0596"
- "ADR 0595"
- "ADR 0593"
- "ADR 0584"
- "ADR 0573"
- "ADR 0567"
- "ADR 0564"
- "ADR 0548"
- "ADR 0448"
- "ADR 0429"
- "ADR 0398"
- "ADR 0363"
- "ADR 0283"
---
# 47, milestone G: pipelines per module: registration, watched branches, steps and policy, what holds a delivery, approval, groups, dependencies, a publish
One file of milestone G's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
[G.md](G.md). Its design lines are numbered across every file of the part and cited as "design 47 G §n".
## Pipelines per module
*ADR 0666, ADR 0667; ADR 0595, ADR 0596, ADR 0448 §2, §4, ADR 0548 §5, ADR 0564 §2, §4, ADR 0283, ADR 0656 §4, §6, ADR 0633 §5,
ADR 0664 §4, ADR 0398 §2, ADR 0593 §9; research 086, Direction.*
§1 From milestone G's delivery. A change of any module, the delivery system's own parts included, goes from a commit to
the machines through that module's **pipeline**: the pipeline steps its **policy** names, run for each commit or group
on each of the module's **watched branches** by the seat `mesh-pipeline-runner`, ordered by the catalog graph's edges
between artifacts, with no hand act (ADR 0666 §1). Milestone G is the one milestone that builds it, beside the two
graphs, the revision view and the delivery record (ADR 0667 §1). Until G's delivery the sections this one replaces
(*Checks*, *A try*, *The Approve and the merge*, the state table and the trunk-only want) hold as written, and they
check and deliver milestone G itself (ADR 0667 §2); each of them says so in a line of its own.
```
a session ──merge-pull (seat git)──► forge ──commit on a watched branch──► forge bridge ──► indexer (mesh-catalog)
│ registrations; a catalog graph
│ per watched branch; the revision
│ validated before take-in
▼ take-in.taken
pipeline runner (mesh-pipeline-runner) ── asks each pipeline step on the serving seat's work queue, hears step-ended:
│ lint, unit tests, integration tests ──► the build seats (node-build-go, node-build-node, node-build-image)
│ composition ──────────────────────────► the assigner (mesh-wants)
│ code review ──────────────────────────► the runner's own verb `review`, from the reviewer's bus account
│ approval ─────────────────────────────► operator-channel: accepted kind ask, then decided
▼ pipeline-ended (every step's result), keyed by source revision
assigner ──► wants from a revision whose required steps passed, on the watched branch a placement chose
gate ──► the delivery record keeps the step and pipeline events
```
### A module's registration
- §2 **What it holds.** The seat `mesh-catalog` keeps each module's **registration**: its git origin, the path of its
manifest, its watched branches and its policy, on the bus, every version with who changed it and the warrant of the
operator's Approve (ADR 0666 §2). The indexer is a foundation part, so the registrations are kept in its old sections
(ADR 0619 §1 to §3, ADR 0666 §4): one key per module in its old `state` section `registrations`, and every version on
its old `streams` section's stream `registration-history`, kept with no age limit.
The catalog graph is derived from the registrations and the manifests they point to; the mesh knows modules, and a
repository only as a module's git origin.
- §3 **Changing one is a trusted act.** The seat's verbs `register` (a module whole), `policy` (one module's step
statuses, per artifact), `watch` and `unwatch` (add or remove a watched branch) each raise an authorising ask of tier
approve through the seat `operator-channel` (design 46 §10), naming every value the change moves, one line each
("`mesh-grants:program` unit tests: `required` → `bypass`"), and write the version only on its warrant; a Decline or
an expiry writes nothing (ADR 0666 §2). Until a record binds each forge account to its bus identity, `register` and
`policy` refuse code review as a `required` step, naming why, so no review gates while its author cannot be told
(ADR 0666 §22; issue 1966, note 157). A manifest moved to another path is the one manifest change that changes the
registration; any other manifest change is a commit, judged at its revision.
- §4 **Said and read.** Each written change is said as the seat's event `registration-changed` (the module, the version,
what moved); the verb `registrations` answers every registration, or one with its history. The indexer derives the
modules it keeps from them, and the forge bridge its watched branches, each by a first view of `registrations` and
then that event, never by reading the ledger (ADR 0666 §3, ADR 0596).
- §5 **An unprotected branch is refused.** `register` and `watch` read a branch's protection through the seat `git`'s read
verb `branch` (its head, and whether a rule refuses a direct push and admits only merges), and refuse a watched branch
the forge does not protect, naming it (ADR 0666 §3).
- §6 **The foundation parts are the manifest validator's list.** The manifest validator's list (ADR 0619 §3) holds
exactly the foundation parts, ADR 0619 §1's and the runner, which joins them (ADR 0666 §4); the checker leaves the
list when it is removed (*How milestone G itself is checked and delivered*). A registration holds no foundation
value. How it is checked: a unit test of the manifest validator refuses a template in the manifest of every part on
its list, the runner's included, and judges every other part's manifest as any part's.
- §7 **No part fixes a name.** Every branch, repository and module name a part needs is read from the registrations and the
catalog graph; the lint step refuses such a name in a string, a constant or a table of code logic, a Go import path
not being code logic (ADR 0666 §5). About 39 such names in 9 parts were found on 2026-11-09 (research 086, Findings);
milestone G removes them.
- §8 **The first registrations are one ask.** At its first start on G's build the indexer, holding no registration,
proposes one registration for every module its trunk revision holds, from what it took in (the origin and path of
each), its watched branch the repository's default branch read through the seat `git`, and the statuses the check
judged until then: lint, unit tests, integration tests and composition `required`, code review `optional`, approval
`bypass`. Each step the artifact's build seat answers `steps` with none is `bypass` instead, so no module is held by
a `required` step it has nothing for; the indexer asks `steps` of each build seat as a kept call (ADR 0668 §1, §2),
and the seed waits until every build seat has answered, never reading an unanswered seat as "none": a seat still
unanswered after five minutes is the indexer's `call-unanswered`, naming the seat (ADR 0668 §3), and the seat's new
build serving `steps` is an edge of kind 6 before the seed. A module whose default branch the forge does not protect
is left out of the seed and named in the ask, as `register` would refuse it (ADR 0666 §3). It raises the rest as one
ask naming every registration, as the seat `mesh-module-assigner`'s `adopt` proposes placement whole (ADR 0567).
While the ask is open the indexer's finding `seed-waits`, naming the ask, is raised by the condition keeper as
waiting on the operator (ADR 0283) and cleared by the warrant; a Decline or an expiry leaves the seed unwritten, says
so and keeps `seed-waits`, naming `indexer_seed_again`, which raises the ask again, recorded in the hand-act log.
Until that Approve the runner starts no delivering pipeline and says why, so the operator is told of this one ask
before G's delivery starts. Why: the design's choices under ADR 0666 §3, §7 and ADR 0668 (round 1 of the review by
architectural domain, 2026-11-10). How it is checked: whole (indexer), a build seat that never answers `steps`
holds the seed and raises `call-unanswered`, one that answers none gives `bypass`; an unprotected default branch is
left out and named; `seed-waits` is raised while the ask is open and cleared by the warrant.
- §9 **Kept for the life of the mesh**, never derived again (research 086, choice 25): the history stream's cap is 64 MiB.
About 120 registrations of about 1 KiB, and an estimated change a week each (a guess, not a measure), grow about 6 MiB
a year, so the cap holds about ten years; past 80 % the indexer says `filling`, as every store of *Two graphs, one
source of truth* does.
- §10 **How it is checked.** Whole (indexer): an unprotected watched branch is refused, naming it; a policy change without
the warrant writes nothing, and a declined one writes nothing; a change from `required` to `bypass` asks, showing
that line; `registration-changed` is said and `registrations` answers the history; the first start proposes the seed
as one ask, and `indexer_seed_again` asks it again after a Decline and after an expiry; a policy making code review
`required` is refused. Unit (the Go build module's lint step): a module name in a string, a constant and a table is
refused, an import path is not. Tests 75, 68 and 83.
### Watched branches and the catalog graph per branch
- §11 **Only a watched branch starts a pipeline.** The forge bridge hears every commit of every watched branch the
registrations name, through the seat `git`'s event `branch-moved` (a branch's new head, from the forge's push
webhook, which a merge and an admitted push alike say), and takes the commit from the forge's own record by the seat's
verb `branch`, never from the event's body (ADR 0666 §6). One event for every way a branch moves, because a merge is
not the only one. `branch-moved` is kept on the seat's stream `SEAT_git_branch-moved`, which the bridge hears through
a durable consumer, so a move said while the bridge is down is heard when it starts; at its start it also reads each
watched branch's head the same way.
- §12 **A head with no pipeline is a finding.** A watched branch's head that starts no pipeline within five minutes is the
watchman's finding `pipeline-stands`, naming the branch and its head, raised by the condition keeper (ADR 0564 §2),
unless it waits as progress not owed: a member of a gathered group is governed by ADR 0633 §5's 30-minute bound, and
a merge behind a pending revision of the same branch by its 60-minute bound (ADR 0666 §24). The finding clears on the
runner's `pipeline-started` for that head.
- §13 **The catalog graph per watched branch.** The indexer keeps the catalog graph once per watched branch, from that
branch's manifests at each source revision (ADR 0666 §6): each revision names its branch, and the stores, caps and
pins of *Two graphs, one source of truth* hold per branch.
- §14 **A placement names the branch.** Each module of a placement key names the watched branch its node runs, by default the
registration's first, set by a placement proposal like every other placement change (ADR 0567, ADR 0666 §6). The
assigner computes each node's entries from the catalog graph of the branch its placement names, so a module watched on
`main` and `beta` runs `beta` only where a placement chose it.
- §15 **A source revision per watched branch.** The gate keeps one source revision per watched branch, `source.<branch>`,
in place of `source.main` (ADR 0429 §11 to §13 as ADR 0666 §6 changes them), in the old `state` section `source`
already holds, its key's layout being the only change. The gate is no foundation part: the bus module's delivery
waits on no act of the gate's, since the indexer takes a revision in from the forge bridge's stream and the assigner
writes wants from the runner's events, so the gate's other kept data stay in ADR 0595's templates (ADR 0666 §4), and serves it by the seat
`mesh-delivery`'s verb `source` with the branch, saying `source-moved` on each new revision; the indexer and the
node-engine's catch-up read it there, never the gate's state (ADR 0596). Each want names a build-input fingerprint
computed at one such revision.
- §16 **Validated before any take-in, on every branch.** Before it takes a revision in, on every watched branch, the running
indexer asks the manifest validator built from the revision's heads to judge it in the build seat's sandbox (the
ask `run`, *What ADR 0656 leaves to this design*). A revision it refuses stays pending under ADR 0633 §5's
60-minute bound, its hand acts and its condition `take-in-waits`; the way back is a revert, an ordinary merge
(ADR 0666 §6, §26). A revision on the branch the indexer's own placement chose is taken in only by the indexer it
names (ADR 0633 §1). This validation is no pipeline step and waits on no pipeline, so every delivering pipeline runs
on a revision already taken in.
- §17 **A branch whose protection was removed starts nothing.** On every `branch-moved` the forge bridge reads the
branch's protection again; a move of a watched branch whose protection was removed starts no delivering pipeline, and
the forge bridge writes the finding `branch-unprotected`, naming the branch, which the condition keeper raises and
clears once the protection is back (ADR 0666 §6).
- §18 **A pending revision holds its own branch only.** A merge waits behind a pending revision only on the same watched
branch; other branches move on (ADR 0666 §6, which changes ADR 0633 §3).
- §19 **A refused new indexer holds its branch until a revert lands.** A merge of a new indexer whose own validator refuses
its revision has already landed when it is refused, since the validation runs before take-in and after the merge
(ADR 0666 §6). It stays pending, and every later merge on that watched branch waits behind it, said by
`take-in-waits` at the 60-minute bound, until a revert, an ordinary merge through its pipeline (ADR 0666 §26), lands
and is taken in; nothing takes a later merge in past it. This is the cost of validating every revision with the
validator built from its own heads, the design's reading of ADR 0666 §6, and the operator is told it with the
condition, which names the pending revision and the revert as the way on.
- §20 **How it is checked.** Whole (forge bridge): a commit of a branch no registration names starts nothing; a commit on a
watched branch is taken from the seat's `branch` read, not the event; a head missed while the bridge was stopped is
read at its start. Whole (indexer, assigner): a commit on `beta` gives a revision of the `beta` graph only and moves
only the want of the node whose placement chose `beta`; a revision whose own validator refuses it stays pending and
holds `beta` while `main` moves on. Whole (watchman): a head with no pipeline for five minutes raises
`pipeline-stands`, cleared by `pipeline-started` for that head, and a gathered member does not; a move said while the
bridge was stopped is heard from the seat's stream. Tests 64, 68, 76, 78 and 82.
### Pipeline steps and the policy
- §21 **The runner.** The seat `mesh-pipeline-runner`, held once for the mesh by the module `mesh-delivery-pipeline`,
runs each pipeline (ADR 0666 §7). It is a foundation part, since the bus module's own delivery waits on its pipeline
(ADR 0666 §4): its kept data are in old sections (ADR 0619 §2), it waits on no bus module process to start, and it
joins the manifest validator's list of foundation parts, which refuses its manifest asking a template (ADR 0666 §4,
which changes ADR 0619 §1 and §3). It reads the policy from the registrations, asks each step that is not `bypass` of
the seat that serves it, and says each step's start and end and the pipeline's end (*Health and going back*, below).
- §22 **The steps and who serves them.** Lint, unit tests and integration tests are the build seats' (`node-build-go`,
`node-build-node`, `node-build-image`): each gains the verb `steps`, which answers which pipeline steps an artifact
can run by its language's convention (as *The check from release 4* says the tests are found), and the accepted kind
`step` on its stream `check`, which runs one. Composition is the assigner's, an accepted kind `step` of the seat
`mesh-wants`. Code review comes in through the runner's own verb `review`. Approval is asked as the seat
`operator-channel`'s accepted kind `ask`, on its work queue by the runner's name (design 46 §10, *Asks, warrants and answers on the bus*;
the seat has no verb `ask`), and heard on its event `decided` (ADR 0666 §7, §10). A step with nothing to do ends at once as
`nothing to run`, never as passed.
- §23 **The policy.** Each step's status, per module and per artifact, is `required` (runs; holds the delivery until it
passes), `optional` (runs; a failure is shown and may be accepted) or `bypass` (nothing runs; said as bypassed),
kept in the registration and never in a manifest: the manifest validator refuses a manifest that names a status
(ADR 0666 §7; research 086, R3). A `required` step that ends `nothing to run` holds the delivery and names the step.
- §24 **Asked on a work queue, ended by an event.** The runner asks each step on the serving seat's work queue and hears
its end as that seat's event `step-ended` (the record's `step ended`), on
`mesh.seat.<seat>.event.step-ended.<node>`, the node that ran it in the subject and each holder's account granted only
its own node's subject, through a durable consumer of its own, so a step outlives a restart of either side (ADR 0666
§7, ADR 0363 §2). A build seat's holder restarted mid-step gets the step again from its work queue and finishes it
(ADR 0664 §1). A unit or integration test step says its test counts in `step-ended`, and `pipeline-ended` names any
repository over 50 integration or 500 unit tests, and any catalog module over them (ADR 0666 §8; the test budget). A step's outcome is one of `passed`, `failed`, `nothing to run`,
`bypassed`, `carried` (with the pipeline it was carried from), `could not run` (naming the part not heard),
`waiting on <person>`, `accepted` (a failed `optional` step a person accepted, with who and why), `not asked` (an
`approval` step after a failed `required` step), `superseded` and `cancelled`.
- §25 **Carried, not run.** A step whose build-input fingerprint and policy did not change is carried by its package
digests, as ADR 0548 §5 holds, the runner making the carry instead of the checker: a test step runs only the packages
with no kept result for their digest, and a run on request's results are reused when the merged commit's inputs match
(ADR 0666 §8; research 086, choice 24). An `approval` step is never carried.
- §26 **Approval comes last.** The runner asks the `approval` step only once every other `required` step of the pipeline
passed, so the operator approves a commit the mesh already judged, the one place ADR 0661 §3 had the check gate the
ask. A failure after an approval is said, as a failed `optional` step is, and the approval stays.
- §27 **Kept on the bus, in old sections.** The runner keeps each pipeline's state in its old `state` section `pipelines`,
one key per pipeline keyed by its watched branch, source revision and module, written by compare-and-set so a holder
replaced mid-pipeline and its successor never both write one; its step log on its old `streams` section's stream
`step-log`; each step's output in its old `objects` section `step-outputs`, named in the log; and each package's
passing result per level in its old `state` section `kept`, under the digest of what its tests read (ADR 0666 §4, §8;
*The runner's kept data*, below). `kept` starts empty: the runner takes no verdict of the checker's, since a step's
result is taken only from the bus account of that step's seat holder (ADR 0666 §21), so the first pipelines after G
run each package's tests once and carry from then on (the design's choice, 2026-11-10).
- §28 **How it is checked.** Whole (runner): a step with unchanged fingerprint and policy is carried and says from where,
and an `approval` step is not; a module with no integration tests shows `nothing to run`, and a `required` unit-test
step on a module with no tests holds its delivery; a bypassed step is said; a runner restarted mid-step hears the
step's end and finishes the pipeline; two runners writing one pipeline key, one loses by compare-and-set; a test step's
counts are in `step-ended` and a repository over budget is named in `pipeline-ended`. Whole (Go build module): `steps`
answers the steps of a fixture artifact, a `step` ask ends with `step-ended` on its own node's subject, one on another
node's subject is refused by the bus, and a build module restarted mid-step finishes it. Unit (manifest validator): a manifest naming a status is refused. Tests 65, 66, 73
and 88.
### What holds a delivery
- §29 **The assigner writes a want only from a passed pipeline.** The runner says each pipeline's end as `pipeline-ended`
(the record's `pipeline ended`), keyed by source revision, with every step's result. The assigner consumes it, and
writes a want only from a source revision whose every `required` step passed for the modules it moves, on the watched
branch a placement chose, by compare-and-set on a newer revision, so an older revision ending after a newer one
writes nothing (ADR 0666 §9). The compare-and-set is keyed per module and watched branch: it compares a revision only
with the last one written for the same module on the same watched branch, so a revision of `beta` ending after a
newer one of `main` writes its own want and refuses neither; a later `pipeline-ended` of the same revision (after a
passing `rerun`, below) is taken, since its end count is higher (the design's choice under ADR 0666 §9: source
revisions are kept per watched branch, `source.<branch>`, and two branches' revisions have no order between them). This is one more rule beside the assigner's others (ADR 0429 §6), checked per module.
From G's delivery it replaces the trunk-only want (ADR 0656 §2 as ADR 0666 §9 changes it). For a group's source
revision the runner says one `group-ended` once every member's modules have ended, and the assigner writes the
group's wants only on it: a member's own `pipeline-ended` writes nothing (ADR 0666 §9).
- §30 **A failed `optional` step holds nothing.** It is shown in `pipeline-ended`, in the delivery record and in the runner's
`show`; a person may accept it by the runner's verb `accept`, recorded in the hand-act log with who and why.
- §31 **A newer commit supersedes an older pipeline of a module whose fingerprint it changed.** On a newer commit of the
same watched branch the runner ends a module's older running pipeline as `superseded` only when the newer commit
changed that module's build-input fingerprint (ADR 0666 §9); a module the commit leaves as it was finishes its
pipeline. A newer publish of a package likewise supersedes the rebuild pipelines an older publish of it started. A
superseded pipeline's waiting asks are dropped by each build seat's `drop` (ADR 0664 §4), naming
the newer commit as the cause, so a cancelled pipeline leaves no ask on a stream (a gap G's prepare found: a cancelled
build withdrew only the builder's wait).
- §32 **A step nothing starts ends its pipeline.** A step whose prerequisite nothing starts (a seat with no holder, a
prerequisite step `bypass`) ends the pipeline refused within five minutes, naming the step and what it waits for,
never as a silent wait (research 086, R5); a step whose seat has no holder ends its pipeline failed, naming the seat
(ADR 0666 §17).
- §33 **A failed head is said to its author, then to the operator.** A `required` step that failed, or ended `could not
run`, on a watched branch's head is the runner's finding `pipeline-failed`, naming the module, the branch, the commit
and the step; the condition keeper raises it as the commit's author's for two hours and then the operator's, as ADR
0505 §5 and §6 have a delivery whose cure is its author's new head, and clears it when a newer revision of that branch
passes that step (ADR 0666 §24). The author is the forge's record of the commit, read through the seat `git`.
- §34 **The delivery record keeps every step.** The gate's delivery record consumes the step and pipeline events and keeps
them as long as the record (ADR 0666 §9; *The delivery record*).
- §35 **How it is checked.** Whole (assigner): a failed `required` step writes no want; a failed `optional` step holds
nothing; an older revision's `pipeline-ended` after a newer one's writes nothing, and a revision of one watched branch
ending after a newer one of another writes its own want; a group with one member passed and
another still running writes no want until `group-ended`. Whole (runner): a newer commit that changed a module's
fingerprint supersedes its older pipeline and drops its asks, and one that left it unchanged lets it finish; a step
with no holder ends the pipeline naming the seat within five minutes; a failed `required` step on a head raises
`pipeline-failed`, the author's for two hours and then the operator's, cleared by a newer passing revision. Tests 66,
67, 87, 89 and 98.
### Approval is a step, and a session merges a pull request
- §36 **No Approve per merge.** The operator's approval is the pipeline step `approval`, its status in each module's policy;
no Approve is asked per merge, and the delivery gate's merge turns and its Approve per merge go (ADR 0666 §10, which
changes ADR 0661 §3 to §5). The operator is asked only where a module's policy says `approval`, and for registrations
and policy changes.
- §37 **The approval is an ask of the runner's.** The runner raises an authorising ask of tier approve as the seat
`operator-channel`'s accepted kind `ask`, under its own name, its `about` the module and the watched branch only, so a newer commit's ask
replaces the older one's (design 46 §10). The warrant ends the step passed; an ask that is declined, expires or is
refused ends it `declined`, and one that is replaced ends it `superseded`. Only a declined `approval` step is asked
again, by the runner's verb `ask-again` (ADR 0666 §10). While it waits the runner
says `wait-held` waiting on the operator, never a stall (ADR 0283).
- §38 **A session merges a pull request.** Any session the tool runner proves, and the operator, merges by calling the seat
`git`'s verb `merge-pull` over the mesh, which merges with the forge tools' account (ADR 0398 §2) at the head the
caller names. It judges that this is still the pull request's head and that the branch's protection refuses a direct
push, the protection read again on every `branch-moved` of the branch, and it judges the head's runs by its modules'
policies: it refuses a head when any run at its build-input fingerprint failed a step a policy marks `required`, and
merges a head whose `required` steps passed or that has no run yet, a failed `optional` or a `bypass` step refusing
nothing; it never waits for a run and never asks an Approve (ADR 0666 §11). The forge keeps only its branch protection.
- §39 **Judged from its own state, never by a call.** The holder of the seat `git` consumes the runner's `step-ended`
through a durable consumer of its own and keeps, in its own state `failed-steps`, each failed `required` step by
module and build-input fingerprint, with the commits it was seen at and the run that failed it, until none of those
commits is a watched branch's head or the head an open pull request names (*The runner's kept data*); so a head
merges while the runner is down, judged on what it already heard (ADR 0666 §11, ADR 0596). A head's fingerprints are
those its runs named for its commit; a step that failed at that fingerprint in any run, a group's or another commit's
of the same content included, refuses it, unless a later run of that same step at that fingerprint, asked again by
the operator or the healers (the runner's `rerun`), passed: that pass clears the failure from `failed-steps` (ADR 0666
§11). The runner's `step-ended` says that the step was a rerun and the caller the runtime proved, and the forge module
clears a failure only for a rerun whose caller is the operator or a healer; a plain pass, or a rerun asked by anyone
else, clears nothing. A run still running is judged by the steps it has ended, since the merge never waits. A refusal names the run, the module and the step, so the session knows what to fix. The gate merges nothing, and its forge merge token is
removed with the checker's buckets and bus account, after the first pipeline after G's delivery has delivered a change
end to end and on the operator's word (ADR 0667 §12; *How milestone G itself is checked and delivered*); the forge bridge hears the landed commit as it hears every commit of a watched
branch.
- §40 **The operator-channel hides no ask.** It keeps design 46's three open asks per asker, never holds the newest back,
and replaces an open ask by the same asker's ask with the same `about` (ADR 0666 §12; design 46 §6).
- §41 **How it is checked.** Whole (forge module, forge bridge): a session's `merge-pull` at its head merges with no run yet,
and with a passed one, and asks no Approve; with the runner stopped a head merges; a head at whose fingerprint any
run failed a `required` step, a head that moved and a branch whose protection was removed since its last move are
refused, each naming why; a failed `optional` step refuses nothing. Whole (runner): an `approval` step is asked last,
a Decline and an expiry each end it `declined` and `ask-again` asks it once more, and a newer commit's ask replaces the
older and ends its step `superseded`.
Live: a declined approval and a fourth ask each reach the operator. Tests 71 and 91.
### Groups
- §42 **Formed from the branch name.** The gate forms a group from a shared branch name carrying its issue number, as it
does today without the fixed list of trunk names (ADR 0666 §13).
- §43 **A member reaches its group by landing.** A member has reached its group when its commit lands on its modules'
watched branch. The forge bridge sets the group on each landed member's commit, reading the members from the seat
`mesh-delivery`'s verb `groups`, and publishes `forge.group.merged` when that verb says every member has (ADR 0666 §13,
which changes ADR 0633 §4).
- §44 **One source revision, one pipeline per branch.** The indexer keeps landed members pending until the group's end and
takes them in together as one source revision of that watched branch, saying `take-in.taken`; the runner starts the
group's one pipeline per watched branch on that event, and a member of a gathered group starts no pipeline of its own
(ADR 0666 §13).
When one member's `required` step fails, none of the group's modules is delivered (research 086, R5).
- §45 **A group that never completes is said.** By ADR 0633 §5's 30-minute bound and its condition; `bridge_group_end_again`
says a group's end again from the gate's group verb, never the gate's `merges` state (ADR 0666 §13, which changes ADR
0633 §5).
- §46 **How it is checked.** Whole (indexer, gate, forge bridge): a group of three repositories, its own packages included,
is one source revision and one pipeline; one member's failed `required` step delivers none; a group with a member that
never lands raises `take-in-waits` at 30 minutes. Tests 67 and 81.
### Dependencies between artifacts
- §47 **Six kinds of edge between artifact references.** The catalog graph's edges run between **artifact references**,
`<module>:<artifact>`, such as `mesh-grants:program`, of six kinds (ADR 0666 §14):
| Kind | B before A | Derived from |
|---|---|---|
| 1 | B published before A builds | a package A's build source imports (ADR 0573 §3) |
| 2 | B published before A delivers | an artifact A's manifest fetches by reference at its start |
| 3 | B delivered before A builds | a build module A is built by, and the toolchain its agreed version names (ADR 0584 §1) |
| 4 | B delivered before A delivers | a provision A requires and B provides, bus state among them (ADR 0614 §5), and a format's reader (below) |
| 5 | B has acted for A's new version | a seat's acting rule (*What ADR 0656 leaves to this design*): a grant, a credential, a verdict, bus state |
| 6 | B runs a version that serves A | a verb or a manifest word A uses and B serves or reads (ADR 0614 §2, §4), the build seats' `kept-artifact` among them |
Each kind is derived from what manifests and seat definitions already say, and declared per artifact in the manifest's
artifact entry, its field `needs`, only where nothing else says it. Today's edges run between modules, and only a
package edge names an artifact; at module level the tool runner and the grants part looked like a cycle, per artifact
they are a chain (`mesh-grants:program`, then `node-tools:runtime`, then `mesh-grants:tools`).
- §48 **Removal runs the other way.** When something goes away the order is reversed: a seat moved to a new holder has its
old holder released before the new one claims (ADR 0666 §14).
- §49 **The edges alone order.** The build and the delivery order by these edges alone; a cycle of delivery edges (kinds 2,
4, 5, 6) is delivered as one step, and a cycle of build edges (kinds 1 and 3) is refused, naming every artifact on it
(ADR 0666 §14; research 086, R17). The cycle rule is the indexer's, in the catalog graph it keeps, so the checking
program's cycle rule goes with the checker.
- §50 **A format's reader first.** A format a running reader cannot read is preceded by its reader, an edge of kind 4 on
every watched branch (ADR 0666 §14): the indexer's manifest validator for a new field of a seat definition or a
manifest, and on each node the node-engine that reads a manifest's new fields before any manifest that writes them
(ADR 0667 §4).
- §51 **How it is checked.** Unit (indexer's graph): a chain per artifact where modules would cycle; two programs needing
each other's new verb are one step; two artifacts each needing the other's new package to build are refused, naming
both; a seat moved to a new holder releases the old first. Live: the tool runner and the grants part delivered in
the order `mesh-grants:program`, `node-tools:runtime`, `mesh-grants:tools`. Test 79.
### A publish rebuilds
- §52 **A version is reserved before the build and released when every artifact is published.** A module's version
is its manifest's `version`, `MAJOR.MINOR`, and a patch the build system gives: the next after the highest version
the catalog holds released for that `MAJOR.MINOR`, 0 for one it holds none of. The builder reserves it when the
module's build starts and passes it to the build of every artifact of the module (§370), so code and packed files
carry it; each artifact published is said as the event `package-published` of the builder's seat `mesh-builds`
(ADR 0666 §15), and the version is released only once every artifact of the module at it is published (§349); only the first watched branch releases (§371). A
failed publish leaves the version reserved, and `builder_publish_again` publishes the missing artifacts under the
same version. The seat `mesh-builds` is new, held once for the mesh, defined in `mesh-delivery-contracts`; the
builder held none until now, and its waits stay on its own stream in this milestone. Why: the operator, 2026-11-10
about 21:40 CET, a design choice of G's part (gaps items 22, 23 and 43). This reserves the number when the build
starts, where ADR 0666 §15 numbers a package at its publication and design 51 publishes a held digest under a new
number: a packed file carries its version, so it must be known before the build; the operator's choice, which a
later research brings the records in line with. How it is checked: test 102.
- §53 **Every dependent is rebuilt against it.** On `package-published` every artifact with a kind-1 edge to the package is
rebuilt against the new version, and the runner, which consumes the event, starts its pipeline; nothing else is
rebuilt, and a change to tests alone publishes nothing (ADR 0666 §15; research 086, R18).
- §54 **A second start writes nothing.** The runner starts a pipeline on two events, the indexer's `take-in.taken` (ADR
0666 §13) and `package-published` (ADR 0666 §15). When both reach it for the same source revision and module, the
second start writes nothing: the runner writes a pipeline's key (watched branch, source revision and module, *The
runner's kept data*) by compare-and-set on its absence, so one revision and module has one pipeline. The design's
choice under ADR 0666 §13 and §15: the key the runner already keeps is the one place a start is judged, so neither
event's producer needs to know of the other.
- §55 **Unread packages refuse.** A build that cannot read the published packages refuses and names the unread state
(ADR 0666 §15).
- §56 **How it is checked.** Whole (builder, indexer): a mesh-sdk merge changing one package publishes one version, and only
the artifacts importing that package rebuild; a merge changing only tests rebuilds nothing; a build whose packages
cannot be read refuses naming the state. Whole (runner): a `take-in.taken` and a `package-published` for the same
source revision and module start one pipeline, the second writing nothing. Tests 70, 80 and 101.
@@ -0,0 +1,343 @@
---
layer: to-be
status: in-progress
design: 47
milestone: G
updated: 2026-11-10
decisions:
- "ADR 0667"
- "ADR 0666"
- "ADR 0664"
- "ADR 0661"
- "ADR 0659"
- "ADR 0656"
- "ADR 0644"
- "ADR 0619"
- "ADR 0596"
- "ADR 0595"
- "ADR 0593"
- "ADR 0573"
- "ADR 0567"
- "ADR 0564"
- "ADR 0548"
- "ADR 0525"
- "ADR 0505"
- "ADR 0448"
- "ADR 0363"
- "ADR 0283"
- "ADR 0240"
---
# 47, milestone G: pipelines per module: any size, the pipeline makes the check, who may say what, health, recovery, tools, kept data, how G itself is delivered, the choices under ADR 0666 and ADR 0667
One file of milestone G's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
[G.md](G.md). Its design lines are numbered across every file of the part and cited as "design 47 G §n".
### Any size
- §57 **A value over the limit is an object.** mesh-sdk's own small object store package (ADR 0595 §9) puts a value over
the bus's per-value limit in the object store beside its state and keeps the object's name in the key; a verb's reply or an event over the
per-message limit carries the object's name (ADR 0666 §16). A replace writes the new object and sets the key by
compare-and-set; the object it replaced stays, as one whose key was deleted does, listed as `key gone` since no key
names it, and only the drop tool removes either, on a person's word: the mesh removes kept data only through `drop`
and `recreate`, each on a person's word (ADR 0595 §4; ADR 0666 §16).
- §58 **One object store per state, granted to its owner.** Each state asked by the template `state` gets its object store
beside it, `<state>-objects`, a template form of ADR 0595 that the bus module provides and the grants part grants to
the state's owner alone (ADR 0666 §16); a foundation part's large values go in an old `objects` section of its own.
Its size is the template's (ADR 0595 §3). An object store holds no space until a value is written to it, so the many
it adds reserve nothing; the few values over the limit (a delivery record, a catalog graph revision list, a test's
output) are estimated, as a guess, at under 1 GiB across the mesh.
- §59 **An object sent is readable by the modules it is for.** A reply's or an event's object is written to the sender's
**sent store**, `<module>_sent-objects`: the bus module plans it, with no manifest field, for every module of the new
form that serves a verb or emits an event, and a foundation part declares it as an old `objects` section
`sent-objects` (ADR 0619 §2). Its cap is the objects template's (ADR 0595 §3), and it keeps an object 7 days, after
which the bus expires it. That age is transport, not kept data: an object sent exists only to carry one reply or one
event, read within its call's bound or its consumer's lag, so its expiry is not a removal of kept data that ADR 0595
§4 holds to a person's word (the design's choice; 7 days is a guess at the longest a consumer lags, read from the
fill tools once G runs). A full sent store is the bus module's `full` and its condition (ADR 0595 §6), and the sender
then refuses the large reply or event loudly, naming the store. The grants part derives from the manifests a standing grant to read them: the
callers its seat definition names for the verbs it serves, and the consumers whose `consumes` declare its events;
no other module may read them (ADR 0666 §16). The grant follows the manifests, so it is written when they change,
never per object. A consumer's reader of
the form is delivered before its producer writes it, an edge of kind 4.
- §60 **Its tools come with the package.** The package serves each module that imports it `<module>_state_objects` (the
objects of each state, with their size, the key that names each or `key gone`, and the fill against its cap),
`<module>_state_objects_drop` (drop the objects whose key is gone, on a person's word as ADR 0595 §4 removes kept
data), `<module>_sent_objects` (each sent object, its size, when it was sent and to which verb or event, its age
against the store's and the fill against its cap) and `<module>_sent_objects_drop` (drop sent objects older than an
age a person names); each drop names who asked and is recorded in the hand-act log.
- §61 **Its cost.** Only the modules that import the package are built with it, so no other module is rebuilt for it: a
package published before its users build (ADR 0573 §2, ADR 0667 §3).
- §62 **How it is checked.** Whole (mesh-sdk, against the real bus): values of one, ten and a hundred times the per-value
limit stored, sent as a reply and as an event, and read back whole by a caller and a consumer the manifests declare,
and refused to a module that declares neither; a replaced large value leaves its old object listed `key gone` beside
the new one, and a key deleted leaves its object listed `key gone`, each removed by the drop tool and by nothing else;
a sent object is readable within its 7
days and expired after; each drop without who asked is refused. Tests 69 and 90.
### The pipeline makes the check, and the checker goes
- §63 **Every step runs on parts built from the change.** Every pipeline step that runs a change's code runs on parts built
from the change's own heads, in the build seat's sandbox, with no network and no bus account (ADR 0666 §17, ADR 0448
§2, §4): the composition step composes each machine's declaration with the composer built from the heads and refuses
a change in which two modules own one path; the build seats' steps run lint and tests. A step whose serving part the
change alters runs from the change's build of it, built within 20 minutes or ending `waiting for a build node` or
`did not build`, the first tier of *The check on the change's own acting parts* made the runner's.
- §64 **The run on request.** The runner's verb `run` takes one or more members, each a module at a named commit, runs them
through their pipelines and delivers nothing, replacing the checker's try (ADR 0666 §18). Its callers are the
sessions, as the agents' bus identities the tool runner proves, and the operator, and nothing else, since a run of a
group builds and publishes its packages' tagged versions (design 51). The runner says `run-started`, the indexer builds
the run's candidate from it, and the candidate's composition step writes no want (ADR 0656 §9); the candidate is
dropped on that run's `pipeline-ended`. A step that could not run ends `could not run`, never as passed. A
composition step for a node that sleeps passes it with a warning (ADR 0593 §9).
- §65 **The runner is an acting part in the checker's place.** The acting rule's step `check` becomes the runner's step
`pipeline` (*What ADR 0656 leaves to this design*): its own change runs on its own new version, a failing new runner
holds while the old one runs pipelines (ADR 0656 §4), and the pipelines in flight when its holder is replaced are
taken up again from its kept state (ADR 0666 §19).
- §66 **What the checker did, and where it goes.**
| The checker's | From G's delivery |
|---|---|
| the merge check, one status `mesh/check` | the pipeline, its result in `pipeline-ended`, the runner's `show` and the delivery record; no status on the forge |
| the try | the run on request |
| the composition check | the composition step, the assigner's |
| the kept verdicts and the carry | the runner's `kept`, which starts empty, and its carry (ADR 0548 §5); the checker's verdicts go with its buckets |
| the checking program: the manifest validator at the heads, the cycle rule, the composer, the rule names | the indexer's validation before take-in; the indexer's cycle rule; the composition step; `widens` in the pipeline's end |
| the `run` ask, published by the checker's account | published by the runner's account and the indexer's (its validation), each with step keys under its own name |
| its buckets and bus account | removed with the gate's forge merge token after the first pipeline after G's delivery has delivered a change end to end, on the operator's one word, the buckets through `drop` after its snapshot, whose restore is tested first (ADR 0667 §12) |
- §67 **How it is checked.** Whole (runner, assigner): a run on request of `feature/1966-x` delivers nothing, and a call of
`run` from another account is refused; a composition step refuses two modules owning one path; a step whose part
cannot be heard ends `could not run`; a node asleep passes with a warning; a runner stopped mid-step takes its
pipelines up again. Live: once the checker is removed no module claims the seat `mesh-delivery-checker`. Tests 64,
84 and 88.
### Who may say what
- §68 **Callers per verb, in the seat's definition.** Each seat definition names, per verb, the callers allowed to call it,
in its field `callers` (holder roles, modules, the operator, the healers), which the grants part reads as its one
source of caller limits; the runner's verbs are the first (ADR 0666 §20). A verb whose definition names no `callers`
admits only the seat's holder roles and the operator, so a field left out opens nothing. It replaces the holder's
trusted config value `callers` of the seat `git` and the package seats (design 51), which no holder set for most
verbs. A format its running reader cannot read, so its reader is delivered first (ADR 0667 §4).
- §69 **A step's result from its holder only.** The runner takes a step's result only from the bus account of that step's
seat holder, naming the commit and the build-input fingerprint; a result from another account, or naming another
commit or fingerprint, is refused and said (ADR 0666 §21).
- §70 **A review gates, once it can.** A code review's result is taken through the verb `review` from the reviewer's bus
account and refused from the commit's author, so a review gates where a policy says `required` (ADR 0666 §22, which
changes ADR 0659 §2). Until a record binds each forge account to its bus identity no policy may say it (*A module's
registration*; issue 1966, note 157).
- §71 **A widening is said, never refused.** A change that alters any part serving a step (the runner, step detection, the
lint rule, a build seat's test runner, the composer), or widens an acting rule, a grant or a credential, says so in
its `pipeline-ended`, its field `widens` naming each. The running runner computes it, from the sources of the change
against those of the watched branch, never the runner built from the change, so a change cannot hide its own
widening; nothing refuses it for that (ADR 0666 §23, the operator, 2026-11-10). The teller passes `widens` on to every
channel, as it does `recovery-merged`. This is what replaces ADR 0656 §8's naming in the Approve ask.
- §72 **How it is checked.** Whole (runner, grants part): a forged step result and an author's own review are refused; a
caller not in a verb's `callers`, and any caller but the holder roles and the operator of a verb with no `callers`,
are refused by the bus; a change widening a grant, and one altering the Go build module's test runner, each name it in
`widens`, computed by the running runner, and are delivered. Tests 85 and 86.
### Health and going back
- §73 **The runner's events.** Each on `mesh.seat.mesh-pipeline-runner.event.<event>.<module>.<branch>.<commit or group>`,
a branch or group name escaped as a key's name is, declared in the seat's definition and published by the runner's
account alone (ADR 0666 §24, ADR 0363 §2):
| Event | Says |
|---|---|
| `pipeline-started`, `pipeline-ended` | a pipeline's start, and its end with every step's result, its test counts, the source revision and `widens` |
| `group-ended` | a group's one pipeline's end, on which alone its wants are written |
| `run-started` | a run on request's start, with its members at their commits |
| `step-started`, `step-ended` | each step's start and end: the step, its status in the policy, its outcome, its build-input fingerprint, its test counts, for a carried result what it was carried from, and for a rerun that it is one and the caller the runtime proved; a bypassed step too |
| `wait-held`, `wait-ended` | a step's wait: on a person (approval, code review), on a build node, on the revision view |
- §74 **What a session hears after its merge.** Between its `merge-pull` and the delivery, a session waits with `mesh_wait`
on the runner's `pipeline-started` and `pipeline-ended` of its module, branch and commit, and then on the status
view's `delivered` of the source revision; a failed head reaches it as `pipeline-failed` (*What holds a delivery*).
- §75 **Nothing stands still unseen.** The watchman times each step's owed progress from `wait-held` and `step-started`,
never by run length; a step or a watched branch's head standing still five minutes is its finding `pipeline-stands`,
raised by the condition keeper and cleared on the step's end, or for a head on its `pipeline-started` (ADR 0564 §2,
§4). A step waiting on a person is said as waiting on that person (ADR 0283), never as a stall; a group waiting for
its members, and a merge behind a pending revision, are governed by their own bounds (ADR 0666 §24). At its start the
watchman seeds its open waits from the runner's `stands`, as it seeds `take-in-waits` from `indexer_pending`.
- §76 **The runner's own health.** Its manifest declares its health check, run outside its process (ADR 0240): the runner
answers `show`, and its durable consumers of `step-ended`, `take-in.taken`, `package-published` and `decided` are
each less than five minutes behind; a failed check names which.
- §77 **The runner waits for its view.** With no revision view it says so in `<module>_first_views` and raises `view-waits`
after five minutes, as every part does (ADR 0656 §6).
- §78 **Going back is one act.** A failing new version holds while the old keeps running (ADR 0656 §4); a return to an
earlier build is one value in the placement, the module's `build` in its placement key, set by a placement proposal
(ADR 0666 §24).
- §79 **How it is checked.** Whole (runner, watchman): a step whose worker dies raises `pipeline-stands` within five minutes;
a head with no pipeline raises it and its `pipeline-started` clears it; a step waiting on the operator raises nothing;
a runner restarted mid-step takes its pipelines up again; its health check fails naming a consumer behind. Whole
(assigner): a placement's `build` delivers the earlier build. Tests 76, 77 and 88.
### A recovery fix is an ordinary merge
- §80 **No recovery merge verb.** A fix that recovers the mesh is merged like any change on a watched branch, by a
session's `merge-pull`, and runs its pipeline; no trusted recovery merge verb is built (ADR 0666 §26). The shape this
design sketched for one (a verb `merge` of the seat `mesh-delivery` with `recovery-callers`) is dropped.
- §81 **Named a recovery, said everywhere.** Its author names it a recovery by the seat `mesh-delivery`'s verb `recovery`
(the commit and why), never by a pull request's text: the gate marks the delivery record `recovery` with the caller
the runtime proves, and says `recovery-merged`, which the teller passes on to every channel (ADR 0666 §26). A widening
it carries is said in its `pipeline-ended` like any other (*Who may say what*).
- §82 **How it is checked.** Whole (gate): a merge named a recovery is marked in its record and `recovery-merged` is said;
a recovery named by a description is not. Test 92.
### The tools
§83 Every new state has a tool that reads it and every new act a tool that starts it by hand (ADR 0666 §25), against the
four lines a module's tools answer; every read tool of a store also answers its fill against its cap:
| Part (seat) | Read everything it holds | Do by hand what it does itself | Recover without help |
|---|---|---|---|
| the runner (`mesh-pipeline-runner`) | `show` (one pipeline whole, its steps, step log and outputs), `list` (the pipelines of a module, a branch or a commit), `stands` (what stands still, since when), `why-carried` (where a step's result was carried from), `kept` (the kept results by digest) | `start` (a delivering pipeline for a watched branch's head), `run` (the run on request), `rerun` (one step again) | `accept` (a failed `optional` step, with why), `cancel` (a pipeline, dropping its asks), `ask-again` (a declined `approval`) |
| the indexer (`mesh-catalog`) | `registrations` (with each one's history); `indexer_edges` (an artifact's edges per watched branch), `indexer_order` (the order of a change, its cycles named), `indexer_catalog_difference` (two revisions); `indexer_pending` (a group with its missing members) | `register`, `policy`, `watch`, `unwatch` (each on the operator's Approve) | `indexer_seed_again` (the first registrations' ask raised again), `indexer_take_in_pending` (a group taken in as gathered), `indexer_drop_pending` (dropped) |
| the gate (`mesh-delivery`) | `source` with a branch (`gate_source`: every branch's source revision) | — | `gate_source_again` (say `source-moved` again for a branch) |
| the forge module (`git`) | `git_failed_steps` (the failed `required` steps it holds, by module and fingerprint, with the run that failed each) | — | `git_failed_steps_drop` (drop one, with why) |
| the grants part (`mesh-grants`) | `grants_callers` (the callers each verb admits, read from the seat definitions) | — | `grants_why_refused` (for an account and a verb, the grant it lacks and the definition's line that leaves it out) |
| the build seats | `steps` (the steps detected for an artifact) | `steps` with `again` (detect again) | `drop` (ADR 0664 §4) |
| the builder (`mesh-builds`) | `builder_reserved` (each module's reserved version, §369); the released versions are the catalog's `versions` | `builder_publish_again` (publish the missing artifacts under the reserved version) | — |
| the assigner (`mesh-wants`) | `assigner_why_not` (why a module is not on a machine yet: the pipeline it waits for, its hold, the placement, the node's last `running`) | — | `assigner_release` |
| the watchman | `watchman_views` (how far behind each part's view is, from each part's `view-waits` and first-view tools) | — | each part's `<module>_first_view_again` |
| the operator-channel | `asks` (with each asker's asks held back) | — | `ask-again` (offer a held-back ask now) |
| every module that imports mesh-sdk's small object store package | `<module>_state_objects`, `<module>_sent_objects` | — | `<module>_state_objects_drop`, `<module>_sent_objects_drop` |
§84 Every recover tool writes its act, who and why in the hand-act log of the seat `mesh-hand-acts`. How it is checked:
each tool answers its whole-module test's case, every store's read answers its fill, and `mesh_describe` reads each
(test 93).
### The runner's kept data, and the build capacity
§85 Each kept form names its section or template, its retention and its cap; a state template fixes its own size (ADR 0595
§3), up to 64 MiB. The numbers are estimates, to be read from the fill tools once G runs: an estimated 20 merges a day
(as *The delivery record*), each starting a pipeline for about 3 modules of its repository whose fingerprint it changes,
and an estimated 2 mesh-sdk publishes a day, each rebuilding about 120 artifacts and starting about 120 pipelines: about
300 pipelines a day, of about 6 steps each.
| Part | Kept data | Section or template | Retention | Cap and growth |
|---|---|---|---|---|
| the runner | `pipelines`: one key per pipeline, keyed by watched branch, source revision and module, its steps, statuses, outcomes, fingerprints, test counts and end count | old `state` section | a pipeline that ended passed on a watched branch, 90 days after its end; any other (failed, superseded, cancelled, a run on request's), 7 days after its end; always while it is its branch's newest for its module; deleted by the runner (§330) | 256 MiB; about 300 pipelines a day of about 4 KiB is at most about 105 MiB at 90 days, under half the cap |
| the runner | `step-log`: one entry per step's start and end, its output, its pipeline and the `kept` digests it wrote or carried, by name | old `streams` section | by its age, 100 days, ten days past the longest retention it ages (§330) | 128 MiB; about 3,600 entries a day of about 0.2 KiB is about 70 MiB at 100 days |
| the runner | `step-outputs`: a lint or test step's output | old `objects` section | 7 days | 1 GiB; about 1,200 steps run a day (the rest carried) of about 50 KiB is about 420 MiB at 7 days |
| the runner | `kept`: a package's passing result per level, by digest, with `last-read`, written by each carry that reads it | old `state` section | 30 days after `last-read` | 128 MiB; a publish changes the digest of about 1,000 importing packages at two levels, so about 4,000 entries a day of about 0.3 KiB, about 36 MiB at 30 days |
| the indexer | `registrations` and its stream `registration-history` | old `state` and `streams` sections | the life of the mesh, never derived again | 64 MiB (*A module's registration*) |
| the indexer | catalog graph revisions, per watched branch | objects in the old form (ADR 0619 §2) | while a record pins it or it is its branch's current | 512 MiB, as *Two graphs, one source of truth*; a second watched branch on a few modules adds a few MiB |
| the gate | `source`: one key per watched branch | its old `state` section, as today | 64 revisions of each key; a branch's key deleted when `registration-changed` says the last registration watching it unwatched it (`unwatch`) | a few KiB |
| the forge module | `failed-steps`: failed `required` steps by module and fingerprint, with the commits each was seen at | state | an entry deleted once none of its commits is a watched branch's head or the head an open pull request names, judged on each `branch-moved` and each pull request's close | the template's 64 MiB; an estimated 50 failed steps a day of about 0.5 KiB, most gone within days, is under 1 MiB |
| every module that imports the object store package | `<state>-objects` beside each state | objects | an object no key names, its key deleted or its value replaced, until `<module>_state_objects_drop` on a person's word (ADR 0595 §4, ADR 0666 §16) | the template's; nothing reserved until written |
| every sender of the new form, and a foundation part by its old `objects` section | `<module>_sent-objects` (`sent-objects`) | objects, planned by the bus module with no manifest field | 7 days, transport (*Any size*) | the objects template's cap; full is the bus module's `full` |
| the grants part, for each seat event a definition keeps | `SEAT_<seat>_<event>`, among them `SEAT_mesh-pipeline-runner_*`, `SEAT_<build seat>_step-ended`, `SEAT_git_branch-moved`, `SEAT_mesh-builds_package-published` and `SEAT_mesh-catalog_registration-changed` | a stream the grants part makes with its durable consumers | the seat definition's age (`keep`), 90 days unless the definition names less | the seat definition's cap (`keep`) |
§86 **The build capacity.** A pipeline runs a module's steps once per commit on a watched branch, carrying what did not
change, where the check ran before the merge and carried after each trunk move; a group runs one pipeline per watched
branch; a second watched branch runs the steps of the modules it carries once more. A mesh-sdk publish asks about 120
lint steps and the test steps of the importing packages, about 240 more, the rest carried; a newer publish of the same
package supersedes the older one's rebuild pipelines, so two publishes close together run the rebuilds once. The first
pipelines after G's delivery run every module's lint and tests once, since `kept` starts empty (ADR 0666 §21): about
120 modules, one round of the build capacity, taken in the `check` stream's order; from then they run only what
changed. Before G's delivery the operator is told the first round's estimated length, read from the checker's last
full check of every module (its verdicts' run times). A step queued on `check` behind the build capacity is said
`wait-held` on a build node and is owed no progress while queued; the watchman raises one finding per build seat,
`build-capacity-waits`, when that seat's oldest queued step has waited 60 minutes, cleared when it starts. A pipeline
whose commit is named a recovery has its steps asked on the build seats' stream `delivery`, ahead of the first round. The steps go on the build seats' stream `check`,
after `delivery` and before `recheck`, within each node's build capacity (ADR 0525 §4, §5), and a run on request on the
same stream. How it is checked: live, the build nodes' time per day in the week after G, read from the build modules'
step keys and the builder's build log, against the checker's last week (test 99).
### How milestone G itself is checked and delivered
- §87 **Under the clauses as they stand.** Milestone G is checked and delivered under ADR 0656 §5 and the clauses it changed
as they hold before its delivery: the acting parts (the indexer, the build modules, the assigner, the grants part,
the node-engine, and the checker, which makes G's own check) act from the milestone's heads, each first in its step,
in the order of their ordering edges; the trunk-only want, the checker and the Approve per merge as ADR 0661 leaves it
govern this delivery, no exemption is asked and no delivery goes ahead of it (ADR 0667 §2, ADR 0644 §1).
- §88 **Its other parts as any module.** mesh-sdk's small object store package is a package published before the modules
that use it build; the manifest validator moves with the indexer; the runner is placed like any module and acts only
from the next change on; mesh-delivery's `contracts` and `sdk` move under its `modules/` folder (ADR 0667 §3).
- §89 **Readers first** (ADR 0667 §4): an edge of kind 4 each, which the delivery plan derives: the indexer's manifest
validator for the seat definitions' new fields (`callers`, `acts`, `subject`, `keep`) before any definition using
them; on each node the node-engine that reads `form` and `catch-up` before any manifest writing them.
- §90 **The stream maker first** (ADR 0667 §5): the grants part, which makes each kept seat stream and its durable
consumers, before the parts that hear a kept stream.
- §91 **The bus module first** (ADR 0667 §6): the bus module, with `<state>-objects`, the sent store and the grant of each
state's object store to its owner alone, before the modules requiring them, the grants part writing that grant from
the milestone's heads.
- §92 **A bus restart is said first** (ADR 0667 §7): a restart of the bus its new version needs is said to the operator
before it starts.
- §93 **A gap is built, not worked around** (ADR 0667 §8): an order the delivery plan cannot derive from the edges is
built in the delivery system within G, never a step done by hand.
- §94 **A node-engine of the version before applies what it can read** (ADR 0667 §9): it applies every want whose
manifests use no field it does not read, and a want that uses one waits, by the reader edge above, for the new
node-engine on that node.
- §95 **The new assigner and the new merge switch on the first registrations** (ADR 0667 §10). The new assigner, which
writes a want only from a passed pipeline, is delivered before the forge module's new `merge-pull`, which asks no
Approve, and before the runner: an edge of kind 4 from `mesh-delivery-assigner` to each, declared in their manifests'
`needs` since nothing else says it (the design's choice: without it a merge made with no Approve could reach the old
assigner, which writes wants from the trunk with no pipeline). Both switch on one fact, the first registrations
written, said as `registration-changed`: until it the new assigner keeps the trunk-only want and the new
`merge-pull` refuses every merge, naming the missing registrations.
- §96 **Until then, the operator merges a fix at the forge** (ADR 0667 §11). Until that fact an ordinary change waits for
it, and a fix, an indexer fix included, is merged by the operator's own hand at the forge (ADR 0661 §3) and
delivered under the trunk-only want still in force; `indexer_seed_again` asks the first registrations again. Before
the milestone's delivery every merge goes as ADR 0661 has it.
- §97 **What is removed, and when** (ADR 0667 §12). The checker's buckets and bus account and the gate's forge merge token
are removed only after the first pipeline after G's delivery has delivered a change end to end (test 63), the runner
then making every check in the checker's place (ADR 0666 §19), and only on the operator's word, asked once for all
three. The checker then leaves the manifest validator's list of foundation parts (ADR 0666 §4) and is no longer
placed, so no running module declares its buckets and they
are orphans `orphans` lists; they go through ADR 0595's `drop` on that word, after the stream snapshot `drop` takes
(ADR 0595 §4, §5, §10), kept 90 days as the delivery records are; a restore from that snapshot is tested before the
word is asked. The runner is on that list from G's delivery.
- §98 **Told to the operator before it starts**: G's own merges are asked as ADR 0661 has them (ADR 0667 §2, §11); the one
ask of the seed registrations; the bus's restart (ADR 0667 §7); and later the one word for the checker's removal
(ADR 0667 §12).
- §99 **How it is checked.** Tests 94 to 97, and 100 for the assigner's edge.
### Choices this design makes under ADR 0666 and ADR 0667
| Choice | Why |
|---|---|
| §100 The registrations in the indexer's old `state` section with their history on an old stream, capped at 64 MiB, kept for the life of the mesh | the indexer is a foundation part (ADR 0619 §1 to §3, ADR 0666 §4); a registration keeps every version with who and on whose Approve, and nothing derives it again |
| §101 The runner a foundation part, its kept data in old sections, on the manifest validator's list | the bus module's own delivery waits on its pipeline (ADR 0666 §4) |
| §102 The want's compare-and-set keyed per module and watched branch | source revisions are kept per watched branch, so two branches' revisions have no order; comparing across them would let `main` refuse `beta`'s want (ADR 0666 §9) |
| §103 A second start of a pipeline for the same source revision and module, on `take-in.taken` and `package-published`, writes nothing, by the pipeline key's compare-and-set | the runner starts on both events (ADR 0666 §13, §15); the key it already keeps judges a start in one place, so neither producer knows of the other |
| §104 A refused new indexer revision holds later merges on its branch until a revert lands | the validation runs after the merge and before take-in (ADR 0666 §6), so the refused revision has landed; taking later merges in past it would deliver them on a graph its own validator refused |
| §105 Each check at its row's level, every requirement R1 to R18 keeping its named test | the record's rows name the levels; the test budget and one check per release bound what runs |
| §106 The approval asked as the operator-channel's accepted kind `ask` on its work queue | the seat has no verb `ask`: an ask is its accepted kind, by the asker's own name (design 46 §10) |
| §107 The gate no foundation part, its `source` in the old section it already has | the bus module's delivery waits on no act of the gate's; only the key's layout changes |
| §108 The verbs `register`, `policy`, `watch`, `unwatch`, `registrations` and the event `registration-changed` on `mesh-catalog` | one verb per trusted act, each its own ask naming what moves; readers follow the event (ADR 0596) |
| §109 The seed of the first registrations proposed as one ask, with the statuses the check judged until then and approval `bypass`, raised again by `indexer_seed_again` | registering is a trusted act (ADR 0666 §3), and one ask for the whole seed is how placement was adopted (ADR 0567); a declined or expired seed must not leave the pipelines stopped with no way on |
| §110 Code review refused as `required` until forge accounts are bound to bus identities | a review is refused from its author (ADR 0666 §22), which cannot be told until then |
| §111 The seat `git`'s read verb `branch` and event `branch-moved`, kept on its seat stream | registering reads a branch's protection through the seat `git` (ADR 0666 §3); a branch moves by a merge or an admitted push; a stream keeps a move said while the bridge is down |
| §112 The watchman's finding `pipeline-stands` for a step or a head still five minutes, cleared by the step's end or the head's `pipeline-started` | the record's five minutes (ADR 0666 §24), one finding for both, timed from the runner's events |
| §113 The runner's finding `pipeline-failed`, the author's for two hours, then the operator's | ADR 0666 §24 with ADR 0505 §5, §6 |
| §114 A module's watched branch and its `build` in the placement key, set by a proposal | a placement names the branch and a return is one value in it (ADR 0666 §6, §24); every placement change goes by a proposal (ADR 0567) |
| §115 The gate's `source.<branch>`, its verb `source` and event `source-moved` | one source revision per watched branch (ADR 0666 §6), read through the seat (G's prepare, the indexer's watch of the gate's `source`) |
| §116 The build seats' verb `steps` and accepted kind `step` on `check`; the assigner's kind `step` on `mesh-wants`; `step-ended` with the node in its subject | steps are asked on the serving seat's work queue (ADR 0666 §7); the `check` stream already orders after `delivery`; a node's account says only its own node's ends (ADR 0363 §2) |
| §117 The outcomes, with `accepted`, `superseded` and `cancelled`; an approval expired or refused ends `declined`, replaced `superseded` | every end a step can have is said as itself (ADR 0666 §10) |
| §118 `approval` asked last, its `about` the module and the branch | the operator approves a commit the mesh already judged, the point ADR 0661 §3 kept in one place; one ask per module and branch, a newer commit's replacing it |
| §119 A superseded pipeline's asks dropped by `drop`, and a pipeline superseded only when its module's fingerprint changed | a cancelled pipeline must leave no ask on a stream (ADR 0664 §4; G's prepare); a module the commit did not change has nothing newer to run (ADR 0666 §9) |
| §120 A group's wants only on `group-ended` | a group is delivered whole or not at all (ADR 0666 §9; research 086, R5) |
| §121 The six kinds derived from existing words, `needs` per artifact only where nothing says it | one form of each fact (ADR 0656 §6); the catalog entry's `needs` already exists from G |
| §122 The cycle rule in the indexer's graph | the graph is the indexer's, and the checking program goes with the checker |
| §123 The builder's seat `mesh-builds` and its event `package-published` | the record has the builder say the publication as an event of its seat (ADR 0666 §15); its waits move only when a later change gives the seat its verbs |
| §124 Each state's object store `<state>-objects` through mesh-sdk's small package, sent objects readable by a standing grant derived from the manifests, and the package's two tools | one object store per state, granted to its owner; the sender's declared callers and consumers read what it sends (ADR 0666 §16); only its users import it, so nothing else is rebuilt |
| §125 The `run` ask published by the runner's account and the indexer's; the verb `run` called by the sessions and the operator only | the steps and the validation run code from the change, in the sandbox only, and each asker reads only its own step keys (ADR 0363 §2); a run publishes tagged packages, so nothing else may ask one |
| §126 The checker's step `check` becomes `pipeline`; `kept` starts empty | the runner is an acting part in the checker's place (ADR 0666 §19); a step's result is taken only from its seat holder (ADR 0666 §21), so no verdict of the checker's is taken in, at the cost of one round of every module's tests |
| §127 The field `callers` in a seat definition replaces the holders' trusted `callers`, a missing field admitting the holder roles and the operator only | the record makes the definition the grants part's one source (ADR 0666 §20); a field left out must open nothing |
| §128 `widens` in `pipeline-ended`, computed by the running runner over every part serving a step, passed on by the teller | a widening is said and nothing refuses it (ADR 0666 §23, §26); a change must not compute its own |
| §129 `merge-pull` judged from the forge module's own `failed-steps`, heard from `step-ended`, any run at the head's fingerprint counting unless a later rerun of that step passed, the protection read again on every `branch-moved` | the record has it judge from the events it consumes, never by a call, so a head merges while the runner is down (ADR 0666 §11, ADR 0596) |
| §130 The new assigner before the new `merge-pull` and the runner, by `needs`, both switching on the first `registration-changed` | a merge with no Approve must never reach an assigner that writes wants without a pipeline (ADR 0667 §10) |
| §131 The forge bridge's finding `branch-unprotected` | a move of a branch whose protection was removed starts no delivering pipeline and is said (ADR 0666 §6) |
| §132 The verb `recovery` of `mesh-delivery` | a recovery is named by its author as a fact the bus keeps with who said it, never read from text (ADR 0666 §26, research 086 R10) |
| §133 No forge status for a pipeline | the step results live on the bus (research 086 R10), shown by the runner and the delivery record; a status would be a second copy outside it |
| §134 The runner's `pipelines` kept 90 days after a passed end on a watched branch, any other 7 days, its step log 100 days by age, its outputs 7, keyed by source revision | a retention the runner judges from its own facts, never from the gate's records (ADR 0596); the delivery record keeps the step events itself (§34), so nothing it traces needs the runner's key; one nothing delivered has no trace to serve after a week; about 300 pipelines a day must fit its caps, so they are 256 MiB and 128 MiB |
| §135 The forge module's `failed-steps` kept until no head it was seen at is a watched branch's head or an open pull request's | an entry judges only a head that can still be merged; once neither names it, nothing can be refused by it |
| §136 The gate's `source.<branch>` deleted when the branch's last watch goes | a branch no registration watches makes no revision, so its key would name nothing |
| §137 The sent store kept 7 days by age, with no person's word | an object sent carries one reply or event and is transport, not kept data (ADR 0595 §4); its readers fetch it within a call's bound or a consumer's lag |
| §138 A replaced object listed `key gone`, as a deleted key's is | no key names it, and one listing lets the drop tool take both on a person's word, as ADR 0595 §4 and ADR 0666 §16 have it |
| §139 The checker's removal after the first end-to-end pipeline, on one word, its buckets through `drop`, the snapshot kept 90 days | ADR 0667 §12 asks one word for all three; 90 days is the delivery records' retention, the longest a trace reads back |
| §140 The pipeline steps on the `check` stream after `delivery` | a delivery's build is never held by a pipeline, as a check never held one (ADR 0525 §4) |
@@ -0,0 +1,376 @@
---
layer: to-be
status: in-progress
design: 47
milestone: G
updated: 2026-11-10
decisions:
- "ADR 0666"
- "ADR 0656"
- "ADR 0648"
- "ADR 0645"
- "ADR 0644"
- "ADR 0641"
- "ADR 0639"
- "ADR 0636"
- "ADR 0633"
- "ADR 0621"
- "ADR 0619"
- "ADR 0618"
- "ADR 0615"
- "ADR 0614"
- "ADR 0603"
- "ADR 0597"
- "ADR 0596"
- "ADR 0595"
- "ADR 0571"
- "ADR 0567"
- "ADR 0564"
- "ADR 0548"
- "ADR 0493"
- "ADR 0441"
- "ADR 0437"
- "ADR 0421"
- "ADR 0363"
---
# 47, milestone G: the delivery record, what the gate owes the forge, the state table, the two graphs and a change's graph difference
One file of milestone G's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
[G.md](G.md). Its design lines are numbered across every file of the part and cited as "design 47 G §n".
## The delivery record, and what the gate owes the forge
### The delivery record
*ADR 0656; ADR 0595, ADR 0596, ADR 0597, ADR 0603 §7, ADR 0493 §3, §11, ADR 0633 §4, §5, ADR 0441 §1, ADR 0548 §8,
ADR 0564 §2, ADR 0363 §2.*
§141 From research 085's milestone the gate, holder of the seat `mesh-delivery`, keeps one **delivery record** per
milestone's delivery, a ledger instance (ADR 0595's template `ledger`, ADR 0597) it alone writes (ADR 0656). It
holds:
- §142 **the group's state**: the heads, the verdicts, the checks and the asks, which `merges` holds today; from milestone
G's delivery the pipelines' `step-started`, `step-ended` and `pipeline-ended` in place of the verdicts, the checks and
the asks, kept as long as the record (ADR 0666 §9);
- §143 **the trace**: the milestone, its issues, its pull requests, their commits, and the graph revisions the delivery
moved between;
- §144 **what happened to each entry on each node**: for every entry of the graph difference, taken in, built, checked,
composed, wanted, running healthy, held (with the hold's reason, so a reader of the record sees why an entry stands
still without asking its holder), failed (with what failed), or away (ADR 0656).
§145 It holds no tiers, and only the gate orders work by it, so it is no second copy of the keys, the objection research
063 had to a stored plan (research 085, Findings 10). Its fields, retention and tools are this design's choices under
ADR 0656.
- §146 **The outcomes arrive as events, through a durable consumer of the gate's own.** The gate's manifest `consumes`
each step event of *What each step says* (below), and `wait-held` and `wait-ended` of each holder. The consumer
resumes from the last event applied; an event applied twice changes nothing; an event is applied only when it comes
from its owner's account; and running healthy is taken from the node-engine seat's `running` event, never from a
have read across the seam (ADR 0596).
- §147 **It ends when every present node runs its entries**, and the gate says `record-ended` on the seat `mesh-delivery`
with the record's milestone and its nodes away. It names the nodes away, each with since when, and ends without
waiting for them, as a node away holds nothing (ADR 0603 §7).
- §148 **A record open too long is a finding.** The watchman writes the finding `record-open` for a record still open 24
hours after its merge (a delivery of the whole mesh takes under an hour, so a day means something stands still) and
clears it on `record-ended`; the condition keeper raises it (ADR 0564 §2). The finding names the entries still held
or failed, read from the record's own events. It is written only while no other condition covers the record: while
an entry of it is held by a wait that raised `acting-part-late`, or a store that holds it raised `full`, that
condition already tells the operator why the record is open, and a second one for the same cause would only be noise.
- §149 **A node away that wakes adds its outcomes.** When it wakes and catches up by its wants (*A change's graph
difference is its delivery*, below), its outcomes reach the record through the same consumer as any other, and the
record shows the node no longer away.
- §150 **An Approve given holds at its heads, until G's delivery.** An Approve the operator gave for a group's heads holds while those heads
stand: a check of the same heads asked again, after a main move or for any other reason, records its verdict in
the record and asks the operator nothing again (issue 1972). The Approve is withdrawn only as ADR 0441 §1 has it,
when a member stops being mergeable, and a carried verdict is read as current (ADR 0548 §8). From G's delivery no
Approve is asked per merge; an `approval` step's answer is the runner's, kept in the record as its step's end
(ADR 0666 §10).
- §151 **From G's delivery, a record for every landed merge.** A session merges through the seat `git` and the gate merges
nothing, so every merge is one the gate did not make: the gate opens a record for each source revision of a watched
branch the indexer takes in, a group's members in one, and `forge-made` no longer marks a record apart. A merge its
author names a recovery is marked `recovery` (*A recovery fix is an ordinary merge*).
- §152 **A small fix has a record of its own.** A small fix is a milestone of one issue (ADR 0493 §3), so it has a
delivery record like any milestone; nothing is merged outside a released milestone (ADR 0493 §11).
- §153 **It pins the graph revisions it points at.** The gate says, as the seat `mesh-delivery`'s events `pinned` and
`freed`, which catalog and assignment graph revisions a record starts and stops pointing at, and as
`heads-replaced` that a candidate's heads were replaced or its pull request closed. Only the gate's account may
publish them (ADR 0363 §2). The indexer and the assigner hear them through a durable consumer each, declared in
their manifests' `consumes`, which resumes from the last event applied after a restart, so a `freed` said while one
of them was down is still applied; neither reads the gate's state (ADR 0596; *Two graphs, one source of truth*,
below).
- §154 **A record is kept for 90 days by default**, the gate's setting `record-retention`. Ninety days covers every trace
the operator has asked of a past delivery so far, which went back weeks, never months; the setting can keep records
longer. When the retention removes a record, the gate says `freed` for each revision it pinned.
- §155 **Its size, its cap and its growth.** A record's state of 30 modules on four nodes is about 30 KiB, against the
bus's 256 KiB value limit (research 085, Findings 8). The ledger keeps every operation beside that state: 30 modules
on four nodes with seven outcomes each is about 840 outcome operations a record, at about 0.2 KiB each about 170 KiB,
so a record costs about 200 KiB with its snapshot. At an estimated 20 deliveries a day (a guess from the days of
research 085, not a measurement) the ledger grows about 4 MiB a day, about 360 MiB at the default retention; its cap
is 768 MiB, twice that, so a busier month than estimated still fits. Removing a record at its retention removes its
operations and its snapshot with it, so the ledger's size follows the retention, not the mesh's age.
- §156 **The switch carries today's state in, once.** At the new gate's start, `merges` and every group in flight become
records, and from then on the gate writes `merges` no more; `turns`, which nothing writes while the check gates no
merge, is dropped with the hold (*Nothing merges into a repository under check*). The switch is safe to run
twice: a group in flight becomes a record keyed by its milestone and heads, and a switch that finds that record
already there leaves it as it is, so delivering milestone G again after a revert makes no second record and asks
nothing again. A revert of the gate is the delivery system's restore of its kept data (*A module's kept data on the
bus, backed up and restored with its delivery*).
- §157 **The forge bridge asks the seat for a group.** It reads a group's members from the seat `mesh-delivery`'s verb
`groups`, never the gate's `merges` state, both to set the group on each merged message and to publish a group's
end again (ADR 0656, which changes ADR 0633 §4 and §5; ADR 0596). Its account holds no grant to read `merges`.
- §158 **What the gate owes the forge is said, not watched, and a merge made at the forge has a record too** (*What the
gate owes the forge*, below).
- §159 **Its tools**, against the four lines a module's tools answer:
| Line | The gate |
|---|---|
| read everything it holds | `gate_record` (one record whole: the group's state, the trace, each entry's outcome per node, the nodes away), `gate_records` (every record with its fill against the value limit, and the ledger's fill against its cap), `gate_consumer` (its durable consumer: the last event applied per family, the events waiting, the age of the oldest) |
| do by hand what it does itself | `gate_record_repair` (for one record, asks each owner for the outcome of each entry missing one through that owner's read verb: the indexer's `take-in` read, the builder's build read, the checker seat's check read (from G's delivery the runner's `show`), the seat `mesh-wants`'s `entry`, and the node-engine seat's verb `composition` of that node; applies the answers as the consumer would) |
| recover without help | `gate_record_end` (end a record left open, a node gone for good or an entry that never runs, with the reason, recorded in the hand-act log of the seat `mesh-hand-acts`) |
| one seat, many tools | the seat `mesh-delivery`'s verbs, with `groups` answering a group's members and the acts said for it |
- §160 **How it is checked.** In the gate's whole-module test: the gate stopped and restarted in the middle of a delivery
leaves the record complete with no outcome counted twice; the events `pinned`, `freed`, `heads-replaced` and
`record-ended` are said; a `freed` from an account other than the gate's is refused by the bus; a group approved
before the switch is not asked again after it, nor after milestone G is delivered again following a revert; a record ends once every present node runs its
entries, naming the nodes away; a held and a failed entry are kept with their reason; a record open past 24 hours
raises `record-open`, cleared by `record-ended`; a node away that wakes adds its outcomes and is no longer shown
away; a group's heads approved and checked again ask the operator nothing again; a small fix's merge gets a record
of its own; a record past its retention is removed and frees its revisions; the tools read a record, list the
records with their fill, and a repair completes a record missing an outcome through the owners' read verbs. In the
forge bridge's whole-module test, a group's members are read from `groups` and its end published again from it, and
a read of `merges` by its account is refused. Live: one call of `gate_record` traces an issue of the registry
milestone to each node's running build, also after six later merges; a node away is named with since when and its
outcome taken on waking; a record of 30 modules on four nodes stays under 256 KiB; a group checked again at old
heads after a main move is not asked of the operator again (issue 1972).
### What the gate owes the forge
*ADR 0596 §1, §2, ADR 0656 §7, ADR 0437 §8, ADR 0441 §5, ADR 0633 §1, §4, ADR 0363 §2, ADR 0564 §2; from research 085's
milestone, this design's choices under ADR 0596 and ADR 0656 §7.*
§161 The forge bridge today performs what the gate's states `merges` and `owed` ask (a merge, a status, the delivery's
view, a comment, a line on the commit's note) by watching those keys (ADR 0437 §8), and the forge module writes the
checker's `mesh/check` from a watch of the checker's state `owed`: reads of another module's bus state that ADR 0596
§2 ends when their owner moves. From research 085's milestone:
- §162 **Every act is an event, under one id.** The gate says each act it owes as the event `owed` of the seat
`mesh-delivery`, on `mesh.seat.mesh-delivery.event.owed.<repository>.<number>`, carrying the act, the pull request,
the head and an id; the checker says its status the same way, as the event `owed` of the seat
`mesh-delivery-checker` on `mesh.seat.mesh-delivery-checker.event.owed.<repository>.<number>`. Only the owner's
account publishes each (ADR 0363 §2). The subject per repository and pull request lets the bridge, a person and a
test read one pull request's acts alone. The seat events are kept on each owner's stream `owed`, 7 days and at most
64 MiB (an estimated 20 deliveries a day, with about 15 acts of about 1 KiB each, is about 2 MiB over 7 days).
- §163 **Every act is safe to repeat at the forge.** A status and the delivery's view replace what stands; a merge of a
pull request already merged at that head is answered performed; a comment and a line of the note carry the act's
id, and the seat `git`'s verb skips an id the pull request or note already holds. This is chosen over recording the
id before the act: an id recorded and then not performed (the bridge stopped between the two) would be lost, while
an act repeated changes nothing. The bridge's own state `performed`, a key-value state in the new form (ADR 0595),
form 1, one key per id with the outcome and when, kept 7 days as the stream is, its size the one its template fixes
(ADR 0595 §3), is therefore a
saving and a read, never what keeps an act from happening twice.
- §164 **Every outcome is said, and the gate records it.** The bridge says each act's outcome on its own stream `forge` as
the event `owed.ended`, with the id and one of `performed`, `refused` (the forge's own words), `could not be
performed` (the forge did not answer within the call's bound, with the error) or `undecodable` (an act it cannot
read, with why): an act it cannot decode is said, never only logged. The gate hears the stream `forge` through its
durable consumer, writes the outcome into the delivery record, and says an act's id is answered only once an
outcome is recorded. The checker does the same for its own acts: it hears `owed.ended` for its own ids, records each
outcome in its own state (it watches only its own state), says again at its start, under the same id, every act of
its own still unanswered, and lists one unanswered past 15 minutes in its own stalled read.
- §165 **What is unanswered is said again, and stalls by a bound.** At its start the gate says again, under the same id,
every act its records hold unanswered. An act unanswered 15 minutes after it was said is listed by `stalled`, which
the condition keeper raises as the stalled line (ADR 0421 §7, ADR 0564 §2): fifteen minutes is many times a
forge call's time, and short beside the check's hour.
- §166 **A group's merges follow one another, until G's delivery.** The gate says a group's next `merge-pull` only once the previous member's
merged message is heard (ADR 0441 §5), so a member the forge refuses holds the rest, and none is merged ahead.
- §167 **From G's delivery the gate owes no merge, and the checker nothing.** A session calls `merge-pull` itself (ADR 0666
§11), and a group's members land one by one, the group ending when every member has (*Groups*); the checker's `owed`
goes with the checker, and the runner owes the forge nothing, a pipeline's result living on the bus. The gate still
owes the delivery's view, a comment and the note's line, performed by the forge bridge as above.
- §168 **The bridge catches up from the seat.** At its start the bridge resumes its durable consumer and also reads
`groups`, which answers, per group, the acts the gate said with their ids and their recorded outcomes; an id said
and not answered is performed. Its tools: `bridge_owed` (the ids it performed with their outcomes, and its
consumer's backlog: the last event applied, the events waiting, the age of the oldest), `bridge_owed_again`
(perform one id again now) and `bridge_owed_drop` (drop one id with its reason, written in the hand-act log of the
seat `mesh-hand-acts`, and said as `owed.ended` with the outcome `dropped`).
- §169 **The switch carries what is owed.** At the new gate's start (*The switch carries today's state in, once*) every key
of `owed` and `merges` the old bridge has not performed becomes an act of its record, with an id made of the key and
its revision; the new bridge counts as performed every id whose key and revision the old bridge's own bookkeeping
names, so nothing is done twice and nothing dropped. A merge handed to the forge during the switch is such an act:
its merged message finds the record holding it, so it opens no `forge-made` record.
- §170 **A merge made at the forge has a record too.** A merge the forge reports for which no record holds a `merge-pull`
of that pull request at that head (a person merged it in the forge's own page, as on 2026-11-07 and 11-09) is taken
in like any other merge (*Taken in by the indexer it names*), and the gate opens a delivery record for it, marked
`forge-made`, with no Approve, so its trace and its outcomes on the nodes are kept like every delivery's and no
later merge waits behind a merge the gate never heard. The gate says it as the delivery's `transition` with the why
`forge-made`, which the teller passes on to the operator (the operator, 1921's note of 2026-11-07: "a merge made in
the forge is taken in like any other").
- §171 **How it is checked.** In the forge bridge's whole-module test: an `owed` said while the bridge is stopped is
performed once after its restart; the bridge stopped between an act and its `owed.ended` performs it again on its
restart and the forge holds it once (the comment and the note by their id); an act said twice is performed once; an
undecodable act is said `undecodable`; `bridge_owed`, `bridge_owed_again` and `bridge_owed_drop` answer, the drop
writing the hand-act log; its account cannot read the gate's or the checker's state. In the gate's: an act left
unanswered is said again at the gate's start under its id and listed by `stalled` after 15 minutes; a group's second
`merge-pull` is said only after the first member's merged message; the switch with a merge handed and not yet
merged makes no `forge-made` record; a merged message with no record's merge opens a `forge-made` record, said as
`transition` with why `forge-made`, and a later merge in the same repository is taken in behind it. Acceptance
tests 53 and 51.
## The state table, from milestone G's delivery
§172 **From milestone G's delivery the gate keeps no merge states.** With no check before a merge and no Approve per merge
(ADR 0666 §10, §17), nothing is `proposed`, `ready`, `rejected` or `held` before a merge: a commit's states are its
pipeline's steps, kept by the runner (*Pipeline steps and the policy*). The table, the gate's `table`, `recheck` and
`close` and the one key per pull request go with the check; `stalled` lists the acts owed to the forge past their 15
minutes and the records `record-open` names.
## Two graphs, one source of truth
*ADR 0656, which supersedes ADR 0645 to ADR 0648; ADR 0595,
ADR 0596, ADR 0603 §2, §6, §7, ADR 0615 §1 to §6, ADR 0621 §1, §2, ADR 0614 §3, ADR 0567 §5, ADR 0571 §8, ADR 0614 §4, ADR 0618 §2, ADR 0619 §1 to §3, ADR 0636 §1,
§3, §4, §7, ADR 0639 §7, §8, ADR 0564 §2, ADR 0363 §2.*
§173 From research 085's milestone. One graph answered two questions, which modules exist and which version runs where,
and one module running as several placed versions would have given one entry two shapes and one key two writers; two
graphs answer them, the second computed from the first, so there is one source of truth (ADR 0656; research 085,
Findings 11). How each is kept, read and retained is this design's choice under ADR 0656.
```
manifests ──► indexer (mesh-catalog) ──► catalog graph revision ──┐
├──► assigner (mesh-wants) ──► assignment graph revision
placements (mesh-module-assigner) ───────────────────────────────┤ │ │
node capabilities (node-engine seat) ────────────────────────────┘ │ └─► wants, from a trunk revision only
▼
a change's assignment graph − the current one = its graph difference = its delivery
```
- §174 **The catalog graph is the indexer's.** The indexer, holder of the seat `mesh-catalog`, keeps the modules as their
manifests declare them; it is today's module graph, and *module graph* stays its other name (ADR 0656). At each
revision it holds one entry per module: its bases, its packages, the toolchain version and recipe version of the
build module that builds it as ADR 0603 §2 has them, its provides and requires, its invokes and serves, and its
fingerprint, with the rules the seats declare (*An acting part's new version acts first*, below).
- §175 **The assignment graph is the assigner's, computed and never written by hand.** The assigner, holder of the seats
`mesh-module-assigner` and `mesh-wants`, computes the module versions placed on nodes, with the edges between
versions, from the catalog graph, the placements and the nodes' capabilities, and nothing else writes it
(ADR 0656). Each entry is one module version on a node; its edges are provisioning, contribution, and the acting
parts' versions that are to act on it (ADR 0656), whose rules and versions come in with the catalog graph. It is
kept, but it is no stored plan: it has one writer, no part orders work by a stored plan, and any revision is computed
again from the inputs it names and compared with the one kept, by a tool (below), so a kept revision is a checked
derivation, never a second source of the kind research 063 removed (research 085, Findings 5).
- §176 **Each graph is kept per revision, and each revision names its inputs** (ADR 0656). The indexer keeps a catalog
graph revision for each source revision it takes in; the assigner keeps an assignment graph revision for each change
of its inputs, naming the catalog graph revision, the placements and the capability readings it was computed from.
Both parts are the foundation (ADR 0619 §1), so both keep their revisions as objects declared in an `objects`
section in the old form, each with a cap it declares there, never in the new form (ADR 0619 §2), and neither waits
on the bus module to start; the manifest validator refuses either manifest that declares them in the new form
(ADR 0619 §3). An assignment graph revision is announced by an event of the seat `mesh-wants` and served by its
verbs. This replaces ADR 0603 §2's one key per module with five past values as the graph's form (ADR 0656, which
changes ADR 0603 §2); the keys are written no more, and a revert of milestone G restores them from their backup
(*Reverted*, below).
- §177 **A revision is made by a merge, and also with no merge.** The indexer makes a catalog graph revision when it
takes a source revision in. The assigner makes an assignment graph revision on each new catalog graph revision, on
the seat `mesh-module-assigner`'s event `assignments-changed` (ADR 0567 §5, ADR 0641), and on the node-engine seat's event
`capabilities-changed`, which a node-engine says when the capabilities it states in its node record change
(ADR 0614 §4), so the assigner follows an event and never reads a node record across the seam (ADR 0596). A
placement change is traced like a merge. At its first start with no revision kept, the indexer takes in the head the
gate's source names for every repository by its catch-up path and keeps that as revision 1, and its verb `revision`
answers that it waits until then (lead-47's ruling in G's prepare: a first start has no merge to make a revision).
- §178 **A revision is kept while a record pins it or it is current.** A revision of either graph, and the input revisions
it names, is removed when no delivery record pins it and it is not current: neither trunk's newest revision nor the
newest of an open candidate. Pins are counted per revision, so a revision two records point at stays until both
have said `freed`. The indexer and the assigner remove one only on applying `freed` or on a revision ceasing to be
current, never on a timer and never by reading the gate's state (ADR 0596; *The delivery record*, above). A trace
must read every revision it moved between, and a revision neither pinned nor current is read by nobody.
- §179 **An unchanged entry is stored once.** A revision is kept as its list of entries' digests, and each entry as an
object of its own named by its digest, so an entry that two revisions share is stored once; an entry object is
removed when no kept revision lists it. Consecutive revisions differ by the few entries a delivery moves, so this
keeps the growth to what changes. It is chosen over a larger cap because whole revisions would grow with every
revision whatever changed, and a cap would only delay the same fill.
- §180 **The caps and the growth** (estimates, to be read from the fill tools once the milestone runs). A whole assignment
graph revision of about 120 modules on four nodes is under the bus's 256 KiB value limit (its unit test), and a
catalog graph revision of about 120 entries about 120 KiB. A record pins the revisions before and after its
delivery, and consecutive records share one, so at an estimated 20 deliveries a day about 20 revisions of each graph
a day stay pinned. A delivery moving 5 modules on four nodes adds about 20 assignment entries of about 1 KiB and a
list of about 15 KiB, and 5 catalog entries and a list of about 4 KiB: about 0.7 MiB a day of assignment graph and
0.2 MiB of catalog graph, about 63 MiB and 18 MiB at the records' default retention of 90 days. The caps are 512 MiB
for each, many times the steady state. Placement-only and capability-only revisions are pinned by no record and go
when they stop being current.
- §181 **A store filling is said before it is full.** The indexer, the assigner and the gate each say their fill against
its cap in their read tools, and the event `filling` of their seat when a store passes 80 % of its cap; the watchman
writes the finding `store-filling` naming the part and the store, the condition keeper raises it (ADR 0564 §2), and
it clears when the store falls below 70 %. A full cap refuses loudly, naming the part and the store: the indexer
keeps no new revision and says the merge pending with the reason `objects full`, the assigner keeps its last
revision and writes no new want, and the gate opens no new record and holds the merge; each says it as the event
`full` of its seat, which the condition keeper raises as urgent. When a removal brings the store back below its cap,
the part says `room` of its seat, takes the refused work up again (the pending merge, the next revision, the held
record) and the condition clears; a condition that never clears would hide the next fill. Nothing is dropped to make
room: a removal is only the rule above, and the setting `record-retention` or a larger cap is the operator's.
- §182 **What happened is not in the graph.** An entry says what is to run and what it waits on; whether it was built,
wanted or runs healthy is said by the parts as their events and kept in the delivery record (ADR 0656).
- §183 **The want stays the one record a node reads.** The assigner writes `want.<node>.<module>` from a trunk
revision's assignment graph only; a node-engine reads its want, never the assignment graph, and the have stays what
it runs (ADR 0656, which changes ADR 0571 §8).
- §184 **From G's delivery, per watched branch and between artifacts.** The catalog graph is kept once per watched branch,
each revision naming its branch, and its edges run between artifact references, of the six kinds of *Dependencies
between artifacts* (ADR 0666 §6, §14). The assigner computes a node's entries from the catalog graph of the branch its
placement names, and writes a want from a revision of that branch whose `required` steps passed, in place of a trunk
revision's alone (ADR 0666 §9, which changes ADR 0656 §2).
- §185 **Reverted.** Only the new form is written: the indexer, the assigner and the gate keep nothing of ADR 0603 §2's
keys or of `merges` and `turns` beside the new forms, since nothing reads them after milestone G. A revert of
milestone G is a change like any other, checked and delivered, and the delivery system restores what it must
(*A module's kept data on the bus, backed up and restored with its delivery*, under *A backup before the apply*).
Milestone G changes the form of these kept data, and raises their `form` (a kept data declaring none reads as form
0, so G's own move takes their restore points):
| Part | Kept data before G (form 0) | After G | Restored at a revert |
|---|---|---|---|
| the indexer | the state `modules` (ADR 0603 §2's one key per module) and its durable consumer's position on the forge bridge's stream `forge`; the states `holds`, `engine-reads` and `hold-bounds` of its mesh-wide hold | catalog graph revisions as objects, form 1; `modules` no longer declared, nor its tool `indexer_read_modules` or its view; the mesh-wide hold, its three states and its tools `indexer_holds` and `indexer_engine_reads` gone, the wait per node being the assigner's (*Composing waits per node, by the assigner*); every reader of it reading the catalog half (*Every other reader of which modules exist*, under *The revision view*, below) | yes: `modules` and the hold's three states as they stood at G's delivery, and the consumer's position |
| the gate | the states `merges` and `turns` | the delivery record's ledger, form 1; `merges` and `turns` no longer declared | yes: `merges` and `turns` as they stood at G's delivery |
| the assigner | the wants, written from the indexer's `modules` | the same wants, form 0, written from the assignment graph; the assignment graph revisions as objects, form 1 | no |
The wants keep their form: their keys and values are unchanged, only what the assigner computes them from changes,
so G raises no `form` on them and a revert restores none. Restoring the wants would send nodes back to older
fingerprints until the reverted assigner computed them again; leaving them, the nodes keep what runs and the reverted
assigner writes them again from the caught-up indexer. The assigner's placement and every other kept data of the
three keep form 0 and are never restored, so nothing decided since (a placement, a verdict, the source revision) is
set back. The restored `modules` is as it stood at G's delivery, so a module added since is missing from it until
the reverted indexer takes in its next source revision, and a reverted reader that learns which modules exist from
`modules` does not name it until then. What a reader granted since stays: the forge module's write grants on a
repository it learnt of from the catalog half are kept, since it grants writes and takes none away, so a revert
costs no repository its account's writes.
### A change's graph difference is its delivery
- §186 **The difference names everything a plan named.** For a change (a pull request's heads, a delivery group's
heads, or a merge), the indexer gives its catalog graph and the assigner its assignment graph. Compared with the
current revision, the difference names the new versions, the moved edges, the touched nodes and the order, read off
the edges, and no plan is stored (ADR 0656). The assigner serves it by the seat `mesh-wants`'s verb `difference`,
for two revisions of the assignment graph or for a candidate against trunk. ADR 0603 §6's tiers, as ADR 0633 §5
changes it, are a view worked out from that difference (ADR 0656, which changes ADR 0603 §6), read through
`difference`, with the waits and holds read through their owners' tools and the pending revisions through
`indexer_pending`.
- §187 **The preview is a candidate's difference.** Issue 1874's plan preview of a group before its merge is its
candidate's difference, read by one call of `difference`, and needs no code of its own: a candidate's graphs are
computed for its check anyway, so the preview costs nothing more.
- §188 **A changed fingerprint with no difference is refused by name.** When a module's fingerprint in the change
differs from the running one while the difference is empty, the assigner refuses it, naming the module, and the
check fails naming it.
- §189 **A candidate's graphs are kept apart, and dropped with its heads.** A candidate's two graphs are computed per
check, kept apart from trunk's, and dropped on the gate's event `heads-replaced`, said when the candidate's heads
were replaced or its pull request closed. A candidate costs a computed graph per check.
- §190 **Only a trunk revision writes wants**, whether a merge taken in or a placement or capability change made it; a
candidate's graph writes none (ADR 0656). From G's delivery a want comes from a revision of the watched branch a
placement chose whose `required` steps passed, and a candidate is a run on request's: the indexer builds it on the
runner's `run-started` and drops it on that run's `pipeline-ended`, the gate's `heads-replaced` no longer making
candidates (ADR 0666 §9, §18).
- §191 **Each part acts on its own entries.** The builder, the build modules and the grants part each act when their own
entries in the new revision differ from what they run (ADR 0656), reading them through the seat `mesh-wants`'s verbs
and events, never its bus state (ADR 0596), and naming no other module (ADR 0656). The node-engine acts on its want
alone, as it does today: the want is the one record a node reads, and handing every node the assignment half would
have each node read every other node's placements.
- §192 **A node asleep catches up when it wakes.** A node away holds nothing and catches up by its wants (ADR 0603 §7);
a want's new form reaches only a node-engine that says it reads it (ADR 0614 §4, ADR 0618 §2).
- §193 **No delivery goes ahead of a change.** A change is delivered as its own difference, its acting parts' new versions
first in their own steps (ADR 0656); the one exception is the delivery before research 085's milestone (*The
bootstrap delivery, and the one milestone after it*, under *Milestones*; ADR 0644).
@@ -0,0 +1,354 @@
---
layer: to-be
status: in-progress
design: 47
milestone: G
updated: 2026-11-10
decisions:
- "ADR 0667"
- "ADR 0666"
- "ADR 0663"
- "ADR 0660"
- "ADR 0656"
- "ADR 0644"
- "ADR 0641"
- "ADR 0639"
- "ADR 0636"
- "ADR 0635"
- "ADR 0625"
- "ADR 0621"
- "ADR 0619"
- "ADR 0615"
- "ADR 0614"
- "ADR 0603"
- "ADR 0596"
- "ADR 0584"
- "ADR 0564"
- "ADR 0548"
- "ADR 0525"
- "ADR 0498"
- "ADR 0493"
- "ADR 0448"
- "ADR 0441"
- "ADR 0404"
- "ADR 0363"
---
# 47, milestone G: the revision view, what ADR 0656 leaves to this design, the choices under ADR 0656, what each step says and their tools
One file of milestone G's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
[G.md](G.md). Its design lines are numbered across every file of the part and cited as "design 47 G §n".
### The revision view
- §194 **A pair, each half served by its one owner** (ADR 0656). For a trunk revision, or for a candidate's heads before
any merge, the indexer serves the catalog half by the seat `mesh-catalog`'s verb `revision`: the catalog graph, the
heads, the seat definitions, the manifests' verdicts and the fingerprints. The assigner serves the assignment half by
the seat `mesh-wants`'s verb `revision`: an assignment graph revision, named by its own revision and naming its
inputs, the catalog graph revision, the placements and the capability readings. A part's view for the current
revision is the newest assignment half and the catalog half it names. `seat-definitions` stays the seat list's verb
(ADR 0636 §4), and the catalog half carries the same definitions at its revision.
- §195 **Every part takes a first view, then follows the events.** The checker, the builder, the grants part and the
indexer's own later passes take a first view from the two verbs and then follow the two seats' events, never a list
compiled into their build nor another module's bus state (ADR 0656, ADR 0596). The node-engine reads only the catalog
half, for the seat definitions it composes with, and its want; it never reads the assignment half (*Each part acts on
its own entries*, above). Of the view the assigner reads only the catalog half, never its own output back; its other
inputs stay the placements and the capabilities (ADR 0656). A running part acts only on a trunk revision's view; a
candidate's view is read only by the parts that judge a candidate, inside the check its manifest validator and
composer, and the indexer's candidate pass (ADR 0656, which changes ADR 0636 §4 in that the candidate pass joins
them). From G's delivery a running part acts on a revision of a watched branch as on a trunk revision, and a
candidate's view is read only by a run on request's steps and the indexer's candidate pass (ADR 0666 §6, §18).
- §196 **Every other reader of which modules exist reads the catalog half, in the same milestone.** From milestone G the
indexer declares no state `modules` and serves neither its tool `indexer_read_modules` nor a view of it (*Reverted*,
above), so every module that learns from it which modules exist moves in milestone G, not after: the watchman (its
manifest findings), the status view (`view_reach`), the forge module (which repositories its account writes), the
holders of the seats `mesh-config`, `mesh-provisioner` and `mesh-self-check`, the claude-code module and the tool
runner. Each takes a first view of the catalog half by the seat `mesh-catalog`'s verb `revision` and follows its
event `catalog-revision`, through `meshcatalogclient` in Go or the seat's generated TypeScript contract in the forge
module, names the seat and never the indexer, and keeps no list of its own (ADR 0656 §6, ADR 0596 §2; ADR 0615 §1,
under which every reader of the indexer's state moves in one milestone). A reader that misses a `catalog-revision`
(a gap in the revisions it heard) asks `revision` once more, said in its log (ADR 0615 §5). The design's choice
under ADR 0656 §6: one form of the fact, never `modules` kept beside the catalog graph for these readers, which
would be a second source of the same fact. How it is checked: test 61.
- **The forge module's tools come from mesh-sdk's TypeScript side.** mesh-sdk's TypeScript side has no view
today; milestone G adds there a view follower with its read and ask-again tools, beside the proved caller, a
verb's `callers` and a seat's publish, so the forge module, reading through the seat's TypeScript contract,
answers `<module>_first_views` and `<module>_first_view_again` as the Go parts do from `go/views`, with no
follower or tool of its own. Its cost: a release of the TypeScript side rebuilds every TypeScript module, which
the delivery carries like any change of a package its users build in.
- **The order is the module graph's, and the foundation's own rule where the graph has no edge.** Six of the
readers declare the verb in their `invokes`, so the served-verb edge delivers none of them to any node before a
build serving `revision` runs (ADR 0615 §2, ADR 0614). Two are left out of the graph's order (ADR 0614 §3, ADR
0615 §2): the tool runner, a foundation part, and the forge module, on a cycle with the indexer, which reads the
forge through the seat `git`. For both the order is carried by ADR 0615 §4 and §6: the owner answers at once from
what it holds, and a reader started before it waits, saying so. The tool runner asks `revision` of the indexer's
own runtime, never through itself, the tool's `callers` list naming it (ADR 0663, which changes ADR 0621 §1, §2 and
ADR 0615 §3; accepted); the forge
module answers the indexer's reads through the seat `git` before it has a first view of its own, so neither waits
on the other.
- **With no view, a reader waits; it never reads "no modules".** All eight follow *A part with no view says it
waits* (below): an empty or missing view is never taken as a mesh with no modules, each says `view-waits` after
five minutes, and once it has a first view it keeps working on what it heard while the indexer is down (ADR 0615
§6).
- **A candidate's revision moves no reader.** `catalog-revision` says whether it carries a trunk revision or a
candidate's, and a candidate's changes nothing in any of these readers; the forge module grants no write before
its first view and none from a candidate's revision (ADR 0656 §6: a running part acts only on a trunk revision's
view).
- §197 **The trunk's heads come from the catalog half.** The checker takes the trunk heads a check merges onto from the
catalog half, which carries the heads, and never reads the gate's state `source` (ADR 0596 §2); with the hold and
the turns removed it reads nothing of the gate at all (*Nothing merges into a repository under check*).
- §198 **The indexer reads every definition before it judges.** At its start the indexer reads the seat definitions of
every contracts module's trunk through the forge (the seat `git`'s verbs) before it judges a manifest or answers
`seat-definitions`, and only then follows the forge bridge's stream; a definition merged while it was down is
therefore never judged against a list that lacks it. The design's choice under ADR 0636 §1 and §4, as the operator
asked it (1921's note of 2026-11-07: "the indexer reads its seat definitions at start"). How it is checked: in the
indexer's whole-module test, started with a definition on a contracts trunk that no event announced, the first
manifest claiming that seat is judged with it.
- §199 **Who holds a seat is applied by one rule, from what each node runs.** The node-engine and the grants part decide a
seat's pass by mesh-sdk's `SeatsToPassOn` (ADR 0660 §3), reading the manifest of the build each assignment runs
(ADR 0660 §2). What each node runs is heard, never asked: each part keeps it from the node-engine seat's events
`running.<node>.<module>` (*What each step says*), through a durable consumer of its own declared in its `consumes`,
so a pass is decided with no call to a node that may be away. The seat's stream keeps the last message per subject
with no age limit, so the last `running` of every module on every node stays on it however long ago it was said,
and each part's durable consumer starts from the last message per subject, never from now: a consumer made after a
node's last `running`, and two parts' consumers made at different times, hold the same builds. The event carries the module, the fingerprint and the
digest of the build's manifest, which is the indexer's manifest of that build (ADR 0660 §2's "the indexer's
manifest of it"), read by digest from the catalog half; the builder's done key is not needed, since the event names
the digest it would give. A node that has said no `running` for a module since the part's consumer began counts by
the trunk's manifest, as ADR 0660 §2 has it where the running build cannot be read, and both parts apply that same
fallback in the one function (ADR 0660 §3). Never another node's have key, its want or the assignment half (ADR 0596
§2; *Each part acts on its own entries*). The design's choice under ADR 0660 §2: the node that runs a build says what
it runs, and an event kept by a durable consumer answers when that node is away. How it is checked: test 56.
- §200 **A part with no view says it waits.** It names the revision it has no view for, acts on nothing new, and keeps
running what it runs, as ADR 0636 §1 has a reader of the seat list do; the checker, the builder and the grants part
wait too, and wait for the view, not only the seat list (ADR 0656, which changes ADR 0636 §1); the node-engine waits
for the catalog half as ADR 0636 §1 already has it wait for the seat list. Each answers in its runtime's first-view
tool (below) the revision it holds, the one it waits for and since when, and after five minutes without a view writes the finding
`view-waits` naming itself and the revision, as a reader of the seat list does, which the condition keeper raises
(ADR 0564 §2); it clears when the view arrives. Five minutes is the bound the seat list's readers already keep, so an
indexer or assigner down for a restart raises nothing. A part restarted while the indexer or the assigner is down
waits and says so.
- §201 **Each process knows its own build from its start.** The node-engine hands every process it starts the
fingerprint of the build it starts it with, and the process takes its own build from that, never learning it later
(ADR 0656, which changes ADR 0639 §7 from the indexer to every process). *The fingerprint handover*, below, says its
form.
### What ADR 0656 leaves to this design
§202 ADR 0656 leaves how each part is built to this design, under issue 1921; these four needed a shape of their own.
- §203 **An acting rule's fields.** The seat's definition is where ADR 0656 has an acting part declare what it acts on. A
seat's definition gains one optional field `acts`, a list of rules, each with three fields of its own: `step`, one of `take-in`,
`validate`, `check`, `build`, `compose`, `grant` and `place`, and from G's delivery `pipeline`, the runner's, in
`check`'s place (ADR 0666 §19); `on`, either `every` (every module) or a `language`
naming the language of the modules it acts on, matched against what the manifest says its language is, as the
indexer's language map matches today; and `bound`, how long an entry waits in that step for the acting part's new
version (*An acting part's new version acts first*, below, gives each step's default). The definition format's own
schema (design 26) gains the field, and the format stays 1. The indexer reads it into the catalog graph, the assigner
into edges, and the checking program from the revision view. **Its cost in mesh-sdk:** the seat-definition reader in
mesh-sdk's runtime refuses a definition with a field it does not know or a format other than 1, so a reader built
before the field refuses every definition that carries `acts`, and a refused definition blocks new claims of that
seat only (ADR 0636 §3), never what runs. The runtime therefore learns `acts`, which rebuilds every module once
(ADR 0656, Consequences); that is the same rebuild the fingerprint handover makes, so the milestone rebuilds every
module once in all, and no other module's code changes. A definition carrying `acts` reaches only readers built with
that runtime: the seat definitions that gain it are members of milestone G's group, and every reader is rebuilt in
the same delivery; the format's reader itself is delivered before them, as a release of mesh-sdk's seat-definition
reader merged ahead of G's check (the operator's choice of a reader first, 2026-11-09; ADR 0667 §4). The bootstrapped
definitions every reader carries from its start (ADR 0636 §2), of which `node-backup` carries no `acts`, are made
again from the new definitions in the same change, and mesh-sdk's existing test that each bootstrapped copy equals its definition holds
them to it.
- §204 **One wiring of the seat list's reader.** The reader of the seat list and its two tools of ADR 0636 §7 are wired once,
by mesh-sdk's runtime (`go/seatlist`), for every part that reads the list; no part wires its own. Four delivery
parts (the assigner, the checker, the indexer and the grants part) each carry a hand-wired copy today, each with its
own pair of tools, and each copy would have to learn `acts` apart. The design's choice under ADR 0636 §7, which puts
the tools in the runtime bundle: one wiring learns `acts` once, and every part's two tools are the same, named by
their module, with the same callers (any person and the healers to read, the operator and the healers to read
again), the node-engine's among them. How it is checked: mesh-sdk's seat-list test registers both tools for a
fixture part; a search of the delivery parts' code finds no wiring of its own.
- §205 **The fingerprint handover.** The node-engine starts each process, a service or a container alike, with the
environment value `MESH_FINGERPRINT`, the fingerprint of the want it applies; mesh-sdk's runtime reads it once at the
process's start and holds it as the process's own build (ADR 0656). A process started with no value says `own build
unknown` in its runtime tool and its journal, and the indexer acts on it as ADR 0639 §8 has it. **Its cost:** one
change of mesh-sdk's runtime, which rebuilds every module once (ADR 0656, Consequences), and one of the
node-engine; the order between them is the composing step's wait of the node-engine (*Order without a person*,
below), so a module whose runtime reads the value is composed only by a node-engine that hands it.
- §206 **The build seat's ask that runs a program in the sandbox.** The checker asks the seat `node-build-go` for an ask
`run` on the build seats' `check` stream: one whole job on one node (ADR 0525 §3), which fetches the named heads,
builds the named program at them, runs it in the run step (ADR 0448 §2) with the input the ask names by its sha256 in
the asker's own state (the checker's `inputs`, a day), asked of the seat `mesh-delivery-checker`'s verb `input` and
checked against that digest, laid as a file, and writes the program's exit and its answer, carried whole, on the
build module's step key named by the ask's id (ADR 0525 §6). It is an accepted ask of the seat, not a request verb, because it is a
long job pulled where there is capacity, never a call to a named node. Only the checker's account may publish `run`,
and from G's delivery the runner's and the indexer's (its validation before take-in), each under its own name.
Every step key of a `run` ask starts with the asker's name (`checker.<ask id>`), so the checker's read grant is fixed
in advance to its own prefix and never follows ask ids one by one (ADR 0363 §2); no other part can have a program run
or read its verdict. From milestone G the seat definition of `node-build-go` in `mesh-delivery-contracts` names it; B0
brings the ask with its types in mesh-sdk's `go/delivery` and the grants check asks have today (*The bootstrap
delivery, and the one milestone after it*). The checking program, the acting parts and the composer a check builds
from a change all run through it (ADR 0656, ADR 0644). A program is built once per fingerprint: the build is the
builder's build of that fingerprint (ADR 0498 §1), kept like any build and reused by every later ask naming it, so two
checks of changes that leave the checking program unchanged ask one build. Only a build made in a run step that runs
nothing but the build is kept and reused: a program's own run happens in a separate run step over a copy, so a program
that rewrites its own binary while it runs changes no kept build. A candidate's build is never delivered to a node: a
want names only a trunk revision's fingerprint (*Only a trunk revision writes wants*), and a candidate's build is kept
only for checks.
- §207 **The first tier's own bound.** A check's first tier has 20 minutes for all its builds together, inside the check's
one-hour bound of the state table and the checker's step bound (ADR 0639 §5); an acting part not built within it is
one the first tier cannot build, and the check fails naming it (ADR 0656). The verdict tells two cases apart: `waiting
for a build node` when no build node of the language took the ask within the bound, and `did not build` when one
took it and the build failed, so the operator knows whether to free a build node or fix the change.
### Choices this design makes under ADR 0656
§208 ADR 0656 decides the direction and leaves every choice made in working it out to this design, each with its reason
(ADR 0656, Consequences; the operator, 2026-11-06 20:3x). The choices, and why:
| Choice | Why |
|---|---|
| §209 Both graphs kept as objects in an `objects` section in the old form, each with a cap of 512 MiB | both parts are the foundation, whose new kept data goes on the old sections so neither waits on the bus module to start (ADR 0619 §1, §2); the caps are many times the estimated 90 days |
| §210 An unchanged entry stored once, a revision being a list of its entries' digests | consecutive revisions differ by a few entries, so the stores grow by what changes; a larger cap over whole revisions would only delay the same fill |
| §211 No old form written beside the new; a revert restores the parts' kept data on the bus from a restore point taken before they moved, then they catch up forward | only the new form is looked after (the operator, 2026-11-06 21:3x), and a revert still works, as the delivery system's capability for every change of a kept data's form |
| §212 A module's kept data on the bus backed up before a `form` change and restored beside the live data at a revert, a missing restore point holding the revert | ADR 0404 covers only the items on a module's node, so the bus's kept data had no restore point; a restore never goes over live data, and a revert with nothing to restore must not start on the newer form unasked |
| §213 Only kept data whose `form` changes restored, the wants never; at a revert the node-engine last on its node, and the reverted assigner and gate only after the reverted indexer took in the trunk's head | restoring anything else would set back what was decided since; restored wants, or an assigner reading an indexer not yet caught up, would send nodes to older fingerprints; the node-engine of before may not know how to restore |
| §214 A restore point holding the consumers' positions and the catch-up tool the newer manifest declares, called after a restore | the reverted build then hears everything since as after any restart; the stream `forge` keeps 7 days, so what fell out of it is taken in from the trunk by the part's own tool |
| §215 A revision removed when no record pins it and it is not current, pins counted per revision | a trace must read every revision it moved between, and a revision neither pinned nor current is read by nobody; counting pins keeps a revision two records share |
| §216 The indexer and the assigner hear `pinned`, `freed` and `heads-replaced` through durable consumers | an event said while either was down is applied when it comes back, so no revision leaks and none is dropped early |
| §217 Records kept 90 days by default, the gate's setting `record-retention`, the ledger capped at 768 MiB, a record's operations removed with it | the traces asked so far went back weeks; about 840 outcome operations make a record about 200 KiB, so 90 days at an estimated 20 a day is about 360 MiB, and the cap is twice that |
| §218 `record-open` only when no other condition covers the record | the cause is already told once; a second condition for it is noise |
| §219 `full` cleared by `room` when the store falls back below its cap | the refused work is taken up again, and a condition that never clears would hide the next fill |
| §220 The switch into records keyed by milestone and heads, safe to run twice | delivering milestone G again after a revert makes no second record and asks no group again |
| §221 A store passing 80 % of its cap said as `filling` and raised; a full cap refused as `full`, naming the part | the operator hears of a store filling while there is time, and a full store stops work loudly instead of dropping what a trace needs |
| §222 A candidate's graphs kept apart and dropped on `heads-replaced` | a candidate must never write wants or be read by a running part, and its graphs mean nothing once its heads are gone |
| §223 The verbs `revision`, `entry` and `difference` on the two seats | each half of the view, and the difference, is served by its one owner through its seat, never read from its state |
| §224 The node-engine reads its want and the catalog half, never the assignment half | the want is the one record a node reads; the assignment half would have each node read every node's placements |
| §225 Composing waits per node, held by the assigner, with no new field in the want: a node's node-engine want first, its other wants once its new node-engine runs | a node away holds only itself (ADR 0603 §7); an old node-engine reads its want as it is, so it is reached with no form it cannot read |
| §226 Capability changes said as the node-engine seat's event `capabilities-changed` | the assigner follows an event instead of reading node records across the seam (ADR 0596) |
| §227 The step events, their fields and their subjects, with the node in the subject of every event a node publishes | every outcome reaches the delivery record as the event of the part that did it (research 085, Findings 7), and a node's account can be granted only its own node's subjects (ADR 0363 §2) |
| §228 A first tier of only the changed acting parts, bounded at 20 minutes, its verdict telling `waiting for a build node` from `did not build` | an ordinary change pays nothing more; a bound turns a build that never ends into a named failure, and the two words tell the operator which act frees it |
| §229 The build seat's ask `run`, published only by the checker's account, its step keys starting with the asker's name | the program is a long job pulled where capacity is, run in the sandbox every check already uses (ADR 0448 §2), and no other part can have a program run or read its verdict |
| §230 A program built once per fingerprint and reused, only from a run step that runs nothing but the build; a candidate's build never delivered | a check that leaves the checking program unchanged costs no build, and a program run from a change can never change a kept build or reach a node |
| §231 Every program built from a change run with no network and no bus account | a change not yet merged is not trusted, and the sandbox already keeps the logins outside (ADR 0448 §2, §4) |
| §232 Every change of the checking program's fingerprint named in the verdict and the Approve ask, with the rule names of the trunk's and the heads' programs compared by the running checker outside the sandbox as its detail | only the fingerprint covers a helper a rule calls; the comparison is made from the sources by a part the change did not build, so a program that drops a rule and hides it is still named; a rule widens or narrows what judges or acts on every module, so the operator sees it before approving |
| §233 A rule matching a module with no holder for its step held by name, and its check failed | a rule nobody serves would otherwise pass in silence |
| §234 Each step's wait held by the part that does the step, with its own read and release tools and the events `wait-held` (at the wait's start, with its bound) and `wait-ended`, timed by the watchman, whose clock starts when the new version's build is done | the part that does the step already holds its state; the watchman timing from `wait-held` still raises a wait whose holder stopped, and counting from the build done leaves a slow build to the build's own wait |
| §235 The bound per step in the acting rule, with a default per step | the time a step's new version needs is the acting part's to know, not another module's |
| §236 A build module's wait ends on the agreed toolchain naming the new build module | the agreed toolchain is what a fingerprint takes (ADR 0584 §1), so before it names the new build module no module could be built once by it |
| §237 The running indexer makes a catalog graph revision with the named indexer's entry | the newer indexer can then be wanted and granted, so a revision waiting for it is never stuck behind it |
| §238 The acting rule's field `acts` with `step`, `on` and `bound`, the definition format staying 1 | the steps and the language match are what the indexer's map and the checker's cases held in code (research 085, Findings 2); the reader refuses an unknown field, so the runtime learns it in the one rebuild the milestone makes |
| §239 The fingerprint handed as `MESH_FINGERPRINT` at a process's start | one value every runtime reads before anything else, a service and a container alike |
| §240 The delivery record's consumer, held and failed outcomes, end and `record-ended`, the finding `record-open`, node away and wake, switch done once, and tools | a restart must lose and double nothing; a reader sees why an entry stands still; a node asleep must not hold a delivery open; a switch run twice must ask no approved group again |
| §241 A small fix's own record | a small fix is a milestone of one issue (ADR 0493 §3) |
| §242 An Approve given held while its heads stand (issue 1972) | the operator approved those heads; a check of them asked again changes nothing they approved (ADR 0441 §1, ADR 0548 §8) |
| §243 The milestone events on a subject of their own | a waiter on one member's pull request otherwise wakes on every member's |
| §244 The issue tracker's link kinds to a decision and a research effort, and the knowledge base's link from a decision to its milestone | the trace from research to the running build is then links all the way, with no text match (research 085, Findings 7; ADR 0493 §4) |
| §245 The view's state read and asked again by mesh-sdk's `go/views` tools `<module>_first_views` and `<module>_first_view_again`, which gain the revision a part holds and what it waits for; the typed first view and the following of each half in the seats' client packages `meshcatalogclient` and `meshwantsclient`, built on `go/views`; the finding `view-waits` after five minutes; and `node_process_builds` | every part's view and every process's own build is read and steered by a tool; `go/views` already follows an owner's events durably and serves those two tools, so a second follower or a second pair of tools would be two forms of one thing; a view tool typed by the two seats would make mesh-sdk import contracts (ADR 0635 §4), so the typed half sits in the seats' client packages (ADR 0625 §4); a part waiting for the view is raised on the bound the seat list's readers keep |
| §246 The seat list's reader and its two tools wired once by mesh-sdk's runtime | ADR 0636 §7 puts them in the runtime bundle; four hand-wired copies would each learn `acts` apart |
| §247 The trunk's heads from the catalog half, and nothing read of the gate by the checker | ADR 0596 §2; with the hold and turns removed nothing of the gate is left for the checker to read |
| §248 The indexer reads every contracts trunk's definitions at its start, before it judges | a definition merged while it was down is never judged against a list that lacks it (ADR 0636 §1) |
| §249 Another node's running build kept from the node-engine seat's `running` events by a durable consumer, the event carrying the fingerprint and the manifest's digest, the trunk's manifest for a node that said nothing | ADR 0660 §2 reads the manifest of the build each node runs; an event kept by a durable consumer answers while a node is away, where a call would wait on it; one fallback in the one function keeps the two parts agreed (ADR 0660 §3) |
| §250 What the gate and the checker owe the forge said as the event `owed` per repository and pull request, each act safe to repeat at the forge, each outcome said as `owed.ended` and recorded, an unanswered act said again at the gate's start and stalled after 15 minutes | ADR 0596 §1, §2 end the watches of the gate's and the checker's keys; an act safe to repeat cannot be lost between the act and its record, where an id recorded first could; an outcome said and recorded leaves no act unseen |
| §251 A merge made at the forge opens a `forge-made` delivery record | its trace and outcomes are kept like every delivery's, and no later merge waits behind a merge the gate never heard |
| §252 Every delivery part and the gate reach the forge only through the seat `git`'s verbs and events, the act verbs granted by the holder's trusted `callers` to the forge bridge alone, a failed read answered as an error | the delivery parts name no other module (ADR 0656 §1, acceptance test 27); the forge's answers are typed in the seat's contract instead of guessed in each caller; the bridge stays the one part that acts on the forge; an error read as an empty answer would hide a forge down |
| §253 A check that failed because a part of the mesh was not heard says `could not run`, naming the part, releases its claim, and is asked again once per heads and part on that part's `running` event, raising `check-could-not-run` after 60 minutes | the operator sees a mesh fault apart from a failing change, and the check is asked again on the one event that can change its outcome, never on a timer (issue 1373) |
| §254 A module held for its claim raises `module-held` until it is composed | a module left out in silence would look delivered (the mesh's rule that failure is loud) |
| §255 The indexer waits for the seat `git` at most 2 minutes at its start, then judges from its kept definitions and raises `view-waits` after five | longer than a forge's restart, and no start held behind a forge down for good |
| §256 The forge before the forge bridge before the gate, reverted the other way | the verbs are served before they are called, and `owed` is said only to a bridge that hears it |
| §257 The store seat's holder's own new build kept on its build node and fetched by `kept-artifact` when its seat is broken | its own build needs the store it replaces; a step of the delivery replaces the hand bootstrap |
| §258 Every drop and release tool writes the hand-act log | a hand act that changes what the mesh runs or keeps is recorded with who did it and why, as every hand act is (seat `mesh-hand-acts`) |
§259 Each choice is checked by the tests its section names; the review by architectural domain judges them.
### What each step says
§260 Each step says what it did as its own event, the event of the part that did it. A catalog graph revision kept
carries the source revision; an assignment graph revision kept and a difference worked out carry the source revision
and the assignment graph revisions; an entry taken in, built, checked, composed, wanted and running also carries the
entry's fingerprint and its node. The gate's delivery record is built from them. The seat's event comes first where
the parts follow it through a seat (ADR 0656); a holder's own event stays under its own subject, declared in its own
manifest's `streams` and published on `mesh.stream.<module>.event.<event>` (ADR 0363 §1, §2). A seat's event is
declared in its definition and its holder's manifest claims the seat; a seat event's name has no dot, since it is read
as a subject's token, and it is kept on the stream `SEAT_<seat>_<event>`, which the grants part makes with its durable
consumers, keeping it by the age and cap the definition's `keep` names, 90 days unless it names less. **An event a node publishes carries the node in
its subject**, and the grants part grants each node-engine's account only its own node's subjects, so one node cannot
say another runs a build (ADR 0363 §2); the gate's events are granted to the gate's account alone.
| Step | Event | Owner: the seat, then the module | Subject | Declared in |
|---|---|---|---|---|
| a catalog graph revision kept, saying whether it is a trunk revision or a candidate's and its watched branch | `catalog-revision` | `mesh-catalog`, the indexer | `mesh.seat.mesh-catalog.event.catalog-revision`, the watched branch in the subject from G's delivery | the seat's definition in `mesh-delivery-contracts` |
| an assignment graph revision kept | `assignment-revision` | `mesh-wants`, the assigner | `mesh.seat.mesh-wants.event.assignment-revision` | the seat's definition in `mesh-delivery-contracts` (ADR 0641 §2) |
| a difference worked out | `difference` | `mesh-wants`, the assigner | `mesh.seat.mesh-wants.event.difference` | the same |
| an entry taken in | `take-in.taken`, which gains the entries | the indexer's own | `mesh.stream.mesh-delivery-indexer.event.take-in.taken` | the indexer's manifest |
| an entry built | `build.ended` | the builder's own | `mesh.stream.mesh-delivery-builder.event.build.ended` | the builder's manifest |
| an entry checked | `checked` | `mesh-delivery-checker`, the checker | `mesh.seat.mesh-delivery-checker.event.checked` | the seat's definition in `mesh-delivery-contracts` |
| an entry wanted | `wanted` | `mesh-wants`, the assigner | `mesh.seat.mesh-wants.event.wanted` | the seat's definition in `mesh-delivery-contracts` (ADR 0641 §2) |
| an entry composed, and running healthy | `composed`, `running` | `node-engine`, the node-engine on each node | `mesh.seat.node-engine.event.composed.<node>`, `.running.<node>.<module>`, the latter on a stream kept last per subject with no age limit | the seat's definition in `mesh-contracts` |
| a node's capabilities changed | `capabilities-changed` | `node-engine`, the node-engine on that node | `mesh.seat.node-engine.event.capabilities-changed.<node>` | the same |
| a wait held, and ended | `wait-held` (step, acting part, its version, the entry, since when, its bound), `wait-ended` (the same, and how: ran, released) | each holder: `mesh-wants` for the assigner (placing, wanting and composing), `mesh-grants` for the grants part, the builder's own stream | `mesh.seat.<seat>.event.wait-held`, `.wait-ended`; `mesh.stream.mesh-delivery-builder.event.wait-held`, `.wait-ended` | each seat's definition; the builder's manifest |
| a store filling, full, and back below its cap | `filling`, `full`, `room` | `mesh-catalog`, `mesh-wants`, `mesh-delivery` | `mesh.seat.<seat>.event.filling`, `.full`, `.room` | each seat's definition |
| a record pins or frees a revision; a candidate's heads replaced; a record ended | `pinned`, `freed`, `heads-replaced`, `record-ended` | `mesh-delivery`, the gate | `mesh.seat.mesh-delivery.event.<event>` | the seat's definition in `mesh-delivery-contracts` |
| a milestone's ask asked, withdrawn and answered, until G's delivery | `milestone-asked`, `milestone-withdrawn`, `milestone-answered` | `mesh-delivery`, the gate | `mesh.seat.mesh-delivery.event.<event>`, the milestone in the event, on the seat's family stream, apart from each delivery's `transition` | the same |
| a delivery record opened, and a merge named a recovery | `record-opened`, `recovery-merged` | `mesh-delivery`, the gate | `mesh.seat.mesh-delivery.event.<event>` | the same |
| a pipeline, its steps, its waits and a run on request, from G's delivery | `pipeline-started`, `pipeline-ended`, `group-ended`, `run-started`, `step-started`, `step-ended`, `wait-held`, `wait-ended` | `mesh-pipeline-runner`, the runner | `mesh.seat.mesh-pipeline-runner.event.<event>.<module>.<branch>.<commit or group>` | the seat's definition in `mesh-delivery-contracts` |
| a pipeline step ended, from G's delivery | `step-ended` | each build seat, `mesh-wants` | `mesh.seat.<seat>.event.step-ended.<node>`, the node that ran it | each seat's definition |
| a registration changed; a package published, from G's delivery | `registration-changed`; `package-published` | `mesh-catalog`, the indexer; `mesh-builds`, the builder | `mesh.seat.mesh-catalog.event.registration-changed`; `mesh.seat.mesh-builds.event.package-published` | the seats' definitions in `mesh-delivery-contracts` |
§261 The events, their fields, their subjects and which are a seat's are this design's choices: a seat's event where
other parts follow the step through the seat, a holder's own event where only the delivery record hears it, so that
nothing reads another module's bus state (ADR 0596). The builder's waits go on its own stream because the builder
holds no seat of its own; the watchman and the gate follow them there. How it is checked: each seat definition's
conformance fixtures name the subject of every event it gains, and a case of the holder's whole-module test matches an
event it publishes against them, as for every seat (design 26); the gate's whole-module test hears each row through
its durable consumer, with exactly the fields this section gives it; a `running` event published by one node's account
on another node's subject is refused by the bus.
### Their tools
| Line | The assigner | The indexer |
|---|---|---|
| read everything it holds | `assigner_revision` (one assignment graph revision whole, with the revisions of its inputs), `assigner_revisions` (every kept revision with what pins it, and the store's fill against its cap), `assigner_entry` (one entry, with the seat rule that gave each edge), `assigner_difference` (a change's difference), `assigner_waits` (*Order without a person*), `assigner_candidate_graphs` (every candidate's graphs: its heads, its revisions, since when), `assigner_consumer` (its consumer of the gate's events: the last applied, the waiting), `assigner_puts` (each put with its step, since when, held or not, the `running` that ended it, and for a put without hold whether it is past its 30-minute bound; a put older than the trunk's newest build of its module said so) | `indexer_catalog_revision` (one catalog graph revision), `indexer_catalog_revisions` (every kept revision with what pins it, and the store's fill against its cap), `indexer_candidate_graphs` (every candidate's catalog half), `indexer_consumer` (the same as the assigner's) |
| do by hand what it does itself | `assigner_recompute` (compute a revision again from its named inputs and compare it with the one kept) | `indexer_recompute` (compute a catalog graph revision again from its source revision and compare it with the one kept) |
| recover without help | `assigner_drop_candidate_graph` (drop a candidate's graphs whose gate event never came), `assigner_release` (*Order without a person*) | `indexer_drop_candidate_graph` (the same for its half) |
| one seat, many tools | `mesh-wants`: `revision`, `entry`, `difference` | `mesh-catalog`: `revision`, beside `seat-definitions` |
§262 Every drop and release tool writes its act, who did it and why, in the hand-act log of the seat `mesh-hand-acts`.
Beside ADR 0636 §7's two tools in mesh-sdk's runtime bundle, which read a reader's seat list and make it read the
list again, the view is read and steered by the two tools mesh-sdk's `go/views` already serves every part that takes a
first view: `<module>_first_views` gains which view revision the part holds, what it waits for and since when, beside
what it heard and how far it is behind, and `<module>_first_view_again`, granted as ADR 0636 §7's second is, makes it
read the view again now. `go/views` stays seat-neutral, naming no seat and no seat's type (ADR 0635 §4); the typed
first view of each half and the following of its events are the seats' client packages, `meshcatalogclient` for
`mesh-catalog` and `meshwantsclient` for `mesh-wants`, each built on `go/views` (ADR 0625 §4), so no part follows the
view by a follower of its own. A tool
of the node-engine, `node_process_builds`, reads the build each process was started with. The tools answer the four
lines every module's tools answer (design 26), so that every state these parts keep is read and every act they do is
steered by a tool.
§263 **How it is checked.** Unit (assigner): a revision of the assignment graph computed again from its named inputs
equals the one kept; a fixture change with a new fingerprint and an empty difference is refused, naming its module;
one revision of about 120 modules on four nodes stays under the bus's value limit; of the view the assigner reads only
the catalog half. Unit (indexer): a catalog graph revision holds one entry per module of its source revision. Whole
(indexer): a source revision taken in gives one catalog graph revision kept as objects in an `objects` section in the
old form within the cap its manifest declares; the manifest validator refuses the indexer's or the assigner's manifest
that declares them in the new form. Whole (indexer, assigner): a revision a delivery record pins is not removed; one
two records pin stays until both free it; one neither pinned nor current is removed; a `freed` said while the part
was stopped is applied after its restart; a candidate's graphs are dropped on `heads-replaced`; a store past 80 % says
`filling` and raises `store-filling`, and a full one says `full` and refuses its next revision naming itself; for a
candidate's heads both `revision` verbs answer, the assigner's half named by its own revision and naming its inputs; a
placement change with no merge, and a `capabilities-changed`, each give a new assignment half on the same catalog half,
whose difference moves only the module concerned, and a part takes that pair as its view; after its first view a part
acts on a seat event without asking a verb again; a running part does not act on a candidate's view; a pull request
that adds a seat and a module using it is validated by the indexer's candidate pass and checked by the checker with
the same definitions; the tools of the table answer and the drop tools write the hand-act log. Whole (assigner): a
pull request's graph leaves every node's want unchanged; a placement-only revision moves the want of the module it
places; the builder and the grants part read their entries only through the seat `mesh-wants`'s verbs and events, and
the node-engine reads its want and the catalog half and never the assignment half. Whole (node-engine): a part started
while its node's want differs from what runs reports the build it was started with. Live: a search of the readers'
code finds none of the reads the revision view replaces, each by name: the indexer's read of the checker's previews,
the checker's watch of the indexer's `candidates.<try id>`, the forge bridge's read of the gate's `merges` and `owed`,
the checker's read of the gate's `source` and `turns`, the forge module's watch of the checker's `owed` (its `mesh/check`
status, now the checker's `owed` event performed by the forge bridge) and its read of the gate's `source`, the grants
part's read of the assigner's state `wants`, any module's read of the indexer's `modules` (its tool
`indexer_read_modules` in an `invokes`, its view in a `consumes`), the
checker's validator request with no seat definitions, a seat list compiled into the node-engine, the checker, the
builder or the grants part, a seat list's reader wired by a part itself, and a call of the forge module's own tools by
a delivery part or the gate; an old node-engine that wakes takes its new build in a form it reads.
@@ -0,0 +1,408 @@
---
layer: to-be
status: in-progress
design: 47
milestone: G
updated: 2026-11-10
decisions:
- "ADR 0667"
- "ADR 0666"
- "ADR 0663"
- "ADR 0662"
- "ADR 0661"
- "ADR 0656"
- "ADR 0648"
- "ADR 0646"
- "ADR 0644"
- "ADR 0639"
- "ADR 0636"
- "ADR 0633"
- "ADR 0619"
- "ADR 0614"
- "ADR 0603"
- "ADR 0596"
- "ADR 0595"
- "ADR 0584"
- "ADR 0564"
- "ADR 0551"
- "ADR 0548"
- "ADR 0539"
- "ADR 0534"
- "ADR 0498"
- "ADR 0448"
- "ADR 0404"
- "ADR 0391"
- "ADR 0363"
- "ADR 0235"
- "ADR 0233"
---
# 47, milestone G: the acting parts, the removed hold, the check on the change's own acting parts, after the merge, taken in, and kept data on the bus
One file of milestone G's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
[G.md](G.md). Its design lines are numbered across every file of the part and cited as "design 47 G §n".
## Order without a person: the acting parts
### An acting part's new version acts first, a wait with a bound
*ADR 0656, which supersedes ADR 0646; ADR 0603 §1 to §4, §8, §11, ADR 0614 §1, §3, §6, ADR 0633
§1, ADR 0539 §7, ADR 0584 §1, §2, ADR 0564 §2.*
§264 From research 085's milestone. A seat's definition may carry a rule, the step its holder acts in and the modules it
acts on, and a holder of such a seat is an **acting part** (ADR 0656): the indexer taking in and validating, the
checker checking, the build modules building, the node-engine composing, the grants part granting, the assigner
placing. *What ADR 0656 leaves to this design*, above, gives the rule's fields. Adding one needs its manifest and
its seat's rule, and no code elsewhere: the indexer's map from language to build module and the checker's own module
names go, since every new acting part needed code changes elsewhere (research 085, Findings 2).
- §265 **The rule becomes edges between versions.** In the assignment graph the assigner gives an edge from the acting
part's version to each version its rule names, and no part names another module in its code to order by (ADR 0656).
- §266 **Within a revision the new version acts first, a wait with a bound.** The entries an acting part acts on wait for
its new version in its own step, with the bound its rule's `bound` gives (ADR 0656), the part's own as ADR 0603 §8
has every wait. A bound's clock starts when the new version's build is done, as the builder's `build.ended` of that version says, its
time carried in `wait-held` as `clock-from`, not when the wait begins, so a slow
build of the acting part is the build's own wait and not counted twice. When a rule names none, the step's default holds: 60 minutes for building (a build module's own
build and its spread to a majority of build nodes), 30 for composing (a node-engine's apply on one node), 10 for granting and placing (a write of one part), and the first tier's 20 for checking; from G's delivery 30 for the runner's `pipeline`, whose wait ends when the new runner runs healthy, one module's apply on one node as composing's is (the design's choice under ADR 0666 §19, 2026-11-10). A module changed with
its build module is no longer built with the running recipe and again later, and a build module's edge, a trigger no
want waited on, becomes this wait (ADR 0656, which changes ADR 0603 §1, §3 and ADR 0614 §1, §6).
- §267 **A build module's wait ends on the agreed toolchain.** For building, an entry waits until the agreed toolchain of
its language (ADR 0584 §1) names the new build module, never merely until the new build module runs on one node: a
fingerprint names the agreed toolchain (ADR 0603 §3), so only then is the module built once, by the new one. A build
node still on the old build module builds nothing of that language until it reports the agreed one (ADR 0584 §2).
Every other step's wait ends when the acting part's new version runs healthy, as the node-engine seat's `running`
event says.
- §268 **Composing waits per node, by the assigner.** A node's wants wait only for that node's own node-engine, never for
another node's, so a node away holds only itself (ADR 0603 §7). The want gains no field: the assigner, which writes
the wants, holds a node's other wants until the node-engine seat's `running.<node>.<module>` says the new node-engine version
runs on that node, and writes that node-engine's own want first. A node-engine of before milestone G thus gets its
own want first and every other want once it runs the new one, so an old node-engine never composes a module it
cannot read. The clock of that node's bound starts when the node is present and its node-engine's want is written,
so a node asleep raises nothing while away.
- §269 **A failed or late new version holds its modules, and a condition names it.** When the new version fails, or its
wait passes its bound, the entries waiting for it stay held, the modules stay on their running builds, and the
watchman writes the finding `acting-part-late` naming the acting part, its step and since when, and the condition
keeper raises it (ADR 0564 §2). The holder says `wait-held` at the start of the wait, carrying the acting part's new
version, its bound and `clock-from`, and the watchman times it by that bound alone, raising no `pipeline-stands` for
a step held in it: a holder stopped in the middle of a wait still has its wait timed, so a stopped holder hides
nothing. At its own start the watchman reads the open waits from each holder's read tool, as it seeds
`take-in-waits` from `indexer_pending`, so a wait said while it was down is timed too. An entry moves on only once the new
version runs, or its holder's release tool releases it; either way the holder says `wait-ended`, and the finding and
the condition clear. The operator sees each stuck acting part as one condition. Going on with the running version
instead would build or check a change with a part it replaced, the cause of the failures of research 085, Findings
4; stopping the whole delivery would hold modules the failed part does not act on (the operator, 2026-11-06 17:0x).
- §270 **A wait holds only within its step, and skips the holder's own inputs** (ADR 0656). An entry waits only for its
own step's holders, so two acting parts that act on each other in different steps (the indexer taking in the
checker, the checker checking the indexer) form no cycle. Within a step a holder's own change is its first act, and
what its new version is built from or needs (a base, a package, a provider) is acted on by its running version,
never waited for: the running build module builds the shared contracts and the registry holder, then the new build
module builds the rest, so ADR 0614 §6's cycle through them stays allowed, now for that reason.
- §271 **The artifact store's holder takes its own new build even when its seat is the one broken.** A build module
stores the artifacts it builds through the seat `oci-artifact-registry`, so the
holder of that seat is in its own build's path: its new build needs the store it replaces. As every holder's own
inputs are (above), that store is acted on by the running holder: the running holder stores its new build, and only
then is the new one wanted. When the running holder is what is broken (the seat refuses or does not answer a store,
as in the hand bootstrap of 2026-11-07 to 11-09), the build module keeps that one build on its own node among its
kept builds (*The bootstrap delivery*: `build_go_kept`), says in its step key that it is kept on that node, and the
builder's done key names it so with its digest, which the want carries as it carries every artifact's digest; the
node-engine composing the holder fetches it through the build seat's verb `kept-artifact` of that node, and the new
holder, once it runs, takes the store of every build after it.
- The verb sits in the build seats' definitions (`node-build-go`, `node-build-node`, `node-build-image`, in
`mesh-delivery-contracts`), and its callers are the node-engines alone: the definition names them, and the grants
part grants it to no other account.
- It answers only for the module the seat list names as the holder of `oci-artifact-registry` at the running
revision, and refuses every other, naming the module, so a manifest that only claims the seat, and a store outage,
never turn into delivering from build nodes.
- The bytes go as the reply's object in the build module's sent store `<module>_sent-objects` (*Any size*), never in
a value, since an artifact is over the bus's value limit; the build module is no foundation part, so it keeps no
old `objects` section, its kept data being in ADR 0595's templates (ADR 0666 §4), and the build itself stays among
its kept builds on its node. The sent store's cap is the objects template's; a holder image larger than its free
room refuses `kept-artifact` loudly, naming the store, as a full store does. The node-engine checks the bytes it
fetched against the digest its want names, never a builder's key (ADR 0596), and applies nothing that differs.
- A kept build that a step key names as kept is never swept until the module's `running` event names a later
fingerprint, which the build module hears through a durable consumer of the node-engine seat's events. Each build
seat reads and drops its kept builds by its own tools: `build_go_kept`, `build_node_kept` and `build_image_kept`,
with their `_drop`. The disk cost is one image of the store's holder on one build node (a guess: tens of MiB).
- While the keeping node is away, or its sweep removed the build, the want waits, and the node-engine says in its
have that it waits for that node or for a build no longer kept. A want that waits so for 60 minutes, building's
default bound, is the watchman's finding `kept-build-waits`, naming the module, the node and the build node; the
operator or the healers recover it by `builder_build_again`, which builds and keeps it again.
- A node-engine of before G does not know `kept-artifact`: the holder's want on its node waits for its new
node-engine (ADR 0667 §9). A new node-engine is itself fetched from the store; while the store is broken it waits,
so on a node that has neither the store's holder's new build nor G's node-engine, the want waits and
`kept-build-waits` names the node-engine's version as the cause, for the operator's hand at the forge as ADR 0667
§11 has it.
This is the one artifact the mesh delivers from a build node instead of the store, and only for the holder of
`oci-artifact-registry`; the design's choice under ADR 0656 §3 (a wait skips what the holder's own new version needs) and ADR
0526 §2, whose build by a session's call it makes a step of the delivery instead of a hand act; the digest, the
holder check, the sweep, the bound and the old node-engine are the design's choices of 2026-11-10 (round 1). How it
is checked: test 60, and whole (build module, node-engine): a module claiming the seat but not its holder in the
seat list is refused; bytes differing from the want's digest are not applied; a want waiting 60 minutes raises
`kept-build-waits` and `builder_build_again` ends it.
This is the one artifact the mesh delivers from a build node instead of the store, and only for the holder of
`oci-artifact-registry`; the design's choice under ADR 0656 §3 (a wait skips what the holder's own new version needs) and ADR
0526 §2, whose build by a session's call it makes a step of the delivery instead of a hand act. How it is checked:
test 60.
- §272 **The check refuses a cycle among the waits within one step** (ADR 0656, which changes ADR 0603 §2's refusal of a
cycle), counted beside the edges ADR 0614 §3 and §6 list; a cycle through an acting part's edges across two steps, or
through a holder's own inputs, is none.
- §273 **The indexer's own steps have no wait, and a newer indexer is reached.** Taking in and validating stay as *Taken in
by the indexer it names* has them: a revision is taken in only by the indexer it names, which judges its own change
at its start, and no build waits on which indexer judged it (ADR 0603 §4, as ADR 0633 §1 changes it). So that the
named indexer can start at all, the running indexer makes, for a merged revision naming a newer indexer, a catalog
graph revision that is the previous one with only the indexer's entry replaced by the one its manifest at the merge
gives, and nothing else of the revision, so no other want moves before the named indexer takes the revision in; the assigner wants it and the grants part grants it like any module, and once it runs it takes the revision
in whole. Without that, a revision waiting for its indexer would wait for good.
- §274 **A rule with no holder is no silent pass.** An entry a rule matches with no holder for its step is held by the
assigner, naming the missing holder as the hold's reason, and the check fails naming it.
- §275 **An acting rule grants nothing.** A holder's bus grants come from the grants part as today (ADR 0539 §7). An
acting rule changes what a part acts on across every module it matches, so the operator's Approve ask of a change
names any acting rule it adds, and any it widens: a `step`, an `on` or a longer `bound` that now matches more
modules or holds them longer is named like an added rule. From G's delivery there is no Approve ask per merge, and
the pipeline's end names it in `widens` instead, refusing nothing (ADR 0666 §23).
- §276 **Each step's wait is its own part's, read and released by its own tools.** The part that does a step holds its
wait, so each wait has one owner that already holds that step's state, and says `wait-held` and `wait-ended` (*What
each step says*) with the step, the acting part, its version, the entry and since when:
| Step | Holder | Reads its waits | Releases one |
|---|---|---|---|
| building | the builder, on its build key | `builder_waits` | `builder_release` (build the entry with the running build module), beside `builder_build_again` (ADR 0603 §11) |
| placing and wanting | the assigner, on its hold | `assigner_waits` | `assigner_release` (ADR 0603 §11) |
| granting | the grants part | `grants_waits` | `grants_release` |
| composing | the assigner, holding a node's other wants until its new node-engine runs there (*Composing waits per node*) | `assigner_waits` | `assigner_release` |
| checking | the check's first tier | `checker_first_tier` | its ask-again (*The check on the change's own acting parts*) |
| pipeline, from G's delivery | the runner, holding the pipelines its new version is to run until it runs healthy | `runner_waits` | `runner_release` (run them with the running runner) |
Each release writes the hand-act log of the seat `mesh-hand-acts`, with who released and why.
- §277 **How it is checked.** Whole (assigner): a fixture seat declaring a rule, with a fixture holder, gets its edges with
no code change elsewhere. Whole (assigner, builder, three build nodes): a group changing the shared contracts and the
build module that builds them, the new build module updated on the first build node first, builds no module with the
new build module while one node of three runs it, builds the contracts with the running build module, and once the
second node reports it and the agreed toolchain names it, builds each other module once, by the new one; the third
node builds nothing of the language until it reports the agreed version. Whole (assigner, builder, grants part,
watchman): a fixture acting part whose new version fails, and one whose wait passes its bound, each leave their
modules on their running builds, say `wait-held` at the wait's start with its bound, and raise `acting-part-late`
naming it; a holder stopped in the middle of a wait still raises it, and a watchman restarted mid-wait reads the
wait from the holder's read tool and times it; a bound counts from the new version's build done; each holder's release tool
moves a held entry on, says `wait-ended` and writes the hand-act log, and the condition clears; a wait ends on its
own when the new version runs; each holder's read tool lists its waits with step, acting part, version and since
when; a rule's `bound` overrides the step's default; a change to the runner holds its pipelines until the new runner
runs, raises `acting-part-late` past 30 minutes and no `pipeline-stands`, and `runner_release` moves them on; a
`wait-held` carries `clock-from` from the builder's `build.ended`. Whole (assigner, node-engine): during a node-engine change with
one node away, the present nodes take their new node-engine and then their other wants, nothing waits on the node
away and no condition is raised for it; a node asleep since before milestone G wakes, takes its new node-engine
first, then the rest. Whole (indexer, assigner): a merged revision naming a newer indexer gives a catalog graph
revision that is the previous one with only the indexer's entry replaced, and no other want moves; the new indexer is wanted and granted, starts,
and takes the revision in, with no build waiting on which indexer judged it. Whole (assigner): a module with no
holder for its step is held by name, and the check of a change bringing it fails naming the missing holder. Unit
(graph): an acting part acting on itself, two acting parts acting on each other in different steps, and a cycle
through a build module's edge each pass the cycle check, each new version first in its own step; a cycle among
waits within one step is refused. Unit (assigner): the Approve ask of a change that adds an acting rule, and of one
that widens one, names the rule. Live: a search of the delivery parts' code finds no other module's name.
## Nothing merges into a repository under check: removed
§278 **Removed at research 085's milestone.** The hold, the merge turns, their stalled line, the gate's tools for them and
the setting `check-gates-merge` go in milestone G, the gate's and the forge module's alike (the operator, on Telegram,
2026-11-09 01:11 UTC, choosing "Remove them in G"; the forge's merge then judges no check, *The seat `git`*). The setting has been false since 2026-10-25, so the gate wrote no turn and held no merge in that time, and the
operator's word for G is that no check gates delivery (1921's note of 2026-11-07). From G's delivery no merge waits on a check, and none on an Approve either (ADR 0666 §10): the checker is gone, and the
pipeline runs on the landed commit (*Pipelines per module*). **Its record is accepted:** ADR 0661 ends ADR 0548 §2
to §4, §9 and §10 and ADR 0551 and changes ADR 0534 §4's judgement of `mesh/check` by the merge; until G's delivery the
rule below holds as those records have it. ADR 0662 is withdrawn; G builds ADR 0661 §1, §2 and §6, and ADR 0666 §10
changes its §3 to §5 (the merge on the Approve alone), which G therefore builds for no merge. Beside it, ADR 0663 (accepted: the indexer answers `revision` in its own runtime to
exactly the parts that invoke it, the tool runner among them) holds the tool
runner's first view of the catalog half (*Every other reader of which modules exist*). How it is checked: in the gate's whole-module test an approved merge into a
repository under a running check is handed at once, and the gate's manifest declares no `turns` and no setting
`check-gates-merge`; in the checker's, a check claims at once with no gate state granted to read.
## Checks: the check on the change's own acting parts
### The check on the change's own acting parts
*ADR 0656, which supersedes ADR 0648, ADR 0644; ADR 0448 §2, §4, ADR 0391 §1, ADR 0603 §10, ADR 0614 §7, ADR 0633
§6, ADR 0636 §4, ADR 0639 §5, ADR 0498 §1.*
§279 From research 085's milestone. ADR 0603 §10 and ADR 0614 §7 let a check pass while the part that would build or
check the change never ran: 7 of 24 failures since 2026-11-01 (research 085, Findings 4). The acting parts a change
alters, and the checking program, the rules every check applies, are built from the change's heads and check it; the
running versions never check in their place, and a check fails, naming the part, when one cannot be built or run
(ADR 0656).
- §280 **Two tiers on the change's assignment graph.** The first tier builds, at the change's heads, only the acting parts
whose fingerprint in the change's assignment graph differs from the running one and which are to act on a module
the check acts on; a change to an ordinary module asks no first-tier build, since building every acting part for
every check would make an ordinary change pay for builds that change nothing. The second tier runs the check's
levels with those programs and with the revision view of the change's heads (ADR 0656). This keeps ADR 0603 §10's
building of changed build modules first and widens it to every acting part.
- §281 **The judging rules are a checking program built from the change.** Every check builds its checking program from
the change's heads and runs it with the revision view as its input; when it cannot be built or run, the check
fails naming it, and the running checker's own rules never judge in its place (ADR 0656). It is built once per
fingerprint and reused (ADR 0498 §1): checks whose heads leave the checking program unchanged ask one build between
them.
- §282 **Every program built from a change runs only in the build seat's sandbox.** The acting parts the first tier builds
and the checking program run in the run step, with no network (ADR 0448 §2) and no bus account, the logins staying
outside (ADR 0448 §4), through the seat `node-build-go`'s ask `run` (*What ADR 0656 leaves to this design*), as
the validator, the composer and the Go build module already run; a change not yet merged is not trusted. The running
checker alone asks, reads the program's verdict, records it and publishes it.
- §283 **A first tier that cannot build an acting part fails the check, naming it.** The verdict never passes on the
running version's word: a module whose changed build module the check cannot run is no longer composed from its
manifest (ADR 0656, which changes ADR 0603 §10 and ADR 0614 §7), and ADR 0614 §7's reason, a changed build module
invoking a verb no running holder serves, is one reason the first tier cannot run an acting part: the check fails
naming the build module and the verb. An acting part not built within the first tier's bound of 20 minutes is one
it cannot build, and the verdict says `waiting for a build node` or `did not build`.
- §284 **A change to the checking program is named, by a part it did not build.** Every change of the checking program's
fingerprint is named in the verdict and the Approve ask, whatever changed: a helper a rule calls changes what the rule
judges as much as the rule does, and only the fingerprint covers every input. The rule-name comparison is its detail:
each checking program declares its rules by name in its source. The running checker, outside the sandbox, reads the rule names from the
trunk's sources and from the heads' and compares them; every rule removed, added or altered (its source changed) is
named in the verdict and in the operator's Approve ask. The program built from the change is never asked which rules
it has, so a program that drops a rule and hides it is still named.
- §285 **ADR 0633 §6 stays, beside the change's own validator.** Whether the running parts can take the change in is
still checked with the trunk's manifest validator, built from the trunk (ADR 0633 §6); the change's own validator,
built in the first tier, judges the change's manifests besides (ADR 0656). A change fails if either refuses it.
- §286 **The asking and recording are covered by the checker's whole-module test**, which starts the changed checker on a
real bus and asks one check of a fixture group end to end (ADR 0391 §1).
- §287 **One seat list for both readers of a change's heads.** Inside every check, a lone pull request's as a group of one,
the checking program built from the heads makes one seat list from them, and the checker hands it to the manifest
validator and the composer (ADR 0644, ADR 0636 §4 with its insight of 2026-11-06); the running checker reads no
definition of the heads itself (*The bootstrap delivery, and the one milestone after it*).
- §288 **Its tools.** The checker's read of a check names the checking program's build that judged it, its fingerprint and
the heads it was built from, and the rules named changed; `checker_first_tier` lists a check's first-tier builds,
each with its acting part, its fingerprint and its outcome (`built`, `waiting for a build node`, `did not build`),
and asks one of them again. Asking a whole check again stays the checker's existing ask-again.
- §289 **What it costs.** A check of a change to an acting part costs one build per changed acting part, within the
checker's step bound (ADR 0639 §5); an ordinary change costs nothing more; a checking program costs one build per
fingerprint, shared by every check that uses it.
- §290 **How it is checked.** In the checker's whole-module integration test: a fixture change whose acting part does not
build, and one whose checking program does not run, each fail their check, naming the part; a checking program that
builds but does not run fails naming it; a first-tier ask no build node takes within the bound says `waiting for a
build node`, and one that fails says `did not build`; a change that breaks a rule of the checking program fails its
own check; a change that removes a rule passes, and its verdict and the ask name the removal, also when the
program built from the change hides it; a change to a helper a rule calls, with no rule renamed, names the checking
program's new fingerprint in the verdict and the ask; a program that rewrites its own binary while it runs changes
no kept build; a fixture checking program that tries to reach the bus or the network
fails; a `run` ask published from an account other than the checker's is refused by the bus, and the checker's
account cannot read another account's step key; a fixture build module invoking a verb no running holder serves
fails naming it and the verb; a change to an ordinary module asks no first-tier build; two ordinary checks with the
same checking program ask one build of it; a group that changes the assigner's placing is checked with its own
assigner; a fixture indexer change whose manifest the trunk's validator refuses fails its check, even when its own
validator passes it; a fixture group whose heads add a seat has that seat in the list both the validator and the
composer receive; the check's read names the checking program's build, heads and changed rules; `checker_first_tier`
lists a check's first-tier builds and asks one again; the changed checker asks one check of a fixture group end to
end. Live: the registry group passes its one check with its own checker, validator and composer.
## After the merge, from milestone G
- §291 **From milestone G's delivery, per watched branch.** The gate writes one source revision per watched branch,
`source.<branch>`, as a commit or a group lands there; the pipeline runs on each revision the indexer takes in, and
the wants follow a revision whose `required` steps passed, on the branch each placement chose (ADR 0666 §6, §9).
- §292 **From research 085's milestone, the wants follow the trunk's assignment graph.** A merge taken in makes a
catalog graph revision and then an assignment graph revision; the assigner writes each want from that revision,
its rules unchanged (ADR 0656), and each acting part's new version acts first in its own step (ADR 0656; *Two
graphs, one source of truth*, above).
## Taken in by the indexer it names, from milestone G's delivery
- §293 **From milestone G's delivery** (ADR 0666 §6, §13, which change ADR 0633 §1 and §3 to §6): before any take-in, on every
watched branch, the running indexer validates the revision with the manifest validator built from its heads, in the
sandbox, and a revision it refuses stays pending, as the bullets above have it, with the way back a revert; a pending
revision holds only its own watched branch; a group's member reaches it by landing, and the group ends when the gate's
group verb says every member has; `bridge_group_end_again` reads that verb; and the check's refusal below goes with the
check (*Watched branches and the catalog graph per branch*, *Groups*).
## A backup before the apply: kept data on the bus
### A module's kept data on the bus, backed up and restored with its delivery
*ADR 0404, ADR 0235, ADR 0233, ADR 0539 §16, ADR 0595, ADR 0619 §2, ADR 0633 §1, §5, ADR 0363 §2; from research
085's milestone, this design's choice under ADR 0656.*
§294 **ADR 0404's backup does not cover a module's kept data on the bus.** It backs up the items a moved module keeps on
its own node (ADR 0404 §2, ADR 0233), and the bus's streams are dumped whole by the bus module on its own rhythm
(ADR 0235), not per module and not before a delivery. A key-value state, a stream or an object store a module keeps on
the bus (ADR 0595, ADR 0619 §2), and its durable consumers' positions on the streams it reads, therefore have no
restore point taken before its module moves. That is a gap of the delivery system, and milestone G builds it, because
a revert of milestone G is the first change that needs it. It is built as the delivery system's capability for every
later change of a kept data's form, not as a case of this milestone.
- §295 **Its form is declared.** Each kept data a manifest declares names a `form`, a number its holder raises whenever it
changes how it writes that data, or stops declaring it; a declaration naming none reads as form 0. The declaration
alone cannot tell a changed layout of the same bucket, so the holder says it. Only kept data whose `form` changes is
backed up and restored, so a part's other kept data, and every decision it holds, is never set back.
- §296 **It is backed up before the module moves.** When a want moves a module whose new manifest declares a kept data at
another `form` than the running one, or no longer declares it, the node agent applying it first asks the seat
`node-backup` of the node holding `mesh-broker` for a restore point of that kept data, and waits for its event
`ended`, as for any backup before the apply. The bus module's account takes it, as it takes the bus's snapshots
(ADR 0235 §5). A restore point is keyed by the module, the kept data, its form and the fingerprint it was taken
before, and it holds the kept data whole, the position of each durable consumer the module reads with, and the
catch-up tool the newer manifest declares beside that kept data. A failed
backup holds that module as any failed backup does.
- §297 **A revert restores it before the reverted build starts.** When a want takes a module back across a change of a
kept data's `form`, the node agent applying it asks that seat's verb `restore` for the restore point of that module,
kept data and form, waits for the seat's event `restored`, and only then starts the reverted build. The node agent
that restores is the one running when the revert starts. As every restore is, it is brought back beside the live data
and never over it: the live kept data of the newer form is set aside under a name of its own, and only the operator
removes it, so nothing written since is destroyed. The consumer's position is set back with it, so the reverted
build hears everything since as after any restart.
- §298 **The order of a delivery that crosses a form change** is the module graph's (*Order without a person*), with three
edges the assigner, which writes every want, keeps:
- the new versions of the `node-backup` holder and of the bus module run before any module whose kept data's form
changes is moved, since the restore point needs both;
- at a revert, a node's node-engine goes back last on that node, after every module it restores there has said
`restored` and runs, since the node-engine of before may not know how to restore;
- the reverted assigner and gate are wanted only once the reverted indexer has taken in the trunk's head, as its
`take-in.taken` naming the current source revision says (ADR 0633 §1), since the assigner of before computes the
wants from the indexer's `modules` and would otherwise write the fingerprints of the restore point. Until then the
running assigner writes no want, and every module keeps the fingerprint it runs.
- §299 **The restored part catches up forward, with the code it already has.** Read on main, mesh-delivery at 2d201f78
and mesh-catalog at 1d07778c:
- **The indexer** (mesh-delivery, `modules/mesh-delivery-indexer`): its durable consumer `<node>_<module>` on the stream
`forge` redelivers every message since the restored position, and `handle` takes each
merge through `Indexer.Arrive` into `pending` and then into `modules` (`applyMerged`); `applySource` takes the
gate's `source.main` in, and `ApplySource` leaves a revision older than the latest it has seen. **The stream
`forge` keeps 7 days**: the forge bridge's manifest declares no age, and a stream's default is 7 days, at most 30
(mesh-sdk `go/catalogue` `StreamDefaultDays`, `StreamMostDays`), so it does not cover the records' 90 days. A
merge older than the stream's first message is never redelivered, and the code then leaves that repository's
modules at the restore point's fingerprints. So the restore runs one forward step: once the reverted indexer
runs, the node agent that restored it calls its tool `indexer_take_in` with each repository the gate's source names
(`NewTakeInRepository`, which takes in the head the source names for a repository). The catch-up tool is declared
by the newer build's manifest, beside the kept data whose form it changes, and recorded in the restore point when
the backup is taken; the node agent takes it from the restore point, never from the manifest being applied, since
at a revert that is the manifest from before the change, which names none. So the delivery system names no
module's tool.
- **The assigner** (mesh-delivery, `modules/mesh-delivery-assigner`): it keeps nothing restored. Its pass
(`passer.wants`) writes, from what the world holds now, each node's want by the six rules from the indexer's
newest fingerprint at the trunk, and only where the value differs; so once the indexer has caught up it writes
the trunk's wants, and nothing older.
- **The gate** (mesh-catalog, `modules/mesh-delivery-gate`): `Holder.Load` reads the restored deliveries and groups
back; `readOnStart` then reads what happened while it was away: `wantForge` reads the forge's open pull requests
at the next look, `hearAsks` reads the teller's answer to every ask it still holds as pending, and
`SourceCatchUp` brings the newest merge of each repository into `source.main`, never moving a repository back. An
ask the gate of milestone G raised after the restore point is not among the pending ones, so its answer is not read
and the operator is asked again. Whether the first look clears a merge kept in the restored `merges` that the forge
merged since was not read in the code; the catch-up test below proves it with the real builds.
- §300 **A missing restore point holds the revert, naming it.** When the restore point a revert needs does not exist, or
`restored` does not come, the node agent applies nothing of that module, keeps what runs, and writes the have phase
`held` with the reason `restore point missing` and the module, kept data and form it names; the assigner asks the
operator (hold, or start the reverted build on the live data as it is), raises the condition naming them, and on
the answer writes the node's want again naming it (ADR 0539 §16).
- §301 **What the operator is told.** A revert across a change of a kept data's form puts that kept data back to the
moment before the change moved it: the deliveries made since stay delivered, but what the part wrote there since
(for milestone G, its delivery records and its graph revisions) is set aside and not read again; an Approve asked
and answered since is asked again, and one the gate asked before still reads its answer. The revert's Approve ask
says this in those words, naming each kept data restored.
- §302 **Its tools.** The seat `node-backup`'s `backed-up` lists each module's restore points of its bus data, with the
kept data, the form and the fingerprint each was taken before, and the data set aside at each restore, with its
size; `restore` restores one; `discard-aside` removes data set aside by a restore, only on the operator's call, and
writes the act, who and why in the hand-act log of the seat `mesh-hand-acts`. `backed-up` and `restore` exist on
the seat today and gain the module's kept data on the bus as an item; `discard-aside` is new.
- §303 **How it is checked.** Whole (node-engine, backup holder, bus module): a want moving a module across a `form`
change, and one moving a module whose kept data declares no `form` to one that does, each take a restore point
first, keyed by module, kept data, form and fingerprint; a want taking it back restores it beside the live data and
the consumer's position before the reverted build starts, and the data set aside is listed with its size and
removed only by `discard-aside`, which writes the hand-act log; a revert of a group holding the node-engine and a
module whose form changes restores the module before the node-engine goes back; a revert whose restore point is
missing is held, naming it, and moves on only on the operator's answer. The catch-up is proved with the real builds
of the indexer, the assigner and the gate from before milestone G, never fixtures (acceptance test 36).
@@ -0,0 +1,509 @@
---
layer: to-be
status: in-progress
design: 47
milestone: G
updated: 2026-11-10
decisions:
- "ADR 0668"
- "ADR 0667"
- "ADR 0666"
- "ADR 0660"
- "ADR 0659"
- "ADR 0656"
- "ADR 0635"
- "ADR 0625"
- "ADR 0619"
- "ADR 0614"
- "ADR 0603"
- "ADR 0596"
- "ADR 0595"
- "ADR 0564"
- "ADR 0563"
- "ADR 0551"
- "ADR 0548"
- "ADR 0534"
- "ADR 0493"
- "ADR 0443"
- "ADR 0441"
- "ADR 0398"
- "ADR 0363"
---
# 47, milestone G: the verbs G adds, what retires, and the answers to the builders' and the reviewers' questions
One file of milestone G's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
[G.md](G.md). Its design lines are numbered across every file of the part and cited as "design 47 G §n".
## The verbs milestone G adds
§304 From research 085's milestone the seat gains:
| Verb or event | Answers or does |
|---|---|
| `groups` with a group | that group's members, which the forge bridge reads in place of the gate's `merges` state (ADR 0656), and the acts the gate said it owes the forge for it, each with its id and its recorded outcome (*What the gate owes the forge*) |
| `owed` | an act the gate owes the forge (a merge, a status, the delivery's view, a comment, a line on the commit's note), with its pull request, head and id, on `mesh.seat.mesh-delivery.event.owed.<repository>.<number>`, said only from the gate's account and heard by the forge bridge through a durable consumer (*What the gate owes the forge*) |
| `milestone-asked`, `milestone-withdrawn`, `milestone-answered` | until G's delivery: the one Approve ask per milestone (ADR 0493 §9 as ADR 0659 §1 changes it, issue 1783), held until it is answered, or withdrawn by a new head and asked again (ADR 0441 §1); said on `mesh.seat.mesh-delivery.event.<event>`, the milestone in the event, apart from each delivery's `transition`, which stays as it is, so a waiter on one member's pull request wakes only on that member's `transition`. G's delivery ends the ask and its three events with the Approve per merge (ADR 0666 §10) |
| `record-opened` | a delivery record opened, which the watchman times for `record-open` |
| `pinned`, `freed`, `heads-replaced` | the events by which the indexer and the assigner keep or drop graph revisions, said only from the gate's account (*The delivery record*) |
| `record-ended`, `filling`, `full`, `room` | a delivery record ended; the ledger past 80 % of its cap; the ledger full; the ledger back below its cap (*The delivery record*) |
§305 From milestone G's delivery the seat's `table`, `recheck` and `close` go with the merge states (*The state table*),
the milestone ask and its three events with the Approve per merge, and it gains (ADR 0666 §6, §26):
| Verb or event | Answers or does |
|---|---|
| `source` with a watched branch | that branch's source revision; the indexer and the node-engine's catch-up read it, never the gate's state |
| `source-moved` | a new source revision of a watched branch |
| `recovery` | marks a merge its author names a recovery (the commit and why), its record marked `recovery` with the caller the runtime proves |
| `record-opened`, `recovery-merged` | a delivery record opened; a merge named a recovery, which the teller passes on to every channel |
§306 **The seat `mesh-pipeline-runner`**, from milestone G's delivery, defined in `mesh-delivery-contracts` with the callers
of each verb (ADR 0666 §7, §20, §25):
| Verb | Answers or does | Callers |
|---|---|---|
| `run` | the run on request of one or more members, each a module at a named commit; delivers nothing | the sessions (the agents' bus identities the tool runner proves) and the operator, nothing else |
| `start` | a delivering pipeline for a watched branch's head, by hand | the operator, the healers |
| `show`, `list`, `stands`, `why-carried`, `kept` | one pipeline whole with its step log; the pipelines and runs of a module, a branch or a commit; what stands still; where a result was carried from; the kept results | any person, an agent session, the healers |
| `review` | a code review's result for a commit and fingerprint | the reviewers the definition names; refused from the commit's author |
| `rerun`, `accept`, `cancel`, `ask-again` | one step again; a failed `optional` step accepted with why; a pipeline ended, its asks dropped; a declined `approval` asked again | the operator, the healers (`accept` and `ask-again` the operator) |
§307 **The seat `mesh-catalog`** gains, from milestone G's delivery, `register`, `policy`, `watch`, `unwatch` and
`registrations`, and the event `registration-changed` (*A module's registration*), and `catalog-revision` names its
watched branch in its subject. **The build seats** gain the verb
`steps` and the accepted kind `step`, and **the seat `mesh-wants`** the kind `step`, each saying `step-ended`. **The
seat `mesh-builds`**, new and held once for the mesh, says `package-published` (*A publish rebuilds*).
§308 **The seats `mesh-catalog` and `mesh-wants`** gain, from research 085's milestone, `revision` on each (the two halves
of the revision view, ADR 0656), and `entry` and `difference` on `mesh-wants` (ADR 0656), with the events of *What
each step says*.
§309 **The seat `node-engine`**'s event `running.<node>.<module>` carries, from research 085's milestone, the module, its
fingerprint and the digest of its build's manifest, so the node-engine of another node and the grants part decide a
seat's pass from it (ADR 0660 §2; *Who holds a seat is applied by one rule*). No verb is added.
§310 **The seat `git`.** The seat `git` (design 26, *The git seat*), of the Delivery domain, defined in
`mesh-delivery-contracts`, holds no verb today, and the delivery parts and the gate reach the forge by naming the forge
module's own tools and events and guessing the shape of their answers (on 2026-11-09 one guess, an answer wrapped in a
`result` field, made 316 conditions stand, issue 1966). From research 085's milestone the seat's definition carries the
verbs and events below, their inputs and answers typed in its contract, served and said by the module that claims the
seat; every delivery part and the gate call and hear the seat, never the forge module by name (acceptance test 27).
They are this design's choice under ADR 0596 §1, §2 (a module's events are subscribed to and its data asked through
its seat verbs) and ADR 0625 §1 (a seat's contract is generated from its definition). The table is built from what the
parts' manifests declare in `invokes` and `consumes` and what their code calls, read on main on 2026-11-09 (mesh-delivery
042b8d1f, mesh-catalog's gate); a declaration nothing calls (the checker's `gitea_commits`, `gitea_compare`,
`gitea_list_branches`) gets no verb and is dropped from its manifest:
| Verb | Answers or does | Called by (today's call) |
|---|---|---|
| `pull` | one pull request, by its repository and number or by its merge commit: number, base, head branch, head, merge commit, author, state, and `merging` while the forge merges it; an unknown one answers the error kind `not-found` | the forge bridge (a merge the gate did not make; `gitea_api`), the gate (a stalled line's author) |
| `branch` | from milestone G's delivery: a branch's head, and whether a protection rule refuses a direct push and admits only merges | the indexer (`register`, `watch`), the forge bridge (a watched branch's head) |
| `open-pulls` | every open pull request of every repository, its head and base, the statuses its base requires and those its head has | the forge bridge at its start and each reconnect (ADR 0443 §5), the indexer, the gate (`gitea_open_pulls`) |
| `tags` | a repository's tags, paged, the page's bound said when more exist | the forge bridge, for the builder's floor (`gitea_api`) |
| `trees` | the trees of one commit | the forge bridge, the checker, the indexer (`gitea_commit_trees`) |
| `file` | one file at one commit | the forge bridge, the checker, the indexer (`gitea_get_file`) |
| `contains` | whether one commit contains another | the indexer, the gate (`gitea_contains`) |
| `statuses` | the statuses a commit carries | the gate (`gitea_commit_statuses`) |
| `status`, `comment`, `view`, `note` | a commit status, a comment, the delivery's one view comment, a line on the commit's note under `refs/notes/mesh-plan`; a comment and a note line carry the act's id and an id already held is skipped | the forge bridge alone, performing the gate's and the checker's `owed` (`gitea_commit_status`, `gitea_add_comment`, `gitea_delivery_view`, `gitea_note_append`) |
| `merge-pull` | until G's delivery: merges a pull request at the head the operator's Approve names; refuses a head that moved, a branch no rule guards, a head the Approve does not name and a merge git refuses; judges no check (below). From G's delivery: merges with the forge tools' account (ADR 0398 §2) at the head the caller names, judging that it is still the pull request's head and that the branch's protection refuses a direct push, the protection read again on every `branch-moved`, and refusing a head when any run at its build-input fingerprint failed a `required` step, judged from its own state `failed-steps` heard from the runner's `step-ended`, never by a call; a head with no run yet or a passed one merges, it never waits for a run and never asks an Approve (ADR 0666 §11). A pull request already merged at that head is answered performed | until G's delivery the forge bridge alone (`gitea_merge_pull_request`); from it any session the tool runner proves, and the operator |
| Event of the seat | Says | Heard by (today's event) |
|---|---|---|
| `pull.updated`, `pull.merged`, `pull.closed` | a pull request's new head, its merge with the merge commit, its close | the forge bridge, the gate (`gitea.pull.*`) |
| `forge.pull`, `forge.status`, `forge.delete` | the forge's own webhook of a pull request, of a commit status, of a deleted branch | the gate (`forge.pull`, `forge.status`), the forge bridge (`forge.delete`) (`gitea.forge.*`) |
| `repo.writable` | a repository the forge can write again | the gate (`gitea.repo.writable`) |
| `branch-moved` | from milestone G's delivery: a branch's new head, by a merge or an admitted push, from the forge's push webhook | the forge bridge |
§311 Each is said on `mesh.seat.git.event.<event>`, declared in the seat's definition, and heard through the hearer's
`consumes` of the seat.
- §312 **A failed read answers an error, never an empty answer.** When the forge does not answer, refuses or answers what
the contract cannot type, the verb answers an error naming why; an empty list or an absent file is answered only
when the forge said so. A caller never reads an error as "none". How it is checked: the seat's fixtures hold an
error answer for each verb, and each caller's unit table has a row for it (the forge bridge, the checker, the
indexer, the gate).
- §313 **Who may call an act.** The holder's trusted config value `callers`, which today names per verb who may call the
two package seats' verbs (design 51), gains a line per verb of the seat `git`: the act verbs name the forge bridge
alone, the reads name each part that declares them in `invokes`; the grants part grants by it, and the holder
refuses a caller it does not name. From G's delivery the callers per verb are the seat definition's field `callers`,
the grants part's one source (ADR 0666 §20): `status`, `comment`, `view` and `note` the forge bridge alone,
`merge-pull` the persons and agent sessions the tool runner proves, the reads the parts that declare them. The forge module's own acting tools (`gitea_merge_pull_request`,
`gitea_commit_status`, `gitea_delivery_view`, `gitea_note_append`, `gitea_add_comment`) retire with the milestone,
and so do its watch of the checker's state `owed` and its read of the gate's `source`, so the bridge stays the one
part that acts on the forge. How it is checked: test 51 reads the grants, not the code.
- §314 **`merge-pull` judges no check, and from G's delivery no Approve, only the runs at the head's fingerprint.** The operator's answer that no check gates delivery (Telegram, 2026-11-09 01:11 UTC,
"Remove them in G") covers the forge module's own setting `check-gates-merge` as well as the gate's: both are
removed, and `merge-pull` merges an approved head whatever its `mesh/check` says. The record that ends ADR 0551 and
ADR 0548 §2 to §4, §9 and §10 also changes ADR 0534 §4's judgement of `mesh/check` by the merge; it is to be accepted
before the push (*Nothing merges into a repository under check*). From G's delivery it judges no Approve either, its caller
is any session the tool runner proves, and it refuses a head when any run at its fingerprint failed a `required` step,
never waiting for one (ADR 0666 §11; *Approval is a step, and a session merges a pull request*). The reads the
gate would have needed to merge (the forge's word for a conflict, the base's required statuses, the merging account's
write access) are not added: no part of the mesh but `merge-pull` merges, and it answers git's own refusal of a merge
as refused.
- §315 **The order is the module graph's, and each step has its way back.** The verbs are a served-verb edge (ADR 0614):
the forge module's new build runs before the forge bridge's, and the forge bridge's before the gate's, since the
bridge calls the verbs and performs the gate's `owed`, and the gate says `owed` only to a bridge that hears it; all
three are ahead of the acting parts' steps, which read through the seat. While the new forge runs and the old bridge
still calls the retired acting tools, the old bridge's acts fail loudly and stay unperformed in the old gate's keys,
and the switch carries them (*What the gate owes the forge*). A revert goes back in the other order: the gate, then
the bridge, then the forge, each wanted only once the one after it in the forward order runs its reverted build, so
no part calls a verb nobody serves. ADR 0656 §3 stands beside it: the acting parts' new versions act first in their
own steps. Two things cover the gap while the forge is still on its old build and serves no verb of the seat: the
indexer starts on its kept definitions (below), and a check whose read through the seat `git` fails says `could not
run`, naming the forge, and is asked again on the forge module's `running` (*A check runs to its end*).
- §316 **A part that cannot read the forge keeps what it has, and says so.** The indexer, at its start, waits for the
seat `git` at most 2 minutes; with no answer it judges from the last definitions it kept, says in its
`<module>_first_views` that it waits for `git` and since when, writes `view-waits` after five minutes, and reads the
definitions once the seat answers; it then judges again every manifest it judged from kept definitions. Two minutes is longer than a forge's restart, and short enough that a start is
not held behind a forge down for good. How it is checked: test 54.
- §317 **How it is checked.** The seat definition's conformance fixtures hold one answer and one error of each verb and one
of each event, and the forge module's tool tests answer each fixture; the forge bridge's, the checker's, the
indexer's and the gate's unit fakes answer from the same fixtures; a call of an act verb from an account other than
the forge bridge's is refused (test 51); live, a search of the delivery parts' and the gate's code finds no name of
the forge module's tools or events.
§318 **Links of the trace.** No part reads a review line (ADR 0659 §1 to §3); who may review and the review verb's grant
stay issue 1782's, outside milestone G, and that verb gates nothing (ADR 0659 §2). The trace's links are this
design's choices under ADR 0656, so that one call traces research to the running build
with no text match (research 085, Findings 7). The issue tracker gains link kinds from an issue to the decision and to the research effort
it carries, made by a tool call and never by text, as ADR 0493 §4 has every link made; the knowledge base gains a
typed link from a decision to the milestone of the issue tracker that builds it, made by a tool call, which joins the
link kinds of its link-fits rule (design 55), beside the `became` link a research effort gets at its graduation
(playbook 02). How it is checked: whole (gate), one ask per milestone, withdrawn by a new head;
a waiter on one member's pull request wakes only on that member's transition. Whole (issue tracker, knowledge base):
an issue linked to a decision and to a research effort reads both back; a decision linked to its milestone reads it
back. Live: research 085's milestone's record reads back research 085 to its decisions, its milestone, its issues and
its pull requests with no text match.
§319 **A session hears that a record was accepted** (issue 595). The knowledge base already says, on its holder's own
stream, the event `reviewed` for every judgement of a record; from milestone G that event carries, when the operator's
Approve accepts a record, that it was accepted and by the operator, with the warrant, and the tool runner's account is
granted to hear it, so a session waiting on a record wakes on it. The design's choice under ADR 0596 §1 (a module's
events are subscribed to): a new event of the seat `knowledge-base` would be a second path for the same fact (lead-47,
2026-11-09). How it is checked: in the knowledge base's whole-module test an Approve that accepts a record says
`reviewed` with what was accepted and by whom, and the tool runner's account hears it.
## What retires at milestone G
- §320 At research 085's milestone's delivery: the indexer's map from language to build module, and the checker's own
module names and its cases for a change to the manifest validator and to the Go build module (ADR 0656); a build
module's edge as a trigger, with the extra build per recipe change (ADR 0603 §3, as ADR 0656 changes it); composing
from manifests a module whose changed build module the check cannot run (ADR 0603 §10 and ADR 0614 §7, as ADR 0656
changes them); the module graph's one key per module with five past values as what parts read (ADR 0603 §2, as
ADR 0656 changes it); the tiers worked out from five live sources (ADR 0603 §6, as ADR 0656 changes it); a seat
list compiled into a part, and every read of another module's bus state the revision view replaces (ADR 0656); the
gate's `merges`, carried into the delivery records and written no more, and its `owed`, said as events; the hold,
the merge turns, their stalled line and tools and the setting `check-gates-merge`, once their record is accepted;
the last three reads of a pull request's description (ADR 0659 §4); every delivery part's call of the forge module's
own tools, for the seat `git`'s verbs; and the four seat-list readers the delivery parts wire by hand.
- §321 At milestone G's delivery, from research 086 (ADR 0666, ADR 0667): the checker (`mesh-delivery-checker`), its seat,
its try with `tryevent` and the indexer's try candidates, its kept verdicts and carries (the runner's from then), the
checking program and `mesh/check`, and its buckets and bus account, removed with the gate's forge merge token only
after the first pipeline after G's delivery has delivered a change end to end and on the operator's one word, its
buckets through `drop` after a snapshot whose restore is tested (ADR 0667 §12); the bundle of steps run before a merge; the Approve per
merge, the milestone ask and its three events, and the gate's merges; the gate's merge states, one key per pull request and its verbs `table`, `recheck` and
`close`; the trunk-only want; `source.main`, for one source revision per watched branch; every fixed branch,
repository and module name in code logic; the recovery merge verb this design sketched, never built; and the holders'
trusted `callers` values, for the seat definitions' `callers`. The words **merge check**, **try**, **trunk commit**
and **merge turn** go to *Not:* lines with the as-is update after that delivery, as the glossary's entries say.
## What milestone G's builders found open, answered by this design (2026-11-10)
*ADR 0666, ADR 0667, ADR 0668; ADR 0656, ADR 0596, ADR 0595 §4, §9, ADR 0619 §1, §2, ADR 0563, ADR 0564 §2, ADR 0625
§1, §4, ADR 0635 §4, ADR 0548 §5, ADR 0363 §2; design 27, *Which module answers*. The operator, 2026-11-10: a small
choice within what a record decides is the design's own, written here with its reason and reviewed by the reviewers
by architectural domain.*
§322 Milestone G's prepare and develop met these questions (issue 1966). Each line is the design's choice, with the
record it follows from, and replaces the builder's own choice where one was made.
### The runner and its steps
- §323 **A step's build seat is read from the artifact's language.** The catalog graph entry names each artifact's
`language`, as its manifest's artifact entry says it and as the indexer's language map matches today; the runner
reads it from the catalog half of its revision view and asks lint and the test steps of the build seat whose
definition's acting rule `build` has `on` naming that language. With no such seat, or no holder of it, the pipeline
ends failed, naming the seat (ADR 0666 §18). Why: the language is already in the manifest and the catalog half is
the runner's one view (ADR 0666 §24, ADR 0596). How it is checked: whole (runner), a Go and a TypeScript fixture
module each ask their own build seat, and one with no holder ends failed naming the seat.
- §324 **An acting rule's `on` may name an artifact kind.** Beside `every` and a language, `on` may be `kind: image`,
matched against the manifest's artifact entry's kind; the seat `node-build-image`'s rule says `kind: image`. Why: an
image has no language, and the rule's fields are this design's (*What ADR 0656 leaves to this design*). How it is
checked: a unit row of the definition reader accepts `kind: image` and refuses another kind.
- §325 **An approval never asked ends `not asked`.** When a `required` step failed before the `approval` step was asked,
the `approval` step ends `not asked`, naming the failed step, never as passed; a `rerun` that passes the failed step
asks it then, and the pipeline ends again: the runner says `pipeline-ended` once more for it, its end count one
higher, which the assigner takes (*What holds a delivery*). Why: approval comes last (above),
and every end a step can have is said as itself (ADR 0666 §10). How it is checked: whole (runner, assigner), a failed
unit step leaves the approval `not asked`; its passing rerun asks it, and once approved the second `pipeline-ended`
writes the want.
- §326 **A build seat keeps its `steps` answer.** The build module keeps each artifact's detected steps in its state
`steps`, from the template `state`, one key per artifact holding the answer for that artifact's newest build-input
fingerprint, replaced when a newer fingerprint is detected and by `steps` with `again`; a key whose artifact no
longer exists is dropped by `steps` with `drop`, on a person's word, written in the hand-act log. With one key per
artifact (about 120) the state needs no aging and no read time. Why: ADR 0666 §25 asks a tool for "the steps
detected for an artifact and detect again", which a reply computed anew each time would not need; a build module is
no foundation part, so the template form (ADR 0666 §4). How it is checked: whole (Go build module), `steps` answers
from the key, a newer fingerprint and `again` replace it, and `drop` removes one.
- §327 **The step code lives in the domain SDK.** The step run and the fetch-and-release code the three build modules
share move, in this milestone, into a build-step package of `mesh-delivery-sdk`, which the Go, TypeScript and image
build modules import; none keeps a copy. Why: code shared between modules lives in an SDK, and the delivery
domain's shared code is `mesh-delivery-sdk`'s (ADR 0635 §4); the copies were met in develop. How it is checked: a
search of the three build modules finds no fetch, release or step-run function of their own.
- §328 **Lint per language.** Go's lint step is the Go build module's linter with the fixed-names rule; TypeScript's is the
type-check with the fixed-names rule; an image's lint is the fixed-names rule over its build files;
an image has no unit or integration test step, so `steps` answers none for it and the seed has those `bypass`
(*A module's registration*). Why: ADR 0666 §5 has the lint step refuse fixed names in every language, and §7 lets a
build seat answer only the steps an artifact can run. How it is checked: whole (TypeScript and image build modules),
a fixture naming a module in code fails lint.
- §329 **What the fixed-names rule exempts.** It exempts a Go import path, a comment and a test file (`_test.go`,
`*.test.ts`), never a struct tag or any other string of code. Why: none of the three is code logic (ADR 0666 §5),
and a test fixture names modules. How it is checked: unit (lint rule), a name in a comment and in a test file
passes, in a struct tag fails.
- §330 **The runner's own kept data age by its own deletes, in the step log's order.** The runner deletes its own
`pipelines` keys, `kept` entries and `step-outputs` objects by the retentions of *The runner's kept data*. It keeps,
in its old `state` section `aged`, three step-log sequences, one per retention (7, 30 and 90 days), each the last
entry it aged at that retention. At each step's end it reads the step log onward from each sequence, at most 20
entries per sequence, while the entry is past that retention: at 7 days it deletes the entry's output and the
pipeline it names unless that pipeline ended passed on a watched branch or is its branch's newest for its module; at
30 days each `kept` digest the entry names whose `last-read` is past 30 days; at 90 days the passed pipeline the
entry names, unless it is its branch's newest. It then moves the sequence; nothing is scanned whole. Each delete
writes a line in the runner's journal naming the key or object and its retention. A foundation part's sent store
(`sent-objects`) is aged the same way by its owner at each send, from the sequence of its own sends. Nothing waits on
a timer, and nothing but the owner deletes. Why: an old section cannot declare an age, and deleting one's own entries
is the owner's act, not the removal of a store ADR 0595 §4 holds to a person's word; §57's rule that only the drop
tool removes an object holds for a template's `<state>-objects`, while the runner's `step-outputs` are its own old
section's objects. How it is checked: whole (runner), an output 7 days old is gone after the next step's end, a
passed pipeline stays to 90 days, and one step's end deletes at most 20 per sequence.
- §331 **The kept event streams' caps, and when one is full.** On the seat `mesh-pipeline-runner`, each kept 90 days:
`pipeline-started` 32 MiB, `pipeline-ended` 192 MiB, `group-ended` 64 MiB, `run-started` 16 MiB, `step-started`
and `step-ended` 128 MiB each, `wait-held` and `wait-ended` 32 MiB each; the seat `git`'s `branch-moved` 64 MiB; each
build seat's `step-ended` 128 MiB; `mesh-wants`'s `step-ended` 32 MiB; `mesh-builds`' `package-published` and
`mesh-catalog`'s `registration-changed` 16 MiB each; all 90 days. Why: about 300 pipelines a day of about 6 steps
(*The runner's kept data*) say about 1,800 step events a day of about 0.5 KiB, about 80 MiB in 90 days, and about 300
pipeline ends of about 4 KiB, about 105 MiB, 55 % of its cap; a build seat runs about 1,200 steps a day, about 54
MiB; publications and registration changes are a few a day; estimates, read from the fill tools once G runs. A kept
seat stream at its cap drops its oldest message, as a stream with a cap does; the grants part, which makes the
streams, says `filling` on its seat `mesh-grants` past 80 % and `room` below 70 %, which the watchman's
`store-filling` raises and clears as for every store (*A store filling is said before it is full*). How it is
checked: each seat definition's fixtures name each stream's `keep`; whole (grants part), a stream past 80 % says
`filling`.
- §332 **A group's end is said under the group.** `group-ended` is said on
`mesh.seat.mesh-pipeline-runner.event.group-ended.<branch>.<group>`, with no module part, since a group spans
modules; a session that merged a group's member waits on `group-ended.<branch>.<group>` of its group after its own
`pipeline-started` (*What a session hears after its merge*). Why: every other runner event names one module
(*Health and going back*). How it is checked: the seat's
fixtures.
- §333 **The runner hears the indexer's own event.** The runner's manifest `consumes` the indexer's own event
`take-in.taken` (ADR 0666 §13), which ADR 0596 §1 lets any module subscribe to; the indexer's name stands in that
manifest only, never in the runner's code. Why: ADR 0666 §13, in force, names that event. How it is checked: a search
of the runner's code finds no module name (lint).
- §334 **A publication's pipelines and their key.** `package-published` carries the package's artifact reference
(`<module>:<artifact>`, from the catalog entry), its version and digest, the watched branch and the source revision
its build was made from. The runner reads the dependents from that revision's catalog graph, the artifacts with a
kind-1 edge to the package, and starts each one's pipeline keyed by that branch, that source revision and the
dependent module, the version in the pipeline's state; a `take-in.taken` of the same revision and module is the
same pipeline (*A second start writes nothing*). Why: a pipeline's key is branch, source revision and module (above),
and the publication is made from a revision of a watched branch (ADR 0666 §15). How it is checked: whole (builder,
runner), a publish starts one pipeline per dependent, keyed by the publishing revision.
- §335 **What the teller says of a widening.** Each entry of `widens` names what widens (`acting-rule`, `grant`,
`credential` or `serving-part`), its name, the module and the commit. The teller says one message per
`pipeline-ended` that carries any, on every channel, once per module, watched branch and commit: it keeps in its
state `widens-said`, from the template `state`, one key per module and watched branch holding the last commit it
said, replaced by the next and deleted when `registration-changed` says the branch is no longer watched; its tool
`teller_widens_said` reads it. Why: ADR 0666 §23
says a widening in the pipeline's end, and the teller passes it on (*Who may say what*). How it is checked: whole
(teller), a `pipeline-ended` said twice with the same `widens` gives one message.
### Callers
- §336 **The forms of `callers`.** A verb's or an accepted kind's `callers` is a list whose entries are: a holder role (a
seat's name), a module, `operator`, `healers`, `persons` (any person the tool runner proves), `sessions` (an agent
session the tool runner proves), `invokers` (every module whose manifest declares the verb in `invokes`), and
`holder:<seat>@same-node` (the holder of that seat on the node of the verb's holder). A definition whose `callers`
today is text is given a list in this milestone: "any caller whose role grants it" becomes `invokers`, "a person"
`persons`, and every other text the names the design gives that verb. Why: ADR 0666 §20 makes the definition the
grants part's one source of caller limits, in a form it reads. How it is checked: unit (definition reader), each
form accepted and any other entry refused; the grants part's table test grants each form.
- §337 **The bus module's restore points.** The verbs the holder of `node-backup` on the bus module's node calls to take
and restore a module's kept data on the bus name `holder:node-backup@same-node`. Why: only that holder takes them
(*A backup before the apply: kept data on the bus*). How it is checked: a call from another node's `node-backup`
holder is refused by the bus.
- §338 **Callers on accepted kinds.** An accepted kind of a work queue carries `callers` as a verb does, and the grants part
grants publish on its subject to them alone: the build seats' `step` the runner; `run` the runner, the indexer and
the assigner, and the checker until its entry is removed with its buckets and bus account (ADR 0667 §12); `mesh-wants`'s
`step` the runner. Verbs: `steps` the runner and the indexer (its seed); `drop` the runner and the builder; both
`input` verbs (`mesh-catalog`'s and `mesh-wants`') the holders of the build seats. Why: a step's result is taken only
from its seat holder (ADR 0666 §21), so the ask side is limited too. How it is checked: a `step` published by another
account is refused by the bus.
- §339 **The contract generator reads `callers` and makes nothing of it.** The generated contracts carry no caller check;
the grants part reads `callers` from the definition, and the generator refuses a definition whose entry is no form
above. Why: one source of caller limits (ADR 0666 §20). How it is checked: the generator's test refuses an unknown
entry.
- §340 **The reader release first.** mesh-sdk's seat-definition reader released before G's check reads `callers` as text
or as a list; G's own reader refuses text. Why: readers first (ADR 0667 §4), and every definition is a list from G; it is merged ahead of G's check because the
running checker, which makes G's own check (ADR 0667 §2), must read G's definitions, the operator's choice of a
reader first (2026-11-09).
How it is checked: unit rows for both forms in the release, and for the refusal in G.
- §341 **TypeScript contracts as JavaScript.** The generator emits each seat's TypeScript contract as `index.js` with its
`index.d.ts`, so a TypeScript module imports it with no build step of its own. Why: a seat's contract is generated
from its definition (ADR 0625 §1), and a gap of the build system is built in it. How it is checked: a TypeScript
module builds against a generated contract with no `tsc` of the contract.
### The catalog, the builder and the assigner
- §342 **A module not watched on a branch.** A watched branch's catalog graph takes each module not watched on that branch
from the registration's first watched branch. `register` names a module's watched branches; with none named it takes
the repository's default branch, read through the seat `git`. Why: a placement's default is the registration's first
branch (ADR 0666 §6). How it is checked: whole (indexer), a `beta` revision holds a `main`-only module at `main`'s
head.
- §343 **Branch names the indexer's keys use.** `register` and `watch` refuse a watched branch named `candidate` or
`entry`, naming why, since the catalog keeps its revisions under `<branch>.<revision>` beside those two key forms.
How it is checked: whole (indexer), each is refused.
- §344 **The bus module plans a sent store from what the catalog already says.** It plans `<module>_sent-objects` for a
module of the new form whose catalog graph entry claims a seat whose definition has a verb or an event, or declares
an event of its own, read from the catalog half of its revision view and the seat list; the indexer's event carries
no field `sends`. When a seat's definition gains its first verb or event later, the bus module plans the store for
its holders on the seat list's change. Why: no manifest field (*Any size*), and the catalog half is every part's view
(ADR 0656 §6). How it is checked: whole (bus module), a module claiming a seat with a verb gets a sent store, one with
neither gets none, and a definition gaining a verb gives its holder one.
- §345 **A large value reaches the tool runner in chunks.** A bundle's put of a value over the bus's per-message limit is
sent to the tool runner as a put session on the bundle's call subject, named by the call's id, in chunks under that
limit, in order, each answered by the tool runner before the next is sent, and written as one object through the
object store's own chunking; a put not sealed within the call's bound is dropped by the tool runner and its call
fails, naming the object. No value is split over objects. Only modules that import the object store package are
rebuilt for it. Why: one object per value (ADR 0666 §16), through the tool runner (ADR 0595 §9). How it is checked:
whole (mesh-sdk), a value of a hundred times the limit is read back whole, and a put stopped half way fails naming
the object and leaves none.
- §346 **One object store package.** The assigner's and the indexer's object store code is mesh-sdk's small object store
package, with no copy in either. Why: ADR 0595 §9. How it is checked: a search finds no second copy.
- §347 **Reading sent objects is a bus state call.** mesh-sdk lists the call that reads a sent object under its existing
bus state capability. Why: ADR 0595 §9 puts the calls in that package. How it is checked: the package's table test.
- §348 **The builder reads the catalog through its seat.** The builder reads the registrations' watched branches through
`mesh-catalog`'s `registrations` and `registration-changed`, the released versions it numbers from through
`versions` and `version-released`, keeping no list of versions of its own, and a build seat's holder from the seat list; the
manifests, the packages, each package's name in its ecosystem (the Go module path, the npm name, which the catalog
graph entry's packages carry) and a run's candidate from the catalog half of its revision view, never the indexer's
state. With no holder of a build seat, a build ends `could not run`, naming the seat, and is asked again on the seat
list's change. Why: ADR 0596 §2. How it is checked: the builder's account holds no grant to the indexer's state.
- §349 **The catalog holds released versions only, and says each.** The indexer keeps, for the seat `mesh-catalog`,
each module's released versions in its old `state` section `versions`, one key per module and `MAJOR.MINOR` holding
its released patches with each artifact's digest and the source revision built (issue 1961's catalog of versions).
It hears every artifact's `package-published` (packages, images, bundles and archives alike) and records a version
as released once every artifact the module's catalog entry names is published at it, then says `version-released`
(the module, the version, its artifacts, the source revision) on `mesh.seat.mesh-catalog.event.version-released`,
kept 90 days at 16 MiB; the verb `versions` answers a module's released versions, its callers the builder and any
person or session. A reserved version is not in it. The builder's `version.numbered` is no longer said or heard.
Why: the operator, 2026-11-10 about 21:40 CET (gaps items 23 and 43). How it is checked: whole (indexer), a version
with one of two artifacts published is not released, and with both is, said once.
- §350 **A superseded build's drop is a kept call.** The runner ends a superseded build's step `superseded` at once, and
asks the build seat's `drop` as a kept call (ADR 0668 §1, §2), so it is asked again through every transport fault
and said `call-unanswered` after five minutes in the runner's findings. How it is checked: whole (runner), a drop
unanswered is asked again, and raises `call-unanswered` after five minutes.
- §351 **One rule for asking again.** mesh-sdk's kept-call form (ADR 0668 §7) asks an ask again only while it is open and
not replaced, and every asker and every hand ask-again tool uses it. How it is checked: unit (mesh-sdk), a replaced
ask is not asked again.
- §352 **The assigner's newer-revision check reads its own state.** The want gains no field (*Composing waits per
node*): the assigner keeps in its old `state` section `written` one key per module and watched branch, the source
revision and end count it last wrote that module's wants from, compares a new `pipeline-ended` with it by
compare-and-set, and deletes the key when `registration-changed` says the branch is no longer watched; its tool
`assigner_written` reads it. How it is checked: whole (assigner), an older revision ending after a newer one writes
nothing, and a later end of the same revision writes.
- §353 **The assigner follows the registrations.** `mesh-delivery-contracts`' client `meshcatalogclient` carries a typed
follower of `registrations`, a first view then `registration-changed`, built on `go/views`; the assigner and the
forge module's merge switch on its first registrations (ADR 0667 §10). How it is checked: whole (assigner), it keeps
the trunk-only want until the first `registration-changed`.
- §354 **The assigner's composition step runs the composer in the sandbox.** It asks the seat `node-build-go` the ask `run`
(*What ADR 0656 leaves to this design*), its step keys under `assigner.`, and serves the ask's input by its seat
`mesh-wants`' verb `input`, as the checker's seat does today; the indexer does the same for its validation by
`mesh-catalog`'s `input`. Both are foundation parts, so each keeps its inputs in an old `state` section `inputs`, one
key per input named by its write time and its sha256, deleted when the build seat's `step-ended` of that ask is heard
or a day after its write, whichever is first, the day judged at each new ask over at most 20 of the oldest keys;
`assigner_inputs` and `indexer_inputs` read them. Both verbs' callers are the holders of the build seats. The Go build module reads no revision verb. Why: the
composition step runs on parts built from the heads, in the sandbox (ADR 0666 §17). How it is checked: whole
(assigner), a composition step's `run` is answered and its input read by digest.
- §355 **The assigner says an unanswered `manifest-reads`.** The assigner, the one caller of the node-engine's
`manifest-reads` from G, writes `call-unanswered` into its own findings state, and the condition keeper's reads gain
it in the same change (ADR 0668 §3). The assigner and the runner each declare that state, `findings`, in their old
`state` section, both being foundation parts. How it is checked: whole (assigner, runner, condition keeper), a node-engine
that never answers raises `call-unanswered` after five minutes, and the keeper raises it.
- §356 **Two acting parts in different steps make no cycle.** The assigner's cycle check counts waits within one step only
(*A wait holds only within its step*). How it is checked: the unit rows there.
- §357 **Which provider a requirement points to.** In the assignment graph, by design 27's order: the named seat's
holder, a pin, the provider on the consumer's node, the only provider; otherwise the entry is held, naming the
candidates, and nothing is guessed. A contribution edge runs from a consumer's entry to the provider its requirement
resolves to, wherever that requirement carries values the consumer contributes. How it is checked: unit
(assignment graph), each step of the order and a hold.
- §358 **The catalog's shared view takes a branch.** The client's view of the catalog half is per watched branch, named by
its caller. How it is checked: unit (client), two branches give two views.
- §359 **`difference` names its revisions.** `difference` with none of `from`, `to` and `group` is refused, naming the
missing argument. How it is checked: a unit row.
- §360 **An approved ask binds the placement.** What an approved ask binds to includes the placement's watched branch and
its `build`, beside the fingerprint. How it is checked: whole (assigner), a placement changed after the Approve asks
again.
- §361 **A placement's `build` is a held put.** A placement's `build` is written as a held put of that build, released when
the placement drops it; a put a person wrote is never released by a placement change. How it is checked: whole
(assigner), a placement's `build` holds that build on its nodes, removing it releases the put, and a person's put
stays through a placement change.
- §362 **The indexer's first-start catch-up runs apart from its source handler.** At its first start the indexer takes in
the heads the gate's source names by its catch-up path before it starts its handler of `source-moved`. How it is
checked: whole (indexer), a `source-moved` said during the catch-up is applied after it, once.
- §363 **A stale ask is dropped, backups included.** The assigner drops an ask it raised once the want it asked for is
replaced, a backup ask among them (built in mesh-delivery #200). Why: ADR 0596 and ADR 0668 §2. How it is checked:
whole (assigner), a backup ask whose want was replaced is dropped and not asked again.
### The condition keeper and the node-engine
- §364 **The node-engine claims its seat.** The node-engine's manifest claims the node seat `node-engine` (ADR 0563), and
the indexer and the node-engine's own guard read its holder from the seat list, keeping no module name. How it is
checked: lint finds no module name in either.
- §365 **The condition keeper reads its sources from the catalog.** The catalog graph entry carries each kept data a
manifest declares (its name and its section or template); the keeper takes a first view of the catalog half and
reads a module's `findings` wherever its entry declares a state `findings`, and the node-engine's holder from the
seat list. It joins the readers of *Every other reader of which modules exist*, reading every watched branch's newest catalog
revision, so a module watched on any branch is a source. A condition of a module that is in no branch's revision is
cleared, said with the reason `module left the catalog`. Before its first view the keeper keeps raising from the
sources it held, and says `view-waits` after five minutes (*A part with no view says it waits*). Why: no fixed names (ADR 0666 §5),
and the keeper reads findings (ADR 0564 §2). How it is checked: whole (keeper), a fixture module declaring `findings`
is read with no code change.
### From round 1 of the review by architectural domain (2026-11-10)
- §366 **The runner's stores say their fill.** *A store filling is said before it is full* holds for the runner's
`pipelines`, `step-outputs` and `kept`: it says their fill in `show` and `kept`, `filling` past 80 % and `room` below
70 % on its seat, and `full` at the cap, when it starts no new pipeline, says each start it refused, and takes them
up on `room`; nothing is dropped to make room. Why: the runner joins the stores of *Two graphs, one source of truth*
(ADR 0666 §24, ADR 0564 §2). How it is checked: whole (runner), a full `pipelines` refuses a start, said, and
`room` starts it.
- §367 **A forge bridge message is read again on a transport fault.** The indexer reads a message of the forge
bridge's stream again when reading it met a transport fault, as main's `UnreadAgain` does (ADR 0668 §1, §4): the
message is left unacknowledged and its read asked again on the bridge's next answer, while a message the bridge
itself answered as lost stays lost, said in the indexer's journal and in `indexer_pending`. G's own change for it
(`LostAgain`, commit 106fc16b) is not built. Why: one rule for kept calls (ADR 0668), already on main. How it is
checked: the indexer's take-in table, a transport fault reads the message again and a lost answer does not.
- §368 **A manifest says its `MAJOR.MINOR`.** Each module's manifest names `version`, two numbers `MAJOR.MINOR`; the
manifest validator refuses any other form, a pre-release or custom suffix (`beta`, `alpha`) among them: no custom
version exists for now. A manifest without it is refused once G's reader runs (ADR 0667 §4: the reader is delivered
first). Why: the operator, 2026-11-10 about 21:40 CET. How it is checked: unit (manifest validator), `1.4` accepted,
`1.4-beta` and `1.4.2` refused.
- §369 **The reservation is one key per module and `MAJOR.MINOR`.** The builder, a foundation part, keeps in its old
`state` section `reserved` one key per module and `MAJOR.MINOR`, the version its build reserved, written by
compare-and-set at the build's start; a newer build of the module takes the next after the higher of the highest
released and the one reserved, so two builds never share a version, and a superseded build's version is never
released, leaving a gap in the patches. The builder deletes the key when the catalog says `version-released` for it;
`builder_reserved` reads the keys. This is no list of released versions: numbering reads those only from the
catalog. Why: the operator, 2026-11-10 (a version reserved when the build starts); the key and the gap are the
design's choice. How it is checked: whole (builder), two builds close together reserve two versions, and the key
goes on `version-released`.
- §370 **The version reaches every artifact's build.** The build seat's ask carries the version, and the build module
passes it to the artifact's build as the build argument `MESH_VERSION`: a Go package is tagged `vMAJOR.MINOR.PATCH`,
an npm package's version is it, an image carries it as its tag and label, and a program reads it as its own version.
A Go package's version is its tag: this departs from ADR 0573 §2, which has a Go package's version be its trunk
commit, by the operator's choice of 2026-11-10, and a later research brings that record in line. How it is checked:
whole (Go and TypeScript build modules), a built package and program carry the reserved version.
- §371 **Only the first watched branch releases.** Only a build of the registration's first watched branch reserves and
releases a version; a build of another watched branch reserves none, publishes no version and is delivered by its
build, its fingerprint, as every want names one. Why: the operator, 2026-11-10. How it is checked: whole (builder),
a `beta` build reserves nothing and is delivered.
+83
View File
@@ -0,0 +1,83 @@
---
layer: to-be
status: in-progress
design: 47
milestone: G
updated: 2026-11-10
decisions:
- "ADR 0668"
- "ADR 0667"
- "ADR 0666"
- "ADR 0664"
- "ADR 0663"
- "ADR 0662"
- "ADR 0661"
- "ADR 0660"
- "ADR 0659"
- "ADR 0656"
- "ADR 0648"
- "ADR 0646"
- "ADR 0645"
- "ADR 0644"
- "ADR 0641"
- "ADR 0639"
- "ADR 0636"
- "ADR 0635"
- "ADR 0633"
- "ADR 0625"
- "ADR 0621"
- "ADR 0619"
- "ADR 0618"
- "ADR 0615"
- "ADR 0614"
- "ADR 0603"
- "ADR 0597"
- "ADR 0596"
- "ADR 0595"
- "ADR 0593"
- "ADR 0584"
- "ADR 0573"
- "ADR 0571"
- "ADR 0567"
- "ADR 0564"
- "ADR 0563"
- "ADR 0551"
- "ADR 0548"
- "ADR 0539"
- "ADR 0534"
- "ADR 0525"
- "ADR 0505"
- "ADR 0498"
- "ADR 0493"
- "ADR 0448"
- "ADR 0443"
- "ADR 0441"
- "ADR 0437"
- "ADR 0429"
- "ADR 0421"
- "ADR 0404"
- "ADR 0398"
- "ADR 0391"
- "ADR 0363"
- "ADR 0283"
- "ADR 0240"
- "ADR 0235"
- "ADR 0233"
---
# 47, milestone G — every line milestone G builds
This is milestone G's part of [design 47](../47-delivery-from-commit-to-delivered.md): the pipelines per module of
research 086 and the two graphs of research 085, one milestone (ADR 0667 §1). The main file keeps the purpose, the
whole shape, the acceptance tests and the milestones; every line milestone G builds is in this part's files, moved whole from the main
file on 2026-11-10, and is cited as "design 47 G §n". A sentence that holds a delivered line and G's change together
stayed in the main file, and G builds what it says from G's delivery. A section named in italics is in this part, or,
when it is not here, in the main file.
The part is six files, each read whole, its design lines numbered across them:
- [G-1-pipelines-registration-and-steps](G-1-pipelines-registration-and-steps.md): pipelines per module: registration, watched branches, steps and policy, what holds a delivery, approval, groups, dependencies, a publish.
- [G-2-pipelines-sizes-checks-and-tools](G-2-pipelines-sizes-checks-and-tools.md): pipelines per module: any size, the pipeline makes the check, who may say what, health, recovery, tools, kept data, how G itself is delivered, the choices under ADR 0666 and ADR 0667.
- [G-3-delivery-record-and-graphs](G-3-delivery-record-and-graphs.md): the delivery record, what the gate owes the forge, the state table, the two graphs and a change's graph difference.
- [G-4-revision-view-and-steps](G-4-revision-view-and-steps.md): the revision view, what ADR 0656 leaves to this design, the choices under ADR 0656, what each step says and their tools.
- [G-5-acting-parts-check-and-kept-data](G-5-acting-parts-check-and-kept-data.md): the acting parts, the removed hold, the check on the change's own acting parts, after the merge, taken in, and kept data on the bus.
- [G-6-verbs-retires-and-answers](G-6-verbs-retires-and-answers.md): the verbs G adds, what retires, and the answers to the builders' and the reviewers' questions.
@@ -2,7 +2,7 @@
layer: to-be
status: in-progress
code: [mesh-host, mesh-controller, mesh-lab, mesh-catalog, mesh-sdk]
updated: 2026-10-14
updated: 2026-11-04
decisions:
- "ADR 0292"
- "ADR 0283"
@@ -44,7 +44,7 @@ core's own health definitions ([to-be 45](45-a-core-that-cannot-fail-silently.md
operator's conversation (to-be 46), healers
```
One judge per machine, for every hosting form. Nothing else on the machine judges a module, and nothing
The node-engine alone judges health on a machine, for every hosting form. Nothing else on the machine judges a module, and nothing
else sets a container's check.
## 1. Liveness, for everything that stays up
@@ -257,7 +257,7 @@ health needs a record of its own.
- **`module check`** refuses a `health` field naming an endpoint the module does not declare under
`listens`, a port or an address, an interval, timeout, count or grace outside its bounds, a tool the module
does not serve, or a `tool` kind with no other kind beside it on the module.
- **The bed.** mesh-lab provides a throwaway container runtime that the catalogue's check, run on the build
- **The bed.** mesh-lab provides a throwaway container runtime that the catalog's check, run on the build
seat (ADR 0237),
uses to start every resource whose declaration or image changed, alone, and read its check. It must say
healthy within its grace. A check that names a provision in `needs` gets no provider on the bed, so there it
@@ -273,7 +273,7 @@ health needs a record of its own.
nothing long-lived and need no declaration.
1. **Liveness first, with no declarations** (Phase A). From then every long-running resource is judged. The
catalogue's count of long-running resources without `health` is written down and starts.
catalog's count of long-running resources without `health` is written down and starts.
2. **The seven modules whose images ship checks** adopt them by name; for the two that were wrong in the
mesh's configuration, the corrected check is what the bed proves. 19 containers are covered at once.
3. **The other container modules, and the containers without an image check in three of the seven,** declare
@@ -333,7 +333,7 @@ the machine itself, beside its liveness looks, and says it in the same statement
that is the module declaring it whole there; the uplink's holder steps back from it. A VPN client's write
that the client's module took is undone within seconds, before the second look, and is no finding. One
nothing took stands for 90 s, so it is raised as `machine.<m>.systemd-resolved.rewritten`, naming its
writer, and cleared when the resolver puts its file back. Nothing in the judge changes for this.
writer, and cleared when the resolver puts its file back. Nothing in the node-engine's judgement of health changes for this.
- **Asked further through the uplink seat.** `node-uplink` serves `resolvers` (the file, whether it is the
mesh's, its writer) and `links` (each link, its default route, the resolvers its manager knows). They are the
same from every holder, and optional until both holders serve them: promised, so a holder may serve them,
@@ -384,11 +384,11 @@ health of this design, not yet through the machine's own judgement as §10 does
|---|---|---|---|
| A — liveness and the statement | `mesh-host` (node-engine) | liveness for every long-running resource; restarts counted and kept; the state per resource in the report; the change event and its repetition; nothing restarted on health | the node-engine tests of ADR 0240 rules 1 and 6 pass; every machine's report carries a state for every long-running resource |
| | mesh-controller | the last state per machine; `module.<module>.<machine>.unhealthy` on the second statement, cleared on the first that does not say it; the gate reading the stated health; `node show` and `status` | the controller tests of rule 4 pass; mesh-lab's replay of the crash loop fails its gate within the bound; a module stopped on purpose on the live mesh is raised and cleared |
| B — the field | mesh-controller | `health` parsed on every long-running resource; `module check`'s refusals; the catalogue-wide parse | a test per refusal; the whole catalogue passes `module check` |
| B — the field | mesh-controller | `health` parsed on every long-running resource; `module check`'s refusals; the catalog-wide parse | a test per refusal; the whole catalog passes `module check` |
| | `mesh-host` (node-engine) | the scheduler and the kinds: http, tcp, unit itself; exec and runtime as the container's check; tool through the tool runner | the rule 3 tests pass; the replay of issue 145 raises the consumer within two looks |
| C — the provider hold | mesh-controller | `needs` read against the provider composed for the consumer; the consumer's finding held under the provider's condition; the consumer's gate waiting | the rule 5 test (one provider, three consumers, one condition) passes |
| D — the proof | mesh-lab, mesh-catalog | the bed; the catalogue's check starting every changed resource on it; adopted image checks proved | the replay of the studio's false *unhealthy* fails the bed, not a machine |
| E — the migration | mesh-catalog, mesh-controller | the declarations of §9 steps 2–5; the count kept in the catalogue and its test; `module check` refusing after the date | the count is zero, or the date has passed and `module check` refuses |
| D — the proof | mesh-lab, mesh-catalog | the bed; the catalog's check starting every changed resource on it; adopted image checks proved | the replay of the studio's false *unhealthy* fails the bed, not a machine |
| E — the migration | mesh-catalog, mesh-controller | the declarations of §9 steps 2–5; the count kept in the catalog and its test; `module check` refusing after the date | the count is zero, or the date has passed and `module check` refuses |
| F — the machine's network | `mesh-host` (node-engine), `mesh-controller`, `mesh-catalog` | §10: the five parts judged on two looks and stated; the three conditions said once; the gate waiting on another's; `node show` | the tests of ADR 0241 pass; the drill's replay raises and clears; a VPN connect on the laptop is raised naming its writer and cleared by the reconcile |
| G — the machine's hardware | `mesh-catalog` | §11: the `sensors` module, its tools, the drive reader and the fan watch, both checks declared | its tests pass; `module check` accepts its health; on the first machine both checks are stated healthy |
@@ -448,7 +448,7 @@ open:
composes the field — the endpoint as the port the machine published it on, the defaults written out — only
for a machine whose newest statement says so, and strips it for an older engine, which parses strictly
and would refuse the whole declaration. So the engine rolls out first, then the controller, and the
catalogue declares only once that controller runs: until then the composition check refuses a declaration, which
catalog declares only once that controller runs: until then the composition check refuses a declaration, which
is the protection working.
- **The engine's looks.** http and tcp from the machine to the published port; a redirect is an answer and
is not followed; a certificate is not judged. A unit's readiness is read from the show liveness already
@@ -481,8 +481,8 @@ machines: one condition, urgent, listing all three; their gates wait; after reco
failing is raised), which fails with four conditions when the hold is taken out.
**Phase D — the bed.** In mesh-lab's replays, which every merge check of a module of the graph already runs
from the lab's trunk with the runtime and the change's catalogue — so nothing else had to change for the
catalogue's check to start it. It proves the resources whose declared check or image the change touches
from the lab's trunk with the runtime and the change's catalog — so nothing else had to change for the
catalog's check to start it. It proves the resources whose declared check or image the change touches
(every declared one when it cannot tell), each alone: its literal environment, the files its module writes
in full, an empty place for every other mount, no secret and no provider. A program that stays up while its
check does not see it fails the change; one that does not stay up alone is said and left to the first
@@ -490,15 +490,15 @@ machine's gate; a mesh-built image and a tool or unit check are said. The replay
bound to the address its hostname names, and an image check asking the loopback — fails the bed, and passes
once the hostname is set to every address.
**Phase E — the migration.** The catalogue keeps the count in a file of its own, and its merge check fails
**Phase E — the migration.** The catalog keeps the count in a file of its own, and its merge check fails
a change that raises it and one that lowers it without writing the new number. It starts at 93 long-running
resources. The first batch takes it to 70: the image checks of the seven modules that ship them, adopted where
they read healthy on the live mesh — except the mail antivirus, whose six-minute start is past the bound,
and the mail cache, whose image ships none — and tcp or http on endpoints four services already declare.
Still to do for these phases' "done when": each read on the live mesh once rolled out in order — the
node-engine, then the controller, then the catalogue's declarations; the count's first live reading; and
the bed's first run on a catalogue change at the build seat.
node-engine, then the controller, then the catalog's declarations; the count's first live reading; and
the bed's first run on a catalog change at the build seat.
## As built — Phase F
@@ -508,7 +508,7 @@ open:
- **The look.** Every 30 s, on the liveness loop's tick. The resolvers are asked concurrently, three
questions each, with a reply read over raw UDP so "no such name" and "none" are told apart. The tunnel is
read with the tunnel tool's handshake and allowed-address listings, never its dump, which holds the
private key. The hub is the peer whose allowed addresses are a range. The judge keeps nothing on disk.
private key. The hub is the peer whose allowed addresses are a range. The node-engine's network probe keeps nothing on disk.
Its two looks start afresh when the engine starts.
- **The statement.** A `network` beside `resources` in the health statement. The controller reads the
statement leniently, so the engine rolls out first and the controller after, and an older controller
+4 -4
View File
@@ -29,7 +29,7 @@ shape — what each is for, where its records live, and how they depend on one a
| Domain | Purpose | Its records live in |
|---|---|---|
| **Module** | to say what one module is, in the manifest every other domain reads | the catalogue, one manifest per module |
| **Module** | to say what one module is, in the manifest every other domain reads | the catalog, one manifest per module |
| **Core** | to keep the controller, the bus, the store and every node's engine running and agreed | the controller and the store |
| **Placement** | to decide, send and apply what each node runs, and say why | the controller's `inventory` database |
| **Provisioning** | to resolve which module serves a provision for which consumer, and wire the two | the controller |
@@ -134,7 +134,7 @@ rule stands with the new word: where a domain's records live in the controller,
on a head word defined twice or also retired. Decision records are never checked. A document that cannot
be reworded at once is named with a date in the check's allowance list; a graduated research effort may
be kept there, as a record of what was said.
- **In the catalogue**, its own repository check reads a copy of the words retired for the tools and fails
- **In the catalog**, its own repository check reads a copy of the words retired for the tools and fails
when what a module's tools show an agent uses one. The copy and the glossary are compared whenever both
are at hand; a change retiring a tools word changes both repositories.
- **Homonyms** are checked by review: the reviewer looks for the bare word in the diff.
@@ -145,8 +145,8 @@ rule stands with the new word: where a domain's records live in the controller,
`node-build-agent`, the licence manager's `release`, the controller's `plan`, `doctor` and queue verbs,
the packet filter module's tool — each in its own repository's change.
- **The descriptions served by the core's own repositories** (the controller's, the node-engine's and the
tool runner's verbs) are outside the catalogue and so outside its check.
- **A probe of the served descriptions** in the self-check, once the catalogue's check has run a while.
tool runner's verbs) are outside the catalog and so outside its check.
- **A probe of the served descriptions** in the self-check, once the catalog's check has run a while.
- **A domain on each decision record**, which would let the reading order be printed per domain; a change
to the record schema, not made here.
- **The reverse rule** — a design defining a word must find it in the glossary — proposed by research 034
@@ -48,7 +48,7 @@ another. A *routing domain* is a domain whose names a resolver sends to one link
|---|---|---|
| the seat `node-resolver` | the controller's set | a node seat, its verbs `routes`, `route`, `unroute`, required of every holder |
| the stepping back | the controller's composition | where a module holds `node-resolver` and renders `/etc/resolv.conf`, the uplink holder's rendering of it is left out |
| `systemd-resolved` | the catalogue | holds the seat, provides `split-dns` at the machine's reach, writes the file and resolved's drop-in, runs the guard |
| `systemd-resolved` | the catalog | holds the seat, provides `split-dns` at the machine's reach, writes the file and resolved's drop-in, runs the guard |
| the guard | `systemd-resolved`'s process, as root | keeps the file the module's, keeps an outside write, serves the verbs on the machine's socket |
| the adapter | `forticlient`'s process, as root | reads the client's write, routes its domains over its tunnel, takes the write, takes the route away when the tunnel goes |
@@ -3,18 +3,46 @@ layer: to-be
status: in-progress
code:
- mesh-controller cmd/mesh-controller (the verbs artifacts, collect, images and mirrors), internal/builder (copied bases), internal/inventory (artifact_mirrored)
- mesh-catalog modules/artifact-store-tools (the store's tools), modules/distribution (its unbuilt code removed)
- mesh-catalog modules/gitea (package retention)
- mesh-catalog modules/artifact-store-tools (the store's tools), modules/distribution (its program, holding the two image seats)
- mesh-catalog modules/gitea (package retention; the two package seats' verbs in its Go bundle)
- mesh-catalog modules/mesh-build-go, modules/mesh-build-node, modules/mesh-build-image (publishing through the seats)
- mesh-delivery modules/mesh-delivery-builder (versions, tag asks; from milestone G a package numbered at its publication, the seat `mesh-builds`), the forge bridge, the indexer, the checker, the assigner, modules/mesh-delivery-pipeline (`tag-wanted` from milestone G)
- mesh-sdk (the bus helper for sending in parts)
- mesh-catalog modules/docker (image pruning)
updated: 2026-10-12
- mesh-host internal/apply (every new image of a module pulled before any of its containers is replaced; a failed pull applied again on the status view's `settled` for the store's holder, and at the node-engine's start), internal/compose (each routed image reference written with its seat and that seat's holder)
- mesh-delivery modules/mesh-grants (what a node-engine hears: the status view's `settled`)
updated: 2026-11-10
decisions:
- "ADR 0667"
- "ADR 0666"
- "ADR 0605"
- "ADR 0612"
- "ADR 0614"
- "ADR 0613"
- "ADR 0617"
- "ADR 0618"
- "ADR 0624"
- "ADR 0606"
- "ADR 0607"
- "ADR 0610"
- "ADR 0611"
- "ADR 0627"
- "ADR 0595"
- "ADR 0596"
- "ADR 0615"
- "ADR 0620"
- "ADR 0621"
- "ADR 0346"
- "ADR 0386"
- "ADR 0564"
- "ADR 0240"
- "ADR 0311"
- "ADR 0251"
- "ADR 0189"
- "ADR 0257"
---
# 51 — The registries keep what is named
# 51 — The registries: what is published, under which version, and what is kept
**Three places hold built things: the artifact store, the package registry and each machine's
container runtime. Each gets tools that say what it holds, what names each thing, and what could go.
@@ -24,6 +52,580 @@ registry, and the machine's declaration for its images.**
(ADR 0251,
extending ADR 0189.)
## What is published, and how (from 2026-11-03)
**Every registry is a seat; a build module publishes into it over the bus; the builder gives every version.**
(ADR 0605, ADR 0606, ADR 0607, ADR 0610, ADR 0611, from research 081.) What follows is the to-be shape; the sections from
*The parts* on keep what the registries hold, and stand. Every interaction below is a seat verb, a module's tool or an
event: no module reads or writes another's bus state (ADR 0596). A module asks another's data through its tools, and
asks work of another by an event of its own (ADR 0610 §1).
### The four registry seats
| registry seat | holds | read side it serves | holder today |
|---|---|---|---|
| `npm-package-registry` | npm packages | the npm registry protocol | the forge module |
| `go-package-registry` | Go modules | Go's module proxy protocol | the forge module |
| `container-image-registry` | container images | OCI distribution, with an image's own verbs (its tags, mirroring an outside image) | `distribution` |
| `oci-artifact-registry` | bundles and archives, by digest | OCI distribution | `distribution` |
Each is held once for the mesh. The last two replace the seat `mesh-artifact-store` and front the one artifact store;
while one module holds both, both deliver the provision `artifact-store`, and splitting them between two holders takes a
decision of its own. `mesh-artifact-store` stays served until every node-engine reports applied a build that reads the
new names (ADR 0610 §4); a sleeping node holds it open. `distribution` closes it itself. The status view's
`delivered` counts only the nodes present (an away node is normal, ADR 0603 §7), so it is only the wake-up, never the
proof (ADR 0610 §4, its progressive insight of 2026-11-03): at its start and on each `delivered` event, `distribution`
asks the status view's `node_haves` for every node, away ones included, and stops serving the old name once every node
whose declaration names an artifact has applied a build whose node-engine states the capability to read the new names
(ADR 0614 §4), judged by that stated capability and never by a fingerprint. Its tool `registry_old_name` lists the
nodes still holding it open, and drops a retired node from the window by hand, recorded as a hand act; a node holding
it open for seven days is a finding naming the node, cleared when the window closes. Closing the old name emits
`old-name-closed` (the old seat name, the time, the nodes that held it last, and the nodes dropped by hand) on
`distribution`'s own family `distribution.events`, kept seven days and capped at 16 MiB, dropping its oldest when
full (it carries a handful of events per window), never on a seat's `<seat>.events`: it is one module's window, not
the seats' contract. A node away when the last `delivered` was said should close the window when it returns and
applies the new build, with no other delivery: `distribution` also wakes on the node-engine seat's event
`mesh.seat.node-engine.event.manifest-reads-changed`, which each node-engine says when the capabilities it states
change and when its node returns after being away (ADR 0618 §4), and on it reads that node's stated capabilities
through the seat's verb `manifest-reads` (ADR 0618 §3), and its applied build through `node_haves`, never a watch of
the node-engine's have state (ADR 0596). `distribution` declares `seat:node-engine.manifest-reads` in its `invokes`:
that is the grant the grants part composes, and with it the grants part grants `distribution` the subscription to
the event's subject. A node-engine that does not yet serve `manifest-reads` counts as stating nothing: the window stays
open and `registry_old_name` names the node. A returned node that then applies the build whose node-engine reads the new
names says the event again, as its stated capabilities change, so ADR 0618 covers every node of this window and no
`delivered` is waited for. `cargo-package-registry` stays
named, without a holder, until a build module publishes cargo packages.
**One contract, a seat definition** (design 26, *A seat's definition*). Verbs: `publish`, `publish-part` (ADR 0611), `versions`, `remove` (a
tagged version; the holder itself refuses `remove` of a version with no tag, but for the retention removal below), and
on `container-image-registry` `mirror` and `tags`; the two seats `distribution` holds add `hold` and `release`,
with the events `held` and `released`, for the artifact sweep (ADR 0617 §2), both verbs in the seat definition and
in `distribution`'s caller list. The seats this milestone changes, these four, `mesh-broker` and the four it adds a verb or an event to, are defined
whole, their contracts moved into `mesh-contracts` (ADR 0613 §1, ADR 0620; design 26). Events: `published`, `refused` (added to ADR 0605 §2's two, additively) and `removed`, each
carrying the name, version, kind, tag, digest, fingerprint, commit and holder, and `refused` its reason; each seat's
events are its own family, `<seat>.events`, kept seven days. A holder stores
under the version it is given and counts nothing.
**Who may call which verb is the holder's to say**, in a trusted config value of the holder listing its callers, the
form ADR 0363 gives a restricted family: `publish` and `publish-part` the build modules, and a part only from the
proved caller that opened its transfer; `mirror` mesh-build-image; `remove` the builder, for a tagged version, and the
holder of the artifact sweep, for an untagged bundle, archive or copied base with the reason retention (ADR 0610 §3);
`hold` (on the two seats `distribution` holds: keep one untagged bundle, archive or copied base that the artifact
sweep's rules keep from removal by retention; never an image of its own) the module that runs the artifact sweep
alone (ADR 0617 §2); `release` (let a hold go) that module, and the operator's session only through
`registry_holds`, each release by hand recorded as a hand act. When `registry_holds`, `distribution`'s own tool,
calls its own seat's `release`, the caller the holder proves is the one the tool runner proved and stamped on the
`registry_holds` call, the operator's session (ADR 0386 §7), carried on to `release` by the tool runner's stamp and
never by the tool's own words; `distribution`'s own account is not on `release`'s list, so the tool cannot release in
its own name. Every removal, whoever asked it, emits `removed` with its reason.
Declaring `invokes` alone grants nothing. The holder checks the caller identity the tool runner proved and stamps on
the request (design 25 § 12.4), never a name in the request's body, and answers any other caller with a refusal naming
the verb.
### Publishing
```
builder ── build request (name, version or tag) ──▶ build module
│ publish(name, version, digests of every part)
▼
registry seat's holder ── answers the parts it lacks
│ the build module sends those parts, in chunks, by `publish`
holder: hashes what it received, asks `builder_versions`,
stores in its own store, emits `published` or `refused`
▼
builder (durable consumer: entry, done key), indexer, status view, checker
```
- **The file travels in parts through the seat** (ADR 0611). `publish` opens a transfer, naming it and the digest of
every part (an image's layers, a package's file, a bundle's blob); the holder answers the digests it lacks. The build
module sends only those through `publish-part` (transfer, part digest, sequence, last), each at most 1 MiB, with
mesh-sdk's bus helper for sending in parts, added to mesh-sdk's runtime in the milestone's one rebuild. A `publish` opening a
transfer already open answers the parts held, so a cut transfer goes on from there. The parts land in the holder's
own object store `incoming`, asked for as bus state in its manifest (design 25 § 12) with a cap of 8 GiB, the most the
objects template allows (design 25 § 12.1), and no lifetime, since that template keeps for good; the holder counts its
fill against the cap its binding carries, never a number of its own. The holder itself drops a transfer with no part
for 24 hours and deletes its parts (ADR 0611 §3), so an abandoned transfer does not stay. **Both are mesh-sdk's
`parts.Receiver`, shared by every holder** (ADR 0611 §3 for the drop, ADR 0627 for the shared receiving side), never copied into a holder: an expiring key per open
transfer, in a state of the holder with a key lifetime, is armed when a transfer is opened or opened again, and its
expiry (an event, never a timer) drops the transfer with its parts, or arms it again for the rest of the day if a
part came; a key that cannot be written fails the opening loudly. The cap is read once from the binding's fill and
kept; only where no binding is read does the holder state the 8 GiB it asked for. The holder hashes every part and refuses one whose bytes do not
match its digest. At 80 % of the cap it writes a finding (cleared below 80 %); at the cap it refuses a new transfer
with `refused` naming the cap. Its tool `registry_incoming` lists open transfers and the fill, and drops one by hand.
- **The holder asks the builder**, through `builder_versions`, whether the name, version and digest are recorded, and
refuses loudly otherwise (ADR 0605 §4). A rebuild of a held fingerprint answers the held version and stores nothing.
- **How a publish ends**: the holder emits `published` or `refused`. The build module waits for one of them, matching
on its transfer, name and version, at most
10 minutes, narrating "waiting on <seat>" at least every five minutes; past the bound it writes the key refused,
naming the seat, and the builder, hearing that build's end event as it does every build's, writes the finding for a
refused publish. A `published` that arrives after that is still heard by the builder on its durable consumer: the
entry turns `published` and the builder writes the done key then, so a late store is never lost.
- **What is published when**: a package or an image from a trunk build under its version, or as a tagged version; a
bundle or an archive from every done key by its digest alone, a candidate's included, and at the trunk's claim the
build module calls `publish` with the version and the held digest, which stores nothing. From the delivery of design
47's milestone G a package's version is given at its publication instead (*The versions*). An upstream image is copied
by `mirror` with its pinned digest.
- **The done key names the reference the seat answered**, in ADR 0605 §9's form from this milestone on:
`<registry>/<module>/<artifact>@sha256:<digest>` for an image, bundle, archive or upstream copy and
`<name>@<version>` for a package. A key in the old `artifact-store://` form keeps it, every reader reads both forms,
and none is built again for its form. A node-engine built before this milestone cannot read the new form, so a
want whose build carries it reaches a node only once that node's engine states the capability to read both forms
and both seat names; the assigner holds the node's want meanwhile and names the capability as the reason, and a
node away keeps its want and catches up on return (ADR 0612 §2, made general by ADR 0614 §4).
- **The forge's accounts and teams are what the catalog declares.** The forge module removes, at each start and
when its teams change, the teams and the accounts of the retired per-node package-reading form that nothing
declares any more; one the forge refuses to delete because it owns something has its login prohibited. How it is
checked: after a delivery the forge module's team and account tools list none of them.
- **No build module holds a registry's write credential** (ADR 0605 §5). The npm write token goes. The image push
credential and the artifact store's write binding that ADR 0605 §5 revokes do not exist today: the store takes
writes from any process on the mesh network, so the rule protects nothing until its write side is closed. So
`distribution`'s own program serves the store's port in front of the registry container, which listens on its
node's loopback only: reads (the OCI distribution protocol's GET and HEAD) stay open to every node's container
runtime, and a write reaches the store only from `distribution`'s own process, after a `publish` it accepted.
**Until every build module publishes through the seats**, a window, the build modules'
builds still running push straight to the store, as they do today, with no credential: today's store takes an
unauthenticated OCI write from the mesh network, and no build module holds an image push credential. So
`distribution`'s program keeps accepting such a write from the mesh network, no wider than today, until every
node's have of every build module, read through `node_haves` at its start and on each `delivered`, runs a build
that publishes through the seats; then it refuses every write but its own process's, naming `publish`, says so in
its log and emits `direct-writes-closed` (the time, the build modules' builds last seen, the nodes dropped by hand)
on `distribution.events`. While the window is open, a direct write to a tag the seat holds `published` is refused,
naming the tag and `publish`, so an old build module cannot overwrite a version published through the seat. Since the
window has no credential, closing it removes nothing from the store or the
vault: it is the program's refusal alone. Its tool `registry_direct_writes` lists whether the window is open and
the nodes whose have still runs an old build module, and drops a retired node from it by hand, recorded as a hand
act; a node holding it open for seven days is `distribution`'s finding naming the node, cleared when the window
closes. **While the program is down**, the store answers no read and no write: a node pulling an image fails and
retries, a build module's write fails and its build says so, and what already runs is not touched. The holder's
health check is declared in its manifest and run outside the program's process, as every module's (ADR 0240), so
it still answers while the program is down: it probes the read side every minute and names the program. The
program serves again at once when it restarts, holding nothing but its transfers in `incoming`. Each holder keeps its write side as an own secret beside a read-only tool token (the forge module: `write:package`, its
tool token `read:package`).
- **`distribution`'s first delivery** moves the registry container to its node's loopback and lets the program take
the store's port, and it is the one delivery whose own containers serve every pull. Read on the node-engine's main
(its apply of a container): the node-engine pulls a container's new image just before it replaces that container,
then sets the running one aside, stopped, starts the new one, and starts the old one again if the new one does not
run (issues 1742 and 1945). It does so one container at a time, so a module with two containers pulls its second
image only after its first container was replaced; for `distribution` that second pull would meet the stopped
registry. **So the node-engine pulls every new image of a module before it replaces any of its containers**, and a
pull that fails replaces nothing, the module keeping what it ran: a change in the node-engine, a subtask of this
milestone's node-engine work. The quick fix, a second port for this one delivery, is refused, since every module
with more than one container meets the same order. `distribution`'s declaration lists the registry container before
the program, so the port is free when the program starts. **What a pull meets in the swap**: from the registry
container's stop until the program listens on the port, the store answers nothing. On main, a failed pull fails that
module's apply, and the node agent tries a failed apply again only on the next change of the module's want or
composition, on the node-engine's verb `compose` naming the module (by hand), or when its liveness probe finds a
declared resource missing or down; only a failure of the bus itself is tried again on a clock (a bounded backoff,
at most four times before the have says failed). So another module's apply whose pull falls in that window stays
failed, its running containers kept, until one of those: its have says failed naming the image.
**So a pull that falls in the swap is tried again when the store's holder has settled, never on a timer.** Neither
the condition keeper's `condition-cleared` (ADR 0564 §3) nor the status view's `delivered` comes in the swap: a
finding of the holder held during its own delivery raises no condition and so no clear (ADR 0564 §13 (c)), and
`delivered` waits for every have to equal its want, which the failed have itself blocks (design 47). The status
view's `settled`, said once for a module on a node at one composition when its have reaches its want running and
healthy (design 47), is blocked by nothing else. `distribution` claims a seat held once for the mesh and runs on
one node, so the node-engine on every node hears `settled` for the store's holder, on whichever node the holder
runs, and then applies once more each module on its own node whose have says failed naming an image of that store,
said in its journal. **No `settled` is missed in a race**: the node-engine keeps in memory the last `settled` it heard
for each holder since its own start, never reading the status view's state (ADR 0596). When it records a pull
failed against a store, it compares the pull's start with that event's time: only when a `settled` for that
holder was heard after this pull started does it apply again at once. That is the one retry, once per `settled`: a
second failure after the same `settled`, or the at-once retry failing again, starts no further apply. It finds the holder by the seat the failed image came through, read from its
declaration, never by a module's name: **the composition writes, beside each image reference it routes, the seat the
reference came through and that seat's holder**, taken from the holdings the composition already has, so the retry
matches `settled` by the holder its declaration names. A change of the seat's holder composes the declaration
again, so the name it carries is the holder of now. The seat and the holder are not part of what a container is
(they are not in its digest), so a declaration composed again for them replaces no container. **The seam that changes is the grants part's list of what a node-engine
hears** (`NodeAgentHears`; the node-engine declares no `consumes` of its own): it gains one entry, the status
view's `settled` family, which the node-engine filters for the holder of the seat its failed image names. **At its
own start** the node-engine also applies once more every have that failed naming an image of a store, so a restart
or an absence across the swap misses nothing. A module already being applied is not applied a second time; a retry
whose pull fails again says failed again and starts no further apply. A `settled` of any other module starts
nothing, and no clock starts an apply. `compose` naming the module stays, but only as the hand recovery of a pull
still failed after that, recorded as a hand act; it is no step of the delivery.
- **The package seats' read sides need no credential** for the mesh's own packages: the forge serves the mesh owner's
packages to anonymous reads, so the provisions `npm-package-registry` and `go-package-registry` carry no
credential (form none), and mesh-build-node, which held a pair for both writing and installing, requires none (the
operator's answer of 2026-11-03, that the mesh's packages may be read without a credential). Public reads stay (the
operator, 2026-11-04): the forge's package reads and the store's GET and HEAD answer anonymously on the mesh network
and, where a public route serves them today, through it, the forge's public route included. The forge keeps serving
the registry's public root (ADR 0346 §6, unchanged), so a lock file naming that root installs as today, and the lab
trusts it as before (ADR 0346 §7).
- **The forge module serves both package seats' verbs from its Go bundle**, the one that already serves its package
retention, renamed for both packages; its tools bundle in TypeScript is unchanged, so no holder needs generated
TypeScript types in this milestone.
- **Go packages** are fetched through the Go seat's provision first and Go's public proxy second, with no `GOPRIVATE`
and the checksum database off for the forge's paths (ADR 0605 §6); `go.sum` and the digest the builder records (Go's
`h1:` hash, computed by the Go build module at the publish) refuse a mesh package with other content. For this
milestone the fetch keeps a third source last, the forge's git over the build module's own account (Go's `direct`):
between the recipe change and the first numbered versions of mesh-sdk and `mesh-contracts` in the Go seat, a build
by the new recipe could otherwise fetch nothing it names. The first change after those versions are in the Go seat
removes `direct`, said in its pull request. The builder also tags each Go version in git (`go/v0.1.<n>`), so a user
that names a version can fetch it from the forge's git as well. No mirror of outside modules is built; one could
come later as a holder of a seat of its own.
### The versions
- **From the delivery of design 47's milestone G, a package is numbered when it is published** (ADR 0666 §15). The
builder numbers a package's version at its publication, never only when its build is claimed: a package's trunk
build is claimed with no number and built by its digest, and once its build is done the builder gives it the next
count of its series, under compare-and-set, and says `numbered`, on which the build module calls `publish` with
the version and the held digest, as below for a floor not yet known. A build of an older source revision of the
same watched branch than one already numbered for that name is not numbered and publishes nothing, so a version never
names older content than the one below it. When the holder says `published`, the builder says the publication as the
event `package-published` of its seat `mesh-builds` (the name, the version, the fingerprint, the commit, the watched
branch). On it every artifact with a "published before it builds" edge to the package is rebuilt against the new
version, and the pipeline runner, which consumes the event, starts its pipeline (ADR 0666 §15; design 47, *A publish
rebuilds*);
nothing else is rebuilt, and a change to a package's tests alone publishes nothing. This removes the claim's wait
for earlier merges' numbers below, which held a group on 2026-11-09 (research 086, Findings). Why at publication: a
number given at the claim must wait for every earlier merge's number, and a build that never publishes keeps a
number nothing holds. An image, bundle or archive keeps the rule below. How it is checked: in the builder's
whole-module test a package's trunk build is numbered only once built, an older revision's build after a newer one
publishes nothing, `package-published` is said once per publication, and only the importing artifacts rebuild
(design 47, test 80).
- **A build that cannot read the published packages refuses**, naming the unread state, never building against a guess
(ADR 0666 §15; design 47, test 70).
- **Until that delivery, the builder numbers every trunk build** of a package, image, bundle or archive at its claim: the package series
its manifest declares (design 32; `0.1` when it declares none) and the next count for that name, under
compare-and-set. Numbers follow the order of the forge bridge's merge events: a claim of a later merge waits until
every earlier merge of the same name whose fingerprint the indexer still holds is numbered (a fingerprint replaced
by a later merge before its claim is skipped, design 47 *After the merge*); a wait past 30 minutes writes a finding
naming the merge it waits on. A fingerprint already numbered keeps its number.
- **A package is numbered per source revision**, not per fingerprint: a second trunk build of a revision already
numbered for that package (a build module's change reaching it by a second build, ADR 0603 §3, or the contracts
move's one rebuild) keeps the package's version and publishes nothing, since a package's content is its source,
but only when `versions` holds that revision `published`; a revision numbered but never stored is published by its
next build under the same version. The build log says the version was kept, and why.
So a publish that triggers a rebuild of the package's own build module (the shared contracts, the forge module
that holds their registry and the Go build module that builds them, ADR 0614 §6) never comes round to a new
version, and the triggers end. An image, bundle or archive is numbered per fingerprint, as above.
- **The builder's state `versions`** holds one key per name, tag and version, with its fingerprint, commit, digest,
time and state: `numbered`, `published`, `refused` with its reason, or `removed` with the time, the reason (a
branch's end, retention, the sweep) and the event that removed it. History one, cap 64 MiB, the most the template
state allows (ADR 0595 §3). An estimate, not a count: about 30,000 keys a year (some 18,000 trunk versions, about
50 numbered builds a day, and some 10,000 tagged ones) of about 0.5 KiB each, some 15 MiB a year, so the cap holds
about four years at that rate; past 80 % the builder writes a finding, cleared below it. Only the builder reaches it; others call `builder_versions` or hear its events. The build log
carries each change too.
- **The floor**: on a name's first claim, or when `versions` holds nothing for it, the count starts above the highest
of the seat's `versions`, the package's highest git tag (the forge bridge's tool `bridge_tags`) and the highest
pseudo-version a consumer requires (the indexer's tool `indexer_requirements`). The builder numbers nothing for that
name until all three answered (ADR 0606 §3), and writes a finding naming the silent one meanwhile, cleared once all
three answer. Today that gives Go `v0.1.14` and npm `0.1.18`; a name with none starts at `0.1.0`.
- **An unknown floor does not stall the build of an image, bundle or archive** (ADR 0617 §1 for an image). The floor of `distribution`'s own
names is `distribution`'s `versions`, which only its new build serves, and the same holds for the forge module and
the builder: waiting would never end. So a trunk build of an image, bundle or archive whose floor is not yet known
is claimed with no number, so none travels in its build request, built unnumbered and published by its digest (as a
bundle or archive is from every done key, ADR 0605 §3; an image so by ADR 0617 §1). Such fingerprints are numbered
in merge order once the floor answers (ADR 0606 §1). What wakes the floor is an event of the source that was
silent, never a timer: for the seat's `versions`, the holder's `published` on the builder's durable consumer of
`<seat>.events`, which that by-digest publish itself says; for `bridge_tags`, the forge bridge's next message on
its stream `forge`, which the builder already consumes; for `indexer_requirements`, the indexer's next
`manifest-accepted`; and for each, the condition keeper's event clearing the silent module's health condition, on
the seat `mesh-conditions`' family (ADR 0564 §3), so a source that recovers with nothing to say still wakes it. On
any of these the builder asks the silent sources again; beside them, its tool `builder_floor_again` asks the three
sources of one name again at once by hand, recorded as a hand act. Once all three answer it numbers the build and emits
`numbered`, which the build module consumes to call `publish` with the version and the held digest, which stores
nothing. A package's trunk build waits for its floor, since a package is published only under
its version.
- **Events of the builder**: `numbered` (name, version, tag, fingerprint, commit, head when it answers an ask), on its
own family, kept seven days; a waiter on a build's end does not wake on it. **Tools of the builder**:
`builder_versions` (a name's versions in order, one call), `builder_publish_again` (one fingerprint under its number,
after a holder failed; when the build's file is gone it builds the fingerprint again under the same number, and the
new digest replaces the recorded one only if no `published` was ever emitted for that number, else it takes a new
number; it refuses a version refused for other bytes), `builder_tag` (ask a tagged version), `builder_tag_asks` (open asks and
their state), `builder_untag` (remove a branch's tagged versions), `builder_floor_again` (ask a name's floor
again by hand, a hand act) and `builder_old_form` (below).
### Tagged versions
- **Asked by an event, never by a push** (ADR 0610 §1). The checker emits `tag-wanted` (repository, branch, head,
tag), on a family of its own, `checker.asks`, kept seven days, apart from its verdicts, so a waiter on a verdict does
not wake on it, for each head of a delivery group member that declares a package; a person asks through `builder_tag`.
From the delivery of design 47's milestone G the checker goes, and the pipeline runner says `tag-wanted` instead, on
its own seat `mesh-pipeline-runner`, for each member that declares a package of a run on request of a group not yet
merged (ADR 0666 §18): a group merged together is one source revision whose packages are published before its
dependents build, so only a run on request needs a tagged version. The
builder consumes the event on a durable consumer and keeps the ask in its own state `tag-asks`, removed when its
branch is merged or deleted, or its pull request closed. An ask the builder has not answered within five minutes is narrated in the build log
with what it waits on.
- **Numbered below the next version** (`0.1.15-feat-x.2`), never the latest; npm keeps it under a dist-tag of its own
and Go's `@latest` skips it. A package new in a group is numbered from its floor (`0.1.0-feat-x.1`).
- **A group's check builds after `published`**: Go members by the tagged version, TypeScript members with their lock
naming it and the registry's integrity; nothing is packed for a check, and a lone pull request's check publishes
nothing. No `published` within the publish's bound (10 minutes) fails the check naming the package. From the
delivery of design 47's milestone G the same holds for a group's run on request, whose pipeline steps build after
`published`, and a step that gets no `published` within the bound ends failed, naming the package.
- **Removed with its branch**: on the forge bridge's `merged` event, its pull `closed`, or its branch-deleted event,
heard on a durable consumer, the builder
calls each seat's `remove`. It acknowledges the event only once every seat emitted `removed`; until then it retries
every minute and, past 15 minutes, writes a finding naming the seat. A version with no tag is not removed by a
branch's end; retention may remove an old unreferenced one (below).
- **The forge bridge says a branch's end**: beside its `merged`, `refused`, `open` and `pull` kinds on its stream
`forge`, it says a branch-deleted kind, from the forge module's `forge.delete` event, which it consumes on a durable
consumer as it consumes the pull events. Only the forge module's account may publish `forge.delete`, the subject
being in its own namespace (design 32 § 2), so no other module can end a branch's tagged versions. Every existing
consumer of `forge` ignores a kind it does not know. Its tool `bridge_tags` answers a package's git tags, for the
floor.
### Retention
The retention of *The package registry* below, and the artifact sweep, keep working, now through the seats: each
removal emits `removed` and the builder marks its entry, so `versions` never says `published` for bytes that are gone.
With the store's write side closed, the artifact sweep (seat `mesh-artifact-sweep`, held by artifact-store-tools) no
longer deletes or holds by writing to the store: it calls `remove` on the seat that holds the thing, with the reason
retention, and `hold` to keep an untagged bundle, archive or copied base its rules keep from removal by retention,
which then skips it (ADR 0617 §2), both granted to its module alone by `distribution`'s caller list; its rules of what is kept (*The artifact store* below) stand, and it reads both reference forms.
`distribution` keeps the holds in its own state `holds` (bus state, template state), emits `held` (the thing's
name, kind and digest, the caller that asked, the time) and `released` (the same, and who let it go: the sweep, or
the operator's session by hand) on the seat's `<seat>.events`, and its tool `registry_holds` lists what is held,
since when and for whom, and releases one by hand through the seat's `release`, recorded as a hand act. A `remove` or `hold` the holder refuses to the sweep writes the sweep's finding, naming the
thing and the reason, cleared by its next run with no refusal.
The Go seat keeps what the npm seat keeps: every referenced version and the newest five of each package series. A
Go version is referenced when a `go.mod` on a repository's default branch requires it; the forge module reads every
`go.mod` as it reads lockfiles, and a `go.mod` it could not read stops a real run before anything is deleted, as an
unread lockfile does.
### Health and conditions
Observers write findings; the condition keeper raises and clears the conditions from them (ADR 0564). Findings: a
publish refused (the holder when it refuses, the builder when a build module's bound ran out; cleared when that version
is stored, or when a later version of the name is published), a registry seat not answering (each holder's health check,
which calls `versions` on each seat it holds and probes the read side every minute, so a dead seat is seen with no
publish running), a removal not done (the builder), a floor source silent (the builder), a store past 80 % (the holder,
the builder), a node holding the old seat name open for seven days (`distribution`, cleared when the window closes), a node
holding open the window of direct writes for seven days (`distribution`, the same), a node holding open the window of
the node-engine's old-form done key for seven days (the builder, the same). A build narrates its publish: asked, waiting on a seat, stored, refused.
### The move, one milestone, ordered by the module graph
The move is one milestone: one delivery group, one check, one merge (ADR 0612 §1, with design 26's seat definitions
and design 32's manifest words; ADR 0613 §1 adds the bus module's work and the knowledge base's). Its order is not
a sequence of deliveries but edges of the module graph, which the indexer keeps and each delivery part waits on by
its own rule; nothing stores the order (ADR 0612 §2, ADR 0614 §1). The edges this move relies on:
| Order | Edge | Kept by |
|---|---|---|
| A build module's build that publishes through a seat runs only after a holder build serving `publish` and `publish-part` runs healthy | served verb: each `invokes` entry of a seat verb or module tool is an edge to the module whose build serves it (ADR 0614 §2). The provision edge alone is empty here: today's holder builds already offer `npm-package-registry` and `artifact-store` | the assigner, counting the holder's own have as ADR 0603 §5 counts a provider's; the status view names the wait |
| A holder's check of `builder_versions` and the builder's `remove` | the two calls close a cycle, so both verb edges on it are left out of the graph and the calls retry (ADR 0614 §3); the builder retries `remove` each minute with its 15-minute finding | the indexer's graph, naming each edge left out |
| mesh-build-go's fetch from the Go seat only after the forge module serves its read side | provision: `go-package-registry`, offered only by the forge module's new build (ADR 0603 §5) | the assigner and the provisioner |
| No credential goes before its replacement works | the build modules' manifests drop the write credentials in the same change that makes them publish through the seats, so the vault mints none for the build that publishes (ADR 0612 §2) | the served-verb edge above |
| A build carrying the new reference form, or a manifest using this milestone's words or seat names, reaches a node only through a node-engine that reads them | a reader's capability the node-engine states, the baseline when it states none (ADR 0614 §4) | the assigner, holding that node's want and naming the capability |
| The holders' `incoming`, `<seat>.events`, `distribution`'s `holds` and `distribution.events` exist before the holders start | bus state: each entry is a requirement on the provision `bus-state` of the bus module (ADR 0614 §5) | the assigner, as for any provision |
| The shared contracts, the forge module that holds their registry and the build module that builds them | package and build module edges are triggers, never waits; the cycle they make holds nothing and is not refused (ADR 0614 §6); inside the group every member takes `mesh-contracts` and mesh-sdk by the group's head (the checker's group pin) | the indexer's graph |
**How many builds** (ADR 0603 §3). The three build modules change in this milestone, so a module they build can
be built up to three times in one window, and this milestone expects that count: once with the recipe that runs,
once more when the agreement of the build nodes moves to the new build module, and once more when a first numbered
publish of mesh-sdk or `mesh-contracts` triggers their users (ADR 0614 §6). The contracts move rides the first
build and adds none (ADR 0613 §1). ADR 0614 bounds nothing here; a bound, such as a settle before building a
fingerprint whose inputs still move, is a question for a record, put to the operator, and is not designed here.
**Every build keeps the old reference form** while any node-engine the mesh counts states it alone, away ones
included, the node-engine's own builds as every other, never by a module's name (ADR 0624 §1; ADR 0601 §4). The
builder writes into every build key each reference form a counted node-engine states, beside the new form, which it
writes only once every present node-engine states it (ADR 0618 §2); a counted node whose engine states nothing counts
as stating the baseline's forms, and a node leaves the count only when it is retired, never because it is away (ADR
0624 §1). Of the forms kept, the oldest a counted engine states is written into the build key's single reference
(ADR 0605 §9) and the others are listed beside it, so an engine that predates the list still fetches the build (ADR
0624 §3). The assigner holds a node's want for a build's reference forms only when that node's engine states none of
them (ADR 0624 §2); a hold for a manifest word or a seat name the engine does not state stays as ADR 0614 §4 has it.
So a node back from being away with an old node-engine still gets any build, the node-engine's own included, through
the oldest form, and can always update itself (ADR 0603 §7, §9). The old form in the build keys is a window like the
old seat name's: it closes when no counted node-engine states the old form alone, and the builder then leaves it out
of new build keys. The builder reads each node's stated capabilities through the node-engine seat's verb
`manifest-reads` (ADR 0618 §3) at its start, and wakes on the seat's event
`mesh.seat.node-engine.event.manifest-reads-changed`, said when a node's stated capabilities change and when the node
returns after being away (ADR 0618 §4), never on a watch of the node-engine's have state (ADR 0596) and never on a
timer. The builder declares `seat:node-engine.manifest-reads` in its `invokes`: that is the grant the grants part
composes, and with it the grants part grants the builder the subscription to the event's subject. A node-engine that
does not yet serve `manifest-reads` counts as stating the baseline's forms: the window stays open and names the node.
Its tool `builder_old_form` lists whether the window is open and the counted nodes, present or away, whose
node-engine states the old form alone, and drops a retired node from the count by hand, recorded as a hand act; a
node holding it open for seven days is the builder's finding naming the node, cleared when the window closes. Closing
it says so in the build log and emits `old-form-closed` (the time, the nodes that held it last, the nodes dropped by
hand) on the builder's own family beside `numbered`; a waiter on a build's end does not wake on it.
**When the group is pushed.** Only once the release that adds the node-engine's stated capability (design 47) runs on
every node, read from the status view's haves before the push, and once the progressive insights of ADR 0595 and
ADR 0597 this design is written to are accepted. No release of the manifest validator goes ahead: the indexer and the assigner
serve their first views as tools of their own, in a form the running manifest validator already takes in (ADR 0621 §4; design 25
§ 12.2). A node away for weeks does not hold the push for ever: it is left
out of that read only by a recorded hand act naming the node and why, as `registry_old_name` drops one, said in the
group's pull request; the node then takes the new node-engine as any away node does when it returns.
**The milestone's own check** runs the changed build modules (ADR 0603 §10) against the running holders, which serve
no `publish`: a changed build module whose manifest invokes a verb no running build serves is one the check cannot
run, and the modules it builds are composed from their manifests, the verdict naming them and the verb (ADR 0614 §7).
**The foundation's deciding parts** (the builder, the checker, the indexer, the forge bridge) keep their new state
(`versions`, `tag-asks`, the stream `checker.asks` and the like) in their old `state` and `streams` sections in this
milestone, so none of them waits on the bus module's process, which needs them first; the holders ask theirs as bus
state.
**Before the merge, the operator is told** two things that come with it: mesh-build-node no longer requires
`npm-package-registry`, so its provision key goes retiring and the provisioner asks the operator once per consumer
(ADR 0570 §5); and closing the store's write side changes nothing the operator sees. `package-version.sum` and its
guard go in the same change (ADR 0606 §6, read with ADR 0612 §1).
**Rolled back by one revert** (ADR 0612 §4): reverting the milestone's merge brings back the build modules'
manifests that require the write credentials, so the vault mints them again as own secrets on the revert's delivery,
and the builds that publish through the seats go with it. The old seat name still retires on the node-engines'
reports (ADR 0610 §4). The revert's order is the module graph's, as the move's is: `distribution`'s reverted build
is delivered before a build module's reverted build only where that build module's reverted manifest requires or
invokes something only `distribution`'s reverted build offers; the milestone's prepare step checks the build
modules' manifests for such an edge. The done keys written in the new form stay in the builder's state after a
revert and are not built again for their form; each still carries every form a counted node-engine states, the
oldest in its single reference, so a node is held from them only when its engine reads none of those forms (ADR 0624
§1-3). **On a fresh mesh** the foundation's bootstrap (research 075) pushes the holders' own images
to the store on its node's loopback, with no credential, as the publish contract allows for a write that reaches the
store from its own node, and records their references under the seat's reach. No one-off credential exists: the
node-engine writes no push credential and the holder's front keeps no bootstrap token. How the rest of the bootstrap
goes is research 075's. **A fresh mesh cannot raise the front of `distribution` by that push alone**: the front is
the holder's program, a bundle the builder builds and publishes through the front itself (ADR 0605 §7), so the
bootstrap must also push that bundle to the loopback store, and the holder's node fetch it there, with the first steps
naming the loopback reference until the front serves. That is the genesis fix of issue 1152, not this milestone's.
### Acceptance tests
Research 081's tests 1-3, 5-7, 9, 10, 12, 13, 15-20, 22 and 23 (its Direction) are this design's, with their labels.
Each integration test below is a case of its module's one whole-module integration test, which starts the module
against the real bus (test budget: mesh-delivery holds 76 integration tests today, over its 50; these add cases, not
tests, and each change that touches the builder's or the indexer's tests merges two old ones into its whole-module
test).
- **Builder.** A branch pushed with no ask publishes nothing; a lone pull request's check publishes nothing; a group
introducing a new package takes `0.1.0-<tag>.1`; the checker's `tag-wanted` yields `numbered` and `published`, and
members are built only after `published`; no `published` in 10 minutes fails the check naming the package;
`builder_untag` removes a branch's tagged versions with `removed`; a tagged version whose digest another tag names
keeps its tag on the store pinned today (a registry that cannot remove a tag alone), the holder answers `kept` with
that reason, `removed` is not said, and the builder records the version as kept on the store under its shared digest,
which `builder_versions` names so (it is not recorded as gone), and its bytes go with the other tag's removal, the move to a registry that
removes a tag alone being the next milestone's; a `remove` while the holder is down is retried and
past 15 minutes writes its finding; a late `published` after the bound writes the done key; `builder_publish_again`
after the build's file is gone builds again under the same number; with the seat's holder stopped at a first claim
nothing is numbered and the finding names it; two merges claimed in reverse order are numbered in merge order; a
retention removal turns the entry `removed`.
- **Builder, added in round 2** (integration, cases of the builder's whole-module test). Two merges close together,
the first replaced before its claim: the second is numbered at once; a build module's bound running out writes the
builder's finding, and a later version of the name clears it; `builder_publish_again` after a `published` takes a
new number.
- **Holder (gitea, distribution).** A caller not on the caller list is refused for each verb, and one module naming
another as the caller in the request's body is refused; a part sent by a module other than its transfer's opener is
refused; a transfer cut in the middle resumes from the parts held,
and one left 24 hours is dropped by the holder, its parts deleted; at the cap a new transfer is refused naming the cap
its binding carries, and the 80 % finding is written against that cap; a version a `go.mod` requires
survives retention, and an unreadable `go.mod` stops the run; a part whose bytes do
not match its digest is refused; only the missing layers are sent; `remove` of a version with no tag is refused;
with no publish running, a Go seat that stops answering while its holder runs writes its finding and clears it when it
answers (a holder down whole is its module's own health check's); `registry_incoming`
lists and drops.
- **Holder, added for the milestone, unit** (table cases of `distribution`'s caller list and store front): a write to
the store's port from any account but `distribution`'s process is refused, and a read is answered; the artifact
sweep's `remove` with the reason retention is accepted and the same call from another caller is refused; a `hold`
of an image or from another caller is refused; `release` from a caller not on the caller list is refused, a
`release` carrying the operator's session as the proved caller is accepted and `distribution`'s own account as
the caller is refused; while the direct-write window is open, a direct write to a tag the seat holds `published` is
refused naming the tag and `publish`.
- **Holder, added for the milestone, integration** (cases of `distribution`'s and the forge bridge's whole-module
tests): the sweep's `remove` removes an untagged bundle and emits `removed`; `hold` keeps an archive from
retention's removal, emits `held` and is listed by `registry_holds`, which releases it with `released` and records
its hand act; a refused sweep `remove` writes the sweep's finding and its next clean run clears it; the forge bridge
says a branch-deleted kind for the forge module's `forge.delete`, a `forge.delete` from another account is refused
by the bus, and an existing consumer of `forge` ignores the new kind; with the program stopped a read fails and the
holder's finding is written, a write fails too, and after its restart the read is answered and the finding
cleared; a build module's old build pushing straight to the store is accepted until every node runs a build
module publishing through the seats, and refused after, naming `publish`, with `direct-writes-closed` emitted and
its log line written; `registry_direct_writes` names the node still running an old build module, and drops it by
hand with a hand act; a node that was away, returning with the new build, closes the old seat name's window on
its `manifest-reads-changed` event with no `delivered` said (ADR 0618 §4); a waiter on a build's `published` does not wake on `held`,
`released`, `old-name-closed` or `direct-writes-closed`.
- **Builder, added for the milestone, integration** (cases of the builder's whole-module test): with the seat's
holder down at a first claim, a bundle's trunk build is built unnumbered and published by its digest, the holder's
`published` makes the builder ask the floor again and number it, and the build module, hearing `numbered`,
publishes the version with the held digest; a package's trunk build waits; with `bridge_tags` silenced (a floor
source other than the publish target) the floor finding is written and cleared once it answers, and with
`bridge_tags` still silent after the by-digest publish, the build stays unnumbered until the forge bridge's health
clears (no timer runs), and is then numbered and published by version; `builder_floor_again` asks the three
sources at once and records the hand act; a build key carries only the old form while one present node's
node-engine lacks the capability, or does not serve `manifest-reads`, and carries the new form beside it once every
present node states it (ADR 0618 §2), the old form in its single reference (ADR 0624 §3); with one node away whose
node-engine lacks the capability, or states nothing, every build still carries the old form beside the new, and any
build, the node-engine's own included, is moved to that node because it reads the oldest form (ADR 0624 §1-2),
`builder_old_form` naming that node meanwhile and dropping a retired one from the count by hand with a hand act; a
build whose forms that node reads none of is held for it; that node, back with the new node-engine, says
`manifest-reads-changed` and the window closes with no `delivered` and no timer (ADR 0618 §4), the old form left
out of new build keys, with `old-form-closed` emitted and its build-log line written, and a waiter on a
build's end does not wake on it; with the image's own seat silent
at the claim of `distribution`'s own image, the image is still built, published by its digest, and numbered once
its new build answers (ADR 0617 *How it is checked*).
- **Builder, added for the milestone, unit** (cases of the builder's numbering): a second trunk build of a package's
revision held `published` keeps its version and publishes nothing, while one numbered but refused is published by
its second build under the same version.
- **Node-engine, unit** (a case of its apply test, with the runner it already fakes): a module of two containers
whose second new image cannot be pulled replaces neither container, says the image, and keeps both running; with
both images pullable, both are pulled before the first container is set aside.
- **Node-engine, unit** (cases of its apply test, with the runner, the bus and the clock it already fakes): a
module whose pull failed, its have failed naming an image of a store, is not applied again with the clock moved
past the bus backoff's four tries and no event heard; it is applied once more, and its new image pulled, on a
`settled` for the holder of the seat its image came through, a `settled` said for the holder on another node
included; a pull that fails after a `settled` for its holder heard since that pull started is applied again at
once, while a `settled` heard before the pull started applies nothing at once, a second failure after the same
`settled` applies nothing, and a race retry that fails again starts no further apply; a
`settled` of another module applies nothing; at the
node-engine's start it is applied once more with no event; a module being applied when `settled` arrives is not
applied twice; a retry whose pull fails again says failed again and starts no further apply.
- **Node-engine's composition, unit** (cases of its composition test): a declaration's routed image reference names
the seat it came through and that seat's holder; a change of the seat's holder composes the declaration again with
the new holder named and recreates no container.
- **The grants part, unit** (a case of its composition test): a node-engine's subscriptions hold the status view's
`settled` family beside the backup holder's word, and nothing more; the subscriptions of `distribution`, the builder
and mesh-config, each declaring `seat:node-engine.manifest-reads` in `invokes`, hold the subject
`mesh.seat.node-engine.event.manifest-reads-changed`, and no other module's subscriptions hold it.
- **Checker.** A changed build module invoking a verb no running holder serves is not run, and the verdict names the
modules composed from their manifests instead, and the verb.
- **Vault.** Reverting the milestone's merge mints the build modules' credentials again; the bootstrap holds no
credential of its own to revert.
- **Round 1's fixes, unit and integration cases of the modules' existing tests.** A shared-digest tagged `remove` on the
store's 2.8 form answers `kept`; the idle drop fires on the key's expiry, including one that fell due while the holder
was stopped (checked at its start); `family-not-heard` is raised when a family stays silent past its bound, and the
builder's `publish-refused` and `publish-unanswered` findings name the name and the seat, each cleared when the
family or the answer returns.
- **Live.** The status view shows each build module's new build waiting on its holder's build serving `publish`
until that runs healthy (ADR 0612 *How it is checked*); no build module's provision key holds a write credential;
`registry_old_name` names the nodes holding the old name open, an away node among them. After the delivery:
mesh-sdk's first numbered version is `published` on the Go seat and an image is read back by its digest, both
shown by `builder_versions`; a node runs a module from a reference in the new form; a node-engine away across the
milestone wakes and applies the new node-engine; the node-engine's apply journal for `distribution` on each node
shows every new image pulled before its first container was replaced, and no node's pull of any module failed
during the delivery (each node's haves, none failed naming an image), or, where one fell in the swap, its have
turned healthy after the status view's `settled` for the store's holder, the node-engine's journal naming that
`settled`, and no `compose` was called for it; mesh-build-node installs from a lock file
naming the registry's public root with no credential. Go's `direct`: its removal is named on the milestone's issue,
and the change that removes it adds to the Go build module's recipe test a case that refuses `direct` in the fetch.
## Reviewed by architectural domain
The amendment of 2026-11-03 (ADR 0605 to 0611, research 081's graduation, designs 51, 26 and 32 together) was reviewed
by the four reviewers by architectural domain side by side (playbook 01), and the lead ruled on every finding. Two
findings reached a decision and became records: ADR 0610 (a module's bus state is its own, ADR 0596, so the checker
asks by an event and holders ask the builder's tool; retention; the old seat name closes on what node-engines applied)
and ADR 0611 (the file travels in parts through the seat). What was found, and what answers it:
| Domain | Found | Answered by |
|---|---|---|
| security | caller lists named only on the caller's side; the handed object's bytes unchecked; no caller identity; pull request seat definitions served as contracts; the bootstrap's credential | *Who may call which verb* (holder-side lists, the identity the tool runner proved); *Publishing* (parts hashed); design 26 (only the trunk's entry is the contract); *The move* (a one-off bootstrap credential) |
| upgrade | the steps moved no image, bundle or archive before their credentials went; Go users between steps 2 and 3; no node-engine reading the new forms before step 2 | *The move* (every move in step 2, a node-engine reading both forms in step 1, step 2 waiting on the node-engines' reports, git tags for Go, reverse-order rollback) |
| seams | five reaches into another module's bus state; a shared hand-off store; how a publish ends; how the indexer learns out-of-step types; no named path for the node-engines' reports | ADR 0610, ADR 0611; *Publishing* (`published` or `refused`); design 26 (the check's verdict event); the status view's `delivered` events and `node_haves` |
| tools | no read or drop tool for asks, transfers, the old name's window | `builder_tag_asks`, `registry_incoming`, `registry_old_name`, design 32's `config_renames` and `config_retiring` |
| running qualities | the versions value growing; the floor with a part down; merge order and a replaced merge; windows closing on wants; retention against "never removed"; a Go reference undefined; the in-transit cap | *The versions* (one key per version, a cap, the floor's wait, merge order skipping a replaced fingerprint); *Retention* (a Go reference); *Publishing* (the cap refused) |
| testing | failure paths untested; the test budget | cases of each module's one whole-module integration test, listed under *Acceptance tests* |
| health | conditions raised by their observers; no health check of a seat between publishes; a refused publish with no clearing | findings for the condition keeper (ADR 0564); the holder's health check; *Health and conditions* (each finding with what clears it) |
| events and logs | removal and `published` failing silently; a publish silent for 10 minutes; events with no family or retention | the builder's durable consumers and acknowledgement rule; narration every five minutes; each event's family and seven days |
The milestone's amendment (ADR 0612 to ADR 0614: one milestone ordered by the module graph, the new reference form
from it on, the store's write side closed, anonymous package reads, the floor and source-revision rules, the sweep
through the seats) awaits its own review by architectural domain, which rewrites this section.
## The parts
```
+2 -2
View File
@@ -56,8 +56,8 @@ The glossary holds the three words.
| part | where | does |
|---|---|---|
| seats `node-nfs-server` and `node-mounts` | the controller's closed set | node seats, capacity 1, with their verbs |
| `nfs-server` | the catalogue | holds `node-nfs-server`, provides the provision, writes its export file, runs the service, opens 2049 to the private network |
| `mounts` | the catalogue | holds `node-mounts`, writes a unit pair per share, keeps each share's state, serves the tools |
| `nfs-server` | the catalog | holds `node-nfs-server`, provides the provision, writes its export file, runs the service, opens 2049 to the private network |
| `mounts` | the catalog | holds `node-mounts`, writes a unit pair per share, keeps each share's state, serves the tools |
| the binding | the controller | gives a consumer the server's name; the consumer asks the server's seat for each share's path and access over the bus |
| the credential | the vault | per SMB source, the `mounts` module's own secret `smb-password-<source>` (a member of the family `smb-password-*`), issued outside the mesh and given with `secret accept` or typed at the desk prompt, unsealed on the node as a file; the username is the user part of the source's entry in the setting `sources` |
+37 -6
View File
@@ -2,7 +2,7 @@
layer: to-be
status: in-progress
code: [mesh-catalog modules/mesh-issues, mesh-catalog modules/claude-code, mesh-catalog modules/messenger, mesh-sdk]
updated: 2026-10-11
updated: 2026-10-26
decisions:
- "ADR 0275"
- "ADR 0278"
@@ -13,6 +13,7 @@ decisions:
- "ADR 0291"
- "ADR 0294"
- "ADR 0300"
- "ADR 0493"
---
# 53 — The issue tracker
@@ -81,7 +82,10 @@ agent finds them with `mesh_search` ("open an issue") and calls them as `issue-t
| `set` | a number and any of `severity`, `needs`, `suggested-owner` | changes them as a person decides (§ 10) |
| `tracking` | optionally condition keys | for every condition key an issue links, the issues that link it and where each stands: status, needs, worker, fix (§ 12) |
| `groom` | optionally `confirm` and a pass's id | the duplicate check over the backlog (§ 9): without `confirm`, starts a dry run in the background and answers its id; with the id alone, its progress and findings; with `confirm` and the id, applies exactly that pass's findings, each checked again |
| `import` (slice 3) | optionally `dry-run`, a commit | reads every issue folder of hq through the records module and writes each as an issue at its own number; creates what is absent, fills a status the tracker holds empty, never overwrites, never advances the counter; run again, changes nothing and says so |
| `import` (slice 3) | optionally `dry-run`, a commit, and `milestones` with a design's number | reads every issue folder of hq through the records module and writes each as an issue at its own number; creates what is absent, fills a status the tracker holds empty, never overwrites, never advances the counter; run again, changes nothing and says so. With `milestones`, it seeds that design's milestone records from its table instead (§ 13) |
| `milestones` | optionally a design, a status, or one milestone as design/id | the milestone records, each with its issues and their count by status; one milestone with its issues' rows and its history (§ 13) |
| `milestone-set` | a design, an id, an outcome, optionally an order, or `announce` | makes a milestone record, or changes its outcome or order; with `announce`, says the record again as its event (§ 13) |
| `milestone-move` | a milestone as design/id, a status and a reason | opens or closes a milestone; closing is refused while an issue linked to it is neither resolved nor wontfix (§ 13) |
Each verb's description says in plain words what it does and what it refuses, without the mesh's internal names, so
an agent picks the right one from `mesh_search` alone. A refusal says what was wrong and what would be accepted.
@@ -100,8 +104,8 @@ the issue's worker, who works on it, as the worker states it
- `located-in`: entries of the registered list of owners (repositories and modules), never free text;
- `fixed-by` (pull requests or commits), `amended-design`, `replay` or `replay-none`, and a reason for `wontfix`;
- `notes`: appended, each with who wrote it, when, and the text;
- `links`, typed: to another issue (`duplicates`, `relates-to`), a pull request, a decision record, a design, a
condition key (the issue **tracks** that condition, § 12) or a delivery;
- `links`, typed: to another issue (`duplicates`, `relates-to`), a pull request, a commit, a decision record, a design,
a condition key (the issue **tracks** that condition, § 12), a delivery, or the one milestone it belongs to (§ 13);
- `documents`: the report, and a diagnosis and a resolution when written, each with its author and date, revised in
place with its history kept (ADR 0291);
- `record`: the path of the issue's folder in hq, while one exists; none is opened any more, and the folders are
@@ -111,7 +115,7 @@ the issue's worker, who works on it, as the worker states it
kind `depends-on` (§ 10).
**The registered list of owners** is a setting of the module, changed through the controller's settings verb like any
other module setting. Slice 1 starts it with the repositories in hq's `00-META/repos.md` and the modules the catalogue
other module setting. Slice 1 starts it with the repositories in hq's `00-META/repos.md` and the modules the catalog
registers.
**An issue that has a folder in hq** kept its status in that folder's frontmatter until the import of slice 3 ran;
@@ -167,7 +171,7 @@ event carries a secret, and an issue holds none.
| any other status | no `by` and no `take-over`; the move ends the work |
| `located` | `located-in` names at least one registered owner |
| `resolved` | the issue is at `fixing` (or already `resolved`, to correct what it holds); `located-in`, and `fixed-by` saying what fixed it |
| `resolved`, for a core issue (its `located-in` names the controller, the node-engine, the tool runner, the SDK, or the catalogue's bus, forge or build agent) | `replay` (an id from mesh-lab's replays register) or `replay-none` saying why none is possible (ADR 0237) |
| `resolved`, for a core issue (its `located-in` names the controller, the node-engine, the tool runner, the SDK, or the catalog's bus, forge or build agent) | `replay` (an id from mesh-lab's replays register) or `replay-none` saying why none is possible (ADR 0237) |
| `wontfix` | a reason |
A refused move changes nothing and says which rule refused it. The rows for `diagnosing`, `fixing` and `resolved` are
@@ -203,6 +207,7 @@ worker; one that stops moves the issue on, or is stale a day later.
| The triage fills only what is empty, links no cycle, and an issue is ready only when its dependencies' fixes are delivered | the rows of ADR 0279's "How it is checked" |
| The duplicate check acts only on a clear duplicate, never on an older or a resolved issue, once per issue, loudly when it cannot judge | the rows of ADR 0278's "How it is checked" |
| An issue's documents are kept whole, with author, date and history, and the import of hq's folders loses nothing (ADR 0291) | the module's tests of `documents` and of the import, one case per document kind; the comparison of every issue with its folder before the folders are removed, written on issue 427. Tracked by issue 427 |
| An issue belongs to at most one milestone, linked only by the verb, and only to an open one (ADR 0493 §2 to §4) | the module's table test of the `milestone` and `commit` link kinds, one case per refusal; the test that the triage and the duplicate check never add a `milestone`, `pull-request` or `commit` link; one integration test that starts the module whole on a real bus and makes, links and refuses |
| Live | on the mesh, an agent calls `issue-tracker.open` and gets the next number; two sessions on two nodes open at the same moment and get two different numbers; `list` shows both |
## 8. The slices after the first
@@ -312,6 +317,32 @@ with no pull request open is **abandoned**.
**tracking line** in every condition's message; the words and the verdict it changes are its own (to-be 45 § 5).
The controller learns nothing of issues.
## 13. Milestones
**A milestone is a record of the tracker, made from its design's table** (ADR 0493 §1). The state `milestones`, which the
manifest declares beside `issues`, keeps one value per milestone, keyed by its design's number and its id: the id as the
design's table writes it, the outcome, its order in the table, its status (`open` or `closed`, with a reason), who made
and who last moved it and when, and the hq commit and path it was seeded from. It is written by compare-and-set at the
revision read, and its history is the key's kept values with the events `milestone-set` and `milestone-moved`.
**An issue's milestone is the issue's own link, not a list on the milestone.** The link kind `milestone` (its target
design/id, such as 47/R6) is written in the issue's log like any link, so the rule that an issue belongs to at most one
milestone (ADR 0493 §2) is checked inside that issue's one write, refused naming the milestone it is in; a link to a
milestone that does not exist or is closed is refused (§3: a fix found on the way joins the open milestone). A milestone's
issues are read from the issues in memory. Pull requests and commits are linked to the issue they fix the same way, with
the kinds `pull-request` and `commit` (§4); nothing reads them from a description, and the triage never adds one.
**The seed** is `import` with `milestones` and a design's number: it reads the table through the records module, makes
each record that is absent in the table's order, links each issue it names that has no milestone, refuses (and names)
an issue another milestone holds or two rows name, closes a milestone whose issues are all done (wontfix, or resolved
with every live fix delivered, or resolved with no live fix) when it refused none of its row's issues, and run again
changes nothing. Once a design is seeded, the tracker is the only list of its milestones'
issues: the design's table keeps its rows without an Issues column, and the knowledge base's `progress` reads
`milestones` (issue 1781).
Readiness, the one ask per milestone and its release are the delivery seat's (ADR 0493 §7 to §11, issue 1783); the
tracker gives them the records and links they read.
## What it leaves out
Priorities beyond severity, notifications beyond the `ready` and `ready-to-verify` events and the stuck-fix warning, full-text or semantic search, the forge's own issue lists, and an index of any kind:
+624 -44
View File
@@ -2,34 +2,68 @@
layer: to-be
status: in-progress
code: [mesh-catalog, hq]
updated: 2026-10-18
updated: 2026-11-04
decisions:
- "ADR 0290"
- "ADR 0321"
- "ADR 0423"
- "ADR 0424"
- "ADR 0592"
- "ADR 0593"
- "ADR 0595"
- "ADR 0596"
- "ADR 0597"
- "ADR 0616"
- "ADR 0613"
---
# 55 — The knowledge base
**Where it stands, 2026-10-17** (the records cleanup, issue 1072; playbook 07, "The design's state is written back"). Built and live since 2026-10-11: the knowledge base is the module mesh-knowledge in mesh-catalog, holding every decision record and research effort (issues 425 and 426, resolved and delivered). Left: the later slices, issues 428 and 429.
**Amended, 2026-11-02** (ADR 0592, on the operator's word: "our knowledge base must be nats-native"; "don't use
file references or local files anymore"). The records leave the store for the bus: each record's head in the
module's state, its versions on a stream, its sections' bodies once each in an object bucket by digest. A record is
written one section at a time in a draft, and reviewed one section at a time. A section is a part with a title,
never a file. § 1, § 2, § 4, § 5, § 8.1 and the fifth slice of § 9 say how; until it is built, the module keeps its
records in the store as before.
**Amended, 2026-11-03** (ADR 0597, ADR 0595 and ADR 0596, from research 082; the operator, 2026-11-02 21:53: "the
writes are the record"). The knowledge base is the first **ledger**: a record is an instance of a ledger type, every
change to it is an operation kept in the ledger's history, and its head is the ledger's state, derived from those
operations by the tool runner's `apply` and never written by the module. A section's text lives only in the
`write-section` operation that wrote it, with its digest; the head names each section by its title, digest and that
operation's sequence. So the object bucket `sections`, the state `names`, the stream `versions` and the module's own
commit rule fall away (ADR 0597 §12, changing ADR 0592 §1 to §12, §17, §25, §32, §33). Its kept data is asked for in
`requires` by template (ADR 0595), and no other module reads it: another module asks the knowledge base's tools or
hears its events (ADR 0596). The ledger itself, the same for every module, is designed in
[design 25](25-the-bus-on-nats.md) § 12; how a module asks for it, in [design 32](32-what-a-module-declares.md) § 4.
**Amended, 2026-11-04** (ADR 0616; the operator, 2026-11-03, on issue 1968: "I'm starting to lose the overview"). The
knowledge base serves a read-only overview page for the operator, built from its own ledger and three other modules'
verbs and events (§ 11), in the milestone that moves it onto the ledger (ADR 0613 §1).
§ 1, § 1.1, § 2.1, § 4, § 8.1, § 9 and § 10 say what changes here.
**The mesh keeps its decision records and research efforts whole in a module of its own, `mesh-knowledge`, one
instance on the control-node, holding the seat `knowledge-base`: each record's number, status, topic, typed links,
its clauses with their own status, and its reasoning, with every version kept. A record is proposed, checked when it
is written, reviewed by the knowledge base's own judgement and accepted there; the operator's Approve is asked when a record needs
it. Agents ask what holds, and why, in one bounded call.**
(ADR 0290,
from research 045.)
its clauses with their own status, and its reasoning in titled sections, with every version kept, all of it on the
bus. A record is written section by section, checked when it is submitted, reviewed section by section by the
knowledge base's own judgement and accepted there; the operator's Approve is asked when a record needs it. Agents
ask what holds, and why, in one bounded call.**
(ADR 0290, ADR 0592 and ADR 0597,
from research 045 and research 082.)
A **clause** is one numbered statement a decision record makes, with its own status. The **knowledge base** is the
module that holds the records; the seat it holds is `knowledge-base`. The glossary holds both words.
A **clause** is one numbered statement a decision record makes, with its own status. A **section** is one titled
part of a record's reasoning. The **knowledge base** is the module that holds the records; the seat it holds is
`knowledge-base`. The glossary holds these words.
**Acceptance.** A session started in any folder on any node asks "what holds about the merge window, and why" and
gets, in one call under 4 KiB, the clauses in force, the records they come from, what changed them since, and how to
read the reasoning behind each.
read the reasoning behind each. A session writes a research effort of more than 100 KiB one section at a time, a
session on another node takes the draft over and submits it, and every section is judged.
This document designs the first slice in detail, tracked by issue 425. The slices after it are in
This document designs the first slice in detail, tracked by issue 425, and the fifth, the records on the bus
(ADR 0592), kept as a ledger (ADR 0597). The slices after the first are in
[§ 9](#9-the-slices-after-the-first), which also designs the third: designs and the glossary's entries become records,
and the knowledge base works out each design's state (ADR 0423, ADR 0424).
@@ -40,17 +74,40 @@ and the knowledge base works out each design's state (ADR 0423, ADR 0424).
mesh-knowledge (seat knowledge-base, held once for the mesh)
├ its process, launched by the node runtime
├ a database in the store records, versions, clauses, links; ranked full-text search
├ verbs ask, get, holds, links, history, reserve, propose, import, return
├ on the bus, asked for in requires by template (ADR 0595), read by it alone (§ 2)
│ ledger records one instance per record (decision/0290, research/082):
│ history every operation, in order, each section's text in its write-section
│ state the head, derived by apply: fields, clauses, links, sections as
│ title, digest and sequence
│ snapshot the latest head per record, never expiring
│ state drafts one key per record being written: its author and its sections as title,
│ digest and the sequence of their write-section
│ state asked one key per part asked of the judgement tool, not yet answered: ticket, node, when
│ state findings the whole-set findings standing now, and the told marks (told.<topic>)
│ state sent per record, the last operation whose event was sent
│ stream reviews one message per part reviewed: the digest judged, the verdict, the findings
├ written through the tool runner's apply on the control-node, the only publisher on the
│ ledger's history (ADR 0597 §3, §9)
├ in its memory the search index, built from the bus at start and kept by watching the
│ ledger's state
├ verbs ask, get, list, holds, links, history, findings, progress,
│ reserve, open, write, remove, order, submit, drop, take-over, propose,
│ withdraw, retract, import, return
│ served by the control-node's tool runner
├ events proposed, reviewed, accepted, changed, imported, drafted, confirmed, returned
├ events reserved, opened, written, removed, ordered, submitted, dropped, taken-over, proposed,
│ part-reviewed, reviewed, accepted, changed, moved, checked, formed,
│ imported, drafted, confirmed, returned
├ consumes the router's warrants: the operator's Approve for a record that needs it (§ 5)
└ consumes the delivery module's delivery-done announcement: a design's state (§ 9)
├ consumes claude-code's judged: the judgement tool's answer to a part (§ 5)
├ consumes the delivery module's delivery-done announcement: a design's state (§ 9)
├ consumes the issue tracker's, mesh-delivery's and the router's events for the overview page (§ 11)
└ serves the overview page, read-only, on a port it declares, through the route proxy (§ 11)
mesh-issues (control-node) the counters for decision and research numbers (§ 6);
the issues' design links, read for a design's state (§ 9)
mesh-delivery (its seat) announces each delivery done, on the bus (§ 9)
claude-code (same node) claude_code_judge: review a proposal (§ 5), draft and confirm clauses (§ 7)
claude-code (same node) claude_code_judge: review a section or a head (§ 5), draft and confirm clauses (§ 7);
emits judged with the answer of each ticket (§ 5, a dependency of the fifth slice)
records (any node) records_read at a commit: the import's source (§ 8)
messenger (control-node) the router: the operator's ask and its warrant
@@ -59,20 +116,109 @@ and the knowledge base works out each design's state (ADR 0423, ADR 0424).
```
The module is written in Go against the SDK. It holds no checkout of this repository; the import reads it through
the records module, as the issue tracker's import does.
the records module, as the issue tracker's import does. Until the move of § 8.1, its records are in a database in
the store; from the move on, it requires no database (ADR 0592 §1, changing ADR 0290 §7).
**A record is changed by an operation, and the head follows from it** (ADR 0597 §1 to §8). Every change to a record
is one operation the module hands to `apply`: among them `reserve`, `propose`, `write-section`, `submit`,
`take-over`, `review` (a part's verdict), `ask` and `warrant` (the operator's ask and answer), `accept` and
`withdraw`. The module checks its own rules first (an `accept` needs the operator's Approve where the record needs
it, § 5; only the author writes a draft, § 4), then calls `apply`, which checks the operation against the record's
type, appends it to the instance's history with the sequence it expects, derives the head by the operation's effect,
and writes the head and its snapshot. The author is the account the bus proved for the caller of the module's verb:
the module names the tool call it serves, and the tool runner stamps the caller it proved for it, never a name the
caller or the module gave (ADR 0597 §7; [design 25](25-the-bus-on-nats.md) § 12.4).
**Every operation's event is sent once, after a restart too.** `apply` emits nothing; the module sends the event of
each operation it applied (`submitted`, `reviewed` and the rest) with the operation's sequence as the message's
id, so the bus drops a second send within its duplicate window, and keeps the last sequence it sent per record in a
state of its own, `sent` (one key `<kind>.<number>`). The duplicate window of its event stream and of `reviews` is
one day, far longer than a start (40 seconds at most, § 10); a module stopped between a send and its `sent` key for
longer than a day sends that one event again, which a consumer already takes as a bus delivered at least once. A
missed send is never chosen over a second one. At start it sends the events of every later operation in each record's history, so a
module stopped between `apply` and its event loses none, and a consumer of `mesh-knowledge.reviewed` never waits for
one that was never sent.
**A write is whole or refused, and an operation commits when its history takes it** (ADR 0597 §5, §6, changing
ADR 0592 §10). The commit point of every change to a record is the operation appended to the ledger's history: a
failure before it is appended refuses the call, and nothing is taken; a racing writer is refused by the bus, which
expects the history's last sequence for the instance. Once it is appended, the call answers that it is taken, with
its sequence; the head is derived by `apply` as an update of the revision it read, and a head behind its history is
caught up by the next `apply` (ADR 0597 §6). A full state bucket answers that the operation is taken and the head behind,
never that it was refused. So nothing an author was told was refused takes effect later. A reservation is an
operation `reserve` on an instance with no history, so two sessions reserving at once get two numbers or one
refusal. The module's other state (`drafts`, `asked`, `findings`) keeps the compare-and-set on the key's revision,
retried at most three times and then refused with the reason (ADR 0597 §12).
**The search index** is a full-text index in the module's own memory, written with the pure Go library bleve. At
start the module reads every head from the ledger's state and the bodies of every current version from their
`write-section` operations into it, then keeps it current by watching the ledger's state, noting the last sequence it
took in (ADR 0597 §12, changing ADR 0592 §11). The index is the module's own, in its memory; the ledger's declared
index (ADR 0597 §4) is not used for it, because a full-text index is not a key-value bucket. `ask` and `holds` answer from it, ranked by title, clauses
and sections as before, and refuse with "index not built" while it is built; `get`, `list` and `propose` answer from
the ledger's state at once (ADR 0592 §11). The integration test measures the start; the estimate is 20 to 40 seconds and about
100 MB of memory for today's 736 records. Nothing but the module writes it, and nothing outside it reads it.
### 1.1 Its tools, health and events
Every piece of state has a tool that reads it, and every act the module does by itself can be done by hand
(ADR 0592 §32, changed by ADR 0597 §12: the sweep and the digest check become the ledger's repairs):
| Tool | Reads or does |
|---|---|
| read a head | one instance's state in the ledger, whole, with the sequence of the last operation it holds |
| read a record's history | the instance's operations in order, each with its sequence, author and when; a version is its `submit` |
| read a section | one `write-section` operation, by its sequence, its text checked against its digest |
| read a draft | one key of `drafts`, with its author and since when |
| read a review | the part verdicts of one version, from `reviews` |
| in-flight parts | the keys of `asked`: each part waiting on the judgement tool, its ticket and since when; ask one again |
| told marks | the `told.<topic>` keys; clear one, so it is told again |
| fill | each bucket's and stream's size and count against its cap |
| rebuild the index | the search index, built again from the bus |
| review again | asks one part's review again, for a version still proposed |
| the ledger's repairs | the tool runner's `rebuild` (a head from the history or the snapshot), `snapshot` and `lag` (how far each head is behind its history), served for the module's own ledger (ADR 0597 §10) |
| integrity | checks every section a head or draft names resolves to a `write-section` whose text hashes to its digest |
| form-only | lists, dry-runs and runs the form-only versions of § 2.2 |
| move, and check the move | § 8.1, each with a dry run |
**Health** (ADR 0592 §33) is unhealthy, naming the cause, when a bucket or stream does not answer, when the index is
behind the ledger's state, when a head lags behind its history (the ledger's lag, ADR 0597 §12, changing
ADR 0592 §33), and when a bucket or stream is at its cap. It names the source it serves from (the database or the bus) and the result
of the move's last check, and counts drafts idle more than a week, records the form-only check refused, and parts
waiting more than 30 minutes. A part waiting more than 30 minutes is asked of the operator once through the operator
channel, and the ask clears when the part is judged; the module stays healthy meanwhile, because a record waiting on
its review is not the module failing (issue 508). The condition at 75 percent of a cap is the bus module's (ADR 0595 §6; [design 25](25-the-bus-on-nats.md) § 12).
**Events** (ADR 0592 §34) are kept 30 days; what a later reader needs is also in the `submit` operation, in the ledger's history. Each carries:
| Event | Carries |
|---|---|
| `opened` | the record, the version it starts from, the author |
| `written`, `removed` | the record, the section's title and digest, the author |
| `ordered` | the record, the titles in order, the author |
| `submitted` | the record, the new version, its section digests, the author |
| `dropped` | the record, the author, the reason (asked, or idle 14 days) |
| `taken-over` | the record, the previous author, the new author, the reason |
| `part-reviewed` | the record, the version, the part, its digest, the verdict |
| `reviewed` | the record, the version, every part's verdict: one event per version, as before |
| `moved` | the record, its counts on the bus |
| `checked` | the move's check: records compared, every difference |
| `formed` | the record, the version, the names changed |
None is named `drafted`, which stays the event of a clause the import's judgement wrote.
## 2. What one record holds
- `number` and `kind` (decision or research; with the third slice also design and glossary entry, § 9), its key
together; `title`, `topic`, `status`, `date`, `deciders`;
- its **reasoning**, in sections: for a decision, context, the options weighed, consequences, how it is checked,
references; for a research effort, its overview and each of its documents by name; for a design, its `to-be`
section and, where something of it runs, its `as-is` section (§ 9); markdown, as written;
- its **reasoning**, in **sections**, each a plain title and its text in markdown: for a decision, Context,
Considered Options, Consequences, How it is checked, References; for a research effort, its overview and each of its
parts by title; for a design, its `to-be` section and, where something of it runs, its `as-is` section (§ 9);
- for a decision, its **clauses** (§ 3);
- its **links**, typed, each stored once and read from both ends;
- its **versions**: every change is a new version with who made it, when, and why in one line; `history` lists them
- its **versions**: every `submit` is a new version with who made it, when, and why in one line; `history` lists them
and gives the difference between any two. A progressive insight is a version marked as one, dated, saying what stood
before.
before. A form-only version (§ 2.2) is marked `form`.
| Link | From → to |
|---|---|
@@ -84,6 +230,105 @@ the records module, as the issue tracker's import does.
| `touches` | a research effort → a record, issue or design it bears on (by link), or an area (as text) |
| `cites` | any record → any record or issue it names |
### 2.1 Where it is kept
A record is kept as one instance of the knowledge base's ledger `records` (ADR 0597 §11), so that a new version
costs only the sections it changes; the forms of ADR 0592 §1 to §9 that it replaces are named in its §12.
```
records: history (stream, one subject per instance) records: state (key-value, derived)
┌───────────────────────────────────────────────┐ ┌─────────────────────────────────┐
│ 101 decision/0290 propose fields, … │ │ decision/0290 │
│ 102 decision/0290 write-section "Context" │ │ title, status, clauses, links │
│ text, digest 3f9a… │ apply │ current sections: │
│ 103 decision/0290 write-section "Options" │ ───────▶ │ Context 3f9a… 102 │
│ text, digest 81c2… │ │ Options 81c2… 103 │
│ 104 decision/0290 submit sections 102, 103 │ │ pending sections: none │
│ 230 decision/0290 write-section "Context" │ │ after operation 231 │
│ text, digest 0d77… │ └─────────────────────────────────┘
│ 231 decision/0290 submit sections 230, 103 │ records: snapshot (one per instance,
└───────────────────────────────────────────────┘ the latest head, never expiring)
```
- **The head** is the instance's state, `<kind>/<number>`: the record's fields, its clauses with their status and
source, its links, the operator's ask and warrant, its current and pending version, the latest verdict of each
part's review (§ 5), and its sections in order, each a title, a digest and the sequence of the `write-section`
that wrote it, never the text. A section's title is held to 200 bytes, so an entry is at most about 300 bytes,
and a head with 64 pending and 64 current sections holds at most about 40 KiB of them, within a state value's
256 KiB (ADR 0597 §11). A reserved number is a head at `reserved`, with who reserved it, when, for what and when it
expires. It is derived by `apply` and never written by the module.
- **A version** is the operation `submit`: who wrote it (the caller the bus proved), when, why, its mark, the
reason of any take-over since the version before, and the version's sections (title, digest and sequence each),
which its effect sets as the head's current sections. It never copies a section's text. Who wrote each section is
the author of its `write-section`.
- **A section's text** is in the `write-section` operation that wrote it, with its digest, at most 40 KiB within a
history entry's 256 KiB: a section unchanged in a new version costs nothing, since no operation is written for it.
`apply` refuses a `write-section` whose digest does not match its text, and the module checks the text against
the digest each time it reads one. A dropped draft's operations stay in the history, named by no version
(ADR 0597 §11).
- **The history** is kept for good: the ledger template's history refuses a new operation when full, rather than
dropping its oldest, and the bus module raises its condition at 75 percent of the cap (ADR 0595 §3, §6). Each
instance's snapshot, the latest head on a subject of its own, makes a rebuild fast (ADR 0597 §8).
- **A draft** is a key in the state `drafts` (§ 4). **A part's verdict** is the operation `review` on the record's
history first, then a message on the stream `reviews`; a `review` with no message on `reviews` is sent at start
with the operation's sequence as its id, so the consumers of `reviews` miss none and hear none twice. A part
asked of the judgement tool and not yet answered a key in the state `asked` (§ 5). **The whole-set findings** standing
now are keys in the state `findings`, and what was told to the operator once is a key `told.<topic>` there. These
keep their own forms (ADR 0597 §12), asked for in `requires`: the states by the template state; `reviews`, kept for
good and heard only where granted (ADR 0592 §6, §8), as a bare stream with its own configuration (kept for good,
refusing when full, a grant), because no template both keeps for good and takes a grant (ADR 0595 §2); the bus module's read of fill every minute
covers it like any entry that refuses when full.
**Caps** (ADR 0592 §25, its object bucket's cap lapsing by ADR 0597 §12). Each is set from the move's dry run, within
its template's bound (ADR 0595 §3): a history at most 8192 MiB, a state or a ledger's state at most 64 MiB. The
starting figures, from today's 83 MB for 736 records with every version copying every section, are:
| Kept data | Template | Cap |
|---|---|---|
| `records` (history) | ledger | 1 GiB |
| `records` (state) | ledger | 64 MiB |
| `reviews` | a bare stream, its own configuration | 512 MiB |
| `drafts` | state | 64 MiB |
| `asked`, `findings`, `sent` | state | 64 MiB, the template's bound |
A write refused at a cap names the cap, and the module's health turns unhealthy naming it.
**The ledger's state is the tightest cap.** 64 MiB is already the template's top. A head holds no text, only fields,
clauses, links and its sections' titles and digests; estimated at most 8 KiB for a usual record, the 736 heads of
today need about 6 MiB, and about 1000 once designs and glossary entries become records (slice 3, § 9) about 8 MiB.
Those are estimates; the move's dry run measures the real total, and a total above 32 MiB is told to the operator
before the move.
**Nobody else reads any of it** (ADR 0596 §2, ADR 0597 §9, changing ADR 0592 §8 and §9). Only the knowledge base's
own account reads its ledger's history, snapshot and state and its other kept data; the ledger's history is published
on only by the tool runner's ledger credential. Another module asks the knowledge base's verbs (`get`, `history`,
`ask`) or hears its events (`reviewed`, `accepted` and the rest); the reads of `heads` and `sections` that ADR 0592
let another module declare lapse once those verbs answer what each reader needed. `reviews` stays a restricted event
family (ADR 0363 §4), heard only by a module granted it in mesh-knowledge's trusted config value `readers`, which
names nothing today. A draft is answered by the verbs to its author only, and a version's bodies as `get` answers
them, so the text in the history is no more open than ADR 0592 kept it. No secret is kept in any of it.
### 2.2 A section is a part with a title
A section's name is a plain title, unique in its record: "Context", "Direction", "The move". It is never a file's
name: a name with an extension, a number prefix such as `00-`, or a slash is refused, and so is a text that holds a
local path (in a person's home folder or the temporary folder), a reference to a file and line, or a link whose
target is a relative path or a file (ADR 0592 §29).
**A reference has one form** (ADR 0592 §30): the record, a section's title, then a row or clause inside that
section's text, joined by ›, such as "research 081 › Direction › D3"; a clause as its record and number,
"ADR 0290 §7". Sections never nest: `get` resolves a record and a section's title, and the row is an anchor in the
section's text, which a web page links.
**The records imported with file-named sections** (the research efforts' `00-overview.md` and the like) get titles in
one form-only version per record, written after the move by the move's tool alone; no verb writes one. It changes only section names and the
targets of links, each link to a record's file becoming a reference in the form above. It is marked `form`, lists the
names it changed, and is accepted without a judgement because a check proves only form changed: each section's text,
with every link replaced by its label, is the same before and after, and each new link target resolves to the record
the old name named. `get` accepts the old section names as aliases, recorded in that version. A part's review carries
over to it, its meaning being unchanged. It is not a change of meaning; `history` shows it as a change of form
(ADR 0592 §31).
## 3. Clauses
A clause holds its record's number and its own (`0276 §4`), its wording, a `status` and a `source`:
@@ -103,9 +348,49 @@ A clause holds its record's number and its own (`0276 §4`), its wording, a `sta
## 4. Writing a record
`reserve` gives a number (§ 6). `propose` takes the record whole: its fields, its clauses, its reasoning in sections,
its links, and for each `changes` the clauses it changes. It is refused, with every reason at once, when one of the
29 rules of the hq checks that judge one record or its prose fails, among them:
`reserve` gives a number (§ 6). A record is then written in a **draft**, one section per call, and submitted as a
version (ADR 0592 §17):
| Verb | Does |
|---|---|
| `open` | opens a draft of a reserved or existing record, with its fields, clauses and links; called again by its author, changes them |
| `write` | writes one section: its title and its text; one call per section |
| `remove` | removes one section from the draft |
| `order` | sets the sections' order |
| `submit` | makes the draft a version: every rule below is checked, every reason of a refusal named at once, and the review asked (§ 5) |
| `drop` | discards the draft |
| `take-over` | makes the caller the author of a draft or a proposal, with a reason |
| `propose` | `open`, a `write` of each section and `submit` in one call, for a record that fits one bus message |
```
open ──▶ write ──▶ write ──▶ … ──▶ submit ──▶ proposed, reviewed by part (§ 5)
▲ │ │
└─ remove, order └── refused: every reason named, the draft kept as it was
drop: the draft is gone take-over: another session becomes its author, with a reason
```
A draft is a key in the state `drafts`: its author, when it was opened, the version it starts from, the record's
fields and clauses, and its sections in order as title, digest and the sequence of the `write-section` that wrote
each. Each `write` appends a `write-section` operation with the section's title, text and digest to the record's
history at once, through `apply`, and names its sequence in the draft (ADR 0597 §11, changing ADR 0592 §17), so an
unsubmitted draft's text is already in the history, the knowledge base holds the only copy of a draft, and a
session on any node can read it through the verbs; `submit` carries the draft's sections into the version. A draft holds at most 64 sections and 1 MiB; one untouched for a week is counted in
the health, and one idle for 14 days is dropped and its author told by `dropped`.
**A draft and a proposal have one author** (ADR 0592 §19). Only the author writes a draft or revises a proposal;
another caller is refused, naming the author. `take-over` makes the caller the author, keeps the reason on the
record, and tells the previous author by the event `taken-over`. It answers a proposal that only the machine that
wrote it could revise (issue 1102) and one left proposed for ever by a version from an unproven writer (issue 465).
A proposal waiting for the operator's Approve cannot be taken over: its author withdraws it first. The reason of a
take-over is carried in the next version's message.
**Only a proven caller writes** (ADR 0592 §20, §21): `open`, `write`, `submit`, `propose` and `take-over` refuse a caller
the runtime could not prove. The operator's Approve binds the section digests of the version shown; a version with
any other section is asked again.
`submit` and `propose` are refused, with every reason at once, when one of the rules that judge one record or its
prose fails, among them:
- a link names a record or clause that does not exist;
- a decision has no clause, or a clause has no bold lead;
@@ -113,21 +398,62 @@ its links, and for each `changes` the clauses it changes. It is refused, with ev
that replaced it;
- its topic is not one of the reading order's;
- a research effort graduates without naming what it became;
- its text uses a retired word of the glossary, or a daemon's command line.
- its text uses a retired word of the glossary, or a daemon's command line;
- a section is over 40 KiB (it says: split it), or the clauses together are;
- a section's name looks like a file, or its text holds a local path, a file and line, or a link to a file (§ 2.2).
`write` refuses a section over 40 KiB, or one whose name or text breaks § 2.2, at once, so a session learns it on the
section it just wrote.
A proposed record can be revised by its author as new versions until it is accepted. Nothing proposed is ever served
as in force.
## 5. Review and acceptance
When `propose` takes a record (or a new version of a proposed one), the knowledge base reviews it itself: it asks for
a judgement in a separate call, with no tools, that sees only the record, the records it links and the rules, and
answers `approve` or `changes` with its findings, the way the issue tracker's triage judges an issue. The judgement
goes through the agent module's judge (`claude_code_judge`) today, and through the mesh's inference layer once one
exists; nothing in this design depends on which. On `changes`, the record stays proposed, the findings are kept with
that version, and its author revises it with a new version, which is reviewed again. A judgement that cannot be had
(the judge unreachable, or its answer unreadable) leaves the record proposed and says so; it is never taken as an
approval. On `approve`:
When a version is submitted (by `submit` or `propose`, a new version of a proposed record included), the knowledge
base reviews it itself, **in parts** (ADR 0592 §22 to §28, changing ADR 0290 §4): one judgement per part, each in a
separate call, with no tools, that answers `approve` or `changes` with its findings, the way the issue tracker's
triage judges an issue. The judgement goes through the agent module's judgement tool (`claude_code_judge`) today, and through
the mesh's inference layer once one exists; nothing in this design depends on which.
- **The head** is one part: the title, the brief, the clauses (at most 40 KiB together) and the links, judged
against the clauses of the records it links, in what room is left, those not shown named.
- **Each changed section** is a part of its own, judged with **the frame** of at most 16 KiB: the title, the links,
and only what the section names (rows of other sections, clauses, the clauses of linked records), with the digest
of the Context section (the Overview, for a research effort) it is read beside. What does not fit is cut, and the
question says what was cut. A section is at most 40 KiB, so each question stays under the judgement tool's 60 KiB.
- **What is judged again.** A section is judged again only when its own text or what it names changes; the Context
only when it changes. So a usual revision judges only the sections it changed.
- **At most two judgements of one version run at once.** A revision of eight sections takes a few minutes, and
about four times the tokens of one whole judgement.
- **The rules on the whole record** (§ 4) stay code, run at `submit`; no judgement is asked to find a link to nothing.
```
version 3 of research 081
├ head title, brief, clauses, links ── judged ──▶ approve
├ Overview unchanged since version 2, same frame ── kept ──▶ approve (version 2's)
├ Direction changed ── judged ──▶ changes: "D3 contradicts ADR 0290 §7"
└ Findings changed ── judged ──▶ approve
version 3 stays proposed, with the findings of Direction
```
**The parts wait on the bus** (ADR 0592 §23). Each part asked of the judgement tool is a key in the state `asked` (the part,
the tool's ticket, the node, when it was asked), collected again at start, so a restart loses no review. The tool's
answer comes as the event `judged`, which the claude-code module emits for each ticket and the knowledge base
consumes; until claude-code emits it, the knowledge base polls the ticket, which is not NATS-native and is tracked by
issue 1956. The judgement tool is the claude-code module's own tool, not a seat's verb: a seat for judgements (held by the
mesh's inference layer once one exists) is a note on that issue. A part waiting more than 30 minutes asks the
operator once through the operator channel, and the ask clears when the part is judged.
**A part's verdict** is the event `part-reviewed` and a message on the stream `reviews`: the record, its version, the
part, the digest judged, the verdict, the findings, who judged and when; the head keeps the latest verdict of each
part. **`reviewed` keeps its meaning**: one event per version, once every part is judged, carrying each part's
verdict, so every wait on it keeps working. A part's review is kept for a new version when what it was judged with is
unchanged, and for a form-only version (§ 2.2); any other part is judged again. **A version is accepted when every
part's review approves.** On `changes`, the record stays proposed, the findings are kept with that version and the
part they name, and its author revises it with a new version. A part that cannot be judged (the judgement tool unreachable,
or its answer unreadable) leaves the version proposed and says which; it is never taken as an approval. When every
part approves:
1. a record that does not need the operator is accepted at once;
2. a record whose author marked it `needs operator` gets an ask on the router with Approve and Decline, shown on a
@@ -138,18 +464,18 @@ On acceptance the record and its clauses move to `accepted` and `in force`, ever
`supersedes` name moves to `changed` or `superseded`, and `accepted` and `changed` events are emitted. Then the 4
rules that judge the whole record set run (an accepted decision cited by nothing, and the like). A failure does not
undo the acceptance. It is a fault of the records, which their authors repair, not of the module: it is told to the
operator once, as a warning naming the rule and the records, and cleared once the rule holds again. The module's
health names it and stays healthy, because health says only whether the module works, and a finding never holds a
rollout at the module's first-node gate (the operator's decision of 2026-10-12 on issue 504, as issue 508 decided for a proposal never
reviewed).
operator once, as a warning naming the rule and the records, kept in the state `findings`, and cleared once the rule
holds again. The module's health names it and stays healthy, because health says only whether the module works, and
a finding never holds a rollout at the module's first-node gate (the operator's decision of 2026-10-12 on issue 504,
as issue 508 decided for a proposal never reviewed).
The rule `cited` is also judged ahead, in the review, before the judgement: a decision that names no home and that no
accepted record links is not accepted. Its review, by the knowledge base itself, asks changes naming the rule (issue
504). It is not refused at `propose`, because no record can link a number only reserved: a record that cites a new
504). It is not refused at `submit`, because no record can link a number only reserved: a record that cites a new
decision is proposed after it and accepted, and the new decision is proposed again.
An accepted record is changed only by a new record, or by a progressive insight: a new version marked as one, which
is reviewed like a proposal.
An accepted record is changed only by a new record, by a progressive insight (a new version marked as one, which is
reviewed like a proposal), or by a form-only version of § 2.2, which a check, not a judgement, accepts.
## 6. Numbers
@@ -194,6 +520,63 @@ reporting nothing created (issue 488).
Before the records leave this repository (issue 426), every record is compared with its file at the import's commit,
field by field and section by section, and the result is written on issue 426.
### 8.1 The move off the store
The records leave the store once, and the database is dropped only after a check and the operator's yes
(ADR 0592 §12 to §16; the forms the records are copied into are those of ADR 0597 §12):
1. **Order.** The ledger is built first, in the order of ADR 0595 §10: mesh-sdk's typed `requires`, binding and
package of the new calls; the manifest validator's rules; the bus module's process, verbs and events; the tool
runner's calls, `apply` among them, with its ledger credential per module assignment (ADR 0597 §9, as its
progressive insight of 2026-11-03 has it, waiting for the operator's Approve); then mesh-knowledge moves, asking for
its ledger, states and stream in `requires`. An indexer whose manifest validator predates the new form refuses a manifest
that uses it, and the placement holds the module off a machine whose tool runner does not read the typed
binding, so mesh-knowledge cannot be delivered before them. The release sdk1 (issue 1585, ADR 0593 §10), which
created object buckets and history streams through the grants part, is no longer needed by the move: the
knowledge base asks for no object bucket and no stream `versions`. The claude-code module's `judged` event is
delivered beside, and is not needed for the move (§ 5).
2. **Copy.** The move copies everything the database holds onto the bus, every record, version, clause, link,
review, finding, ask with its warrant, reservation and told mark: each record's versions as operations on its
instance in the ledger, in order (a `write-section` for each section a version changed, then its `submit`, then
the record's review, ask, warrant and acceptance), through `apply`, so each head is derived and never copied; each operation is stamped with the knowledge base's own
account and keeps the database's author as a separate field marked imported, which `history` shows as the author
of an imported version;
each standing finding into `findings`, each told mark as `told.<topic>`. A clause keeps its number, status and source as the database holds
them (ADR 0321). It emits `moved` per record, writes nothing twice, and a second run changes nothing and says so.
A dry run lists what it would write and the size each bucket and stream will need, from which the caps are set.
3. **The window.** From the move's final copy through the check to the switch, every writing verb is refused with
its reason ("the knowledge base is moving"). Reading verbs answer throughout.
4. **Check.** A tool compares the database and the bus record by record: for each record the count of each of
those, the digest of every section of every version, computed from the database's text and read from its
`write-section` on the bus, that each text hashes to its digest, that each head derived equals the head the
database holds, and a digest of every review's, finding's and ask's content. It emits
`checked` with every difference, and the health shows its last result.
5. **Switch.** Only once the check shows no difference, the module answers from the bus. The switch is a key on the
bus, so a restart never falls back to the database. A difference is told to the operator, and the module stays on
the database.
6. **Rollback.** Until the database is dropped, the module writes each change to the database too, after `apply`
has taken its operation, so a rollback of the delivery reads a current database. What the database holds is
kept as a key in the state `findings`, `database.sequence`: the last history sequence written to it. At start,
and after a write the database refused, the module catches the database up from the history from that sequence
on, so a restart between `apply` and the database write loses nothing. A database still behind after three tries
raises the condition `database-behind`, naming each record it lacks and saying that a rollback now would lose
them, and never answers the author that the write was refused; the module's health is unhealthy while it stands,
the drop (step 8) is refused while it stands, and the catch-up tool copies the records again from the ledger and
clears it. A rollback is a person's act, and the condition is what tells them it is unsafe. **After a rollback**,
the older module wrote to the database alone, and not only versions: acceptances, verdicts, asks, warrants,
reservations and changed clauses too. So until the drop, every start of the module refuses every writing verb
and runs the check of step 4 before it serves writes; a difference it finds is copied from the database onto the
ledger as operations, and the check runs again, so writes are served only once it is clean. A record changed on
both sides (an operation the database never took, and a change the older module made) never checks clean: it is
told to the operator at once, naming the record and both changes, so the refused writes read as a decision
waiting and not as a stall. A rollback is safe
only until the drop. This settles the rollback ADR 0597 §13 left to the design.
7. **Tell and ask.** Once the check is clean, the operator is told its result and asked, once, whether the database
may be dropped, because dropping it removes data.
8. **Drop.** On the operator's yes, the delivery after it removes the module's requirement of a database, and the
database is dropped by the store's module, through its tool for it, which is built there first if it has none.
9. **Titles.** The move's tool then writes the form-only versions of § 2.2, one per record with file-named sections.
## 9. The slices after the first
| Slice | Delivers | Done when the operator sees | Tracked by |
@@ -202,6 +585,7 @@ field by field and section by section, and the result is written on issue 426.
| 2 | the decision records and research efforts leave this repository; path mentions become "ADR NNNN" and "research NNN"; playbooks 01 and 02 changed | this repository holds no decision record, and `get` answers every one | issue 426 |
| 3 | designs and the glossary's entries as records, moved in one delivery, and each design's state worked out by the knowledge base (§ 9.1 to § 9.3; ADR 0423, ADR 0424) | `get` answers design 47 with its sections and links, a word's entry answers from the knowledge base, and a design's state follows its issues' deliveries without anyone writing it | issue 428 |
| 4 | meeting notes, drawings and blog posts | not decided; needs its own decision | issue 429 |
| 5 | the records on the bus, written and reviewed by section, the move off the store and the titles (§ 1, § 2, § 4, § 5, § 8.1; ADR 0592), kept as the first ledger (ADR 0597), delivered after the ledger's build (ADR 0595 §10), then mesh-knowledge, with claude-code's `judged` event beside | the acceptance tests of the fifth slice in § 10, live; the knowledge base requires no database | the issues its hand-off opens (playbook 04) |
Numbers from the issue tracker, which `reserve` needs, are the tracker's own slice, tracked by issue 424. This
repository keeps no copy of the records, generated or otherwise (issue 435, answered by the operator). Playbooks
@@ -228,7 +612,7 @@ the page as the authority on words (ADR 0423, changing ADR 0244).
|---|---|
| the knowledge base's own rule on a retired word (§ 4) | the *Not:* and identifier lines of the entries, no longer the page through the records module; it judges a design when it is proposed, as it judges a decision |
| hq's word check | the entries' *Not:* and identifier lines, and its uniqueness check (a head word heading two entries, or also retired) over the entries; it covers what stays in this repository, and designs leave its coverage |
| the catalogue's repository check | the retired words of no scope or *(tools)* from the entries; its copied list is retired, so hq has no copy to compare |
| the catalog's repository check | the retired words of no scope or *(tools)* from the entries; its copied list is retired, so hq has no copy to compare |
| hq's cycle check | the design records, for every design naming its decisions, not files under `03-DESIGN/` |
Each of the four fails, saying so, when the knowledge base does not answer, and never passes on nothing.
@@ -299,6 +683,50 @@ milestones and nothing of how a delivery runs; it only listens for the announcem
| An answer stays within its bound | the module's test over the full import of `main` at a recorded commit: every `ask`, `get` and `holds` of a fixed question list |
| A record written in this repository meanwhile writes its clauses | `records.py`, check `clauses`, on every hq pull request, until the records left this repository (issue 426); since then `records.py`, check `no-records`, refuses any record written here |
| Live | the acceptance sentence, asked from a session outside this repository |
| A record is kept as a ledger instance, a section's text once in its operation, and read by no other module | one integration test that starts the module whole against a real bus server: a record of three sections and a second version changing one give one head, two `submit` operations and four `write-section` operations, the changed section's text found only in its operation; another module's account reading the ledger's history, snapshot or state, the head among them, is refused (ADR 0597 How it is checked, clauses 9, 11, 12) |
| Search answers from the index as it did from the store | a unit test over a fixed set of records and a fixed question list; the integration test restarts the module and asks again |
| A draft is written by section and has one author, and a take-over tells the previous one | unit tests of each verb of § 4, of a refusal naming the author, and of `take-over` emitting `taken-over`; a take-over refused while the operator's Approve is waited for |
| A ledger that keeps its history | in the integration test: the history at its cap refuses a new operation and keeps its oldest; a draft's written section is in the history before `submit` and named by no version after `drop`; a section title over 200 bytes is refused |
| A long record is judged whole, one part at a time | unit tests: the frame never passes 16 KiB and says what it cut, with twenty clauses of 2000 bytes and a 40 KiB Context; every question stays under 60 KiB with a 40 KiB section and that frame, and the head part with 40 KiB of clauses; a section over 40 KiB is refused saying split it; an unchanged section keeps its review, a changed frame asks it again |
**The fifth slice's tests, one per failure path** (ADR 0592; the review by architectural domain's testing ruling). Unit tests are
table-driven; one integration test starts the module whole against the real bus server. The module's count today is
1 integration and 104 unit tests; these add about 20 table cases and stay within the budget of 50 and 500.
| Failure path | Test |
|---|---|
| two writes race on one draft | unit: the second compare-and-set loses, is retried, and is refused with the reason past its tries |
| `submit` races `take-over` | unit: one wins; the other is refused naming the new author or the new version |
| two reservations race | unit: two numbers, or one refused; never one number twice |
| a write cut between the history and the head | the ledger's integration test (design 25 § 12.7): the call answered that the operation is taken; the next `apply` derives the head. The module's own integration test: stopped after `apply`, restarted, it sends the event once |
| a failure before the operation is appended | unit: the call is refused, and no head, event or version follows later |
| a change through the bus during the move | unit: read back from the database, so a rollback of the delivery reads a current database (ADR 0592 §14) |
| a section changed after the operator's Approve | unit: the record is asked again; a version with every section unchanged is not (ADR 0592 §21) |
| a head behind its history | unit: health unhealthy naming the lag; the ledger's `rebuild` clears it |
| a text does not hash to its digest | unit: `apply` refuses the `write-section`, and a read refuses it, naming the digest |
| a full ledger state | integration: `submit` answers taken with the head behind; health unhealthy naming the cap |
| a full ledger history | integration: `submit` refused with the head unchanged |
| a judgement timeout for one part | unit: that part stays asked and the version proposed, saying which; the others keep their verdicts |
| a restart with parts asked | integration: the parts in `asked` are collected again and judged |
| `reviewed` once per version | unit: one `reviewed` after the last `part-reviewed`, carrying every verdict |
| told once | unit: a whole-set finding told once across a restart, again only after its mark is cleared |
| a second run of the move | unit: changes nothing and says so |
| the move's check | unit: a changed review, a missing finding and a missing ask, each named |
| writes during the switch | unit: every writing verb refused with its reason; reading verbs answer |
| an older manifest validator | the manifest validator's test (ADR 0595 §8): a manifest asking for a ledger in `requires` refused by a manifest validator that does not know the template, accepted by one that does |
| the bus module's forms | the bus module's test (design 25 § 12), against a real bus server: the ledger, states and stream created for their module, `reviews` heard by a module granted it in `readers` and by no other; the condition at 75 percent raised and cleared below |
| a reference | unit: "record › title › row" resolves to the section; a nested title is refused |
| a form-only version | unit: accepted when only names and links changed and each target resolves; refused otherwise |
| an unproven caller | unit: `open`, `write`, `submit`, `propose` and `take-over` refuse it |
| the index behind | unit: health unhealthy while the index's sequence is behind the ledger's state; `ask` refuses "index not built" |
| a forward delivery after a rollback | unit: an acceptance and a verdict made by the older module are found by the check at start, the writing verbs refused meanwhile, the changes copied and checked, then writes served; a record changed on both sides is told to the operator |
| a restart between `apply` and the database write | unit: the module is stopped after `apply` and before the database write, restarted, and the database matches the history; health showed it behind meanwhile |
| the database refuses past its tries | unit: `database-behind` names the record; the drop is refused while it stands; the catch-up tool clears it |
| a restart between `apply` and its event | unit: the module is stopped after `apply` of a `review`, restarted, and sends one `reviewed`; a second start sends none |
| the move as operations | unit: each record's versions copied as `write-section` and `submit` operations in order; the derived head equals the database's; a second run appends nothing |
| the start | integration: the time to a built index measured and reported, failing above 40 seconds, the estimate's top |
| A section is a part with a title | a table test, one case per refused name and text of § 2.2; a form-only version whose text changed beyond its links is refused |
| Every bucket has a tool, and health says the index | the manifest test compares tools and events with the code; a unit test of the health before and after the index is built |
**The third slice's acceptance tests** (§ 9.1 to § 9.3; research 062's direction), what its build proves before it
is done:
@@ -318,9 +746,161 @@ is done:
8. Every entry of the glossary's Config section is filed under the Config domain, and the domains the entries name
are the twelve of ADR 0354.
9. Tests 1 to 8 pass together after the one delivery, run against main and the live knowledge base, with nothing
in this repository, the catalogue or the instruction text pointing at a removed path.
in this repository, the catalog or the instruction text pointing at a removed path.
**The fifth slice's acceptance tests** (§ 1, § 2, § 4, § 5, § 8.1; ADR 0592), what its build proves before it is
done:
1. The move's check, run live, names no difference between the database and the bus: 656 decision records and 80
research efforts (the counts of 2026-11-02, or the counts on the day), every version, clause and link, and the
digest of every section of every version.
2. The operator is told that result and asked before the database is dropped; after the yes and the delivery, the
module's manifest requires no database and the store holds none for it.
3. A session writes a research effort of more than 100 KiB one section at a time from one node; a session on another
node takes the draft over with a reason, the first session hears `taken-over`, and the second submits it.
4. Every changed section of that effort is judged on its own, each question under 60 KiB, and the effort is
accepted once every part approves.
5. A section named like a file, a text holding a local path, and a section over 40 KiB are each refused, the last
saying split it.
6. After the titles' form-only versions, no record holds a section named like a file, `history` shows each as a
change of form, and `get` of "research 062 › Direction" answers that section.
7. The fill tool shows each bucket and stream against its cap; the second version of a record with one changed
section adds one `write-section` and one `submit`, not one operation per section.
8. During the move's window a `write` is refused saying the knowledge base is moving; after the switch a restart
still serves from the bus; the health names the source and the check's result.
9. A part's review waiting on the judgement tool survives a restart of the module, and one past 30 minutes reaches the
operator once.
10. Every test of the table above passes in the one check of the pull requests, within the test budget.
11. As a ledger (ADR 0597 How it is checked, clauses 11 and 12): `get` answers the same digest for every record
before and after the move; `ask` answers from bodies read from their operations; `mesh-knowledge.reviewed` is
emitted once per review; the module's manifest asks for no stream `versions`, no object bucket `sections` and
no state `names`, and the bus holds none for it once the move's check is clean; its tools and health name the
ledger's repairs and lag, and no digest store; the consumers of `reviews` still hear it.
## 11. The overview page
**The knowledge base serves one read-only web page for the operator** (ADR 0616 §1), so the state of the work is one
address away rather than an answer read in chat. It shows three blocks: every design in progress with its milestones
and their issues (the tree the `progress` verb answers); the decisions and research efforts accepted in the last seven
days and those waiting (proposed, or waiting for the operator's Approve); and what waits on the operator: records
waiting for an Approve, the operator channel's open asks and the delivery groups waiting for an Approve. The seven days
are counted from the ledger's dates when the page or its tool answers, never kept as a window in the model. What
reached which nodes is not on it: a merged group no longer waits on the operator.
```
mesh-knowledge's process
├ its own ledger records, their status and dates (no first view needed)
├ issue tracker first view: milestones, list then its events
├ seat mesh-delivery first view: groups then group, transition, merged
├ seat operator-channel first view: asks then the router's offered, closed
│ (a restricted stream granted to the knowledge base alone)
▼
the page's model, in memory ──▶ the page (GET only) ──▶ route proxy ──▶ the operator
└▶ its tool (the model as data)
```
- **Built from mesh paths alone** (ADR 0616 §2). Besides its own ledger, the model comes from three other modules, each through
a verb for the first view and events after it: the issue tracker's `milestones` and `list` and its events; the seat
`mesh-delivery`'s `groups` and its `group`, `transition` and `merged` events, a group leaving the block on `merged`;
and the seat `operator-channel`'s `asks` and the router's events `offered` and `closed`, an ask entering the block on
`offered` and leaving it on `closed`. It never hears an asker's `decided` family. It reads no other module's bus
state (ADR 0596 §2), and its manifest holds no `reads` entry, which the manifest validator refuses (ADR 0595 §8).
- **The router says when an ask starts and ends** (ADR 0616 §7). The router holding `operator-channel` emits `offered` when it
offers an ask on a channel, and `closed` once for every end of an ask: answered, expired, cancelled by its asker,
replaced by a newer ask about the same subject, or ended by the router itself on an `unlink` or `allow-link`. Each
carries the ask's id, asker, headline and the channels it was offered on, and `closed` how it ended; never an option,
a token or a warrant's proofs, so neither says more than `asks` already answers. Both go on a restricted stream of
the router (ADR 0363 §4), heard only by a module the router's trusted config value `readers` grants, which names the
knowledge base alone; `decided` stays read by its asker only. The stream is of the template events: kept seven
days, capped at 64 MiB, dropping its oldest when full, so a page down longer than a week rebuilds from `asks`.
- **Current on events, never polled** (ADR 0616 §3). Each source's block is built once at start from its verb, its first view,
and then kept in memory from that source's events. A verb is asked again only for a source marked unanswered.
- **A source that does not answer says so, never shows as empty** (ADR 0616 §6). A source is marked unanswered for one of two
causes, named in the mark: its verb did not answer within its bound, or its subscription missed the bus's idle
heartbeat past its bound, so a lost subscription or a silent source is found, not taken for a quiet one. Its block,
on the page and in the tool's answer, then says so with the time of its last answer (the verb's last answer or the
subscription's last event or heartbeat, whichever is later). A mark from the verb: the verb is asked again on a
bounded backoff (from 10 seconds, doubling, at most every 5 minutes), and its first answer rebuilds the block and
clears the mark. A mark from the subscription: nothing is asked while it is silent; its next event or heartbeat
makes the module ask the verb once, to rebuild the block with what it missed, and that answer clears the mark (an
unanswered verb then turns the mark into one from the verb). These are the only asks the page makes after start.
- **It writes nothing** (ADR 0616 §4). The page has no form and no verb behind it and answers GET only. It is served by the
module's own process on a port the module declares, reached through the route proxy by a route the module
requires, which only the operator may open. The port listens `from: machine`, the narrowest listening scope the
manifest has today, so a connection from another node is refused. That scope does not name a module: every local
process of the knowledge base's node reaches the port, not only the route proxy, until issue 1968 gives a scope
that grants one module's process. That scope is a change to mesh-sdk's manifest types, so it rebuilds every module
that imports them, and it rides a later milestone's one rebuild rather than adding one here. A route proxy runs on
the knowledge base's node (read from placement, 2026-11-04), so the page is reachable through it; a route proxy on
another node cannot reach a port listening `from: machine`, so a page placed where none runs is unreachable until
issue 1968.
- **Every number on it can be read by a tool** (ADR 0616 §5): a tool of the knowledge base answers the page's model as data,
marked reads, so the page shows nothing a tool cannot read (tools-are-how-a-module-is-spoken-to); a second tool,
marked acts, asks one source's verb again by hand and rebuilds its block, recorded as a hand act.
- **Health.** The module's health carries the page's last rebuild and each source's last answer, and is degraded while
any source is unanswered.
- **Built after the ledger store**: the page reads the records from the ledger (§ 2.1), so it is built after the
knowledge base's ledger store, in the same milestone (ADR 0613 §1).
How it is checked (ADR 0616 *How it is checked*): a unit test builds the model from fixture issues, milestones,
records, groups and asks and sees the three blocks; a fixture `group` or `transition` event changes the delivery block
and `merged` takes the group out; `offered` adds an ask and `closed` takes it out; no verb is asked again in either
case; a record accepted eight days before the answer's time is not in the seven-day block, with no event between. The
manifest has no `reads` entry, names `groups` and `asks` among what it invokes, and consumes no `decided` family. The
handler refuses any method but GET, and the route's grant names only the operator. The tool's answer equals the model
the page renders. For each source, a verb failing at start marks it unanswered from the verb on the page, in the tool
and in the health, never as an empty list, asked again on the backoff alone, its first answer clearing every mark;
and a subscription stopping its heartbeat marks it unanswered from the subscription, asks nothing while silent, and
asks the verb once on its next event or heartbeat. In the router, an ask offered emits `offered` once and each of its
five ends emits `closed` once with how it ended, with no option, token or proof in either body; the knowledge base
hears the stream and another module, an asker among them, is refused. A connection to the page's port from another node
is refused (what `from: machine` gives; a local process other than the route proxy is not refused before issue 1968). The re-read tool rebuilds one source's block and asks no other. Live: after its delivery the operator opens the
page and sees design 47's milestones, rendered headless and looked at before it is handed over.
## What it leaves out
Semantic or vector search; a browser view; line comments on a proposal (the judgement's findings name the section and
clause instead); and the rules of how-we-build, which are not decision records. Each needs a decision of its own.
Semantic or vector search; a browser view other than the overview page of § 11 (its reading of the buckets is
announced, ADR 0592); line comments on a proposal (the judgement's findings name the section and clause instead),
and any form or writing from the overview page; and the rules of how-we-build, which are not decision records. Each
needs a decision of its own.
## Reviewed by architectural domain
The fifth slice was reviewed by architectural domain on 2026-11-02 (four reviewers, two architectural domains each; the knowledge base's own
review of ADR 0592's fourth version beside), and the lead ruled on every finding. What was found, and what answers it:
| Architectural domain | Found | Answered by |
|---|---|---|
| security | unproven callers could write or take over; an Approve did not bind the sections shown; readers were named outside ADR 0363's grant (the knowledge base's review of version 6); a proposal waiting on the operator could be taken over; readers' grants and a body's match with its name were unsaid; a draft had no bound | ADR 0592 §4, §8, §9, §17, §19, §20, §21; § 2.1, § 4 |
| seams | asked parts lived only in memory; told marks and reservations had no form on the bus; the judgement tool's ticket is polled; who creates buckets and grants was unsaid; the judgement tool is a module's tool, not a seat | ADR 0592 §2, §7, §16, §23; § 1, § 5 (a seat for judgements a note on issue 1956), § 8.1 |
| running qualities | three writes could stop halfway; caps had no figures; a usual revision judged every section again, with no limit on parallel calls; start time unknown | ADR 0592 §10, §22, §25; § 1, § 2.1 (caps), § 5 |
| health | a stale index, a missing body, a full bucket and the move's state were not visible; waiting reviews and idle drafts were not counted | ADR 0592 §25, §33; § 1.1 |
| events and logs | per-part verdicts would have broken every wait on `reviewed`; events did not say what they touched; a take-over's reason and each section's author were lost after 30 days | ADR 0592 §3, §27, §34; § 1.1 (the events table) |
| testing | each failure path lacked a test; the budget was not counted | ADR 0592's How it is checked; § 10 (the failure-path table) |
| upgrade | writes during the switch, a rollback after it, and the order of the three deliveries were unsaid; the form-only check did not prove new link targets | ADR 0592 §13 to §16, §31; § 8.1, § 2.2 |
| tools | unnamed objects, missing bodies, form-only versions, asked parts and told marks had no tool | ADR 0592 §32; § 1.1 (the tools table) |
The knowledge base's review of the fourth version found that the reference form read as nested sections: ADR 0592
§30 and § 2.2 say sections never nest.
### The amendment of 2026-11-03
The amendment of 2026-11-03 to ADR 0595, ADR 0596 and ADR 0597 (designs 25 § 12, 32 § 4 and 55 together) was
reviewed by the four reviewers by architectural domain side by side (playbook 01), over three rounds, and the lead
ruled on every finding. What was found, and what answers it:
| Domain | Found | Answered by |
|---|---|---|
| security | the author could be words the module chose; a person's dangerous tools had no role, mark or path to the process; the caller travelled as a plain field | design 25 § 12.3 (marks, the process's own tool subject, the identity seat's signed token), § 12.4 (the tool runner stamps the caller it proved; the move's authors marked imported) |
| seams | the bus module asked for its own events in the new form, which it would have to create itself (ADR 0595 §10); a person's tool had no join to the process; a verdict was written twice with no order | design 25 § 12.3 (its events on its old `streams` section; the process's own tool subject); design 55 § 2.1 (the `review` operation first, `reviews` caught up from it) |
| running qualities | overdue creation was undefined and raised by nobody; the database's rollback write lived in memory; a forward delivery after a rollback could miss acceptances and verdicts; no size estimate of the heads | design 25 § 12.2 (five minutes, the watchman, durable consumers, `check` at start); design 55 § 8.1 step 6 (`database.sequence`, the check at every start before the drop), § 2.1 (the heads' estimate) |
| health | the bus module's health would have fired on a quiet mesh; conditions had no clearing; `database-behind` had no clearing | design 25 § 12.2 and § 12.3 (each condition with what clears it); design 55 § 8.1 step 6 |
| events and logs | an event lost when the module stopped after `apply`; the bus module's events had no reader | design 55 § 1 (each event sent with its operation's sequence as id, the state `sent`); design 25 § 12.3 (`history` of one entry) |
| testing | the bus module had no test that starts it whole; live tests would have filled the live bus; the budget was not counted | design 25 § 12.7 (the nats module's integration test, live drift only by a manifest change, the budget paragraph); design 55 § 10 |
| 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 |
**Left to the operator**, because each changes an accepted record: a margin between raising and clearing the
condition `full` (ADR 0595 §6 raises and clears it at 75 percent, so an entry sitting there flaps), and an event of
its own for `drop` and `recreate`. **A correction of fact** for ADR 0595 §4: the bus module deletes through `recreate`
as well as `drop`. Each is noted on issue 1966.
@@ -88,7 +88,7 @@ and may not be copied to anyone else. The vendor serves only its newest version,
file (a `file://` URL), with `updates_disabled`. Betterbird installs it into every profile, and the person
cannot remove it.
Owl declares the range of Betterbird versions it supports. The catalogue's check refuses a manifest whose
Owl declares the range of Betterbird versions it supports. The catalog's check refuses a manifest whose
Betterbird pin lies outside the range of its Owl pin, so a Betterbird upgrade that Owl does not support yet
waits for Owl.
@@ -205,7 +205,7 @@ module needs.
**The preferences are one entry each.** The setting `prefs` maps a preference's name to its value, so a node's
layer overrides one preference, or takes one out with null, and the operator's setup lives in the mesh-wide
layer, not in the catalogue. The module ships only its policy's locks and the names it keeps at Betterbird's own
layer, not in the catalog. The module ships only its policy's locks and the names it keeps at Betterbird's own
default (issue 586). `prefs` refuses a credential's preference, an account's (§4), and the four prefixes the
settings below own: `calendar.registry.`, `calendar.list.`, `ldap_2.servers.` and `mailnews.tags.`, so each value
has one owner.
@@ -254,11 +254,11 @@ own layers. With `propose` it proposes the next layer for the operator's Approve
each node's that needs one, each only after the one before it was set or declined, against the layer as it then
stands and carrying that layer whole (ADR 0277 keeps one open ask per module and machine). It proposes nothing
while a desktop node does not answer, because a layer derived without it would put on every node what only some
hold. The first mesh-wide proposal also carries the operator's setup of `prefs`, which the catalogue held before.
hold. The first mesh-wide proposal also carries the operator's setup of `prefs`, which the catalog held before.
## How it is checked
- **The catalogue's tests:** both pins carry a URL, a version and a sha256; a Betterbird pin outside Owl's range
- **The catalog's tests:** both pins carry a URL, a version and a sha256; a Betterbird pin outside Owl's range
is refused; the generated policy file names Owl as `force_installed` from the placed file with
`updates_disabled`, and sets `DisableAppUpdate`; `prefs` refuses the account prefixes and the four of §8;
`accounts` refuses a password-like field; a declared account's user.js holds only the module's own keys; every
@@ -38,7 +38,7 @@ request, and the five, sharing their branch's name, are one delivery group (ADR
future state. The five are merged within one merge window, so they are one batch and one rollout (ADR 0276
§1, §2), in an order declared with `after:` lines in each pull request (ADR 0239 §11): mesh-sdk, then
`mesh-host`, then mesh-controller, then mesh-catalog, then hq. The release holds every package but T6, R1 and R2:
the media catalogue and the applications live in repositories of their own and move after it, and only
the media catalog and the applications live in repositories of their own and move after it, and only
then can the old forms be refused (R1) and the record say what runs (R2).
**The moves of data run after the delivery, in this order, each a verb that says what it did:**
@@ -58,7 +58,7 @@ the backlog rollout once it is heard from (ADR 0360 §10).
**Nothing breaks on the way.** ADR 0349 clause 17: each file is filled the old way or the new way, never
both, by the form of its manifest, and the old forms stay accepted until the last module has moved.
Inside the release this still holds: the media catalogue and the applications kept in their own
Inside the release this still holds: the media catalog and the applications kept in their own
repositories move after it, so the old forms stay accepted until they have (R1).
**Where it stands, 2026-10-17** (the Milestones section below). The packages' branches were merged into
@@ -169,9 +169,9 @@ as T2.
**T5 (issue 658) — The ten modules without a build.** *mesh-catalog. A day.* ca-trust, de-spiegel, invoicing,
local-model-consumer, matrix, node-env, only-office, sshd, step-ca and supabase gain an archive build for
their templates. **Proof:** as T2; afterwards no manifest in the catalogue carries file text.
their templates. **Proof:** as T2; afterwards no manifest in the catalog carries file text.
**T6 (issue 659) — The media catalogue and the applications.** *mesh-media-catalog and each application's
**T6 (issue 659) — The media catalog and the applications.** *mesh-media-catalog and each application's
repository. Two days.* **Proof:** as T2, per repository.
## 2 — Config (ADR 0348)
@@ -185,10 +185,10 @@ object or list not trusted; a predefined key not on the list or of another type
value falling back to a trusted key; a value neither in a template nor read at runtime; a placeholder
naming an undeclared value; a `reload-on` or `restart-on` naming an undeclared file; a moved module's
mergeable file not naming its keys; a mesh word or `puid`/`pgid` in `takes-config`. **Proof:** the registration refusal tests, one per
rule; every manifest in the catalogue still registers.
rule; every manifest in the catalog still registers.
**K2 (issue 661) — The list of predefined keys.** *mesh-controller and mesh-catalog. A day.* `predefined.json` at the
catalogue's root, with `font-size` and `agent-managed-settings` first; the build validates it and every
catalog's root, with `font-size` and `agent-managed-settings` first; the build validates it and every
manifest naming a key; the merge check refuses removing a key still named or holding a value; the newest
trunk build's list is published. **Proof:** the merge check refuses a planted removal; an older build's
list does not replace a newer one.
@@ -214,9 +214,9 @@ the controller reads `mesh-config_resolved` where it read its layers (ADR 0349 c
an exception to ADR 0348 §9 that R1 removes), and `settings` answers by forwarding to `config`. **Proof:** composition of
every node before and after is byte-identical; `settings` and `config` list the same values.
**K6 (issue 665) — The catalogue says config.** *mesh-catalog. A day.* The 15 modules using `${setting:}`, the 9
**K6 (issue 665) — The catalog says config.** *mesh-catalog. A day.* The 15 modules using `${setting:}`, the 9
declaring settings and the 4 with `takes-settings` move to the new names and the full declaration.
**Proof:** the catalogue's check finds no old name in a moved module.
**Proof:** the catalog's check finds no old name in a moved module.
**K7 (issue 666) — The operator's acceptance on dunst.** *live. An hour.* With every level cleared the first
workstation's dunstrc says 10; a mesh font size, then that node's font size, then dunst's own value on
@@ -326,7 +326,7 @@ ADR 0349; claude-code reads its managed settings through it.
## 8 — The old forms go (ADR 0349 clause 17)
**R1 (issue 682) — Refused and removed.** *mesh-controller, `mesh-host`, mesh-catalog. Three days.* Once every module of
every catalogue has moved: the catalogue's check refuses inline text, `settings`, `${setting:}` and the
every catalog has moved: the catalog's check refuses inline text, `settings`, `${setting:}` and the
old contribution forms; the controller's filling passes but placement, its settings, secret and binding
code and tables (a new migration) go; the node-engine keeps opening sealed values for the core's files
only; the controller stops reading `mesh-config_resolved`. **Proof:** the controller's test that its
@@ -345,7 +345,7 @@ each makes true. Whether a milestone's issues are delivered is read from the iss
| # | Outcome | Packages | Issues |
|---|---|---|---|
| 1 | Config, provisioning, secrets, bindings, collections and runtime asks run the new way; the old forms are still accepted | every package but T6, B3, R1, R2 | 647, 650 to 679 but 659, 681, 684, 685 |
| 2 | The media catalogue and the applications carry their file text as templates | T6 | 659 |
| 2 | The media catalog and the applications carry their file text as templates | T6 | 659 |
| 3 | The other providers answer their consumers; the old forms are refused; the record says what runs | B3, R1, R2 | 680, 682, 683 |
## What is deliberately not here
@@ -128,7 +128,7 @@ identity present on a machine into that machine's declaration, and the node-engi
resource. A login that exists is adopted under its name, uid and home; the mesh never renames or deletes one. An
agent's machine account has its own home and group, no password, no root group and no sudo rule, and the node-engine
judges on every look that it cannot become root without a person, by the ways ADR 0266 §12 to §17 list. No module declares a login for a
person or an agent: claude-code's `agent-account` resource goes, and the catalogue's check refuses a manifest that
person or an agent: claude-code's `agent-account` resource goes, and the catalog's check refuses a manifest that
declares one. The node record's operator account and agent account are read from the identities, no longer stated
at the controller's terminal or in the mesh-config snapshot; the machine facts `account`, `agent-account` and their
homes keep their names. A machine names an agent account only where the identity seat marks an agent as its agent
@@ -204,8 +204,8 @@ Checked on 2026-10-17 (playbook 02, step 1); no conflict was found.
## 6. Effects, asks and break-glass (ADR 0387)
Every seat verb and module tool is one permission and carries one **effect**, set in its module's manifest:
**reads**, **acts** or **dangerous**. The catalogue's check refuses an unmarked tool, once every module already in
the catalogue is marked. A dangerous tool is granted only by name, and naming one in a role goes to the operator as
**reads**, **acts** or **dangerous**. The catalog's check refuses an unmarked tool, once every module already in
the catalog is marked. A dangerous tool is granted only by name, and naming one in a role goes to the operator as
an ask first. Every other dangerous act is an ask (ADR 0259), bound to that act and carried out on the warrant.
The **break-glass** agent holds every tool and never asks. It is sealed until the operator opens it, or a condition
@@ -246,7 +246,7 @@ carry them:
1. A licence token replaced under a running session keeps that session working.
2. The sandbox module loads KVM on the home server, and a sandbox runs there.
3. Every existing module's tools carry an effect, and the catalogue's check refuses an unmarked one.
3. Every existing module's tools carry an effect, and the catalog's check refuses an unmarked one.
4. The switch, run on the mesh's own modules in the lab from the bed test kept on the lab's branch
`research/053-signed-bus-logins`, loses nothing and leaves every identity on the new bus.
5. The acceptance sentence at the top, end to end.
@@ -260,7 +260,7 @@ From research 057 (ADR 0411 to ADR 0414):
unaltered and the self-check raises `agent-can-become-root` for it, on a machine that marks no agent account too;
the operator's existing logins are
unchanged.
8. No manifest in the catalogue declares a login for a person or an agent; the catalogue's check refuses one.
8. No manifest in the catalog declares a login for a person or an agent; the catalog's check refuses one.
9. For every machine, the declaration before and after differs, for the modules not set to run for an identity, only
in the machine accounts' `user` resources (now the controller's, and `nox` added on the other machines); claude-code on the control node, run for `nox`, places the same
files in the same home; on the other machines the guard stays off and the operator's sessions keep the mesh's tools.
@@ -292,7 +292,7 @@ and the issue tracker takes only registered owners. The building waits until the
| # | Outcome, in one sentence | Proves | Repositories and their parts | Depends on |
|---|---|---|---|---|
| 1 | Every tool on the mesh says whether it reads, acts or is dangerous, a tool's description shows it, and the catalogue refuses a module that leaves one unmarked | test 3 | mesh-sdk: the effect in a tool's declaration, an unmarked tool served as dangerous; mesh-controller: the manifest field; mesh-catalog and mesh-media-catalog: every module marked, the check | — |
| 1 | Every tool on the mesh says whether it reads, acts or is dangerous, a tool's description shows it, and the catalog refuses a module that leaves one unmarked | test 3 | mesh-sdk: the effect in a tool's declaration, an unmarked tool served as dangerous; mesh-controller: the manifest field; mesh-catalog and mesh-media-catalog: every module marked, the check | — |
| 2 | A session works on a repository's workspace through the mesh's tools alone: read, glob, search, edit, write, git, its tests and its merge check, with no command runner | — | mesh-catalog: the module `nox-workspace` on the node seat `workspace`, on the always-on nodes; mesh-controller: the seat | 1 |
| 3 | A thread created through the thread seat runs headless on an always-on node, its conversation readable through the seat, its usage counted per thread, and a move to another node loses at most the turn in progress | — | mesh-catalog: `nox-threads` (seat `thread`, restricted streams, leases), `nox-thread-handler` (seat `thread-handler`), claude-code (mirror and rebuild), claude-licence-manager (usage per thread) | 2 |
| 4 | The operator starts, follows, answers and stops a thread from a terminal client, and answers its questions on Telegram | — | mesh-catalog: the terminal client, a Go program of `nox-threads`; claude-code: questions and permission requests through the asks | 3 |
@@ -313,7 +313,7 @@ waits for nothing; 12 waits for milestone 6.
| # | Outcome, in one sentence | Proves | Repositories and their parts (issues) | Depends on |
|---|---|---|---|---|
| 11 | The agent's forge account is `nox`, with its keys and its place in the agents' write team kept | test 12 | mesh-catalog gitea: the rename, keys registered on `nox`, every `forge-account` entry (993) | — |
| 12 | The mesh makes the operator's logins and nox's on every machine from the identities, and judges nox unable to become root everywhere | tests 6 to 9 | identity module: logins, machines, kept logins, the agent account mark, the operator's verb (994); the node-engine (`mesh-host`): existing logins adopted, every agent login judged (995); mesh-controller: machine accounts composed, node accounts read from the identities, the terminal lines retired (996); mesh-catalog: claude-code declares no login, the catalogue's check refuses one (997) | 6 |
| 12 | The mesh makes the operator's logins and nox's on every machine from the identities, and judges nox unable to become root everywhere | tests 6 to 9 | identity module: logins, machines, kept logins, the agent account mark, the operator's verb (994); the node-engine (`mesh-host`): existing logins adopted, every agent login judged (995); mesh-controller: machine accounts composed, node accounts read from the identities, the terminal lines retired (996); mesh-catalog: claude-code declares no login, the catalog's check refuses one (997) | 6 |
| 13 | The operator and nox each reach the bus with their own password, held to their role; the operator's only where no agent runs as the operator | test 11 | mesh-controller: the operator's and nox's bus accounts, secrets at 0600, the fifteen-minute verdict (999); identity module: nox's role refuses approvals and dangerous tools (998); until milestone 7 builds the asks, a dangerous act of nox's is refused, not asked | 12 |
| 14 | The operator starts a claude-code session for nox or for themself, and nox pushes over SSH with its own key | test 10 | mesh-controller: run for, assignments keyed by identity, the refusals (1001); mesh-sdk: calls as the identity, a start goes down only (1002); claude-code: started for nox or for the operator (1003); ssh-client and gitea: nox's own key, closing issue 989 (1004) | 11, 13 |
+1 -1
View File
@@ -279,7 +279,7 @@ before `mesh-mail-notifier` is unassigned; test 12 with milestone 4.
|---|---|---|---|---|
| 1 | In a browser on the laptop and the workstation, the operator signs in and browses, searches and reads every account's mail with its attachments, and writes a mail that goes out on their Approve | tests 1 to 9 | mesh-catalog: `mesh-mail`'s account bucket (issue 1255, ADR 0439 §2); the module `mesh-mail-web` (manifest, sign-in, the pages, the send, the seat's verbs, the integration test) | — |
| 2 | Each new mail is read into a mail group on the mail page; the mail that matters reaches the operator's phone as one mail signal, a scam warning shows on the page only, the operator's corrections become reading lessons, and the pop-up for every new mail is gone | tests 10, 11, 13 to 17 | mesh-catalog: the seat `mail-reading` declared in `mesh-mail`'s manifest; the module `mesh-mail-reader` (batches, mail entries, reading lessons, mail signals, health, the integration test); `mesh-mail-web`'s mail groups, mail signals, scam warnings and reading lessons; `mesh-mail-notifier` unassigned (issue 1418) | 1 |
| 3 | Betterbird is gone from the laptop and the workstation, its profile and mail kept in the home | ADR 0379 §2 | mesh-catalog: Betterbird unassigned on the operator's Approve, then the `betterbird` module removed from the catalogue (issue 806) | 2 |
| 3 | Betterbird is gone from the laptop and the workstation, its profile and mail kept in the home | ADR 0379 §2 | mesh-catalog: Betterbird unassigned on the operator's Approve, then the `betterbird` module removed from the catalog (issue 806) | 2 |
| 4 | **Replaced by design 63** (2026-10-22): on the mail page the operator asks questions about their mail and gets the mails that answer them, in a mail conversation kept as a thread | test 12 | mesh-catalog: `mesh-mail-web`'s mail conversation as a client of the thread seat; the thread's mail tools under a caller of their own (issue 1419); `mesh-mail`'s folder case and `-any` switches | 2 (the reading lessons); design 58's milestone 3 (issue 880) |
**Milestone 1, confirmed by the operator on 2026-10-19, is delivered;** its live proof on the laptop and the
+2 -2
View File
@@ -199,10 +199,10 @@ missing page and expects the error.
## Milestones
The milestones build ADR 0468, feature `files-through-the-store`. They are cut by release order: the catalogue's
The milestones build ADR 0468, feature `files-through-the-store`. They are cut by release order: the catalog's
merge check reads manifests with the controller the mesh runs, and the controller vendors the SDK, so a new
manifest field ships SDK first, then the controller and every other strict reader of manifests (the build modules,
the delivery's indexer), then the catalogue (playbook 07, *a new manifest word*).
the delivery's indexer), then the catalog (playbook 07, *a new manifest word*).
| # | Outcome | Proves | Repository | Issues |
|---|---|---|---|---|
+1 -1
View File
@@ -48,7 +48,7 @@ document is written and this one's status becomes `implemented`.
| [`45-a-core-that-cannot-fail-silently.md`](45-a-core-that-cannot-fail-silently.md) | **Designed.** The core says when it is wrong, refuses what is stale or unreadable, heals what it knows, upgrades one machine at a time with a witness that rolls it back, and is checked against the real mesh before merge: the writers and signals tables, the condition store, `doctor`, the minimal output channel, healers, the lease and report order, staged upgrades, the facts snapshot and replays, in six phases | ADR 0227, ADR 0224, ADR 0218 |
| [`46-the-conversation-with-the-operator.md`](46-the-conversation-with-the-operator.md) | **Designed.** The mesh tells and asks its operator over channels that are holders of two kinded benches, `channel` and `intake`, declaring capabilities from a fixed vocabulary; the router orders them by work context and never lowers the bar; an answer that performs an action is checked and performed by the controller, on a TOTP code or a verified Telegram sender, never on a desk click alone; operator messages addressed or answered by the mesh's responder, untrusted input kept as data, references for what words may not carry, and a recoverable factor; Telegram first, in six phases | ADR 0234, ADR 0227 |
| [`47-delivery-from-commit-to-delivered.md`](47-delivery-from-commit-to-delivered.md) | **Designed.** A delivery is one commit in one repository, from its pull request's head to every machine; a delivery group is deliveries sharing a branch name, ordered and checked as one future state; both owned by the `mesh-delivery` module with one state table, its state on the bus, every transition said, noted on the commit and shown on the pull request; the controller keeps the planner, the gate, sending and the rollout, and the core's own updates never wait for the module | ADR 0239, ADR 0238, ADR 0236 |
| [`49-the-mesh-in-domains.md`](49-the-mesh-in-domains.md) | **In progress.** Every concept belongs to one of eleven domains, which owns its one word; the glossary is organised by them and is the authority, a retired word is named on its replacement's line with its scope, and two checks hold this repository's documents and the catalogue's tool descriptions to it | ADR 0244, ADR 0006, ADR 0008, ADR 0302 |
| [`49-the-mesh-in-domains.md`](49-the-mesh-in-domains.md) | **In progress.** Every concept belongs to one of eleven domains, which owns its one word; the glossary is organised by them and is the authority, a retired word is named on its replacement's line with its scope, and two checks hold this repository's documents and the catalog's tool descriptions to it | ADR 0244, ADR 0006, ADR 0008, ADR 0302 |
| [`50-split-dns-on-a-machine-with-a-vpn-client.md`](50-split-dns-on-a-machine-with-a-vpn-client.md) | **In progress.** A machine whose VPN client pushes servers of its own runs a resolver of its own, on a node seat, that routes the VPN's domains over its link and every other name to the mesh's resolvers; the VPN client's module carries the adapter | ADR 0247, ADR 0223 |
| [`51-the-registries-keep-what-is-named.md`](51-the-registries-keep-what-is-named.md) | **In progress.** The artifact store, the package registry and each machine's container runtime get tools that say what they hold, what names each thing and what could go; every removal is a dry run unless a person asks and says why, and what decides is always a record | ADR 0251, ADR 0189 |
| [`52-shares-and-mounts.md`](52-shares-and-mounts.md) | **In progress.** A node shares one folder at a time through `nfs-server`, which provides it as a provision to the private network only, mapping every client to the folder's owner; a node that asks mounts it through `mounts`, a mount unit and an automount per share, so nothing mounts or fails at boot; a device that comes and goes is an occasional source whose absence is a state | ADR 0263, ADR 0051, ADR 0092 |
@@ -1,8 +1,8 @@
# Diagnosis — 2026-09-21
1. The report's own remedy was taken: the same order against a second ACME implementation. The
catalogue's own certificate authority, step-ca, was raised in the bed beside Pebble, pinned as
the catalogue pins it, and the same proxy pointed at it over the same challenge path. It issued
catalog's own certificate authority, step-ca, was raised in the bed beside Pebble, pinned as
the catalog pins it, and the same proxy pointed at it over the same challenge path. It issued
within a second of the order.
2. The name was still not served, and the reason was neither authority's: the bed's stand-in
backend, a netcat loop behind the route, used flags this machine's netcat has not got and never
@@ -1,6 +1,6 @@
# Diagnosis — 2026-09-21
1. The catalogue was read again for mounts no resource declares: twenty-four remained, in two
1. The catalog was read again for mounts no resource declares: twenty-four remained, in two
kinds only. Nine media modules mount the operator's library, and every one of those paths is
already in the module's `accesses` — the vocabulary ADR 0051
gave exactly this. Four modules mount the container runtime's socket, and every one of them
@@ -9,6 +9,6 @@
check that was withdrawn needed only to read both: an access is a declared path, and a
capability declares the facility it grants.
**Located in:** the catalogue's parser. The check is back, refuses an undeclared mount naming the
path and the three remedies, and a test parses the whole catalogue. Decided in
**Located in:** the catalog's parser. The check is back, refuses an undeclared mount naming the
path and the three remedies, and a test parses the whole catalog. Decided in
ADR 0091.
@@ -18,7 +18,7 @@ Not "a registry cannot be installed" — **a mesh cannot hold its own modules.**
The artifact store is one store for everything a module ships: images, and archives, which are
directories from a module's repository packed and pushed as content-addressed blobs. So it is the
mesh's module catalogue in artefact form, and the same role a separate object store plays in the
mesh's module catalog in artefact form, and the same role a separate object store plays in the
arrangement being replaced.
Until it exists, a module can be described and resolved but nothing it carries can be kept
@@ -6,7 +6,7 @@ opened: 2026-09-04
## What was observed
Rolling the module runtime out to the catalogue (the runtime that serves a module's tools and
Rolling the module runtime out to the catalog (the runtime that serves a module's tools and
runs its events under the module's own account), each tools+events module receives its
configuration the way the design intends: a mergeable config file the module declares, into
which the assignment's settings are merged. The runtime container mounts that file and reads
@@ -38,7 +38,7 @@ failing to load because the value that would fix them is present but unread.
## Why it matters beyond this instance
Every tools+events module converted to the runtime model now takes its URL and credentials
this way, so this is not one module's quirk — it is the config path for the whole catalogue.
this way, so this is not one module's quirk — it is the config path for the whole catalog.
The gap turns the headline promise of the settings design ("change it without editing it, on
the fly") into "change it, then recreate the container by hand," which is the manual step the
design existed to remove. And because the file is genuinely updated, nothing surfaces the
@@ -6,7 +6,7 @@ opened: 2026-09-02
## The symptom, as observed
Found by review of the catalogue examples (2026-09-02), not by an outage — the outage is the
Found by review of the catalog examples (2026-09-02), not by an outage — the outage is the
part the design permits to be silent.
The cache module declares its access-control file as an ordinary file resource with fixed,
@@ -40,5 +40,5 @@ even when what grew inside since is somebody else's work the mesh asked for.
some other way?
- ADR 0010 treats every added resource type as a security artefact. Does a create-once
semantic widen what a compromised control plane can express, or narrow it?
- Are there other seeded-then-mutated files already in the catalogue that this failure is
- Are there other seeded-then-mutated files already in the catalog that this failure is
waiting inside?
@@ -6,7 +6,7 @@ opened: 2026-09-02
## The symptom, as observed
Found by review of the catalogue examples (2026-09-02). The media stack is several modules —
Found by review of the catalog examples (2026-09-02). The media stack is several modules —
a library server, the acquisition managers, a download client and their satellites — and each
of them declares the same library and download directories as its own resources.
@@ -28,7 +28,7 @@ shared workspace of several modules was written six times as six private ones. T
a media-stack peculiarity: any pipeline of modules handing files to each other on one machine
(an ingest directory, a spool, a drop folder) hits the same wall.
It is also a fork in the design the catalogue has otherwise avoided: the fix could be a new
It is also a fork in the design the catalog has otherwise avoided: the fix could be a new
owning module the others depend on, a shared-resource concept in the manifest, or a statement
that co-located file handoff is not a thing the mesh supports and these modules are one
module. Each answer changes what a module *is*, which is why this is an issue and not a patch.
@@ -6,7 +6,7 @@ opened: 2026-09-05
## The symptom, as observed
Found while converting the catalogue (2026-09-05), across several modules at once. A module can
Found while converting the catalog (2026-09-05), across several modules at once. A module can
declare *things that exist* — a directory, a file with fixed content, a network, a container — but
it cannot declare *a step that runs* at a defined point in its own lifecycle. Three converted
modules need exactly that and have nowhere to put it:

Some files were not shown because too many files have changed in this diff Show More