Found after G's merge: a G tool runner waits on itself, grants freezes once
G's indexer runs, the watchman does not build, gitea needs G's build runtime,
and the graph ordered the tool runner first because the SDK's calls were undeclared.
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
Milestone G was pushed with its dry run's take-in item still open; once
merged, the running indexer refused G's own indexer with the live seat
list, and its trunk builds waited on renamed packages only the take-in
publishes. Playbook 07 gains step 2b: the live take-in run whole, every
build against the published packages, the gate's merge path read for the
group, and a dry run with an open item is not a pass. The glossary gains
"dry run"; the playbooks page lists the step.
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
No template writes the four binary bytes of /etc/hostid, so it is no resource
and the composer cannot see a second writer: the apply guards it by the pool's
label, reads it back, is unhealthy on a mismatch, and keeps the file on leave.
The operator, 2026-11-12: an integration test mocks every external dependency and tests the internal wiring.
Withdraws section 637 and A-315 (A-320).
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
mesh/check being carried to 224348ff4d69 on b9cd0bc492ac | from 9ebf6e58f0d7
Cites the record's final clauses, drops the catalog check and every
write of the package's files, and writes the lead's answers as design
lines: a run that never waits on a scrub, waits ended by events,
ZFS snapshots kept in the ledger before any removal, hand acts as unit
instances, subjects per kind, the follower's findings, the readers of
the new manifest words and one node-engine integration test.
Today's node-engine writes a cron step as an invalid calendar but a
minute list as a valid one, so the scheduled run declares
0,15,30,45 and the milestone no longer waits on another session's fix.
The lead answered that a resource following a set value and one line
per list entry are built in the node-engine in this milestone, so the
module's files, units and handlers are placed only once their value is
set, as ADR 0679 holds. The cron-to-calendar fix leaves the milestone
and stays an ordering edge the scheduled run waits on.
Adds row 12 and a section to the main file, and the milestone part
zfs-owns-zfs with numbered lines and its three prerequisites, so a
builder takes ownership of ZFS's packages, files, units and one pool's
devices, properties and scheduled ZFS snapshots without a choice of
its own. Leaves one design question open (a resource that follows a
value only once it is set). Adds ZFS snapshot to the glossary beside
the two snapshots it already names.
mesh/check being carried to b03f5193b8c4 on 023a355cdb2c | from 7247b92fd6b1
A seat's view is said on its holder's module subject, so a follower must know
the holder; asking for it every 5 seconds was polling and kept a holder that
moved. It now follows the seat-holders view as A-295's holder function does,
reached from the catalog half's claim, and re-follows when the holder changes.
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
Developer J27 met, building A-210, a status view that claims no seat and an
assigner holding two seats, both followed by the teller by module name. ADR
0540 §1 already names the seat mesh-delivery-view; G defines it with its one
view, puts the assigner's asks and wants on mesh-wants, and has a follower find
the holder in the background so no start stops for it.
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
mesh/check being carried to ce0287dd2d87 on 7247b92fd6b1 | from 0d04a16560e4
A restart of resolved and a timed ask at the own resolver answered in 44-46 ms
with the first mesh resolver silent, so no read catches the pass today: the
value stays ADR 0678's until a read of resolved's server switches exists, and
the proof is the Go build steps at the next silence. The phases table and the
as-built notes go back to main: a to-be design states no live state.
ADR 0678: on a machine holding node-resolver the file names the own resolver
alone, so a program gave up after about 2 s while resolved still waited on a
silent first mesh resolver (issue 1748). Design 50 section 2 now gives the
file timeout:3 attempts:2 and how the value follows the measured pass; the
new milestone part resolver-wait holds the lines that build it, putting the
design in the shape of a main file and milestone parts.
Before any take-in the gate held no group: its records open at the take-in, and from G it writes
`merges` no more, so the forge bridge's §715 read of each member's base through `groups` had
nothing to answer from. ADR 0666 §13 has the gate form the group; §716 keeps it in the states
`deliveries` and `groups` the gate already holds (§613), heard on the seat git's pull-updated,
pull-merged and pull-closed, and says who deletes each key and how `groups` answers.
A-236 now points to it, and A-279 is carried over from the answers branch in the form §716 makes
it, its Approve-entry form dropped.
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
mesh/check pass ac294e7b8628 on f9bdd3b1d1ce | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | composition passed in 91s on 4…
The operator asked for the manager built as clean as possible, one manifest of several parts. The seat's verbs stay
on the runtime of its own, since a process account answers none; the tools that only read get a bundle of their own
so they answer while the manager fails; the carry-over ran live, so its code and the store database's and grant-key's
requirements leave now and retire on the operator's Approve. The glossary names the two senses of part.
The module-development documents described a manifest the mesh no longer
reads: four languages where the builder builds two, a Go bundle with no
system, a scheduled process the guide never said how to write, the old
kept-data sections as the norm, and the controller as the one refusing.
They now name each part of a module and its manifest form as the
manifest validator, the builder and the node-engine read it, and the
playbook lists where those parts still disagree, so an author writes
the form every part takes.
A-213 sent the validation before take-in and the per-branch take-in to design lines: the indexer needs
the run's job and verdict, what holds a revision while the run is out, and how a branch other than
the trunk gets its merges and its groups, none of which a line said.
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
The indexer writes every edge of the catalog graph, and kind 5 had no line saying which steps give it,
between which artifacts, or what fills a catalog entry's acts, which the runner and the builder read.
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
§708 says the named seat is found by its definition's delivers and its holder from the placements' holds, so no
entry field is added for it; §709 carries the manifest's contributes into the catalog entry and gives the edge kind
contribution its contract meaning; §710 writes the held revert's ask in the backup ask's shape, with one message to
the operator.
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
The operator replaced the instruction on implementing a design on
2026-11-11 about 21:48 CET: the lead answers each question met while
building in one line against the principles, and only one no principle
settles goes on, to the operator when it changes what they see or how
they work, removes data or needs their terminal, otherwise to the design
writer as a design line. Playbooks 02, 07 and 08, the glossary's design
question, AGENTS.md, the code reviewer and the drawn overview still said
only the operator or the design writer answers; they now say the rule.
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
In milestone 47/G's develop the lead answered over 100 questions, most of
them a design line meeting the code: a form the code cannot take, or a part
assumed built that was not. The prepare had read the design alone. The
operator, 2026-11-11 about 23:45 CET: the prepare reads the code each design
line lands in as well, and lists every such place before any developer
starts; the lead answers each in one line against the principles.
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
mesh/check being carried to 8d772ad40c95 on 18639c73921a | from e1819e0a0d08
The lead answered the four open questions against hq's principles on
2026-11-11: the vault serves licence secrets to the tool runner's account
(principle 6), the operator's word replaces ADR 0183 §21 and ADR 0206 §16, §18
with no record, the store database stays one milestone as the carry-over's
read-only source (principle 7, the delivery gap named), and the milestone no
longer waits for design 47's G: its conditions are said on the operator
channel as any module does today.
Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
The operator, 2026-11-11: the licence manager itself moves every consumer off a
licence at 99 % of its session or weekly window to the licence with the most
room, configurable, with its Postgres database replaced by bus state and tools
for all it keeps and does. That night a session meant to switch missed the
readings, so no session does it any more. The new milestone part writes every
line it builds (kept data, the one carry-over of today's rows, the vault move
of ADR 0550 §3, bindings and holdings as events, the switch, its warning and
condition, the tools, adding a licence), and names the three questions no
record settles; the main file is put in the shape a builder reads whole.
Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
The operator, 2026-11-11 about 21:30 CET: a living list of principles; the lead answers each question against it
and does not register every detail. Adds 00-META/principles.md, the lead-answers file G-20 with A-1, and lets the
developer take a lead answer from it.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
Round 1 of the review found §705 patched per finding: the commonest cause
(a machine down by its own network or silence) was missed, the keeper's
silence, the race between a check and its condition, the wait's ends, its
event fields, its finding's telling and its tools were unwritten. §706 now
says them once, following ADR 0677; §705 points to it. §707 gives the
writer's own finding-refused to each bundle's key part, with the statement's
bundle, in place of the G-15 edit, since G-15 is at its size cap. The
glossary's waiting call moves below the kept call's Not: line.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
§705 said the assigner hears rewritten and unreachable from the node-engine's
finding events, but the node-engine only states the network; the watchman
raises those findings and the keeper holds them as conditions, and an
unreachable is raised on the machine that cannot be reached. The assigner now
reads the machine's conditions through mesh-conditions' verb at the judging
and judges again on condition-cleared, never reading the watchman's state.
§677 cited ADR 0259 §3, never in force; it now cites ADR 0286 §6 and ADR 0259
§6 with ADR 0676's clauses, says waiting call for the held call, and checks
what ADR 0676 decides. The glossary gains the waiting call and the holder that
asks for a marked verb served from a module's process. §580 gives the writer's
own finding-refused to every bundle within its own key part.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
Every must of the last review round is written as its reviewer proposed or
as the narrowest line: the gated call keyed by its own call id with one ask
per act across instances, the holder granted from its want, the keeper's
protected restore on a standing grant with a cancel and its partial stream
removed, the node-engine's kept entries in its composition state, the
indexer ordered before the parts that ask its entries, and G's own deletions
moving the gate's copy mark. Develop's D-33 to D-49 are §698 to §704.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The operator's O-8: the holder keeps a module's call, asks, and runs that
same call on the Approve; the caller hears the end on its own subject of
the seat's gated-ended and never calls again, while a person through the
tool runner keeps ADR 0286 §37's path for now (§677, resting on a record
to come). Develop's D-26 to D-31 and the reader release's order are §691
to §697, with §668, §682 and §554 corrected to them.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The holder of a marked verb a process serves now asks, checks and claims
the warrant itself, under its own name and in its own state, and a holder
of before G is never reached (§677). The keeper's snapshot is sent by the
keeper's own verb and a protected stream's never leaves it, restored in
place (§681, the operator's O-7). The recovery module's hand verbs get
their fields, answers and asker (§682); the node-engine keeps its entries
on its node (§683); the grants part composes a want's account before its
first views, so no cycle stands (§684). The republish queue is kept on the
bus, §588 rests on ADR 0674, and D-20 to D-25 are §685 to §690.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The four reviewers' musts on §587 to §676 are written into the lines they
name: the snapshot sent on its call's own session with its digest
recorded, warrants matched to the current ask and its digest, the gate's
copy at every start, the recovery module's hand tools as seat verbs, the
catalog half's pending entries and the node-engine following no branch,
the keeper following a moved finding stream, the builder's republish queue
and its toolchain wait, and more. The operator's answer of about 16:10 CET
ends every named caller list: every verb takes its class's default, and a
module's process that calls a marked verb carries the operator's warrant
for that one call (§677). Develop's D-16 to D-18 are §678 to §680, in a new
part G-18 so that G-17 stays under 60 KB.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
Batch 7 of design 47 G is written as §610 to §676 in G-17 (§614 was
committed ahead): the operator's answers on callers by class, on the five
parts that move only their findings, on the forge and image registry's
other entries, and on the gate's kept data; the refreshed build maps'
questions of mesh-tools, mesh-host and mesh-networking, mesh-sdk,
mesh-delivery, mesh-catalog and mesh-contracts; and develop's D-1 to D-15.
§588 now carries the operator's yes to publishing again on an event, its
record to come. Lines the answers correct are corrected in place, in G and
in design 34 every-event and design 46 7-approval-mark, which ship in G's
release. The main file now lists ADR 0668 and ADR 0672.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
Design 47 G §614 answers develop's D-5 and D-12 ahead of the rest of
batch 7: the reader through meshcatalogclient on the part's one views
reader, the branches from the registrations or the gate's source, the
manifest entries each part declares, an older build's entry asked once by
fingerprint, a none-yet branch read as empty, the first pass after every
first view, and a dropped branch's findings cleared.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
Eight questions met in the join and develop after batch 5 are written as
lines §587 to §594 of a new part G-16, each of internal form within the
records and lines it cites: the ledger's upkeep calls' shapes, publishing
again every unpublished reserved version, a whole read of a module's build
keys, one event of a node's capabilities (manifest-reads-changed, ADR 0618
§4, ADR 0673 §2), the object stores' caps, the gate's merge path from G's
delivery, the gate's dropped Approve-per-merge reads, and the manifest
readers on the catalog graph entry. §568 now cites ADR 0673 in place of
"number to come". The automatic publish on a registry holder's running is
left to the operator: no record decides it.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
Writes round 1's musts into the lines they name. A build edge is met by a running
holder. An act cut off by a move ends through its failure path. Pins survive a
race and a restart, and the gate restates them. Each point's digest is kept on the
bus. The words of a failed build move to the assigner's hold. Also writes the
operator's answers of 14:55 and 15:15 CET: three automatic rebuilds and then an
ask; the image registry copies its template keys at its first start; refused asks
kept are a setting.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
Writes §560 to §584 (G-15) and corrects the lines of G-1, G-12 and G-14 those
answers name. They cover the recovery module's events, findings, cap, hand tools
and digest check; the dump giving way to a restore; the builder's reads and its
retry on an event; mixed build and delivery cycles; refused asks; mesh packages
in lock files; and the forms the developers asked about. They carry the
operator's answers of 2026-11-11 (14:05, 14:15 and 14:30 CET): a put-off dump is
that night's backup; the recovery module moves freely; it is one process holding
its seat; refused asks are listed; a failed build says so; and the forge and the
image registry modules join the foundation.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The bus module's new build cannot be built: its image needs the registry's
mirror, which the registry holder serves only with a state binding the grants
part never heard and waited for that very build to say. The operator chose
(2026-11-11 13:30 CET) to compose key-value and object-store bindings from the
fields the running bus module already answers, delivered with the grants part
alone. Records that §7's 'needs no edge' missed the bus module's own build
through the registry.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
Its verbs answer on acceptance and its events carry the act's form and fingerprint,
it never restores beside the nightly dump either way, a node-engine may call it only
for a want its node holds, and its grants are listed whole as ADR 0672 has them; the
long form of an invokes entry is read by the second reader release first.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The operator chose a module of its own for snapshotting and restoring a module's
kept data on the live bus, so the bus module and the snapshot account keep their
narrow grants; the reviewers' musts are written into the lines they name, and the
new lines go to G-14 so G-12 stays within a part's size.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The operator made an old Approve that pull request's approval step, decided by the
registration's policy, so §510's carried act and §608's merge wait go; round 3 of
the third batch has no fourth round, so its findings are answered here (§543 to §550).
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
Develop met questions the design did not answer on restore points, a bundle's
channel to the tool runner, the want's new fields, the finding stream's form
under ADR 0595 and ADR 0666, and per-branch views; each is now a design line
(G-12, §516 to §541) with its reason and check, so develop builds them and
decides nothing.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
mesh/check being carried to 529cba366b07 on cbafc7556a40 | from ec6be19b1138
The four reviewers' round-2 findings are answered as design lines: the build seats' accept subjects, workers and
grants and the rollout's order as one seam, an ask's start and end outside a pipeline, the builder's heard
toolchains, the tool runner's order from the package a build resolved, the step log's single write, the objects
stores' caps and a carried merge's wait.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The operator answered who may drop a build seat's steps, whose name a step key carries, and that a review in G
refuses no one for authorship. The four reviewers' musts on G-10 are answered as design lines, and develop's next
questions of internal form (the watchman's, builder's, indexer's, forge bridge's, assigner's, view's, bus module's,
keeper's and node-engine's) in the new part file G-11 (§480 to §515); the teller's words wait for the operator.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The operator answered D-12, D-13 and D-19 at the terminal, and ruled on 2026-11-11 that a question touching nothing
the operator sees, no permission and no data kept is answered as a design line by the design writer and read by the
reviewers by architectural domain. The new part file G-10 carries those answers and the internal-form ones (§456 to
§479), the earlier lines point to them, and playbooks 02, 07 and 08 and the glossary say who answers a design
question now. The questions that touch who may call or what the operator sees are left for the operator.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
Four developers of design 47's milestone G ran out of context on 2026-11-11 after one or two subtasks: the
milestone part and the main file they were told to read whole come to about 580 KB.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The generator emits body types and sending stays mesh-sdk's, the reader release reads needs-approval and the
bodies map, an accepted kind's name is separate from its stream, and the bus module's created and recreated do
carry types.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
Develop met verbs and events in mesh-contracts whose callers, classes, states or bodies no line named: the bus
module's acting verbs, the node-engine's thirteen verbs, the keeper's findings-views, the grants part's fill
events, two answers and three field forms.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
mesh/check being carried to d0760629e5fe on 6c1e759e267b | from f1fe609b3e85
The seat definition's Binding named a bus name and subjects while
created and recreated carry mesh-sdk's membership binding, which the
grants part needs; one form for the events and list's answer means the
generated contract must decode what is on the wire, unchanged.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
mesh/check pass 27ec6f8500da on f1fe609b3e85 | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | composition passed in 91s on 3…
G-4 §200 already had the grants part write view-waits as a finding, while
G-8 §387 left it out of the observers that say findings as events. Adding
it, with its state findings and finding stream in its old sections, lets
the bindings first view's two conditions move to findings at G's delivery.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
A binding was written only on the bus module's live created event, so one
event the grants part never heard lost the binding for good (issue 1966):
a registry holder lacked three entries the bus held, and its publishes
were never said published. The operator chose to ask the bus module: at
every start and on a re-ask the grants part takes a first view from the
seat mesh-broker's list, whose entries now carry their binding, and
composes the bindings from it; a binding the bus no longer lists is kept
and said, never removed by a first view.
The same change puts design 25 in playbook 02's shape: section 12.2 to
12.6 move, unchanged and numbered, into the part of milestone bus-state,
so the main file falls from 104 KB to about 71 KB.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
mesh/check being carried to 8e9116469a0a on f1fe609b3e85 | from fbd7981b7be2
The served version comes from what the bundle runs and a reading from the
runner that made it, so no placement or clock lifts a deny; the runner's
state takes the old form the bus module can create; kept calls stay open on
their key; and the closed directory's mode is read by node-files.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
Each of the 25 recommendations becomes a design line with its question id,
so the builders find every field, test and source named; the live readings
of the credentials go into the gate's stated bound.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The review found that reading the catalog graph instead of manifests needed the entry to carry the manifest and
stay while a build names it, the grants to follow the wanted build, the pre-G node-engines their manifests by
digest, and the restore, caller, stream, finding and test-budget lines a name for every field they left open.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The operator's rule is that the indexer alone uses manifests to build the catalog graph, so every other part's
read of a manifest becomes a read of the catalog half. Lead-47's rulings settle the finding layout as a seat
contract with generated writers, process-builds as a node-engine seat verb, a grants-for read on mesh-grants for
widens, and aside on node-backup.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The prepare found about a hundred places where G's lines left the builder a choice. Each answer is now a line of
G-9 with its question and its check: one default of callers per verb class, so no verb is closed for lack of a
list; the seat-definition forms; kept data and restore points; versions; steps and test counting; the readers and
the gate's remaining parts. Earlier lines the answers change are amended in place.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
mesh/check being carried to 95ae1dd6ed90 on 7dfb6f0b7b15 | from c74546a16f78
The operator answered that only the indexer uses the manifests, to build
the module catalog; so the secrets review and the tool runner read the
catalog revision, and the bus read and its nats tool extension go.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
mesh/check pass de62fe58523a on c74546a16f78 | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | composition passed in 69s on 4…
The client's node prefix stays on its own keys, so the router's record is
still read where the router writes it; the remaining notes say where the
runner's version is read and what each limit costs.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
A stuck state recovers as a kept call, a node with no or stale readings is
denied, the caller-named subjects are withheld too, and the per-machine key
form and the client's prefix are named, so no path serves a marked tool
unasked; the forge's loosening is marked by the operator's answer.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
Call again stands by the operator's choice; the credential file's reach is
a known limit, as G's shared account is; and the forge's two loosening acts
move to a marked tool of their own, so tightening stays unasked.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The bus withholds a marked subject from a runner that does not honour the
mark again, as ADR 0286 has it; marks follow G's catalog half; a recording,
a stuck gate, an absent router and a start before the marks are read each
have a stated answer, so nothing runs unasked and nothing fails silently.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The operator answered "Build the gate in G" and wants no new records: the
marked-wait lines now hold by the operator's answers, each departure said in
its Why, and design 46's milestone 7 becomes a part a builder reads whole,
written to the mesh as built (marks read from the bus, the capability hold,
the client's claim in bus state, the hand-act seat), delivered with G and
every-event.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The operator chose every module stream, mail too (ADR 0671), so the stream
lines hold and the restricted-stream deny goes. The operator also asked that
a wait respect the approval mark; that extends ADR 0286 to events and has the
tool runner's gate hold it, so those lines are written pending the record.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
No tool answered which subjects a stream holds, so the secret review could not find an
event the list missed; a module's tools read everything it holds, so the nats module's
tool gains that read, built first as a small fix.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The reviews found waits that time out for ever on a misspelt name, refusals that would
loop a watcher, an acceptance no answer could prove, readers still describing the list,
and no way back said. Each is now a design line; the stream-events lines are written for
the recommended option and marked pending the operator's answer.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
Watchers reread on a timer because mesh_wait refuses every event outside a list of five,
and the delivery status view's events, which playbooks have watchers wait on, are not on
it. ADR 0670 grants the tool runner every event subject and drops the list; this writes
that as milestone every-event, one delivery group of mesh-sdk, mesh-delivery and
mesh-tools, and puts design 34 in the main-file-and-parts shape.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The finding events lacked a stream, a consumer per source, a rule against a restart clearing what still stands, a
take-over rule and presence events; the 2026-11-11 answers move to a part file of their own so each stays under its
size. The test budget is counted per module, the upgrade window between the builder and the registry holders gets
its edge, and the readers of the new manifest words come first.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The keeper finds its sources in the catalog and names none in its manifest, so one generic consumes form with its
validator rule and per-module grant carries the finding events; the operator's answer that a verb open today stays
open covers the connectivity verbs that name no callers; and findings of a module no longer placed on a node would
otherwise stand forever.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The condition keeper read other modules' findings states, which only their owner may reach; a node-engine
restarted with the full seat list never cleared its own finding, because only its process remembered writing it.
Observers now say each finding as an event and state all they own at each start and on the keeper's ask, so the
keeper's view is rebuilt from events alone. The `invokers` form is the operator's choice, and the tool runner's
shared account stays as it is in G, named as a known limit.
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
The operator, 2026-11-11: the scan was a flaky check, and the rule is a guideline, not a decision. The names
G's own work removes are removed by its subtasks; the exemption line and the scan's checks go with it.
Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
The four reviewers found two triggers for one rebuild, digests read from the builder's own keys, a mesh-wide wait
with no owner, bound or tool, new states with no retention or cap, a first fill the builder could race, and a
registry check whose source goes; each is now a design line with its reason, and test 60 follows section 271.
Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
The operator answered on 2026-11-10 that only an imported package and the build toolchain make a dependent stale,
every other edge only ordering, that a dependent waits for its dependency's delivery to every present machine,
that a want names the released version and each part's digest, and that one tool answers a part's edges both
ways. G's answers move into a file of their own so each file of the part stays under 60 KB.
Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
A module's version can change without changing the part an edge points to, a delivery happens per node, a build
of another branch has no version, and acting and serving are facts, not versions: the lead's review of §374 to
§376 found each would mark edges behind wrongly or redo work. A first fill keeps the first query from finding
the whole mesh behind.
Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
The operator chose on 2026-11-10 that the catalog of versions keeps a lockfile per released version (issue
1961): each edge's dependency version, so one query answers what is outdated after a restart or a missed event,
while each edge kind is still started by its own event, a release or a delivery.
Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
The operator's answer of 2026-11-10 allows no custom version, and a tagged version is one: a group's run on
request delivers nothing, so it builds its members against each package member's build by digest and publishes
no version, and `tag-wanted` and `tag-asks` go with G's delivery.
Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
Design 51 still numbered a package at its publication and said `version.numbered`, which the operator's choice
of 2026-11-10 replaces: the catalog's released versions are the one list, and a packed file carries its version.
The catalog's first versions are filled from what is published, so numbering continues above today's.
Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
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
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.
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.
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.
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.
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.
mesh/check failed: ace: novox/mesh-catalog#505 does not merge into the trunk: files in conflict: .gitignore | 495d740d5ffc on d698942b1d56 | unit 1245…
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…
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.
Design 47 names ADR 0548 (a check runs to its end, a trunk move carries a verdict by its package digests, the hold and the merge turn), ADR 0551 (the hold and turns only while the check gates merges), ADR 0549 (placement files read by the indexer) and ADR 0550 (the vault signs and adopts the loaded hashes), and ADR 0547's answers on placement and signing. Design 24 gains every secret in the vault; design 39 moves grants and tokens into it. The glossary gains carried verdict, merge turn and placement file.
mesh/check pass de4c69d47634 on 132aae843383 | a compiled program is not refused: mesh-build-node reported no programs | unit 39 run, 0 kept, 1 skippe…
Tests 18 and 19 do not cover tests 3, 7, 9, 10 and 11 as restated, so each now names the test or live read that proves it, or says it is not yet proved.
Release 6 is delivered, so the as-is designs still describing the controller's plans were wrong,
and design 47's tests 1 to 12 named batches, plans and the merge window that no longer exist.
Release 6 deletes delivery plans, batches, the merge window and tiers, so
design 47's sections that described them as current are rewritten to the
assigner's seven rules, the controller's signed compositions per node, the
node agent, credentials on a done build, the switch as release 5's last plan,
the hand path by mesh-compose and a want, and the view's delivered, moving,
settled and stuck events. The glossary gains composition and restates want,
declaration, send and apply; the playbooks follow a delivery by the view and
the have keys and call no plans, plan, push or what-if.
Design 63 turns the mail page into the operator's list with Owly beside it (ADR 0515
to 0519), in six milestones with their issues; its reference mockup is kept beside it,
its data invented. Playbook 10 says how a page is designed before it is built: mockups
with fixed data, the operator picks, the pick is the reference. The as-is of the mail
modules now describes mail reading as delivered, the glossary gains design 63's words,
design 59's milestone 4 is marked replaced, and AGENTS.md allows a design's mockup.
Issues 1855 and 1856.
Lessons from closing only-office's old directories: a directory keeps its id until emptied on the
operator's word, then leaves the manifest in a second fix; and a fifth try is refused, not queued.
mesh/merge-gate head 333e73830c31 merged into trunk 93963aeb5189 — pass: group feat/upgrade-safety composed: every machine composes with the change as it d…
mesh/merge-gate head 9a74de0bd64f merged into trunk 77d4a8a39e1f — pass: group feat/quiet-deliveries composed: every machine composes with the change as it…
The operator, 2026-10-22: a milestone is a milestone; which module reaches the machines first is what the delivery plan is for. The prepare step still lists every part a change reaches, as issues of the same milestone; an order the plan cannot keep is an issue of the build and delivery system.
The operator, 2026-10-21: issues opened along the way were only listed and left. Small ones are fixed in between as small fixes, the rest right after the delivery, outside the running milestone's branch, so its fixed scope holds.
mesh-delivery reads a pull request's issues from the words 'issue <n>' in its description; okioki #9 listed its own bare and named two follow-ups that way, and the Approve's ask named the follow-ups.
The review of hq#453 after its merge found the design calling ADR 0481 proposed, and the operator's rule (the page uses the bus and makes no OkiOki call, 2026-10-21) only implied. A document crosses the bus in parts, as scanner.document does.
The operator asked for a page showing the business's income, expenses and to-do as the
bookkeeping service holds them now, on their own hardware: okioki moves whole to the home
server and okioki-web runs beside it, behind Keycloak, never changing what the accountant did.
The review found features stated as in force that rest on records still proposed
(ADR 0468, ADR 0474 and the scanning record to be reserved), and rules without
the test that checks them.
The operator asked on 2026-10-21 to configure the printer and scanner easily, or through
the mesh's tools; the design names the configure verb, its deny list and the proposed
decision it rests on (ADR 0474, number to be reserved).
Design 47's catch-up of merges nobody heard is decided by ADR 0457 and bounded by ADR 0463, so other sessions read them from its frontmatter. Playbook 07 gains four lessons from 2026-10-20: a Retry is never asked beside an Approve (issue 1408), an ask is named only after it is read on the router, a check's wait is read from its delivery and not the build queue, and a catalogue change removing a module is tried against the controller (issue 1406).
Playbook 04 step 3: the one grants list that gives reading and sending at once, and mesh-mail-notifier's pop-up for every new mail, read from mesh-catalog main a67f0196 and the live mesh.
Playbook 04 step 6. Also names ADR 0378 §5 beside ADR 0440 §4 for the page's use of mail-reading, its writes with correct and undo, and issue 1419 in §8's last sentence, as the graduation's review noted.
Research 066's confirmed direction becomes ADR 0458 to 0462. Design 59 gains the sections and milestones 2 to 4 they decide, the glossary gains Mail as the thirteenth domain with four homonym rows, and design 49 lists Config and Mail so its count matches the glossary.
R3d's prepare step found four things the gate reads that must ship before it, and two steps that needed the operator's terminal; R4 gains the controller's deletions (1318).
The check took 3 to 4.5 minutes on every change and paid the whole suite again on every re-ask; the operator's target leaves it about a minute. ADRs 0444 to 0447 decide how; the glossary gains composition check and kept verdict, and merge gate is struck once release 4 is delivered (issue 1303).
Research 063 graduated into ADR 0429 and this design (playbook 02 step 3).
The design names the parts and the releases; its other sections hold until
each release is delivered and are rewritten as each is prepared (issue 1130).
The words the plans use are marked as going at release 6, not struck: they
stay true until that release is delivered.
The operator decided on 2026-10-18 that a domain word is used only when clearly defined. epic had three uses and no code; design 47 now names two ways, hotfix and feature.
mesh/merge-gate head 64e357da7d7e merged into trunk a6db6a70cffa beside mesh-catalog#352@07717974 +1 more — pass: the change touches no module of the mesh'…
Feature owned-paths (issue 1024) planned no controller release for a new key on directory resources, though the controller judges every machine with the node-engine's vendored validator; and the controller's release, on the feature's branch name, joined the catalogue's delivery group and could not merge before it.
mesh/merge-gate head 499407c66936 merged into trunk 2cf1c64e24f5 beside mesh-catalog#349@7104df6f — pass: the change touches no module of the mesh's graph
hq main moved after this change's check; it touches neither design 29 nor anything this change edits. The branch's tree is the reviewed design 29 change merged with main.
The operator asked why review takes so long: a fresh reviewer per round or per mark reads
everything again, and a reviewer waiting on the forge's checks spends its run waiting.
Design 29 is ADR 0422's home: it now says what `unknown` and `knows` mean on a directory under a home, that the found class no longer holds in ~/.ssh (ADR 0415, 0417), and lists ADR 0412, 0415, 0416, 0417 and 0422 among its decisions.
The tracker and the delivery records hold whether a milestone is delivered, when and by what;
a copy in the design's table is a central status kept by hand (AGENTS.md). Design 47 loses its
copied cells.
node-tools still has a manifest (invokes *, waits, the mcp-endpoint provision) —
describe it in prose instead of saying it has none. The TypeScript sources
remain on main; only the built artifact is Go. The mesh-controller seat
answers 63 verbs as its own runtime, not 60-93 per node (that is node-tools'
own node-scoped seat verbs). Prefer reading mesh_overview live over a count
that drifts. An as-is document amends nothing — reworded accordingly.
mesh-console is gone: the tool runner (node-tools) is a core component on
every node, host-side and never a container (ADR 0175), announcing seven
tools by address (ADR 0195, 0367), not the five-tool container the old
as-is doc described. The to-be document's unsettled items get owners:
the mesh's own verbs already shipped (ADR 0154); identity and
per-assignment grants are design 58 milestone 6 (issue 883).
Design 57 was merged as a release with three tasks left and still said
designed, so another session took it for unbuilt. Say it in-progress, with
what is left and when it is built.
mesh/merge-gate head 24701df23e8a merged into trunk dd5a06529556 beside mesh-catalog#340@ae9cda85 — pass: the change touches no module of the mesh's graph
The operator confirmed six milestones on 2026-10-17; issues 973-981 and 971
carry their repository parts, linked depends-on in order. The as-is described
the predecessor's pipeline; it now says what runs today, which design 47
replaces.
ADR 0401-0408 graduate research 055: no release branch, two more ordering
rules, the composed check as each member's gate, a backup before the send,
installed toolchains, events and work queues on the bus, the merge window
as keys, and one chain kept on the bus alone. Design 47 is rewritten from
them (one design per thing); the glossary takes hotfix, feature, toolchain,
milestone and epic and retires release branch; design 18 loses the
toolchain image; playbooks 07 and 08 drop the release-branch wait.
mesh/merge-gate head 7b5f3582be90 merged into trunk 6dcfa2226e63 beside mesh-controller#357@114c99e0 +1 more — pass: the change touches no module of the me…
mesh/merge-gate head e7417cf1248c merged into trunk c22b58143b74 beside mesh-host#116@bff1ac14 — pass: the change touches no module of the mesh's graph
From the delivery-time audit of 2026-10-16: seven review rounds on issue 704, a feature branch's first
check failing on 29 problems, mesh-catalog #300 waiting 12 h unmarked, the mail modules failing live,
98 issues held in fixing.
Threads on the bus, a headless thread handler in a sandbox per session, a workspace toolkit with no
general command runner, one identity seat, effects on every tool, signed bus logins and the switch
to them; names the build's acceptance tests for the milestones.
The research playbook named acceptance tests the milestones carry, which
playbooks 02 and 04 did not know; its pre-check also disagreed with the
knowledge base's deferral rule.
Proposing records one after another serialises their reviews and the
operator's asks; retyping the effort's findings into each record makes them
long and gives the review more to send back.
Research 053's identity part took six versions and about two hours: options
that broke the mesh's own rules were offered and argued back, a version was
proposed after every answer, and reviews returned findings a pre-check
would have caught. A lab run was planned where an in-process test answered.
The operator found 04 odd on 2026-10-15: it went from a settled design straight to building,
with no work breakdown, and contradicted playbook 07 on pull requests. 01 now starts from the
operator's idea with setup questions, findings and a direction the operator confirms; 02
graduates that direction into one record per reversible choice and hands the design on; 04
breaks it into milestones usable on their own, one issue per repository part, each milestone
one feature step of 07. 01 notes the knowledge base's insight-only rule for an active effort
until issue 844 is delivered.
A feature waited a day for its last issue, each small issue paid for its context again, and
waits nobody saw cost the most time. The operator set the flow on 2026-10-15: prepared context
per repository, one to two hours of local development on unit tests, one review of at most three
rounds back to the same agents, one push for the integration checks, then the delivery plan;
steps for a larger feature; a separate playbook for small fixes; models per step; a wait list
with bounds; a prepared clear at each phase end.
A temporary-directory quota failure, a delivery group's manifest-check
ordering, and an agent that stops or finishes without committing each cost
time during that feature because the playbook did not yet say what to do.
Writing them down so the next feature avoids the same detours.
On 2026-10-15 issues spanning one repository finished in two to four minutes, while those spanning two or
three ran for thirty to sixty, mostly merging the feature head and checking again as other agents landed.
The operator asked for agents that finish in five to ten minutes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
They lived in a file on one machine that only one session's agents read. They are how every feature's
agents work, so they belong with the method; a feature keeps only its local facts (paths, branch, locks).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The operator, 2026-10-15: the smaller model is as good as free against the weekly allowance, so the
limit that matters is how many agents the lead can settle and follow (three to five); subagents on the
larger model stay at two at most and as rare as possible.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A reviewer that does not know its round keeps finding the next smaller thing: one decision record went
through nine rounds on 2026-10-15, each spending the operator's shared weekly allowance. The operator
asked for three to five rounds, the round told to the reviewer, and the allowance in every report.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Five agents at once, each stopping on an undecided design question and restarting, spent a
week's allowance in a night. Also write down the lessons of feature 57: never land on a red
check, a new manifest word lands with the controller that reads it, and review the tree that
is pushed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Huge pages at always flooded the control-node's spinning disks with journal
write-back and cost the controller its lease; the setting needs an owner,
and the kernel module is the one to-be 42 already names for the kernel.
Redoes the design-48 edit of the unmerged pull request 284, which cited the
record under its file number 0280; the record now lives in the knowledge base
as ADR 0368.
A push starts the forge's checks, which build the modules and run every
test for up to a quarter of an hour, so a review finding fixed after the
push costs another full run (the operator, 2026-10-14).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A finished issue's agent is gone, so left in fixing it goes stale; the lead
takes it over until the feature is delivered. One repository is one
delivery, not a group; readiness comes from depends-on links (review
comment 12466).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Feature 57 was first worked as a pull request per issue into protected
branches and lost most of a day waiting on merge checks. Record the issue
as the unit, a review and checks once at the end, landing by fast-forward
under a lock, and the lessons met on the way.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A machine that says nothing is often asleep; its builds wait for the
backlog walk (ADR 0360 clause 10), so no new pull request is needed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The pull requests' checks still run before the walk, and by then the
release's branches have reached main. Name the silent machine too, and
list ADR 0360, which the passages rest on (review comment 12348).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ADR 0360 sends a merge's builds to every machine at once, so release 57
has no first node to hold it and P6 can no longer wait at a gate. ADR 0362
moves the wait for the provisioner to the walk's end.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The word setting waits for R2, P3 waits for F3, the group's order is declared with after: lines, and a stop's fix is a new merge.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Role names instead of node names, the failure rule as ADR 0276 and 0299 have it, readiness and adoption of existing credentials said exactly, and the counts and refusals corrected.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The operator chose one delivery over one per package; the packages meet on one branch per repository and reach main as one delivery group.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
So config and provisioning are built in small, provable steps with at most five worked at once.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The operator would not read the Telegram asks: the ADR 0343 ask was thirty plain lines, a settings
proposal a wall of masked values. The design takes ADR 0345: the asker's summary and points are the body,
everything else a note the channel shows apart, and an ask's values whole on a proving channel.
The design said the tools answer no address and declared only the accounts. It
now names ADR 0329 and ADR 0326, the five new settings and prefs as one entry per
preference (§8), what the tools show (§6), and how each part is checked.
mesh/delivery-group group feat/335-a-busy-container-is-replaced-when-idle rejected: its order contradicts itself: novox/mesh-catalog@190608193764, novox/mesh-c…
mesh/merge-gate head a0eccc713a81 merged into trunk c2a7016b620e — fail: head a0eccc713a81 does not merge cleanly into trunk c2a7016b620e: in conflict 03-D…
mesh/repo-check head a0eccc713a81 merged into trunk c2a7016b620e — fail: head a0eccc713a81 does not merge cleanly into trunk c2a7016b620e: in conflict 03-D…
mesh/merge-gate head ac5bdeb17860 merged into trunk a0e51c061b5e — fail: head ac5bdeb17860 does not merge cleanly into trunk a0e51c061b5e: in conflict 03-D…
mesh/repo-check head ac5bdeb17860 merged into trunk a0e51c061b5e — fail: head ac5bdeb17860 does not merge cleanly into trunk a0e51c061b5e: in conflict 03-D…
The controller sends a machine the take act on the operator's warrant, on mesh.node.<node>.ask.access-act;
the machine verifies the mesh's signature and records the act. Rule 1 asks every kind of state to name its
one writer.
The review asked that the trunk-less verdicts, mesh-delivery's trunk head, the
refuse-ask race and the lost check's recheck be said, and found the revision
spliced mid-paragraph.
A merge check now judges the head merged into a named trunk commit and its
verdict goes out of date when the trunk moves; the designs and the glossary say
so, with the tests that hold it.
ADR 0313 makes the span from the move to fixing to delivered the operator's
target; the delivery budget stays a measure inside it, and its leaf figure is
three minutes since ADR 0304.
The knowledge base's whole-set cited rule (to-be 55, ADR 0313's own review)
refuses to accept a record nothing cites. Design 47 already builds on
ADR 0282's delivery budget, which ADR 0313 extends with the operator's
wider fix-time target, so it is the record's home.
PR #88 (merged 2026-10-06) already fixed the holder to read open state first,
coalesce bursts and hold a start grace minute, after a new consumer replayed a
morning's 96 settled events as fresh alerts. §5 still only said a rate cap; this
names the rules actually built, under ADR 0318.
The operator decided on 2026-10-12, on issue 504, that a rule of the
record set that fails is a fault of the records, not the module failing:
health says only whether the module works (issue 508's principle), so a
finding must not hold a walk at the module's first-node gate.
The knowledge base's cited rule failed for ADR 0303, 0306-0312, 0314 and 0315: accepted,
and nothing cited them. Each design that owes the decision now names it in its decisions
and says it in prose, so the records can name these designs as their homes.
to-be 45 section 2's field table put the count of observations, the last observed
time and the evidence in the conditions bucket, which made every look a write and
broke ADR 0289's rule that a bucket is written only on a change.
A token a media server got from its vendor could only be typed in per consumer; the vault now takes it
from the provider, sealed to one call, and keeps it as the provision's one credential.
ADR 0302 made Media a domain: content, kind, media release, library,
media file, media-importer, download client, engine and grab now have
one meaning each. Release already meant two things, so the Media sense
is qualified in the homonyms.
mesh/repo-check pass: THE CHANGE ALTERS ITS OWN CHECK (merge-check.sh): main's version judged it; the change's judges the pull requests after it merges; it…
mesh/repo-check pass: THE CHANGE ALTERS ITS OWN CHECK (merge-check.sh): main's version judged it; the change's judges the pull requests after it merges; it…
ADR 0290 rule 9: once the import is checked record by record, hq keeps no copy.
The records and efforts are removed; every link or path to them reads "ADR NNNN" or
"research NNN"; a design's decisions: lists "ADR NNNN". 02-DECISIONS keeps a pointer
README with the reading order's six topics, which the knowledge base reads through the
records module; 01-RESEARCH keeps a pointer README. The checks drop the rules that
judged records (the knowledge base holds each at propose; checks/README.md says where)
and refuse a record written here again. Playbooks 01 and 02 and the skills write and
read records with the knowledge base's verbs.
The operator could not tell from a notification whether its cause was
known, tracked and being fixed. An issue tracks a condition by its key;
the tracker answers which issues track which conditions, and the router
says it in every message about the condition. Amends to-be 53 and 45,
playbook 03 and the glossary, and points ADR 0253 at the new line.
Nodes, assignments, walks, builds and settings could be seen only by polling verbs, and a setting
changed with no event. Each becomes a record mirror: a bucket written from the store after the commit
and only when the value differs, one event per write, compared with the store on every self-check run
(D17, mirror-drifted, healer H6). The write-only-on-a-change rule from issue 326 now holds for every
bucket; the conditions bucket breaks it and issue 420 tracks that. The effort stays active for G1, G3
and the views.
Graduates research 039. The tool runner (and the controller for its own verbs) asks the operator
through the existing operator-channel asks and runs the exact call once on the warrant, reusing the
act digest and warrant check of ADR 0259 and the shown-in-shape form of ADRs 0274 and 0277, so
risky agent calls stop resting on the agent's restraint. Amends to-be 46 and hands it off.
The review found questions no record decides: 012's minimum-viable-node
half and 027's packaging, secrets, sizing and leftovers questions, so both
stay active. Where the record lives (006) is issue 414, and 037's two
other leftovers are issues 415 and 416; to-be 06 now points at issue 414.
Ten graduated and two abandoned efforts still said active, so the record
read as open questions that later ADRs and designs had answered. Each now
names in became: what decided or overtook it. To-be 45's undecided item
moves from research 017 to issue 409, and research 037's shell follow-up
is issue 410.
The live module check refused mesh-catalog#190's smb-users setting (ADR 0262);
ADR 0283 decision 7 gets a dated insight, to-be 52 and the 0263 note follow.
Two agents could start on one issue without seeing each other, and an issue
could be resolved without anyone having said they started its fix. Adds the
status fixing, the issue's worker (by, who@node) with take-over and a stale
bound, and resolved only from fixing; settles what to-be 53 left out as
claims, under the new glossary word worker. Amends to-be 53, playbook 03 and
the hq-diagnose and hq-status skills, with pointer notes on ADR 0275 and 0281.
A module whose only unhealthy part waited for the operator's secret failed
its gate, held every later walk and told the operator there was nothing to
do. The record adds a waits answer and a waiting state, checked by the
controller, read by the gate as waits for a person, and said as a
needs-operator condition naming the act; and secret families so each SMB
source's password is one hidden line at the desk prompt.
The operator accepted them on 2026-10-10. The runtime seat and the default
half of declared settings are live; the rest is tracked by issue 398. To-be 42
cited them only as waiting, so it now names them.
From the independent review: a core delivery could wait on a leaf judgement past
its ten minutes, the window figure's split was not stated beside it, and the
one-repository rule was credited to the wrong issue.
The operator asked that a bug fix land on every node in under five minutes. 51
walks measured from the controller's own records put a leaf walk at a median of
6.0 minutes (7 of 20 within five) and say where the time goes: waiting behind
another walk, the first-node judgement, the merge window. The record weighs each
lever by what it would have saved, keeps three readings for core modules (ten
minutes, the measured worst being 8.8), and proposes the measure and condition
that check it. To-be 47 gains the section, the owners and five slices; the
glossary gains delivery time, delivery budget, core and leaf module.
The record is read-only and hand-written; numbers collide and private knowledge
has no home. Framed as questions, weighing git as the store against a store
with hq as its public export.
Every controller change walks the core's tier and holds up every other walk
(issue 382), while most of the week's change sat in one package. Framed as
questions: which domain changes most and needs the core least.
The operator approved measuring, from the delivery's own events, whether each fix
an issue names reached the machines; delivered is not resolved, and a merged fix
that does not arrive must be said rather than found.
The import of slice 3 (ADR 0275) was checked against every folder: no report changed since the
commit it read, and the tracker holds each report's status, owner, fix, design amendment, replay
and closing day. The keys are removed from all 361 reports, cycle.py refuses them in any report,
and the playbooks, skills and READMEs that still pointed at them name the tracker instead.
The operator asked for severity and what an issue needs to be estimated by the
judgement that already reads the backlog, and for dependencies between issues,
an issue being workable only once what it waits for is on the machines.
Review found the two questions together exceed the consumer's ack wait, which the
tool runner did not extend; the record says so and names the fix it waits on.
The operator asked for duplicates to be consolidated, and better, when an issue is
opened rather than on a schedule. A judgement needs a model, and the mesh had no
channel for one; the agent module answers one question with no tools, under the
node's licence, and the tracker acts only on a clear duplicate, closing the newer
issue and keeping its report on the older one.
The operator does not want to run manual commands on the control node. Issue 339 made every trusted
setting the terminal's alone, and a module's own secret the terminal's or the give verb's: each a line
an agent could only hand the operator to type. ADR 0274's pattern is extended: an agent proposes, the
operator approves on a channel that proves who answered, the controller sets the layer on the warrant
bound to the exact values shown. A secret is asked for by a verb and typed at the desk, bounded, the
prompt naming who asked. The designs 44, 52, 46 and 13, issue 339, ADR 0259 and 0266 and the glossary
are amended with dated notes.
Issue numbers collided while each author read main and the open pull
requests; since 2026-10-10 the tracker (ADR 0275) hands them out. The
playbook and the hq-new-issue skill now open every issue there, keep a
folder only for a design or governance issue, and say where its status
lives until slice 3. Research 042's finding that the SDK had no
compare-and-set is corrected, and to-be 53 names the module's code.
The operator named the module on 2026-10-10: the mesh's own parts carry the
mesh- prefix, and the seat is the role. A dated insight in ADR 0275 says so,
and that compare-and-set state was already in the runtime (ADR 0259): slice 1
added the SDK's Increment. To-be 53 and the glossary say the same, and the
design is handed to mesh-catalog and mesh-sdk (in progress).
Two catalogue merges 18 s apart opened two walks; the second superseded the
first and nothing gave it its word for 58 minutes (issue 362). The operator
decided that merges are collected in a rolling merge window (90 s, at most
10 min) and each batch is walked once, one commit per repository (the later
one of a repository, which contains the earlier), one walk at a time; the
walk-to-delivery bookkeeping is repaired too and every wait has a condition.
Amends to-be 47 and 10, adds merge window and batch to the glossary, and
corrects the issue's account of the S16 condition.
Numbers taken by reading a repository many branches write at once collide;
one counter in a module of the mesh's own, advanced by compare-and-set,
ends that at the source. The operator delegated the five open questions
on 2026-10-10; each is decided as the research recommended. The glossary
gains the issue tracker, retires "ticketing system" and lists ticket as a
homonym, since ADR 0258 already uses it for an answer's one-time token.
The operator asked for mesh tools to add shared instructions and context. Issue 340 made that text the
terminal's until a surface of the operator's own exists; the operator channel is that surface. Proposed,
for the operator to accept.
Opens the effort the operator asked for on 2026-10-10: an issues module on the bus that hands out
numbers atomically, so agents stop colliding on them, and takes in the 357 issue folders. Findings
cover the first slice, where the truth lives, the import, conditions, views, and hits as a model.
The setuid search did not finish within its bound on the control-node, so no
approval proven there is honoured; a confined start may answer the question
ADR 0259 asks directly, at a cost that does not grow with the disks.
The desk's actions sit on dunst's middle click, which a touchpad cannot give, and the context menu
names a command dunst's PATH does not hold. Located in the dunst module; dunst's own code settles
what a tap with do_action does.
The confirmation review of issue 356 found that the by-path chmod and chown of an ordinary mesh directory outside a home follows any link in its path. Issue 356 closed it for a handed-over directory, on every apply; the general gap is older and wider, and is recorded here rather than fixed in passing.
The review of 2026-10-09 proved a responder can reach the hand-over's subject through a reply, and that the apply followed a link the hand-over had refused. The record no longer says only the controller may publish there: it says the ask is signed with the mesh's key and verified by the engine, and that a handed-over directory is changed through a descriptor that followed no link. To-be 45's writers table gains the row for a hand-over asked of a machine.
cycle.py skipped a rejected option only when "Options rejected" was its nearest heading; a record that
lists its options under ### subheadings of "## Considered Options" had them held as deferrals.
A review found the check too lenient: an issue cited as context beside a deferral passed it, and one
insight excused every deferral in a record. The tracking issue is now named as tracking it, an insight
covers only its section or what it quotes, and the phrases include "not decided here", "postponed" and
"future work". ADR 0273's four undecided items get issue 357.
ADR 0244 left the code renames of the node-engine and the tool runner for later with no issue, owner or
date, and two days on the operator believed them live. Open the issue with the inventory, the risk and a
staged plan; add the rule to playbooks 02 and 04, as a dated insight on ADR 0244, and as a cycle.py check
that found the same gap in ADR 0270 (issue 355).
Review of hq #254: a hand edit is written back on the look that finds it, and a key that
decides what runs is never taken over; the guard and the condition cover settings.local.json,
plugins and plugin installs; after a node's first adoption an unrendered file is moved to the
copies; autoMode is a permission rule; the named leftovers, the owned and excluded entries,
pending requests with the exact nox line, and the agent's existing corrections as first lessons.
The engine on every node's PATH was the one a person copied at installation, a build behind every delivery; and the way out of issue 339 was a terminal act at the machine, which ADR 0272 and the operator's rule of the same day make impossible to type. The record, located in the engine, the controller and the catalogue's check, with the fixes' pull requests; ADR 0272 gains the rule as a dated insight: the operator types one command, nox, and every text addressed to the operator names a nox line. words.py now refuses a daemon's line, with --list lines for the catalogue's copy; the lifecycle and the operator's-machine designs and issue 343's quotations are reworded.
Research 040 measured the homes on four nodes: a skill retired a week ago on all four, the
operator's rules on one, nothing raised. The module now owns every configuration file under
the agent's home, excludes the program's working state by name, and raises agent-home-drift
on a hand edit; a fourth scope carries the operator's personal rules to every node; an agent
proposes a lesson when corrected and the operator accepts it at the terminal or on a warrant.
To-be 36 §10 and to-be 40 WP7–WP10 say what is built; ADR 0216 and 0243 gain notes.
The 2026-10-09 16:19-16:36 sequence on the control node: a release's gate
held the machine's report against a newer send another plan made, failed
three healthy builds and put them back to a controller that could not
read the store; that controller then passed the newer plan's gate from
its own health. Measured and guessed apart; the fix in review.
The catalogue's #125 stayed held 28 hours after ADR 0270 went live. The record covers a held merge when a
later delivered walk sent its module everywhere, as the machine steps say; a build held back for a person
and sent on the operator's word travels by a backlog walk, which gives one step per machine and whose end
mesh-delivery read for nothing. Report, diagnosis located in mesh-delivery, the fix in mesh-catalog #163,
and a progressive insight on ADR 0270's one-machine consequence, which this widens.
Plans of a branch superseded each other by when they were made; the
catch-up's late plan of an older merge took over a newer one, once a
security fix to the forge's module. Recorded with the fix in review.
Records the 2026-10-09 outage on the control node: what was measured
(the unit ran, the private address refused; a restarted node-engine's
undecided statement cleared the network condition and its reopening
dated the fault after the send), what the reproduction showed of
bind-dynamic, what is still guessed, and the fixes in review.
The confirmation review: hq requires only mesh/repo-check, so a watcher
that looked for mesh/merge-gate alone would never have said this
repository's own unchecked pull request. And the delivery domain's own
condition, a delivery held past its bound, says it rather than a provider
standing.
An ordinary line meets the generic verb's reading forms and never a
terminal-only command (node account and node agent-account by ADR 0266,
token, operator, a secret's export); a terminal line drops ADR 0266's
served mark, so it reads as the terminal. How it is checked says the
withholding tests search base64 too and fail when what they guard goes,
and the control-node refusal is tested through the acts.
- §3: the node-engine vouches and decides nothing; deadline first, other
namespaces refused, each account bounded and answered busy; the subject
is the machine's own in the writers table.
- §4: phase 1 refuses the agent account (phase 2 answers it); an ordinary
settings line takes the settings verb's path; the controller's module is
assigned at the terminal only, so the terminal does not follow assign;
'no wider than today' holds only while its two measured facts hold.
- §5: every line is a call, followed to its answer; 'nothing ran' only of
a line nobody took, otherwise 'not known' with the call; the answer is
its asker's alone.
- §7: after the four merge, the operator assigns mesh-cli to every node.
- How it is checked: each claim with its test or measurement, the
MESH_VERB refusal in mesh-cli named a courtesy, and the sudo and
agent-account facts read on the control-node today.
The forge's announcer reads only repositories whose update time moved; a
pull request opened after its push does not move it. Located in the forge
module, with the fix (mesh-catalog) and how it is checked.
Found in the review of the picom settings: a backend of xrender"; write-pid-path = "… adds an option of
the caller's. The two files marked trusted false on main are judged (user-dirs.dirs open, dunstrc not),
and typed settings validated at the verb and quoted at render are proposed; until then nothing new goes
trusted false.
The record said a merge needs a person; the forge requires no approval and
the merge tool merges once the checks pass, so nothing enforces the
operator's yes. What still remains now says so, and that the restart fix
counts from when the controller first saw the search pending. Item 10 and
routes A and B describe the follow-ups of the review of 2026-10-09.
The operator reports picom leaving a chat window stale after a workspace switch before, never recorded.
The diagnosis now names the graphics stack, puts picom first among the candidates, and makes the first
step at the next empty reminder turning compositing off, which loses nothing; a Betterbird restart comes
after, refused while a message is being written unless the operator says yes.
Records the symptom, what four reminders raised from a throw-away profile showed (drawn every time, at
depth 32), what that rules out, the candidates left, and what to measure at the next real reminder.
Status diagnosing: the cause is not known.
The records send the operator to "the controller's terminal", and on the
control-node `mesh-controller` is not a command: the controller is a mesh
process with its own account and environment, and nothing puts anything on
PATH. The record proposes mesh-cli, a module on every node whose program
asks the node-engine over a local socket; the node-engine vouches for the
account from the kernel and asks the controller on its node's own subject;
the controller runs the line as the terminal only for the operator's account
where no agent can be that account. The glossary gains mesh-cli, nox (its
zsh alias) and the controller's terminal.
Item 10 said two minutes; the engine's bound is 15, with a two-minute limit
inside it still to settle. What still remains now names a build from another
repository registering a module (mesh-controller 174), the forge's tools
changing its protection (mesh-catalog 153), and the urgent condition every
engine restart raises (mesh-controller 175).
The routes found around the agent account since the record was written are
closed on main (the store's reader, places and served keys, what every session
obeys, execute withheld on the control node); the record names them, drops the
store gap it said kept the boundary from holding, and says plainly what still
remains, first the login shell's execute on the other nodes. To-be 36 §9 gains
the prerequisites and the order the parts go out in.
The re-review closed the command verb to reads, moved enrolment to the
controller's terminal, widened what the node-engine judges, and found the
store's reader able to read every secret; say each, and that the boundary is
not in force until the store is fixed.
The review found ways round the record: a verb that set the accounts, root
following a link below a home, a tool reading any path as the operator, a
restore written beside the agent's files, a stale verdict passing. Record each
bound, the exact ways judged and not judged, the guard on every tool and its
record's limits, and a rollout order the guard does not block.
The operator chose this remedy for ADR 0259 section 8: an agent there could
become root through the operator account's sudo and docker group, and read the
tool runner's credential. Record the node fact, the node-engine's judgement
the self-check reads, the guard, and how a session starts; issue 333 holds
the measured symptom and to-be 36 the design.
The confirmation review found the home scope wrote the operator's own
~/.claude on nodes where the agent is the operator, and that text put
straight on the bus at the mesh or node scope still renders; record both,
the fix for the first, and what closes the second.
Shared agent text is the terminal's until a surface of the operator's own
updates it, the wider controller rule stands, and a password is not a
setting: 342 names every module that takes one through a setting.
The operator accepted both on 2026-10-09. Design 47's state table gains covered and what ends a held
delivery by itself, and its group the wait for a composed check and the lift; design 45's signals table
gains S17 and its planned bus step says the wait is told at once. The glossary's delivery entry names its
six final states.
Decision 1 named S6 for a failed new-module build; S6 is a lost build ask. Such a build is said by one
line in the controller's log until its module is assigned. A module on one machine never gets a 'rest'
step, so covered never reaches it. The forge module's tests run in the catalogue's TypeScript check, #151.
Node-engine #66 passed both required statuses after #64/#65 had merged,
and its merge did not compile: each side added Applied.Declared. The
check clones the head alone and nothing marks a verdict stale when the
trunk moves; ADR 0237/0238 say the head, so the fix needs a decision.
Merge order on a protected trunk is kept only as the first filter; the forge's compare, through a new
read-only tool, decides whether a later merge contains a held one. A merge held without a passing check is
covered only by a later delivery whose own check passed. Covered says a later merge that contains it was
delivered, not that the change runs: a revert in between stays possible. A delivery that only adds a module
is delivered whatever its build does, and covered wins over go when a person's walk fails between two
readings. The glossary gains covered beside superseded and delivered.
ADR 0271 names the bus upgrade as the mesh call and says S17 clears once the step sent the new bus.
The review found that a mergeable file takes any key, not only those it
names, and that the text a session reads stays registrable through a verb;
say both, and the follow-ups the module took.
Issues 319 and 316: fifteen held deliveries asked a person a question with no right answer, and stop,
the only way out, records a delivered change as an error. ADR 0270 delivers a merge that moves nothing at
once, adds the final state covered for a merge a later delivered walk of the same trunk carried, and lifts
a group hold once its composed check passed.
Issue 336: a send held for the bus's planned step raised nothing for 28 minutes. ADR 0271 adds row S17,
said at the first refusal for the operator with the verb, keeps S3 from calling it lateness, and has the
delivery plan say before the merge that a person's bus upgrade follows.
Each issue's diagnosis says what the fix does and how to verify it once delivered.
Record the hole the review traced, why the module cannot tell who called,
which kinds run or are obeyed in a session and which stay registrable,
the fix in the controller and the module, what is registered today, and
that it must land before ADR 0266's agent account is switched on.
Each fix's pull requests are merged and delivered; each issue now says
what was read live on 2026-10-09 to show it, so the record stops
listing fixed faults as located.
The operator accepted ADR 0269 on 2026-10-09. ADR 0118 gets the dated note the README asks for where a
later record narrows its mechanism. The node-engine's to-be design names the decision and says what it
changes, which the cycle check requires of an accepted record.
Third review: a person's stopping a unit the mesh also held stopped leaves no trace, so it is started
again on removal; the home server's restored weekly timer would start a scrub of about 46 hours at once.
A masked or since-changed unit is left alone, and a failed restore waits.
Unassigning the zfs module would leave the home server's pool with no scrub schedule: ADR 0118 never
starts a unit on the way out, so the distribution's timer the module held stopped would stay stopped.
The host now records what it declared beside what it found, and gives back only what the mesh's own
declaration stopped.
A new module counts as something to move, so its delivery is held; a later walk
reaches only the delivery whose merge is its commit. Four covered deliveries were
stopped before this issue was found, and their merged pull requests now say error.
The operator's decision of 2026-10-09: execute runs any command as an
account that can become root without a person, so the control-node stops
offering it now, and every node marks it as needing approval once the
mark exists. To-be 41 gains WP7 for the seat and the shell module.
Located in the controller (places and accesses taken through every verb, no line-break check) and the node-engine (a found directory chowned as root, through a link too, and any path mounted). ADR 0266's boundary depends on the fix.
A merge to a shared repository moved every module that read it, in a gated
tier each (issue 338). The operator's rule maps a change onto the artifacts
whose build source it touches and adds only modules with a build dependency
on a changed artifact; sharing a repository is no dependency. Supersedes in
part ADR 0162 decision 1 (the packages kind) and ADR 0238 decision 3 (whole
repository and context reads); adds build source to the glossary.
Adds what the fix cannot see (definer functions and views; the name check
as a backstop) and, as a follow-up, that the reader's read-only session is a
default a statement can turn off, so the missing write grants are the guard.
A controller merge walks three gated tiers because the route proxy and the
build seat are planned by repository, not by the paths their builds read,
and their programs carry the commit. Located; fix directions recorded.
Opened and diagnosed: pg_read_all_data on the login the store seat's query
runs as. Says what the store can and cannot tell about whether the key was
read, why it should be rotated once the fix is taken, and that no rotation
mechanism exists yet. The fix is mesh-catalog PR 143.
For 28 minutes on 2026-10-08 every send to the control-node waited for a bus upgrade only a person can start, and nothing but a walk's note said so. Located in the controller: the refusal is kept as the walk's note, S3 fires only past a 30-minute bound with generic words, and probe DB reads only a running step.
The record said its data is still copied; the shipped follow-up backs it up as this controller reads
it and lists an unplaceable line rather than failing the machine.
The record claimed a left-out module kept what the machine holds for it and that an entry's unknown key
was read like a top-level one; neither is true of the merged controller.
Dropping an unknown key would run a module without something its manifest says. Also name the check by
what a key is about, narrow the listing to one machine, and say how to roll back below this record.
The operator asked for one place that lists every module's preferences and each machine's value, and
for a list of the values the catalogues hard-code that should become preferences.
A stored manifest read strictly would fail the whole catalogue after a controller rollback, and a node
called default would lose its layer. Also scope the default, retire tunable, and list the new checks.
A ${setting:} nothing set failed composition, and settings refused a key no file asked
for yet, so no order of changes could add a setting to a running module. A manifest may
now default a preference; the operator's own value still has none.
A leftover user unit stayed raised on the workstation: no seat verb showed
the dangling enable link that keeps asking for it, or reset its failed
record, so the only step left was a shell. Lands per ADR 0246.
The review of mesh-controller#150 found the controller now makes an
assignment after the person's act, which no record decided. Decide it,
cite it from the glossary and to-be 45, and correct issue 325's account
of what is settled where and what is sent.
The bus's own numbers were unexplained and raised by nothing. Measured again
read-only: mesh-delivery rewrites unchanged deliveries (326), every controller
verb dials its own connection (327), API errors have no reader (328), event
consumers outlive their declaration (329), and design 25's dead-letter stream
was never built (330). The two slow consumers join issue 270, whose missing
system account they share.
The SAS sentence now holds for modes with spaces, a hung read is unhealthy in two to three minutes, not
one, every USB drive is told sat, and the limits of a stuck read are recorded.
After the second review: smartd is dropped as a second reader that could wake or keep awake the drives,
a stuck read or a drive not looked at is unhealthy, a drive asleep for a day is HIGH and never unhealthy,
and a board chip's maximum says nothing of a fan. The never-woken and hourly claims now say exactly what
holds.
Review found that ADR 0253 let any process at the operator's session release,
stop or start a delivery in the operator's name, and that its tokens, fallback
words and quiet warnings failed on the paths that go wrong.
Rule 4 now matches the module after review: the NVMe temperature bit, old-age attributes, a fan's minimum
or alarm and a board chip's limits raise nothing; a stale watch does. The standby caveat is recorded: no
mesh tool sees a drive's spin-down timer, so spinning drives are read hourly.
The store's tools counted 23.8 GiB nothing records: copied bases the sweep could never
let go of, platforms a let-go index left behind, and images from before the mesh. Package
retention read no lockfile, so it kept versions by age alone.
The operator read the reworded popup and could not tell whether to act, and was
sent to open a session to act at all. The record now decides the verdict, the
quiet rule and the path by which a notification is answered.
A machine's temperatures, fans and drive health were read by the laptop's vendor module only; the
machines' 20 drives were watched by nothing. The sensors module reads them on every machine, holds no
seat until a caller must reach it by role, and says a hardware fault through ADR 0240's health until the
machine judges its own hardware. To-be 48 gains §11 and phase G.
The operator chose a generic boundary for the bar: a block is said in terms no bar
owns and rendered by the seat's holder, placed only where the machine reports the
hardware, and generic hardware comes from the generic seat's module, not a vendor's.
To-be 42 records it; ADR 0208 points to it.
The operator could not read the mesh's notifications: they were the summary meant
for an agent, with ids, commits, keys and verbs, in UTC. The condition now carries
a headline, an explanation and a resolved line beside its summary.
Issue 247 left adding the operator's account to a daemon's group a sudo step by hand. Decide that
a module declares it with the user resource's groups, that the mesh gives back only what it added,
and that the node-engine says relogin needed; amend to-be 41 with WP6 and resolve the issue.
An answer over the bus's max_payload was refused inside the controller and
every caller timed out, while calls said answered. Diagnosed and proved (R314),
and told apart from issue 200, whose permission refusal issue 265 already fixed.
Liveness judged only long-running resources, so a module whose daemon
is a package's unit failed at every login while its machine read
healthy, and a degraded service manager was said by nothing.
The build seat ran the merge-check.sh in the change's head, so a branch older
than the script, or one that gutted it, merged untested; and the media
catalogue did not require mesh/repo-check at all. Located, fixed on branches,
replayed as R310; the protection change awaits the operator.
A group of the controller, the node-engine and the lab, each ready, was
refused as a cycle: built by put the controller's member first, engine
before controller the node-engine's. ADR 0249 ranks the rules (declared,
then built by and version skew, then engine before controller) and
supersedes ADR 0239's sentence that made a declared order against an
inferred one a cycle; design 47 says the precedence. Resolved by
mesh-controller #134 and mesh-catalog #119, replay R309 (mesh-lab #64).
Store-bound packages ran five to seven times slower there while the rest
ran alike: the throwaway store flushes to a disk the mesh's own data keeps
busy. And a holder recreated mid-check left its store and bus running.
The branch building ADR 0169 carried a fix making a node's declaration
consumer as it enrols. The controller already asserts every node's
consumer before each send, and the self-check's healer asserts a missing
one again, so the fix is dropped rather than merged and the record says
why. The installer now places the bus's accounts at genesis.
Two incidents in two days had one shape: a change took effect that nobody saw first (issues 241
and 304). Three guards where the change is made — a settings layer read before it is replaced, a
push that says what it will change, a running module's data move acknowledged — each silent when
nothing is at stake. Accepted by the operator on 2026-10-08.
To-be 44 is in progress in mesh-controller (feat/no-change-takes-effect-unseen), migration 0078,
fitted onto what the controller does since: a whole-mesh push that says so and leaves a machine
waiting for a gate, a person's push that says what it recreates (ADR 0242), a named push's cascade.
The decision index is generated (ADR 0248), so no line is added to its README.
303: a media server's previews were reached through a link its container never mounted — fixed by
mounting them. 304: settings set replaces the whole layer with nothing to read it first and no
history. 240 is fixed by mesh-controller#47; 242 has backups running and records what the rollout
taught. (First opened as 245 and 246; main has since taken both numbers, and 302 was the last.)
292 and 298 resolve with replays now registered in mesh-lab. The other fixed
core issues say why no replay can be laid over the commit before their fix. The
rest are re-checked against main.
The operator asked on 2026-10-08 for the deprecated issues to be gone. In hq an issue
is closed, never deleted, so each one is resolved with its fix, closed wontfix with a
reason, or re-checked against main and the live mesh.
301: S15 counted the operator's pushes of recorded builds, the word ADR 0242
asks for, as repairs and wanted a healer for three causes. 302: the lab's
replays register was never compiled before a merge, because its check ran in
the TypeScript toolchain. To-be 45 §7 and §9 say how each is now decided and
checked.
Research 033 measured the laptop's VPN client and the mesh overwriting each
other's resolver file in nine of nine sessions, each time cutting off one
kind of name. The operator chose a resolver module on a node seat of its
own, installed only where something requires split-dns, with the VPN
client's module carrying the adapter. Graduates research 033 into to-be 50,
and amends connectivity §2, to-be 48 §10, the seats and the glossary.
The controller that merged (mesh-controller #116) dropped the staged seat and
marked both verbs optional, stored in the seat's row and read back optional.
words.py matched a retired word only when nothing followed it, so the
plural of every retired word passed. The pattern now takes s or es on the
last word; 14 uses in 9 documents are reworded, two of them 'the hosts'
for the node-engines.
Design 33 said a seat's verbs change additively, and section 3 made each
one a condition of holding, so a verb added in the controller and served
from the catalogue could land in neither order. It happened three times on
2026-10-07. Section 7 now says the three steps and how each is checked.
The written decision index is the one file every decision PR edits, at the
end of its topic, so on 2026-10-07 each merge forced the others to rebase
and be checked again. The diagnosis weighs four fixes and recommends
generating the index on read.
The agent reached machines over ssh because search never found the verbs by the commands it knew.
Records the three rules (generated instead-of table, search by replaced command, the shell guard
with the operator's recorded override) and how each is checked; to-be 36 names it.
The plan delivering the first health declarations recreated the database and
the document store (record) and nine of mail's containers at once. Record
held only against a person's push to another machine; it now holds against
every send but a person's, and a send says what it recreates.
plans counted a plan's time from its last save, and every advance saved it, so a queued build read
as seconds old and was never late; located in the controller, fix in mesh-controller PR #119.
ADR 0244 sorts the mesh's concepts into ten domains (ADR 0006's contexts
carry over as domains), keeps machine and node as distinct words, and
makes the glossary the authority with every retired word on its
replacement's Not: line. To-be 49 draws the domains; the glossary is
reorganised by them, its two contradictions removed and the missing
words added. words.py now fails on a retired word in running prose and
on a word defined twice, so the rule is enforced rather than believed;
the 63 documents it failed on are reworded here, and research 034 is
kept as the record of the words it studied.
The operator asked for one language per domain because the same concept
keeps arriving under different words. Inventory the words in use, test a
domain split, list the clashes with evidence, and describe how the
glossary rule would be checked.
The laptop's VPN client replaces the mesh's resolver file on every connect and
the node-engine writes it back minutes later, so either the mesh's names or the
corporate ones fail for whole sessions. Measure how the client sets DNS and
weigh how names can be routed by domain without breaking ADR 0223's one-answer
rule.
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.
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.
description:Proposes one decision record or research effort to the knowledge base (seat knowledge-base, hq playbooks 01 and 02) from a draft the lead names - reserves its number when it has none, proposes it whole, reads the knowledge base's own review, revises and proposes again until it approves or asks the operator, at most four versions. Writes nothing in hq or in any repository.
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.
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 neither the milestone part nor the milestone's lead-answers file gives; 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 its answer is in an hq commit (playbook 07, step 0b);
- 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.
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.
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 your build map first, then, at the commit the handover names, every design
line its rows cite (the milestone part's `§n`, found by searching its files) and each section of the design's main
file those lines name, whole; read a further line of the milestone part when a cited line points to it. Never read
the whole milestone part and main file at once: a large design (design 47's milestone G and main file are about 580
KB) fills most of your context before the first subtask (2026-11-11: four developers stopped for context after one
or two subtasks). Then read 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 design line, or the lead's one-line answer in the milestone's lead-answers file, which names the principle (`00-META/principles.md`) that settles 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.
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 and the design's main file, read whole, then the code each design line lands in - 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), the list of design questions the design does not answer, and the list of places where a design line and the code disagree. Decides nothing; writes only its build maps and the milestone file's two lists.
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.
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.
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.
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.
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.
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.
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.
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).
- Seams inside a module, at run time: for every event, queue and piece of state the subject adds or changes, which processes read it on each node (a module's program, its tool runner, any other process its manifest names, the same module on several nodes), and whether each gets every item it needs. A NATS durable consumer or a queue group hands each message to one reader only: two processes reading under one name split the messages silently, and the bus refuses nothing. A design line that names one reading place per module where more than one process reads is a **must**; only a work queue, where one reader per item is the point, is shared. (The operator, 2026-11-14: on ace the assigner's program and its tool runner read one durable consumer, and the runner took all 178 first registrations the program acts on; lead answer A-397.)
- 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.
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.
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.
description:Use when the operator asks to clean up the forge and the working copies — stale or merged branches, old pull requests, finished worktrees, leftover folders, stashes. Triggers on "cleanup", "clean up our repos", "stale branches", "old worktrees", "tidy the forge". Reads first, deletes only what the operator approves, and reports what it cleaned, kept and left.
---
# hq-cleanup
Runs playbook [09 — Cleanup](../../../00-META/process/09-cleanup.md); the playbook is authoritative. This skill
adds the mechanics.
## 1. Take stock (one read-only agent, smaller model)
Brief it to change nothing and to write one report to the session's scratchpad:
- **Forge.** `gitea.gitea_list_repos`; per repository its default branch and **every branch from the git refs**
(`gitea.gitea_api` GET `/repos/{owner}/{repo}/git/refs/heads`; the list tool misses branches, issue 949);
`gitea.gitea_branch_protection_get`; open pull requests (`gitea.gitea_open_pulls`, titles and update times
from `gitea.gitea_api``/repos/{owner}/{repo}/pulls?state=open`). Per branch: contained in the default branch
(`gitea.gitea_contains`, with the default branch's sha), patch-equal (`git cherry` in a local clone), tip date.
- **Local.** Under the projects folder: each clone's `git worktree list --porcelain`, `git branch -vv`,
`git branch --merged origin/<default>`, `git stash list`, `git status --porcelain` per worktree; folders and
loose files beside the clones with `du -sh` and newest file. A worktree under another session's scratchpad is
Kept.
- A **Missing tools** section: each read it did without a mesh tool.
## 2. Classify and ask
Classes as playbook 09 step 2: Safe, Likely safe, Kept, Unknown. Tell the operator the counts and the report's
place, and ask one question: delete the Safe list? Likely-safe and Unknown items are asked separately.
| Research | the knowledge base, not a file: `knowledge-base.ask`, and `knowledge-base.get` with `kind: research` and a number | `status` (`active` / `graduated` / `abandoned`), `date`, links (`became`, `touches`, `cites`) |
| Decisions | the knowledge base, not a file: `knowledge-base.holds` with a topic (the clauses in force, with their records), `knowledge-base.get` with a number, `knowledge-base.links` | `status` (`proposed` / `accepted` / `superseded`), `topic`, `date`, `deciders`, each clause's status, links both ways, what changed it since |
| Issues | the issue tracker, not a file: `mesh_call issue-tracker.list` (optionally `status`, `owner`, `phrase`) and `issue-tracker.get` | `status` (`open` / `diagnosing` / `located` /`fixing` /`resolved` / `wontfix`), `worker` and `stale` while `diagnosing` or `fixing`, `opened`, `located-in`, `fixed-by`, `amended-design`, `record` (the folder here, when it has one) |
## Steps
1. Read the frontmatter block from every file above — a grep across each tree is enough, no
need to load bodies.
2. Render what was asked as Markdown tables. Group and sort sensibly. The **ADR index** is one
of these views: records ordered by number, with title, date and status, and reconstructed
ones marked.
1. Read the designs' frontmatter (a grep across `03-DESIGN/` is enough, no need to load bodies), the
issues from the tracker, and the records from the knowledge base. An issue report carries no status;
where an issue stands is only in the tracker (ADR 0275). A decision record's or research effort's
status is only in the knowledge base (ADR 0290).
2. Render what was asked as Markdown tables. Group and sort sensibly. The **ADR index** by topic is
`knowledge-base.holds` with each topic of the reading order `02-DECISIONS/README.md` writes, in that
order, with a `bound` large enough for the topic (it says what it cut); it is the only place the list is
shown (ADR 0248). The knowledge base has no verb that lists every record by number: a view by number
is built from `get` per number, and says which numbers it read.
3. Flag anything inconsistent at the end, as flags — do not silently correct the render:
- a `graduated` or `abandoned` effort with an empty`became:`
- a `graduated` or `abandoned` effort with no`became` link
- an `implemented` design with an empty `code:`
- a `superseded` record with no`superseded-by:`
- a `superseded` record nothing`supersedes`
- an `open` or `diagnosing` issue with no activity
- a to-be design whose `decisions:`points at a record that does not exist
- a to-be design whose `decisions:`names a record `knowledge-base.get` does not find, or one that is
not `accepted`
- an as-is design whose claims are older than its `updated:` date suggests
## Do not
- **Do not write a status file.** Central status files are explicitly rejected. The view is
always generated, always ephemeral. This includes the ADR index — the hand-written one had
already drifted after a single addition, which is why it was removed.
- Do not infer status from prose. Trust only the frontmatter; if it is wrong, flag it.
already drifted after a single addition, which is why it was removed, and the generated one
written into `02-DECISIONS/README.md` made every two open decisions conflict (issue 297), which
is why that went too. the index test fails if the list is stored there again.
- Do not infer status from prose. Trust only a design's frontmatter, the tracker for an issue and the
knowledge base for a record; if one is wrong, flag it.
python3 00-META/checks/index.py the reading order in 02-DECISIONS/README.md is current
python3 00-META/checks/index.py --write regenerate it
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, no word is defined twice,
and the glossary names no seat's holder
```
Non-zero exit on any problem, so it can be a gate rather than a report.
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 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
@@ -20,43 +28,95 @@ indistinguishable from one that cannot.
| Check | Asserts | Found |
|---|---|---|
| `links` | every relative link resolves | — (run ad hoc during authoring; now permanent) |
| `rests-on` | `decisions:` and `extends:` name records that exist and are **accepted** | the class behind both incidents |
| `live-citation` | a governing document citing a **superseded** record names its replacement in the same paragraph | `01-to-be/README.md` citing ADR 0022 as live guidance |
| `supersession` | if A says it was superseded by B, B says it supersedes A | ADR 0012 never declared that it superseded 0011 |
| `numbering` | the number in the filename is the number in the heading | — |
| `topics` | every record names a topic the index knows | — |
| *(index.py)* | the written reading order matches what the records say | — |
| `no-records` | `02-DECISIONS/` and `01-RESEARCH/` hold their README and nothing else: a decision record or research effort lives in the knowledge base (ADR 0290 rule 9) | written with the change that removed the records (issue 426); it failed on a record file put back in `02-DECISIONS/` before it passed |
| `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
The decision records and research efforts left this repository for the knowledge base (ADR 0290, issue 426),
and the rules these checks held over them left with them. The knowledge base holds each as a rule of its own,
named in its refusal: `knowledge-base.propose` refuses a record that breaks one of the rules that judge one
record, naming every reason at once, and the four rules that judge the whole record set run after every
acceptance and raise a condition when one fails (mesh-knowledge's `rules.go`, one table-test case per rule).
| Rule here until issue 426 (the Python checks, deleted with issue 1296) | Where it lives now |
|---|---|
| `records.py``rests-on`, for a record's `extends:` | the knowledge base's `rests-on` at propose, and the whole-set rule `rests-on-live` |
| `records.py``rests-on`, for a design's `decisions:` naming an accepted record | **nowhere yet**: this repository cannot read the knowledge base. The reviewer checks each new entry with `knowledge-base.get`. Designs become the knowledge base's own kind under issue 428 |
| `records.py``live-citation`, in a record | the knowledge base's `live-citation` |
| `records.py``live-citation`, in `00-META/` and `03-DESIGN/01-to-be/` | **nowhere yet**, as above: the reviewer checks a cited record's status with `knowledge-base.get`; issue 428 |
| `records.py``supersession` | the knowledge base's `supersedes-accepted` and `self-link`, and the whole-set rule `supersession` |
| `records.py``partial-supersession` | the knowledge base's `changes` link to a clause, `changes-in-force` and `supersedes-accepted`, and the whole-set rule `partial` |
| `records.py``clauses` | the knowledge base's `has-clause`, `clause-numbering`, `clause-lead` and `clause-size` |
| `records.py``numbering` | the knowledge base's `title` and `reserved` |
| `records.py``topics`, `index.py` (a record's topic) | the knowledge base's `topic`, against the reading order the index test still checks |
| `records.py``insights` | the knowledge base's `insight-form`; an accepted record changes by a new version marked as a progressive insight |
| `index.py --print` | `knowledge-base.holds` with a topic |
| `cycle.py` research: a known status, `became:` when graduated | the knowledge base's `research-status`, `overview` and `became` |
| `cycle.py` no two decision records share a number | the knowledge base's `reserved`, and the issue tracker's counter behind `knowledge-base.reserve` |
| `cycle.py` an accepted decision cited by nothing | the knowledge base's whole-set rule `cited`: a record accepted there is cited by another record or names a home (`homes` at propose) |
| `cycle.py` a deferral names the issue that tracks it | the knowledge base's `deferral` |
| `words.py` over research efforts from 2026-10-07, and `kept` in `words-allowed.md` | the knowledge base's `retired-word` and `daemon-line`, from this glossary |
## What is deliberately not checked
- **`02-DECISIONS/` and `01-RESEARCH/` may cite superseded records freely.** A decision record
discusses history; research records what was observed. Flagging those would produce noise on
correct documents, and a check that cries wolf gets suppressed — which costs more than not
having it.
- **`03-DESIGN/00-as-is/` may rest on a superseded record.** It describes what runs, and what
runs was built under whatever was decided at the time
*as-is describing a superseded decision is exactly what as-is is for*).
- **Whether a citation's prose is still true.** Only whether the record it points at is live.
A document can cite an accepted record and describe it wrongly, and nothing here notices.
So "governing" means `00-META/` and `03-DESIGN/01-to-be/` — the documents that tell somebody
what to do.
- **Whether a record a document cites exists, or is still accepted.** A checkout cannot read the knowledge
base, and a check that called the mesh would make every merge here depend on it. Until designs become the
knowledge base's own kind (issue 428), the reviewer asks `knowledge-base.get` for each record a change
cites in `00-META/` or `03-DESIGN/01-to-be/` (the documents that tell somebody what to do). An as-is
document may rest on a superseded record: it describes what runs, and what runs was built under whatever
was decided at the time (ADR 0006: *as-is describing a superseded decision is exactly what as-is is for*).
- **Whether a citation's prose is still true.** A document can citean accepted record and describe it
wrongly, and nothing here notices.
## Adding a check
State what incident it would have caught, and make it fail before you make it pass. A check
whose failure has never been observed is a guess about its own correctness.
## cycle.py
## The cycle test
The development cycle, checked ([ADR 0080](../../02-DECISIONS/0080-the-development-cycle-is-checked.md)):
a to-be design names a decision, an in-progress/implemented design names its owning code, a
located/fixed issue names its owner, a fixed/resolved issue says what fixed it, a graduated
research overview says what it became, and no two issue records share a number (issue 155 — the
number is how a record is cited, and `main` lags every open pull request, so two people reading it
allocate the same one). And a core issue — one opened from 2026-10-07 whose`located-in` names a core
repository — resolves only with `replay:` (an id in mesh-lab's replays register) or `replay-none:` saying
why none is possible ([ADR 0237](../../02-DECISIONS/0237-a-change-is-judged-against-the-mesh-that-runs-before-it-merges-on-the-build-seat.md));
it failed on a resolved core issue carrying neither before it passed. `python3 00-META/checks/cycle.py`
The development cycle, checked (ADR 0080):
every design parses, its `layer:` matches its folder and its `status:` is known; a to-be design names a
decision in `decisions:`; an in-progress or implemented design names its owning code; and no two issue
records share a number (issue 155 — the number is how a record is cited, and `main` lags every open pull
request, so two people reading it allocate the same one). An issue report carries the day it was `opened:`
and no status key — `status:`,`located-in:`, `fixed-by:`, `amended-design:`, `replay:`, `replay-none:` or
`resolved:` — because an issue's status lives in the issue tracker (ADR 0275); it failed on all 361 reports
that carried them before they were removed. The rules on an issue's status this check held until then — an
owner for a located issue, a fix for a resolved one, and a core issue's `replay` or `replay-none` (ADR 0237)
— are refused at the write by `issue-tracker.move`. Its rules on research efforts and decision records left
with them (the table above).
## The words test
One word per thing, checked (ADR 0244).
It reads the glossary's *Not:* lines (the retired words, each with its scope) and *Identifier until
renamed* lines, and fails on a retired word or a bare identifier in running prose — what is left once code,
quotations, struck-through text, link targets, comments and frontmatter are taken out — in `00-META/`,
`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 catalog's copy
of the tools' retired words (`retired-words`) with the glossary.
It also fails on a **daemon's line** (ADR 0272,
its insight of 2026-10-09): the operator types one command, `nox`, and a document names a `nox` line, never the
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 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 —
"the host" for the node-engine in 30 designs, "control plane" in 10, the glossary's own entry for the tool runner —
and two glossary contradictions (the "console", the deprecated broker's seat), fixed in the change that
added it. A retired word's plural (`s` or `es` on its last word) is matched as the word: until 2026-10-07
it was not, so "alerts", "rollouts" and "the hosts" (the node-engines) passed while their singulars
failed; the plural failed on 15 uses in 10 documents before it passed. A verb that reads like a plural
("a node hosts") is a finding too, and is reworded. Homonyms (*plan*, *gate*, *tier*, *ask*, *store*, *record*, *check*) are not checked by it: a
word list cannot tell one sense from another, so they are reviewed.
out=append(out,fmt.Sprintf("cycle: 04-ISSUES/%s: is numbered %s, and so is %s -- an issue number is how it is cited, and two records "+
"answering to one means a citation that resolves to whichever the reader opened. Take the next free number across main AND every open pull request",e.Name(),number,first))
}else{
seen[number]=e.Name()
}
}
for_,e:=rangeentries{
p:=path.Join("04-ISSUES",e.Name(),"00-report.md")
if!e.IsDir(){
continue
}
if_,err:=fs.Stat(fsys,p);err!=nil{
continue
}
front:=frontmatter(readFile(fsys,p))
iffront==nil{
out=append(out,"cycle: "+p+": no frontmatter")
continue
}
iffront.scalar("opened")==""{
out=append(out,"cycle: "+p+": opened: says nothing -- the day the issue was opened, YYYY-MM-DD")
continue
}
varcarried[]string
for_,k:=rangetrackerKeys{
if_,ok:=front[k];ok{
carried=append(carried,"`"+k+":`")
}
}
iflen(carried)>0{
out=append(out,fmt.Sprintf("cycle: %s: carries %s, but an issue's status, owner, fix and replay live in the issue tracker (ADR 0275): "+
"move it with `issue-tracker.move`, and keep no copy here",p,strings.Join(carried,", ")))
# Words allowed — documents the words test does not hold to the glossary's retired words
Read by the words test (`words_test.go`) (ADR 0244).
One row per document. *Until* is the date by which it is reworded — past it, the row fails like the words
themselves. A row whose document no longer uses a retired word fails too, so this list only shrinks. The
research efforts this list kept as written (research 034 and 042) live in the knowledge base now (ADR 0290),
which keeps a record's words as it was imported.
| Document | Until | Why |
|---|---|---|
| `04-ISSUES/285-the-merge-gate-compared-broken-to-broken-and-passed/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/300-a-new-module-is-not-built-at-its-merge/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/302-the-labs-go-replays-were-never-checked-before-merge/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/305-a-recheck-left-the-old-verdict-standing/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/336-a-send-held-for-the-bus-step-raises-nothing/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/336-a-send-held-for-the-bus-step-raises-nothing/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/338-a-module-built-from-a-shared-repository-moves-on-every-merge-to-it/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/341-a-merge-check-judges-the-head-not-what-merging-it-makes/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/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 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 |
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)," ")))
@@ -37,13 +38,13 @@ incident behind it is not written down, and the fix is to write it down, not to
| Rule | What it means |
|---|---|
| **Never write to a production database directly** | No insert, update, delete or schema statement executed against production by hand. Schema changes go through numbered migrations; data changes go through application code or the module's own capabilities. Raw statements skip every side effect the proper path has — events, audit, cache invalidation, fan-out. |
| **Every schema change is a migration** | Numbered, in the module's own language, compiled with it. Both a baseline for a fresh installation *and* an incremental migration for installations that already exist. If code references a column, the migration creating it must exist. [ADR 0013](../02-DECISIONS/0013-schema-changes-are-numbered-migrations.md) |
| **Every schema change is a migration** | Numbered, in the module's own language, compiled with it. Both a baseline for a fresh installation *and* an incremental migration for installations that already exist. If code references a column, the migration creating it must exist. ADR 0013 |
| **Never bypass the pipeline** | No manual database edit, no manual restart as a workaround. Fix the cause and deploy. A workaround that works is a workaround that is never removed, and the next person cannot tell the node from its declaration. |
| **Never create a symlink** | A hand-made link caused production data loss through container volume resolution, and the judgement needed to make a safe exception is exactly the judgement unavailable at the moment it matters. **The mesh creates none at all** ([ADR 0012](../02-DECISIONS/0012-the-mesh-creates-no-symlinks.md), which supersedes [ADR 0012](../02-DECISIONS/0012-the-mesh-creates-no-symlinks.md)). The links the installer still reconciles are a migration, not a permission. |
| **Never create a symlink** | A hand-made link caused production data loss through container volume resolution, and the judgement needed to make a safe exception is exactly the judgement unavailable at the moment it matters. **The mesh creates none at all** (ADR 0012, which supersedes ADR 0012). The links the installer still reconciles are a migration, not a permission. |
| **Never push directly to the main branch** | Branch, push, review, merge. Every merge is a human checkpoint, without exception — **including in this repository**. A documentation repository is not a lower tier of care; a decision record lands the same way a service does. |
| **One change per pull request, and never merge unapproved work** | Unrelated improvements bundled together cannot be reviewed or reverted separately. And the checkpoint is **a person deciding, not a person clicking** — work may be merged by whoever wrote it once a human has explicitly approved *that merge*, and never on a standing permission, an instruction to do the work, silence, or the author's own judgement that it is ready. [ADR 0023](../02-DECISIONS/0023-approval-is-the-checkpoint.md) |
| **One change per pull request, and never merge unapproved work** | Unrelated improvements bundled together cannot be reviewed or reverted separately. And the checkpoint is **a person deciding, not a person clicking** — work may be merged by whoever wrote it once a human has explicitly approved *that merge*, and never on a standing permission, an instruction to do the work, silence, or the author's own judgement that it is ready. ADR 0023 |
| **Never open a pull request unprompted** | A permissions list saying it is allowed is not a request. |
| **A failed step fails the job** | A sequence that continues past a failure does the next thing in the wrong place. Gate each step on the last. [ADR 0010](../02-DECISIONS/0010-delivery.md), and §5. |
| **A failed step fails the job** | A sequence that continues past a failure does the next thing in the wrong place. Gate each step on the last. ADR 0010, and §5. |
### A failed step must stop the steps after it — how it was earned
@@ -69,7 +70,7 @@ reported failure, nothing stopped, and the damage happened somewhere nobody was
- **Every runtime variable is declared.** A variable the module reads and the manifest does not
declare is invisible to the mesh: it will not be generated, injected, or audited.
- **Provisioned credentials arrive through declared requirements**, never hardcoded in code,
compose files or scripts. [ADR 0009](../02-DECISIONS/0009-modules-and-the-graph.md)
compose files or scripts. ADR 0009
- **Never install a package by hand.** A package is declared in the manifest and arrives the
way every other package does. A hand-installed package is invisible to the mesh: it is not
declared, not reproduced on the next node, and not present after a rebuild — and the node
@@ -82,7 +83,7 @@ reported failure, nothing stopped, and the damage happened somewhere nobody was
- **Every standalone application gets its own repository**, with a manifest at its root,
registered as a build source. Creating an application directory in the monorepo is a
### Contexts integrate through the record, never through a shared schema
@@ -172,6 +173,46 @@ 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):
| 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 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
lowest level that reproduces it, before its fix.
- **A test that needs longer than a second, or a database, the network or a service, is not a unit test.**
- **A suite over sixty seconds is a defect with its own issue**: it is made faster or split, not accepted.
- **Never run a merge check, a throwaway database or an integration suite locally.** The forge's checks do,
on the builder.
- **A report names its tests and how long they took**, so a test over its budget is seen when it is added.
### Tests within a time budget — how it was earned
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.
### A report is read from the system, never from what asked for it
The same rule as the two above, pointed at reporting rather than at verification. **Anything
@@ -198,8 +239,8 @@ declaration was never wrong. Nothing ever asked the system.
### Search the record before forming a hypothesis
The first action on any error message, failing service or unexpected behaviour is to search the
operational memory for the literal error text — before a hypothesis, not after one fails. The
knowledge base is indexed on symptoms.
record for the literal error text (`records.records_search`) — before a hypothesis, not after one fails.
The search matches the words as written, so search with the error's own words.
This fires hardest on *familiar* ground, where a confident trail feels like progress. Two
entries were each rediscovered from scratch over several hours in a single session because the
@@ -214,7 +255,7 @@ This document is governed. It does not change by commit message or unilateral de
1.**Propose** — a change stating what rule is changing, why the current wording is
inadequate, and what reviewed it.
2.**Review** — sign-off by reviewers who are not the proposer.
3.**Record** — the change is a decision and gets a record in [`02-DECISIONS/`](../02-DECISIONS/), because a
3.**Record** — the change is a decision and gets a decision record in the knowledge base (playbook [02](process/02-graduation.md)), because a
rule the mesh enforces is architecturally significant.
@@ -37,41 +39,66 @@ how-we-build.md ──► constitution sync ──► knowledge base ──► i
| Layer | What it is | Changes when |
|---|---|---|
| `00-as-is/` | The mesh that exists today. Describes shipped behaviour, including behaviour nobody would choose again. | Something ships, or an as-is claim is found to be wrong. |
| `01-to-be/` | The mesh being built toward. Every statement traceable to a record in `02-DECISIONS/`. | A decision is taken or amended. |
| `01-to-be/` | The mesh being built toward. Every statement traceable to a decision record in the knowledge base. | A decision is taken or amended. |
A to-be document that ships does not move. Its as-is counterpart is written or updated, the
to-be document's frontmatter goes to `implemented`, and both stand — one describing what runs,
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
[`playbooks.html`](playbooks.html): a picture of these playbooks, never their authority.
| # | Playbook | Trigger |
|---|---|---|
| [01](01-research.md) | Research | An idea worth investigating before committing to design |
| [02](02-graduation.md) | Graduation & design change | Research concludes, or a design must change |
| [01](01-research.md) | Research | An idea from the operator, or one worth investigating before committing to design: setup questions, findings, a direction the operator confirms |
| [02](02-graduation.md) | Graduation & design change | Research concludes (its direction confirmed), or a design must change: decision records, the to-be design |
| [03](03-issues.md) | Issues | Something is wrong — often with the owner unknown |
| [04](04-build-handoff.md) | Build handoff | A design is ready to be built |
| [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) | Feature branches across repos | Work that changes code, in one repo or several at once |
| [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 |
## The cycle is checked
The flow above is a rule, and a rule states how it is checked:
[`00-META/checks/cycle.py`](../checks/cycle.py) refuses a to-be design that names no
decision, an `in-progress`/`implemented` design that names no owning code, an issue marked
`located`/`fixed` with no owner or `fixed`/`resolved` with no fix, and a `graduated`
research overview that does not say what it became. Run it with `records.py` and `index.py`
before any HQ merge. What the checks cannot see — that code work actually started from a
the cycle test in [`00-META/checks/`](../checks/) refuses a to-be design that names no
decision, an `in-progress`/`implemented` design that names no owning code, two issue folders
sharing a number or an issue report carrying a status key; a `graduated` research effort that
does not say what it became is refused by the knowledge base's `propose` (ADR 0290). Run it with the records, index and
words tests before any HQ merge: `go test ./...` at the root runs all four, and the checker runs the same as `mesh/check` (ADR 0527). The issue rules the check
once held — `located` with an owner, `resolved` with a fix, a core issue with its replay — are
refused at the write by the issue tracker's `move`
(ADR 0275). What the checks cannot see — that code work actually started from a
handoff — is held by playbooks [04](04-build-handoff.md) and [07](07-feature-branches.md):
a feature branch exists because a design or an issue sent it.
## Status lives in frontmatter
## Status lives in frontmatter, an issue's in the tracker
Research overviews, design docs, issue reports and decision records each carry their status as
YAML frontmatter (schemas in the section READMEs and playbooks). There are **no central status
Design docs carry their status as YAML frontmatter (schema in playbook [02](02-graduation.md)).
Research efforts and decision records carry theirs in the knowledge base, which refuses a wrong one at
`propose` (ADR 0290). An issue's status lives in the
issue tracker, which refuses a wrong status at the write, and its report here carries only
the day it was opened (playbook [03](03-issues.md)). There are **no central status
files** and no decision ledger. **Every decision is a record in
[`02-DECISIONS`](../../02-DECISIONS/)** — if it is worth recording it is worth a record, and if
it is not worth a record it is not recorded. Cross-cutting views, the decision index included,
are generated on demand by the `hq-status` skill and never written to disk.
the knowledge base** — if it is worth recording it is worth a record, and if
it is not worth a record it is not recorded. Cross-cutting views are generated on demand by the
`hq-status` skill and never written to disk (ADR 0248); the decisions of a topic are
@@ -25,7 +25,7 @@ Three questions, answered from the machine:
## The steps
1.**Name what it provides and requires**, if anything. A name is what a consumer is coupled to,
not the role it plays ([ADR 0027](../../02-DECISIONS/0027-a-provision-names-what-the-consumer-is-coupled-to.md)):
not the role it plays (ADR 0027):
`postgres-database`, not `database`. Most modules provide nothing and require nothing — an
application is usually a leaf.
@@ -33,11 +33,22 @@ Three questions, answered from the machine:
`package-manager`, `seat`. A capability is detected and refused against; it is not something a
module can install.
3.**Write the resources in the order they must happen.** They are applied in the order written
3. **Choose each part's form, from the table in [design 20](../../03-DESIGN/01-to-be/20-writing-a-module.md) *What a
module is built of*.** Tools are a `bundle` the tool runner loads (`loads`, and every tool in `tools`); a service of
the module's own code is a `process` resource; a scheduled job says `schedule`, a one-time step `run-once`, a
migration of the module's own state `prepares`; a seat's implementation is a claim and the verbs it serves; an image
is an `image` or `upstream` artifact run by a `container`; a program of the operating system is a `package` and its
`service` resources. A bundle or a package is in Go or TypeScript, the languages the builder has build modules for.
4.**Ask for kept data in `requires`, by template** (`state`, `events`, `work-queue`, `log`, `objects`, `ledger`), each
entry with its `name`, `storage`, `template` and `options`. The old sections `state`, `logs`, `streams` and
`objects` are for the parts the bus module needs before it can answer, and for no new entry anywhere else.
5.**Write the resources in the order they must happen.** They are applied in the order written
and orphans are removed in reverse, so a `network` is written before the containers that join
it and removed after them.
4.**Put every secret in a file, never in `env`.** A declaration travels over the broker in plain
6.**Put every secret in a file, never in `env`.** A declaration travels over the broker in plain
text: a password in `env` is a password the broker sees. **The mesh delivers parts; a module
that needs them combined combines them.**
@@ -52,7 +63,7 @@ Three questions, answered from the machine:
the container env-file: [/var/lib/postgres/superuser.env]
```
The host fills the hole on the machine, which is the only place both halves exist — the mesh
The node-engine fills the hole on the machine, which is the only place both halves exist — the mesh
discarded the value
([credentials and their rotation](../../03-DESIGN/01-to-be/13-credentials-and-their-rotation.md)).
A **provisioner** is the exception: it reads a password file, so it mounts the `.secret`
@@ -67,21 +78,64 @@ Three questions, answered from the machine:
Add `restart-on` naming the env file, or the container keeps the credential it started with
through every rotation.
5. **Pin every image by digest.** A tag moves. The manifest in a repository names artifacts; the
manifest the mesh holds names digests, and they are not the same document.
7. **Pin every image by digest.** A tag moves. An `upstream` artifact's `from`, and a container's `image` written
directly, name `@sha256:`: the builder refuses an upstream reference with a tag alone. The manifest in a repository
names artifacts; the manifest the mesh holds names digests, and they are not the same document.
6. **Decide generate or accept.** A new module's credential is generated. **An adopted one keeps
8. **Decide generate or accept.** A new module's credential is generated. **An adopted one keeps
the credential it already has** — `secret accept` — because minting a new password for a
database that already exists locks the application out of its own data.
7. **Add a provisioner only if the software cannot read a file.** A proxy that watches a
9. **Add a provisioner only if the software cannot read a file.** A proxy that watches a
directory needs nothing. PostgreSQL needs `CREATE ROLE`, an object store needs a bucket and a
policy, an identity provider needs a realm and a client — those need a small program beside
them. It reads what the mesh granted and reconciles; it does not decide anything.
8.**Prove it in the lab, against the real software.** Not that a container started — that the
thing works: the credential authenticates, a wrong one is refused, the containers reach each
other, the data survives a restart.
10. **Prove it in the lab, against the real software.** Not that a container started — that the
thing works: the credential authenticates, a wrong one is refused, the containers reach each
other, the data survives a restart.
## Where the parts of the mesh read a manifest differently
*Written 2026-11-12 from reading the manifest validator, the builder, the node-engine's vocabulary and the tool runner
on their main branches.* The manifest validator accepting a manifest does not yet mean every other part takes it.
Until each of these is closed in the part named, write the form in the right column:
| the manifest validator accepts | but | so write |
|---|---|---|
| a `bundle` or a `package` in any language word | the builder builds only Go and TypeScript bundles and TypeScript packages, and refuses the rest by name at the build | a bundle in Go or TypeScript |
| an `upstream` artifact whose `from` names a tag alone | the builder refuses an upstream reference with no `@sha256:` | the reference with its digest |
| a `log` asked for in `requires` by template | the tool runner's log calls reach only a log of the old `logs` section; a template log is reached only by its stream's read and fill calls, so a module cannot append to it through the runtime | a template log only where the module's own bus account publishes it; a log its tools append to through the runtime waits for the tool runner's fix |
| any `type` and any field on a resource | the node-engine refuses an unknown type and a field the type does not use, when the module is composed for a machine: in the change's composition step only for the machines the change touches, and for a module assigned nowhere never | each resource's fields as the node-engine's vocabulary has them (mesh-sdk's declaration package) |
| `schedule` and `run-once` on a `process` unjudged | the node-engine refuses a process with both, or a scheduled one with `restart-on`, `replaces` or `witness`, or an invalid cron | a process in one mode |
How it is checked: each row is closed by a change in the part it names, which deletes the row in the same pull
request; a reviewer of a manifest reads these rows.
## 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
@@ -89,7 +143,7 @@ Six attempts, one real bug. Recorded because the ratio is the lesson: **the mesh
time and the scaffolding was not.**
- A shape existed in the language and no host implemented it, so every declaration carrying one
was refused whole — correctly, and the host said exactly that. **Nobody was reading the host's
was refused whole — correctly, and the node-engine said exactly that. **Nobody was reading the node-engine's
log.** Read it first; it is the only place that says why a machine did nothing.
- A blind find-and-replace renamed a provision in quotes and missed the same word bare.
- A command was tested only for the invocations that should fail, so it rejected every real one
@@ -99,9 +153,30 @@ time and the scaffolding was not.**
## Rules
- **Read the host's log before theorising.** A declaration that was sent and not applied says so
there and nowhere else.
- **Read the check's verdict, then the node-engine's log, before theorising.** The change's check names every
problem the manifest validator and the composition step found; a declaration that was sent and not applied says
so in the node-engine's journal (`<node>/node-service-manager.journal`) and nowhere else.
- **A failing test is kept, not skipped.** It is the reproduction.
- **Never rotate during an adoption.** Rotation is a separate act, afterwards, deliberately.
- **A data directory is never removed by the mesh** ([ADR 0030](../../02-DECISIONS/0030-data-outlives-the-mesh-that-declared-it.md)),
- **A data directory is never removed by the mesh** (ADR 0030),
and that protects against the mesh only — not against a disk or a mistaken command.
## Moving a module's directory
When a fix moves what a container mounts to a new path (issue 1843: only-office's working directories
moved into a root-only box), the old directory does not go away by itself, and it is closed in three steps.
1. **The move.** The new directory gets a new id at its new path. The old one keeps **its old id at its old
path** for as long as it holds data, with the mode it should now have: the node-engine leaves a directory
it finds at a path under a new id as it found it, and sets no mode when the owner differs (issue 339), so
only the old id closes it. The node-engine removes a directory that is no longer declared only when it is
empty; a non-empty one is kept on disk with no further cleanup.
2. **The deletion, on the operator's word.** Its contents are data, so they are removed only after the
operator's yes, through `<node>/node-files.delete`. That tool moves into the node's trash: the disk space
comes back only when the trash is emptied (issue 1870: no tool does that yet).
3.**The declaration leaves** in a second small fix, once the directory is empty (issue 1854).
Plan the three in the first fix's issue, so the second fix is not found later by accident.
A service that starts on empty working directories may need minutes before it answers (OnlyOffice: about
two): the live check after the delivery waits for it before calling the move broken.
**Trigger.** One issue in one repository, small enough to build in about an hour: a bug with a known cause,
a missing check, a wording, a playbook or design edit. Anything larger, or anything that needs a change in a
second repository first, is a feature and follows [playbook 07](07-feature-branches.md). A feature is the
larger kind: it touches several modules and has a research effort or a design before it. **Needing a decision
does not make a fix a feature**: the decision is settled first (step 1) and the fix stays small (the operator,
2026-10-16).
**Related issues in one fix.** A small fix may cover two or three related issues when they are in the same
repository, mostly in the same module, and together still fit in about an hour: they touch the same files, or
one would be wrong or unsafe without the other (switching a clipboard's history on before its history tool stops
handing out what was copied). Each issue is named in the commit and the pull request and moved to `fixing`,
and each is resolved on its own once the fix is delivered. More issues, a second repository, or more than an
hour is a feature.
**Who runs it.** Anyone who writes code, engineers and agents alike.
**A fix found during a milestone rides in that milestone's group** (the operator, 2026-10-21, after a day with ten
mesh-sdk merges, each rebuilding about forty dependent modules, and eight mesh-controller merges, each sending a
delivery to every node). Playbook [07](07-feature-branches.md) makes a milestone one piece of functionality
released once as one delivery group (ADR 0482). A small fix in a repository the running milestone touches, mesh-sdk
and mesh-controller above all, is built as below but on the milestone's branch, so its pull request joins the group
and merges with it. The exception is a fault that is broken for the operator now (something they see failing at
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 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). **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**, answered as playbook [07](07-feature-branches.md), step 0, *Who answers a design question*,
says, before any code builds it: the session's lead answers it in one line against the principles
(`00-META/principles.md`), written in the issue's note, naming the principle that settles it; one no principle
settles goes to the operator, one question with its recommendation, when its answer changes what the operator sees
or how they work, removes data or needs their terminal, and otherwise to `hq-design-writer` as a design line
(playbook [02](02-graduation.md), *Answering a design question*), read by the four reviewers by architectural
domain in one round and told to the operator in one line. 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 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
the repository's own clone, which stays on `main` (playbook [07](07-feature-branches.md), step 0, item 2). Write the
test that fails today first, on an assertion about what the code does: a test that fails only because it
does not compile has not failed first (playbook [07](07-feature-branches.md) step 1); make the change; keep `gofmt`, `go vet` and the repository's whole unit suite green
before every commit (each test well under a second; never a merge check or a database locally: how-we-build §5, ADR 0391).
Check that it compiles with `go vet`, never `go build` in a module's folder: with one main package it writes the
program beside `go.mod`, and `git add -A` takes it (issue 1577: two 5-10 MB programs committed on 2026-10-21,
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). 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 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): 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 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
in the description does not hold it back: the Approve merges whatever is asked; 2026-10-25, machines lost modules
when a second change merged first). **A reviewed follow-up to a fix still waiting for the Approve is folded into
that pull request** (head moved): one Approve, one delivery. Both are checked as playbook
[07](07-feature-branches.md) step 3 says.
**At the second instance of a fault kind found in a review, the developer searches for every instance** and names
each in the report (playbook [07](07-feature-branches.md) step 2, item 9).
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, 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, 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.
**A second fault found by the delivery.** When a fix's delivery shows a second fault that keeps the issue's
done-when from holding, and that fault is in the same files, it is taken into the same issue as a second pull
request with a review round of its own. A fault in other code is opened as an issue of its own, and the first
issue waits for it (issue 937: mesh-catalog #335 was taken in; issue 943 was opened).
**A fix that moves a file to a new filler compares the values first.** When a fix makes a module's file filled a
new way for the first time (the provisioner client in place of the controller, a provider's entry in place of a
composed value), the fix lists every value the old way put into that file on each machine it reaches and shows,
in its review, that the new way gives the same values, or says which differ and why. A difference nobody looked
at is an outage: on 2026-10-16 the forge and the identity provider on the control node were down for 17 minutes
because postgres's consumers were served the port inside its container instead of the port it is published on
(issue 957). The comparison is read from the machines (the file as it is today) before the merge, not from the
code.
## Bounds
| Waiting on | Bound | Past the bound |
|---|---|---|
| building the fix | 1 hour | it is a feature: stop and plan it under playbook 07 |
| the review | 15 minutes | ask the reviewer where it stands |
| 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 |
A wait past its bound is said to the operator at once, with what is being done about it.
## Models
The fixing agent runs on the smaller model; the reviewer on the larger. A session fixing alone does the
reading itself and uses one subagent only for the review.
## How it is checked
- 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 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.
- An issue in `fixing` with nobody on it shows in `issue-tracker.list` with `flag: abandoned`; a stopped fix
moves it back to `open` with its note.
- A fix found during a milestone is named in the lead's report with the group it rides in, or with the reason it
went alone. `mesh-delivery.deliveries` shows the milestone's members in one group, merged as one source revision
per milestone; a merge of mesh-sdk or mesh-controller outside the group, with no reported reason, is this rule skipped.
- The repository's own clone says `main` (`git -C <clone> branch --show-current`); another branch there is a
<pclass="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>
<ahref="#cycle">The cycle</a>
<ahref="#feature">A feature, step by step</a>
<ahref="#tests">When tests run</a>
<ahref="#review">The review loop</a>
<ahref="#issues">An issue's life</a>
<ahref="#where">Where things live</a>
<ahref="#all">All playbooks</a>
</nav>
<!-- ============ THE CYCLE ============ -->
<h2id="cycle">The development cycle</h2>
<pclass="lead">Work enters as an <b>idea</b> or a <b>symptom</b>. An idea becomes a decision, a design and then milestones; a symptom becomes an issue. Both end as code delivered to the machines, and the as-is design is updated. <b>No design without a decision; no development without a design or an issue that sends it.</b></p>
<divclass="box scroll">
<svgviewBox="0 0 1080 470"role="img"aria-label="The development cycle across playbooks 01 to 09">
<h2id="feature">A feature, step by step (playbook 07)</h2>
<pclass="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>
<divclass="box scroll">
<svgviewBox="0 0 1080 430"role="img"aria-label="Playbook 07 in lanes: lead, fixing agents, reviewer, the mesh, the operator">
<li><spanclass="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><spanclass="tag new">new</span>The prepare reads the design whole, then the code each design line lands in, and lists under Design meets code every place where they disagree: a form the code cannot take, a part the line assumes built that is not, a rule in code the line would break. The lead answers each in one line against the principles before develop starts.</li>
<li><spanclass="tag new">new</span>Design complete: the lead answers each question in one line against the principles, naming the principle; only one no principle settles goes to the operator (when it changes what they see or how they work, removes data or needs their terminal) or else to the design writer as a design line, read by the reviewers by architectural domain. Develop starts only when every answer is in an hq commit.</li>
<li><spanclass="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><spanclass="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><spanclass="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 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>
<li><spanclass="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><spanclass="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><spanclass="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><spanclass="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 build map: stop that subtask and report, file:line.</li>
<li><spanclass="tag new">new</span>Start a subtask only with room to finish it; stop between subtasks, never inside one.</li>
</ul>
</div>
</div>
<!-- ============ TESTS ============ -->
<h2id="tests">When tests run</h2>
<pclass="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>
<divclass="box scroll">
<svgviewBox="0 0 1080 170"role="img"aria-label="Test levels over a feature's timeline">
<textx="120"y="162"class="mute">develop</text><textx="470"y="162"class="mute">end of step 1</text><textx="640"y="162"class="mute">review</text><textx="800"y="162"class="mute">step 3</text><textx="960"y="162"class="mute">merge</text>
<textx="10"y="44"class="t">Unit</text><textx="10"y="60"class="mute">on the machine</text>
<textx="100"y="154"text-anchor="middle"class="t">issue-tracker.open</text><textx="100"y="172"text-anchor="middle"class="mute">anything beyond the issue</text>
<textx="405"y="260"text-anchor="middle"class="t">After round 3: the operator</text><textx="405"y="278"text-anchor="middle"class="mute">what is left, with a recommendation</text>
<pstyle="font-size:14px">Only what makes the change <b>wrong</b> against its issues, their acceptance criteria and its decisions. Anything more (hardening, a further case, a nicer form) becomes a new issue, and the round does not wait for it.</p>
<h3style="margin-top:12px">What every round reads</h3>
<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 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>
<divclass="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>
<!-- ============ ISSUE LIFE ============ -->
<h2id="issues">An issue's life (playbook 03)</h2>
<pclass="lead">The issue tracker (seat <code>issue-tracker</code>) holds every issue's number, status, owner, fix and links. Its <code>move</code> refuses a wrong move at the write.</p>
<divclass="box scroll">
<svgviewBox="0 0 1080 230"role="img"aria-label="Issue statuses and the moves between them">
<pathclass="edge dash"d="M700,70 C700,30 600,30 590,30 C400,30 120,30 90,68"marker-end="url(#ar5)"/><textx="320"y="24"class="mute">stopping: back to open, with a note of branch, last commit and what is left</text>
</svg>
<divclass="legend"><span>A worker idle for a day may be taken over without a reason; otherwise <code>take-over</code> with a reason. An issue about a condition is linked to it, so the alert names the issue.</span></div>
</div>
<!-- ============ WHERE THINGS LIVE ============ -->
<tr><td>Decisions (ADRs) and research efforts</td><td>the knowledge base (seat <code>knowledge-base</code>)</td><td><code>reserve</code>, then <code>propose</code> the record whole</td><td>a file in hq</td></tr>
<tr><td>Issues: status, owner, fix, links</td><td>the issue tracker</td><td><code>open</code>, <code>move</code>, <code>note</code>, <code>link</code></td><td>a status key in a report</td></tr>
<tr><td>Designs, as-is and to-be</td><td>hq <code>03-DESIGN/</code>, status in frontmatter</td><td>a pull request</td><td>the two layers mixed</td></tr>
<tr><td>Playbooks, glossary, how-we-build</td><td>hq <code>00-META/</code></td><td>a pull request</td><td>a copy in a session's memory</td></tr>
<tr><td>The rules every session keeps</td><td>instruction sections (module <code>claude-code</code>)</td><td><code>claude_code_instructions_propose</code>, the operator's Approve</td><td>a hand-edited file</td></tr>
</table>
</div>
<!-- ============ ALL PLAYBOOKS ============ -->
<h2id="all">All playbooks</h2>
<pclass="sub">Open a card for its steps, what it produces and how it is checked.</p>
<footer>Drawn from hq main f269e83 on 2026-10-19 and kept in hq beside the playbooks. The playbooks are the authority; this page is a picture of them, and a change to a playbook's steps updates it in the same pull request (not yet checked: issue 1222).</footer>
</main>
<script>
constP=[
{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.","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 · 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."},
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 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"],
check:"propose refuses; the records and index tests; set-wide rules raise conditions."},
{n:"03",name:"Issues",kind:"symptom",c:"--sym",
trig:"Something is wrong: an unenforced rule, a stated behaviour that does not happen, a silent failure.",
who:"Anyone opens; a worker claims it by moving it.",
steps:["Open it in the tracker: title, report; take the number it gives.","Tracker unreachable: take no number, say so.","A design or governance issue: a folder in hq with the report.","About a condition: link the condition's key.","Move to diagnosing with by, before investigating.","Note the trail; a folder issue also gets a dated diagnosis.","Move to located with located-in, a registered owner.","Move to fixing with by, before fixing.","Name fixed-by at the merge; stay fixing until proven live.","Move to resolved; a core issue gives replay or replay-none.","A design gap: run 02 and give amended-design.","Not going to be fixed: wontfix with a reason."],
prod:"A tracker record with notes and links; for a design issue, its narrative folder in hq.",
next:"02 · 07 · 08",bounds:"A worker idle for a day is stale",
prev:["Numbers that collide","Two agents starting the same work","Status held in two places"],
check:"The tracker's move refuses at the write; the cycle test checks the folders."},
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.","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"],
check:"Read by the lead and the reviewer; a check is tracked by issue 845."},
trig:"how-we-build.md changed a rule the mesh enforces at runtime.",
who:"Whoever made the change.",
steps:["Edit how-we-build; the reasoning stays there.","Record the change as a decision (02).","Publish the derived page under its slug.","Keep the section numbering stable.","Read the page back; verify the change is there.","Note the sync in the record's consequences."],
prod:"A decision record; the derived constitution page injected into design sessions.",
next:"02",bounds:"no time bound",
prev:["Drift between the reasoned and the enforced copy","A publish that said success and did nothing","Edits to the derived page that vanish"],
check:"The read-back in step 5."},
{n:"06",name:"Writing a module",kind:"side",c:"--side",
trig:"Something that runs today must run on the mesh.",
who:"Whoever ports or writes it.",
steps:["Read what runs: compose file, environment, where data sits.","Name what it provides and requires.","Declare capabilities for machine facts.","Choose each part's form (design 20).","Kept data in requires, by template.","Write resources in the order they must happen.","Every secret in a file, never in env.","Pin every image by digest, upstream too.","New: generate the credential; adopted: accept it.","Prove it against the real software: auth, refusal, restart."],
prod:"A module declaration, optionally a provisioner, and its proof.",
next:"07",bounds:"no time bound",
prev:["A service running with no password","A new password locking out adopted data","A test that cannot fail"],
check:"Example tests refuse the env-file mistake; review."},
{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, read the milestone part and the design's main file whole, then the code each design line lands in. (new)","List every place where a design line and the code disagree, beside the design questions. (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 lead answers every question against the principles; one no principle settles goes to the operator or the design writer; 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)","Dry run, for a change of what judges, builds or merges it: the live take-in run whole with the seat list it will read, every build against the packages as published, the gate's merge path read for the group; an item left open holds the push. (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 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","A dry run with an open item, taken as a pass"],
check:"The checker's one status, mesh/check; the review record; the dry run's section in the milestone file; the tracker's move."},
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, the design lines it builds and the code; a design question is answered by the lead against the principles (one no principle settles by the operator or the design writer) 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 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",
trig:"The operator asks, or merged branches, stale pull requests and old worktrees pile up.",
who:"A session on the operator's word; the operator decides every deletion.",
steps:["Take stock, read-only.","Write one report: item, class, evidence.","Classify: safe, likely safe, kept, unknown.","Report stale pull requests; never close them.","Ask: delete the safe items as listed?","Delete only the approved list; never force.","Report what was cleaned, kept and unknown."],
prod:"A stock report, the approved deletions, issues for missing tools.",
next:"03",bounds:"A worktree is safe only if untouched for 2 h · a PR is stale after 3 days",
prev:["Deleting unfinished work","Deletion by name or age alone","Missing tools left as session notes"],
check:"The report names the evidence for each deletion."},
trig:"A page the operator will use is about to be designed or rebuilt, or the operator judges one unusable.",
who:"The design's lead; the operator picks.",
steps:["Gather what the page must carry: the as-is, the real data's shape, the operator's words, how others do it.","Draw three to five mockups with fixed, invented data, phone and desktop. (new)","Show them; ask one question per round. (new)","Make the pick the reference, with the operator's own details replaced. (new)","Write what is new as decisions, then the design and its milestones.","Hold the build to the reference; done when the operator uses it."],
prod:"The reference mockup beside the design, its decisions, an acceptance test of live use.",
next:"02, then 04",bounds:"A round 1 h · 3 rounds without a pick: ask what is missing",
prev:["A page judged unusable the day it ships","Rebuilding after delivery"],
check:"The design links its mockup; the review shows the build beside it; the operator's use is the last test."}
];
constkinds={all:"All",idea:"From an idea",symptom:"From a symptom",build:"Code changes",side:"Alongside"};
@@ -14,31 +14,32 @@ 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. |
| `hq` | This repository, under the company organisation — mission, research, design, decisions, issue diagnosis. Company-scoped ([ADR 0019](../02-DECISIONS/0019-how-this-repository-works.md)); the mesh is its first product. The source of truth for *why*. Carries no implementation. |
| `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. |
## What the mesh becomes
[ADR 0019](../02-DECISIONS/0019-how-this-repository-works.md) records the repositories the
so far** — the lab was built first ([ADR 0016](../02-DECISIONS/0016-the-lab.md)). The tiered
so far** — the lab was built first (ADR 0016). The tiered
decomposition below is the planned shape; the repositories built to date do not map onto it
one-for-one — `mesh-catalog`, `mesh-sdk` and `mesh-tools` exist where the table names
`mesh-foundation` and `mesh-surfaces`, and reconciling the two is itself still ahead.
| Repository | Tier | Holds |
|---|---|---|
| `mesh-host` | 0 | **exists.** The node host — one statically linked binary, requiring nothing present ([ADR 0005](../02-DECISIONS/0005-the-node-host.md)) |
| `mesh-host` | 0 | **exists.** The node-engine — one statically linked binary, requiring nothing present (ADR 0005) |
| `mesh-foundation` | 1 | the four pinned services, as declarations |
| `mesh-controller` | 2 | **exists.** The controller and its contexts — one of seven built ([ADR 0006](../02-DECISIONS/0006-the-substrate-and-the-control-plane.md)) |
| `mesh-controller` | 2 | **exists.** The controller and its contexts — one of seven built (ADR 0006) |
| `mesh-surfaces` | 3 | tools, web, cli |
| `mesh-sdk` | — | the stable spine modules build against — the tool-serving harness, the messaging/event framework, the contracts and core primitives. Holds nothing per-module and nothing volatile ([ADR 0039](../02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md)). |
| `mesh-sdk` | — | the stable spine modules build against — the tool-serving SDK harness, the messaging/event framework, the contracts and core primitives. Holds nothing per-module and nothing volatile (ADR 0039). |
| `mesh-lab` | — | **exists.** The lab — scenario lifecycle, networking, placement. Ships to nobody; runs on a workstation. |
| `mesh-delivery` | — | the delivery domain: the parts that build, check and deliver a change by watching and writing keys on the bus, nine modules each whole in it, prefixed `mesh-delivery-` (ADR 0429). Made by the forge module from its config (ADR 0428). |
Tier 4's shape is open, and deliberately so: see ADR 0019 and
@@ -47,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. |
@@ -56,7 +57,7 @@ Named by role, because the layout is itself part of the as-is design — see
## Why applications do not live in the monorepo
A standalone application in the monorepo is a convention violation, and reviewers reject it.
The reasoning is recorded in [`02-DECISIONS/0010`](../02-DECISIONS/0015-applications-live-in-their-own-repository.md):
The reasoning is recorded in ADR 0015:
the mesh installs, provisions for, and ships an application through exactly the same machinery
whether or not its source sits beside the mesh's own — so co-location buys nothing and costs
the monorepo's review cadence.
@@ -67,7 +68,7 @@ Each module is a standalone package that consumes its dependencies from the priv
not from a sibling directory. The workspace was removed after it caused build-versus-development
divergence — a workspace member importing another resolved to local unbuilt source in the
pipeline and to a published version in development. Recorded in
- **Areas touched:** every `hal/*` and `noxflow/*` module; the pipeline's dependency
graph; the knowledge base; agent identity and credentials.
## Summary
HAL has 124 modules. That number is not a maintenance problem in itself — it is the
**symptom of missing bounded contexts**. Modules are split not because they model
different domains, but because splitting is the only lever the platform offers:
- no way to run one daemon on one node without making it a module
(`hal/claude-licences` — one daemon, single-node)
- no way to expose two of a kind from one module
- no namespace separating the mesh from the software it runs
This effort establishes the **current state**, the **ideal state**, and the sequence
between them.
## Trigger
A night of debugging that produced four fixes and one conclusion. Every fault was a
boundary fault:
- Per-agent Claude credentials had to be written by the *noxflow runtime*, because
`agents.claude_account` is in noxflow's database — even though agent identity is a
mesh concept and node identity already lives in the mesh registry.
- Whether `hal/brain` may depend on noxflow took three attempts to answer, twice
wrongly, because the ownership boundary was never stated.
- Authoritative documentation existed in `mesh_docs` and was not found, while a
proposal in repo markdown was invisible to search entirely.
## Decisions taken (2026-08-22)
| Question | Decision |
|---|---|
| What should noxflow become? | Decompose into `hal/*` modules; noxflow returns to tasks/workflows |
| Who owns agent identity? | `hal/agents` — a mesh concept, alongside nodes |
| Where do third-party apps live? | Out of this repo. They run *on* the mesh; they are not *of* it |
| Knowledge structure | Modelled on `papa-hq`; implementation choice left open |
## Open questions
Tracked in [`analysis.md`](analysis.md) under "Open questions".
## Deliberately not decided
Recorded so they are not mistaken for oversights. Each is open, and each comes out of
[ADR 0001](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md); this effort stays
`active` until they are answered.
| Question | Status |
|---|---|
| `hal/scheduler` — infrastructure, or part of the work context. | Open. |
| Which context owns the executor. | Open. |
| Catalogue destination — one repository or many. | Open. Phase 4. |
| What the shared library keeps after extraction. | Open. Phase 3. |
| Where human agent modality is recorded — which user, on which node, a human agent acts as. | Open. Required by the model; not yet stored. |
| Which domains the modules outside the platform core group into. | Open, from [ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md), which settles the principle and deliberately not the list. |
Eight contexts instead of 33 platform modules, with the catalogue elsewhere.
The naming corrects itself in the process: what is called "brain" today is
infrastructure, and the word survives only as a concept an Agent owns — never again as a
module name.
This shape depends on **named features with per-node opt-in** — without it, every
independently-deployable unit inside a context becomes a module again and the count
returns. That mechanism is the subject of a separate ADR.
## Decided since
| question | decision |
|---|---|
| Meetings — own context or part of agents? | **Neither.** A meeting is a thread in the record; `hal/stream` absorbs it. The category was wrong. |
| Thoughts — autonomy or agent behaviour? | `hal/agents`. Any agent can have a thought. |
| `hal/axon` vs `hal/cortex` | `hal/cortex` is vestigial — no `daemon/` source, unit inactive on every node, description copy-pasted from axon. Messaging belongs to `hal/stream`. |
| `hal/hypothalamus` | Orphaned build output. A `dist/` directory with no `module.yml`, so not a module at all. |
| Who owns agent identity? | `hal/agents`. Nodes and agents are decoupled; a node is only a place an agent can run. |
| Where do third-party modules live? | Outside this repository. They run *on* the mesh, not *of* it. |
## Open questions
1.**`hal/scheduler`** — infrastructure (fire an event later, belongs to `hal/mesh`) or
part of `hal/work`?
2.**The executor.** Pulling and routing work items is `hal/work`; spawning a session is
`hal/agents`; providing the place to run is `hal/mesh`. It currently straddles all
three, which is the same kind of straddle that put credential-writing in the noxflow
runtime.
3.**Catalogue destination** — one repository, or per-application repositories, given the
pipeline resolves dependencies across the registry rather than the filesystem?
4.**SDK residue** — after extraction, does `hal/sdk` keep transport (`amqp-client`), or
does that belong to `hal/stream`? Everything imports it, which argues both ways.
5.**Human agent modality.** ADR 0001 requires a fact the mesh does not record: which
user, on which node, a human agent acts as. Where does it live — an attribute of the
| human-modality surfaces — brain **in cortex mode**, desktop notifications, desktop environment | on the host, by definition |
| module stacks | already Docker; systemd layer is the redundant part |
This split is not a compromise between the options. It is what the domain model implies,
and it is a decent sign that the model is doing work.
---
## 6. Options, with costs
| | option | cost | what it buys |
|---|---|---|---|
| **A** | **Keep systemd; systemd-in-container for Phase 0** | privileged containers, heavy images, slow iteration; local mesh keeps a shape production does not have | nothing changes in production; smallest change to the mesh |
| **B** | **Drop the `hal-module@` layer only** — let Docker's restart policies supervise stacks directly | reimplement uniform start/stop across ~12 call sites; lose rate-limited restart and pull-failure recovery | removes the redundant layer; does **not** solve Phase 0 on its own, since the daemons still need supervising |
| **C** | **Containerise the mesh daemons; Docker supervises** | container-aware `systemd_journal`/health; host access for daemons that write host files; the human-modality surfaces stay on the host regardless | terminates the fate-sharing recursion without writing a supervisor; makes local and production the same shape; Phase 0 becomes much less of a special case |
| **D** | **Write a mesh-native supervisor** | the fate-sharing recursion (§3), plus matching systemd's maturity — backoff, resource limits, clean SIGTERM (`noxflow/runtime` already depends on `TimeoutStopSec=60`) — on machines that are somebody's daily driver | most "mesh"; least justified by the evidence |
**D is the option the phrasing "more hal mesh approach" points at, and the evidence argues
against it.** Supervision is not a domain concern the mesh is better placed to solve than
the OS; the mesh's distinguishing feature is brokering capabilities, not restarting
processes. C gets the benefit D is reaching for — the mesh not depending on host-specific
init — without the recursion.
**C and B compose.** C is the one that pays for Phase 0.
Worth noting what is *not* in this table: the dozens of `systemctl` call sites that
configure the **host OS's own** units — NetworkManager, resolved, oomd, zram, docker.service,
fail2ban, sshd, zfs, across the vendor-firmware and power modules, `wireguard`, `sshd`, `zfs`
and others. Those are not HAL supervising itself; they are HAL configuring an Arch box. They
are out of scope for every option above and do not go away under any of them.
---
## 7. An incidental finding
Documentation describes an automatic node rescue: `hal-rescue.sh:20` states it is "triggered
automatically by `hal-health.timer` when hal-meshware is failed".
**It is not.** `hal-health.sh` contains no call to `hal-rescue.sh` (checked, zero matches),
and **no unit in the repository declares `OnFailure=`** (checked, zero matches). The only
real triggers are the manual `rescue_node` tool
(`modules/hal/sdk/src/tools/deploy-rescue.ts:77-92`) and running `install.d/rescue.sh` by
hand.
This is worth recording for two reasons. It weakens any argument that systemd-adjacent
self-healing is already wired — it is not. And it is another instance of the pattern this
whole refactor is about: **a documented mechanism that does not exist, believed because it
was written down.** `00-META/how-we-build.md` calls this out as a rule; here it is again,
found by grep.
---
## 8. Open question
**Which supervision model does the mesh adopt?** A, B, C, D or a combination.
**This no longer gates Phase 0.** When this was written, the local mesh was assumed to be
built from application containers, which forced the question — there is no natural way to
run an init system inside one. The decision of 2026-08-22 to build development nodes as
**system containers** (see [`03-DESIGN/01-end-to-end-testing.md`](../../03-DESIGN/01-to-be/01-end-to-end-testing.md))
removes that pressure entirely: a system container runs a real init, so the existing model
works unmodified and the lab needs no answer here to exist.
What remains is the question on its own merits, which is worth keeping open because the
evidence above still holds: option B removes a layer that 44 of 44 module stacks have already
made redundant, and option C would let the mesh stop depending on host-specific init. Neither
is urgent. Both are now cheap to *try*, because there is somewhere to try them.
Option D — a mesh-written supervisor — remains the one the evidence argues against, for the
fate-sharing reason in §3.
## References
- [`002-local-mesh`](../002-local-mesh/analysis.md) — the effort this came out of
- [`02-DECISIONS/0001`](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md) — agent modality, which
decides what cannot leave the host
- `modules/hal/meshware/daemon/src/cerebellum.ts:815-828` — the self-restart workaround
- `modules/hal/meshware/systemd/hal-module@.service` — the per-module Docker lifecycle
reframes it: things that change together share an **authority**, not a package. This effort's own
measurement is what that record rests on — reachability being the *only* place modules genuinely
co-change is why connectivity is a context and why nothing else needed one.
**What to do with the ~50 modules that co-change with nothing** — *nothing.* They are modules.
Grouping is a tag and a query over the graph, neither of which anybody keeps true by hand.
**What remains is a sequencing question, not a grouping one**, and it moves rather than closes:
*whether applications leave the monorepo before or after they group* is
[research 009](../009-migration/00-overview.md)'s, because it is about how to get from here to
there rather than about what the shape is.
## Open (superseded by the above) questions
| Question | Why it is open |
|---|---|
| Whether provider modules group at all, and if so what a consumer's requirement names instead of a module. | The provisioning reference is load-bearing; getting it wrong is expensive. Opinion and evidence in the analysis; not yet decided. |
| Whether applications group into domains now and leave the monorepo later as a unit, or leave first. | Decided in principle — group first, then split — but the migration order has real cost either way. |
| What to do with the ~50 modules that co-change with nothing. | The evidence gives no grouping signal for them at all. That may mean they are correctly sized already. |
| Whether "group or leave" is even the right pair of options. | [Research 006](../006-mesh-from-scratch/code-skeleton.md) finds a third fate — **absorbed into the node host**, ceasing to be a module at all — and argues it is the correct answer for the reachability cluster this effort measured. If so, the cluster this effort found is evidence for absorption rather than for grouping. |
([ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md)). A
correction inherits the frame of the thing it corrects, and two of the mesh's oldest problems
look unsolvable from inside that frame:
- **The bootstrap circularity.** The mesh needs a database, a bus, a registry and an identity
provider. Those are modules the mesh installs. The mesh cannot install them before it exists.
This has been worked around repeatedly and never designed away.
- **Participation requires privilege.** Everything assumes root on a machine whose packages and
services the mesh owns. A phone cannot participate on those terms, and neither can a machine
someone else administers.
Designing from nothing is a way to find out which parts of the current shape are requirements
and which are residue.
**And there is more residue than expected, from a knowable source.** This began as a
**dotfiles repository** — the first two days of history adopt dotfiles, add per-node dotfile
overrides, and introduce service symlinking with an ignore file. The flat one-directory-per-tool
catalogue, linking rather than copying, adoption of already-configured machines, per-node
overrides, and the desktop modules are all inherited from that, not chosen for a mesh. Recorded
in [`03-DESIGN/00-as-is/10-module-catalogue.md`](../../03-DESIGN/00-as-is/10-module-catalogue.md).
That makes this effort's question sharper than "what would we do differently": much of what
looks like design is a generalisation of *place files on my machines*, never revisited because
it was never stated as an assumption.
## The requirements this is designed against
Stated by the operator, recorded here so the skeleton can be checked against them rather than
against taste:
1. The mesh manages multiple computers — **full control**, through modules installed to nodes.
2. Mesh state lives in a **database**: which modules on which nodes, logs, configuration.
3. Configuration has **several touchpoints** — tool surface, web interface, others — all hosted
by the mesh itself.
4. **Connectivity** is core: every node reachable from every other over a shared overlay, some
nodes publicly exposed, firewalls configured.
5. The mesh **hosts applications** — and requires some of them itself. This is the circularity.
6. **Arch Linux only for now**; ideally any device, including phones, on lighter terms.
7. The end goal is to **operate an IT company** on it — development, design, deployment, full
circle, self-hosted. Personal cloud infrastructure.
8. **Agents make it self-improving and self-healing.**
9. It is **end-to-end testable on one machine**
([ADR 0016](../../02-DECISIONS/0016-the-lab.md)).
## Status
A first skeleton exists, with four design moves that the current shape does not have. It is
`active` because two of them are unproven and one contradicts a record that is already
accepted.
**Finding worth stating up front:** [ADR 0001](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md)
names nine bounded contexts and **none of them owns connectivity** — no overlay, no resolution,
no firewall, no ingress. Requirement 4 has no home in the accepted decomposition, while
[research 005](../005-domain-grouping/analysis.md) found reachability to be the *only* part of
the catalogue where modules genuinely change together under one intent. The skeleton adds it.
## Open questions
| Question | Why it is open |
|---|---|
| Does the record — the event log contexts integrate through — belong to the substrate or the control plane? | It is infrastructure by shape and domain by content. Placing it wrong reintroduces a circularity. |
| One repository per tier, or per context? | Already open from ADR 0001 as "catalogue destination — one repository or many". The skeleton assumes per tier and does not settle it. |
| ~~Does an unprivileged node earn a place in the inventory, or only a presence?~~ | **Answered 2026-08-25** by the operator: a node is a *managed machine inside the mesh*, not an unprivileged something — and a disconnected node is still a node, in a different situation. The question posed a class distinction; the answer is that there is none, and what varies is **state**. Recorded as [ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md). |
| ~~Does absorbing overlay, filtering, packages, supervision and the container runtime make the host too large?~~ | **Answered 2026-08-25** — [`host-size.md`](host-size.md). Measured: the absorption is smaller than the machinery that already applies state, and eight of ten adapters already carry no dependency. The risk is not size but direction, and it is two modules wide. The claim survives with its scope corrected — the host carries one concern, *apply declared state on this machine*, of which the six are instances. Recorded as [ADR 0005](../../02-DECISIONS/0005-the-node-host.md), designed in [`05-the-node-host.md`](../../03-DESIGN/01-to-be/05-the-node-host.md). |
| ~~Four substrate services or five?~~ | **Answered conditionally**, which is the honest form — [`07-the-foundation.md`](../../03-DESIGN/01-to-be/07-the-foundation.md). The substrate is *what the control plane consumes and cannot grant itself*. The identity provider qualifies only if the control plane delegates authentication; if it authenticates natively it is an ordinary hosted service. The count follows from a decision not yet taken, and asserting four was asserting that decision. |
| Does `feature` survive? | The skeleton splits it in two and argues the conflation is what makes the delivery pipeline hard to reason about. Unproven. |
**Today's mesh assumes the second state from the first moment.** Its source, its packages and
its images are all expected to be self-hosted before there is anything to host them — which is
why raising a first node needs a script that exists solely to paper over the impossibility, and
why that script is the least-exercised path in the system.
Making the transition explicit has a second benefit: it is reversible. A mesh whose forge is
broken can re-bind delivery to external providers and keep improving itself while it repairs
the forge. Today that escape hatch does not exist, because the dependency is not expressed
anywhere it could be changed.
### So, concretely
One `gitea` module. One image-registry module. One package-registry module. Each a tier-4
workload. The mesh's own instances are distinguished from any other instance **by what they are
bound to, not by being different modules** — precisely the same answer as postgres, arrived at
by the same test.
## The five fates of a module
Research 005 asked whether a catalogue module should be **grouped into a domain** or **leave
the repository**. Working the tier test across the catalogue surfaces a third answer that
neither option covers, and it is the most common one.
| Fate | Means | Examples from today |
|---|---|---|
| **Absorbed into the host** | It is not a module at all. It is part of what "managing a machine" means, and belongs in tier 0. | overlay membership, packet filtering, package management, service supervision, container runtime, filesystem management |
| **Substrate** | The control plane cannot exist without it. Pinned, host-applied. | relational store, bus, object store, image registry |
| **Control-plane context** | It decides something across nodes. | connectivity policy, inventory, delivery, provisioning, observability |
| **Workload module** | The mesh hosts it. Grouped per [ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md). | media library, desktop session, collaboration tooling |
| **Leaves the repository** | A standalone application, per [ADR 0015](../../02-DECISIONS/0015-applications-live-in-their-own-repository.md). | the applications identified in research 005 |
**The first fate is the finding.** Research 005 measured the reachability cluster — proxy,
resolver, firewall, overlay — as the only place in the catalogue where modules genuinely change
together under one intent. The skeleton explains *why*: they are not four modules that ought to
be one domain module. They are four facets of one thing the host should own, currently
expressed as modules because a module was the only unit available.
Under this skeleton the overlay module and the firewall module **stop existing**. The host holds
membership and applies filtering; tier 2 decides the policy; the swappable backends stay
modules. That is a different and better answer than grouping them, and it was not visible from
inside the current frame.
It also partly answers research 005's other open question — the fifty modules that co-change
with nothing. Several are host concerns rather than domains: package management, container
runtime, filesystem tooling. Silence was the right signal after all; the wrong conclusion was
that grouping was the only available fix.
## What a module looks like on disk
Per [`skeleton.md`](skeleton.md) Move 4, a module declares **parts** — independently selectable
pieces of desired state — and produces **artifacts** — things built once per version.
```
<module>/
module.yml identity, what it provides, what it requires,
<domain>/ grouped per ADR 0022, list per research 005
mesh-lab/ the whole mesh, disposable, on one machine
mesh-sdk/ contracts shared across tiers — types, not behaviour
hq/ company-scoped, not a mesh repository — ADR 0019
```
## The dependency rule
**A tier may depend only on tiers below it.** Substrate never references the control plane.
The control plane never reaches into a node except through the host. A surface holds no logic
a second surface would have to reimplement.
This is the whole of the bootstrap answer, and per this repository's own rule it must say how
it is checked: a dependency-direction lint in the build, failing on an upward import. A tier
rule enforced by intention is the same as no tier rule — that is
[ADR 0010](../../02-DECISIONS/0010-delivery.md) applied to architecture.
## Move 1 — the substrate is applied, not delivered
**The problem.** The mesh needs a database, a bus, an object store and an image registry.
Today those are modules, and modules are installed by the delivery pipeline, which
needs the database and the bus. The first node is therefore raised by a special script that
exists only because of the circularity, and every later change to the substrate has to pretend
the circularity is not there.
**The move.** The host can apply a declaration without anyone telling it to. The substrate is
a **pinned bundle** the host carries: a fixed, versioned, self-contained descriptor of the
four services and nothing else. Raising a first node is `host apply substrate.lock` — not a
special path, just the ordinary one with no control plane on the other end.
The circularity disappears rather than being worked around: **the substrate is applied by tier
0, the mesh is delivered by tier 2, and they are different mechanisms on purpose.**
The price is real and should be named: the substrate is upgraded by bumping a pin and
re-applying, not by the pipeline. It gets less machinery than everything else — no per-node
selection, no provisioning, no fan-out — and that is the point. Five services justify a
simpler mechanism than a hundred.
## Move 2 — the host is one binary with capability profiles
**The problem.** Everything assumes root on a machine whose packages, services and network the
mesh owns. A phone cannot offer that, and neither can a work laptop. The current answer would
be a lightweight fork, which means two implementations and one of them rotting.
**The move.** One host binary, and a **profile** it detects rather than is told:
| Profile | Can | Typical |
|---|---|---|
| `managed` | packages, services, network, filesystem — the full surface | a machine the mesh owns |
| `user` | user-level services and tools; no package or network management | a shared or administered machine |
| `edge` | report presence, relay, expose a tool surface; hold nothing | a phone |
A module declares which profiles it can land on. Assignment to an incapable node fails at
declaration time, not at deploy time — a phone is not a machine that fails to install a
firewall; it is a node the firewall module cannot be assigned to.
This makes the phone case a **capability question rather than a platform question**, which is
what keeps it from becoming a second implementation. It also removes the current unstated
assumption that every node is equivalent — already false, and today handled by remembering.
## Move 3 — connectivity becomes a context
[ADR 0001](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md) names nine contexts
and none of them owns the overlay, the resolver, the firewall or the ingress. `config` owns
PKI, which is the closest thing, and it is not close.
Meanwhile [research 005](../005-domain-grouping/analysis.md) measured the whole catalogue and
found that reachability is the **only** place where modules genuinely change together under one
intent — the proxy with the resolver, the firewall with the overlay, repeatedly, because *how a
node is reachable* is one question asked in four places.
So the evidence and the gap point the same way. `connectivity` owns:
- the overlay every node joins, and the addresses on it
- name resolution, internal and public
- exposure — which services answer from outside, on which names
- filtering — what may reach a node at all
- certificates for both name spaces
This is an addition to an accepted record, so it is a decision, not a drafting choice. It
belongs in a new record that extends ADR 0001 the way
[ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md) does —
not written here.
### Where the networking actually lives
A context is an authority, not a running thing, so naming one does not say who brings the
overlay up. That splits three ways, and the split is the design:
| Concern | Tier | Why there |
|---|---|---|
| **Overlay membership** — this node joins, holds an address, keeps the tunnel up | **0, in the host** | Everything cross-node needs it *before* the substrate is reachable from elsewhere. A module cannot provide it, because installing a module is itself a cross-node operation. |
| **Policy** — who holds which address, what resolves, what is exposed, what is filtered | **2, `connectivity`** | Bookkeeping and authority. It decides; it runs nothing. |
| **Machinery** — resolver, reverse proxy, firewall backend, certificate issuance | **4, modules** | Swappable, and not every node needs them. A node without a reverse proxy is still a node. |
There is a second circularity hiding here, and it has to be closed explicitly: **the host's link
to the control plane does not run over the overlay.** If it did, the overlay would have to be up
before the host could be told how to join it. The link is ordinary outbound internet to a public
endpoint; the overlay carries node-to-node traffic only.
Joining is therefore: host lands → links out with a join token → control plane returns an
address and keys → host raises membership → the substrate on other nodes becomes reachable.
This also makes the `edge` profile honest rather than special-cased. A phone can hold overlay
membership in userspace without privilege, and cannot run the machinery. That is the profile
distinction doing its job.
## Move 4 — `feature` splits in two
The invitation was to check whether the concept survives. It does not, in one piece.
Today a **feature** means both *a thing built once* and *a thing selected per node*, and the
delivery pipeline is hard to reason about precisely because those have different cardinality
and one word ([ADR 0010](../../02-DECISIONS/0010-delivery.md)
is the pipeline half of the same confusion).
Split it:
| Concept | Is | Cardinality |
|---|---|---|
| **artifact** | something built and published — an image, a bundle, a package | once per module version |
| **part** | an independently selectable piece of a module's desired state | chosen per node, per assignment |
A module declares desired state in parts, and produces artifacts. An assignment names the node
and the parts. Delivery builds artifacts once and applies parts per node — and the two words
now carry the two cardinalities that the pipeline already has.
This keeps what features are genuinely for — per-node opt-in of *some* of a module, which the
work breakdown already calls for — and drops the conflation that makes the current model
confusing.
## What the mesh is, versus what it hosts
Tiers 0–3 are the mesh. Tier 4 is everything it carries, and the boundary is stated by
requirement rather than by taste: **a module is part of the mesh if removing it stops the mesh
managing nodes.** A media server does not. A relational store does — which is why it sits in the
substrate and not the catalogue, despite being, in every other respect, an application like any
other. An identity provider, notably, does **not**: the control plane authenticates its own
callers, so identity is a hosted service like the media server.
That test also settles the IT-company goal without a special category. Development, design and
deployment tooling are **workloads** — tier 4, hosted, provisioned, delivered like anything
else. The mesh does not grow a "company" feature; it hosts the tools a company runs on, and
the fact that it runs its own development on them is dogfooding, not architecture.
## What agents are, structurally
Self-improvement and self-healing are not a tier. Agents are participants
([ADR 0003](../../02-DECISIONS/0003-agents-are-persistent-employees.md)) that hold identity in
tier 2, act through tier 3 like any other caller, and run as workloads in tier 4.
This matters for one reason: **an agent must not have a privileged path**. Anything an agent
can do to the mesh, a person can do through the same surface, and anything it cannot express
through the tool surface is a gap in the surface rather than a reason for a back door. Self-
healing built on a private channel is unreviewable, and would be the one part of the mesh with
no human checkpoint.
## How this is tested
The lab ([ADR 0016](../../02-DECISIONS/0016-the-lab.md)) raises the
tree above on one machine: virtual machines as nodes, a real overlay between them, the real
substrate bundle, the real control plane, the real delivery path.
The tier rule is what makes that affordable. A scenario needing only tiers 0 and 1 is one
virtual machine and a pinned bundle — which is also, exactly, the bootstrap path. **The
hardest thing to test becomes the cheapest scenario to run**, and the first-node path stops
being the one thing nobody exercises until it breaks.
## What this skeleton does not answer
- Where the record lives. It is infrastructure by shape and domain by content, and putting it
in the substrate risks recreating a circularity in the one place the design just removed one.
- Whether tier 2's contexts are one repository or several. Open from ADR 0001 already.
- Whether an `edge` node is in the inventory or merely present — which decides whether "node"
is one concept or two.
- The migration. Nothing here says how today's mesh becomes this, and the skeleton is worth
little until that is costed.
## A naming near-miss, recorded
The tier-0 binary was first called `mesh-agent`, because "node agent" is the reflex everywhere
else in the industry. That is wrong here, and wrong in the specific way
[`how-we-build.md`](../../00-META/how-we-build.md) §4 exists to catch: **Agent** is a
first-class concept in this mesh — a participant, some of whom are human, holding identity and
memory ([ADR 0003](../../02-DECISIONS/0003-agents-are-persistent-employees.md)). One document
carried both meanings.
It is the same failure as the anatomy naming in the current runtime: an evocative domain word
pointing at infrastructure.
[ADR 0001](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md) supplies the fix in
its own title — *the mesh brokers capabilities; nodes host; agents think.* Three verbs, three
components: the control plane **brokers** (`mesh-control`), the tier-0 binary **hosts**
(`mesh-host`), the participant **thinks** (`agents`, untouched).
`mesh-node` was the alternative and was rejected: *Node* is the aggregate in the inventory — the
record of a machine — while the binary is what runs on it and does the hosting.
Provisioning is the mechanism the whole mesh rests on: a module declares what it needs, and the
mesh makes it exist, generates the credential, records the grant, and puts the values where the
module will read them. [ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md)
calls it the mesh's core concern rather than its plumbing.
[Research 006](../006-mesh-from-scratch/code-skeleton.md) then asks it to carry **more**: the
control plane becomes a consumer with its own requirements — a source of record, an image
registry, a package registry — satisfied by the same mechanism. That generalisation is only
safe if the mechanism is sound, and the as-is record says it is not, in named ways.
## Why now
Four weaknesses are already documented in
[`03-DESIGN/00-as-is/03-provisioning.md`](../../03-DESIGN/00-as-is/03-provisioning.md), each
observed rather than theorised:
- **Rotation has no fan-out.** A shared credential can be rotated without telling the peers
holding the old one. This has locked the mesh out of its own broker.
- **A grant is not a check.** The record says a resource was provisioned. Nothing verifies it
still exists, still has that credential, or is reachable from where the consumer runs.
- **A frozen password outlives its generation.** A generated secret written once diverges from a
persistent data directory initialised earlier, and presents as an authentication error.
- **No requirements is indistinguishable from provisioning that did not run.** A module that
declares nothing skips the stage, which is correct, and looks identical to failure.
Generalising a mechanism with these properties to the control plane's own dependencies would
make each of them fatal rather than annoying.
## The questions
| Question | Why it matters |
|---|---|
| What does a **grant** mean, exactly — a record that a resource was created, or a claim about the world that is continuously reconciled? | The difference between the current model and one where "provisioned" is checkable. Almost every weakness above is a symptom of the first answer. |
| How is a credential **rotated** with fan-out to every holder? | The mechanism grants easily and regrants not at all. This is the most damaging gap and it has taken the mesh down. |
| Can the **control plane** hold requirements, and what satisfies them before anything is installed? | The generalisation research 006 needs. Ties directly to the self-hosting transition. |
| What happens when a requirement **cannot** be satisfied — no provider, provider on an unreachable node, provider not yet installed? | Today this is silent or a stall. It should be a stated, visible state. |
| Does a requirement belong to a **module** or to one of its **parts**? | Research 006 splits `feature` into artifact and part. A part-scoped requirement means a database is not provisioned where the part that needs it is not installed. |
move one level up: the control plane holds what source exists and what has been built, and builds
the difference. **An event makes it fast; nothing makes it necessary.** The failures this effort
catalogued — a truncated commit list, a broken path match — become latency rather than silence.
**What is a deployed state?** — *Two comparisons, not an event.* Does every node's reported state
match what is declared, and is what is declared built from current source? A milestone can be
claimed by something that did not check; a comparison cannot.
**What produces a verdict, and what is it about?** — *An artifact, and it gates eligibility.* The
mesh must not converge onto something broken, so an artifact may be declared only once the lab
has judged it fit. Sharper than the question expected: a verdict is a property an artifact has,
not a report about a run.
**How does delivery work before self-hosting?** — *It mostly stops being a question.* A reconciler
reads source and writes artifacts; where those live is a binding, external first and internal
later. The transition looked hard because a pipeline's stages name their targets.
## What this effort was right about
Its first question — *what is a deployed state, and how does the mesh know it is in one* — was
marked "everything follows from this", and everything did. Both records above are answers to it:
0058 makes the applier the reporter, and 0063 makes currency a comparison. The effort put the
load-bearing question first.
## What is NOT closed by this
[ADR 0010](../../02-DECISIONS/0010-delivery.md) names four costs
and one of them is a real risk rather than a trade: **a reconciler that cannot reach its target
retries forever, and without something that notices, the failure is silence** — which is the
fault this effort exists to catalogue, reintroduced in a new place. That belongs to observability
and it is not designed.
## The questions (all answered above)
| Question | Why it matters |
|---|---|
| What is a **deployed state**, and how does the mesh know it is in one? | Everything follows from this. If a stage reports transport, "deployed" is a claim nobody checked. A desired-state model with reconciliation gives a different answer from a job-completion model. |
| Does the coordinator dispatch **stages**, or converge nodes on a **declaration**? | The current model is a state machine over stages. The alternative is that a node is told what should be true and reports what is. The second makes drift visible; the first cannot see it. |
| How does a change **become** a pipeline, reliably? | Detection has failed for reasons unrelated to the change, silently. |
| What produces a **verdict**, and what is it a verdict about? | Ties to the lab ([ADR 0016](../../02-DECISIONS/0016-the-lab.md)) and to a module carrying its own assertions. |
| How does delivery work **before self-hosting**, and across the transition? | From research 006: source and artifacts start external and are re-bound to internal providers. The coordinator has to be indifferent to which. |
| Does the **three-silo** split survive the artifact/part split? | [ADR 0010](../../02-DECISIONS/0010-delivery.md) is cardinality-driven, and research 006 renames the thing the cardinality is about. |
The migration appears to need exactly the capability the design declared it would not have.
The way out, to be tested: the new mesh does not adopt anything. It **declares** the workloads
from scratch and points them at data directories that already exist. Nothing inspects a running
machine to learn what is there; the declarations are written from the as-is layer, which is what
that layer is for. Data survives because it was never touched, not because it was adopted.
If that holds, adoption stays out of scope and the migration is ordinary declaration. If it does
not, adoption needs a one-time, explicitly unsupported tool, and that should be a decision rather
than a discovery.
## Sequencing
| Phase | What | Done when |
|---|---|---|
| **0** | **Build the lab's bootstrap scenario** ([ADR 0016](../../02-DECISIONS/0016-the-lab.md)) — virtual machines, a network, a way to place a binary, snapshot and reset. No forge, no coordinator, no pipeline. | A machine can be raised from nothing, reset, and raised again, repeatably. |
| A | Build tier 0, **inside the lab**. The host's interface first — it carries the skeleton's biggest unproven claim. | A bare machine becomes a managed node with no mesh present. |
| B | Build tier 1 and 2. The bootstrap scenario grows into the full one by addition — the same machines, with more placed inside them. | The lab raises a full mesh from nothing, repeatedly, from pinned external artifacts. |
| C | Enough of tier 3 to operate it. | The mesh can be driven without direct database access. |
| D | Declare the existing workloads against the new model. | The lab runs them, with copies of real data shapes. |
| E | **Rehearse the cutover in the lab** against a mesh built to resemble the real one. | Repeatable, and repeatably reversible. |
| F | Cut over. | The real nodes are managed by the new control plane. |
| G | Reach self-hosting — re-bind delivery from external providers to the mesh's own forge and registries. | The mesh builds and deploys itself. |
Phase G is deliberately last. Per research 006, self-hosting is a state the mesh **reaches**;
attempting the cutover and the self-hosting transition in the same move recreates exactly the
circularity the skeleton removes — and would mean a failed cutover could take away the means to
fix it.
## The questions
| Question | Why it matters |
|---|---|
| What state must **survive** the cutover, versus be re-created? | Workload data must. Provisioned credentials could be re-issued. The mesh's own inventory could be re-declared. Each answer changes the risk. |
| What is the **way back**? | A cutover with no rollback is not a plan. If workload data is untouched, reverting may be as small as re-pointing the old control plane at it — to be verified, not assumed. |
| How is the cutover **rehearsed** against something resembling the real mesh, without copying the real mesh into a repository? | The lab must be able to model the real topology's shape without carrying its identity. |
| Does anything have to keep running **during** the cutover? | Mail and source are the obvious candidates. If yes, "big-bang" is really "big-bang with exceptions", and the exceptions should be named now. |
| Is the forge inside or outside the cutover? | If the mesh's own forge goes down with the old control plane, the means of deploying a fix goes with it. This is the self-hosting circularity appearing as a migration risk. |
[The lifecycle design](../../03-DESIGN/01-to-be/03-scenario-lifecycle.md) closes on an open
question that is measurable rather than arguable:
> **What a snapshot costs.** Whole-scenario snapshots of several machines are the operation the
> inner loop repeats most, so their cost sets the loop's speed. If restoring is slow, the loop
> is slow, and everything above is theory.
Measured on a workstation, 2026-08-24. Numbers in [`measurements.md`](measurements.md).
## Why it matters
[ADR 0016](../../02-DECISIONS/0016-the-lab.md) makes the
bootstrap scenario the inner development loop for tiers 0 and 1 — the argument being that
raising a node from nothing stops being the least-exercised path and becomes the most-exercised
one. **That argument is only true if raising and resetting are cheap.** A loop that costs
minutes is a loop people avoid, and the least-exercised path stays least-exercised.
## Status
Measured, and the finding is a blocker rather than a data point.
**A snapshot on the current host is a full copy of the machine's disk.** 1.6 GB and ten seconds
for one small virtual machine at best — and over two minutes when observed a second time. Cost
scales with the number of machines and the size of their disks, not with what changed.
**With copy-on-write it is 0.13 seconds and costs the delta.** Verified, not assumed. The
projected four-machine reset cycle falls from roughly ninety seconds to roughly fifteen, of
which almost all is a boot that cannot be avoided.
The cause is not virtual machines and not incus. It is that the host offers incus exactly one
storage driver, `dir`, which has no copy-on-write and therefore no cheap snapshot. The kernel
supports btrfs; the userspace tool that would let incus use it is simply not installed.
So the question *"is the lab's inner loop fast enough"* currently answers itself the wrong way,
for a reason that is one declared package away from being fixed — and declaring packages is
something the mesh already does.
## Open questions
| Question | Why it matters |
|---|---|
| ~~How much does a copy-on-write pool actually improve it?~~**Measured: snapshot 9.9 s → 0.13 s, restore 10.4 s → 0.80 s, three snapshots sharing 1.36 GB rather than costing 4.8 GB.** The projected four-machine cycle falls from ~90 s to ~15 s. | Answered. The inner-loop argument holds *with* copy-on-write and did not without it. |
| How does the lab install its own prerequisites on a clean machine? | The lab needs a virtualisation daemon, copy-on-write tooling and a pool before it can do anything — and it cannot depend on the mesh for them, since it is where the mesh is built. |
| Why was the second snapshot more than twelve times slower than the first? | If snapshot cost is unpredictable rather than merely high, that is worse — a loop with a variable multi-minute step is one nobody trusts. |
| Does a scenario snapshot need the machines stopped? | Stateless snapshots of a running virtual machine capture the disk but not memory. Whether a mesh restored that way is coherent is not established. |
| What is the cost at scenario scale — four machines rather than one? | Only single-machine numbers were taken. If the operation is serial, four machines is four times the wait. |
Taken 2026-08-24 on a workstation with hardware virtualisation available, an NVMe-backed ext4
root, and 300 GB free. One virtual machine, 1 GiB memory, 2 CPUs, from a cached distribution
image.
## The environment, before anything ran
| Fact | Value | Consequence |
|---|---|---|
| Hardware virtualisation | present | virtual machines run at native speed; the choice in [ADR 0016](../../02-DECISIONS/0016-the-lab.md) is not paying an emulation penalty |
| Storage drivers the daemon offers | **`dir` only** | no copy-on-write, therefore no cheap snapshot |
| Host filesystems | ext4 throughout | nothing copy-on-write to put a pool on |
| btrfs kernel module | **available** | the kernel can do it |
| `btrfs-progs` | **not installed** | which is the entire reason the driver is absent |
The last two rows are the finding. The daemon advertises only `dir` because the userspace tool
for anything better is missing — not because the host cannot do better.
## Raising a machine
| Step | Time |
|---|---|
| launch call returns | **3.4 s** |
| machine actually usable — a command executes on it | **14.3 s** |
The gap matters for the lifecycle design: `raise` returning is not the same as the scenario
being ready, so the verb has to wait for the second number, not report the first. Reporting
the first would be the mesh's own recurring failure — transport reported as effect.
## Snapshot and restore
| Operation | Time | Disk |
|---|---|---|
| snapshot, first | **9.9 s** | **+1.6 GB** |
| snapshot, second | **> 120 s — did not complete** | — |
| restore call returns | **10.4 s** | — |
| machine usable again | **20.1 s** total | — |
Instance on disk before snapshotting: 1.5 GB. Snapshot directory afterwards: 1.6 GB. **A `dir`
snapshot is a full copy** — the storage cost equals the instance, and nothing is shared.
Implied copy throughput on the first snapshot is roughly 160 MB/s, which is far below what the
underlying NVMe can do and is consistent with a real, durable copy rather than a metadata
operation.
**The second snapshot is the more troubling number.** It exceeded two minutes and was still
running when the observation was cut off; only the first snapshot exists. Whatever the cause —
page cache exhausted by the preceding restore, writeback contention — the practical
consequence is that snapshot cost here is **not merely high, it is unpredictable**.
## What this projects to
A four-machine scenario, taking the optimistic single-machine numbers and assuming the
operations are serial:
| | one machine | four machines |
|---|---|---|
| raise, to usable | 14 s | ~57 s |
| snapshot | 10 s, 1.6 GB | ~40 s, 6.4 GB |
| restore, to usable | 20 s | ~80 s |
A reset-and-rerun cycle is therefore **around a minute and a half at best**, and unbounded at
worst, before any of the mesh's own work begins.
## The judgement
**This is too slow for an inner loop**, and the reason is not the design.
[ADR 0016](../../02-DECISIONS/0016-the-lab.md) argues that
making the bootstrap path the inner development loop turns the least-exercised code in the
system into the most-exercised. That argument holds only while resetting is cheap. At a minute
and a half a cycle, with occasional multi-minute stalls, the loop is one a person works around
— and the path stays under-exercised for exactly the reason it always was.
Nothing about virtual machines causes this. Hardware virtualisation is present and the machines
boot in fourteen seconds. **The cost is entirely the storage driver**, and the driver is absent
because one userspace package is not installed on the host.
The mesh already has the mechanism for that: a module declares a package, and a hook makes it a
working capability — which is precisely what was just done for the virtualisation daemon
itself, and what [`04-ISSUES/007`](../../04-ISSUES/007-an-installed-package-is-not-a-capability/00-report.md)
is about.
## The fix, measured
The comparison was subsequently run. One package — `btrfs-progs`, no dependencies — installed by
hand, the daemon restarted so it re-detected drivers, a copy-on-write pool created on a loop
file, and the identical image launched onto it.
| Operation | `dir` | copy-on-write | |
|---|---|---|---|
| snapshot | 9.9 s, then **> 120 s** | **0.13 s** | ~76× faster, and *consistent* |
grouping modules by domain. [Research 005](../005-domain-grouping/analysis.md) measured that
proposal and found its evidence holds in exactly one place — reachability — which
[ADR 0005](../../02-DECISIONS/0005-the-node-host.md) has since absorbed
into the host. The measured case for domain grouping has therefore been consumed by a decision
taken for unrelated reasons, and what remains is fifty modules that co-change with nothing.
That leaves the original complaint unanswered: the catalogue records **what was installed**
rather than **what anything is for**, and nothing in the system can see a relationship between
two modules. Grouping asserts relationships. A graph records them.
## Why now
A proposal to split modules into *provisioning services* and *applications* was worked through
and abandoned in favour of one concept with facets, for a reason worth keeping:
- The split cannot be filed consistently. A git forge is consumed as a service *and* operated
through a web interface. An analytics service grants tracking identity *and* is a dashboard
somebody reads. An identity provider grants authentication *and* has an admin console.
- The operator's correction is the sharper form: **what runs on the machine is a supervised
container, not something a user started.** That is a fact about *how a thing runs*, not about
what kind of thing it is — so it is a facet, not a taxonomy.
Filing decisions that follow from nothing are the disease research 005 measured. A second
taxonomy would reproduce it.
So [ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md) survives, and the question
becomes what a module must be able to **declare**.
## The shape being investigated
Five declarations, of which two exist today.
| Declaration | Today | Notes |
|---|---|---|
| **requires a resource** — a database, a bucket | yes | provisioning, [ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md) |
| **provides a resource** | yes | as above |
| **requires another module** | **no** | the dependency edge — the graph's substance |
| **excludes another module** | **no** | installing A makes B unavailable |
| **requires a node capability** | **no** | a graphical session, a container runtime, an architecture |
And one structural idea on top: **an interface module carries no implementation.** Adapters
provide it. An assistant interface with several model-provider adapters; a terminal interface
with several terminal adapters. A dependent names the interface and never an implementation.
**Prior art to measure against, not invent past.** This is a package manager's model, and the
platform's own package manager already has all of it: `depends` is the dependency edge,
`conflicts` is exclusion, and `provides` is the interface — several packages provide one
virtual name, and a dependent names the virtual one. That the design arrived at the same shape
independently is evidence for it. It is also a warning: dependency resolution, version
constraints, conflict handling and rollback are a long-solved and easily-botched problem, and
the effort should establish what to **delegate** rather than reimplement.
## Capabilities, and what may be installed
The operator's formulation: *system specs are capabilities, and capabilities unlock installable
modules — you cannot install a graphical application on a node with no display server.*
The question that follows is whether the mesh may install a capability. The effort's working
position, to be tested:
- **Intrinsic capabilities** — hardware, architecture, network position — are facts about a
machine. They are detected, never installed, and a module requiring one it does not have is
not unresolved but **impossible** on that node.
- **Provided capabilities** — a display server, a container runtime — are not a separate kind
of thing at all. They are modules that provide a capability, and requiring one is an ordinary
edge the graph resolves by installing it.
If that holds, "may the mesh install a capability" is not a policy question. It is dependency
resolution, and the only genuinely new thing is detection.
Which is where [issue 007](../../04-ISSUES/007-an-installed-package-is-not-a-capability/00-report.md)
bears directly: *an installed package is not a capability*. A provided capability is not real
because a package is present — it is real when it is present, running and working, and the
difference is exactly the class of fault this repository keeps recording.
## What it touches beyond the catalogue
The operator's assessment is that the machinery around a module is wanted and its integration
is not: **scheduled tasks, hooks, migrations, configuration and environment settings are worth
keeping; seeds are not; and the current integration is wrong enough to need a major refactor.**
That is a claim to test rather than adopt. Research 005 already found supporting evidence from
a different direction — that the densest apparent coupling in the catalogue is manifest
boilerplate churn, cross-cutting changes to the machinery applied N times — which is what an
integration being wrong looks like from the outside.
## Open questions
Struck-through rows are answered, with where. The rest are live.
### Settled
| Question | Answer |
|---|---|
| ~~What does the graph **delete**?~~ | For the existing system: nothing, it is already there ([`analysis.md`](analysis.md)). For the design: the module/resource distinction, the interface as a kind of thing, capability checking as a separate mechanism, domain grouping, and — the first clear deletion — **grant kinds**, once a module may only be granted what it exclusively owns ([`worked-provider.md`](worked-provider.md)). |
| ~~Is an interface a module, or a name?~~ | A **name**, and only where providers are genuinely substitutable. The adapter is what creates one; without an adapter there is a **tag**, which describes and does not bind ([`proposal.md`](proposal.md)). |
| ~~Where do domain modules fit?~~ | They do not. There is core infrastructure — concrete modules named individually, not flavourable, nothing standing in front of them. |
| ~~What happens to domain grouping?~~ | Superseded. Folders assert relationships; edges record them. What grouping was for is a tag and a query. [ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md) is `proposed` and should be superseded rather than narrowed. |
| ~~Is there one kind of edge?~~ | **No — two.***Presence*, where a thing must exist, and *instantiation*, where a provider makes something for a consumer and hands back credentials. Instantiation implies presence, not the reverse. |
| ~~When two modules provide one name, who chooses?~~ | Neither the consumer naming a node nor the consumer not caring. The consumer declares the **scope of its own need** — shared across its instances, or one each — the mesh binds, and the binding is written down and sticky. Where it is written follows the scope. |
| ~~Can several modules share one database?~~ | **No.** A module is granted only what it exclusively owns — no shared writes and no read role on another's store, because reading couples you to its layout just as firmly. |
| ~~What about a dashboard reading a dozen stores?~~ | **The rule is about contexts, not processes.** The mesh's own board reading the mesh's own store is the mesh showing its own data — not a boundary crossing. Everything inside a context reads its store freely; what is forbidden is a *different* context reading it. An earlier answer here was wrong. |
| ~~Can every registry consumer be served another way?~~ | **Largely dissolves.** Of eighteen direct consumers, the owner keeps its database, node appliers are already stopped by ADR 0005, and the bulk are **foreign tenants** — thirteen tables across three contexts — who need to move out rather than read differently. |
### Live
| Question | Why it is open |
|---|---|
| How many instances should a module have? | Not derivable and not global: one-per-mesh is right for the broker and wrong for a store a disconnected node needs. It is per-module and nothing in the schema says it. |
| Can two of something coexist? | `excludes` covers part of it. Two terminals are fine, two things wanting one port are not, two brokers might be either. |
| What does a provider hand back? | Credentials and an address for a store; a command for a terminal. Same relation, different shape crossing it. |
| Is provisioning one mechanism or two? | The mesh's own registry is provisioned **before there is a mesh**, so provisioning is part of the bootstrap and part of what the carried bundle expresses. At bootstrap the store is local; afterwards it is on another node. Same operation, both sides of a tier boundary. |
| Is a tool surface one relation with two audiences, or two? | 56 of 126 modules carry tools — more than carry a service — and what consumes them is an **agent**, not a module. |
| ~~Do the remaining cross-context reads want an interface or events?~~ | **Derived, not chosen.** Neither is SQL — that only ever runs against your own store. ADR 0004 makes disconnection ordinary, so anything that must work while disconnected cannot use a request and needs a local copy: a subscription. Anything where a stale answer is worse than none cannot use a subscription. |
| What does a consumer do about events it missed while disconnected? | Replay from a point, ask once for a full picture and resume, or rebuild. The question every projection has, and unanswered here. |
| What happens to a grant when its consumer is removed? | Dropping is data loss; keeping is a leak. ADR 0005's removal rule does not obviously carry, because the thing lives inside another module's state. |
| Is a declaration composed per node, from what that node reported? | Some configuration follows the hardware. Either the host fills a blank — deciding, against ADR 0005 — or the control plane composes from the node's inventory first. |
| Would `excludes` and capability requirements actually be used? | Zero manifests declare either, which is equally consistent with *nobody needs them* and *nobody can express them*. |
| What does an exclusion mean for something already installed? | Refuse the install, or surface the conflict and let it be decided. |
| Are tiers a view of the graph, or a constraint on it? | If a tier is a computed level the word is a convenience. If *a tier may depend only on tiers below it* is to be enforced, it is a constraint and must be stated as one. |
| Where does resolution happen — the mesh, or the platform's package manager? | The mesh must model mesh-level edges. Whether it also resolves operating-system packages decides whether a solver gets written. |
| How far may the control plane be split? | A single board over several contexts works because they are contexts *inside* one control plane with one interface. If a context becomes its own deployable with its own interface, the board is coupled to N of them and the composition has nowhere to live that tier 3 permits. A constraint on splitting, worth knowing before splitting. |
| What does the pipeline schedule, once features are gone? | It schedules features today. The four categories they split into have different lifecycles, so the unit of work differs for each and needs naming. |
| Should placement leave the catalogue? | A provision pins itself to a named node in the manifest. Placement is an inventory decision, and having it in the catalogue means a second node cannot provide the mesh's store without editing its consumer. |
One module, worked out completely, because it is the case that breaks the tidy version. It
looks like *a container that runs a database* and it is at least nine things.
Postgres is the example. **The shape is not specific to it** — see the end.
## What it carries
**1 — A supervised container.** An image, a version, a data volume, and configuration. Easy,
and the only part the phrase "a docker service" describes.
**2 — Persistent state, and where it lives matters.** The volume is the database. Moving this
module between nodes is not rescheduling; it is a migration. Almost nothing else in the
catalogue has this property, and nothing in `provides` / `requires` expresses it.
**3 — Configuration that is partly the machine's.** Tuning follows the hardware — memory,
storage. A declaration generated centrally cannot know those, and
[research 012](../012-the-minimum-viable-node/00-overview.md) says the machine's own values win
on conflict. So some of this module's configuration is *derived from the node it lands on*.
**4 — A tool surface.** It exposes capabilities agents can call — query, list, provision. That
is not a resource on a machine and not an artifact; it is a contract the mesh publishes on the
module's behalf.
**5 — A provisioner.** The part that matters, and the one below.
**6 — Its own bookkeeping.** The provisioner must remember what it granted to whom, or it
cannot revoke, rotate or clean up. So a module that provides state to others *also* holds state
about its providing — and that state is not the database's data.
**7 — An exposure decision, per node it runs on.** Reachable from the machine only, from the
local network, or publicly. That is a property of *this assignment*, not of the module: the
same module on two nodes may answer differently.
**8 — Credentials it generates.** Per consumer, and they have to reach the consumer. Which
means a provisioning edge carries a payload, and the payload is a secret.
**9 — Health that is not "the container is up".** A container running and a database accepting
connections are different facts, and the second is the one anything cares about. This is the
host's read-back rule, at a distance.
## The provisioner is a second kind of edge
The tidy version of this effort said: *a module provides names, a module requires names, that is
the only edge.* A small game wanting to store data shows it is not.
```
my-cool-game requires postgres # I speak its protocol, it must exist
my-cool-game requires a database FROM postgres, called my-cool-game
```
The first is **presence**: the thing exists and is reachable. Nothing is created; nothing flows
back. `vscode requires terminal` is this, and so is `requires container-runtime`.
The second is **instantiation**: the provider is asked to make something *for this consumer*,
and hands back what the consumer needs to use it. A database, a user, a password, an address.
They differ in every way that matters:
| | presence | instantiation |
|---|---|---|
| creates something | no | yes, one per consumer |
| carries a payload back | no | credentials, an address |
| can be revoked | — | yes, and must be when the consumer goes |
| provider holds state about it | no | yes — who was granted what |
| satisfied by | anything providing the name | that provider, specifically |
**This is the mesh's actual power**, in the operator's words: a small game declares it wants a
database and the mesh makes one. Nobody creates a user by hand, nobody pastes a connection
string. That is worth being precise about rather than folding into a single relation because
one relation is prettier.
## What that costs the design
**The proposal's "one kind of edge" is wrong**, and the current system already knew: it has
`dependencies` for presence and `requires: provision:` for instantiation, with the resolver
deriving a presence edge from every instantiation edge. [`analysis.md`](analysis.md) recorded
that derivation as a convenience. It is not — it is the correct relationship between two
genuinely different relations.
So: **two kinds of edge, one graph.** Instantiation implies presence. Presence does not imply
instantiation.
## Which provider, when two nodes run one
Asked directly, because two nodes can each run a relational store and a consumer has to be
served by one of them. Neither obvious answer is right.
**Not "the consumer names the node."** That is placement in the consumer's manifest — a small
game edited because a database moved, which is the fault
[`proposal.md`](proposal.md) separates constraints from placement to avoid.
**Not "the consumer does not care" either.** For presence it genuinely does not: a terminal is a
terminal. For instantiation it cares permanently, because the data lands in exactly one store
and the wrong choice is discovered long afterwards.
**What the consumer does know is the scope of its own need.** Not which node — how many of the
thing it wants, relative to itself:
| Scope | Means | Example |
|---|---|---|
| **shared** | one instance serves every instance of this consumer | the mesh's own registry: every node reads the same rows |
| **per instance** | each instance of this consumer gets its own | a local cache, a per-node queue |
That is a property of the consumer, expressible without naming anything. And it is the thing
that actually decides: a shared need cannot be satisfied by a provider each node runs
separately, and a per-instance need should not be satisfied by a shared one.
**Then the mesh binds, and the binding is written down.** Not recomputed: a resolver that
re-derives which store serves a consumer will one day derive a different answer and relocate a
database, so the binding is made once and changed only deliberately.
**Where it is written down follows the scope.** A shared grant belongs to the *module* and every
assignment of it references the same one — which is the answer for one module installed on two
nodes wanting one database between them. A per-instance grant belongs to the *assignment*. Same
relation, two homes, and which home is not a detail: it is what makes two instances share
something or not.
The pieces that follow, none of them settled here:
- **When several providers satisfy the scope**, something chooses — most plausibly locality,
preferring a provider on the same node. That is a default, and it must be overridable, because
the reason to override it is exactly the reason nobody anticipated it.
- **A binding is a thing that can be wrong.** Once recorded it can be inspected, and a consumer
bound to a store on a node that no longer exists is a question somebody can be asked rather
than a failure at connect time.
- **Moving a binding moves data.** Whatever the mechanism, changing it is a migration and not a
configuration change, and a design that lets it look like the latter will lose something.
## Provisioning is early, not late
An assumption worth killing: that provisioning is something the control plane does for
consumers once a mesh is running.
**The mesh's own registry is a provisioned database.** So is its virtual host on the broker.
Neither exists until something creates them, and nothing in the mesh works until they do. The
order is:
```
1 the store runs from the bundle the host carries
2 a database is created in it a provisioning step
3 the mesh's own schema is applied a migration, against that database
4 the control plane starts and only now is there a mesh
5 everything else is provisioned the ordinary path
```
Steps 2 and 3 happen **before there is a mesh to do them**. So provisioning is not a
control-plane service that consumers use; it is part of the bootstrap, and part of what the
carried bundle has to be able to express.
**Which strains what a declaration is.** [ADR 0005](../../02-DECISIONS/0005-the-node-host.md)
has the host applying *declared state on this machine*. A database inside a running store is not
a file or a unit — and at bootstrap it is, at least, local: the store is on the same machine as
the host applying the bundle.
Later it is not. A consumer on one node provisioned from a store on another is the ordinary
case, and reaching it is not the host's job.
**Resolved as two mechanisms, which is the answer rather than a compromise**
([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)). The host
runs bootstrap actions locally from the bundle; the control plane provisions across the mesh
afterwards. Different actors, different scopes, different trust paths — so there is no single
operation with a tier boundary running through it.
## Several modules, one database — and the case for refusing
Asked, then reconsidered by the operator: *maybe we should not allow it.*
The permissive version was a per-consumer **schema** inside a shared database — its own
namespace, its own migrations, revocable by dropping the schema, with a cross-context join
possible but deliberate.
**The stricter version is better, and it goes further than schemas.**
> **A module is only ever granted a resource it exclusively owns.**
No shared writes. And **no read-only role on another module's database either** — reading
another context's tables couples you to its layout exactly as firmly as writing them does, and
the coupling is harder to see because nothing breaks until the owner changes a column.
That is what [`how-we-build`](../../00-META/how-we-build.md) §4 already says: *contexts integrate
through the record, never through a shared schema.* The permissive version kept the letter of it
and left the temptation in place, and the path of least resistance wins eventually. A boundary
that is merely inconvenient to cross is a boundary that gets crossed.
### What it costs
**Cross-module reporting.** Anything wanting to know what several modules hold can no longer
join across them. It consumes their events, or calls their interface, and neither is as
immediate as a query.
That cost is the point rather than a regrettable side effect — it is §4's whole argument, and
the mesh already has both mechanisms: an event stream every context publishes to, and a tool
surface every module exposes. What gets harder is the thing that was making work belonging to
one context keep having to be implemented in another.
**One more connection per consumer.** A dozen modules means a dozen databases rather than a
dozen schemas in one. For a relational store this is unremarkable; it is worth stating only so
nobody discovers it as a surprise.
### What it deletes
The effort has been looking for what the design *removes* rather than adds, and this is the
first clear instance:
- **Grant kinds.** There is one — an exclusive resource. No schema grants, no read roles, no
scoping rules for who may see what inside a shared thing.
- **The question of who owns which table**, and with it the guessing at revocation time.
- **Cross-module migration ordering.** Two modules migrating one database need their migrations
ordered against each other. Exclusive ownership means a module's migrations are ordered only
against itself.
- **A whole class of permission modelling** that a shared store would otherwise need.
### The rule is about contexts, not processes
An earlier version of this file argued that a dashboard reading a dozen stores was caught by the
rule, because a dashboard is a surface and surfaces speak to an interface. **That was wrong, and
it drew the line in the wrong place.**
The mesh's own board showing nodes, modules and deployments is not a separate context reaching
across a boundary. It is the mesh showing its own data. Reading that store is not a violation
however it is done, and requiring it to go through an interface to reach facts its own context
owns would be ceremony.
**The rule is: a context is granted what it exclusively owns.** Everything inside that context —
its service, its surface, its tools — reads it freely. What is forbidden is a *different*
context reading it.
Which is exactly what the count below shows: the problem was never surfaces. It was three other
contexts keeping their tables in the mesh's database.
**And one surface over several contexts is normal.** The board visualises the mesh, the work
engine, the knowledge base and more, and the alternative — a separate web application per
context — is worse for everyone who uses it. That is not a compromise with the rule; composing
several sources into one view is what a surface *is*.
What it changes is only where it reads from: each context's **interface**, not each context's
**store**. Most of that already exists — 56 of 126 modules carry a tool surface, more than carry
a service.
**And the unified board is what keeps those interfaces honest.** If a view cannot be built from
a context's interface, that interface is inadequate — discovered in the one place where it is
cheap to notice, rather than the first time something else needs the same data and quietly
reaches for the store instead.
**But "the board calls each context's interface" is not quite it either**, and the objection is
right: if every context runs its own service with its own interface, the board is coupled to N
of them instead of N schemas, something has to compose them, and composition is logic — which
tier 3 says a surface does not hold. That moves the problem up a layer rather than solving it.
**The skeleton already answers this and the argument above talked past it.** `work` and
`knowledge` are not separate services; they are **contexts inside the control plane**, alongside
the record, inventory, delivery and the rest — and `api` is listed there as *the one interface
every surface speaks to*.
So the board speaks to **one** interface. Behind it the contexts stay separate: separate stores,
integrating through the record. But they are one tier, one repository, one deployable, and
coupling *within* a tier is not what the tier rule forbids.
Which resolves the objection rather than deflecting it: the problem does move up a layer, and
the layer it moves to already exists and has this as its job.
**The caveat is load-bearing.** This holds only while the contexts are not separate deployables.
The moment one becomes its own service with its own interface, the board is back to N clients,
something must compose them, and the composition has nowhere to live that tier 3 permits. That
is a real constraint on how far the control plane may be split, and it is worth knowing now
rather than discovering it by splitting.
If composing even one interface turns out too slow, the answer is a projection the board owns
and keeps current from events — not access to somebody else's tables.
### Checked against the real consumers
The rule's survival turned on whether every reader of the mesh's own registry could be served
some other way. **Eighteen consumers open a direct connection to it.** Four groups, and only one
of them is work.
| Group | What happens under the rule |
|---|---|
| **The owner and its machinery** — the mesh module, the SDK, the environment and configuration synchronisers, secrets | Nothing. It owns the database. |
| **Node appliers** — the overlay, the shell daemon, the resolver | **Already resolved.** [ADR 0005](../../02-DECISIONS/0005-the-node-host.md) stops the host querying the mesh database, decided for tier reasons with nothing to do with this. |
| **Foreign tenants** — the work engine (10 tables), the knowledge base (2), pipeline logs (1) | They need **their own database**. They are not reading the registry; they are storing their own data in it. |
| **Genuine cross-context reads** — the work engine reads `nodes`; two others read a handful | The only ones needing an interface or events. |
**Thirteen foreign tables live in the mesh's registry database**, belonging to three separate
contexts. That is [`how-we-build`](../../00-META/how-we-build.md) §4's shared schema, counted.
**So the question was the wrong shape.** The bulk of the problem is not readers needing a new
route to data — it is **tenants needing to move out**. Tasks, agents and teams have nothing to do
with nodes and modules; they are co-located by history. Give that context its own database and
its dependency on the registry shrinks to a single table.
What remains is a handful of genuine cross-context reads, small enough to enumerate rather than
estimate. **The rule holds.**
### Request or subscription, and what decides
The remaining cross-context reads need one or the other. **Neither is SQL** — under exclusive
ownership a module runs SQL against its own database and nothing else, whatever transport a
query might travel over. Both options are the mesh's own channel, and both ride the broker
([ADR 0002](../../02-DECISIONS/0002-nodes-communicate-over-a-broker.md)), so the transport is
not the distinction.
**The distinction is where the answer lives when you need it.**
| | request | subscription |
|---|---|---|
| you ask | at the moment you need to know | never — you are told |
| the answer lives | on the other side | in your own store |
| freshness | always current | as current as the last event you received |
| when the other side is down | you cannot answer | you answer from your copy |
| what you must handle | a round trip that can fail | events you missed while you were down |
**What decides is not taste.** [ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)
makes disconnection an ordinary situation rather than an exception. So:
> **Anything that must keep working while disconnected cannot use a request** — there is nobody
> to ask. It needs a local copy, which means a subscription.
And the converse: anything that must be *correct at the instant of asking*, where a stale answer
is worse than no answer, cannot use a subscription. A display can lag. A decision about whether
a grant is still valid cannot.
That turns an apparently open question into a derived one. What remains genuinely open is
narrower: **what a consumer does about the events it missed** while it was disconnected — replay
from a point, ask once for a full picture and resume, or rebuild from scratch. That is the same
question every projection has, and nothing in the record answers it yet.
## A migration belongs to the consumer and runs on the provider
A game defines migrations. They run against the database the store granted **it**. So the
migration is:
- **owned** by the consumer — it is that module's schema, versioned with that module;
- **hosted** by the provider — it runs inside something the consumer does not control;
- **ordered** after the provisioning edge — there is nothing to migrate until the grant exists;
- **scoped** to the grant — the consumer's migrations touch its database and no other.
Ownership crosses the edge, which nothing in *provides* and *requires* expresses. And it is the
*action* category from [`features.md`](features.md) made concrete: not an artifact, not node
state, and not something the host can apply, because the thing it changes is not the machine.
It also gives a consumer's own install an internal order — **provisioned, then migrated, then
started** — that depends on an edge rather than on the module's contents.
## What still has no answer
**How many instances of postgres should exist?** One per mesh is wrong — a node that must work
while disconnected cannot depend on a database elsewhere. One per node is wrong — the mesh's own
registry is one thing, not one per node. So the answer is per-module, and nothing in the schema
says it. This is [`cases.md`](cases.md) axis *how many instances*, and postgres is the case that
proves it cannot be a global rule.
**What happens to a grant when the consumer is removed?** The game is uninstalled. Its database
still exists, holding its data. Dropping it silently is data loss; keeping it forever is a leak.
| What is the closure for a one-node mesh? | The skeleton asserts four pinned services. [Research 006](../006-mesh-from-scratch/00-overview.md) already asks whether it is four or five and does not answer. A graph gives a computed answer instead of an asserted one, which is [research 011](../011-the-module-graph/00-overview.md). |
| Is "tier" the same thing as a graph level? | Tiers were named as a bootstrap order. If the closure is computed, tiers may be a derived view of the graph rather than a separate concept — or they may be a coarser boundary that survives for a different reason. |
| ~~What happens when existing configuration contradicts what the mesh needs?~~ | **Answered** — the machine's configuration is kept, the conflict is flagged, and it is reconciled afterwards. |
| ~~Do flags block, or only inform?~~ | **Answered** — they inform. Adoption always completes, and the node is a node. |
| Can a module say which of its settings are load-bearing? | The question that dissolves the conflict rule rather than choosing a side. A setting the module *requires* cannot be kept from the machine without producing something installed and broken; a setting it merely *prefers* should always yield. Until a module can say which is which, adoption is defaulting in the dark. Belongs with the graph. |
| Does a `failed` line still let adoption complete? | *Flags inform, they do not block* was decided about conflicts, where the mesh chose and the machine works. A failure is *we could not*, which is different in kind — and treating them alike hides the worse one behind the commoner one. |
| How is a flagged conflict reconciled, and by whom? | The briefing hands it to a session. What that session is empowered to change, and whether the resolution is recorded so the next adoption does not re-raise it, is undecided. |
| ~~How long is a machine adopted?~~ | **Decided** ([ADR 0100](../../02-DECISIONS/0100-a-node-in-use-is-adopted-before-it-is-converged.md)) — for as long as it is being migrated: a mode per node, recorded, ended by an explicit and previewed flip. |
| Where does the kept original live, and for how long? | Whether it is recorded in the node's state so adoption is visibly reversible, and whether it is returned when the mesh stops managing the thing. |
| What shape is a briefing? | Structured enough to be acted on, prose enough to be read. It is the first thing a session on a new node sees, which makes it an interface rather than a log. |
| Does owning a package mean owning its version? | Owning configuration and owning the package are different scopes. The second means the mesh decides which version is installed, and that decision then has to survive the machine's own package manager updating it. |
| How does a bundle stay true between building and applying? | It is built against a scan of the target. The machine can move between the scan and the apply, so the host has to verify rather than assume — and fail plainly when the bundle no longer fits. |
| What cannot be precomputed at all? | Anything built from source on the target still needs a toolchain and a network at that moment. Tailoring moves that cost rather than removing it, and *minimal viable* has to be honest about what it cannot ship ahead. |
| Does presence differencing understate the gap? | Knowing a package manager is installed does not say it is the version the mesh needs. A difference computed on presence alone is optimistic. |
# Migrating a node that is in use — adoption as a mode, not a moment
*2026-09-22. Measured on the machine that will be the control-node, which is running the
predecessor mesh today. Nothing below names it; the counts are its own.*
## The question
The mesh replaces a predecessor mesh that is running, on the same machines, with the services
people use. The control-node is decided: it is the machine that already carries the predecessor's
broker and build pipeline. So the question is not *where* the mesh starts but **how a machine
running the predecessor becomes a node of the mesh without its services noticing** — and then how
each of the other machines follows.
## The operator's proposal
Proposed by the operator, 2026-09-22, and the shape this document tests:
1. **Stop the predecessor's control on a machine** — its daemons that write configuration: the
network and firewall configuration above all, which decide what is reachable and what is
blocked. Its services keep running; only the control over their configuration stops.
2. **Bring the mesh up on that machine in adoption mode.** It takes custody of those files and
keeps what it finds in force.
3. **Migrate the modules one at a time**, data preserved, per the cutover procedure.
4. **Move to the next machine and repeat** — adopted first, keeping its local configuration, then
migrated.
5. **When every machine is migrated, flip adoption mode**, and the mesh takes full control of the
configuration it has been holding.
This is the research above made concrete. It keeps the conflict rule already decided here — *on
conflict, what is on the machine stays* — and gives the middle state, *adopted*, a length: not a
one-time import before generating starts, but a mode that lasts for as long as the machine is
being migrated, ended by an explicit act.
## What the machine actually looks like
Measured, read-only:
| | |
|---|---|
| Containers running | 60, all the predecessor's services and their stores |
| The predecessor's control | user-level daemons, separate from the services; none of the 20 running system services is the predecessor's control |
| Firewall | the predecessor's, active: 54 incoming rules and 52 forwarding rules, each served port allowed explicitly — how a default-deny firewall reads |
| Files the predecessor's configuration sync writes | 12, of which 3 are system files (an ssh server drop-in, the package manager's configuration, one service's configuration); the rest are the operator's shell and agent files |
| Per-service configuration | environment and composition files per service, written by the predecessor's service tooling |
**Stopping the predecessor's control stops nothing that serves.** The services are containers and
system units that run without it; what stops is the rewriting of their configuration. Nothing
changes on the machine until something else writes.
## What collides, measured rather than assumed
An earlier note assumed the mesh's foundation could not stand beside the predecessor because both
want the store's and the broker's standard ports. **The measurement says otherwise.** The
predecessor publishes its own store on a non-standard port and its broker on another; the standard
ports the foundation binds for its store and its bus are free.
What does collide:
| The mesh wants | Held by | When |
|---|---|---|
| the registry's port | the predecessor's registry | at genesis — the foundation raises a registry |
| the broker's management port, on loopback | the predecessor's broker | at genesis |
| the private network's port | the predecessor's own tunnel | at genesis on a control-node that is the private network's hub; otherwise when the node is placed on it |
| the web ports | the predecessor's reverse proxy | when the route proxy is assigned |
| the resolver's port | a resolver the predecessor runs | when a resolver module is assigned |
On the control-node, which is the private network's hub, three of these fall at genesis and cannot
be deferred; two only when a particular module is taken, the moment its predecessor stops anyway.
Today the foundation's ports are **fixed**: written in the installer's bundle and in the
catalogue's manifests, so a collision is found when a container fails to bind, not before — and a
port changed at genesis would be changed back when the foundation is adopted as modules, since the
applier recreates a container whose declared spec differs. The private network's address range
must also stay clear of the range the predecessor's tunnel uses; on the machines measured they are
distinct.
## What would break if the mesh came up as it is today
**The firewall.** Genesis loads a base ruleset — drop anything undeclared — in its own table
([ADR 0088](../../02-DECISIONS/0088-the-foundation-filters-before-anything-listens.md)). The
predecessor's firewall is a different table. The kernel runs every base chain registered at the
same hook, in priority order: an accept ends only its own chain and the packet goes on to the next,
and a drop in any is final — whether the other firewall's chains are nftables or legacy iptables.
So the
mesh's base ruleset would drop everything the predecessor's firewall allows and the mesh has not
declared — every web, mail and database port in the table above — the moment genesis ran.
**The files.** The host writes a declared file whatever it finds at the path, reporting it as
updated. A file the predecessor left — the ssh server drop-in, the resolver's configuration — is
replaced the first time a module declaring that path is assigned, before that module's service
has moved.
**The container names.** The applier keys a container on its name. A catalogue module whose
container carries the same name as the predecessor's service it replaces takes that container over
the moment it is assigned: today, *assigning a module is migrating it*, never a preparation.
**The published ports.** The foundation publishes its ports on every interface, and a published
container port reaches the container through the forwarded path, not the incoming one. A firewall
that filters only incoming traffic never sees it. The base ruleset is what keeps the store
unreachable from outside today — and it is the thing that cannot be loaded on this machine.
## The pipeline freezes while the control-node migrates
The predecessor's build pipeline and its coordinator run on the control-node. Stopping its control
there stops the predecessor's updates for **every** machine it manages, until the migration is
done. Their services keep running; they receive nothing new. That is the price of the proposal and
it is worth stating, not a reason against it: the migration is the period in which the predecessor
is being replaced, and it does not need to keep changing.
## What adoption mode has to mean
For the proposal to hold, *adopted* must be a **state the mesh records per node**, not an
intention, and each thing the mesh would otherwise take must say what it does in that state:
- **What is found is kept until its module is taken.***Found* is precise: present at a declared
path or name with no record in the host's store. A found file or container is held, its original
recorded, until the operator **takes** the module on that node — the cutover, done when the
module's data has moved. Assigning prepares; taking migrates. Without the distinction the rule
never fires: the host only ever sees what assigned modules declare.
- **The firewall found on the machine stays in force.** The mesh loads no table on an adopted node
that drops by default or holds an accept. What it needs open it declares as openings the host converges
*through the found firewall*, on the incoming and the forwarded path, marked as the mesh's and
re-checked on every reconcile so a reload or reboot does not lose them. An accept in a table of
its own would not help: the found firewall's drop would still be final. What a table of its own
*can* do is refuse, and a refusal is final too — so the mesh guards the store and the broker's
management port from everyone but the private network and the machine itself, in a table that
only refuses, ahead of the container runtime's redirect — which the found firewall does not do
and cannot undo. The bus, the registry and the hub's port stay open to
anywhere: a node enrols before it has a private-network address.
- **The foundation's ports are the node's to give** — set at genesis, checked free, and kept as
that node's settings, read everywhere they are used, so adopting the foundation as modules does
not move them back.
- **The flip is per node and previewed** from what is actually reachable — listening sockets and
published ports, not the found firewall's allow list, which does not see what a container runtime
forwards.
## Options weighed
| Option | Verdict |
|---|---|
| Cut the machine over in one go: stop the predecessor's store, broker, registry and proxy, raise the foundation in their place | Rejected. Every predecessor service goes down until it has migrated, and the predecessor's other machines lose their broker. The rollback is restarting the predecessor, which is a recovery, not a step. |
| A separate machine as the control-node | Rejected. Contradicts the decision that the control-node is the machine that already carries the predecessor's broker and pipeline. |
| Converge on joining, as the mesh does today | Rejected. The base ruleset closes every predecessor port at genesis, and found files are replaced before their services move. |
| Make only the foundation's ports configurable and otherwise converge | Rejected as insufficient. It solves the bind collisions and none of the firewall or file ones. |
| Treat assigning a module as migrating it | Rejected on review. The rule that keeps found files would never fire — the host only sees what assigned modules declare — and an assignment on an adopted node would be an outage rather than a preparation. |
| **Adoption as a mode, per node, ended by an explicit flip** | The proposal. It is the conflict rule already decided here, given a duration. |
## What this leaves open
Answered by the decision record this feeds — [ADR 0100](../../02-DECISIONS/0100-a-node-in-use-is-adopted-before-it-is-converged.md)
— only for the migration's needs. The general questions above stay open: whether a module can say
which settings are load-bearing, what shape a briefing takes, how a flagged conflict is reconciled.
One is newly sharp: the mesh opening ports through a firewall it did not install needs to speak that
firewall. There is one kind on the machines measured; a machine with another is not covered until
**The predecessor's world**, now on the same broker: ~50 AMQP connections per machine from four
machines, 595 queues, four vhosts, six users. All of it AMQP, all of it retiring module by module.
NATS speaks no AMQP: that world cannot move; it does not need to.
## How NATS answers each of those
| The mesh relies on | NATS | Note |
|---|---|---|
| topic routing keys | subjects with wildcards | same shape (`mesh.events.>`) |
| RPC and tool invocation over an exchange + reply queue | request/reply, native | simpler than today |
| competing consumers | queue groups | same |
| durable control queue, hold-unacked-and-retry, catch-up | JetStream: streams, durable consumers, ack/nak with delay, replay | the 0083 guarantee moves to JetStream; core NATS alone is at-most-once and would not do |
| dead-letter | max-deliver + advisories, or a stream fed from them | different mechanism, same effect |
| TLS bus | TLS | same |
| accounts scoped by emits/consumes, vhosts | accounts (isolation) with users and per-subject publish/subscribe permissions | stronger than today; the controller writes an auth config the host declares and the server reloads, instead of calling a management API |
| management API | `nats` CLI and an HTTP monitoring endpoint | no vhost concept — accounts instead |
| MQTT | built in | same |
| a module seat `mesh-broker` | unchanged — the seat is the server, the module changes | ADR 0079 |
| multi-node | clusters and leaf nodes | not needed now; a leaf per node is a later question |
Nothing the mesh needs is missing. The differences are in the shape of durability (JetStream must
be declared, streams and consumers are objects) and of accounts (configuration, not API calls).
## The cost, honestly
The bus is the mesh's nervous system. Moving it means: a new `nats` module in the catalogue taking
the `mesh-broker` seat; the controller's and the host's link packages rewritten; the tool runtime's
client swapped behind the unchanged contract; enrolment, reports, builds and the guard's ports
re-derived; the lab beds that prove the bus (store window, enrolment, upgrades) re-run on the new
one; and eight decisions amended or superseded. Weeks, not days — and none of it can be done
halfway on a live mesh: the controller, every host and every tool runtime move together.
## The sequencing question, answered
1. **NATS first, directly.** Stalls the migration for the length of the build; the mesh's bus
changes under a half-migrated node; the predecessor's clients still need AMQP, so a second
broker runs anyway, plus a bridge for whatever crosses. Rejected.
2. **Finish on AMQP, NATS after.** Wastes nothing — no module written from here on speaks AMQP —
but leaves the decision unmade while modules are written, and the runtimes idle. Adequate.
3. **Decide NATS now; build it in the lab in parallel; cut the mesh's bus over in one rehearsed
rollout after the core is migrated.** The predecessor's clients never notice: their broker is
the one the mesh adopted, kept as a compatibility module with an end date — the day the last
AMQP client is gone. **Recommended.**
## What this leaves open
- The **decision itself**, as a record: the bus is NATS; the AMQP broker becomes the predecessor's
compatibility broker and retires with the last AMQP client. Written when the operator says so.
- **JetStream's shape for the control plane**: one stream per concern (control, nodes, builds,
events) or one with subjects; retention; what the store window guarantee looks like as ack-wait
and nak-delay. Measured in the lab, not designed on paper.
- **Accounts as configuration**: the controller writes users and permissions into a file the host
declares, reloaded on change — which is the [ADR 0102](../../04-ISSUES/102-an-address-recorded-at-genesis-or-build-does-not-follow-the-nodes-ports/00-report.md)
discipline applied from the start — or the JWT/operator model. The first is simpler and matches
how the mesh already writes everything.
- **The MCP bridge** the operator asked for the same day is written against the sdk's contract, so
it moves with the bus and is not written twice.
- Whether a **leaf node per machine** replaces the hub-and-spoke bus later — out of scope here.
Which S3-compatible implementation replaces it, and what is the migration track for the data and
the provisioning model that sit on top of it?
**Why now, and why not sooner.** Nothing is on fire: nodes that already hold the images keep
running, and issue 113 establishes that the deploy path tolerates an unfetchable-but-present
image by design. The forcing function is not an outage but a one-way door — **no node that does
not already hold the images can ever provision the module again**, so the mesh's ability to stand
a node up from its declarations is already broken for this module, and silently.
**The direction is not a departure from the design; it is the design.** The foundation document
already states the commitment:
> The dependency is on the **protocol**, not the product: AMQP for the bus, S3 for the object
> store, the OCI protocol for the registry. That is what keeps the naming safe rather than a
> commitment that cannot be revisited.
The object store is also **not** a foundation service — ADR 0028 removed it, and it is an
ordinary module required through the module graph by whatever wants one. (The "exception that is
not a swap" in that passage is the relational store, whose provisioning model borrows PostgreSQL's
own meaning of databases, roles and schemas. The object store carries no such coupling: a bucket
is a bucket.) So this effort is an instantiation of an existing principle, not a redesign — which
is the cheapest kind of decision to make and the strongest kind to cite.
## What the replacement has to carry, measured
Taken from the module's manifest, its composition, its tool surface, and a search for its
consumers across the catalogue — not from assumption.
| Requirement | Evidence in the module today |
|---|---|
| S3 API | The protocol every consumer speaks; already the design's stated dependency. |
| ~~OIDC login against the mesh's identity provider~~ | **Struck 2026-09-24. Not a requirement, and it never worked.** Six variables are wired and an entrypoint blocks on the provider, which reads as a live feature. The module's own hook comment records the end state as *"policy claim missing"* — a failing login. See [01](01-candidate-comparison.md). |
| **Per-application access keys, each scoped to a bucket** | The real requirement. A "user" of the store is normally an application; the mesh already mints a credential per provisioned bucket. |
| **One live consumer using it as opaque primary storage** | A file-sync application, since early 2023: objects named by internal id, metadata in its own database. Highest-risk consumer — a live copy drifts, and its bucket name must be preserved. |
| Erasure-coded multi-node topology | Four server nodes with two data directories each, behind a load balancer. |
| A single-node form | Declared as a flavour, for development and small nodes. |
| Buckets as a typed provision | The module declares a provision type of `bucket` on a named network; the mesh mints the credential and the provider creates it (ADRs 0048, 0084). |
| A tool surface | Bucket create/list/delete, object list/info/delete, presigned URL, and provisioning. |
| A console | Published on its own subdomain through the reverse proxy, with an unlimited request-body middleware for uploads. |
**Consumers, counted:** one application module, one capture module that takes a private bucket per
node, one workflow module's tools, and the delivery/rescue internals of the shared library. The
surface is small — the cost is concentrated in the provisioning handler, the tool handlers and the
OIDC story, not spread across the catalogue.
## Candidates
**Four candidates, not three.** The comparison was briefly narrowed to SeaweedFS on the strength of
console single sign-on; that axis turned out not to be a requirement, and the incumbent's own
maintained fork had been omitted altogether. Both errors, and why they happened, are recorded in
[01 — the candidates measured](01-candidate-comparison.md), which carries the evidence and the
requirement-by-requirement detail.
In short, and only in short:
- **The maintained fork of the incumbent** — the community edition was archived and its images
deleted, but a fork publishes, tracks CVEs, and preserves the on-disk format, S3 API and
environment surface. Costs **an image reference** where every other option costs a data
migration, two rewrites and a maintenance window. Does not end the dependence on an abandoned
codebase; buys time to choose deliberately.
- **Garage** — its permission model *is* the requirement (per access key, per bucket), its admin
API is the closest match to how the mesh provisions, and the highest-risk consumer is
first-party documented against it. Remaining cost: no object versioning, no server-side
encryption or object locking, partial lifecycle — **unmeasured against the ten buckets, and the
one thing that could still disqualify it**.
- **SeaweedFS** — longest field record and erasure coding. Its console sign-on is a paid feature,
which is now beside the point. What weighs against it is narrower: its S3 surface is a gateway
translating onto its own file-system API, with no first-party support for the opaque consumer.
- **RustFS** — closest in shape to the incumbent, so the least porting. But it reached general
availability eight days before this was written, and carries an open defect in the credential
path. Two earlier claims about it are corrected in 01: it is **not** a drop-in that retains
existing data.
- **Ceph RGW** — remains rejected as disproportionate where the object store is an ordinary
module rather than a platform.
**This is now two decisions, not one:** whether to repoint to the fork or migrate, and — if
migrating — to which. Repointing does not foreclose migrating, which is the argument for taking it
first. On the corrected requirement the migration ranking is Garage, then SeaweedFS, and not yet
RustFS. Two measurements gate any graduation: **which S3 endpoints the consumers actually call**
(Garage cannot be ranked fairly until counted), and **whether the fork can read the incumbent's
on-disk format in place** — tested on a copy, because the migration between them is one-way. Both
are in [01](01-candidate-comparison.md#what-is-still-unmeasured).
## The migration track, in outline
Data movement is the easy half, and deliberately reversible.
1. **Stand the replacement up beside the incumbent**, on its own ports, its own provision type and
**its own data directory**. Nothing removed. The data directory matters: reusing one the
incumbent already holds would put a fresh single-drive store on top of a live erasure set.
2. **Copy bucket by bucket with a neutral tool.**`rclone` rather than the incumbent's own client
— the client has been withdrawn upstream too, so building the migration on it would inherit
the same dependency this effort exists to remove.
3. **Verify per bucket** — object counts and checksums, not a transfer exit code.
4. **Repoint consumers through the connection the module already publishes.** Consumers read an
API URL from the module's declared connections rather than addressing the store directly, so
the cutover surface is that value plus the provisioning and tool handlers.
5. **Freeze writes, final incremental sync, flip**, and keep the incumbent read-only as the
rollback until confidence is earned. For the opaque consumer this is **not optional and not
instant**: it stores objects by internal id with metadata in its own database, so a copy taken
while it runs will drift. It needs a maintenance window for the final sync, and the window is
proportional to 82,496 objects rather than to 230 GiB.
6. **Retire**, and only then remove the module.
The genuinely new work is not the copy. It is the **provisioning handler** and the **tool
handlers**, both written against the incumbent's admin API. *The OIDC wiring was previously listed
here and is struck: it is not a requirement and it never worked.*
## Open questions
- ~~How much of the OIDC requirement survives, and in which build?~~ **Answered, and it was the
wrong question.** The console requirement does not exist, and the login it referred to never
worked. What replaced it: which S3 endpoints consumers actually call, and whether the fork reads
the incumbent's format in place.
- Does the mesh's bucket provision translate to the candidate's identity model without weakening
what ADR 0049 says about a consumer's identity fitting the tightest backend?
- Should this effort also answer issue 113's general question — mirroring third-party images into
the mesh's own registry — or is that a separate decision? Replacing one withdrawn product with
another unmirrored upstream leaves the same one-way door in place, just further from the hinge.
- Is the four-node erasure-coded topology still warranted, or was it inherited? Worth re-asking
while the product is being chosen, rather than reproducing a shape by default.
**What.** Which rotation mechanisms the mesh's providers can actually support, measured against
their code rather than assumed. Every provider in the catalogue was read, found by listing every definition that provides something: how it names what it
makes for a consumer, what its remove destroys, whether it re-applies a password, whether its
backend can hold two secrets for one login or two logins on one resource, and how its own
administrative credential is set. The consumer side was read too: when a module reads a secret, and
what makes it read a new one.
**Why.** [ADR 0113](../../02-DECISIONS/0113-the-vault-makes-every-secret.md), as first drafted,
chose *overlap*: add a second login beside the first, move every reader, then remove the old one,
"through the adapter's existing create and remove", with "no consumer changes". A review showed that
claim false. In most providers the consumer's data is named after its login, and remove drops the data
with the login. Overlap as written would have deleted every consumer's database on its first
rotation. The mechanism has to be chosen on what the providers do.
**What it touches.** Rotation in 0113 and [to-be 27](../../03-DESIGN/01-to-be/27-a-module-requires-the-mesh-resolves.md),
which [ADR 0114](../../02-DECISIONS/0114-a-shared-credential-rotates-over-two-credentials.md) decided on
these findings. The identity budget in
[ADR 0049](../../02-DECISIONS/0049-a-consumers-identity-fits-the-tightest-backend.md), if a consumer
gets two logins. The rotation already implemented, which [to-be 13](../../03-DESIGN/01-to-be/13-credentials-and-their-rotation.md)
describes.
**Documents.**
- [01 — The providers](01-the-providers.md): the survey, one row per provider, and what it shows.
- [02 — The readers](02-the-readers.md): how a secret reaches a running process, and what already
recreates it.
- [03 — The options](03-the-options.md): each rotation mechanism against those facts, and a
recommendation.
**Finding, in one paragraph.** All nine credential providers already re-apply a consumer's password
in place on every create, and the controller's `rotate` command relies on that. It is a working
rotation with a stated window. Eight of the nine name the consumer's resource after its login, and five
destroy the consumer's data when they remove the login. The harness, keyed by login, would do the same
on any change of login. Only one backend holds two passwords on one login, and two more hold several
tokens. Eight backends can grant two logins the same rights over one resource; the ninth can give one
login a second token. So every provider can hold **two credentials** over one resource, but only after
each adapter separates *the consumer's resource* from *the credential that reaches it*. In postgres
that also means the resource belongs to a role no login owns. Administrative credentials are a
different case. They have one party and a fixed name, and five backends take them only at first
initialisation, so changing one needs the old and the new value at once.
| provider | the consumer's resource is named | remove destroys | create re-applies the password | two secrets on one login | two logins on one resource |
|---|---|---|---|---|---|
| postgres | a database named `login`, owned by the role `login` | the database and the role | yes, `ALTER ROLE … PASSWORD` when the role exists | no: a role has one password | yes, but only through a role that cannot log in owning the database, with each login working as it. Otherwise whatever one login creates is its own, and dropping that login means handing its objects over first. Not done today |
| mssql | a database named `login`, with the login mapped into it | the database and the login | yes, `ALTER LOGIN … WITH PASSWORD` | no: a login has one password | yes, two logins mapped to users in `db_owner`. A user owning a schema cannot be dropped, and a login with an open session cannot. Not done today |
| mongodb | a database named `login`, with a user holding `dbOwner` | the database and the user | yes, `updateUser` with the new password | no: a user has one credential | yes, two users with `dbOwner` on one database. Not done today |
| redis | the key prefix `login:` on an ACL user named `login` | the user, **not** its keys | yes: `ACL SETUSER … reset … >password` replaces all of them | **yes**: an ACL user holds several passwords, added with `>` and removed with `<`. Today's `reset` discards all but the new one | yes, two users on one key prefix, once the prefix is not the login |
| minio | a bucket derived from `login`, and a service account whose access key is `login` | the access key; the bucket **only if empty**. A bucket holding objects is left, and the failure logged | yes, by removing the access key and adding it again, which leaves a moment with no key | no, but an access key *is* the login: a second key is a second login | yes, two service accounts with one bucket policy. The access key is capped at 20 characters |
| lavinmq | a virtual host named `login`, and a user named `login` with permissions on it | the virtual host, with any queued messages, and the user | yes, the user is written again with the password | no: a user has one password | yes, permissions for two users on one virtual host |
| mosquitto | a client named `login`, with a role named for it on the topic prefix `login/#` | the client and its role | yes, the password is set when the client exists | no: a client has one password | yes, two clients holding one role, once the prefix is not the login. The MQTT client identifier is chosen by the consumer, not tied to the login; a duplicate one takes the older session over |
| mailu | a mailbox `login@domain`, unless the consumer contributes its own account name | the mailbox with its mail, for a login-named one; a contributed name is left for an operator | yes, the password is set when the user exists | no for the password; a user can hold several authentication tokens, per the backend's documentation | **no**: a mail user *is* its mailbox |
| gitea (npm) | a user named `login` on a team of an organisation that owns every package | the user; **packages survive**, because the organisation owns them | yes, the user's password is set on every run | no for the password; a user can hold several access tokens | yes, trivially: a second member of the same team |
## The other providers
| provider | answers with | credential |
|---|---|---|
| umami | a website, found by its public name | none. The site id it makes has no way back to the consumer today |
| cloudflare-dns | a public name derived from `login` | none handed to the consumer; its own API token is an operator value |
| showcase | a route | none |
| mesh-vault | custody: it records and withdraws sealed values in a ledger | it holds secrets; it makes none today |
verdaccio provides the npm registry too, and has no provisioner.
## Each provider's own administrative credential
| provider | identity | how the backend takes it |
|---|---|---|
| postgres | a fixed superuser | from a file **only at first initialisation** |
| mssql | `sa` | from the environment at first setup. The image documents no file form, and the definition records that as a declared exception |
| mongodb | a fixed `root` | from a file **only at first initialisation**, when the data directory is empty |
| mosquitto | a fixed admin client | seeded into the broker's dynamic-security file **once**; the seeding step skips when the file exists |
| lavinmq | a fixed admin name | per its own bootstrap code, **only on a first boot** with an empty data directory. No resource in the definition runs that bootstrap; what sets it on a running mesh is outside the catalogue |
| redis | the default user | from `requirepass` in a configuration the mesh renders, read when the server starts |
| minio | a fixed root user | from a file, read when the server starts |
**In five of seven, a new administrative value takes effect only through a command run with the old
one.** The credential file is mounted directly into both the server and the provisioner. So replacing
it recreates the provisioner, which then holds only the new value while the backend still expects the
old one, and the provisioner is locked out. That is worse than changing nothing.
Every provider module also has its own bus account, an own secret, read at start.
## What the tables show
1. **Every credential provider already rotates in place.** All nine re-apply the password on the
same login each time `create` runs. The controller's `rotate` command relies on that: it replaces
the credential in the inventory and sends both ends in one push. Its own comments state the window,
between the provider applying and the consumer restarting, in which the consumer cannot
authenticate.
2. **Eight of nine name the consumer's resource after its login.** Only gitea separates them,
because an organisation owns the packages. A second login therefore has no resource of its own to
reach, and cannot share the first one's without the adapter granting it.
3. **Five of nine destroy the consumer's data when they remove the login**: postgres, mssql and
mongodb drop the database, lavinmq drops the virtual host with its queued messages, and mailu
deletes the mailbox with its mail. minio drops only an empty bucket, and redis leaves the keys. In
those five, *retire a login* and *delete the consumer's data* are one call. With the harness keyed
by login, a changed login triggers it too.
4. **One backend holds two passwords on one login** (redis). Two hold several tokens beside one
password (gitea and mailu). A rotation built on two secrets per login would work for three
providers out of nine.
5. **Eight of nine can give two logins the same rights over one resource.** Group roles in postgres,
database roles in mssql and mongodb, permissions in lavinmq, a shared role in mosquitto, a shared
policy in minio, a shared key prefix in redis, a shared team in gitea. mailu cannot, because its
user is its mailbox, but it can give one user a second token. So every provider can hold **two
credentials** over one resource, though not every one as two logins. No adapter does either today.
6. **Ownership is a trap in two backends.** In postgres whatever a login creates is that login's, so a
second login cannot alter the first one's tables, and the first cannot be dropped while it owns
them. The one-step way out deletes them. In mssql, a login cannot be dropped with a session open,
nor its user while it owns a schema.
7. **The administrative credentials have one party and a fixed name**, and five backends take them
only at first initialisation. The provisioner needs the old and the new value at once to change
them. Today nothing can give it both.
8. **A consumer's identity is already the resource's name.** The login is derived from the
assignment, which is a module on a node, so the current login and "the consumer" are the same
string today. A second login would need a new name. The resource can keep the one it has.
## Seen on the way
The redis configuration names no ACL file, so a consumer's ACL user exists only in memory. A restart
of the redis server erases every consumer's user. The provisioner does not create them again until it
restarts itself, because its in-memory record says they are done. That is not a rotation finding, but
it is a live fault, and it is recorded here so it is not lost.
The operator's wish, written as behaviour: what a person or an agent sees the mesh doing. This is a
target to design toward, not a design. Every part of it is to be decided through a record before it
is built.
## Principles
**1. Every loop compares what should be with what is, never with what it did.** Desired state is the
mesh's: assignments, requirements, seats. Observed state is read from the thing itself: the container,
the backend, the node. A loop that compares against its own memory of what it applied is blind to
anything that changed behind its back. That is issue 120, and it is the pattern this whole effort is
written against.
**2. Healing is the ordinary path run again, never a second path.** Repairing a lost login is
provisioning it. Repairing a dead container is converging the node. Repairing a stale declaration is
delivering it. A repair that needs its own code is a second way of doing something, which is exactly
what the mesh is removing everywhere else.
**3. A repair never destroys.** Healing may recreate, re-provision, re-deliver and restart. It may
never delete a consumer's data, retire a credential someone still uses, or pick a winner between two
contradictory states. Where the only repair is destructive, it is escalated.
**4. Nothing fails silently.** Every condition the mesh cannot repair within its budget becomes
visible. It is named, it says since when, why, and who can resolve it. It is visible until it is
resolved, and resolved by observation, not by someone clicking it away.
**5. What the mesh cannot fix goes to an agent.** Per the mission, an agent may be human or not. A
condition that needs judgement is handed to one, as work, with what the mesh knows. It is not handed
over as a notification that someone may or may not read.
**6. Correctness, not only liveness.** A running process that authenticates with a dead credential,
serves an old version, or routes nowhere is not healthy. What a provision's contract promises is what
is checked: the credential authenticates, the route answers, the version is the declared one.
## The loop, everywhere
Every part of the mesh that owns something runs the same loop:
1. **know** what should be true: from assignments, requirements and seats;
2. **observe** what is true: from the thing itself, on its own cadence;
3. **repair** the difference by running the ordinary path again, within a budget of attempts and
time;
4. **raise** a *condition* when the budget is spent or the only repair is destructive;
5. **clear** the condition when observation shows it resolved.
A **condition** is a durable fact about something the mesh owns, such as a node, an assignment, a
provision, a seat or a rotation: what is wrong, since when, the evidence, what was tried, and who can
resolve it. Conditions are the one thing a person or an agent looks at to know whether the mesh is
right. `status` is the list of open conditions. When it is empty, the mesh is right, not just up.
## On NATS
[ADR 0106](../../02-DECISIONS/0106-the-bus-is-nats.md) moves the bus to NATS, and NATS makes most of
this cheaper, because observation becomes something every component publishes rather than something
a central process polls.
| the wish needs | on NATS |
|---|---|
| every component says it is alive | a heartbeat on a subject per node and assignment; silence past its interval is a condition, and nobody polls |
| every component says what it observed | observations published on subjects (`mesh.observed.<node>.<assignment>`, for instance), consumed by whoever owns the comparison |
| the last known state survives restarts | a JetStream key-value bucket of observed state per owner; the provisioner's "what I applied" and a rotation's step live there, not in memory |
| conditions are durable and watchable | conditions as entries in a key-value bucket, watched by anyone who cares: a surface, an agent, the controller |
| the bus itself is observed | the server's advisories (a consumer exceeding its deliveries, a slow consumer, a client disconnecting) and its monitoring endpoint become observations like any other |
| a repair is retried, not lost | JetStream redelivery with delay, which is the same mechanism [ADR 0083](../../02-DECISIONS/0083-one-push-leaves-the-mesh-consistent.md)'s guarantee moves to |
| work handed to an agent | a condition that needs judgement published as a task on a subject an agent's queue group consumes |
**Who compares.** Each owner compares its own: the host for its node's containers and files, a
provisioner for its backend, the vault for rotations, the controller for delivery and seats. The
controller's observability context does not repair anything. It holds conditions, their history,
and the view across the mesh. It notices what no owner can see about itself: an owner gone silent.
## What stays human
Some repairs need the operator's key, and the mesh says so rather than pretending otherwise:
re-raising the vault or the broker, and recovering a node's identity. These are conditions too, with
the procedure named, and they are the only ones that can never clear themselves.
## Open
- The budgets: how many attempts, over how long, per kind of repair.
- How a condition that needs judgement reaches an agent, and how the agent's action is recorded.
- Where the observability context stores history (to-be 06 left it open; volume argues against the
relational store).
- Which correctness probe each provision's contract offers, and how often it runs.
*Measured 2026-10-02 on one installation: two workstations, two servers, all four converged to
the mesh; the predecessor retired on the last workstation the day before. Numbers are from the
machines and the repositories, not from memory.*
## 1. What the predecessor's desktop looks like
The predecessor's catalogue on the laptop held **34 modules**, of which **28** are the operator's
environment rather than services. By what they declare:
| shape | count | examples |
|---|---|---|
| package only | 9 | browser, mail client, process monitor, media player, file manager, chat |
| package + `/etc` files + system service | 5 | login manager, display server, power and thermal daemons, package manager configuration |
| package + files under the home | 6 | shell and prompt, the agent at the terminal, scripts, the sync client, a music player |
| files under the home + user units + hooks | 2 | the desktop environment, audio |
| third-party organisation tooling | 6 | out of scope here |
**The desktop module alone** declares **88 files**, **4 flavors** (the window-manager stack, and
one per class of machine), **2 user units** with a hook to enable them, 8 files under `/etc`, a
wallpaper shipped as an asset, and reads **about 90 environment variables** as theme knobs,
substituted into its templates at sync time and set through a theming tool. Its hook exists
because *shipping a unit file does not run it*: one unit had been deployed for months and ran on
one machine only, because somebody had enabled it there by hand.
**The shell module** ships `~/.zshrc`, the prompt configuration, an `~/.ssh/config` that the
predecessor generated from its registry, and a `LOGIN_SHELL` variable applied with `chsh` by a
hook. Two flavors: the prompt theme, and autocompletion.
**Other modules write into the desktop module's files.** The chat client places i3 and notifier
snippets into `config.d` directories the desktop module owns, and its launch flags, window
placement and notification colours are each a variable with a default.
**One-off steps live in hooks** across the set: enable user units, `chsh`, create a swap file,
`mkinitcpio`, enable a vendor VPN service the package ships disabled. Every one is state the
host could declare or a verb a seat could serve; none is today.
## 2. What the migration did with them
The migration's module to-do scoped the whole set out as *desktop / workstation ricing — the
workstation's own environment* and *node/OS tooling — managed on the node, never catalogue*. The
last workstation's runbook then split the same set three ways: **A**, system scope, which the
host's vocabulary can express today (the login manager, the display server, the power daemons,
the package manager, the container runtime); **B**, under a home or a user unit, waiting on
to-be 29; **C**, package only, the operator's call. The migration log closes the workstation with
*the operator's desktop awaiting its design*.
Two things followed from scoping them out. Nothing regenerates those files now, so a fix is a hand
edit — the login manager's session script was fixed this way on the day of writing, and recorded
in a repository nothing deploys from. And the one piece of this family written as a mesh module,
the ssh client, was closed on hold in the catalogue until the controller carried the account fact.
## 3. What the records already give
| wanted | record | state |
|---|---|---|
| one module per managed thing; every module may have tools | [ADR 0040](../../02-DECISIONS/0040-what-a-module-is.md) | accepted; examples are services, and the shell is named as a *shared* seat |
| a module declares its own node-scoped seat | [ADR 0121](../../02-DECISIONS/0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md), [ADR 0126](../../02-DECISIONS/0126-a-module-declares-its-own-seats.md) | accepted |
| a seat's contract is its tools; a holder may add its own | [ADR 0132](../../02-DECISIONS/0132-a-seat-carries-the-tools-its-holder-must-serve.md), [ADR 0170](../../02-DECISIONS/0170-the-firewall-seat-serves-its-verbs.md) | accepted; one node seat serves verbs live |
| a capability the machine reports gates a holder | [ADR 0161](../../02-DECISIONS/0161-what-deserves-a-seat.md) §3 | accepted; the profile already reports `graphical-session` |
| the account as a node fact; a file under the home owned by it | [to-be 29](../../03-DESIGN/01-to-be/29-a-node-has-operator-accounts.md) §1–2 | built in the controller; its record proposed in an open change |
| inside a home: owned, written into, written by the module, found | proposed in the same change | proposed |
| a setting declared with type, meaning, default and cost | proposed with the container-runtime records | proposed |
| a managed file is derived; an edit is overwritten | [ADR 0011](../../02-DECISIONS/0011-managed-files-are-generated-never-edited.md) | accepted |
| the mesh writes into a shared file, never over it | [ADR 0102](../../02-DECISIONS/0102-the-mesh-writes-into-a-shared-file-never-over-it.md) | accepted |
| a module names no path; the host resolves the home | [ADR 0112](../../02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md) | accepted |
| the `user` shape: a login shell is declared state | [to-be 05](../../03-DESIGN/01-to-be/05-the-node-host.md) | designed; used by no module |
## 4. What is missing
1. **The account is recorded nowhere.** The node record has the column; on all four nodes it
is empty. Every home-scoped module is unassignable until the operator states it.
2. **User-scoped units.** The host's `service` shape has no user scope. To-be 29 says it
plainly: *a workstation's per-user daemons have no form the mesh can send.* The desktop
module's two units, the audio masks, the power module's memory guard and the thermal
daemon's profile switcher all need it.
3. **One-off steps.**`mkinitcpio`, `chsh`, creating a swap file. Each is either declared
state the host lacks a shape for, or a verb a seat should serve. An action in a declaration
one supervised process per module, under the module's own account, carrying that module's
compiled tools. Measured on the live mesh:
| who answers | how it runs | count |
|---|---|---|
| the mesh's own verbs | the controller binary, on its node | 17 verbs |
| the store seat | the store's own runtime | 2 verbs |
| the packet-filter seat | **a container per node**, built on the tool-runtime base image, with the network namespace and `NET_ADMIN`, on all four nodes | 3 verbs and 1 own tool |
| every module's own tools | the module's container, one per node it runs on | 67 tools across the catalogue |
| the console | a container per node, loopback MCP, `invokes: *` | serves none, calls all |
| the host | — | serves nothing; answers no question about the machine |
**The packet-filter holder is the case to look at.** The module is a package, three files and a
system service. To serve three verbs it also declares a built image and a container on every
node whose only job is to answer them. Scaled to the environment — a shell, a prompt, a launcher,
a notifier, a compositor, a login manager, a service manager, a boot loader, a downloads folder —
that is one container per module per node for software that is itself not a container, and the
operator's judgement is that tools should not run inside a container at all.
## The direction
**One tool executor per node, on the host side.** A process the host supervises, the way the
launcher supervises the host ([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)): not a
container, one bus credential for the node, module-agnostic. It loads the tool code of every
module assigned to the node and serves each module's tools and each held seat's verbs on the
subjects the membership issues — nothing changes in what [ADR 0159](../../02-DECISIONS/0159-a-tool-call-names-the-machine-and-a-holder-serves-its-seats-verbs.md)
and [ADR 0160](../../02-DECISIONS/0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md)
say about subjects, grants and memberships; what changes is that one process subscribes for the
node instead of one per module.
- **A module brings its tools as a built artifact**, a bundle the pipeline produces, never an
image. The executor knows bundles and subjects; it knows nothing of zsh or nftables.
- **A tool is code the module wrote**, one function behind an MCP verb. `execute` on the shell
seat is a function with a string argument. The executor does not declare, template or
interpret tools; it runs them.
- **Root is the module's concern.** A tool that must change the packet filter or rebuild boot
images escalates itself. The executor does not run as root for everyone, and the caller does
not know.
- **Any node may call any tool on any node.** The executor's credential may call everything,
as the console's already does; per-module grants on the calling side are not kept.
- **The mesh's own verbs stay with the controller** ([ADR 0154](../../02-DECISIONS/0154-the-meshs-own-verbs-are-the-controller-seats-tools.md)),
and a mesh-scoped seat's verbs run on the node that holds it
No hub is added; the controller's node is already one.
**The console is the executor, renamed.** It already runs on every node with a credential that
may call everything, and it already serves the mesh's tools to whoever is on the machine over
MCP on loopback ([ADR 0152](../../02-DECISIONS/0152-the-operators-surface-is-a-module-the-console.md)).
It moves out of its container into the host's process tree, gains the serving half, and takes a
name that says what it is — *the node's tool runtime* or simply *node tools*; "console" names
the operator's half only.
## What it supersedes, and what it keeps
| record | effect |
|---|---|
| [ADR 0047](../../02-DECISIONS/0047-a-module-runs-its-code-as-its-own-process-with-its-own-account.md), [ADR 0150](../../02-DECISIONS/0150-a-modules-own-code-runs-as-supervised-processes-under-one-account.md) | superseded *for tools*: one process per node runs every module's tool code, under one account. A module's long-running service — a daemon, a container — is untouched; the executor runs tools, not services. The record must say why one account for every module's tools is acceptable: every tool may be called from every node anyway, and root is taken by the tool, not granted to the process |
| [ADR 0152](../../02-DECISIONS/0152-the-operators-surface-is-a-module-the-console.md) | kept in substance — a module, assigned per node, loopback MCP, the machine's login is the authority — changed in form: host-side, not a container; serves as well as calls; renamed |
| [to-be 33](../../03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md) §6, [to-be 34](../../03-DESIGN/01-to-be/34-the-console.md) | amended the same way |
| [ADR 0170](../../02-DECISIONS/0170-the-firewall-seat-serves-its-verbs.md) §3, *a container may ask for a capability* | moot for that holder: the verbs run on the host side and escalate as they need |
| the container-runtime seat, proposed in an open change: *the holder runs as a supervised process and serves the verbs locally to the host and on the bus* | consistent — a supervised process serving verbs is what the executor is; the open question is whether that holder keeps its own process or serves through the executor like everyone else |
| the tool-runtime base image | no longer the way tools reach a node; may remain the way a module's *service* is built |
## What stays open
- **The executor's language.** The host is a static Go binary and loads no plugins, so the
executor is a sibling process, and its language decides the language of every tool bundle.
One decision, taken once.
- **How a bundle reaches the node.** An artifact of the module's build, delivered as the host
delivers everything else; whether it is a file resource in the declaration or a thing the
executor fetches by digest.
- **Reload.** A push that adds or upgrades a module's bundle reaches a running executor as a
reload, not a restart, or every tool on the node blinks on every push.
- **The host's own questions.** [Issue 160](../../04-ISSUES/160-a-machine-says-little-about-itself-and-only-when-asked/00-report.md)
wants a machine to say more about itself. With an executor on every node, "what is this
machine made of" is a seat verb like any other, served there.
learn the things their container used to be handed: where the module's configuration file is, where
its token or password is, which port the service listens on, where a provision's address is written.
A container is given these as an environment and mounts, composed by the mesh per module per machine.
A bundle has no environment of its own: the runtime's process carries four words for every bundle it
loads, and nothing per module ([design 38](../../03-DESIGN/01-to-be/38-building-the-operators-machine.md) WP4).
## Why
Two holders moved on 2026-10-03 — the packet filter and the intrusion prevention — and both could,
because neither needs anything but a fixed path and root. Of the thirty-three modules whose tools
still run as containers on the runtime's image, thirty-one are not like that: their environment
names a configuration file, a credential file, a service address, a grants directory. Moving them
one by one without a rule for this would give the mesh thirty-one answers to one question. The
measurement and the options are in [01](01-what-the-containers-are-given.md).
## What it touches
The runtime (which hands a bundle what it is given), the composer (which resolves `${dir:…}` and
`${port:…}` for a container today and would for a bundle), the manifest (where a bundle would say
what it needs), and design 38, which records the gap and must say the rule once there is one.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.