Compare commits

..
Author SHA1 Message Date
jschoubben 3a969c6b99 Designs 33 and 08: the converged answer carries the node's links (H-A-325) 2026-11-21 21:14:05 +01:00
jschoubben da58998af4 Designs 08 and 33: no interface never opens an outward link (H-A-324) 2026-11-21 21:11:18 +01:00
jschoubben 41005dfc1e Designs 08 and 33: the build's forms (H-A-317 to H-A-321) 2026-11-21 20:53:37 +01:00
jschoubben 8fc4f09d8f Designs 08 and 33: the reviews by domain (H-A-314, H-A-315, H-A-316) 2026-11-21 20:43:11 +01:00
jschoubben 654a08b5a0 Designs 08 and 33: an adopted node refuses allowances; expired ones removed at the holder's start (H-A-312) 2026-11-21 20:39:52 +01:00
jschoubben 9dcbc0fef1 Designs 08 and 33: ADR 0683's number, the allowance's identity and expiry, the verbs required from the start 2026-11-21 20:34:01 +01:00
jschoubben 9e99e9562b Designs 08 and 33: the firewall seat's control verbs beside the derived ports (the operator, 2026-11-21)
The operator decided that the packet filter's module must have tools to
control it beside what is derived from the modules' declarations: deriving
every open port from listens left no way to open a port no manifest names.

Design 08 section 4 keeps the derived ports as the automatic part and adds
allowances set by hand; the node-engine stays the one renderer, asks the
holder's allowed verb at every compose, refuses the compose and keeps the
loaded filter when it gets no answer, and renders allowances only on a
converged node. Design 33 gives the seat allow, disallow and allowed,
widens rules, and adds the event allowances-changed and the holder's
state: one allowance per protocol, port and interface, removed and
journalled at its expiry. Both follow ADR 0683 and design 47 H's lead
answers H-A-304, H-A-305, H-A-307 and H-A-308.

Both designs are put in playbook 02's shape: their new lines live in
milestone parts, and design 08's adoption lines move to a delivered part
so the main file stays under 80 KB. The glossary gains allowance.
2026-11-21 20:33:52 +01:00
19 changed files with 419 additions and 3617 deletions
-55
View File
@@ -1,55 +0,0 @@
---
name: hand-pack-builder
description: Builds one hand pack of the Novox mesh - a folder holding one module's bundle (or a few), built from a repository commit the way the Go build module builds it, with SHA256SUMS, the build script and NOTES.md naming the exact placement steps - for a hand placement the lead says to the operator first. Places it on a node only when the caller asks for that in a later message. Never builds in a developer's worktree, never commits or pushes in a code repository.
tools: Read, Grep, Glob, Bash, Write, Edit, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search, SendMessage
model: opus
---
You build one hand pack for the lead who started you. A hand pack is a folder of built artifacts that a person puts on
a node by hand, a hand act, when the delivery cannot bring them: most often a circle, where the fix is the very bundle
the node-engine cannot fetch or the pipeline cannot pass without it. The handover names the module and its artifacts
(`<module>:<artifact>`), the repository and the commit, the node, the pack's folder, the pack it is built like, and the
read that confirms the cause.
**Confirm the cause first, read only.** Before you build, do the read the handover names: the seat's verb through the
mesh MCP server (`mesh_search` finds it), the store or the journal it names. Say what it answered, what that means, and
whether the pack answers that cause. When it does not, stop and report before building.
**Build like the earlier pack.** Read the earlier pack's NOTES.md and its build script or go.work files, and the pack it
points to. Then:
- Make your own worktree of the repository, detached at the named commit, under hq's `.work/` with the name the
handover gives; never build in a developer's worktree or a working copy's checkout. Siblings the build needs (the
mesh packages of other repositories) come from their `origin/main`, in worktrees of your own or in checkouts the
earlier pack used when they sit at `origin/main` and are clean; say each sibling's commit.
- Build as the Go build module builds: `CGO_ENABLED=0`, `GOFLAGS="-trimpath -buildvcs=false"`,
`-ldflags "-s -w -X main.builtFor=<system>"`, `GOTOOLCHAIN=local`, no version stamped, the mesh packages placed by a
go.work file kept in the pack. Run the unit tests of the packages the commit changed.
- Write the build as a script in the pack that refuses a worktree not at the commit and is loud on failure; run it
twice and say whether the sha256 is the same.
- Prove the artifact: a tools bundle answers `initialize` and `tools/list` over stdio (say the count and the tools the
fix concerns); a program carries what the fix adds (a string, a flag). When the delivery released the same commit
already, fetch the released artifact from the registry and compare: same source, and why the bytes differ if they do.
- Write `SHA256SUMS` over every file of the pack.
**NOTES.md says the placement whole**, so the lead can say it to the operator and a person can run it without asking:
- What each file is, from which repository, commit and directory, its size; the siblings and the toolchain.
- Why: the cause as read, with the digests or the lines read and the time read, and the circle the pack breaks.
- Where each file goes on the node, read from the unit or the tool runner's module list there (never assumed), with the
file's present sha256, owner and mode; the old file kept once beside it as `<file>.pre-h1`, the new one put with the
same owner and mode through a temporary name and a rename.
- Which units restart, in which order, and the check after each that must pass before the next step (a verb's answer,
a unit's state).
- How the node-engine's have of the module comes to the released fingerprint: read in the node-engine's code on main
whether it asks again on its own, on its verb `compose`, or only after a restart, and name the function that decides.
- The undo, and the notifications the steps may raise.
**Placing**, only when the caller asks for it in a later message, after the lead has said it to the operator: copy the
pack to the node, check `SHA256SUMS` there, run the steps of NOTES.md one by one and read each check; stop at the first
that fails and report it. Reading a node by a shell is allowed only on the days the operator allows it; otherwise
through the mesh MCP server alone.
Report in under 500 words: the cause's read and what it means, the pack's folder, its sha256 lines, the placement steps
in order, what you could not read or prove, and any finding (a fault the pack works around) for the lead to note on
the issue that covers it. Separate fact from guess, in the glossary's words.
+8 -3
View File
@@ -306,9 +306,7 @@ controller and the store; for module assignment, by the seat `mesh-module-assign
- **transport fault** — a failure of a call or a step because the part it asks did not answer for a moment, not
because of what it asked: a name lookup that timed out; a connection refused, reset or unreachable; a seat verb
answered with no responders while a holder of that seat is named in the assignments (ADR 0664 §1); and, for a call,
its own deadline passing (ADR 0668 §1); a holder's `away` to a seat ask, its word that a part it depends on did
not answer, naming that part (ADR 0668 §1, ADR 0664 §1, insights of 2026-11-21); and a 401 or 5xx answer of the forge to
a step's fetch of its source (ADR 0664 §1, insight of 2026-11-21). A build or check step that meets one is given again by the bus, at most
its own deadline passing (ADR 0668 §1). A build or check step that meets one is given again by the bus, at most
three runs (ADR 0664 §1, §2); a kept call is called again. A fault in what was asked (a compile error, an unknown
revision, a seat no holder is named for) is not one, and ends the step or the call at once.
*Not:* ~~transient error~~ (hq), ~~network blip~~ (hq)
@@ -1166,6 +1164,11 @@ it should not. **Recorded by** the controller. **Upstream of** Provisioning and
- **packet filter** — what the mesh enforces on a node about which packets pass, the
`node-packet-filter` seat and its verb `rules`. A **found firewall** is a program the mesh found on a
machine and keeps retired or in force; *firewall* says that, and a wrapped program's firewall is its own.
- **allowance** — a port of the packet filter opened by the operator, through the seat, beside the ports derived from
the modules' `listens`: set with the `node-packet-filter` seat's verb `allow`, taken back with `disallow`, read with `allowed`, each with
who set it, when, why and an optional `until`, at which it is removed, and rendered by the node-engine into a converged node's input chain
(design 08 §4, design 33). It is not an `opening`, the resource the node-engine converges through a found firewall.
*Not:* ~~pinhole~~ (hq), ~~hand rule~~ (hq)
- **intrusion prevention** and **ban** — refusing a source that misbehaved, and the refusal itself; the node seat
`node-intrusion-prevention` is of this domain.
- **reach** — how far an assignment's endpoint may be reached from: the node, the private network, or
@@ -1584,6 +1587,8 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
| | a human | **operator** or **person** | words every domain uses |
| firewall | what the mesh enforces | **packet filter** | Connectivity |
| | what was found on a machine | **found firewall** | Connectivity |
| allowance | a port of the packet filter opened by the operator, through the seat | **allowance** | Connectivity |
| | the share of model use every session draws on in a week (playbook 07's report) | **weekly allowance** | — |
| ticket | an answer's one-time token (ADR 0258) | **answer ticket** | Operator and conversation |
| | a question someone must answer | **issue** | The record |
| deploy | the per-node part of a delivery plan | **deploy plan** | Delivery |
+41 -92
View File
@@ -22,7 +22,7 @@ code:
- mesh-host internal/apply (the service that reflects a rule set; a whole file handed to its new owner)
- mesh-controller cmd/mesh-controller/nodes.go (a token issued for a machine's tunnel key, ADR 0169)
- mesh-host cmd/mesh-host/join_tunnel.go (a machine joins through the tunnel, ADR 0169)
updated: 2026-10-14
updated: 2026-11-21
decisions:
- "ADR 0241"
- "ADR 0117"
@@ -36,6 +36,7 @@ decisions:
- "ADR 0194"
- "ADR 0191"
- "ADR 0180"
- "ADR 0683"
- "ADR 0170"
- "ADR 0169"
- "ADR 0168"
@@ -696,10 +697,14 @@ program that reads it, and another proxy may implement the same file.
## 4 — Filtering
**Derived from what is assigned here, and from the private network's shape** — a node's open ports are a
consequence of what runs on it and who must reach it, not an independent declaration to keep in
step by hand. That is true of a converged node; an adopted one keeps the firewall it was found
with until it converges (below).
**Derived from what is assigned here and from the private network's shape, with allowances set by hand beside
them.** The automatic part of a node's open ports is a consequence of what runs on it and who must reach it, not a
declaration to keep in step by hand. Beside it, the holder of `node-packet-filter` keeps **allowances**: ports opened
by the operator, through the seat's verbs, each with who set it, when, why and an optional expiry, rendered into the same input
chain and surviving every render and restart; an allowance is removed at its `until` and said (ADR 0683,
the firewall's control verbs, amending ADR 0170; the operator, 2026-11-21; design 47 H's lead
answers H-A-304, H-A-305, H-A-307, H-A-308, H-A-310, H-A-312 and H-A-314 to H-A-316). That is true of a converged node; an adopted one keeps the firewall it was found
with until it converges, and takes no allowance (design 08 adoption §2 to §6).
**A rule names its source** (ADR 0007).
A rule with no source is open, and must say so rather than appear to restrict something. `scope:`
@@ -790,57 +795,25 @@ undeclared one does not — then the module is removed and the port closes with
rule. *A rule set that is written but never loaded passes every check that reads the file, which
is why the check reads packets.*
### While a predecessor still serves the same thing
### By hand, beside the derived ports
*2026-09-22, ADR 0104.*
The mesh's proxy owns the two public ports and derives its routes from what modules contributed, so
it cannot stand beside a predecessor's proxy and cannot serve the predecessor's names. During a
migration a provision of this shape — one provider, a scarce machine-wide resource — may instead be
answered by an **adapter**: a module that provides `route` and writes each contribution into the
predecessor's own configuration, pointing at the machine port the contributing module publishes.
The predecessor's proxy goes on serving every name and renewing every certificate; the mesh's proxy
is taken last, when every route is one the mesh contributed. The adapter is refused on a converged
node, and removed when the predecessor's proxy retires. *How it is checked:* the adoption bed takes
a module behind the adapter and asserts the name answers and the predecessor's own names still do.
*2026-11-21, ADR 0683.* Deriving every open port from the modules' `listens` left no way to open a port no manifest
names (a program the operator runs by hand on the workstation, for a while). One renderer stays: the node-engine
composes the filter file, and nothing else writes the input chain.
### On an adopted node
```
caller ── allow / disallow ──▶ node-packet-filter (holder) state allowances, one key per allowance
│ event node-packet-filter.allowances-changed (node)
▼
node-engine ── allowed ──▶ holder composes the filter: derived ports + allowances, input chain only
│ writes the filter file; the holder's unit loads it (reload)
```
*2026-09-22, ADR 0100.* **The firewall found on the machine stays in force**, and the mesh
loads no table there that drops by default or holds an accept — neither genesis's base ruleset nor
the derived one. Every base chain at a hook runs and a drop in any is final, whatever the other
firewall is written in, so a second, stricter table would close every port the machine serves, and
an accept in one would open nothing the found firewall drops. What the mesh needs reachable it
declares as **openings**: a port, from where, on the incoming path or the forwarded path — a
published container port is forwarded, and a firewall that filters only incoming traffic never
sees it. The controller derives them from what the filter would be derived from, each from where
the filter would admit it: the assigned modules' `listens`, the hub's port, the bus and the registry
from anywhere; the store's port and the broker's management port from the private network. The node-engine converges each opening through
the found firewall in that firewall's own terms, marks it as the mesh's, removes only what it
marked, and re-checks every opening on each reconcile so a reload or a reboot does not lose it for
longer than one reconcile. An opening is state, not a command, so it travels over the link like any
other resource. **The mesh guards its own ports in a table of its own that only refuses** —
passing everything by default and holding nothing but refusals, and the found firewall's reload
does not touch it. Its ports are derived (ADR 0103): every machine port a
*taken* module publishes that the filter admits from the private network only, with the store's
port and the broker's management port. A port of a module not yet taken may still be the
predecessor's, so it is not guarded; and only packets addressed to this machine are matched, so
traffic it routes for others passes. An opening a found rule already answers is not added, so
removing it never removes the operator's rule. It refuses those ports except from
the private network and the machine itself — loopback and the container runtime's networks, known by the interface a packet arrives on, never by
its source address alone — at
the prerouting hook, before the container runtime redirects the packet, so it matches the port the
packet was sent to, for both address families; the
bus, the registry and the hub's port stay reachable from anywhere, as a node enrols and pulls
before it has a private-network address. One kind of found firewall is spoken; a machine with none
needs no openings, and a machine with another kind is refused adoption. Converging the node refuses
while a found container is still held; otherwise it previews what is reachable now — listening
sockets and published ports — what will close and which modules it will take, then loads the
derived filter in place of the refusal-only table and disables the found firewall without flushing
it. *How it is checked:* the adoption bed asserts the found firewall's rules differ only by the
mesh's marked rules, that the store is unreachable from off the private network before and after
the found firewall reloads and reachable from a container on the node, that a machine not yet enrolled reaches the bus, that a second machine
enrols through the openings before and after a reload and a reboot, and that after the flip the
declared port is open and the undeclared one closed.
The holder keeps each allowance in its own state on the bus and says every change as an event; the node-engine of
that node hears it, asks `allowed` and composes the filter again. An unanswered `allowed` refuses the compose and
keeps the loaded filter, said once, never read as "nothing opened" (the rule for a generator above). Allowances are
rendered only into a converged node's own table. The seat's verbs and event are design 33's (*The firewall seat's
verbs*); every line the milestone builds is in [design 08 control-verbs](08-milestones/control-verbs.md).
### It filters what arrives from outside, and not what the machine's own guests send
@@ -1245,27 +1218,15 @@ The list is worth having in one place, because it is most of the argument:
## Open
- **One resolver (ADR 0194).** *Correction of fact,
2026-10-05:* no node holds `node-dns-resolver` any more, and
ADR 0220 deletes the seat. What stood here before: *"Not built: every node still runs
`node-dns-resolver`. The migration's four steps are in the record, in order."* Nor did it
stay true that *"the workstation moves to the one resolver only once"* zones and the `hosts` file's
holder (ADR 0199)
exist: every node, the workstation included, asks the one resolver, and every node holds
`node-hosts-file`.
- **One resolver (ADR 0194), settled** (2026-10-05): ADR 0220 deletes the seat `node-dns-resolver`; every node, the
workstation included, asks the one resolver and holds `node-hosts-file` (ADR 0199).
- **When the hub is down nothing takes over** (ADR 0006): non-co-located paths stop, co-located direct peers and
every assigned workload keep running; recovery is restore, before certificate renewal.
- ~~**What happens when the hub is down.**~~ **Resolved** by
ADR 0006, together with `06`'s
matching question — they were one question. Nothing takes over. WireGuard has no failover, the
hub is declared rather than elected, and non-co-located paths stop while co-located direct peers
and every already-assigned workload keep running. The recovery path is restore, and its deadline
is certificate renewal.
- **Renumbering the private network.** Made *possible* by declaring the hub rather than inferring it from
an address, but no procedure exists, and a graph delivered node by node has an ordering problem
while it is half-applied.
- ~~**Revoking a route** when a module is unassigned.~~ **Resolved** 2026-08-31 — see §3. The file
a proxy is given is the whole truth about who has a route, so a route does not outlive the module
that asked for it.
- **IPv6.** ADR 0007 makes
it expressible; nothing here says the private network or the resolver handle it.
- **Reporting declared-versus-observed.** ADR 0007 makes the disagreement detectable and does not
@@ -1276,28 +1237,6 @@ The list is worth having in one place, because it is most of the argument:
the composition is a per-node override rather than the design. The interpolation that would let a
module carry a label and a node carry the domain, and the mesh join them, does not yet exist.
## The hub adopts the predecessor's tunnel
*2026-09-23, ADR 0105.*
On an adopted node that is the hub, the private network is not raised beside the tunnel it finds;
it **takes it over**: the found interface's private key, its port, its address and range, and every
peer it had, carried as peers not yet enrolled. The found interface is stopped, its configuration
kept on disk. A predecessor machine sees the same server key at the same endpoint and cannot tell
the tunnel changed hands; when it enrols, it keeps the address the tunnel already held for its key.
The mesh's own addresses are the adopted range's — every binding, hosts entry and endpoint the
controller composes follows it, as readers of a setting. ADR 0100's non-overlap rule applies only
where a found tunnel is left running beside the mesh's; where it is adopted there is one tunnel.
The guard admits the mesh's ports from that one interface, and the predecessor's peers arrive on
it.
*2026-09-27, ADR 0119.* The
found configuration is kept only until the take is proven — the found unit down, the mesh's
interface up and handshaking with a peer. Then it is removed from where the found unit reads it
(its original stays kept), the hold ends, and the predecessor's tunnel cannot be raised again by
anything but a person restoring it by hand. Undeclaring the private network does not bring it back.
## The bus is NATS
*2026-09-23, ADR 0106. Architecture to be written
@@ -1308,3 +1247,13 @@ NATS account with permissions derived from `emits`/`consumes`, declared as confi
writes and the server reloads. The sdk's contract is unchanged. The adopted AMQP broker stays as
the predecessor's compatibility broker until its last client is gone. Built in the lab beside the
migration; cut over in one switch-over after the core; the person's client is designed on it.
## Milestones
Each milestone's lines are in its part, cited as "design 08 <milestone> §n"; the rest of this file records what was
built before milestone parts existed.
| Milestone | Part | State |
|---|---|---|
| adoption: a node the mesh adopted, before it converges (ADR 0100, 0103, 0104, 0105, 0119) | [adoption](08-milestones/adoption.md) | delivered |
| control-verbs: allowances set by hand beside the derived ports, built in design 47's milestone H (ADR 0683) | [control-verbs](08-milestones/control-verbs.md) | to build |
@@ -0,0 +1,79 @@
---
layer: to-be
design: 08
milestone: adoption (delivered)
updated: 2026-11-21
decisions:
- "ADR 0100"
- "ADR 0103"
- "ADR 0104"
- "ADR 0105"
- "ADR 0119"
---
# Design 08, milestone adoption — a node the mesh adopted, before it converges
**What it built.** How the mesh stands beside what it found on an adopted node: a predecessor's proxy, the found
firewall and the predecessor's tunnel, each until the node converges. This part is delivered: it records what was
intended, moved whole from the main file when design 08 was put in the shape of playbook 02 (2026-11-21), and no
builder reads it again. Cited as "design 08 adoption §n".
## Lines
1. **While a predecessor still serves the same thing, an adapter answers the provision** (2026-09-22, ADR 0104).
The mesh's proxy owns the two public ports and derives its routes from what modules contributed, so it cannot
stand beside a predecessor's proxy and cannot serve the predecessor's names. During a migration a provision of
this shape (one provider, a scarce machine-wide resource) may instead be answered by an **adapter**: a module
that provides `route` and writes each contribution into the predecessor's own configuration, pointing at the
machine port the contributing module publishes. The predecessor's proxy goes on serving every name and renewing
every certificate; the mesh's proxy is taken last, when every route is one the mesh contributed. The adapter is
refused on a converged node, and removed when the predecessor's proxy retires. *How it is checked:* the adoption
bed takes a module behind the adapter and asserts the name answers and the predecessor's own names still do.
2. **On an adopted node the found firewall stays in force** (2026-09-22, ADR 0100), and the mesh loads no table
there that drops by default or holds an accept: neither genesis's base ruleset nor the derived one. Every base
chain at a hook runs and a drop in any is final, whatever the other firewall is written in, so a second, stricter
table would close every port the machine serves, and an accept in one would open nothing the found firewall
drops.
3. **What the mesh needs reachable it declares as openings**: a port, from where, on the incoming path or the
forwarded path (a published container port is forwarded, and a firewall that filters only incoming traffic never
sees it). The controller derives them from what the filter would be derived from, each from where the filter
would admit it: the assigned modules' `listens`, the hub's port, the bus and the registry from anywhere; the
store's port and the broker's management port from the private network. The node-engine converges each opening
through the found firewall in that firewall's own terms, marks it as the mesh's, removes only what it marked, and
re-checks every opening on each reconcile so a reload or a reboot does not lose it for longer than one
reconcile. An opening is state, not a command, so it travels over the link like any other resource. An opening a
found rule already answers is not added, so removing it never removes the operator's rule.
4. **The mesh guards its own ports in a table of its own that only refuses**: passing everything by default and
holding nothing but refusals, and the found firewall's reload does not touch it. Its ports are derived (ADR
0103): every machine port a *taken* module publishes that the filter admits from the private network only, with
the store's port and the broker's management port. A port of a module not yet taken may still be the
predecessor's, so it is not guarded; and only packets addressed to this machine are matched, so traffic it routes
for others passes. It refuses those ports except from the private network and the machine itself (loopback and
the container runtime's networks, known by the interface a packet arrives on, never by its source address alone)
at the prerouting hook, before the container runtime redirects the packet, so it matches the port the packet was
sent to, for both address families; the bus, the registry and the hub's port stay reachable from anywhere, as a
node enrols and pulls before it has a private-network address.
5. **One kind of found firewall is spoken**; a machine with none needs no openings, and a machine with another kind
is refused adoption.
6. **Converging the node refuses while a found container is still held**; otherwise it previews what is reachable
now (listening sockets and published ports), what will close and which modules it will take, then loads the
derived filter in place of the refusal-only table and disables the found firewall without flushing it. *How
lines 2 to 6 are checked:* the adoption bed asserts the found firewall's rules differ only by the mesh's marked
rules, that the store is unreachable from off the private network before and after the found firewall reloads
and reachable from a container on the node, that a machine not yet enrolled reaches the bus, that a second
machine enrols through the openings before and after a reload and a reboot, and that after the flip the declared
port is open and the undeclared one closed.
7. **The hub adopts the predecessor's tunnel** (2026-09-23, ADR 0105). On an adopted node that is the hub, the
private network is not raised beside the tunnel it finds; it **takes it over**: the found interface's private
key, its port, its address and range, and every peer it had, carried as peers not yet enrolled. The found
interface is stopped, its configuration kept on disk. A predecessor machine sees the same server key at the same
endpoint and cannot tell the tunnel changed hands; when it enrols, it keeps the address the tunnel already held
for its key.
8. **The mesh's own addresses are the adopted range's**: every binding, hosts entry and endpoint the controller
composes follows it, as readers of a setting. ADR 0100's non-overlap rule applies only where a found tunnel is
left running beside the mesh's; where it is adopted there is one tunnel. The guard admits the mesh's ports from
that one interface, and the predecessor's peers arrive on it.
9. **The found tunnel's configuration is kept only until the take is proven** (2026-09-27, ADR 0119): the found
unit down, the mesh's interface up and handshaking with a peer. Then it is removed from where the found unit
reads it (its original stays kept), the hold ends, and the predecessor's tunnel cannot be raised again by
anything but a person restoring it by hand. Undeclaring the private network does not bring it back.
@@ -0,0 +1,107 @@
---
layer: to-be
design: 08
milestone: control-verbs
updated: 2026-11-21
code: [mesh-host internal/compose (the filter's compose), mesh-catalog modules/nftables, mesh-networking modules/mesh-connectivity-contracts]
decisions:
- "ADR 0683"
- "ADR 0170"
- "ADR 0168"
- "ADR 0595"
- "ADR 0100"
---
# Design 08, milestone control-verbs — allowances set by hand, rendered beside the derived ports
**What it builds.** The packet filter of a converged node opens, beside the ports derived from the modules' `listens`,
every **allowance** the holder of `node-packet-filter` keeps: a port opened by the operator, through the seat, with
who set it, when, why and an optional `until`. The node-engine renders both into the mesh's own table, in the same
input chain, at every compose of the filter; an allowance survives every render and restart, and one with an `until`
is removed at its `until`, by the kernel in the loaded filter and by the holder in its state. This follows ADR 0683
(the firewall's control verbs, amending ADR 0170) and the operator's word of 2026-11-21 20:35 CET (the packet filter's
module has tools to control it beside the automatic provisioning from declarations), written from design 47 H's lead
answers H-A-304, H-A-305, H-A-307, H-A-308, H-A-312, H-A-314 to H-A-316, H-A-321, H-A-324 and H-A-325. The seat's verbs, its event and
its state are design 33 control-verbs; this part holds the render. Cited as "design 08 control-verbs §n".
**Where.** Built in design 47's milestone H, in one delivery group with design 33 control-verbs, three repositories:
the networking repository (the seat's contracts module), the catalog repository (the nftables module, the holder)
and the node-engine's repository (the compose of the filter, the verb `converged`). The ordering edge is the served
verb: the node-engine asks `allowed`, so the holder serving it comes first in the delivery plan. First use: tcp 8000
on the workstation's home-network interfaces.
## Lines
1. **The node-engine is the one renderer of the filter file** (H-A-305; P7). At every compose of the packet filter
(each compose it makes today, and each one line 3 starts) it asks `<node>/node-packet-filter.allowed` of its own
node, within its compose-ask bound, the node-engine's setting `compose-ask-bound`, default 10 s (H-A-314 (5)), and
renders the answer's allowances beside the derived ports. The node-engine's manifest invokes
`seat:node-packet-filter.allowed` and consumes `node-packet-filter.allowances-changed` (H-A-314 (3), H-A-315 (2)).
Nothing else writes the input chain: the holder writes no rule and loads the file as today (`reload`, ADR 0170
§3). The derived part is unchanged: the modules' `listens`, the hub's port, the foundation's ports and their
sources stay as §4 *What was built* says.
2. **Where an allowance is rendered.** In the mesh's own table (family `inet`, name `mesh`), its input chain, after
the derived ports' rules and before the chain's drop policy: one accept rule per allowance, matching its protocol
and destination port; its interface by name, or for the default set (resolved here at compose, H-A-308 (1)) every
input interface that is neither the private network's tunnel nor an outward link (a hub's internet-facing link
included; H-A-324), rendered as a negated match on the tunnel and on each outward link the node reports (§4, *It
filters what arrives from outside*), so an interface that comes up later is covered and neither the tunnel nor an
outward link ever is; the node-engine serves the same classification, the tunnel and the outward links, in its
verb `converged` (design 33 control-verbs §10; H-A-325), so one classifier of links serves the render and the holder; an outward link is opened only by an allowance that names it; its source when it has one, for the family of its CIDR, and no
source match when it has none (both families). An allowance with an `until` matches its port as the one element of
a set of the mesh's table with the `timeout` flag, the element's timeout the time left to its `until` at the
compose, at least 1 s, so the kernel closes the port at its `until` even while the holder is away (H-A-315 (4)); a re-render reloads the
filter and re-arms the time left, which is the right time (H-A-324).
Each rule carries the comment `allowance <key> <at>`, the allowance's key as its answers give it (without the node) and
the time it was set (design 33 control-verbs §7, §9). An allowance opens the input path only: a container's published port is
forwarded traffic and stays its module's `listens`' (§4, *It filters what arrives from outside*). An allowance and
a derived rule on the same port are both rendered; neither removes or narrows the other.
3. **The node-engine composes the filter again on every change of the allowances.** It hears the event
`node-packet-filter.allowances-changed` on the subject of its own node (design 33 control-verbs §8), asks `allowed`
and composes the filter; no timer and no poll. The event's body is not rendered: `allowed`'s answer is the one
input, so an event missed is made good at the next compose. The node-engine drops nothing past an `until` on its
own clock: the holder's answer is the truth (H-A-314 (6)).
4. **An unanswered `allowed` refuses the compose and keeps the loaded filter** (H-A-307 (1), H-A-314 (7), H-A-315
(6); the rule for a generator that cannot say what it opens, §4). When `allowed` does not answer within the
compose-ask bound or answers an error (the holder not running yet, its tool runner away, no holder on the node, a
rolled-back holder that does not serve the verb, a laptop asleep), the node-engine composes no filter file and
keeps the one loaded. The refusal is a withheld part in H-A-306's form: the node-engine seat's composition answer
gains the field `withheld-parts`, a list of `{part, why}`, set when a compose kept a part because its read did not
answer, here `part` `node-packet-filter.allowed`; it is added in the same contracts commit as the verb `converged`
(H-A-321). It is said once in the journal and in `<node>/node-engine.composition`, never "nothing opened". The
holder's module is not held for it, since an old holder that does not serve `allowed` must still be replaceable;
only the filter file resource is kept as it runs. The next `allowances-changed` (the holder says `started` when it starts serving, design 33 control-verbs
§8) or the next compose tries again; by hand it is recovered with the node-engine's compose verb, and the composed
file is loaded with `reload`.
5. **Allowances are rendered only into a converged node's own table** (H-A-307 (2), H-A-312 (1)). On an adopted node
the mesh loads no table that holds an accept (design 08 adoption §2) and speaks the found firewall's terms through
openings derived from what the filter would be derived from (adoption §3); an allowance is none of them. The holder
refuses `allow` and `disallow` there and `allowed` answers none (design 33 control-verbs §3, §6), so the
node-engine renders none. After the node converges, allowances are set with `allow` as on any converged node.
6. **An allowance is removed at its `until`** (H-A-308 (2), H-A-312 (2), H-A-315 (4)). In the loaded filter the
kernel removes its set's element at its `until` (line 2). In the holder's state the holder removes its key at its
`until`, says `allowances-changed` with change `expired` and writes a journal line (design 33 control-verbs §11);
the event composes the filter again (line 3), which leaves its rule out. A holder away at the `until` removes the
key at its next start, before it answers `allowed`; meanwhile the loaded filter is kept (line 4) and the port is
already closed by the kernel.
7. **An allowance survives every render and restart because it lives in one place.** The holder's state on the bus is
the only copy; the rendered file is output, rewritten whole at each compose and never read back. A restart of the
node-engine, of the holder or of the machine renders the allowances again from `allowed`; a delivery of either
module removes none. A running holder keeps the seat while the seat's definition grows (design 33 control-verbs
§13).
8. **How it is checked.** The node-engine's compose tests assert on the input chain's text: with no allowance the file
is byte for byte today's derived file; with one allowance of the default set, a rule with negated matches on the
private network's interface and on each outward link and no positive match on either; with three (one interface named, one with an IPv4 source,
one udp), three rules in that form after the derived ones, each with its comment `allowance <key> <at>`; one with an
`until` renders a timeout set whose element's timeout is the time left. A fake `allowed` that never answers within
the bound leaves the loaded file untouched and one entry in `withheld-parts` of the composition answer, `node-packet-filter.allowed` with its why, and the
holder's module still replaceable; an
`allowances-changed` for the node composes again and one for another node does not; an allowance the fake answers
with an `until` already past is rendered as answered, the node-engine dropping none on its own clock; an adopted
node renders none. Live, read in packets as §4 reads them: before `allow`, a machine on the home network is refused
on tcp 8000 at the workstation (this holds where the home-network links are outward in the node's render, as the
workstation reports them; H-A-314 (8), H-A-324); after `allow` of tcp 8000 with no interface the home-network
machine is still refused, since an outward link is not in the default set; after `allow` of tcp 8000 on the workstation's home-network interfaces it
reaches the port and a machine reaching the workstation over the private network does not; a node-engine restart
keeps it open; after `disallow` neither reaches it; an `allow` with an `until` a minute ahead closes at its `until`
with the holder stopped.
@@ -0,0 +1,147 @@
---
layer: to-be
design: 33
milestone: control-verbs
updated: 2026-11-21
code: [mesh-networking modules/mesh-connectivity-contracts, mesh-catalog modules/nftables, mesh-host (the node-engine seat's verb converged)]
decisions:
- "ADR 0683"
- "ADR 0170"
- "ADR 0168"
- "ADR 0565"
- "ADR 0595"
- "ADR 0625"
- "ADR 0636"
- "ADR 0246"
---
# Design 33, milestone control-verbs — the packet filter seat's allow, disallow and allowed
**What it builds.** The node seat `node-packet-filter` serves, beside `rules`, `reload` and `remove` (ADR 0170), three
verbs that control the packet filter by hand: `allow`, `disallow` and `allowed`; `rules` lists the allowances beside
the ruleset; and the seat says every change of its allowances as the event `node-packet-filter.allowances-changed`.
The node seat `node-engine` gains the read verb `converged`. An **allowance** is a port opened by the operator, through
the seat, beside the ports derived from the modules' `listens`. This follows ADR 0683 (the firewall's control verbs,
amending ADR 0170) and the operator's word of 2026-11-21 20:35 CET, written from design 47 H's lead answers H-A-304,
H-A-305, H-A-307, H-A-308, H-A-310, H-A-312, H-A-314 to H-A-321, H-A-324 and H-A-325; P7, P11 and the instruction that tools are
how a module is spoken to (every act by hand has its verb, every kept thing its read). How the node-engine renders
allowances is design 08 control-verbs. Cited as "design 33 control-verbs §n".
**Where.** Built in design 47's milestone H, one delivery group with design 08 control-verbs, three repositories: the
networking repository (the seat's whole definition in its contracts module), the catalog repository (the nftables
module, the holder) and the node-engine's repository (the verb `converged`, and the render of design 08
control-verbs). mesh-sdk is not in the group: its TypeScript `state()` asks the runtime's state methods as a Go bundle
does (H-A-314 (4)).
## Lines
1. **The seat serves six verbs, and every holder serves all six** (§3). `rules`, `reload` and `remove` as ADR 0170
§1 to §7 say, with `rules`' answer widened by line 5; `allow`, `disallow` and `allowed` as lines 2 to 4 say. The
three are required from the start, in the one delivery group that adds them: §7's three steps (ADR 0246) end for a
seat defined in a contracts module (ADR 0683; H-A-310), since the group's check builds the definition and its
holder together. Each is a node verb, called `<node>/node-packet-filter.<verb>`. Their classes: `allow` and
`disallow` are class `act`, by-caller; `allowed` is class `read` (H-A-315 (2)).
2. **`allow` opens a port by hand.** Arguments: `port`, an integer 1 to 65535, required; `protocol`, `tcp` or `udp`,
default `tcp`; `interfaces`, a list of interface names, each 1 to 15 characters of letters, digits, `_`, `.` and
`-`, default none, which means the default set: every input interface that is neither the private network's tunnel nor an outward link (a hub's internet-facing link
included), so an outward link is opened only when named here (H-A-324; design 08 control-verbs §2);
`source`, one IPv4 or IPv6 CIDR, default none, which means any; `until`, an RFC 3339 time in the future, optional;
`why`, 1 to 500 characters, required. Any other argument is refused. Who set it is the caller as the bus names it on
the request, never an argument; for a session's call that is the tool runner's account (H-A-315 (3)). When is the
holder's clock at the write. It keeps one allowance per protocol, port and interface (H-A-308 (1)): one key per
named interface, each with the same source, who, when, why and `until`, or for none the one key of the default set
(line 7), resolved by the node-engine at compose. An `allow` for a key that exists replaces it whole and answers
what it replaced.
3. **What `allow` refuses**, naming the argument and writing nothing: a caller whose proof is `unproven` (H-A-315
(3)); a node that `converged` (line 10) says is adopted, naming the adoption, or a `converged` that does not answer
(line 10); a port out of range or not an integer, another protocol, a bad interface name, a source that is not a
CIDR, an `until` not in the future, an empty or longer `why`; unless a `source` is given, a port that the loaded
input chain accepts only with a source match (`ip saddr` or `ip6 saddr`) and never from any source, read from the
chain as `rules` shows it, which covers the store's port, the broker's management port and a port opened to the
local network only (H-A-315 (7), H-A-319, ADR 0683 §3; a comment naming each derived rule's scope, so the
holder reads scope and not shape, is owed to milestone H2 and not built here); and a write that would make more than `allowances-max` allowances on the node, the
holder's setting, default 100 (H-A-314 (5); the bound keeps the rendered chain readable and `allowed` in one
answer).
4. **`allow` and `disallow` answer what they did, and are written in the hand-act log.** When a named interface is
an outward link, as the `outward` list of the `converged` answer it asked for this call names them (line 10),
`allow`'s answer sets on that kept allowance the optional field `outward`, the outward link it opens (H-A-324,
H-A-325). The holder reads no shape of the loaded table to tell an outward link from the tunnel. `allow` answers each
allowance as kept, with its key and what it replaced, and that `allowances-changed` (line 6) was said; `disallow`
answers each allowance as removed and that the event was said (H-A-308 (3)). Whether the loaded chain carries an
allowance is read with `rules` (line 5). Each call of either is written in the hand-act log (ADR 0565 §10; H-A-315).
5. **`disallow` takes back an allowance.** Arguments: `port`, `protocol` and `interfaces` with `allow`'s forms and
defaults, which name the same keys (no `interfaces`: the default set's key), and `why`, required as for `allow`;
any other argument is refused, the source among them, since it is a property and not part of an allowance's
identity. It refuses as `allow` does an `unproven` caller, an adopted node and an unanswered `converged`. It deletes
every key named, or, when one does not exist, refuses naming it and deletes none, and says `allowances-changed` with
change `disallowed`, its who and its why.
6. **`allowed` reads every allowance.** No arguments. It answers every allowance kept for its own node only (line 7),
each with its key, `port`, `protocol`, `interface` (absent for the default set), `source` (absent for any), `until`
(absent for none), `why`, `by` (who) and `at` (when). The node-engine is its caller at every compose of the filter,
within its compose-ask bound (design 08 control-verbs §1). On an adopted node it answers none (H-A-312 (1)), so no
answer says a port is open that is not.
7. **`rules` lists the allowances beside the ruleset.** Its answer keeps the filter as the machine enforces it (ADR
0170 §2) and adds `allowances`: `allowed`'s answer, each marked `loaded` only when a rule of the mesh's table carries
its comment `allowance <key> <at>` with an equal `at` (design 08 control-verbs §2), and not loaded otherwise; and
every loaded allowance comment whose key is not kept, listed as "loaded, not kept" (H-A-315 (5)). So a kept
allowance the loaded filter does not carry, and a loaded one nobody keeps, are both visible in one call.
8. **The event `node-packet-filter.allowances-changed`.** The holder says it after every write or delete of its
state, in the seat's family `node-packet-filter.events` on the shared events stream, `max-age-days` 7, its subject
`allowances-changed.<node>` (as the node-engine seat's `composed.<node>`; H-A-314 (2)). Its body: `node`; `change`,
one of `allowed`, `disallowed`, `expired` and `started`; `allowances`, the ones concerned (all of them for
`started`); `by` and `why` for `allowed` and `disallowed`; `at`. The holder says `started` once each time it starts
serving the seat, so a node-engine that refused a compose for want of an answer composes again. The node-engine
of that node hears it (design 08 control-verbs §3); nothing else needs to.
9. **The holder keeps the allowances in its own state on the bus, one bucket per machine.** A state `allowances`
asked for in the holder's manifest's `requires` by the template `state` (ADR 0595 §1, §2) with the template's
option of one bucket per machine, `history` 1, reached only by its owner; a node's holder answers its own node's
allowances only (H-A-315 (1)). The per-machine option is one bucket whose keys carry the node, `<node>` and
`<node>.>` reached only by that machine's holder, so each holder reads and writes its own node's prefix only
(H-A-317). One key per allowance: `<node>.allow.<protocol>.<port>` for the default set (line 2), `<node>.allow.<protocol>.<port>.<interface>` for a named one (the interface is every token
after the fourth, since a name may hold a dot). The allowance's key in every answer, in the event and in the rule's
comment is the same key without the node, `allow.<protocol>.<port>[.<interface>]`. Its value: `port`, `protocol`, `interface`, `source`, `until`,
`why`, `by`, `at`; the source is a property of the value, never part of the key. Only `disallow` and the removal at
its `until` (line 11) delete a key; no render, restart or delivery does. The bus module's own tools read the state's
fill against its cap. The holder's manifest serves the six verbs and requires the state; it does not list the event in
`emits`, which the manifest check refuses for a claimed seat's event: the claim of `node-packet-filter` says the
event, and the holder says it with the seat's publish (H-A-314 (3), H-A-317).
10. **The node seat `node-engine` gains the read verb `converged`** (H-A-316). It answers the node's convergence
state, which the node-engine keeps (ADR 0168): `state`, `adopted` or `converged`; `since`, when it became so, optional and absent for a record written before this change (H-A-324); for an adopted node `found`, the found firewall's kind (H-A-321); and the node's links as the node-engine
classifies them for its render: `tunnel`, the private network's interface name, and `outward`, the list of the
node's outward links (H-A-325; design 08 control-verbs §2). Class `read`, built in the group's node-engine part, added
to the node-engine seat's whole definition. The holder asks it at its start and at every `allow` and `disallow`,
bound 10 s (the default of the node-engine's compose-ask bound), and refuses when it does not answer. When it
holds no answer (its start's ask did not answer and no `allow` or `disallow` asked since), `allowed` asks
`converged` again, bounded by the same 10 s, and refuses when that does not answer, so the node-engine keeps the
loaded filter (H-A-318). It never assumes either state and recovers without a restart.
11. **An allowance is removed at its `until`, by the holder.** The holder keeps an in-process timer per allowance with
an `until`, armed from the watch of its own state at every start (H-A-314 (6)). At an allowance's `until` it
deletes the key, says `allowances-changed` with change `expired` and writes a journal line naming the
allowance (H-A-308 (2)); no removed entry is kept, so `allowed` never answers one. At its start it first deletes
every key whose `until` has passed, with the same event and journal line, then says `started`, then answers
`allowed` (H-A-312 (2)). The kernel closes the port at its `until` even while the holder is away (design 08
control-verbs §2).
12. **The seat's definition becomes whole** (H-A-307 (3), H-A-314 (2); ADR 0625 §1, ADR 0636 §5, §6). It lives in the
Connectivity domain's contracts module, `mesh-connectivity-contracts`, in the networking repository: every one of
the six verbs with its class, its arguments and its answer form as lines 1 to 7 say, the family and event of line
8, the state's value of line 9 as a layout, and the generated Go and TypeScript packages. Its model is the
`node-engine` and `git` seats' whole definitions. The node-engine calls `allowed` and hears the event
through the Go package; the holder serves the verbs and says the event through the TypeScript one.
13. **A running holder keeps the seat while its definition grows** (H-A-315 (6)). A holder running before this group
is not withdrawn when the seat's definition gains the three verbs; it holds the seat until it is replaced. While a
node's holder does not serve `allowed` (a rollback, a laptop asleep), the node-engine refuses the filter's
composes and keeps the loaded filter (design 08 control-verbs §4).
14. **How it is checked.** The holder's tests, against a state in memory: `allow` then `disallow` writes the key, then
deletes it, with an `allowed` and a `disallowed` event, both answers saying the event was said, and two hand-act
log lines; port 0, 65536 and `80a` are refused, as are protocol `icmp`, an `until` in the past, an empty `why`, an
unknown argument, an `unproven` caller, the 101st allowance at the default `allowances-max`, and the store's port
with no source when the fixture chain accepts it only with a source match (accepted with one); `allow` with no `interfaces` stores no interface, so neither the private network's
interface nor an outward link is ever in the defaults; with a fake `converged` whose `outward` lists `eth1`, `allow` naming `eth1` answers that kept allowance with
`outward` `eth1`, and one naming another interface answers it without the field; `allow` with two interfaces keeps two keys; a second `allow` of one key answers
what it replaced; an allowance is removed at its `until`, says `expired`, writes its journal line, and
`allowed` then answers without it; a start with a key past its `until` deletes it and says so before `started` and
before its first `allowed`; with a fake `converged` saying adopted, `allow` and `disallow` are refused naming the
adoption and `allowed` answers none; with one that never answers, both are refused and `allowed`, holding no answer, asks again and refuses; an allowance kept on one node
is absent from another node's `allowed`, and its key in the bucket carries its node while its answer's key does not; `rules` over a fixture ruleset marks an allowance loaded only on an equal
`at` and lists a comment with no kept key as "loaded, not kept". The node-engine's test of `converged` answers both
states. The seat's contract test holds every holder to the six verbs, and the generated packages to the definition.
@@ -1,9 +1,10 @@
---
layer: to-be
status: implemented
status: in-progress
code: [mesh-controller, mesh-tools]
updated: 2026-10-07
updated: 2026-11-21
decisions:
- "ADR 0683"
- "ADR 0246"
- "ADR 0170"
- "ADR 0179"
@@ -214,6 +215,20 @@ container to declare a capability. Removing a predecessor's rule set is an opera
through the seat, recorded on the bus, instead of a shell on the machine. *How it is checked:* ADR
0169's table.
*2026-11-21, ADR 0683 (the firewall's control verbs, amending ADR 0170); the operator,
2026-11-21: the packet filter's module has tools to control it beside the automatic provisioning from declarations.*
The seat serves three more verbs: `allow` (a port 1 to 65535, protocol `tcp` by default or `udp`, interfaces by
default every input interface but the private network's tunnel and the outward links, a source CIDR by default any, an optional `until`, a
required `why`), `disallow` (the same keys) and `allowed` (every **allowance** with who set it, when, why and its
`until`, at which it is removed); `rules` lists the allowances beside the ruleset. The node seat `node-engine` gains
the read verb `converged` (adopted or converged, since when, the found firewall's kind), which the holder asks before
it keeps an allowance. The holder keeps them in its own state on the bus and says
every change as the event `node-packet-filter.allowances-changed`, which the node-engine hears to compose the filter
again; the node-engine stays the one renderer (design 08 §4, *By hand, beside the derived ports*). The seat's
definition becomes whole in its domain's contracts module. Every holder serves the six verbs. Every line is in
[design 33 control-verbs](33-milestones/control-verbs.md), from design 47 H's lead answers
H-A-304, H-A-305, H-A-307, H-A-308, H-A-310, H-A-312 and H-A-314 to H-A-316; *how it is checked* is its line 14.
## The intrusion seat's verbs, 2026-10-02
ADR 0179.
@@ -226,6 +241,15 @@ per-module container ADR 0175
retires; the verbs and the client are the same code once the node's own runtime loads them as a bundle.
The module's own tool beside them reads one jail's effective settings. *How it is checked:* ADR 0179's table.
## Milestones
Each milestone not yet delivered has its part, cited as "design 33 <milestone> §n"; what is above was built before
milestone parts existed.
| Milestone | Part | State |
|---|---|---|
| control-verbs: the packet filter seat's `allow`, `disallow` and `allowed`, built in design 47's milestone H (ADR 0683) | [control-verbs](33-milestones/control-verbs.md) | to build |
## What this does not settle
- Which verbs each seat should serve. That is a decision per seat, and the reason to do it slowly: a
@@ -3,7 +3,7 @@ layer: to-be
status: in-progress
design: 47
milestone: H
updated: 2026-11-21
updated: 2026-11-20
decisions:
- "ADR 0682"
- "ADR 0681"
@@ -61,14 +61,14 @@ per cent of the 527 rows judged (the rest belong to another part's code) (per pa
| symptom (live) | count | cause (from the gap tables) |
|---|---|---|
| wants held or failed on the four machines | 205 held, 66 failed | the catalog half holds no entry for their fingerprints; the node-engines compose nothing new |
| compositions fail on the operator's desktop | entries `asked` since 2026-11-18 03:09, unready answers seen from 2026-11-19 11:56 | an entry ask that failed in transport is never asked again; the node-engine's shadow waits on it without bound (the surveyor's reading); other compositions failed on the removed revision trunk.510 and on a call-token refusal |
| compositions fail on shanks | entries `asked` since 2026-11-18 03:09, unready answers seen from 2026-11-19 11:56 | an entry ask that failed in transport is never asked again; the node-engine's shadow waits on it without bound (the surveyor's reading); other compositions failed on the removed revision trunk.510 and on a call-token refusal |
| delivery records open, none ended | 833 open, 0 ended since 2026-11-14 | the gate hears only `take-in.taken`; nothing writes a record's trace, so its difference is never known |
| pipelines about to start at the next take-in | about 60 (reasoned from the sweep's rule; no tool reads the runner's waiting starts) | the runner's sweep starts a pipeline for every module whose fingerprint has none (b9c50ef0, 2026-11-16); no design line allows it |
| source revision moved twice | both paths on main | A-464 (per merged message) wins live over A-34 (on the take-in): a group's members become separate revisions; a pushed commit reaches the source only through the take-in or the gate's comparison at its next start |
| catalog revision removed while pipelines name it | trunk.510 at 22:51 | pins are judged at restart against a key written once; only the take-in pins pipelines |
| stale bus state | 753 merges, 6,951 owed, 898 asks, 1,256 pulls keys; 5 pipelines running since midday; 31 stale pin records | buckets of the pre-G model never dropped; no tool reads their contents |
| bus load | 98 slow consumers, 117 consumers behind; the watchman 39,037 events behind | mesh-config passes every 5 minutes and polls every minute on main (fixed on the held pull requests); the forge module polls every minute |
| hand-placed programs | every delivery module but the indexer, the image registry and the tool runner (on the home server and the laptop) | G's live start of 2026-11-16 and after; 16 drop-in files under `/run/systemd/system` on the four machines (4 of them `.pre-g` copies), lost at a reboot |
| hand-placed programs | every delivery module but the indexer, the image registry and the tool runner (on ace and g14) | G's live start of 2026-11-16 and after; 16 drop-in files under `/run/systemd/system` on the four machines (4 of them `.pre-g` copies), lost at a reboot |
**Every node, every module** (the assigner's assignments at revision 339, unchanged since 2026-11-18 02:08 UTC; the
node-engines' haves; read 00:47 to 00:54 CET):
@@ -247,8 +247,8 @@ Built 56, built otherwise 8, contradicts 9, missing 3, not judged 7 (of 83). Ass
A-478b's order waits on one machine stay (the order waits reshaped to order one machine's apply, not hold wants).
- **The assigner reads every have** whole and with history (§520 says it goes); wants are not written from the kept assignment graph revision. Medium each, H1. (The node-engine's read of
every node's record stays: it feeds the composer; H-A-60 corrects the earlier reading of §459.)
- **The shadow fault on the operator's desktop**: the entries client leaves an entry `asked` after a transport failure and never asks
again; about 110 entries on the operator's desktop have stood `asked` since 2026-11-18 03:09. Ask again on failure, with a bound
- **The shanks shadow fault**: the entries client leaves an entry `asked` after a transport failure and never asks
again; about 110 entries on shanks have stood `asked` since 2026-11-18 03:09. Ask again on failure, with a bound
(small). The surveyor's reading, to be confirmed by `entry-again` on one entry during the clean state.
- **The tool runner:** A-490m is ready on mesh-tools #77 (merge); it lacks a test that starts it whole.
- **Tests:** the node-engine has 1,719 unit tests against a budget of 500; every change to it shrinks that.
@@ -269,7 +269,7 @@ Built 56, built otherwise 11, contradicts 5, missing 11, not judged 9 (of 92).
retries twelve watches every 5 seconds; the forge module polls every minute; the build modules re-pull every 5
seconds when idle; mesh-sdk's view catch-up asks again on a timer. The gap table's section 5 has the table of
modules, functions and intervals. The fix belongs in mesh-sdk, for every module at once (fix-a-bug-met-twice).
- **`builder_stuck` times out** for a fixed cost, measured in the tool runner's journal on the operator's desktop: 1,010 values took
- **`builder_stuck` times out** for a fixed cost, measured in the tool runner's journal on shanks: 1,010 values took
52.5 seconds and 53 values took 44.5 seconds. Each call starts a tool process that lists every key of `builds` and of
every build seat's `steps`, then reads one value per request. The builder keeps its own index of what is building
and answers from it. Medium.
@@ -373,14 +373,14 @@ like any milestone, but its delivery is by hand, because the running system cann
the operator runs each pack one command at a time and says "done"; the lead checks each with the tools before the
next:
1. **Freeze.** No merge to any delivery repository but H1's own. The runner on the control-node is stopped through the service
1. **Freeze.** No merge to any delivery repository but H1's own. The runner on novox is stopped through the service
seat so no take-in starts a pipeline during the freeze; the assigner stays, so nothing moves.
2. **Merge H1's set to main**, in this order, each reviewed: mesh-contracts #16 and mesh-sdk #200 (held), then
mesh-catalog #708 and mesh-delivery #261 (held, mesh-config), mesh-tools #77 (held), and H1's own pull requests
(indexer take-in, runner, gate, bridge, assigner, node-engine). mesh-delivery #262 is closed as superseded. The
stopped runner starts nothing; the indexer takes the commits in and the gate follows, as the old programs still
running during the freeze do. The new programs take every head in once, at the seed (step 5.9).
3. **Build H1's programs from main** with the packs (the g-start phases, one per program), on the operator's desktop and the control-node as
3. **Build H1's programs from main** with the packs (the g-start phases, one per program), on shanks and novox as
before, from main's head after step 2 so that main is what runs.
4. **Take the stream snapshot that is the drop's rollback** (design 47 H §765) and test its restore; nothing is
dropped yet. The drop-ins are removed and the units the node-engine writes take their place as the wants compose.
@@ -414,7 +414,7 @@ next:
to main through a merge call (`merge-pull`, design 47 H §734), followed from `take-in.taken` through `pipeline-ended` to the node-engine's `running` and the gate's
ended record, with no hand act; then one two-module change along a dependency edge (mesh-sdk and a module that
requires it published), merged in one merge call, the same way. Each proof read with the tools and quoted with its times.
8. **Lift the freeze.** From here every merge is delivered by its pipeline; a hand pack is a breach the lead names. Done at 19:31 on 2026-11-21 (section 10, row 173).
8. **Lift the freeze.** From here every merge is delivered by its pipeline; a hand pack is a breach the lead names.
## 6. The milestones after the clean state
@@ -425,7 +425,7 @@ own pipeline), in this order, the next starting when the previous one's delivery
|---|---|---|---|
| H0 | the design says the one model whole (section 4) | hq, the knowledge base | the four reviewers by architectural domain approve the batch; the operator's four answers are in |
| H1 | the one chain works with no hand act (section 5) | `mesh-delivery`, `mesh-catalog`, `mesh-host`, `mesh-tools`, `mesh-sdk`, `mesh-contracts` | the two proofs of step 7 |
| H2 | the work H1's live run owes, as the lines of its own part, [H2-the-delivery-systems-owed-work](H2-the-delivery-systems-owed-work.md) and [H2-stores-and-tools](H2-stores-and-tools.md) (design 47 H2 §775 to §823): every ask a kept call through a part away, the work queues and journal lines of the asks, the fingerprint over a module's own build source, the stores capped and read in parts, the gate's ledger per module and its delivery times, hq a watched source | mesh-delivery, mesh-catalog, `mesh-host`, `mesh-tools`, `mesh-sdk` | H2 §816 and §817: a change to a delivery part, and a package with its importer in two repositories, each running everywhere within ten minutes of its merge call with no hand act |
| H2 | the builder, the build modules and the registries follow the latest lines (section 3.4; versions, publish again, the floor, a step with nothing to run, a module with no registration) | mesh-delivery, mesh-catalog | a version is skipped by nothing; every registered module has a pipeline with steps |
| H3 | the gate and the forge module carry only the one model; groups by the operator's answer; the forge module without its merge-check machinery | mesh-catalog, mesh-delivery | a group of two repositories delivers as one; every delivery record ends |
| H4 | every delivery part wakes on its inputs alone and is steered by its tools (sections 3.6, 7): the shared wake-up shape (mesh-config's full pass per event and its reads through module tools, the indexer's re-read after every verdict, the node-engine's retry clocks, the build modules' idle pull), the view and the watchman without reads of another part's state, the SDK's generic state tools with the fill against a cap, the missing tools per module, rates on the bus | `mesh-sdk`, `mesh-delivery`, `mesh-catalog`, `mesh-host` | the bus's slow consumers and behind counts at 0 for an hour; every module's tools pass the principle-4 table |
| H4b | the grants part says what it holds as events and reads nothing of another part's bus state (ADR 0596) | `mesh-delivery` | the grants part's own `filling` and `room` and no bucket watch in its code |
@@ -455,7 +455,7 @@ at the prepare, one developer per repository on the larger model for the indexer
- It does not merge the six held pull requests now; they merge in H1's step 2, and one (#262) is closed.
- It does not touch the controller, the vault or the recovery module beyond what the chain needs; the recovery
module is not placed and is a later milestone's.
- It does not change the catalog's module set or the build nodes (the control-node's build agent stays paused).
- It does not change the catalog's module set or the build nodes (novox's build agent stays paused).
- It leaves what the surveyors could not read as named guesses, each with how to check it, in the gap tables'
last sections; the prepare of each milestone checks them.
@@ -477,242 +477,3 @@ the one review (`mesh-code-reviewer`, at most three rounds).
The order between branches is the prepare's dependency table: contracts and copies first (published as the next
mesh-sdk and mesh-contracts versions at the clean state's step 5.2), then the modules; the runner-and-assigner branch
rebases onto the contracts commits before the review.
## 10. Findings of H1's live run, for H2 and H4 (the lead, 2026-11-20 14:22 CET)
Met while the clean state was placed and the first pipelines ran; none changes H1's scope. Each is a line for the
milestone named, written into its part before that milestone's prepare.
| finding | milestone |
|---|---|
| The indexer starts its take-in on a two-minute timer; the first branch take-in after a start waits that long. An event, not a timer (P1). | H2 |
| The readers' first views loop on "asked once more" when the verb's holder is slow; the loop is silent. | H2 |
| The composition step's validate reads "the branch's previous catalog revision" and could not run for the first revision after the seed (main.2 does not exist): a first revision validates against nothing, said so. | H2 |
| The node build module asks a `package-lock.json` of the artifact's path; mesh-contracts's TypeScript artifacts name `.`, where none is: either the artifact path or the module's check is wrong, read against ADR 0499. | H2 |
| The indexer's whole integration test took 32 s to set up on the build node, over the level's 30 s setup bound, so the step failed on time, not on behaviour. | H2 |
| The grants part composes no per-branch consumers. | H4b |
| The runner's publish is malformed on the earlier model's records (one journal line each). | H2 |
| `TakeInSource` has no check for a revision below the newest kept. | H2 |
| `mesh_wait` refuses the operator channel's events. | H2 |
| No bus snapshot on request (a tool of the bus module). | H2 |
| The keeper's orphan rule ignores state buckets. | H2 |
| An artifact's key against the workspace directories H-A-136 adds (ADR 0499 clause 4). | H2 |
| hq has no registration, so its pull requests are refused by the gate (H-A-131). | H2 |
| mesh-delivery-sdk and mesh-delivery-contracts publish as packages of their own. | H2 |
| The hand pack's `build-seats` phase carries the label of the build node only; every machine with a build runtime needs it. | H1, the runbook |
| The claude-code node side wrote a lease over a login the manager had not adopted (H-A-138); its fix is a small fix beside H1. | fixed in H1 |
Added by the lead at 18:40 CET, from the run of 16:40 to 18:40: the first delivery by pipeline landed (a module on the
desktop, with hand restarts), and these were met on the way. A row a lead answer settled says so; the rest are open.
| finding | milestone |
|---|---|
| Validate's base was read as the source number minus one, which names nothing where a take-in moved nothing (the seed, a merge with no mover); the indexer (`mesh-delivery-indexer`) and the assigner's validate. Settled by H-A-151 and H-A-154 (the catalog revision's field `base`), which settle the first-revision row above too. | settled in H1 |
| Compositions on the control-node failed on stale assignments (modules assigned that no watched branch lists); the assigner (`mesh-delivery-assigner`). Settled by H-A-152 and H-A-153 (the run value's field `unlisted`, in the seat mesh-wants), proven at main.24. | settled in H1 |
| A build ask reached the builder before its picture held the pipeline's revision, so it built with no version reserved (main.8, main.21, the first proof); the builder. Settled by H-A-155, H-A-156 (`revision-wait-minutes`) and H-A-162 (a run's ask names no source). | settled in H1 |
| 64 of 82 Go modules carried no package edge, because the indexer read mesh packages from go.sum, which names none at the zero version; the indexer. Settled by H-A-157 (edges from go.mod). | settled in H1 |
| The tool runner (`node-tools`) stopped every subscription on each membership and repair and dropped calls in the gap; the tool runner. Settled by H-A-158 and H-A-160 (make before break). | settled in H1 |
| The builder still numbered every trunk build in a `versions` state of its own and folded a reserved version into an older entry, so builds pinned an old package; the builder. Settled by H-A-159 (the reservation is the one numbering), which also makes a tool to drop or rewrite a versions entry moot. | settled in H1 |
| Packages were pinned by a commit (a pseudo-version of an old tree), so builds ran against pre-H1 packages (main.15, main.20, main.22, main.24); the indexer and the builder. Settled by H-A-161, H-A-165 (`package-wait-minutes`, a re-pin on version-released), H-A-167 and H-A-172 (pins in every form's fingerprint). | settled in H1 |
| A pipeline whose mover had no registration never ended (main.20, main.22), and no tool ended a pipeline by hand; the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-163, H-A-171 and H-A-164 (the seat verb `end-again` on mesh-pipeline-runner, the tool `runner_end_again`). | settled in H1 |
| The SDK's view reader heard an event only on `<subject>.>`, so the seat mesh-catalog's registration-changed on its bare subject reached no handler; mesh-sdk. Settled by H-A-166 and H-A-169 (the finding `event-unhandled`). | settled in H1 |
| The SDK's finding write for an unhandled event waits up to 3 s on the bus inside the event loop, per event, so a missing stream or a slow bus stalls the module: write it outside the loop, or once per change of the count; mesh-sdk. | H2 |
| The indexer dropped a passed pipeline's revision once the pipeline ended, so the want named an entry no longer kept and was held "entry-missing" (main.23, main.25); the indexer. Settled by H-A-168, H-A-170, H-A-173 and H-A-174 (release pins). | settled in H1 |
| A tier-late pipeline's release records are freed only by that module's next pipeline that ends running, so a module with no later pipeline keeps its revisions pinned; the indexer. | H2 |
| The indexer's `publishedAsBuilt` may read a package's imports at the wrong commit when the pin is not the newest of its series; the indexer. | H2 |
| A failed re-pin leaves a pending key behind; the indexer. | H2 |
| A build module's toolchain edge into the movers it is built from made a cycle the runner never broke, so pipelines held their turn with no step for an hour (main.26, main.28, main.30); the pipeline runner. Settled by H-A-175 and H-A-176 (the pipeline ends failed with why `cycle`). | settled in H1 |
| Integration tests pass alone and fail on the build node under load (the bridge, the grants part, the indexer, the assigner's setup at 38 s against 30 s, the tool runner's level at 72 s against 60 s), because a build node runs levels side by side; fixed per test for the indexer and the tool runner only; the Go build module (`mesh-build-go`) and each module's tests. | H2 |
| The Go build module runs builds at idle CPU priority, so a fixed bound in a test or a step can be outlasted by load alone; the Go build module. | H2 |
| The build node counts untagged tests into a module's integration count (156 against the budget of 50 for the pipeline runner); the Go build module. | H2 |
| Modules over the test budget: the node-engine (`mesh-host`) with 1716 unit tests against 500, the indexer with 538 integration tests and the assigner with 64, against 50; each shrinks with every change to its tests. | H2 |
| The Go build module reads failed on the control-node and on the laptop, and a third build node is paused, so one build node (the desktop) builds for the whole mesh. | H2 |
| The builder still starts delivery builds from the take-in path, flooding the one build node, where H §756 says a build is entered only by the runner's build step; the builder. | H2 |
| A newer pipeline withdraws an older pipeline's build of the same module, and the older pipeline then fails instead of that mover leaving it (main.27, withdrawn by main.30); the pipeline runner and the builder. | H2 |
| The step outputs store keeps 0 bytes, so the words of a failed test are lost and only the verdict remains; the pipeline runner. | H2 |
| The pipeline runner's `show` answers 150 KB with no filter, too large for a session to read; it needs a filter (a mover, a step, a state); the pipeline runner. | H2 |
| A run on request cannot place steps for a module that is not a mover; the pipeline runner. | H2 |
| `runner_start` refuses a head whose pipeline exists (H-A-52), so a package module is built again only by a new merge; the pipeline runner. | H2 |
| A required step that could not run has no hand twin: accepting it and running it again are both refused; the pipeline runner. | H2 |
| No tool places a pipeline's waiting movers again; only the runner's start does; the pipeline runner. | H2 |
| No tool shows the pins a build ask carried; the builder. | H2 |
| `builder_build_again` refuses a key that is done; the builder. | H2 |
| The seed registered not every package module (mesh-delivery-contracts, mesh-delivery-sdk) and made no mover of them, so they were registered by hand and nothing was published at H1's heads (H §758); the seed of the seat mesh-catalog. | H2 |
| A want is written only from a pipeline that passed whole (H §750, §751), so a dependent folded in (H §745) that fails blocks a fix of the module it depends on; the assigner. A design question: all or nothing, or per mover. | H2 |
| Packages in one repository carry no kind-1 edge between them (the sibling rule, H-A-136); a design question whether they should; the indexer. | H2 |
| A module (`feh:tools`) carries a required integration step with no integration test to run ("a step with nothing to run"); the seed's steps in the seat mesh-catalog. | H2 |
| The gate (`mesh-delivery-gate`) says old sources again on a restart. | H2 |
| A held take-in does not try again after a passing failure of the forge; the indexer. | H2 |
| The node-engine's early-pass words "reaches no artifact store" read as a fault while placements are not read yet; the node-engine. | H2 |
| The node-engine's resolve-again period is fixed in code, not a setting (P11); the node-engine. | H2 |
| A fetch made inside the node-engine's turn tells the composer nothing; the node-engine. | H2 |
| The node-engine's node-agent wiring has no test; the node-engine. | H2 |
| A bundle reload of the tool runner still unloads before it serves, so calls in the gap meet no responders (said, not silent), and the mesh MCP server's package takes 28 s to load; the tool runner. | H2 |
| The seat node-files has no verb that reads a file's sha256, and its `copy` refuses another node (issue 903), so hand packs were copied by the lead's shell; node-files. | H2 |
| The builder's unit written by hand on the desktop carries none of the manifest's setting variables, so its settings are the defaults; the builder's hand pack. | H1, the runbook |
| The clean proofs of the runbook's step 7 are still owed: the first proof failed on the version race (settled by H-A-155), the second ran for the publish of the SDK packages; the freeze is not lifted (step 8) (lifted at 19:31 on 2026-11-21, row 173). | H1 |
Added by the lead at 19:50 CET, from the run of 18:40 to 19:50; a row met again names the row of 18:40 it adds to.
| finding | milestone |
|---|---|
| The node-engine (`mesh-host`) asks the seat mesh-recovery for a restore point before it moves a data-holding module, and the recovery module is placed nowhere (H §456), so every such take-in was held for good; the node-engine. Settled by H-A-177 and H-A-178 (it moves without a point where no holder is placed and raises the finding `restore-point-missing`). | settled in H1 |
| A package module no machine holds (mesh-delivery-sdk) had a required composition step that could not run, so its pipeline could never pass (main.35, the second proof); the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-179 (the step ends `nothing to run`, ADR 0682 §8). | settled in H1 |
| A module held for a failed restore point kept the hold across the node-engine's start, and no operator's ask was raised for it, so the hold was for good; the node-engine. Settled by H-A-180 (the hold's cause is judged again at the start and on every change of placements). | settled in H1 |
| The forge bridge kept each owed event whole in its state `performed`, filling its kept data to 51 MB of the template's 64 MiB (19,530 keys, the condition "kept data is filling up"); the forge bridge. Settled by H-A-181 and H-A-182 (the outcome, when, and the act's pull request; the act stays in the gate's stream `owed`). | settled in H1 |
| The finding `restore-point-missing` did not reach the conditions after the first move without a point: the finding's wiring to the condition keeper; the node-engine. | H2 |
| The recovery module is placed nowhere, and the assigner derives no placement from the holder of the seat mesh-broker (G §554); the assigner (`mesh-delivery-assigner`). | H2 |
| A pipeline record with 112 or 129 movers exceeds the bus's 1 MiB message limit once its steps are placed, so two pipelines were cancelled; the record's shape (steps per mover key) and the limit as a setting; the pipeline runner. | H2 |
| A change to the SDK package folds in about 112 importers and a change in the catalog repository about 60, so the first re-pin of those repositories cannot run until the pipeline record is reshaped (the row above); the pipeline runner. | H2 |
| Met again on the tool runner's pipeline: a superseded build makes the older pipeline fail instead of its mover leaving it (the row of 18:40 on a withdrawn build); the pipeline runner and the builder. | H2 |
| The gate's owed acts run at about ten times the design's estimate (about 80 note acts per delivery record per pull request), and the gate's own stream `owed` takes the same rate; the gate (`mesh-delivery-gate`). | H2 |
| The forge bridge's `bridge_owed` by pull request still reads every key of its state in the tool runner's process; the forge bridge. | H2 |
| A refused consumer creation is tried again for longer than the tools' wait for an answer, so a person sees a timeout instead of the refusal; the bus module's tools. | H2 |
| Met again: the SDK's finding write for an unhandled event waits up to 3 s on the bus inside the event loop, seen as a 90 s test (the row of 18:40); mesh-sdk. | H2 |
| Met again: the build node counts untagged tests into a module's integration count (the row of 18:40); the Go build module (`mesh-build-go`). | H2 |
| Met again: the step outputs store keeps 0 bytes, so a failed test's words are lost (the row of 18:40); the pipeline runner. | H2 |
| The proof of the runbook's step 7 is still owed: proof 1 failed on the version race, proof 2 twice, on stale pins and on the composition step of a module no machine holds (settled by H-A-179), both settled; the freeze is not lifted (step 8) (lifted at 19:31 on 2026-11-21, row 173). | H1 |
| Four hand placements more (the distribution tools bundle, the assigner, the builder's program, the node-engine twice) and five hand restarts were needed to break circles, each said to the operator; the runbook. | H1, the runbook |
Added by the lead at 21:30 CET, from the run of 19:50 to 21:30; a row met again names the row it adds to.
| finding | milestone |
|---|---|
| A pin named the newest release of the module holding a package (its release number), while a Go package's version is its tag, so every importer of a nested package failed on "unknown revision" (main.39), and pipelines kept failing on old pins; the indexer (`mesh-delivery-indexer`). Settled by H-A-183, H-A-184 and H-A-185 (the pin is the newest version the registry published for the package path, within the series the module's manifest accepts), built in the indexer and placed by hand, because its own pipeline could not deliver it. | settled in H1 |
| Nine Go packages other modules import were never declared artifacts of their modules (among them the builder's `builds`, the bus module's `busgrants`, disk-load's `diskreadings`), so no release published them and their importers' builds wait past the bound; the owning modules' manifests in the catalog. Settled by H-A-186 (an imported mesh package is a declared artifact of its module); still owed: the catalog's check that refuses a manifest whose Go module imports a mesh package path no module of the catalog declares. | H2 |
| A package artifact's declared series (0.1) differed from its module's version series (0.3 for the assigner), so its publishes would pin nothing; the manifests in the catalog. Settled by H-A-188 (a package artifact's series is its module's version series, or left out); still owed: the catalog's check that refuses a mismatch, and the gate's manifest (`mesh-delivery-gate`) naming the series 0.3 in its `packages` so it accepts the assigner's asks, in the catalog's next change. | H2 |
| A pipeline record of 112 or 129 movers exceeded the bus's 1 MiB message limit (the row of 19:50 on the record's shape); the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-187 (steps one key per mover), H-A-189 (a mover's unlogged step-log entries under its mover key), H-A-190 (a step-log entry names its mover) and H-A-191 (`list` answers counts, `mover-count` and `step-count`). Still owed: a tool that reconciles a record whose mover-key writes failed; and a bound on every kept value (64 KiB) and on every tool answer, in mesh-sdk, the lead's proposal, whose scope waits on the operator. | H2 |
| The builder's step path pinned a package of the same pipeline at the module's release number, and the Go build module (`mesh-build-go`), given no pin, took another package's version of the same repository (its "askedFor" fallback), so both built against versions never published; the builder and the Go build module. Settled by H-A-192 (the builder takes a pin from the catalog entry or the registry's package-published event alone; a build module given no pin refuses the build, loud); still owed: the Go build module's half, in the catalog. | H2 |
| The builder's lane narrowed a module's single fetch to the paths of its package artifacts, so a program build found no main module; the builder. Fixed in the builder, by ADR 0499 clause 1. | settled in H1 |
| The indexer's tools bundle missed a catalog-revision event in silence, so the pipeline runner waited 12 minutes for the next revision; the tool runner (`node-tools`). The cause, not the SDK's reader: the tool runner on the control-node was built before the one consumer loop (H-A-132, H-A-133), so two pull loops read the bundle's one durable consumer and each event reached one loop only; the events alternated (the bundle read 42 and 44, the runner's own view heard 41 and 43), and the seat mesh-catalog's revision verb answered a stale revision while the same process had heard the newer one. The fix of the cause is the tool runner's own release reaching that node (pipeline main.43); the kind is closed by H-A-196 (the SDK refuses, loud at bind time, a second pull loop on a durable the same process already pulls), in build. A note: a log line per event handed to a bundle. | settled in H1 |
| The seat mesh-grants's verb `grants-for` was cut after 5 s in two pipelines' composition steps (a widening entry on the vault); the grants part. The cause: the verb answers in 3.4 to 5.0 s, because on every call it reads two whole catalog revisions (about 1.4 MB each) page by page through the seat mesh-catalog's revision verb and composes every account twice, with no cache, while the pipeline runner's read bound is 5 s. A revision read whole over the bus is the same habit as the row of 21:30 on the pipeline record over 1 MiB. The fix chosen (thorough): the grants holder keeps each revision it read, a revision never changing; in build now. Not chosen: raising the runner's bound. | H2 |
| The node-engine (`mesh-host`) on one machine said it cannot create a new version's folder ("operation not permitted"), met twice, two days apart; the node-engine. The cause: an immutable attribute a person set by hand on the engine's versions folder during the recovery of the mixed state of 2026-11-13, since removed; the engine keeps repeating the stale words of its last applied record. No fix in code or unit: the words clear at the next applied composition. Owed: a tool of the seat node-files that shows a file's attributes (none exists), and the engine's record says when its words date from. | H2 |
| Two hand placements more (the assigner's compositions fix and the indexer with pins by package path), each on its machine, because their own pipelines could not deliver them; the runbook. | H1, the runbook |
| The "unknown revision" kind, its cause read at 22:12: the Go build module (`mesh-build-go`), given no pin for a requirement at the zero version (a transitive one, or one a sibling names), borrowed the version of the first package of the same repository in the ask, wrong since pins became per-package versions; the registry, the indexer's pins and the publishes were right for the paths they name; the Go build module and the indexer (`mesh-delivery-indexer`). Settled by H-A-192 (a build module given no pin refuses the build; the catalog's change, in build) and H-A-201 (the entry pins every requirement of the module graph, transitively; in build in the indexer). | settled in H1 once delivered |
| The builder writes a git tag `go/v<version>` for every Go package, while the Go toolchain's direct fallback for a nested module looks for `<directory>/v<version>`, so the tags serve nothing; secondary, as the registry seat holds every real version; the builder. Owed: the tag takes the package's directory, or no tag is written at all. | H2 |
| A build that fails this way is asked again every 30 to 40 s, and the builder reserves a new version number each time (`mesh-build-go` 0.1.65 to 0.1.70 in five minutes): the builder never gives up a failing build of an unchanged fingerprint; the builder. Owed: a failed build of a fingerprint is not asked again until its inputs change, and no version is reserved for a build that failed before. | H2 |
| With H-A-196 and H-A-197 built (the SDK's one guard against a second pull loop on a durable; the tool runner claims through it), two durable pull loops in the delivery repository still call the bus client directly: the watchman's dead-letter loop and the grants holder's main loop; each binds one durable once today, so there is no fault, but the kind is open there; the watchman and the grants part. Owed: both route through the SDK's consume function, in a change after this group's SDK is published (a module builds against the latest published SDK); the review that finds a direct durable pull is the check. | H2, or the next change of the delivery repository |
| The seat mesh-grants's verb `grants-for` (row 69): the grants holder keeps the catalog revisions it read, at most `grants-for-revisions-per-branch` per branch and only for the branches it follows, and learns the branch's newest revision from the catalog-revision event; the grants part. Settled by H-A-193 and H-A-195; merged as pull request #294, whose pipeline failed on other faults, so it is delivered with the next passing pipeline. | settled in H1 once delivered |
| The publishes the builder heard lived only in its memory and were lost at a restart, so a build waiting for a package published before it waited the whole bound; the builder. Settled by H-A-194 (before it waits, the builder asks the package registry seat's `versions` verb once), in pull request #291. | settled in H1 once delivered |
| A package artifact's steps lacked its same-repository requirements (H-A-198), and writing the derived "../" paths into the entry (H-A-199) would have changed the form of the seat mesh-catalog's `modules` value, which every module decodes, so every reader would have had to run the new client before the writer: the mesh cannot derive that ordering edge yet; the Go build module (`mesh-build-go`) and the indexer (`mesh-delivery-indexer`). Settled for H1 by H-A-202 (the Go build module derives the same-repository tree transitively; the indexer takes those directories into the fingerprint for every form without writing them into the entry). Owed: a change of a kept value's form is an ordering edge the delivery plan derives (a contract version on the value, or the readers' release before the writer's). | H2 |
| The indexer pins every other-repository requirement across the module graph, never one of its own repository (H-A-201, pull request #296), and the Go build module refuses a build with no pin (H-A-192, the catalog's change); together they end the "unknown revision" kind (row 72); the indexer and the Go build module. | settled in H1 once delivered |
| The seat mesh-catalog's hand-written digest helpers lived under the contract's generated root, so the generator's check failed every unit step; the contracts module. Settled by H-A-200 (they live in the seat's hand-written client), in pull request #295. Owed: the generator's check runs in the contracts module's own unit step on the mesh (it does today), and the hand-written clients' import of the delivery SDK (ADR 0625 §3) is still on trunk. | H2 |
| The pipeline runner's lint, unit and integration asks carried no pins (only the build ask does, and the builder adds them), so once the Go build module refused a requirement with no pin (H-A-192) twelve test steps of the contracts mover could not run; the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-203 (every step ask carries the entry's pins), in build in the runner. | settled in H1 once delivered |
| The entries of modules not changed since kept their old `packages`: a direct requirement with no pin although the registry held its version, a declared package never published left out, a same-repository chain missed; six build asks were refused; the indexer (`mesh-delivery-indexer`). Settled by H-A-204 (an entry names every requirement, with an empty version where none is published so the builder waits; a publish re-pins every kept entry of any repository; a tool answers one entry's pins), in build in the indexer. Owed: the kept-entry rule "unchanged unless it imports a package the commit moved" is replaced by the publish re-pin everywhere. | H2 |
| A second build node still ran the Go build module (`mesh-build-go`) from before the pin refusal, so one pipeline's build borrowed a pin there and failed "unknown revision" while the first build node refused loud; the fixed build module could not be placed on that node tonight, so its Go steps were paused by its tool; the Go build module and the runbook. Owed: a hand placement reaches every node that runs the module, or the module is delivered by its pipeline (H1's purpose). | H1, the runbook |
| Two pipelines of consecutive revisions ran at once, and the older one's builds failed "revision 45 of main not in the builder's picture within 2m0s" while the seat mesh-catalog's revision verb answered 46; the builder. Settled by H-A-205 (for a revision below the newest it heard, the builder asks the revision verb by number), in build. | settled in H1 once delivered |
| A test step of an entry whose package has no version yet went out without that pin and was refused; the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-206 (a Go artifact's test steps wait for their pins as the build does, "waits on the publish of <path>"), in build in the runner. | settled in H1 once delivered |
| The Node and the Go build modules' tools that list their running steps do not list delivery asks (the builder's own asks), so the check "no running step" before a hand restart cannot see them; the Go build module's was seen at 01:17 to 01:19, its step list showing none while the seat's `current` verb showed asks running; the Node build module and the Go build module (`mesh-build-go`). Owed: each list names every ask the module runs, whoever asked. | H2 |
| A test step held for a pin not yet published had nothing to end it once its build passed (the builder had read the registry and pinned it), so with one pipeline at a time the queue would stop; the pipeline runner (`mesh-delivery-pipeline`) and the builder. Settled by H-A-207 (the build's end reports the pins it built with, the seat mesh-builds' end carrying `packages`, and the runner asks the held steps with them), in build. | settled in H1 once delivered |
| The reading of the module graph (H-A-201) runs at a take-in, which applies a repository whole, so repositories with no merge since the rule changed kept their modules' direct requirements only, and no tool took a repository in again; the indexer (`mesh-delivery-indexer`). Settled by H-A-208 (the tool `indexer_take_in_again`), H-A-209 and H-A-210: the take-in again keeps no catalog revision and asks no gate; it re-reads the repository's kept requirements at its merge commit and recomputes the modules state as a publish re-pin does; in build. Owed: a change of the indexer's rules recomputes every repository by itself at the indexer's start; the tool is the hand form of that. | H2 |
| The pin kind (rows 62, 66, 72, 79, 81 to 85, 87, 88) was fixed one instance per round for five hours, against the rule "at the second failure of a kind, fix the kind"; the rule was then written whole as a specification with a gap table against the code ([H-pins-spec-and-gaps.md](H-pins-spec-and-gaps.md)): 35 lines, 24 built, 6 built otherwise, 1 contradicted, 2 missing, and 7 changes still missing (its section 8), the largest that a re-pin on a publish never became a revision or a mover (the "entry-missing" holds on wants), settled by H-A-211 (a re-pin is taken in as the next catalog revision of the same source); the indexer (`mesh-delivery-indexer`), the pipeline runner, the builder and the Go build module. The lesson for playbook 07: a kind met twice gets its specification before its third fix, and one owner across every part it touches. | H1 (the way of working); H2 for the owed items of the specification's section 8 |
| A catalog revision's number equalled the gate's source revision by habit, so a re-pin had no number to keep its entries under, and the pipeline runner started a pipeline per published artifact (several per release) from its own hearing; the indexer (`mesh-delivery-indexer`), the seat mesh-catalog's definition and the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-212 and H-A-213: a revision's number is the indexer's own counter, with the gate's source as a field; a revision carries its call (`call`: take-in, release of a module version, or take-in again of a repository); one pipeline per release revision; the runner keys pipelines and reads revisions by number. The call's kind is a field of its own, `call-kind`, an enumeration the seat's schema validates (take-in, release, take-in-again), with `module` and `version` or `repository` beside `call`, the words for a person, so no reader parses words (H-A-215). The seat mesh-builds' package-published names the revision it was built from (`revision`, set by the builder), so the runner finds the publishing pipeline among several revisions of one source (H-A-218). Every ask of the runner (build, step, wants) names the catalog revision number in its `revision` field, with the gate's source beside it in `source`, so a build module and the builder read one meaning of the word (H-A-219). A build the builder starts from its own picture takes its revision number from the picture's half into its reservation, so its publish names the same revision its source comes from (H-A-220). The runner's pipeline subjects (pipeline-started, pipeline-ended, wait-held, wait-ended) name their last token `<revision>` and carry the pipeline's revision number, the same number as its key, so name and value agree (H-A-221). In build by the one owner of the pin kind (row 89). | settled in H1 once delivered |
| With revision numbers no longer the gate's source (row 90), two readers still looked a revision up by its source: the seat mesh-catalog's revision verb's source input, and the indexer's freeing of a pipeline's pins on the seat mesh-wants' pipeline-wanted, which named only the source; and the take-in again could re-read only the trunk, since only its merge commit is kept; the indexer (`mesh-delivery-indexer`). Settled by H-A-214 (pipeline-wanted names the revision number; the verb's source input answers the take-in's revision; the take-in again covers the trunk, and another watched branch is re-read at its next merge). In build by the pin kind's second owner: the first ran out of context after the indexer's part, and the hand-over cost one review round. Owed: a take-in again of another watched branch, once branches live longer. | settled in H1 once delivered; H2 for the owed item |
| Beyond the publish re-pin, three more whole recomputes of the indexer (on a build module's assignments change, on a toolchain report, and by the recompute tool) moved fingerprints with no kept revision, and the assigner (`mesh-delivery-assigner`) derived a pipeline's source from its key, which now carries the revision number; the indexer (`mesh-delivery-indexer`), the pipeline runner and the assigner. Settled by H-A-217 (any recompute that moves a fingerprint keeps a revision of `call-kind` recompute naming its reason; the runner treats every revision whose kind is not take-in alike, one pipeline for its movers) and H-A-216 (the assigner keeps the source the pipeline's end names and sends it in pipeline-wanted beside the revision). In build by the pin kind's second owner (row 91). | settled in H1 once delivered |
| The joined pipeline runner (`mesh-delivery-pipeline`) crashed at every start on the control-node ("concurrent map writes" in its per-mover step store: the store's shared maps were written under each pipeline's lock only, while the start placed several branches' waiting pipelines at once) and was rolled back within a minute. Before dying it had split two kept pipelines into per-mover keys, and the old runner then placed one running pipeline's steps again from the emptied record, losing that record's history; no hand repair, as the new runner composes from the keys; the pipeline runner. Settled in H1 by a mutex over the store's maps and a run of the race detector over the runner's start path with kept pipelines. Owed: every module's unit and integration suites run under the race detector in the check, and a tool that lists the runner's state keys (a whole list exceeds the bus; no key listing exists). | H1 (the fix); H2 (the check and the tool) |
| The indexer (`mesh-delivery-indexer`) refused its own take-in-again tool's ask ("a takeins value naming no hand act the indexer serves"): the decoder of a take-in ask kept a hand-written list of hand-act fields that the new field was not added to, and no test sent a tool's value through the decoder; the indexer. Settled in H1 by deriving the check from the ask's fields, and by a table test that decodes every tool's value. Owed: the same table test for every module whose tools write asks its daemon decodes. | H1 (the fix); H2 (the kind across modules) |
| The seat mesh-catalog's revision verb answered from the tools bundle's view of the trunk in memory, which ran one or more revisions behind the kept revisions once releases kept several in a row, so the pipeline runner waited minutes for a revision the indexer had kept (four minutes for revision 52) and the builder's picture failed a pipeline's first builds past its bound (rows 68 and 84); the indexer (`mesh-delivery-indexer`) and the builder. Settled by H-A-222 (the verb answers the newest kept revision read from the store at the ask; the builder's picture holds an ask that names a kept revision number, read by number), in build. | settled in H1 once delivered |
| A release re-pinned a mover of a running pipeline of 120 movers (the tool runner, pinned to the SDK's new version) while that pipeline still built it at the old fingerprint; the build failed and, as a pipeline passes or fails whole, took every other mover with it, because the runner moved only movers of waiting pipelines; the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-223 (a moved mover leaves a running pipeline too: its steps end superseded, its asks are cancelled, the end judgement counts it as left; a pipeline whose every mover left ends superseded), in build in the runner. Also seen in the same pipeline: two builds done "but no version is reserved", because the builder's picture lagged the revision that named their fingerprints (row 95's cause). | settled in H1 once delivered |
| On the build node the SDK's own integration test of the views reader ("the views reader and two handlers share the module's one durable") failed under the new guard against a second pull loop on one durable (H-A-196), while the same test passed locally at review. The cause, not the guard: the test read the durable's pending-ack count the moment the handlers had spoken, while the reader acknowledges afterwards and the bus takes acknowledgements on its own, so one was still pending on the loaded build node; the test now publishes a mark event and waits for the consumer's acknowledged floor to reach it, fixed in mesh-sdk, in review. The kind: a test reading the bus's acknowledgement count right after a handler speaks; mesh-sdk. Also seen: four release-revision pipelines waited with no steps for over ten minutes behind one running pipeline that could no longer pass, because the pipeline runner (`mesh-delivery-pipeline`) runs one pipeline at a time and ends a pipeline only when its last step ends. Owed: a pipeline that cannot pass ends at once (H-A-163 as written), and the queue's setting is raised once the build nodes allow. | H1 (the SDK's fix); H2 (the queue) |
| With the SDK's new guard against a second pull loop (H-A-196), which reads a consumer's cached information at bind, a test fake of a consumer in the indexer (`mesh-delivery-indexer`) that answered no such information panicked, so the indexer's unit step would fail against the new SDK although no indexer code changed; mesh-sdk and the delivery repository's modules. Fixed in H1 by completing the fakes across the delivery repository's modules. Owed: a change of the SDK that adds a call on an interface every module fakes is tried against the modules' suites before its merge (the group's check builds every importer, but runs no importer's suite). | H1 (the fakes); H2 (the check) |
| The builder was restarted by hand while Go asks ran in the Go build module's runtime (`mesh-build-go`), whose step list showed none because it does not list the builder's own delivery asks (row 86); the asks survived the restart because the build module runs them, but the "no running step" check before a hand restart is blind to them; the build modules and the runbook. Owed: one tool across the build seats that lists every running ask, whoever asked it. | H2 |
| The watchman's entry still pinned no client that its same-repository `buildrun` module requires, because the watchman's go.mod names `buildrun` in a replace directive without a require line, and the reading of the module graph (H-A-201) followed require lines only; six test steps were refused "no pin" (rows 79 and 82); the indexer (`mesh-delivery-indexer`). Settled by H-A-224 (a same-repository module named only by a replace counts as required; its requirements are pinned transitively), in build in the indexer. | settled in H1 once delivered |
| The builder keeps one reservation per module and series and bumped its number on any new run of a build (a restart's re-run included), while the run already building carried the old number, so its publish was refused "has no version reserved or released"; and a take-over of the series by another fingerprint dropped the older reservation without stopping the older build, which then published a dropped number; the builder. Settled by H-A-225 (a reservation is kept for the same fingerprint until it is released; a taken-over build is withdrawn; a number never published is freed), in build in the builder. Its last clause is withdrawn by H-A-226: the builder's Built and the reserved answer match by version alone, and the registry refuses a republish with other bytes, so a reused dropped number would let a withdrawn build's late publish land in the new reservation; a dropped number stays a gap, which harms nothing, and the series key keeps only the withdrawn numbers above the catalog's highest released patch. Also seen: after the builder's start it logged "no seat builds an artifact of language go and kind package" dozens of times a second (the journal suppressed over a thousand lines); not a spin but a burst at the start: every catalog entry taken in and every seat definition heard plans every known module again, and a failed plan is not kept, so the same line is logged once per definition and module. Owed: a failed plan is kept and said once until the seat list changes. | settled in H1 once delivered; H2 for the owed items |
| A restart of a node's tool runner (`node-tools`), to load one module's new tools bundle, silences the seat verbs of every module whose tools run inside it: the artifact registry seat answered "no responders" for about two minutes while the control-node's tool runner restarted, and the builder's publishes failed meanwhile; the tool runner and the builder. Owed: a tool runner serves one module's bundle again without restarting (H-A-158's make before break, for a bundle), and a publisher retries a seat that answers no responders, within a bound. Also seen there: the registry seat's list answer exceeds the bus (1.5 MB; pages are owed, the same habit as row 65), and a finding of kind read-side-down raised by one writer cannot be cleared by the tools' writer (owed: one owner per finding kind). | H2 |
| The thirteen issues the lead held were judged against what the milestone delivered: five closed as superseded by H's merge call and the checker's retirement (the forge's status writes, the merge Approve path, a second check overwriting the first, a gate merge without a manifest, a refused merge asked again); three resolved with their fixes named (the controller's check bound, the checker's tests on the desktop, the build node's resolver); one released back to open (the verbs of the seat node-package-manager, which H does not touch); two kept with a note (the bus flood, whose kind now sits on the connection of the control-node's tool runner; the session not told of an answer); and two wait for the proofs (a held module's chain; one release for a change across repositories, proof 2); the issue tracker. A missing tool was met: no forge tool lists merged pull requests by number. | H1 (done); H2 for the two waiting and the tool |
| The artifact registry's receiver read its incoming object store's fill on every chunk it took, and the tool runner (`node-tools`) answered the fill by listing every kept description of the store, the leftovers of about twenty thousand deleted chunks included, so the control-node's tool runner read fourteen megabytes a second and the bus ran at full CPU; every take-in and publish slowed (proof 1's take-in took six minutes), and discovery answered incompletely (rows 65 and 102); the artifact registry, the tool runner and the delivery SDK. The recovery (drop one dead upload, purge the store's leftovers) removes data and was put to the operator. Settled by H-A-227 (a fill is read from the stream's own figures, never by listing; a receiver reads it once per transfer; the owner compacts a store of leftovers), in build in the tool runner and the delivery SDK. Also seen: three findings streams stood full (the pipeline runner's, the builder's and the node-engine's); owed: a findings stream bounded by age, and a reader of its fill. | H1 (the fix); H2 (the compaction and the bounded streams) |
| The validate step's run ask (the manifest validator's program, built and run from the delivery repository's tree) still carried no pins after H-A-203 was built for the test asks, so with the build module refusing a requirement without a pin every validate step ended "could not run" (proof 1's feh at 01:56, the SDK's at 01:30) and no composition followed (rows 81 and 85); the pipeline runner (`mesh-delivery-pipeline`). Settled in H1 by giving the validate ask the pins of the manifest validator's own entry at the pipeline's revision, in build in the runner. The kind: every ask the runner makes carries pins, and a review that reads "every step ask" lists the asks. | settled in H1 once delivered |
| The bus module's keeper reads only a manifest's new-form asks, so the eleven entries the two foundation parts (the artifact registry and the forge) declare in their old sections, all with live data, stand as orphans to it: the registry's incoming store could not be rebuilt empty ("an orphan: drop it, or ask for it in a manifest again"), and the only way to empty it was a drop on the operator's warrant followed by the grants part's assert that makes it again; a careless drop of any of the other ten would lose live data (rows 65 and 104); the bus module. Settled by H-A-229, H-A-230 and H-A-231: every manifest's old-section entries are asked for, never orphans; the keeper keeps, grows and rebuilds only those it made, and creates none (the grants part makes the rest); in build in the bus module. Ten of the eleven clear; the lower-case events stream, which the keeper made under a name the grants part does not derive, stays an orphan, to be dropped on the operator's warrant. | H1 |
| Three fixes were merged between 02:09 and 02:13 and each taken in within a minute (the flood halved after the dead upload was dropped): the validate and composition run asks' pins (the holder of the seat mesh-wants), the tool runner's fill from the stream's figures, and the receiver's one read per transfer. The first lands in the holder that runs on a node of its own and through which every validate step runs, so no pipeline can deliver it to itself: a hand pack for that node, copied by the operator at their terminal (the session's permission check refused the lead's copy) and restarted there before the running pipelines' validate steps can pass. The last of the three re-pins twenty-nine modules into one pipeline; the runbook. | H1 |
| The bus module's drop of an orphan asks the operator's warrant with a window of ten minutes, and then ends with nothing removed ("ask again with a new request") while the operator is away, whereas the session's own asks carry an expiry the asker sets (up to a day); the drop's warrant should carry the asker's expiry too, or at least the operator's answer to the session's ask should count (row 106); the bus module. Owed: the bus module's warranted acts take an expiry from their caller. | H2 |
| The bus module's orphan judgement (row 106) was fixed, reviewed in two rounds (the first found the keeper taking into its care a state's object store the grants part made, and its cap sum dropping kept state buckets) and merged at 02:33; its take-in took close to three minutes while the indexer waited on a package's versions, where the night's others took under a minute; its pipeline waits with five others on the validate fix reaching the node that runs the holder of the seat mesh-wants (row 107); the bus module and the runbook. | H1 |
| Every take-in of the catalog repository since a Go module was removed from it on 2026-11-17 said "its packages are not published": the indexer (`mesh-delivery-indexer`) lists a repository's packages from its kept packages state too, which still holds the removed module, so the forge's listing of the whole set fails, and the indexer's one-directory fallback runs only on its own error, not on the forge's. Nothing of that repository was published since, so the digests of its three same-repository packages froze on their last commit, and a change to one would not move its seven importers, unsaid; met twice tonight before it was read (row 81 on the pins kind; issue 1585, one release for a change across repositories); the indexer and the forge module. Settled by H-A-232 (a repository's packages are those in the merge's tree, and a gone key is dropped and said; the forge answers not-found and the fallback runs on it; any other failure stays loud), in build in the indexer and the forge module. | H1 |
| The operator restated at about 03:33 the bound ADR 0282 decides: a fix to a leaf module runs healthy on every node within five minutes of its merge, a core module within ten. Tonight's measured parts: merge to take-in 25 to 45 s for the delivery repository and 2 min 40 s to 5 minutes for the catalog repository (cause not yet known; the indexer waited on a package's versions); take-in to placement about two minutes under the queue of pipelines at once; a leaf's build step running past six minutes; and no pipeline reaching its composition since 01:56 (the validate asks). No pipeline completed merge to running tonight, so the whole is unmeasured (rows 105 and 107); the pipeline runner (`mesh-delivery-pipeline`) and the condition keeper. Owed: the pipeline's phases timed and said per pipeline (the pipeline-ended event carries each step's start and end), and the delivery time held against ADR 0282 by a condition. | H2 (the measure); H1 records it |
| A release pipeline held the pipeline runner's one slot for nine hours (02:06 to 11:08): its validate ask was lost when the holder of the seat mesh-wants was restarted for a hand pack, and the runner waits on an ask without a bound, so eight pipelines queued behind a step nobody would answer, until the lead cancelled it on the operator's word (rows 107 and 111); the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-235 (every ask the runner makes is bounded, asked again once, then ends could-not-run with a finding, and the slot frees), in build in the runner. | H1 |
| The runner's rerun of a validate step was always refused ("placed no ask now"): the verb looks for the ask by the mover's id, while the validate ask is one per pipeline and names no mover (H-A-51), so a failed pipeline's validate could not be asked again after the pins fix, and proof 1 had to be run a second time from a new merge (row 105); the pipeline runner. Settled by H-A-236 (the rerun of validate asks the pipeline's one validate ask again; the rerun of composition builds the composition ask for the named mover), in build in the runner with the row above. | H1 |
| The bus module's drop and rebuild warrants ask at the destroy level, which needs a code no channel carries yet, so the router held all four of the night's asks unshown ("no channel can carry it now") while the tool answered "the operator is asked", and each expired after ten minutes; the operator saw nothing on Telegram (rows 106 and 108); the bus module and the operator channel's router. Settled by H-A-237 as a weighed bend the operator asked for: the keeper asks at the approve level until a channel carries destroy, with the caller's expiry; the tool reads the router's record and says offered, held or refused; the router's hold reason names the level. Owed: the destroy proof stays designed (ADR 0259), and a channel that carries a destroy answer. | H1 (the bend); H2 (the destroy channel) |
| Once the slot was freed, the first pipeline through the fixed holder of the seat mesh-wants passed at 11:07 (a release of a contracts package, six movers): validate three minutes after placement, compositions on the build node, the pipeline ended passed, and the next took the slot within a minute; the pipeline runner (`mesh-delivery-pipeline`). Still seen: the seat mesh-grants's verb `grants-for`, cut after 5 s, marks every mover's widens could-not-run (rows 69 and 76, the grants cache); and two movers are over the test budget (an NFS server module at 51 integration tests, a package manager module at 121, against 50). | H1 (the pass); H2 (the cut, the budget) |
| Proof 1 runs a second time: one line in the wallpaper module, merged at 11:07:56, taken in 2 min 51 s later as its own pipeline with the one mover, and placed last in a queue of six; the catalog repository's take-in still says "its packages are not published", because the forge's not-found fix is merged but not running yet (rows 110 and 113): the hand packs of the forge module and the indexer go onto the control-node now, on the operator's word, with the tool runner's; the runbook. | H1 |
| On the operator's word ("if you would run all the changes on our local machine, it wouldn't take that long"), the night's merged fixes to the delivery system itself went onto the control-node as hand packs between 11:10 and 11:19 (the indexer, the forge module's code, the tool runner for seventeen units), each by its notes, with the kept copies beside; all units are active and the forge's listing verb is served; the two proofs alone go by their pipeline (rows 107 and 110); the runbook. Seen in the indexer's journal: its findings writer owns four kinds while its code raises others (a missing pin, generated types out of step, a merge not taken in), so the writer refused them once a minute for hours and no finding of the indexer was written; the kind of H-A-233 would have met the same; the indexer (`mesh-delivery-indexer`). Settled by H-A-240 as H-A-242 corrects it (row 119). | H1 |
| The root of row 112: the holders of the seats mesh-builds and mesh-wants take their asks on a plain subscription, not from a work queue, so an ask put while the holder is down (a hand pack's restart) is lost, and neither seat says a word about an ask before the step's end (rows 107 and 112); the pipeline runner (`mesh-delivery-pipeline`), the builder and the holder of the seat mesh-wants. Settled by H-A-241 and H-A-243: the runner puts every open ask of a seat again when the seat's holder starts, on the node-engine's running event; for a seat that says no first word, one silent bound (`ask-silent-bound`, default forty-five minutes) ends the step could-not-run instead of two short ones, so no build of ordinary length is cut; the second ask's id is derived in the accepted form; in build in the runner with rows 112 and 113. Owed: the seats' asks as a work queue, and an ask-taken from both holders. | H1 (the runner); H2 (the queue) |
| Row 117's cause corrected: the refusals come from the SDK's held writer, which at its start seeds every key of the module's shared findings state, the daemon writer's kinds included, and refuses them once a minute, against the design's rule that no bundle reads the whole state to state another's findings (G §580); mesh-sdk and the indexer (`mesh-delivery-indexer`). Settled by H-A-242, which corrects H-A-240: the held writer seeds only the kinds it owns; each writer's kinds stay in code, with a unit test holding the code to them; an unowned kind is said once; no manifest field; in build in the SDK and the indexer (row 117). | H1 |
| A pipeline placed from the queue nine hours after its take-in still carried a mover whose fingerprint a newer revision had moved at 03:33 (the series taken over by the newer build), so its build step found the old build done but holding no number, and the pipeline failed: the rule that a moved mover leaves a pipeline (H-A-223) was applied to running pipelines only (rows 90 and 112); the pipeline runner (`mesh-delivery-pipeline`) and the builder. Settled by H-A-244 (the rule holds for every pipeline not ended; the builder's answer for such a build says "stale: its series moved", never "no version is reserved"), in build in the runner and the builder. | H1 |
| A package's version tag (`go/v0.1.59`) stood at another commit on the forge, so the version-released event could not write it and was given up after five deliveries while the publish went on (row 101); the builder. Settled by H-A-245 (the builder reads the tag through the seat git before reserving a number, and takes the next free one, with the finding version-tagged-elsewhere; a tag is never moved). Owed: its build in the builder. | H2 |
| The bus module's warrant fix (row 114) was reviewed in two rounds and merged at 11:28, and taken in three minutes later as a pipeline of two movers (the bus module and the router). The same take-in proved the hand-placed indexer and forge module (row 117): the forge's listing answered not-found for the gone directory, and the take-in went through where every one since 2026-11-17 had said "not published" (row 110). The bus module's hand pack is built from that merge and placed on the control-node next; then the registry's incoming store is dropped on the operator's warrant at the approve level and made again empty; the bus module and the runbook. | H1 |
| With the bus module's hand pack placed (11:35), the drop of the registry's incoming store was refused by design (the store is asked for again, row 106), and the rebuild was asked at the approve level: the router offered it on Telegram at once, the operator chose Rebuild, and the keeper took a snapshot and rebuilt the store empty at 11:39:46, so row 104's recovery is done (rows 104, 114 and 122); the bus module. Seen beside it: the keeper does not withdraw the ask of a request it refused at once, so a dead "remove it?" stayed on the operator's channel until it expired. Owed: the keeper withdraws the ask of a request it refuses. | H1 (the recovery); H2 (the withdrawal) |
| The rebuild did not end the flood: the bus still delivers about six thousand messages a second (five to seven megabytes) to the control-node's tool runner, so the listing of that store was one source and not the only one (rows 102 and 104). No tool of the bus module reads consumers by delivery rate or creation time, nor a connection's busiest subscriptions, so the source could not be named from the tools (a missing tool, by the instruction one-question-one-tool). Under reading now: the artifact store's bundle asking the registry's list verb in a loop, while the registry answers by listing a store whole and the answer exceeds the bus's 1 MiB; the bus module, the tool runner (`node-tools`) and the artifact registry. | H1 (the source); H2 (the tools) |
| The flood's second source, read at 11:47: the artifact store's bundle starts a sweep on every finished build and an observation on every want change, each reading the builder's builds state key by key (ten thousand keys, two bus answers each, because the tool runner binds the bucket before every read), the starts queued behind one lock and draining back to back, and it asks the registry's list at every pass though its answer exceeds the bus's 1 MiB: about a third of the six thousand messages a second (rows 102, 104 and 124); the artifact store's bundle, the tool runner (`node-tools`) and the artifact registry. Beside it, the registry refuses that bundle's removals as not the sweep's, so the store never shrinks. Settled by H-A-250 (one pending pass, one paged read, a loud stop with the finding artifact-list-unread) in the artifact store's bundle and H-A-251 (the tool runner binds a state once) in the tool runner, both in build. H-A-257, H-A-258 and H-A-260 amend the followed view: its first view is the watch's handover, a build's end comes from the builder's log, and an unread end holds the pass and raises the finding artifact-builds-unread. Owed: the registry's list paged (with row 102), and the sweep's removals taken by the registry. | H1 (the two fixes); H2 (the list, the sweep's refusal) |
| A pipeline's validate passed at 11:40 and the pipeline runner dropped its end: the one validate ask names no mover, the holder's end names the mover whose body it took, and the runner compared it with the first step carrying the ask ("a step's end the runner does not take"), so every mover's validate stayed running and the pipeline held the slot until the lead cancelled it, proof 1's behind it; seen at 01:11 too; the second of row 113's kind, a shared ask read as one mover's (rows 113 and 118); the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-252 (a validate end matched by its ask alone ends every mover's validate step; the same for the composition's shared runs), in build in the runner with rows 112, 113, 118 and 120. | H1 |
| Proof 1's second run passed its pipeline: merged at 11:07:56, taken in at 11:10:47, placed at 11:48:00 after thirty-seven minutes in the queue behind five older pipelines (one held nine hours by a lost ask, one by a dropped end), and built, tested, validated and composed by 11:49:06, sixty-six seconds from placement; the queue, not the pipeline, took the time (row 111); the pipeline runner (`mesh-delivery-pipeline`). | H1 |
| The pipeline's wants were written only at 11:54:21: the holder of the seat mesh-wants runs its pass (the assignment graph, the tiers' judgement, the wants) only when a catalog revision arrives, so a passed pipeline waits for an unrelated merge's take-in (five minutes here, twelve for an earlier one) (rows 111 and 127); the holder of the seat mesh-wants (`mesh-delivery-assigner`). Settled by H-A-256 as H-A-259 corrects it (row 131). The node-engines on the desktop and the build node took the new want within a minute and updated the module's tools bundle, the files bundle following the composer. | H1 |
| The SDK's paged read of a state takes a key as its cursor while the bus reads no key range, so a page read replays the bucket once per page, and a large state read in pages costs more than key by key (rows 102 and 125); mesh-sdk, the tool runner (`node-tools`) and the artifact store's bundle. Settled by H-A-255 in H1 (the artifact store's bundle reads the builder's builds from a followed view, no bus read per pass), amending H-A-250 and H-A-254. H-A-257, H-A-258 and H-A-260 amend the followed view: its first view is the watch's handover, a build's end comes from the builder's log, and an unread end holds the pass and raises the finding artifact-builds-unread. Owed: H-A-254 (pages in sequence order with an opaque cursor, a contract change). | H1 (the view); H2 (the cursor) |
| The pipeline runner's change for rows 112, 113, 118, 120 and 126 was built as eight commits and approved in three rounds (the rounds found a validate rerun covering one mover only, bounds that expired while the runner was down never heard, and a restart asking an answered step again), and is merging now; the pipeline runner (`mesh-delivery-pipeline`). The reviewer's notes stay owed: a holder restarted at the same build with its health unchanged says no new running, so its lost asks are not put again until the seats' asks travel through a work queue; and the builder's build log does say a build started, a first word H-A-241 could use (rows 112, 118 and 126). | H1 (the change); H2 (the notes) |
| Row 128's cause corrected: the holder of the seat mesh-wants does wake its pass on the pipeline-ended and running events, but each pass that keeps a fresh assignment graph revision sits six to eight minutes keeping and removing revisions (every unlisted entry object read one at a time, the kind of row 125), so a wake waits for the blocked pass: feh's wants at 11:54 were the end of a pass begun at 11:46 (rows 125 and 128); the holder of the seat mesh-wants (`mesh-delivery-assigner`). Settled by H-A-259, which corrects H-A-256 on the cause (the keeping runs off the pass loop, one at a time; its judgement reads the entries in one read; each pass and keeping logs its duration), in build in the holder. | H1 |
| Between 11:50 and 12:03 four changes merged and were each taken in within a minute or two: the SDK's held findings writer (rows 117 and 119; its release re-pins 126 modules into one pipeline), the indexer's finding kinds (row 119; its merge was held seven minutes until the SDK's Go package was published, so it builds against the new version), the tool runner's bind once (row 125) and the pipeline runner's bounded asks (row 130). Their hand packs go onto the control-node now; the queue of pipelines behind them runs for hours, the one of 126 movers above all (row 111); the runbook. | H1 |
| Proof 1's one line never reached the file: the wallpaper module is a moved module, so its template file is the provisioner's to fill (ADR 0349 §4); the node-engine deletes the file's content and hands a plan line to the provisioner, and the provisioner's client renders the files archive on the machine. The provisioner on the control-node runs a build from before the indexer's view rename, asks every minute for a first view the indexer no longer serves (503, no responders), and has made no plan since 2026-11-20 09:41; its own pipeline was the one cancelled in row 126, so no current build of it exists. The node-engines did take feh's new want and its tools bundle within a minute, and the builder did publish the new files archive (its digest moved twice since 2026-11-20) (rows 126, 127 and 128); the provisioner and the runbook. The provisioner goes onto the control-node as a hand pack from main on the operator's word (row 117), and its plan then names the new archive. Owed: a cancelled pipeline's movers get a pipeline again by themselves. | H1 (the pack); H2 (the cancel's movers) |
| The four hand packs went onto the control-node between 12:14 and 12:23 (the pipeline runner with its bounded asks, the indexer with its finding kinds, the provisioner from main, the tool runner for seventeen units), every unit active: the provisioner composed every machine from 12:17 without the stale first view; the tool runner's "finding kind not declared" line stopped; the mesh MCP server dropped for a minute at 12:16 and came back by itself; and the big pipeline's validate (row 126's kind) was asked again with the fixed verb at 12:23 and runs under its bound (rows 117, 130 and 133); the runbook. | H1 |
| Proof 1 (its second run) is shown: the wallpaper file on the desktop and the build node carries the merged line, read at 12:26. The chain: merged at 11:07:56, taken in at 11:10:47, placed at 11:48:00, passed at 11:49:06, the want written at 11:54:21, the node-engines applied it within a minute, the provisioner's plan named the new files archive at about 12:23 once a current provisioner ran, and the file was written by 12:26. No hand act touched the module's own path; the hand acts were on the delivery system's parts (the assigner on the build node, the cancel of the held pipeline, the provisioner). The time from merge to running was 78 minutes, 37 of them in the queue and 30 waiting on a stale provisioner, so ADR 0282's five minutes is not met (rows 111, 127, 128 and 133); the runbook. | H1 (the proof); H2 (the bound) |
| Proof 2 began: the SDK's one-line change and the tool runner's were merged in one call at 12:26:59 (the seat git's merge verb with two members), the gate moved main's source to one revision for both repositories, and the indexer took both in together at 12:27:18 as one pipeline of 126 movers, the SDK and the tool runner among them (the SDK's release re-pins every importer); the pipeline waits fifth in the queue (rows 127 and 135). The acceptance: the tool runner runs on every machine at the new SDK version with no hand act; the gate, the indexer (`mesh-delivery-indexer`) and the pipeline runner (`mesh-delivery-pipeline`). Owed: a tool that reads one pipeline's movers, with the lighter read per step (row 124's kind). | H1 |
| The change of the holder of the seat mesh-wants for row 131 was built, reviewed in two rounds and merged at 12:41 as its own pipeline; the first round found wants written at the start before any revision is kept, and the full-store verdict moved out of the pass, both settled by H-A-261 (no want before a revision is kept; the full-store verdict is the pass's own); the holder of the seat mesh-wants (`mesh-delivery-assigner`). The reviewer's notes stay owed: the bus wrappers' race on one handle, met twice (a handle per goroutine, or a guard in the SDK), and a failed first keeping holding the wants until the next event. Also seen: with the pipeline runner's change live, the waiting pipelines collapsed as designed at 12:38 (three left the queue, their movers moved by the newest), so proof 2's pipeline stands next after the one running (rows 130, 131 and 136). | H1 (the change); H2 (the notes) |
| The pipeline ahead of proof 2 (774 steps) made no step the pipeline runner said from 12:42: four contracts modules added to their repository after the registrations' seed of 2026-11-14 were never registered (the seed writes only when no registration is held, and nothing registers a module that enters the module graph later), so their steps waited on a registration nobody had asked, with no bound and no finding (rows 112 and 136); the indexer (`mesh-delivery-indexer`) and the pipeline runner (`mesh-delivery-pipeline`). The build seats were in fact working the other movers while the usage view said none, because it judges a build module by the node-engine's held phase rather than its running asks. The recovery: the four were registered by the register verb, each an Approve on the operator's channel. Settled by H-A-262 (the indexer registers a module the moment it enters a watched trunk's module graph, with no ask, saying registration-changed; the runner raises the finding registration-missing while a mover waits on one), in build in the indexer and the runner. Owed: the usage view judges a build module by its running asks. | H1 (the fix); H2 (the view) |
| The pipeline ahead of proof 2 ended at 13:13:18, its contracts movers still unregistered, and proof 2's pipeline took the slot the same second, placing 182 steps within fifteen seconds; its three contracts movers wait on the same registrations (four Approves open on the operator's channel since 12:59, asked by the indexer at the lead's register calls); a newer merge took 28 movers of the delivery repository out of it at 13:22, while the SDK and the tool runner stay in it (rows 136 and 138); the pipeline runner (`mesh-delivery-pipeline`). | H1 |
| Row 138's fix was built in the indexer and the pipeline runner, reviewed in three rounds and merged at 13:22 as its own pipeline; the rounds found a finding that never cleared, three design points (a pending proposal is skipped; a module the seed left out is not registered by the graph; the branch is the one the siblings hold alike, else the repository's default) and an untested rule, settled by H-A-263, H-A-264, H-A-265 and H-A-266 (row 138); the indexer (`mesh-delivery-indexer`) and the pipeline runner. Its hand packs go onto the control-node next, so the indexer's start pass registers the four modules itself. Owed: a read of the registrations store in one call. | H1 |
| The hand packs of row 140 went onto the control-node at 13:27 and 13:28: the indexer's start pass registered a fifth unregistered module at once (a networking contracts module nobody had noticed) and skipped the four whose proposals were pending, as H-A-265 asks; the lead had those four proposals dropped with the indexer's own tool (the operator's four asks cancelled with them), and the next start registered the four at 13:28:29, each at version 1 with the warrant "module graph". The pipeline runner (`mesh-delivery-pipeline`) at its start said 115 movers of proof 2's pipeline "have no registration yet" before its view of the registrations had loaded, then placed 1048 of their steps at 13:30:55: a fault of the start order of the runner's new check, loud and passing (rows 138, 139 and 140); the indexer (`mesh-delivery-indexer`) and the pipeline runner. Owed: the check waits for the view's first read. | H1 (the registrations); H2 (the start order) |
| Proof 2's pipeline ran from 13:13 with over a thousand steps: the SDK's new version 0.1.29 was published, and the build node built modules against it from 13:58; the tool runner's six steps passed in it. Then the revision of the register-at-take-in merge (13:22) and the indexer's recomputes moved the tool runner and about a hundred other movers to the newer pipelines, as the rule says, so the proof's acceptance follows the tool runner's want on each machine rather than one pipeline's end; the superseded pipeline keeps running its remaining movers (rows 136, 139 and 141); the pipeline runner (`mesh-delivery-pipeline`). Owed: a read of a pipeline's record for one mover's steps (62 KB) still exceeds a reader without a shell, the lighter read of row 124's kind. | H1 |
| The pipeline that carried the tool runner after the move of row 142 ended failed at 15:03:55 on the required steps of three modules of the catalog repository, none of them the tool runner's (its build, tests, validate and composition all passed, its release 0.1.37 reserved): the forge module's TypeScript build cannot find the contracts package it imports and uses fields its contracts type lacks, and its integration test of the whole seat fails; the bus module's integration test of the whole module fails on the subtest "the fill pass runs while the first view is asked", the one every developer tonight reported as failing at trunk and skipped (by the rule of the second failure, the kind is fixed now, not skipped again); and the registry's integration test of the whole module fails; so no pipeline wrote a passed end for the tool runner, and its want stays. Seen beside it: the earlier pipeline passed at 14:26, but the holder of the seat mesh-wants wrote no want for its eleven remaining movers (its record of the pipeline's end names none of them; the SDK's want still names the morning's pipeline); and the builder has asked the registry to publish the tool runner's release again every few minutes since 14:50, with no "published" answered. Under reading (rows 104, 137 and 142); the forge module, the bus module, the artifact registry, the holder of the seat mesh-wants and the builder. | H1 |
| Row 143's causes, read by 15:30: (a) the Node build module places only the SDK into a trunk build and leaves out every other mesh package a package file names, so the forge module's TypeScript build has failed at every build since 2026-11-19 (H-A-267: every named mesh package at its latest published release, as the Go build module does through the pins); (b) the bus module's subtest waits for a first view's "answered", which the keeper never marks for an empty view, so it could never pass (H-A-268: the test waits for the first fill pass); (c) the builder reads every reservation per published event, fifteen seconds apiece, its consumer thousands behind, while its loop asks the same release to be published again every few minutes (H-A-269: one read by digest; no publish asked again while a published is unheard); (d) the holder of the seat mesh-wants skips in silence a passed pipeline's mover whose version the pipeline runner has not yet written, and the version waits on (c) (H-A-270: the skip is said; the runner says pipeline-ended again when a version is written after the end). All four fixes are in build, one owner each; the Node build module, the bus module, the builder, the holder of the seat mesh-wants (`mesh-delivery-assigner`) and the pipeline runner. The failure words of the registry's whole-module test and the forge's whole-seat test could not be read, because the runner's step outputs store holds no bytes for them (the rows of 18:40 and 19:50 on step outputs). The assigner's keeping fix (row 137) went onto the build node by hand at 15:25, and its passes now take 3 to 25 seconds (rows 124, 137 and 143). Owed: step outputs kept and readable. | H1 (the four); H2 (the outputs) |
| The builder's loop asking the publish of the tool runner's release 0.1.37 again (row 143) had a second cause under the first: the artifact registry holds that version at another digest than the build's, so even a heard "published" would not have marked it, and the asks would have gone on until the version ended unreleased; the kind of row 121, met on a registry instead of a tag (rows 121, 143 and 144); the builder. Settled by H-A-275 (a number a registry holds is never reserved; a done build so caught moves to the next free number, with the finding version-held-elsewhere) and H-A-274 (a registry record holding the built digest ends the publish as published), in build in the builder. The builder's fixes of the reading of events and the publish asked again (row 144 (c)) were approved at 15:45. | H1 |
| Row 144's four fixes were built and reviewed by 16:00: the Node build module's and the bus module's test (merged at 15:49 as a pipeline of 36 movers; the Node build module's pack goes onto the build node by hand, so the forge module's build can pass in it); the builder's (approved in two rounds; the second found that every artifact carries its version at build time, so a build whose number a registry holds at another digest is built again at the next free number rather than moved: H-A-279); and the pipeline runner's and the assigner's (approved in two rounds; the first found that a passed mover with no version yet must hold its tier, else a later tier is wanted before it: H-A-277). The merge of the runner's and the assigner's waits on the operator's word, because the session's permission check refused the lead's dispatch of it (row 144); the Node build module, the bus module, the builder, the pipeline runner (`mesh-delivery-pipeline`) and the assigner (`mesh-delivery-assigner`). | H1 |
| The tool runner (`node-tools`) sits in no live pipeline: its last one failed on other movers (row 143) and its fingerprint has not moved since, so nothing builds it again until a merge re-pins it; a module stranded by a failed pipeline gets no pipeline by itself, the kind of row 133's cancelled movers (rows 133, 142 and 143); the pipeline runner. Proof 2 therefore runs a second time, with a new one-line merge of the SDK and the tool runner once the fixes are live. Owed, as one rule: the movers of an ended pipeline that have no passed end are put in a pipeline again at the next kept revision. | H1 (the second run); H2 (the rule) |
| The builder's fix (rows 144 (c) and 145) merged at 15:59 and went onto the build node as a hand pack at 16:09 (its program only, the tools bundle left, so the mesh MCP server stays up; a publish in flight was cut by the restart and is asked again). Within three minutes the builder dropped the tool runner's held release 0.1.37 for a new fingerprint of the tool runner that a fresh pipeline carries, and reserved 0.1.38 for it; its loop that asks a publish again now waits, saying so every thirty seconds, while its events consumer's backlog of about 3,800 messages drains under the bound of a hundred at about one and a half a second (some forty minutes). The Node build module's pack went onto the build node at 15:59 too, and the forge module's build moved into the newest pipeline behind the Node build module's files (rows 144, 145 and 146); the builder, the Node build module and the runbook. | H1 |
| The builder's events backlog (row 148) drained at only fifty a minute under the new builder, holding up every publish and so every pipeline waiting on one: a published at a version many reservations share still cost three seconds (the fallback by version read every reservation at the version, and the journal line read them all again), and the SDK's event hub pulls five hundred messages per pull and handles them one by one, so buffered messages outlive the thirty-second ack wait and are given again (almost every outstanding message redelivered) and handled twice. Every recovery loses something (a purge of the consumer would drop take-ins, source moves and conditions among the publisheds), so the backlog drains while the fixes build (rows 144 and 148); the builder and mesh-sdk. Settled by H-A-280 (each reservation read once, the fallback only over the unbuilt ones, in-progress sent before long work) in the builder and H-A-281 (the hub pulls at most twenty per pull and keeps a slow handler alive with in-progress) in the SDK for every module, both in build. | H1 |
| Row 149's two fixes: the builder's (each reservation read once, the fallback over the unbuilt only, in-progress before the slow pass) was approved and merged at 16:47 as a pipeline of eight movers, its pack for the build node following; the SDK's (the event hub pulls at most twenty messages per pull and sends in-progress every third of the ack wait for a handler still running) is built and in review, and reaches every module at its next build against the new SDK release (row 149); the builder and mesh-sdk. | H1 |
| The SDK's event hub fix (row 150) merged at 16:51, and its release re-pins 126 modules into one pipeline, the tool runner among them. Every merge of the afternoon moved the tool runner to a newer pipeline before the older one could pass (rows 142 and 147), so the lead holds further merges from 16:52 until the queue runs through to the tool runner's pass; the one approved change still unmerged (row 146) waits on the operator's word. The builder's read-once pack goes onto the build node meanwhile, so the events backlog drains faster (rows 142, 146 and 150); the pipeline runner (`mesh-delivery-pipeline`), the builder and the runbook. | H1 |
| The builder was built again against the SDK's hub fix (row 151) and placed on the build node at 16:58 (its read-once pack at 16:52 before it, with no change in the drain rate): the redelivery stopped (two redelivered, against 175 before; nineteen unacknowledged, against the batch of twenty), and the drain rose to about 1.2 messages a second, so the backlog of 2,167 at 17:05 falls under the bound in about half an hour. What remains is about one second of work per event. Each restart of the builder cut one publish in flight, which the loop asking a publish again asked again; the tool runner's release 0.1.40 waits in main.117 on thirteen publishes (rows 149, 150 and 151); the builder. Owed: the cost per event of the builder's published handling, measured and cut. | H1 (the fixes live); H2 (the cost per event) |
| Once the builder's backlog had drained (17:19), the tool runner's release could not publish for another reason: the tool runner imports about twenty packages its own pipeline releases, each package's publish re-pins it (H-A-204), each re-pin keeps a revision of the same source, each such revision's pipeline takes it out of the running one (H-A-223), and each newer build withdraws the older before it publishes; its release ran from 0.1.41 to 0.1.48 in nine minutes with none published: a livelock for any module that imports many packages of one pipeline (rows 142, 147 and 152); the pipeline runner (`mesh-delivery-pipeline`) and the indexer (`mesh-delivery-indexer`). Settled by H-A-283 (a re-pin revision of the same source keeps a mover in its pipeline and asks its build again there; only a new source moves movers), in build in the runner. Owed: pins taken from the reservation and confirmed at publish, so a release re-pins once. | H1 (the runner); H2 (the pins) |
| The pipeline runner's fix for the re-pin livelock (row 153) took two review rounds: the first found the placed-again steps' ask ids equal to the ids the runner had just dropped (the build node refuses a dropped id; the work queue dedupes the composition's; a restart found none of them), and a kept mover placed later reading the branch's held view instead of its kept revision. H-A-286 settled both (every ask id of a kept mover carries its kept revision; its entry and pins are read at that revision wherever it is placed or pin-checked), and H-A-287 aligned the rule of one validate: a pipeline has one validate run, which a kept mover's own validate ask joins. Approved at the second round and merged at 18:01 into a pipeline of its own, with its hand pack for the control-node built beside it; merges are held again from then (rows 112 and 153); the pipeline runner (`mesh-delivery-pipeline`). Owed: the runner's unplaced line for a kept mover whose revision is not yet readable. | H1 (the fix); H2 (the line) |
| While the re-pin fix (row 154) was built, the pipeline carrying the tool runner (row 151) ended at 17:45 could-not-run: its build ask on the build seat had no word from its holder within the silent bound of forty-five minutes (row 118), because the tool runner's build at that pipeline's fingerprint had been withdrawn by the re-pins' newer builds before it could answer; the tool runner then rode the newest re-pin revision's pipeline, nine of them waiting in the queue; the fixed runner, placed on the control-node by hand at about 18:05, keeps it there from now on. The builder meanwhile says the tool runner's release 0.1.55 is queued at the distribution already, while the registry holds nothing of it; the distribution's word is being read (rows 111, 151 and 153); the pipeline runner (`mesh-delivery-pipeline`), the builder and the artifact registry. | H1 |
| The re-pin fix (row 154) was placed on the control-node by hand at 18:05, and the pipeline runner started clean; but the pipeline of row 155 still held the slot: every one of its movers had left to newer pipelines and its last open step had ended could-not-run at 17:45, yet it counted as running, with nine pipelines waiting behind it. The lead cancelled it at 18:08, the second pipeline of this kind to hold the slot with nothing left to do (row 112 was the first) (rows 112, 154 and 155); the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-288 (a pipeline ends, and the next is placed, the moment nothing of it is open: at the last mover's leave, at the last open step's end in any outcome, and at the runner's start pass), in build in the runner. | H1 |
| The cause of row 156's held slot, read from the pipeline runner's code and the control-node's journal: the pipeline did judge its end at 17:45, but never wrote it; the runner computed every mover's widens inside the end's compare-and-set loop (126 movers, each asking the seat mesh-grants and cut after five seconds, about eleven minutes per try) while the pipeline's key kept changing under it, so every write was refused and the reads were made again (212 cuts between 17:45 and 18:05) until the restart, and the start pass judged no ends (rows 112 and 156); the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-289 (the reads an end needs are made once before the compare-and-set and shared by every mover and every retry; a retry reads only the key again), beside H-A-288's end pass at the start; in build in the runner. Owed: the five-second cut of the seat mesh-grants's answer itself (rows 69 and 115). | H1 |
| The tool runner's release 0.1.55 (queued at 17:47) waited more than forty minutes to publish, not lost but at the back of the builder's publish queue: a state bucket with one key per holder and version, worked one version at a time, oldest first, the whole bucket listed and read again before every send (about 1,900 subjects; the read tool timed out on it), and every start of the builder asks a publish again for every done build without a release, so old versions of many modules ride ahead of the ones a pipeline waits on; the second slow drain in the builder today (row 149 was the first) (rows 149, 152 and 155); the builder. Settled in H1 by H-A-290 (a publish a pipeline's step waits on goes before any asked again at a start; a withdrawn or taken-over build never publishes; one listing per pass and four sends at a time; a send that does not send says why; the read tool answers at any size), in build in the builder. Owed: the publish queue as a work-queue stream per holder, with tools to drop one item or put it first. | H1 (the five parts); H2 (the stream) |
| The fix of rows 156 and 157 (a pipeline with nothing open ends at once; an end's reads are made once; a journal line at every end) was approved at its first review round without findings and merged at 18:22 into a pipeline of its own; its hand pack goes onto the control-node at about 18:30, the pipeline runner's second hand pack of the evening, after the re-pin fix at 18:05. After the cancel of 18:08 the queue runs again: the next pipeline took the slot at 18:08 with 853 steps; the tool runner rides the eighth pipeline behind it, and its release of 17:47 still waits in the builder's publish queue (rows 156, 157 and 158); the pipeline runner (`mesh-delivery-pipeline`) and the runbook. | H1 |
| The fix that ends an empty pipeline (row 159) runs on the control-node since 18:26; its start pass found nothing to end, the cancelled pipeline having ended at 18:08; the evening's second pipeline runs since 18:08, with the tool runner's seven pipelines behind it. The builder's publish-queue change (row 158) was built with two gaps its developer named: at a start every old unreleased version still rode ahead of the live ones, and a live build waited for a whole start list. H-A-291 settles both (a start asks a publish again only for each module's newest reservation and retires the ones a newer reservation or release supersedes; a live enqueue makes the pass list again after its sends in flight), added before the review, together with a lock on two test fakes that failed the race detector on main (rows 158 and 159); the pipeline runner (`mesh-delivery-pipeline`) and the builder. | H1 |
| With the two fixes of the pipeline runner live, the queue ran through: three re-pin pipelines passed between 18:39 and 18:45 (each with few movers), and the tool runner's pipeline was fourth in line at 18:47. Its release's publish had reached the front of the builder's publish queue at 18:27, in the very minute the control-node's tool runner restarted for a hand pack's bundle, and failed with no responders; the builder did not retry it in eighteen minutes, so the lead asked the publish again through the builder's own tool at 18:46, and it was published at 18:46:46 (the publish-queue fix of rows 158 and 160, in review, makes the retry the builder's own). The passed pipelines reached the control-node as the evening's first asks for a person's approval: the store and the identity provider, each recorded as a module a person moves, asked on the operator's channel at 18:45 and 18:46 before their containers are made again (rows 158, 159 and 160); the pipeline runner (`mesh-delivery-pipeline`), the builder and the node-engine. | H1 |
| The large pipeline of the SDK's release (853 steps, row 159) ended failed at 18:37: the private network module's unit and integration tests failed, and every other mover passed; its movers get no pipeline by themselves (row 147's rule) and will ride the next merge that touches them. The review of the publish-queue change (rows 158 and 160) found one thing: its read tool reads the builder's own states in pages, which H-A-255 forbade for H1 because each page replays the bucket; H-A-292 allows it for a module's own tool when one page of about 768 KB holds the whole state (one replay instead of a request per key), and the review judges the same head again (rows 158, 159 and 160); the pipeline runner (`mesh-delivery-pipeline`) and the builder. Owed: a failed pipeline's movers put in a pipeline again. | H1 (the review); H2 (the re-pipelining) |
| The builder's publish-queue change (rows 158, 160 and 162) was approved at its third and last review round: the second round had found the read tool paging on past one page, and the retire rule crossing version series (a standing 0.2 would have retired a done 0.1.x build); H-A-293 settled both (a one-page read past its page answers the first page and says it is capped, with the state's size; the newest reservation and release are found per module and series), and the fix was judged in one commit. Merged at 19:00 (19:00:35, rebased first onto the fix that ends an empty pipeline, the builder's code unchanged) into a pipeline of its own, with its hand pack for the build node (the program and the tools bundle) built beside it, the first of the evening's packs to restart the build node's tool runner (rows 158, 160 and 162); the builder and the runbook. | H1 |
| A second re-pin pipeline ended failed at 18:58 on one module's tests, the teller's program and tools integration tests, every other mover passing, after row 162's private network module at 18:37. The movers of these pipelines carry only the re-pin to the SDK release with the event hub fix (row 150: pulls of twenty instead of five hundred, in-progress acks), so the kind is read before another pipeline fails on it: whether the tests depend on the old pull size or timing (a regression every module meets), or fail for their own reasons. The tool runner's pipeline is second in line from 18:58 (rows 150 and 162); mesh-sdk, the teller and the private network module. | H1 |
| A third re-pin pipeline ended failed at 19:01 on the zfs module's tools unit test; the read of all three failures (rows 162 and 164) found none of them the SDK's: the teller's test (an ask refused for want of room is asked again) is sensitive to timing and failed five of seven pipeline runs today, four of them before the SDK's change, so its fix starts now under this milestone (the teller is a module of the delivery system); the private network module's three tests read files outside their own module and failed in every pipeline today (a fix for its repository, after the proof); and the zfs module's test has a data race on the peer's id (a fix for the catalog repository, after the proof). The read also met a missing tool: no tool shows a failed step's test output, only its counts and the names of the failing tests, which belongs with the owed keeping of step outputs (row 144). The tool runner's pipeline was placed at 19:03 with 105 steps; its build, lint, unit and integration steps passed, and validate runs (rows 150, 162 and 164); the teller, the private network module, the zfs module and the pipeline runner (`mesh-delivery-pipeline`). | H1 (the teller's test); later (the two others) |
| The publish-queue change (row 163) runs on the build node since 19:03, the program and the tools bundle, the bundle's restart of the build node's tool runner silencing the tools of the mesh MCP server for about a minute (19:05 to 19:06); within three minutes the builder sent two live publishes and said both published, and its read tool answered the queue (empty) with its three standing publish items. Seen at its start: the start pass wrote one line per module no seat can build (about 6,500 lines the journal suppressed), which can hide other lines for a minute, the kind of row 101's burst (rows 158 and 163); the builder. Owed: one summary line for them. | H1 (live); H2 (the summary line) |
| The tool runner's pipeline (row 165) ended failed at 19:09 on the forge module's six integration steps, while the tool runner's own build, tests, validate and composition had passed; a pipeline's wants are written only when it passes, so the tool runner got none, and a failed pipeline's movers get no pipeline by themselves (row 147). It is the fourth re-pin pipeline of the evening sunk by one module's tests (rows 162, 164 and 165), so the lead stops iterating pipelines and fixes the kind under this milestone: the teller's test that is sensitive to timing, the private network module's tests that read files outside their inputs, and the zfs module's test race, each in its repository, while the forge module's six failures are read. The tool runner gets a pipeline of its own at once, by a one-line probe commit in its repository merged as one call (the operator's word of 2026-11-16 on probe merges), built against the latest published SDK release; the one-call merge of the SDK and the tool runner itself was shown at 12:26 (row 136), and this pipeline shows the delivery part of proof 2 (rows 136, 147 and 165); the pipeline runner (`mesh-delivery-pipeline`), the teller, the private network module, the zfs module and the forge module. | H1 |
| The forge module's six failures (row 167) are one test: its whole-seat test over a real bus, added on 2026-11-20, needs the module's npm packages installed, which the Go integration step never has (it fetches the tree without network), so it has never passed in a pipeline and sank every pipeline carrying the forge since, the one of 15:03 (row 143) included; the forge module and the Go build module (`mesh-build-go`). Settled by H-A-294 (a test that needs tooling its step lacks checks its needs first and ends NOT RUN with the reason and where it was proven, the build module's own precedent), in build in the catalog repository. The probe merge of row 167 landed at 19:13 and became a pipeline of one mover, the tool runner, being watched. The first of the four test fixes is built: the private network module's three tests read their facts from copies in the package's own test data, held equal to the originals wherever the repository is whole; the cause was the artifact's declared paths holding only the module's Go directory (rows 143, 165 and 167). Owed: the Go integration level receives a module's npm tree behind a declared need, and a read tool for a run's test output, which answers nothing through the mesh MCP server today. | H1 (the fixes); H2 (the need and the tool) |
| The tool runner's own pipeline (row 167) waited its turn behind the running ones and was placed at 19:20 with eight steps; the fixed builder (row 166) had built and published the tool runner's release 0.1.56 at 19:15, before the pipeline's turn came, the publish sent by the publish-again path within a minute of the build's end. The first test fix (row 168) went to a second review round: it cited an issue instead of its design line (A-474, a module's tests read nothing outside their module), and its drift guard compared the copies against the sibling module's tree, which that line forbids; the guard now holds only the module's own manifest, and the contracts module's facts are proven against copies without a guard (rows 166, 167 and 168); the pipeline runner (`mesh-delivery-pipeline`), the builder and the private network module. Owed: the facts' home is a test in the contracts module. | H1 |
| The tool runner's own pipeline (row 169) ended failed at 19:21 in its composition step: the compose ask met no responders on the node-engines of three nodes at once, while every node-engine answered discovery three minutes later; the lead ran the step again at 19:25 with the pipeline runner's rerun tool, and H-A-296 settles the kind (a seat ask that meets no responders is asked again with a back-off until its bound, never a verdict at once). The remaining three test fixes are built: the teller's test bed now answers the seat-holder ask the live mesh answers (the fault was the bed's, five of seven pipeline failures today), and on the way a live fault of the teller was fixed (two takers of one event since the SDK's views reader took its bare subject; H-A-295 keeps the ask-again for want of room until A-424 is built); the zfs module's test race is fixed, with a real fault of its client beside it (a peer not root whose write was cut was never told "only root"); and the forge's whole-seat test ends NOT RUN when its npm tooling is missing (H-A-294) (rows 165, 168 and 169); the holder of the seat mesh-wants (`mesh-delivery-assigner`), the pipeline runner (`mesh-delivery-pipeline`), the teller, the zfs module, the forge module and the Go build module. Owed: the no-responders wait in the assigner's composition run and in the runner's asks, and the step's own NOT RUN summary in the Go build module. | H1 (the fixes); H2 (the no-responders wait, the step summary) |
| The tool runner's own pipeline (rows 169 and 170) passed after the composition's rerun, and at 19:28:13 the holder of the seat mesh-wants wrote the tool runner's want on every node (the operator's desktop, the laptop, the home server and the control-node) at the new fingerprint and release 0.1.56, step passed-pipeline (read by the lead at 19:30 through the assigner's reasons tool); the mesh MCP server dropped for a minute at 19:29, as the tool runner on the operator's desktop restarted with the new release; the node-engines' start of the new release on each node is being read, and is row 172's. From the probe merge at 19:13 to the wants: fifteen minutes, the rerun's three minutes inside them. This is the delivery part of proof 2 (row 167); the one-call merge of the SDK and the tool runner was row 136's (rows 136, 167 and 170); the holder of the seat mesh-wants (`mesh-delivery-assigner`) and the tool runner (`node-tools`). | H1 |
| The node-engines applied the tool runner's new composition on every node within thirty-five seconds of the wants: the laptop at 19:28:36, the control-node at 19:28:42, the operator's desktop at 19:28:46 and the home server at 19:28:47, each restarting the tool runner because its bundle and its fingerprint changed, and reporting the new build healthy within twenty seconds (the build digest the node-engines report, 0a11dca2…, is the one the builder published as release 0.1.56 at 19:15); the control-node's node-engine had waited a minute for the composition ("the composer has made none yet", 19:27:43), the no-responders episode of row 170. Proof 2 is shown: the SDK and the tool runner merged in one call (row 136, 12:26), the tool runner running everywhere at the new SDK release by its pipeline (rows 167 to 172), no hand act on its path, and the day's hand packs all on the delivery system's own parts (rows 136, 167 and 171); the node-engine and the tool runner (`node-tools`). | H1 |
| The lead's statement (lead-47, on the operator's desktop, 19:31): the freeze on hand placing of the delivery system's parts is lifted (step 8). Both proofs of the runbook's step 7 are shown; every part of the delivery system now runs a build its own pipeline delivered or, where a hand pack of today still runs (the pipeline runner, the builder, the indexer, the assigner, the tool runner, the private network module and the store module, named in rows 134, 148, 160 and 166), a build whose source is merged on main and whose pipeline has passed or runs. From now a change to any part is delivered by its pipeline only, and a fault met is fixed in its repository and delivered the same way; the operator's rule of 2026-11-16 on probe merges ends with this statement. The merge of the change of the assigner and the runner (row 146) waits on the operator's word only because the permission check of the lead's session refused the dispatch, not as a decision. What H1 leaves to H2 is the owed list across rows 150 to 170; the runbook. | H1 (done) |
| Step 8's tail: the two issues the milestone ran under (one held module holds every reader's version back; a change across the SDK, the controller and the catalog repository needs three releases) were resolved at 19:33 with the proofs as the live case, and the second one's last open note (the indexer's dry run of a branch writes that branch's packages into the live packages state the trunk reads) was carried into H-A-297 as owed work. The recovery-mode rules of 2026-11-15 and 2026-11-16 on the lead's side ended with the freeze. The lead's dispatch of two reviewed merges, the change of the assigner and the runner (row 146) and the teller's test fix (row 170), was refused by the lead session's permission check, so both wait on the operator's word and are not routed through another agent; the catalog repository's two test fixes (rows 165 and 170) merge as one call; this branch's pull request is being opened for hq's check (rows 146, 170 and 173); the indexer (`mesh-delivery-indexer`) and the runbook. Owed: H-A-297 (a dry run reads and writes only its own scratch state, and leaves the trunk's packages state untouched). | H1 (done); H2 (the dry run) |
| The catalog repository's two test fixes (rows 165 and 170) merged as one call at 19:29 and became one pipeline of 36 movers: a commit touching two test files moved every module of the repository, because a module's fingerprint takes the repository's commit rather than its artifacts' declared paths; the take-in took eleven minutes, seven of them without a journal line, while the indexer waited on the forge's listing under a busy control-node (the forge at over five cores). This branch's pull request (#797) was opened at 19:35 and had no delivery record or check seven minutes later; the chain from the forge's event to the gate and the checker is being read (rows 168, 170 and 174); the indexer (`mesh-delivery-indexer`), the forge module and the gate. Owed, by H-A-298: a module's fingerprint over its artifacts' declared paths and its manifest, so a commit outside them moves nothing; and a take-in that says what it waits on after a minute, naming the part. | H1 (recorded); H2 (the fingerprint, the take-in's word) |
| The read of this branch's pull request (row 175) found the chain from the forge's event to the gate whole, and the cause elsewhere: hq is not a source repository of the gate, so an hq pull request gets no delivery and no check from the mesh, as none of the day's earlier hq pull requests did (the row of 14:22 on hq's registration); it merges on hq's own checks, run before every commit (ADR 0527); whether hq becomes a watched source with a mesh check is the operator's question (H-A-299). The same read met four live faults after the pipeline of 36 movers: the forge refuses the mesh's admin account since 19:41, which stops the forge watcher and the gate's acts on the forge (796 owed; being read: its cause, and the tool that provisions the account again); the gate's ledger records for two revisions exceed the bus's message size; the forge bridge's store of performed acts is full ("maximum bytes exceeded"); and the deliveries read tool cannot answer per repository (rows 150, 166 and 175); the forge module, the gate (`mesh-delivery-gate`) and the forge bridge. Owed, by H-A-299: one ledger key per module and revision; every store with a cap it prunes toward, a read of its fill and a limits tool; and a read tool that filters before it sizes. | H1 (recorded); H2 (the three); open (the forge account) |
| The forge's refusal of the mesh's admin account (row 176) was the store's absence: the store's container was replaced between 19:41:04 and 19:41:32 (a move the operator approved on their channel), the forge answered 401 for that minute and said the account was refused, and it recovered by itself at 19:42:11 with a fresh token; the gate's views owed on the catalog repository's two merged pull requests failed in that minute and ended could-not-be-performed, with nothing performing them again; the forge module and the gate (`mesh-delivery-gate`). The record's own pull request (rows 175 and 176) was refused by the mesh's merge verb ("its base main is no watched branch"); the day's earlier hq merges went through the forge's own interface, and the lead's session refused to dispatch that, as it refused the two code merges of row 174, so the three wait on the operator. The private network module's pipeline (the fix of rows 168 and 169) passed at 19:46, the first pipeline of the day with that module's tests green (rows 169, 174 and 176). Owed, by H-A-300: an act failing while a part is away stays owed and is tried again with a back-off; the forge module names the cause it can read; one token mint at a time; a tool that performs every owed act of one record again. Owed too: hq registered as a watched source, so the mesh merges and checks it (H-A-299's question). | H1 (recorded); H2 (the owed acts, hq as a source) |
| One more pipeline fell to the store's half-minute absence (row 177): the re-pin pipeline that followed the tool runner's ended failed at 19:43, with many build steps failed and lint steps could-not-run, because the builder's fetch of each source met the forge's 401 in that minute and the builder read the refusal as the build's verdict; the builder. Meanwhile the pipeline of 856 steps holds the slot since 19:46, and the catalog repository's pipeline of 36 movers waits behind it (rows 170, 175 and 177). Owed, by H-A-301, the same kind as H-A-296 and H-A-300: a step whose fetch meets the forge away is asked again with a back-off until its bound, and a fetch failure is said apart from a build failure. | H2 (owed) |
| Forty minutes after proof 2 (row 172) the home server's tool runner dropped out of discovery: its node-engine restarts it every 20 to 50 seconds, because the composition key for the tool runner at its new fingerprint alternates between two digests written in turn by two composition runs, one resource (the runtime process) differing; the mesh MCP server on the operator's desktop dropped at 20:16 too, and the control-node's tool runner missed a round of discovery, so the other machines' keys are being read; the stale writer is being found and dropped with the assigner's own tool, as the recovery of the moment; the holder of the seat mesh-wants (`mesh-delivery-assigner`), the node-engine and the tool runner (`node-tools`). The same read found the pipeline of 856 steps (row 178) not stalled: its validate run took 25 minutes, and its last test steps passed at 20:15; and a tool fault: the build seats' steps read tool answered empty on every node while steps ran (rows 172, 176 and 178). Owed, by H-A-302: a composition key written by the newest run only; a run whose pipeline ended writes nothing more; the node-engine applies only a newer write and names it; and the steps read tool answers the steps state. | open (the flapping); H2 (the rule, the tool) |
| Row 179's cause was not a stale run: no second composition run writes the key; on three of four machines the node-engine composes the tool runner's self-want itself, and while the grants part does not answer ("withheld unknown") every compose differs in the runtime process, so the node-engine writes a new revision and restarts the tool runner at each compose (every 20 to 50 seconds on the home server, slower on the operator's desktop and the control-node; the laptop, whose compose got the grants answer, is steady); the control-node's tool runner serves the grants answer, which closes the loop; the node-engine and the tool runner (`node-tools`). Settled by H-A-303, which amends H-A-302 (a withheld part keeps the running composition's part and writes no revision; the node-engine applies only a difference in a part it could read; the withheld part is said once), in build in the node-engine; the recovery of the moment, a held put of the tool runner on the home server through the assigner's tool, is being tried. Beside this, the operator decided at 20:24 (the relaying session wrote 20:35), through the session on their desktop, that the packet filter module gets standing control verbs on the seat node-packet-filter (allow, disallow and allowed, with an optional expiry) beside the ports derived from declarations, so design 08 §4 and the seat's verbs change (H-A-304; the decision record amending ADR 0170 is proposed; its first use is tcp 8000 on the LAN interfaces of the operator's desktop); its build runs beside H1's tail (rows 172, 176 and 179). | open (the flapping); other (the packet filter's verbs) |
| The mechanism of row 180's loop, read in the node-engine's code and the home server's journal: the self-compose never asks the seat mesh-grants; what goes unanswered is a module's entry or its registry versions, and a module held for that is composed as a stand-in whose slice of the tool runner's runtime process is rebuilt from what runs without its fingerprint and files words, so the process's module list and words differ from pass to pass and the node-engine restarts the tool runner each time ("restarted because its unit's Environment MESH_TOOL_MODULES changed"); the node-engine and the tool runner (`node-tools`). Settled by H-A-306, which amends H-A-303 (a withheld part is every input a compose asks and does not get; a held module's slice is copied verbatim from the running process; a withheld part is said once), in build in the node-engine. The recovery of the moment works: a held put of the tool runner on the home server through the assigner's tool at 20:22 stopped the loop (one restart at 20:26, then steady); the same hold goes on the operator's desktop and the control-node, to be released when the node-engine's fix is delivered (rows 172, 179 and 180). Owed: a read of composed values by resource. | open (the fix in build); H2 (the read) |
| The pipeline of 856 steps of the SDK's re-pin (rows 178 and 179) ended passed at 20:15, twenty-nine minutes after its placing, its validate run alone twenty-five of them; the catalog repository's pipeline of 36 movers (row 175) was placed in the same second with eleven steps, and runs. The packet filter's build (row 180) met two facts the lead's map had wrong and one design question: the seat's definition lives in the networking repository's contracts module, not in the contracts repository, so the group is three repositories (the networking repository, the catalog repository and the node-engine's); a definition that carries an event must be whole (every verb's answer form, the event's family, generated packages); and what the node-engine does when the holder's allowed verb does not answer as it composes the filter, settled by H-A-307 (it refuses to compose the filter and keeps the loaded one, said once; allowances only on a converged node's own table) (rows 175, 178 and 180); the pipeline runner (`mesh-delivery-pipeline`), the packet filter module and the node-engine. | other (the packet filter); H1 (recorded) |
| The held puts (row 181) went onto the operator's desktop at 20:28 and the control-node at 20:30 too, but they only slow the loop: the node-engines still compose the tool runner themselves and restart it every four to five minutes instead of every half minute; the holds stay until the node-engine's fix (H-A-303 and H-A-306, in build) is delivered, and the mesh MCP server drops for a minute at each restart of the tool runner on the operator's desktop. Two more faults were met meanwhile: the pipeline runner's show verb refuses the record it reads ("unknown field kept-revisions"), because the tool runner's new release carries the runner's tools at a release older than the runner's record form (H-A-309); and the catalog repository's pipeline of 36 movers had eleven steps placed at 20:15, then "written meanwhile, so nothing is placed in it now", with no line since 20:17, being read. The packet filter's work stands: ADR 0683 reserved and in its third proposed version; the design amendments to 08 §4, 33 and the glossary (the word "allowance") committed and pushed on their own branch, in review by two architectural domains; the lead answers H-A-308 (an allowance's identity per interface, its expiry by the holder, the verbs' answers) and H-A-310 (the verbs required from the start in one group; ADR 0246 ended for the seats of contracts modules) (rows 180, 181 and 182); the node-engine, the tool runner (`node-tools`), the pipeline runner (`mesh-delivery-pipeline`) and the packet filter module. Owed: a tool decodes another part's record tolerantly (H-A-309). | open (the loop); other (the packet filter); H2 (the tolerant decoding) |
| The catalog repository's pipeline of 36 movers (row 183) was stuck: its placing, cut at 20:15:59 by a concurrent write of the pipeline's record, was never done again; the last test's late progress was dropped without placing what its end unlocked; and the pipeline runner's health said healthy through seventeen minutes with nothing open; a restart of the runner at 20:35 placed 392 steps in twenty seconds from its start pass. It is the second recovery by restart of this kind (row 156 the first), so H-A-311 settles the kind in the runner, in build: a cut placing is done again at once from the record as read again; a late step end still places what it unlocks; a running pipeline with nothing open and nothing placed for five minutes is unhealthy, and said. The packet filter's build moved: the seat's definition, made whole (six verbs, the event, the state, generated Go and TypeScript packages), is committed in the networking repository, and the holder's build follows (rows 156, 182 and 183); the pipeline runner (`mesh-delivery-pipeline`) and the packet filter module. | H1's tail (the runner); other (the packet filter) |
| The node-engine's fix of the restart loop (rows 180 and 181) is built and in review: a held module's slice of the tool runner's process is copied verbatim from what runs, so a holding pass has a digest equal to what runs and writes no revision; the withheld part is said once, naming the holder asked; the developer read the restart cause in the home server's journal ("its unit's Environment MESH_TOOL_MODULES changed") and found a failure of the race detector that predates the change. The packet filter's design amendments were read by two architectural domains (seams and tools: eight points; security and upgrade: seven) and settled in H-A-314 and H-A-315; among them: the allowances state takes the template's option of one bucket per machine (a shared bucket would have opened a port on every node); the verbs' classes and the node-engine's grants; a caller not proven is refused; an allowance with an expiry is rendered as a set element with a timeout, so the kernel closes it while the holder is away; a port that a derived rule admits only from the private network is refused unless a source is given; the loaded mark is compared on the allowance's time; and a running holder is not withdrawn when its seat's definition grows. H-A-316 adds a read verb `converged` to the node-engine's seat, so the holder knows its node is adopted; H-A-313 settles the stalled pipeline's journal line (row 184) as the tools program's. The packet filter's seat definition and holder are committed; the node-engine's part and the reviews' additions are in build by two developers (rows 180, 183 and 184); the node-engine, the packet filter module and the pipeline runner (`mesh-delivery-pipeline`). | open (the loop's fix in review); other (the packet filter); H1's tail (the runner) |
| The packet filter's design amendments (row 185) now carry every point of the two reviews by architectural domain, and were pushed on their branch at 20:43 (hq's branch design/firewall-control-verbs, head 8fc4f09d): design 08 §4 with its part "control verbs" (eight lines: the node-engine as the one renderer, asking the holder's allowed verb within its compose-ask bound; a refusal keeping the loaded filter; converged nodes only; each expiring allowance its own one-element set with a timeout; the event heard; the acceptance test proving the drop before the allowance); design 33's part (fourteen lines: the six verbs with their classes and refusals, the event and its family, the state one bucket per machine, the verb `converged` on the node-engine's seat, the settings, the holder's start removing expired allowances); and the glossary word "allowance" (a port of the packet filter opened by the operator through the seat). The adoption text of design 08 moved whole into its own delivered part, to keep the main file under its size bound. The decision record ADR 0683 is in its fifth proposed version, with the same points (rows 180, 183 and 185); the packet filter module and the node-engine. | other (the packet filter) |
| The node-engine's fix of the restart loop (row 185) was approved at its first review round at 20:45 (the reviewer took each part out in a copy and saw the tests fail; live, the home server's composition still alternated between two digests, which no tool can read word by word, H-A-306 (4) owed); the lead session's permission check refused dispatching its merge, as it refused the three of rows 174 and 177, so four reviewed merges now wait on the operator's word: the change of the assigner and the runner, the teller's test fix, this branch's pull request, and the node-engine's fix; until the last is delivered, the held puts of row 183 stay. The pipeline runner's fix of the cut placing (row 184) is built and in review: a placing refused because the record changed is done again from the record as read again; a late step end places what it unlocks; the health names a running pipeline five minutes without an open step, written once to the tools program's journal. The packet filter's build met two forms the lead's lines had wrong, settled in H-A-317: the state template's option per machine is one bucket whose keys carry the node, so the state's keys begin with the node while the allowance's own key stays as designed; and a holder does not list its seat's event in its manifest's emits, the claim says it (rows 174, 177 and 185); the node-engine, the pipeline runner (`mesh-delivery-pipeline`) and the packet filter module. | open (the loop); H1's tail (the runner); other (the packet filter) |
| The packet filter's decision record (ADR 0683, "The packet filter's control verbs beside the ports derived from declarations") was approved by the knowledge base's own review at its eighth version at 20:46: fourteen clauses carrying H-A-304 to H-A-316 (the derived ports stay automatic; the six verbs; allow and its refusals; one allowance per protocol, port and interface; disallow; allowed and rules; the state per machine; one renderer, with the event; removed at its until; an unanswered read keeps the loaded filter; converged nodes only, with the read verb `converged`; the verbs required from the start; two settings; how it is checked), changing ADR 0170 and ending ADR 0246's optional-first for the seats of contracts modules. It is marked needs-operator and waits on the operator's Approve on their channel (the ask expires on 2026-11-22 at 19:36 UTC); nothing of it is in force until then. Two more forms met in the build after the record's last version are H-A-317 (the state's keys carry the node; the claim says the event) and H-A-318 (allowed asks converged again when it holds no answer); they are facts of the templates, and enter the record as a progressive insight if its review asks (rows 180, 186 and 187); the packet filter module and the knowledge base. | other (the packet filter) |
| The catalog repository's pipeline of 36 movers (row 184) was not stalled after the pipeline runner's restart; it ran unseen: the builder answered its 36 build asks within seconds (every key already built), and the check asks ran on the Go build module of the operator's desktop at about six a minute, with no journal line from the runner for a step's end nor from the builder for an answered ask, so the lead read a stall where the bus showed the work; by 20:48 its builds, lints, units and validates had passed and three integration steps had failed (the Node build module's, its setup over its thirty-second bound, and the recovery module's whole test), so the pipeline will end failed on those, the kind of rows 162 to 165 again. The read also found the asks of the seat mesh-builds on a work-queue stream no consumer takes (1,524 kept), the home server's Go build module taking no check asks, and the unanswered bound not ending asks left untaken for thirteen minutes. H-A-319 settled the packet filter's refusal of a source-bound port as the chain shows it (a port accepted only with a source match) (rows 165, 184 and 188); the pipeline runner (`mesh-delivery-pipeline`), the builder, the Go build module (`mesh-build-go`) and the packet filter module. Owed, by H-A-320: a journal line per step end and per answered ask; the mesh-builds asks consumed, or the stream bounded; every build seat takes check asks; the unanswered bound ends an ask left untaken. Owed too, by H-A-319: the node-engine's render marks each derived rule with its scope. | H1's tail (recorded); H2 (the owed); other (the packet filter) |
| The pipeline runner's fix of the cut placing (rows 184 and 187) was approved at its second review round at 20:54: the first round had found the stalled rule reading the pipelines through the seat's strict decode, which refuses the runner's own property `kept-revisions` (the live cause of the show verb's refusal, row 183), and counting a required waiting step (an approval, a pin-held step) as nothing open; both are fixed, the property dropped before the seat's decode, so show, stands and the health read every record again; the five-minute bound stays a value named in the code with the rule it comes from (H-A-322). It joins the merges waiting on the operator's word, now five (rows 174, 177 and 187). Meanwhile the lead resumed the home server's Go build module, found paused with a capacity of one while the operator's desktop took every check ask (row 189), and the laptop's, whose Go build module a passed pipeline had delivered at 18:20 (main.131, release 0.1.125, read by a watcher); check asks now run on three nodes. The packet filter's design parts are whole at 41005dfc, with every build form through H-A-321 (rows 183, 187 and 189); the pipeline runner (`mesh-delivery-pipeline`), the Go build module (`mesh-build-go`) and the packet filter module. Owed, by H-A-322: a settings form a tools program can read. | H1's tail (the runner); other (the packet filter) |
| The packet filter's build (rows 185 to 190) reached its third repository at 20:56: the node-engine seat's whole definition in the contracts repository gained the read verb `converged` (the node's convergence state: adopted or converged, since when, and the found firewall when adopted) and the composition answer's field `withheld-parts` (which part a compose kept because its read did not answer, and why), with the fixtures and the generated Go and TypeScript packages, the seat generator's check clean; the holder's build takes the verb from that package, and the node-engine's serving of it follows in the fourth repository. The group's heads so far: the networking repository's seat definition (being amended for the reviews' forms), the catalog repository's holder (the same), and the contracts repository's seat of the node-engine (rows 185, 186 and 190); the packet filter module and the node-engine. | other (the packet filter) |
| The packet filter's fourth part is built at 21:08: the node-engine renders one rule per allowance after the derived ports, with the comment carrying the allowance's key and time, a timed allowance as a one-element set with a timeout, and, with no allowance, the filter file byte for byte as today; its compose asks the holder's allowed verb within a new setting, keeps the filter file as it runs when the verb does not answer, without holding the holder's module, says the withheld part once, hears the event on its own node's subject, and serves the verb `converged` from its record. The developer read four facts the lead's lines had wrong or left open, three settled by H-A-324: an allowance with no interface would have opened a node's outward link (a hub's internet-facing one), so "no interface" now excludes outward links too, and an outward link is opened only when named; a timed allowance's render again reloads the filter and arms the remaining time again, accepted; the converged answer's since is optional for older records; and the allowances go to the renderer rather than to the reader of the derived rules, since the adoption's openings read the latter. The group's heads: the networking repository 32f0ade8, the catalog repository 09d57583, the contracts repository efcef83c, the node-engine 9c357b6f; H-A-324's change of the render and the validator's verdicts on the node-engine's manifest are the last subtask before the group's one review (rows 186, 190 and 191); the node-engine and the packet filter module. | other (the packet filter) |
| The catalog repository's pipeline of 36 movers (rows 184 and 189) stood still a second time: every test had ended by 20:53 (the zfs and forge fixes among them, passed), yet two movers waited "for mesh-grants' packages before their build", though those packages had been published at 20:00, before the wait was written, so no publish event ever came for them; the pipeline runner's health said healthy; the lead restarted the runner at 21:15, and its start pass placed them, the third restart of this kind tonight. H-A-326 settles it on the runner's open branch (a wait on a package is a read first and an event second; a pipeline whose movers only wait on packages counts as nothing open for the stalled rule; the journal says which way a wait resolved), so the fifth merge waiting on the operator (row 190) moves to a new head after its review. The packet filter's design gained H-A-325: the holder reads no shape of the loaded table to tell an outward link; the converged answer carries the node's links (the tunnel's name, the list of outward links) as the node-engine classifies them for its render, and a kept allowance names the outward link it opens; the design parts are at 3a969c6b (rows 184, 189 and 192); the pipeline runner (`mesh-delivery-pipeline`), the node-engine and the packet filter module. | H1's tail (the runner); other (the packet filter) |
| The restart of row 193 ended the catalog repository's pipeline at 21:15:30 through the pipeline runner's start pass (row 159's rule that ends an empty pipeline, at work): it ended failed on the Node build module's integration tests, whose setup took forty seconds against a thirty-second bound while three nodes' checks ran, and on the recovery module's whole test; the zfs and forge test fixes passed in it, so their kinds are closed, while the laptop's Go build module stays at its earlier release, since a failed pipeline writes no wants; the next pipeline was placed at 21:15:42 (rows 159, 165 and 193); the pipeline runner (`mesh-delivery-pipeline`), the Node build module and the recovery module. Owed, by H-A-327, of H-A-294's kind: a setup bound read from the step's own bound; a whole-module test that needs the bus's time under load says NOT RUN rather than failing; both fixed in their modules before the next release that carries them. | H1's tail (recorded); H2 (the two tests) |
| H-A-326's read (row 193) met the fact that the pipeline runner's record knows only the publishes it heard, and a package published before a pipeline existed is in no record of it (the two movers' packages had been published by an earlier pipeline at 20:00); the builder owns publishes, so H-A-328 gives the seat mesh-builds a read verb `published` (module, artifact and fingerprint; answering published, version, digest and when), served by the builder from its reservations and the registries' record, which the runner asks once when it writes a mover's wait on a package, the publish event staying the second path. The seat mesh-builds is defined in the delivery repository's own contracts module (not in the contracts repository, as the lead's map had it; H-A-328 is corrected so), so the runner's open branch stays one branch in one repository, holding the seat's definition, the builder's serving and the runner's asking, and the fifth merge waiting on the operator (row 190) keeps one head, new after its review (rows 190, 193 and 194); the pipeline runner (`mesh-delivery-pipeline`) and the builder. | H1's tail (the runner and the builder) |
| The packet filter's group was complete at 21:23, an hour after the operator's decision (rows 180 to 195): the networking repository's seat definition, made whole (the six verbs, the event, the state per machine, a kept allowance naming its outward link, rules listing what is loaded but not kept); the catalog repository's holder (27 tests, type-checked against the generated packages, the catalog's 33 checks green, the manifest validator accepting its manifest); the contracts repository's seat of the node-engine (the read verb `converged` with the node's state and links, the composition answer's withheld parts); and the node-engine (the compose asking allowed within its bound, the filter kept as it runs when unanswered, the render with timed sets and the default excluding outward links, the event heard, `converged` served from the render's own sources); the one review of the four heads began at 21:24. One fact for the pipeline's check: the manifest validator, run against the trunk's seat files, refuses the node-engine's manifest in both cases for a cause that predates the change (two registry seats' versions verbs absent from those files), which the live seat list is believed to carry; the pipeline's own validate decides (rows 186, 192 and 195); the packet filter module and the node-engine. | other (the packet filter) |
| The pipeline runner's open branch (rows 190, 193 and 195) gained H-A-326 and H-A-328 at 21:25 in three commits: a step held waiting on a package's publish counts as nothing open for the stalled rule; the seat mesh-builds gains the read verb `published` (module, artifact and fingerprint; answering published, version and digest), served by the builder from a reservation of that fingerprint whose artifact is marked published, or from a kept release of it; and the runner, when it writes a mover's wait on a package, asks it once per package and fingerprint and places the mover at once when the answer is published, the journal saying "placed from the published record" apart from an event; a package published before the pipeline existed thus no longer holds a pipeline until a restart. Two manifests and the seat's definition changed, so the manifest validator runs before the branch's third review; the approved head of row 190 is superseded by this one (rows 190, 193 and 195); the pipeline runner (`mesh-delivery-pipeline`) and the builder. Owed: the answer's time, never filled because the builder keeps no publish time, with that record. | H1's tail (the runner and the builder) |
| The manifest validator's run on the pipeline runner's branch (row 197) at 21:28 found the change adding no problem: with the branch's seat definition, the change case's verdicts equal the trunk case's for every one of 157 manifests. But the builder's and the runner's manifests are refused in both cases, on fifteen and three lines naming verbs of the registry and build seats that the validator program does not see in the repositories' trunk seat files (they declare acts and accepts), lines the live validate of the same modules passed today; every developer and reviewer runs the validator this way, because the live answer of the seat list is too large to read into a session. The branch's third and last review began at 21:30 (rows 190, 196 and 197); the pipeline runner (`mesh-delivery-pipeline`), the builder and the indexer's manifest validator. Owed, by H-A-329: the seat mesh-catalog answers the seat list as one object a validator run takes; and the validate step counts only the problems new against its before case for a touched module (the reader found it counts every problem). | H1's tail (the runner); H2 (the validator's reads) |
| The two reviews came back at 21:34 and 21:35, neither approving. The packet filter's group (row 196): five findings, one a real fault (the holder accepted an expiry without seconds that the node-engine's time reader refuses, so every later compose would have withheld the filter), the others form (the verbs served before the holder's start had said started; the holder copying the seat's names instead of importing the generated package, the copies already drifted; the seat definition's description of the default set stale; the stored copy of the node's grant lacking the event's subscription), all in one developer's hands; the holder's ten-second bound on its converged ask stays a value (H-A-330). The pipeline runner's branch (row 197), third round: one finding, the published answer never carrying its time, and never the digest for a release, which the builder did not keep; H-A-331 settles it (the publish time kept on the mark from now on, a release keeping its digest, both absent for older records and said so; a withdrawn number never answered published). The lead takes a fourth look at that one commit rather than a fourth round: the rule of three rounds bent for a detail of form, and said here (rows 196, 197 and 198); the packet filter module, the node-engine, the pipeline runner (`mesh-delivery-pipeline`) and the builder. | other (the packet filter); H1's tail (the runner) |
File diff suppressed because it is too large Load Diff
@@ -1,347 +0,0 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H
updated: 2026-11-20
decisions:
- "ADR 0499"
- "ADR 0573"
- "ADR 0682"
---
# 47, milestone H — the pin rule: its specification and its gaps
The rule by which a catalog entry pins the mesh packages a module's build resolves, written whole from the lead's
answers H-A-147, 151, 154, 155, 156, 157, 161, 162, 165, 167, 168, 170, 172, 173, 183, 184, 185, 186, 188, 192, 194,
198, 201, 202, 203, 204, 205 and 206 ([H-lead-answers.md](H-lead-answers.md)), G §370
([G-7-answers.md](G-7-answers.md)), ADR 0499 §1 to §4 and ADR 0573 §2 and §4 (the knowledge base), then held against
the code as it stands after the evening's three fix branches.
A word first. The glossary's **pin** is a person's choice of provider for a consumer (Provisioning). This file, as the
lead's answers do, uses "pin" for the version a catalog entry names for a mesh package its module's build resolves.
That is a second sense the glossary does not hold; the proposed word is **package pin** (a catalog entry's version of
one mesh package its module's build resolves, its key the package's Go module path), to be added in its own pull
request. Until then "pin" below means the package pin, and "revision pin" means a record keeping a catalog revision
(the indexer's state `pins`).
## The code read
| Part | Repository | Read at |
|---|---|---|
| The indexer (seat `mesh-catalog`) | mesh-delivery, module mesh-delivery-indexer | main `b9cc9747` plus branch `fix/47-H1-indexer-repin` at `94202fb6` (commits `0418a2b9`, `94202fb6`); the tool commit said to be in progress was not in the branch's worktree (clean at `94202fb6`) |
| The pipeline runner (seat `mesh-pipeline-runner`) | mesh-delivery, module mesh-delivery-pipeline | branch `fix/47-H1-runner-step-pins` at `e3fed775` (commits `a926a40e`, `e3fed775`) over main `b9cc9747` |
| The builder (seat `mesh-builds`) | mesh-delivery, module mesh-delivery-builder | branch `fix/47-H1-builder-revision-picture` at `0fcc614e` (one commit over main; its worktree clean) |
| The Go build module (seat `node-build-go`) | mesh-catalog, module mesh-build-go | main `34a884ff` |
| The delivery SDK's build step and step runner | mesh-delivery, module mesh-delivery-sdk, packages `buildstep`, `steprun` | main `b9cc9747` |
Every fact below names its file and function, read with `git show` at those heads; no line numbers (they move).
## 1. The specification
### What an entry pins
- **S1** An entry's `packages` names every mesh package its module's Go build requires, read from the `require` lines of
the go.mod files at the take-in, at any version, the zero version and `// indirect` included, with no build needed
(H-A-157, H-A-201).
- **S2** The set is transitive across the module graph the go.mod files give, not only the module's direct requirements
(H-A-201).
- **S3** A requirement of the module's own repository is never pinned: it is built from the tree (H-A-198, H-A-201,
H-A-202), whether or not that package is also published.
- **S4** A pin's key is the package's Go module path as go.mod requires it, a nested module's whole path included
(`<repository>/modules/<m>/go/clients/<c>`), never a root path or a module's name (H-A-183: "the package path").
- **S5** A pin's version is the newest version the registry seat published for that package path, as the registry's
published events name it (path and version); never a module's release number, never a commit (H-A-161, H-A-183;
G §370: a Go package's version is its tag).
- **S6** The pin stays within the series the module accepts: the one its manifest names in `packages`, the default
where it names none, whether or not a series value holds contents; a publish in another series pins nothing and moves
nothing (H-A-184, H-A-185). A package artifact's series is its module's version series (H-A-188).
- **S7** The pin is always the newest release in that series; an older version never stands over a newer release
(H-A-167).
- **S8** A requirement of another repository with no published version in its series is named with an empty version,
never left out (H-A-161, H-A-204).
- **S9** A pin is written `vMAJOR.MINOR.PATCH` everywhere it is carried (G §370's tag form; the step contract's
semantic-version form), and only an empty version stands for "none yet".
- **S10** A Go package path another module imports is a declared package artifact of its module; the catalog's check
refuses a manifest whose Go module imports a mesh package path no module declares (H-A-186).
### When an entry is computed and pinned again
- **S11** The entry and its pins are computed at the take-in of every watched branch, for every module the take-in
holds (H-A-157; H §743).
- **S12** A package's publish pins again every kept entry, of any repository and whether or not its module changed,
that names the path with no version or an older one in its accepted series (H-A-165, H-A-204).
- **S13** The pins move on the event, never waiting for a merge or a hand act (H-A-165).
- **S14** A pin that moves moves the importer's fingerprint; the importer becomes a mover, and the builder builds a new
key against the release (H-A-167; ADR 0573 §3).
- **S15** A failed re-pin is not acknowledged, so the publish is delivered again (H-A-167).
- **S16** The indexer answers one entry's `packages` and paths at a revision through a tool, without the whole revision
(H-A-204; tools-are-how-a-module-is-spoken-to).
### What the fingerprint takes in
- **S17** Every form's fingerprint (the version line's and the import form's) takes the module's pins, sorted; a
fingerprint with no pin stays as it was (H-A-167, H-A-172; ADR 0573 §2).
- **S18** The objects of every same-repository module directory the build derives from the go.mod files enter the tree
input, a line per directory, for every form, without being written into the entry; the entry's `paths` keep the
manifest's form (H-A-199 as H-A-202 amends it).
- **S19** A module whose every artifact names its paths takes its tree input from the manifest and those paths (ADR
0499 §2).
- **S20** A build's reported imports refine the go.mod's set and never replace it with an empty one while go.mod names
a mesh package (H-A-157).
### Who carries the pins into which ask
- **S21** The builder takes a build's pins from the catalog entry alone and never computes one (H-A-192).
- **S22** The builder's own build ask of a lane (the trunk build it puts on the build seat's stream) carries the same
pins (ADR 0573 §2: the build writes those versions into its workspace; H-A-192).
- **S23** The runner puts the entry's pins into every step ask's fetch (lint, unit, integration), the same pins the
builder gives the build (H-A-203).
- **S24** A run on request's build step ask names no source revision (H-A-162).
### What waits
- **S25** A build step ask names its branch and source revision; when the builder's picture does not hold that revision
yet, the ask waits for the picture to take it in, woken by the state's change events and by each revision the view
takes in, up to `revision-wait-minutes` (1 to 60, default 2), then fails loud naming the revision and the branch; a
build with no version is never made (H-A-155, H-A-156, H-A-162).
- **S26** The builder's picture holds every kept revision: a revision below the newest it heard is read by number
through the catalog seat's `revision`; only one above the newest is waited for (H-A-205).
- **S27** A build whose entry names a package with an empty pin first asks the package registry seat's `versions` once
for that path and takes the newest in the accepted series; else it waits for the registry's published of that path
and series, up to `package-wait-minutes` (1 to 120, default 10), and pins the version that event carries; past the
bound it fails "package <path> has no released version" (H-A-165, H-A-192, H-A-194).
- **S28** The runner asks a Go artifact's lint, unit and integration steps only when every pin of its entry has a
version; until then the steps stand as "waits on the publish of <path>", and end as the build ends when the bound
passes; the publish pins the entry again and moves the mover to its new fingerprint, whose pipeline runs them
(H-A-206).
### What refuses
- **S29** The Go build module refuses, loud, a requirement of another repository the ask gives no pin for (H-A-192).
- **S30** It never takes another path's version, a sibling's version or the latest for it (H-A-192, H-A-201).
- **S31** It builds a same-repository requirement from the fetched tree, transitively through those modules' own
go.mod files, and keeps those directories in the narrowed tree (H-A-198, H-A-202; ADR 0499 §4: a build sees only its
named paths).
- **S32** A version a repository's go.mod names is read as the oldest it accepts, and nothing more; nobody fixes a
version by hand (ADR 0573 §2).
### What keeps the revision an entry lives in
- **S33** The take-in pins the branch's newest kept revision for the same pipeline record as its own, and writes that
revision's number as the field `base` on the revision it writes, absent on a branch's first take-in; both are freed
with the pipeline (H-A-147, H-A-151, H-A-154).
- **S34** A passed pipeline pins, under `release.<branch>.<module>`, the revision of each mover that released a version;
a newer pipeline's `pipeline-wanted` with outcome running frees it from the revisions below only where the newer
revision holds that module's release record (H-A-168, H-A-170, H-A-173).
### From the records, not judged here
- **S35** A delivery group's check builds its members against the group's own heads (ADR 0573 §4). Milestone H's runs
on request replace the earlier model's group check; whether §4 still asks anything of the pin rule is a question for
the lead, not this table.
## 2. The gap table
Sizes: S one function (under an hour), M one module's part (a day), L the part's shape (more than a day).
| Line | Status | Where | What the code does instead | Size |
|---|---|---|---|---|
| S1 | built | mesh-delivery-indexer: `cmd/.../named.go` (the go.mod read, `fingerprint.MeshRequiresOf`); `internal/index/package_trees.go` `otherRequired`; `internal/index/versions.go` `releasedPins` (branch indexer-repin, its `required` argument) | | |
| S2 | built otherwise | `internal/index/package_trees.go` `sameRepositoryRequired`, `otherRequired` | The reading follows only same-repository modules' go.mod files; a pinned package's own requirements (another repository's go.mod) are never read, so a transitive requirement is pinned only where the module's own go.mod lists it as `// indirect` (a tidied go.mod). | M |
| S3 | built | `releasedPins` (skips `trunk.SameRepository`); `fingerprint.OtherPackages` | The indexer never pins a same-repository package, published or not. The Go build module's side is S31. | |
| S4 | built | indexer `HearVersion` (`GoModule` from the registry's published `Module`), `releasedPins` (`s.GoModule == p`); builder `PackagePublished` (keyed by the published `Name`); mesh-build-go `takeZeroRequirements` (`asked[p.module]`) | The key is the full Go module path on every side. Live: the registry holds `.../modules/mesh-grants/busgrants` at 0.1.48 under its nested path (the indexer's `indexer_package_users`). | |
| S5 | built | `releasedPins` (branch); `fingerprint.WithPins` | The entry's pins are registry versions. The fingerprint's version line still takes commits (leftover L1). | |
| S6 | built | `releasedPins` (`m.AcceptedSeries(s.Name)`); builder `awaitPublished` (`man.AcceptedSeries(p)`) | The rule that a package artifact's series is its module's version series (H-A-188) lives in the catalog's check, outside these modules: not judged. | |
| S7 | built | `releasedPins` (the highest in the series) | | |
| S8 | built | `releasedPins` with `required` (branch indexer-repin `0418a2b9`) | The empty version is refused by a run on request's candidate: `internal/index/candidate_values.go` `checkCandidateModule` runs `sdkstep.PackageVersions.Check`, which accepts only a commit or a semantic version, on `runcandidates.go`'s values copied from the module's `Packages`. A run of a module with a package not yet published fails. | S |
| S9 | built | indexer `releasedPins` (`"v"+`), series kept without it (`HearVersion`); builder `publishedPin` (`"v"+`), `PackagePublished` (trims it); runner `stepAsk` (copies); sdk `buildstep` `PackageVersions.Check` (needs `v`); mesh-build-go `takeVersion` (`path@v…`) | One form throughout. The empty version is the one exception S8 names. | |
| S10 | not judged | the catalog's check (mesh-catalog's manifest check), not one of the modules held here | | |
| S11 | built otherwise | indexer `takeInSource` (`takein_source.go`), `recomputeLocked` (`toolchains.go`) | On the first watched branch every module is computed. On another branch the take-in recomputes only the moved repositories' modules and those whose pins name a package of a moved repository; every other entry is carried from that branch's newest revision with the pins it had. | M |
| S12 | built otherwise | `cmd/.../series.go` `heardVersion` (a registry's published runs `Recompute` of every module); `versions.go` `releaseVersion` calls `repin`; `toolchains.go` `Repin` (branch: by pins and by kept requirements) | Two paths move the pins, both in the first watched branch's view only (`ix.Modules`). A kept catalog revision is never rewritten, and another branch's entries are not pinned again. | M |
| S13 | built otherwise | as S12; `catalog_revisions.go` `keepBranchEntries` is called only from `takeInSource` | The view moves on the event, but an entry anyone reads (the builder, the runner, the node-engine through the revision) changes only when the next take-in of that branch writes a revision, which only a merge on that branch makes. | L |
| S14 | missing | `internal/index/movers.go` `moversOf` | A mover is a module of a moved repository whose fingerprint changed, or a module whose pins name a package a mover publishes. A module whose fingerprint moved by a re-pin is neither, so no pipeline builds or tests it. The builder's picture builds the new fingerprint on its own once a later revision carries it (leftover L5), outside any pipeline, with no test step and no want. | L |
| S15 | contradicts (one of two paths) | `cmd/.../series.go` `heardVersion` | The version-released path returns the re-pin's error, so the package-published is not acknowledged (built). The registry-published path logs a failed `Recompute` and acknowledges the event, so that re-pin is lost until the next publish. | S |
| S16 | missing | indexer tools (branch indexer-repin holds none) | The seat verb `mesh-catalog.entry` answers one whole entry by fingerprint, not at a revision. The tool H-A-204 asks is the commit still in progress. | S |
| S17 | built | `versions.go` `pinnedOf`; `fingerprint.WithPins`; `form.go` `formOf` (import form `stands` kept only while its built pins equal the new ones) | | |
| S18 | built | `package_trees.go` `derivedDirs`, `derivedTree` (main `b9cc9747`, merged #296) | | |
| S19 | built | `fingerprint.NamedTree` | | |
| S20 | built | `form.go` `refined` | | |
| S21 | built | builder `internal/build/step.go` `buildEntry` (entry by fingerprint through `mesh-catalog.entry`, then `awaitPublished`) | | |
| S22 | built | builder `internal/build/run.go` `runLane` (`awaitPublished`, `ask.Packages`) | Its `delete(ask.Packages, fb.Package)` loop runs over `req.Builds`, which nothing sets (leftover L6). | |
| S23 | built | runner `internal/pipeline/place.go` `stepAsk` (branch runner-step-pins `a926a40e`) | Empty pins are left out, so a step waits for them (S28). | |
| S24 | built | runner `place.go` `place` (source 0 for a run) | | |
| S25 | built | builder `internal/build/revisionwait.go` `awaitRevision`, `PictureHeld`; `module.json` `revision-wait-minutes` | | |
| S26 | built | builder `revisionwait.go` `keptRevisionHolds`; `cmd/.../keptrevision.go` `keptRevisionVia` (branch builder-revision-picture) | The kept revision is judged by its source and its fingerprints; the pins used are then the entry read by fingerprint (S21). | |
| S27 | built | builder `revisionwait.go` `awaitPublished`, `PackagePublished`; `cmd/.../versions.go` `publishedVersionsVia`; `cmd/.../seats.go` (the published heard); `module.json` `package-wait-minutes` | | |
| S28 | built otherwise | runner `place.go` (`unpinnedPackage`, `PinWait`, `endPinHeld`); `steps.go` `OnStepEndedShared`, `endPipeline` (branch runner-step-pins `e3fed775`) | A failed build ends the waiting steps with its outcome (built). When the build passes, `endPinHeld` ends none and nothing asks them: a waiting required step holds `endPipeline`, so the pipeline never ends and holds its place in the queue. The line counts on S14 (a new pipeline at the re-pinned fingerprint), which is missing. | M |
| S29 | built | mesh-build-go `cmd/mesh-build-go/pins.go` `takeZeroRequirements` ("no pin for … the builder pins or waits") | | |
| S30 | built | as S29; `versions.go` `takeRequirementsOf` leaves forge modules to their own rule | | |
| S31 | built otherwise | mesh-build-go `pins.go` `takeZeroRequirements`, `useOwnModules`; `narrow.go` `ownZeroPackageDirs` | Only a same-repository requirement at the zero version comes from the tree. One at a real version is fetched at that version through the Go seat, while the indexer's fingerprint takes the tree's objects (S18): the build and its key disagree. The repository test is the literal owner prefix `"novox/"+p.repo`, a value written into the code. | S |
| S32 | built | mesh-build-go `versions.go` `takeVersion` (a newer go.mod version is built, and said) | | |
| S33 | built | indexer `catalog_revisions.go` `keepBranchEntries` (`rev.Base`, the newest pinned in the same write); `pins.go` `HeardPins`, `unpinElsewhere` | | |
| S34 | built | indexer `pins.go` `HeardPins` (a release record only for a mover with a version), `HeardPipelineWanted` (running only; the newer revision's own release record) | | |
| S35 | not judged | | The question of whether ADR 0573 §4 still binds after the runs on request is the lead's. | |
Counts: 35 lines; built 24, built otherwise 6, contradicts 1, missing 2, not judged 2.
### The six points the lead asked about
1. **The pin key's form.** On the branches every side keys by the full Go module path: the indexer from go.mod and the
registry's published `Module`, the builder from the published `Name`, the Go build module by `p.module`. A nested
path is pinned when the registry published that path (H-A-186's artifacts). The builder writes one git tag per
release, `go/v<version>` (`internal/versions/tag.go` `GoTagOf`), never `<package dir>/v<version>`. The fetch asks the
Go seat first, so the tag is not on the path, but if the seat misses and the fetch falls through to the forge's git,
a nested path's `@v0.1.x` is an unknown revision (leftover L9). I think the refusals of nested paths seen earlier
came from the pins of H-A-161 (the module's release number) and the undeclared artifacts H-A-186 names. Both are
fixed on main and on the branches; the running indexer predates them (section 3).
2. **Reported imports against the go.mod graph.** `formOf` takes the import form when a build reported imports, and
`fingerprint.Resolve` gives versions only for the holders of what was imported. Since `0418a2b9`, `releasedPins`
adds every requirement the go.mod graph names (`required`), so the entry's pin set no longer shrinks to the imports.
The `stands` case keeps `prev.Packages` only while those equal the new pins (`pinnedOf`), so a moved pin moves the
fingerprint (S17).
3. **The recompute of unchanged modules of other repositories** (`recomputeLocked`, the held-stands guard). At a
take-in naming repository R, a module of another repository is recomputed only when its new pins name a package of
R (`importsOf`). Since `0418a2b9` that set includes requirements with an empty pin, so an importer of R's package is
recomputed. Any other module keeps its held value. A publish recomputes every module of the first watched branch's
view (`Recompute` on the registry's published) or the modules naming the released module's packages (`Repin`).
Other watched branches are not reached (S11, S12).
4. **The lane path's trunk asks.** `runLane` waits in `awaitPublished` and copies the filled pins into `ask.Packages`
for a Go fetch with any pin (S22). The lane runs both for a step ask and for the builder's own picture-driven builds
(L5).
5. **A same-repository requirement that is also published.** The indexer never pins it. The Go build module builds it
from the tree only when go.mod names it at the zero version; at a real version it is fetched from the Go seat at
that version (S31).
6. **The "v" prefix.** It is one form across the indexer, builder, runner, step contract and Go build module (S9). The
empty version is the one value the step contract refuses, which breaks runs on request (S8).
## 3. The leftovers
| What | Where | What it does | Line it contradicts |
|---|---|---|---|
| L1 The version line's commit form | indexer `form.go` `lineVersions` (`fingerprint.HeldVersionsOf`, the gate's heads for an unpublished package, G A-365); `fingerprint.VersionLine` | The fingerprint takes, for each other-repository package, the held module's commit or the branch head's commit. A merge of a package's repository moves every importer's fingerprint before anything is published. | S5 in spirit (H-A-161: never a commit). The pins themselves are versions. |
| L2 The accepted series' contents read at the published commit | indexer `series.go` `HearVersion` (`packagesAt`), `acceptedSeries` (DLV-I6) | Reads the published version's package digests through the forge for the import form, keeps a commit form where it cannot. | none (ADR 0593 §2's import form), but a second source of package versions beside the pins |
| L3 A whole recompute on every registry publish | indexer `cmd/.../series.go` `heardVersion` | `Recompute` of every module on each published version, beside the targeted `Repin` on version-released. | none; it duplicates S12's path, and acknowledges on failure (S15) |
| L4 The requirements state from go.sum | indexer `requirements.go` (`indexer_requirements`, `keepRequirements`, `RequiredOf`) | Keeps per package the highest version each consumer's go.sum names, for the builder's floor. Under the zero version go.sum names none (H-A-157). | none directly; H-A-157 says go.sum is never read for package edges, and H-A-159 removed the builder's own numbering it served |
| L5 The builder's picture-driven builds | builder `internal/build/run.go` (the picture's take calls `consider`), `Reconsider`, `Sweep`; `numbers.go` `PackageNamed` | Builds every fingerprint a watched branch's picture takes in, outside any step ask. It is the only path by which a re-pinned fingerprint is ever built today. | none of this part's lines (the earlier model's "the builder builds every fingerprint of the catalog half"); a builder that builds what no pipeline asked is a question for the lead |
| L6 Dead pin deletion | builder `run.go` `runLane` (`for _, fb := range req.Builds`) | Deletes from the pins the packages `builds` names, over a list nothing fills. | none |
| L7 Commit pins and pull-request heads | mesh-build-go `versions.go` `takeVersion` (a commit resolved to a pseudo-version, else `placePin` from `refs/pull/*/head`), README "A pin on a pull request's head" | Accepts a 40-hex commit as a pin and places a pull request's head beside the workspace. | S5 (H-A-161: never a commit) for a delivery build; it served ADR 0573 §4's group heads |
| L8 The literal owner prefix | mesh-build-go `pins.go` `takeZeroRequirements`, `narrow.go` `ownZeroPackageDirs` (`"novox/"+repo`) | Decides "same repository" by a written owner name. | principle 11 |
| L9 One Go tag per release | builder `internal/versions/tag.go` `GoTagOf`, `reserve.go` | Tags `go/v<version>` once per module, whatever paths its Go packages have. | none of this part's lines; H-A-183 names `<package dir>/v<version>` as what the forge's Go seat looks for |
| L10 The candidate check on pins | indexer `candidate_values.go` `checkCandidateModule`; sdk `buildstep` `PackageVersions.Check` | Refuses an empty version. | S8 |
## 4. Live against main
Read through the mesh at 23:00 to 23:10 CET with read tools only (`mesh-delivery-view.node_haves`,
`mesh-catalog.entry`, `mesh-delivery-indexer.indexer_package_users`). Machines are named by role; the mapping is a
guess (section 7).
**The indexer**
| Machine | Build that runs | Main's or by hand | What main and the branches have that it lacks |
|---|---|---|---|
| the control-node | fingerprint `src2:9ac151c2…`, its entry at commit `f00d3467` (main, 2026-11-20 17:35 UTC) | the entry is main's commit; whether a pipeline or a hand placed it the tools do not say | 8 commits of main on the module: H-A-183, 184, 185 (the pin by path and series), H-A-186, H-A-200, H-A-201, H-A-202; and both commits of branch indexer-repin. Live, the entries of the indexer and the runner still carry 40-hex commits as pins, and the busgrants user `nats` shows no pin though 0.1.48 is published. |
**The pipeline runner**
| Machine | Build that runs | Main's or by hand | What main and the branch have that it lacks |
|---|---|---|---|
| the control-node | `src2:adf598f2…`, entry commit `9598b92c` (main, 17:37 UTC) | the entry is main's commit | H-A-187, H-A-189, H-A-190, H-A-191 (steps per mover); branch runner-step-pins (H-A-203, H-A-206) |
**The builder**
| Machine | Build that runs | Main's or by hand | What main and the branch have that it lacks |
|---|---|---|---|
| the workstation | `src2:48cabb7e…`, held: "entry-missing … src2:f34620ec…" since 17:49 CET | no kept entry names `48cabb7e`, so I take it for a build placed by hand or from before the clean state | not readable: no entry gives its commit |
| the control-node | removed ("the applied declaration no longer holds the module") | | |
**The Go build module**
| Machine | Build that runs | Main's or by hand | What main has that it lacks |
|---|---|---|---|
| the control-node, a build node | `src2:ae502407…`, phase failed: "the want … names no digest for mesh-build-go:files, mesh-build-go:tools" | no kept entry names it: placed by hand or from before the clean state | not readable |
| the workstation, the laptop | `src2:c69b0f1c…`, the same failure | the same | not readable |
The delivery SDK is a package, not a running module; nothing of it runs on its own.
## 5. The tests
Counted as `func Test` per file; a file whose header carries `//go:build integration` counts as integration. Table
rows inside one function count once.
| Module (head) | Unit | Integration | Starts the module whole against a bus and a store | What the tests would not catch of the gaps |
|---|---|---|---|---|
| indexer (indexer-repin) | 163 | 6 | yes, `TestIndexerWhole` (`takein_integration_test.go`) | It covers revision pins (S33, S34), not pins of packages: no whole test publishes a package and reads the entry pinned again, the re-pinned module made a mover (S14), another branch's entries (S11, S12) or an acknowledgement after a failed re-pin (S15). Unit tests `TestAnEntryNamesEveryRequirementPinnedOrWaiting` and `TestAReleaseRepinsAnEntryNamingItsPackageWithNoPin` (branch) prove S8 and S12 in the view only. |
| builder (builder-revision-picture) | 154 | 18 | yes, `integration_test.go` runs `run` | Nothing ties the lane's pins to an entry with an empty pin across a restart; the branch's unit test proves S26. |
| runner (runner-step-pins) | 91 | 4 | yes, `run_integration_test.go` runs `run` | No test builds a mover whose pin-held steps outlive a passed build (S28); the branch's `testruns_integration_test.go` checks the pins in the fetch (S23). |
| Go build module (main) | 217 | 18 | I found none that runs the module's `run` (guess; section 7) | Nothing fetches a same-repository requirement at a real version (S31) or a transitive other-repository requirement not in the go.mod (S2). |
| delivery SDK `steprun` + `buildstep` (main) | 113 (of the module's 150) | 13 (all in `steprun`) | not applicable (a package) | Nothing runs `PackageVersions.Check` on an empty version from a candidate (S8). |
All five are inside the budget of 500 unit and 50 integration tests per module.
## 6. Fix in place or write again
**The indexer.** Fix in place. 14 of its 21 lines here are built. The pin's computation (S1 to S9, S17 to S20) and the
revision pins (S33, S34) follow the design. Its shape breaks in one place: a re-pin reaches only the in-memory view of
the first watched branch, and nothing turns a moved fingerprint into a catalog revision and a mover (S12 to S14, L).
That is a design question before it is code. A revision is numbered by its source (H-A-32), and a publish has no
source, so the design must say what takes in a re-pin (a take-in the publish itself starts, or a revision of its own
form). The rest are S: the acknowledgement (S15), the empty pin in a run's candidate (S8), the tool (S16).
**The builder.** Fix in place. Its four lines (S21, S22, S25 to S27) are built on the branch, in the design's shape
(events and a bound, the versions verb read before the wait). Its open question is L5: it builds every fingerprint its
picture takes in, outside any pipeline. Today that is the only path that builds a re-pinned key, so it must not be
removed before S14 is built.
**The pipeline runner.** Fix in place. S23 and S24 are built, and S28 is built but for one case: a pin-held step whose
build passed is never asked and never ended (M). It needs a design line for that case, for example asking the steps
with the pins the build resolved, which its step end would have to carry, or ending them "not asked" in favour of the
re-pinned mover's pipeline once S14 exists.
**The Go build module.** Fix in place. S29, S30 and S32 are built; S31 holds only at the zero version and on a
literal owner name (S each). L7, the commit and pull-request-head pins, is the earlier model's and can go once no ask
names a commit.
**The delivery SDK.** Fix in place: one change, the candidate check's treatment of an empty pin (S8), shared with the
indexer.
## 7. What I could not read, and what I guessed
- I could not send the lead an interim status mid-run: this agent has no messaging tool but its final report.
- **The tool commit of branch indexer-repin** was not in its worktree (clean at `94202fb6`), so S16 is judged missing.
Check: `git log fix/47-H1-indexer-repin` once it lands.
- **The builder's and the Go build module's running builds** have no kept entry (`mesh-catalog.entry` answers "no
entry of fingerprint … is kept"), so their commits are unknown. That they were placed by hand is a guess. Check: the
node-engine's composition of those modules on each machine (`<node>/node-engine.composition`).
- **Whether a pipeline or a hand placed the indexer and the runner** is not said by the tools I used; their entries'
commits are main's.
- **The role of each machine** is a guess from the mesh's instructions (the control-node, the workstation, the laptop,
a build node). Check: `mesh-controller.nodes`.
- **The Go build module's whole test:** I searched its tests for a call of `run` and found none. A test that starts it
another way may exist. Check: read its `*_integration_test.go` files.
- **S2 in practice:** whether every mesh go.mod lists its transitive mesh requirements as `// indirect` I did not read.
Check: `go mod tidy` is a lint step, or read a module's go.mod at main.
- **The cause of the earlier nested-path refusals** (point 1) is a guess from the lead's answers, not from a record of
those builds. Check: `records_search` with the refused build's words.
- Line numbers are not given, by this agent's way of working (they move with every commit); each fact names its file
and function.
## 8. The shortest list of changes still missing after the three branches
1. **A re-pin becomes a revision and a mover** (S12, S13, S14). Owner: the indexer (its take-in), after a design
line from the lead or the design writer on what takes a re-pin in, since a revision is numbered by its source
(H-A-32). It also covers every watched branch, not only the first (S11). Size L.
2. **A pin-held step whose build passed** is asked with the pins the build resolved, or ended for the re-pinned
mover's pipeline (S28). Owner: the runner, with a design line. Size M.
3. **A failed re-pin on the registry's published is not acknowledged** (S15). Owner: the indexer, `heardVersion`.
Size S.
4. **An empty pin passes a run on request's candidate** (S8, L10). Owner: the indexer's `checkCandidateModule`, or the
SDK's `PackageVersions.Check` with an "empty allowed" form for entries. Size S.
5. **The tool answering one entry's pins and paths at a revision** (S16). Owner: the indexer. Size S (in progress).
6. **A same-repository requirement at a real version comes from the tree**, and "same repository" is read from a
setting or the fetch, not the literal owner (S31, L8). Owner: the Go build module. Size S.
7. **Transitive other-repository requirements** are pinned from the pinned packages' own go.mod files, or a check
refuses an untidied go.mod (S2). Owner: the indexer, or the catalog's check. Size M; needed only if a go.mod is
found that does not list them.
L1 (the commit form in the fingerprint's version line) is left in place until item 1 lands, since today a
package's merge moving its importers' fingerprints is what makes them code dependents in that pipeline at all.
@@ -1,116 +0,0 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H2
updated: 2026-11-21
---
# 47 H2 build map: `mesh-catalog`
Read at `origin/main` `553bfb0ccf7c` (2026-11-21 18:30 UTC), from an archive of that commit. Design: hq `35ddd45e`.
DMC-n and DQ-n are the entries at the end of [H2-the-delivery-systems-owed-work](../H2-the-delivery-systems-owed-work.md).
## What exists today
Searches as run, from the archive's root `mesh-catalog/`: the holders of each seat by `"name": "<seat>"` in
`modules/*/module.json` with `claims`; `grep -n "function \|mint\|vault\|lease\|401" modules/gitea/token.ts`;
`grep -rn "not the sweep\|purge\|chunk" --include='*.go' modules/distribution`; `grep -rn "check-needs\|NeedsMarker"
--include='*.go' modules/mesh-build-go`; `grep -rn "over-budget\|budget" --include='*.go' modules/mesh-self-check
modules/mesh-delivery-gate`; `grep -rn "H-A-237\|cancel" --include='*.go' modules/nats/internal/keeper/requests.go`; each
tool of the H2 tools table by its quoted name.
1. **What exists today.**
- Holders: the seat `git`, `go-package-registry` and `npm-package-registry` are `gitea`'s (the forge module, TypeScript);
`oci-artifact-registry`, `container-image-registry` and `mesh-artifact-store` are `distribution`'s; the sweep's seat is
`mesh-artifact-sweep`, held by `artifact-store-tools`; `node-packet-filter` is `nftables`' (TypeScript, verbs `rules`,
`reload`, `remove`, one tool `firewall_rules`); `mesh-broker` is `nats`'; `mesh-self-check` is `mesh-self-check`'s;
`mesh-delivery` is the gate's (`modules/mesh-delivery-gate`).
- The forge module mints its admin token per process into a 0600 file in its state directory with a lock file beside it
(`modules/gitea/token.ts:5-33`, `:131-285`); it answers a refused admin as `AdminRefused` worded as an account to create
(`token.ts:95-101`); its seat error answers say `refused` or `failed` (`modules/gitea/seat.ts:71`). No tool reads a
token lease; no `forge_merged`.
- The gate keeps the ledger `records` (requires, ledger template, 768 MiB; `modules/mesh-delivery-gate/module.json`
`requires`) and the state `source`; its tools include `gate_record`, `gate_records`; no `gate_times`.
- The self-check holds no delivery budget probe (search above found none).
- The build modules ask for `steps` (state, TTL 172,800 s, objects 256 MiB), `detected-steps`, and the Go one
`kept-builds` objects; none keeps `outputs` (`modules/mesh-build-{go,node,image}/module.json` `requires`).
`check-needs` is a marker file in a package's directory, chosen "not a manifest field"
(`modules/mesh-build-go/cmd/mesh-build-go/digest.go:59-66`).
- The registry refuses a removal by any caller but the sweep (`modules/distribution/internal/holder/verbs.go:165-166`);
its `list` takes `name` only (the seat's definition in `mesh-delivery`); its chunk delete is
`cmd/distribution-tools/bounded.go:62`.
- The bus module's tools: `nats_consumer` (one), `nats_connections`, `nats_backlog`; no `nats_consumers`
(`modules/nats/module.json` `tools`). The keeper asks a drop or recreate at the approve level, naming H-A-237
(`modules/nats/internal/keeper/requests.go:75`, `:334`); a refused request does not cancel its ask (no cancel call in
that file).
- The vault's seat serves `own` to the node-engine of a machine only, read-only, sealed to the machine's key, and a
two-step sealed write exists only for the licence manager (`licence-put`) (the seat's definition in `mesh-contracts`
`identity-and-access/seats/mesh-vault/seat.json`; claim in `modules/mesh-vault/module.json`). No verb writes a
module's own secret from the module.
- `nfs-server` and `pacman` hold 0 and 3 integration tests by `-tags integration` (below).
2. **What the change touches, and what relies on each.** The token file and its lock (`token.ts`): read only by the forge
module's processes. The removal refusal (`verbs.go:165`): relied on by nobody else (every account may call every
verb, §813 (7)). The registry's `list` answer whole: read by the sweep (`modules/artifact-store-tools`). The marker
file `check-needs`: read by the Go build module's digest (`digest.go:68-80`) and `mesh-delivery-sdk`
`steprun.AskNeeds`. The gate's whole-revision ledger entry: read by `gate_record`, `gate_records`, `delivery_status`,
the gate's `deliveries` and `show` verbs (`cmd/mesh-delivery-gate/recordtools.go`, `verbs.go`).
3. **Fates.** The per-process mint goes (§808); the refusal "not the sweep's" goes (§813 (7)); the whole-revision entry
goes (§809); the Node build module's and the recovery module's setup bounds in code go (§800); the marker file's fate
against §800's manifest field is DMC-6. New parts and their lines: state `token-lease` (§808, §820), `outputs` objects
(§791, §820), settings `owed-away-bound` (§807, the bridge's), `token-ttl`, `mint-lease` (§808), `budget-core`,
`budget-leaf` (§810), `again-delays` (§799), tools `forge_token_lease`, `forge_merged`, `gate_times` (the tools table).
## Rows
| line | files and functions | subtask | acceptance (cites) | test |
|---|---|---|---|---|
| §776 | `modules/gitea/seat.ts:71`, `token.ts:95-101`, the version read | C1 forge says `away` (waits DMC-2) | a 401 with the version read failing answers `away`; with the read passing and the fresh token refused answers `refused`; the store stopped 30 s, a merge call answers `away` and lands when called again (§776) | unit, whole (forge module) |
| §775 | `modules/gitea` the seat `git`'s act verbs (`writes.ts`, `mergecall.ts`): take an ask once by its id, state `taken` | C2 forge takes once | a holder given the same ask id twice acts once (§775) | unit |
| §796 | `modules/gitea` `tags` (`seat.ts`, `readall.ts`) answers `commit` per tag | C3 tags with commit (uses `mesh-delivery` D5) | §796 whole (builder) | whole |
| §808 | `modules/gitea/token.ts` (vault read and write, lease `mint` in `token-lease`, delete the replaced token), `modules/gitea/tools` `forge_token_lease`, manifest settings | C4 one mint at a time (waits DQ-7) | two processes, one holding the old token, both refused, mint one token in all; the forge holds one token after; a minter killed holding the lease is replaced after `mint-lease` (§808) | unit, whole |
| §812 | `modules/gitea/tools` `forge_merged` (repository, from, to) | C5 merged pull requests | per tools table (§812) | unit |
| §815 | `modules/gitea/mergecall.ts`, `failedsteps.ts`: judge a source-only head by its registration's policy from the runner's step events | C6 merge a source-only head | an hq pull request whose Go checks fail is refused naming the failed step (§815) | whole |
| §809 | `modules/mesh-delivery-gate/cmd/mesh-delivery-gate/record.go`, `recordevents.go`, `recordtools.go`: head entry `<branch>.<source>`, per mover `<branch>.<source>.<module>`, refusal over 64 KiB, finding `record-too-large`; manifest `records` 1 GiB | GT1 ledger per module | 126 movers write 127 entries, none over 64 KiB; an entry made too large raises the finding, cleared at the end (§809) | whole (gate) |
| §810 | `record.go` (end: `delivery-time`, `class`, `phases`), `settings.go` (`budget-core`, `budget-leaf`), tool `gate_times` | GT2 delivery times (uses `mesh-delivery` D2) | §810 whole (gate and probe) | whole |
| §811 | `verbs.go` `deliveries` filters and cap | GT3 filtered reads (uses D6) | `deliveries` by repository over 4 MB answers under 768 KB (§811) | unit |
| §815 | `takenin.go`, `record.go`: a source-only merge watched as any branch, record ends `nothing to deliver` | GT4 source-only record | raises no `head-untaken` and ends `nothing to deliver` (§815) | whole |
| §810 | `modules/mesh-self-check` a probe reading the gate's times, condition `over-budget` by class | SC1 over-budget probe | a core record 11 min after `merge-called` raises `over-budget` for `core`; the next within ten minutes clears it (§810) | whole |
| §799 | `modules/mesh-build-go`, `mesh-build-node`, `mesh-build-image`: fetch and publish faults end the run `again`; setting `again-delays`; third run `fetch:` or `publish:` | BM1 again on a part away (waits DMC-7) | the kit holds a fetch met by a 401 and a publish met by no responders to `again`, and three such runs to failed with `fetch:` and `publish:` (§799) | conformance kit |
| §800 | `modules/mesh-build-go` summary `not-run`, setup bound from `MESH_TEST_LEVEL_BOUND`, could-not-run at the third starved setup; unpack an install archive | BM2 not run and starved setup (waits DMC-6) | the forge module's whole-seat test runs with its npm tree; a starved setup runs again and ends could-not-run at the third (§800) | whole (Go build module) |
| §800 | `modules/mesh-build-node`: accepted kind `install`, `npm ci` with no install scripts, the archive in `outputs` under the lock's digest; its setup bound in code goes | BM3 install | an install runs no script (§800) | unit (Node build module) |
| §791 | the three build modules: `outputs` objects (1 GiB, 7 days), the verb `output` | BM4 outputs kept | §791 whole (Go build module) | whole |
| §801 | the three build modules: `current` per holder, steps read tools never empty while steps run | BM5 current | a paused holder answers `paused` (§801) | whole |
| §775 | `modules/distribution` publish: take an ask once by its id, state `taken` | RG1 registry takes once | §775 unit | unit |
| §813 (7) | `modules/distribution/internal/holder/verbs.go:165` (refusal goes), `list` paged by `module` and cursor; `modules/artifact-store-tools` reads page by page | RG2 paged list and sweep removals (waits DMC-10) | a pass over 20,000 artifacts removes what it judges (§813 (7)) | whole (sweep) |
| §813 (8) | `modules/distribution/cmd/distribution-tools/bounded.go:62`: purge a deleted chunk's subjects | RG3 chunk leftovers | after 1,000 chunks deleted, messages equal live objects (§813 (8)) | whole (registry) |
| §813 (5) | `modules/nats/cmd/nats-tools/consumer.go`, `main.go`: `nats_consumers` sorts, `nats_connections` busiest subscriptions | N1 flow tools (waits DMC-11) | unit (§813 (5)) | unit |
| §813 (6) | `modules/nats/internal/keeper/requests.go`: a refused request cancels its ask on `operator-channel` | N2 keeper cancels | unit | unit |
| §813 (11) | `requests.go:75`, `:334`: the bend's line names the research as its end | N3 bend line | a drop asks at the approve level (§813 (11)) | unit |
| §813 (4) | `modules/nftables/client.ts`, `tools/index.ts`: read a port's scope from `rules` | P1 scope from the rule (waits DMC-12) | `allow` without a source is refused for a `private-network` port (§813 (4)) | whole (packet filter) |
| §781 | `modules/nftables`: ask `converged` within the verb's `timeout` | P2 converged (waits DMC-12) | §790 | whole |
| §808 | `modules/mesh-vault/cmd/mesh-vault` a write verb of a module's own secret (H-A-345) | VA1 (waits DQ-7) | per its answer | unit |
| §800 | `modules/mesh-recovery` tests' setup bound in code goes | MR1 | §800 | unit |
| §783, §812, §820 | manifests of the gate, the three build modules, `distribution`, `gitea`: findings stream, caps | M1 manifests (waits DQ-5) | the manifest check of §814 | whole |
| §819 | `modules/nfs-server`, `modules/pacman` tests | NP1 shrink to 50 integration | the check's counts | check |
## Order and writers
- After `mesh-delivery`'s D3, D4, D5, D6 and mesh-sdk's S1 to S3, S6, S11. C3 after D5; GT2 after D2; BM1 to BM5 after D3
and the kit (`mesh-delivery` `modules/mesh-delivery-sdk/steprun/conformance`, written by this map's build modules'
agent). P1 after the node-engine's render (the node-engine's map, E6).
- One writer per file: one agent for `modules/gitea` (TypeScript); one for the gate and the self-check; one for the three
build modules and the conformance kit; one leaf agent for `distribution`, `artifact-store-tools`, `nats`, `nftables`,
`mesh-vault`, `mesh-recovery`, `nfs-server`, `pacman`.
## Local facts
- Placement of the siblings: as the `mesh-delivery` map says (`modules/mesh-build-go/cmd/mesh-build-go/workspace.go:17-60`).
The TypeScript modules (`gitea`, `nftables`) build with their `package.json`; their tests are not counted by `go test`.
## Test budget (§819), `go test -list '.*'`, without and with `-tags integration`, top-level functions
Counted 22:20 to 22:30 CET (unit / integration): gate 30 / 2; Go build module 205 / 15; Node build module 117 / 8; image
build module 56 / 6; `distribution` 9 / 1; `artifact-store-tools` 23 / 1; `nats` 38 / 7; `mesh-self-check` 10 / 1;
`mesh-vault` 143 / 2; `mesh-recovery` 24 / 1; `nfs-server` 51 / 0; `pacman` 118 / 3; `gitea`'s Go part 176 / 2. §819's
"NFS server 51 integration, package manager 121 integration" are the build node's counts, which take untagged tests in
(plan section 10: the build node counts untagged tests into a module's integration count); by the tag they hold 0 and 3 (DQ-14).
@@ -1,52 +0,0 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H2
updated: 2026-11-21
---
# 47 H2 build map: `mesh-contracts`
Read at `origin/main` `87eab81be134` (2026-11-20 07:12 UTC), from an archive of that commit. Design: hq `35ddd45e`.
DMC-n and DQ-n are the entries at the end of [H2-the-delivery-systems-owed-work](../H2-the-delivery-systems-owed-work.md).
## What exists today
Searches as run: `ls seats */seats`; the verbs of `seats/node-engine/seat.json`, `seats/mesh-broker/seat.json`,
`identity-and-access/seats/mesh-vault/seat.json` by `python3`; `grep -rn "DisallowUnknownFields" --include='*.go' go`;
`grep -rl '"node-packet-filter"'` over every repository (found only in `mesh-sdk`'s test seat list); live: `mesh_search`
"node-engine composition" answered `mesh-vault.own` "from the node-engine o…" (22:27 CET).
1. **What exists today.**
- The node-engine seat: 18 verbs, none `converged`, none with `timeout` (`seats/node-engine/seat.json`).
- `mesh-broker`: `list`, `show`, `check`, `orphans`, `create`, `apply`, `recreate`, `drop` and the snapshot verbs
(`seats/mesh-broker/seat.json`): §783's and §812's reads through `show`, `list`, `apply` exist.
- `mesh-vault`: `own` answers the node-engine of one machine about its own machine (the caller as the bus proves it),
sealed to the key it stated with `node-key`, read-only; `get` answers one secret sealed to the asker's key to an
asker the vault allows; `licence-put` is a two-step sealed write for the licence manager alone; no verb writes a
module's own secret from that module (`identity-and-access/seats/mesh-vault/seat.json`, verbs `own`, `get`,
`licence-put`, `rotate`, `move-in`).
- Every generated decoder here refuses unknown fields (`go/seats/meshmoduleassigner/contract.go` 8 places,
`go/seats/nodeengine/contract.go` 9, `go/seats/meshconfig/contract.go` 1, `go/clients/nodeengineclient` 2); no
definition carries `form`.
- No seat definition of `node-packet-filter` here.
2. **What relies on each.** Every module importing a generated contract here (the node-engine, the assigner, the tool
runner, the vault, the provisioner) reads with these decoders.
3. **Fates.** Regenerated tolerant (§780). New parts: the vault's write verb (§808, H-A-345; DQ-7), `converged` and
`timeout` (§781; DMC-12).
## Rows
| line | files | subtask | acceptance (cites) | test |
|---|---|---|---|---|
| §780 | every `seats/*/seat.json` and `*/seats/*/seat.json` (`form`), regenerated `go/`, `ts/` with `mesh-delivery`'s `seatgen` | K1 regenerate tolerant, `form` | §780 unit | unit |
| §808 | `identity-and-access/seats/mesh-vault/seat.json`: a write of a module's own secret (H-A-345) | K2 vault write verb (waits DQ-7) | the forge module writes and reads its token through the vault seat (§808) | unit, whole (forge module) |
| §781 | `seats/node-engine/seat.json`: `converged` with `timeout` (waits DMC-12) | K3 | §781 | unit |
## Order and writers
K1 after `mesh-delivery` G1 (the generator); K2 before `mesh-catalog` C4 and VA1; K3 before `mesh-catalog` P2. One agent.
## Test budget (§819)
Not a module H2's count names; its packages' tests are read in the check.
@@ -1,191 +0,0 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H2
updated: 2026-11-21
---
# 47 H2 build map: `mesh-delivery`
Read at `origin/main` `7e597a623eb2` (2026-11-21 21:01 UTC), from an archive of that commit (`git archive origin/main`),
never a working tree. The design read is hq `35ddd45e` (branch `design/47-H2-part`). Every row cites the design line it
builds ("design 47 H2 §n"). Where a line meets code that cannot take it, the row points to the entry under *Design meets
code* (DMC-n) or *Design questions* (DQ-n) at the end of
[H2-the-delivery-systems-owed-work](../H2-the-delivery-systems-owed-work.md); such a subtask waits for its answer.
## What exists today
Searches as run, from the archive's root `mesh-delivery/`:
`grep -rn "CallKept\|DoKept\|DoRepeatable" --include='*.go' modules`; `grep -rn "Subscribe(" --include='*.go'
modules/mesh-delivery-builder/cmd modules/mesh-delivery-assigner/cmd`; `python3` over every
`modules/mesh-delivery-contracts/seats/*/seat.json` listing verbs, accepts and events; `grep -rn "DisallowUnknownFields"
--include='*.go' modules`; each tool of the H2 tools table searched by its quoted name in every `module.json` and Go
file; live: `nats.nats_streams` with `stream` `SEAT_MESH_BUILDS` and `SEAT_MESH_WANTS` (answered by novox, 22:25 CET).
1. **What exists today.**
- The kept call is built in mesh-sdk (`CallKept`, `busretry.DoRepeatable`, `DoKept`) and used by the runner
(`cmd/mesh-delivery-pipeline/drop.go`, `main.go`, `verbs.go`), the assigner (`main.go`, `puts.go`, `askended.go`,
`compositionrun.go`), the builder (`buildrun/asks.go:183`, `cmd/.../reads.go`), the bridge (`moves.go`, `bound.go`).
The runner puts step asks by a JetStream publish with the ask id as message id
(`modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline/asks.go:27-42`), one try.
- Seats `mesh-builds` and `mesh-wants` each accept one kind, `step` (`seats/mesh-builds/seat.json` `accepts`,
`seats/mesh-wants/seat.json` `accepts`); neither declares `ask-taken` nor `version-reserved`. The grants part derives
their work-queue streams `SEAT_MESH_BUILDS` and `SEAT_MESH_WANTS` with a shared worker, ack wait 60 s, max deliver 5,
max age 7 days (`modules/mesh-grants/internal/buscompose/derived.go:86-110`, `:343-358`). The builder hears asks by a
plain subscription (`modules/mesh-delivery-builder/cmd/mesh-delivery-builder/step.go:78`), the assigner likewise
(`modules/mesh-delivery-assigner/cmd/mesh-delivery-assigner/compositionstep.go:257`). Live: `SEAT_MESH_BUILDS` holds
1,558 messages, `SEAT_MESH_WANTS` 1,598, each with 0 consumers, max age 168 hours.
- The runner treats `mesh-builds` and `mesh-wants` as silent seats with `ask-silent-bound` (45 min) and the build seats
as seats that say `ask-taken`, with a second put under `AgainID` and a second bound key `ask2.`
(`modules/mesh-delivery-pipeline/internal/pipeline/asks.go:17-160`, `cmd/.../askbounds.go:20-35`).
- The runner's step record has no `asked-at` or `taken-at`; `pipeline-ended` has no `phases` or `unfinished`
(`seats/mesh-pipeline-runner/seat.json`). Its stalled bound is the constant `StalledAfter` 5 minutes
(`internal/pipeline/consumers.go:26`). It keeps step outputs in objects `step-outputs` (`internal/pipeline/steps.go:138`,
`cmd/.../steps.go:100`; manifest `objects` `step-outputs` 1,024 MiB). Its tools: 14 (`module.json`), with
`runner_health`; no `runner_show`, `runner_movers`, `runner_cancel`, `runner_step_output` or `runner_unfinished*`.
- Delivery modules ask for their stores in the manifest's old sections (`state`, `streams`, `objects`): the runner's
findings stream `mesh-delivery-pipeline-findings` 16 MiB 7 days (`module.json:222-232`), the builder's likewise
(`module.json:140`); the bridge asks for `performed` in `requires` by the state template, TTL 604,800 s
(`modules/mesh-delivery-forge-bridge/module.json:40-45`).
- Generated seat decoders refuse unknown fields (`DisallowUnknownFields` in every `go/seats/*/contract.go`); no seat
definition carries `form` (each has the file's `format: 1`). The seat generator is `modules/mesh-delivery-sdk/seatgen`
(`gogen.go`, `tsgen.go`), not in mesh-sdk.
- Two copies of the contracts and the delivery SDK stand: `contracts/` and `sdk/` at the repository's root (used only by
each other) and `modules/mesh-delivery-contracts`, `modules/mesh-delivery-sdk` (used by every module).
- The build-step part (`modules/mesh-delivery-contracts/parts/build-step.json`) already has the verbs `current`
(answer: the steps running, capacity, paused), `output` (a chunked whole answer by `ask` and `call`), `drop`, and the
event `ask-taken` on `ask-taken.<node>`.
- The builder's tag form is `go/v<version>` (`modules/mesh-delivery-builder/internal/versions/tag.go:4`,
`reserve.go:264`); its floor reads tags by `TagPrefix` (`claim.go:50-56`). Its unbuildable plans are said per module
(`buildrun/buildseats.go:114`). Its publish items are a state bucket (`cmd/mesh-delivery-builder/publishitem.go:44-110`),
read with `builder_publish_queue` (exists). Its published mark keeps `published-at` and kept releases keep `digest`
(`internal/versions/reserve.go:57-59`, `:95-98`, `:102-106`, `:460-463`): §798 is built on main.
- The fingerprint is computed in the indexer alone (`modules/mesh-delivery-indexer/internal/fingerprint/fingerprint.go:1-5`,
`Of`), over the directory's tree or the named paths (`internal/index/inputs.go:97-118`); a repository's commit enters
through unpublished packages and the import form's versions (`internal/index/form.go:27-50`, `:113-125`).
- The indexer's dry run is a copy of its states kept in memory that still writes manifests and packages to the bus
(`internal/index/dryrun.go:12-40`). The validate step and `causedProblems` are the assigner's
(`cmd/mesh-delivery-assigner/validatestep.go:124`, `:203-230`), counting every problem of a touched module. The seat
`mesh-catalog` has `seat-definitions`, no `seat-list`; a registration is keyed `<module>` and requires `module`,
`origin`, `path`, `branches`, `policy` (`seats/mesh-catalog/seat.json` `defs.Registration`).
- The teller keeps a wait for room and its tests (`modules/mesh-delivery-teller/cmd/mesh-delivery-teller/ends.go:16-68`,
`room_test.go`).
2. **What the change touches, replaces or removes, and what relies on each.**
- Plain subscriptions on `mesh.seat.mesh-builds.accept.step` and `mesh.seat.mesh-wants.accept.step`: written by the
runner (`asks.go:27`), heard by the builder (`step.go:78`) and the assigner (`compositionstep.go:257`); nothing else
subscribes (search above).
- `ask-silent-bound`, `SilentWhy`, `AgainID`, `ask2.` keys: written and read only in the runner
(`internal/pipeline/asks.go`, `bounds.go`, `cmd/.../askbounds.go`, `main.go:172`); the setting's file
`MESH_RUNNER_ASK_SILENT_BOUND_FILE` is named in the runner's manifest.
- Objects `step-outputs`: written by the runner's hearer (`internal/pipeline/steps.go:305`), read by `read.go:25-42`.
- The builder's publish-items bucket: written by `publishitem.go:96`, read by `republish.go` and the tools bundle
(`cmd/mesh-delivery-builder-tools/republish.go:37`).
- The runner's drop of `kept-revisions` before the seat decode (`internal/pipeline/steps.go:203-207`, `verbs.go:609`,
`moverkeys.go:294-300`).
- The tag form `go/v<version>`: read by the builder's floor (`claim.go:213`) and by Go's toolchain at fetch.
- The teller's room wait: written and read in the teller only (`ends.go`, `assignerasks.go:20-24`).
3. **What happens to each, and the test.** Plain subscriptions go (design 47 H2 §777; proven by the whole-module tests of
§777). `ask-silent-bound` and its key go (§777); `AgainID` and `ask2.`: no line gives their fate on the build seats
(DQ-4). `step-outputs` goes, dropped through the bus module (§791; the search for its name finds no reader). The
publish-items bucket goes after one move (§793). The `kept-revisions` drop goes (§780). `go/v` tags go from new
versions (§796). The room wait goes (§813 (10); the teller's suite holds no such test). New exported parts and their
placing lines: `ask-taken` and `version-reserved` events (§777, §805, §821), `phases` and `unfinished` (§785, §786),
`asked-at`, `taken-at` (§778), states `unfinished` (§786, §820), `taken` (§775, §820), `dry-runs` (§804, §820), work
queue `publishes` (§793, §820), verb `seat-list` (§814), the source-only registration (§815; its key is DQ-9).
## Rows: each design line, where it lands, its subtask
Labels: `D` contracts (`modules/mesh-delivery-contracts`, regenerated by `seatgen`), `G` the generator
(`modules/mesh-delivery-sdk`), `R` the runner, `B` the builder, `I` the indexer, `A` the assigner, `F` the bridge, `T` the
teller, `V` the view. Each acceptance cites its design line's *How it is checked*.
| line | files and functions | subtask | acceptance (cites) | test |
|---|---|---|---|---|
| §780 | `modules/mesh-delivery-sdk/seatgen/gogen.go`, `tsgen.go`, `load.go` (decoders, `form`, the generator's check) | G1 tolerant decoders and `form` (waits DMC-4) | a value, event, answer with an unknown field decode and return their form; absent `form` reads 1; a definition whose fields changed with `form` unchanged fails (§780) | unit, `seatgen` |
| §780 | every `go/seats/*/contract.go`, `ts/` (regenerated) | D0 regenerate all seats from G1 | the generated decoders keep unknown fields (§780) | unit, `mesh-delivery-contracts` |
| §777, §821, §805 | `seats/mesh-builds/seat.json`, `seats/mesh-wants/seat.json`: accepted kinds as work queues with their settings, `ask-taken` (`<seat>.ask-taken.<ask>`: `ask`, `node`, `at`), `version-reserved` (`module`, `artifact`, `path`, `version`, `fingerprint`, `revision`) | D1 queues and events of the two seats (waits DQ-1, DQ-2, DMC-1) | the seat list carries each family and name (§821) | unit, `mesh-delivery-contracts` fixtures |
| §778, §785, §786, §789, §821 | `seats/mesh-pipeline-runner/seat.json`: step `asked-at`, `taken-at`; `pipeline-ended` `phases`, `unfinished`; `show` filters `mover`, `step`, `state`, answer `capped`, `total`, `next`; the re-pin's event (DQ-13) | D2 runner seat | `pipeline-ended` of two movers carries each step kind's span (§785) | unit, fixtures |
| §791, §800, §801 | `parts/build-step.json` (`output` input `ask`, answer last 64 KB, size, failing tests, "no longer kept"; `current` per holder takes or why not, every ask; summary `not-run`), `seats/node-build-node/seat.json` (accepted kind `install`) | D3 build-step part (waits DMC-6, DMC-16) | per §791, §800, §801 checks | unit, fixtures |
| §806, §814, §815 | `seats/mesh-catalog/seat.json`: `registrations` filters `module`, `repository`, `capped`, cursor; verb `seat-list` (`digest`, `size`, `object`); the source-only registration (`repository`, `branch`, `policy`, `check`) | D4 catalog seat (waits DQ-9) | §806 unit; §815 whole | unit, fixtures |
| §776, §796 | `seats/git/seat.json`: `tags` answer `commit` per tag, the listing's description of `not-found`, `ErrorKind` gains `away` | D5 git seat (waits DMC-2, DMC-3) | §796 whole (builder) | unit, fixtures |
| §811 | `seats/mesh-delivery/seat.json`: `deliveries` filters `repository`, `module`, `outcome`, `since`, answer `capped`, `total`, cursor | D6 delivery seat | `deliveries` by repository over 4 MB answers under 768 KB (§811) | unit (gate) |
| §775 | `modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline/asks.go` `busStepAsker.AskStep`, every seat call of the runner | R1 asks as kept calls with the pace and `ask-unanswered-bound` | a composition ask whose holder is away 40 s passes its step with no hand act (§775) | whole, runner |
| §777, §778 | `internal/pipeline/asks.go` (`Silent`, `AskClock`, `AskUnanswered`), `bounds.go`, `cmd/.../askbounds.go`, `consumers.go` (hear `ask-taken` of both seats), the step record | R2 bound from the pull, untaken bound, drop at the bound, put again only on a transport fault (waits DMC-15, DQ-4) | ask taken 9 min before a restart with a 10 min bound ends 1 min after start and is dropped; untaken for `stalled-bound` named by health; untaken for the whole bound ends could-not-run naming the holder; a put refused for a full stream is said and asked again (§777, §778) | unit, runner |
| §784 | `internal/pipeline/steps.go` (the one place saying `step-ended`), the place an ask is put | R3 journal lines | each way a step ends writes that line once (§784) | unit |
| §785 | `internal/pipeline/steps.go` `endPipeline` (`:731`) | R4 phases | two movers end with each kind's span (§785) | unit |
| §786 | new state `unfinished`; `endPipeline`; the take-in consumer; tools bundle `runner_unfinished`, `_drop`, `_place` | R5 movers put in a pipeline again | of two movers one fails unit; `pipeline-ended` names the other; the next take-in's pipeline carries it; it is wanted (§786) | whole, runner |
| §787, §780 fate | `internal/pipeline/steps.go:203-207`, `verbs.go:609`, `moverkeys.go:294-300` | R6 `kept-revision-unread`, drop of `kept-revisions` goes | unit (§787) | unit |
| §788 | `internal/pipeline/registration_missing.go`, the registrations view, `runner_health` | R7 registrations read first | a start with the view unread raises none, answers `registrations-read` false, places once read (§788) | unit |
| §789 | `internal/pipeline/read.go` `Show`, the `show` verb, new tools `runner_show`, `runner_movers` | R8 a pipeline in parts (waits DMC-8) | one mover of 129 under 64 KB; `runner_movers` of 1,000 under 768 KB (§789) | unit |
| §790 | `internal/pipeline/consumers.go:26` `StalledAfter` to the setting `stalled-bound`; process and tools program read it | R9 stalled bound a setting (uses mesh-sdk S6) | at one minute, health names such a pipeline after one minute, not once a step is placed (§790) | whole |
| §791 | new tool `runner_step_output`; `step-outputs` dropped (`internal/pipeline/steps.go:138`, `:305`, `read.go`) | R10 step output where kept | a failing unit test's words read through `runner_step_output`; past max-age "no longer kept" (§791) | whole (Go build module) |
| §815 | the run on request of a source-only registration's head as one step (`cmd/.../testruns.go`, `internal/pipeline` run path) | R11 a source-only check | a source-only pull request is run on request (§815) | whole (indexer, runner, gate) |
| §783, §820 | `modules/mesh-delivery-pipeline/module.json` (findings stream 8 MiB, `findings-max-age`; `unfinished`; `taken`; setting `stalled-bound`; drop `step-outputs` and `ask-silent-bound`) | R12 runner's manifest (waits DQ-5) | 10,000 findings past the cap refuse none (§783) | whole |
| §775, §777 | `cmd/mesh-delivery-builder/step.go` `serveSteps` (pull the worker, in-progress, ack at the end, `ask-taken`, `taken`); `buildrun/asks.go` publish asks to registries as kept calls | B1 pull and take once | a build ask put while the builder is stopped is taken and ended after its start (§777) | whole, builder |
| §777 | new tools `builder_asks`, `builder_ask_drop` | B2 queue tools | per tools table | unit |
| §792 | `step.go` (the build step's finish) | B3 answered line | unit (§792) | unit |
| §793 | `cmd/mesh-delivery-builder/publishitem.go`, `internal/versions/republish.go`, tools `builder_publish_queue` (exists), `builder_publish_drop`, `builder_publish_first`; the one move of the bucket | B4 publishes work queue (waits DQ-6) | a live publish behind 100 `again` is sent first; a dropped item never sent; a move run twice puts each once (§793) | whole |
| §794 | `internal/versions/heard.go` (handling of `published`, `package-published`), health | B5 one read and one write | 1,000 events over 2,000 reservations: one read and one write each; a backlog held six minutes named (§794) | unit, whole |
| §795 | `buildrun/buildseats.go:114`, new tool `builder_unbuildable` | B6 one summary line | 6,500 unbuildable plans write one line (§795) | unit |
| §796 | `internal/versions/claim.go`, `reserve.go:264`, `tag.go` | B7 tags read before reserve, `version-tagged-elsewhere`, tag `<directory>/v<version>` | a tag at another commit makes the next number and the finding, cleared at the next release (§796) | whole |
| §797 | `modules/mesh-delivery-sdk/buildrecord` and the builder's writer | B8 build record end | unit (§797) | unit |
| §798 | `internal/versions/reserve.go:57-106`, `:452-466` | none: built on main | a publish heard now answers its time (§798): read the existing test | unit (exists) |
| §799 | the builder's reading of a step's why (`buildrun/heardends.go`, `faults.go`) | B9 `fetch:` and `publish:` said apart | per §799 | unit |
| §801 | new tool `build_current` (asks every holder's `current`) | B10 build current | an ask the builder put is listed by `current` while it runs (§801) | whole (Go build module) |
| §805 | `internal/versions/reserve.go` (say `version-reserved` at the reservation) | B11 version-reserved | §805 whole (indexer) | whole |
| §802 | the builder's read of the fingerprint (`internal/build/run.go`) | B12 builder takes the new fingerprint (waits DMC-5) | §802 whole (indexer) | whole |
| §783, §820 | `modules/mesh-delivery-builder/module.json` (findings, `publishes`, `taken`) | B13 builder's manifest (waits DQ-5) | §783 | whole |
| §802 | `internal/fingerprint/fingerprint.go` `Of`, `internal/index/form.go` `formOf`, `lineVersions` | I1 fingerprint over the module's own build source (waits DMC-5, DQ-8) | a commit touching two test files of two modules of 36 moves those two and their importers alone (§802) | whole, indexer |
| §803 | the take-in's waits on the seat `git`, versions, a registry; value of `takeins` (`waiting-on`); finding `take-in-waiting` | I2 take-in says what it waits on | 70 s writes one line and `waiting-on`; six minutes raises the finding, cleared at the answer (§803) | unit |
| §804 | `internal/index/dryrun.go`, `runcandidates.go:213`; state `dry-runs`; tool `indexer_dry_runs` | I3 dry run's own state | trunk packages byte for byte as before; a start finds `dry-runs` empty (§804) | whole |
| §805 | the re-pin path (`internal/index` pins, the consumer of `package-published`), consume `version-reserved` | I4 re-pin once at the reservation | a release importing twenty packages of its pipeline keeps one re-pin revision (§805) | whole |
| §806 | the `registrations` verb, new tool `indexer_registrations` | I5 registrations in one call | unit (§806) | unit |
| §814 | verb `seat-list` (one object in the indexer's objects by digest), `cmd/mesh-judge` reads it by address, `judge/rules.go` refuses an uncapped store of a delivery module, tool `indexer_validate_before` | I6 seat list and the uncapped refusal (waits DMC-9, DQ-10) | a run by hand against `seat-list` gives the live validate's verdicts for the builder's and the runner's manifests; an uncapped entry refused, a foundation part's capped old-section entry not (§814) | whole, unit |
| §815 | registrations state and `register`; take-in of a source-only branch with no movers; refusal when the repository holds a manifest | I7 source-only registration (waits DQ-9) | §815 whole | whole |
| §818 | `indexer_recompute` (exists) | none: a run, not code | the lead reads `runner_movers` (§818) | live |
| §775 | `cmd/mesh-delivery-assigner/compositioninputs.go:24`, `:109` (`compose-candidate` as kept call, `compose-ask-bound`) | A1 compose-candidate kept | §775 whole (runner) | whole |
| §777 | `compositionstep.go:257` (pull), new tools `assigner_asks`, `assigner_ask_drop` | A2 pull validate and compose (waits DQ-1) | a validate ask put while the assigner is stopped is taken after its start; after a pipeline's end both consumers hold 0 pending (§777) | whole, assigner |
| §792 | `compositionstep.go`, `validatestep.go` | A3 answered line | unit | unit |
| §813 (1) | the composition writer (`compositionrun.go`, `puts.go`): `run`, compare-and-set refusing a lower `run` | A4 one writer per composition key (waits DQ-12) | unit (§813 (1)) | unit |
| §813 (2) | the keeping of assignment graph revisions (`revisions.go`, `graphkept.go`), setting `keeping-retry`, finding `keeping-failed`, tool `assigner_keep_now` | A5 failed keeping runs again | unit (§813 (2)) | unit |
| §814 | `validatestep.go:203-230` `causedProblems` (drop the touched clause) | A6 only new problems (waits DMC-9) | a problem the before case holds is not counted (§814) | unit |
| §807 | `cmd/mesh-delivery-forge-bridge/acts.go`, `call.go`, `bound.go` (`owed-away-bound`), `cmd/mesh-delivery-forge-bridge-tools/owed.go` (`bridge_owed_again` `record`, preconditions again) | F1 owed through a part away | forge away 60 s: a note act is performed after, no hand act; a closed pull request's act is ended (§807) | whole, bridge |
| §811, §812 | `bridge_owed` by pull request in the process; `performed` prune and `performed-keep` | F2 performed capped | a write past 70 % prunes to 50 %; a key under `state_keep` survives (§812) | whole, bridge |
| §813 (10) | `modules/mesh-delivery-teller/cmd/mesh-delivery-teller/ends.go`, `assignerasks.go`, `room_test.go` | T1 room wait goes | the teller's suite holds no such test (§813 (10)) | unit |
| §813 (9) | `modules/mesh-delivery-view` usage reading | V1 usage by `current` | unit (view) | unit |
## Order and writers
- **Order.** G1, then D0 (regenerate), then D1 to D6 (one contracts agent, one commit each). mesh-sdk's S1, S2, S3, S6,
S8, S11 (the mesh-sdk map) come before every user. Then R, B, I, A, F, T, V start from D's last commit. Within the
runner, R1 before R2; R2 before R3, R5, R8. Within the builder, B1 before B2, B4; B11 before I4. I1 and B12 land in one
commit pair read together (§802: one release). Merge order of the group: contracts and generator, then the indexer
and the builder (§802), the assigner after the node-engine's tolerant reading (§813 (1)'s edge, the node-engine's map),
then the runner, bridge, teller and view.
- **Ordering edges.** §813 (1): the node-engine that reads `run` tolerantly runs before the assigner writes it (an edge
of the module graph). §818: once the indexer and builder of §802 run, the recompute moves every module once, before
the proofs. §777's stream rebuild through `nats_recreate` runs before the new builder and assigner start (a live act on
the operator's warrant, not code).
- **One writer per file.** One agent per module directory: the contracts agent writes `modules/mesh-delivery-contracts`
and `modules/mesh-delivery-sdk/seatgen`; the runner agent `modules/mesh-delivery-pipeline`; the builder agent
`modules/mesh-delivery-builder` and `modules/mesh-delivery-sdk/buildrecord`; the indexer agent
`modules/mesh-delivery-indexer`; the assigner agent `modules/mesh-delivery-assigner`; one leaf agent the bridge, the
teller and the view. `modules/mesh-delivery-sdk/steprun/conformance` is the build modules' agent's (mesh-catalog map).
- **Not to touch.** `contracts/` and `sdk/` at the repository's root (no line names them).
## Local facts
- Worktree per playbook 07 item 2 under `.work/<slug>/mesh-delivery`, branch `feat/<slug>`; `TMPDIR` under the worktree.
- **Placement of the siblings**, as the Go build module places them (`mesh-catalog`
`modules/mesh-build-go/cmd/mesh-build-go/workspace.go:17-60`): a `go.work` that `use`s the module and, transitively,
every module it requires at the zero version `v0.0.0-00010101000000-000000000000`, each found by module path among the
sibling clones (`mesh-sdk`, `mesh-contracts`, `mesh-delivery`, `mesh-catalog`, `mesh-tools`, `mesh-host`,
`mesh-networking`), with `replace <path> v0.0.0-00010101000000-000000000000 => <dir>` for each. No agent writes another.
- Unit suite: `GOWORK=<that go.work> go test ./...` per module; integration compiled: `go vet -tags integration ./...`.
## Test budget (§819), by `go test -list '.*'` without and with `-tags integration`, top-level functions
Counted at this commit, 22:20 to 22:30 CET (unit / integration): runner 105 / 4; builder 167 / 18; indexer 167 / 6;
assigner 86 / 9; bridge 10 / 2; teller 50 / 5; view 84 / 8; `mesh-delivery-sdk` 149 / 12; `mesh-delivery-contracts` 47 / 0.
§819 names the indexer 170 / 6 and the assigner 87 / 9: the counts differ by 3 and 1 (DQ-14). Each module H2 changes ends
below its start.
@@ -1,71 +0,0 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H2
updated: 2026-11-21
---
# 47 H2 build map: `mesh-host` (the node-engine)
Read at `origin/main` `637cfb1fd044` (2026-11-21 20:48 UTC), from an archive of that commit. Design: hq `35ddd45e`.
DMC-n and DQ-n are the entries at the end of [H2-the-delivery-systems-owed-work](../H2-the-delivery-systems-owed-work.md).
## What exists today
Searches as run, from `mesh-host/`: `grep -rn "TOOL_ENV\|RuntimeToolEnv" --include='*.go' internal`;
`grep -rn "compose-candidate\|ComposeCandidate" --include='*.go' internal`; `grep -rn "comment" --include='*.go'
internal/firewall`; `grep -rln "engine_" --include='*.go' .`; `grep -rln "node-tools\|tool runner" --include='*.go'
internal`; the node-engine seat's verbs from `mesh-contracts` `seats/node-engine/seat.json`; live: `mesh_search`
"node-engine composition" (22:27 CET).
1. **What exists today.**
- The node-engine composes `MESH_TOOL_ENV`, each module's words by module, into the tool runner's process
(`internal/compositions/composed.go:296-336`, `internal/compose/composed.go:369-410`, `:476`); a module's settings
reach its own process as files the manifest names (`${config:<key>}`), and whether they reach its tools bundle's
words is not said in the code read (DMC-13).
- The verb `compose-candidate` answers within `candidateWithin` (`internal/selfcompose/candidate.go:44-49`,
`:101-104`); it takes no ask id and keeps no `taken`.
- The node-engine renders each opening as a ufw rule with the comment `Mark`: `mesh-host <id> <digest>`
(`internal/firewall/firewall.go:415-427`, `:782`), and recognises its own rules by that mark (`markedFor`, `:426`).
- The node-engine has no tools of its own: it serves the seat `node-engine`'s verbs (live: `ace/node-engine.composition`,
`.compose`, `.packages`, `.compose-candidate`, each also on g14, novox, shanks); no `engine_composition_diff`.
- The node-engine seat has no verb `converged` and no verb carries `timeout` (`mesh-contracts`
`seats/node-engine/seat.json`, 18 verbs, each `timeout` absent).
- The composition's value carries `run` as a string (`mesh-contracts` `go/seats/nodeengine/contract.go:1764`); the
generated decoders refuse unknown fields (9 places in that file).
- The tool runner is placed as a unit of the node-engine's composition (`internal/compose/input_held.go`,
`internal/link/engineseat.go`); no drain wait before the new one starts was found.
2. **What relies on each.** The mark `mesh-host <id> <digest>`: read by the node-engine's own reconciling
(`firewall.go:426`, `:452`, `:536-616`) and by the packet filter's holder reading `rules` (`mesh-catalog`
`modules/nftables/client.ts`). `MESH_TOOL_ENV`: read by the tool runner (`mesh-tools` `internal/launch`).
`compose-candidate`: asked by the assigner (`mesh-delivery` `compositioninputs.go:109`).
3. **Fates.** The mark's form against §813 (4)'s comment is DQ-11. New parts: `run` as the composition run's sequence
(§813 (1)), the setting `drain-bound` read by the node-engine (§813 (12)), the tool `engine_composition_diff` (§813 (3);
its place is DQ-12b).
## Rows
| line | files and functions | subtask | acceptance (cites) | test |
|---|---|---|---|---|
| §780 | the node-engine's readers of another part's values (`internal/link`, the generated `nodeengine` contract from `mesh-contracts`) | E1 tolerant reading | §780 unit (mesh-sdk) | unit |
| §775 | `internal/selfcompose/candidate.go` `ComposeCandidate`: take an ask once by its id (`taken`) | E2 compose-candidate once | a holder given the same ask id twice acts once (§775) | unit |
| §781 | `internal/compositions/composed.go:296-336`: a module's settings into its slice of `MESH_TOOL_ENV` | E3 settings to the tools program (waits DMC-13) | §781 unit (mesh-sdk) | unit |
| §813 (1) | the apply of a composition (`internal/apply`, `internal/compositions`): apply again only when a readable part differs and `run` is newer; journal names the run | E4 only a newer run (waits DQ-12) | unit (§813 (1)) | unit |
| §813 (3) | a composition diff by resource, environment by name, secrets masked | E5 composition diff (waits DQ-12b) | unit (§813 (3)) | unit |
| §813 (4) | `internal/firewall/firewall.go` `Mark`, `:782`: comment `derived <module> <listen> scope <any\|private-network\|local-network>` | E6 derived rule's scope (waits DQ-11) | unit (node-engine render) (§813 (4)) | unit |
| §813 (12) | the replacement of the tool runner's unit: wait `drain-bound` for the old to exit | E7 drain wait | the new tool runner starts only after the old exits or the bound passes (§813 (12)) | unit |
| §819 | the node-engine's tests | E8 shrink | the check's counts against the start | check |
## Order and writers
- E1 first (the edge of §813 (1): the node-engine reading `run` tolerantly runs before the assigner writes it); then E2 to
E7. E6 before `mesh-catalog` P1. One agent writes this repository.
## Local facts
- Placement as the `mesh-delivery` map says; `mesh-networking` is among the siblings.
## Test budget (§819)
1,715 unit and 11 integration top-level tests by `go test -list` (22:30 CET); §819 names 1,716 and 11 (DQ-14). Over the
budget of 500 unit: H2's change ends below 1,715.
@@ -1,82 +0,0 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H2
updated: 2026-11-21
---
# 47 H2 build map: `mesh-sdk`
Read at `origin/main` `bdc5cff0d63d` (2026-11-21 15:51 UTC), from an archive of that commit. Design: hq `35ddd45e`.
DMC-n and DQ-n are the entries at the end of [H2-the-delivery-systems-owed-work](../H2-the-delivery-systems-owed-work.md).
## What exists today
Searches as run, from `mesh-sdk/go/`: `grep -n -i "kept" process/call.go`; `sed -n 1,60p busretry/busretry.go`;
`grep -rn "\"refused\"\|ErrorKind" --include='*.go' .`; `grep -rn "func .*Setting" --include='*.go' .`;
`grep -rn "func .*Fingerprint" --include='*.go' .`; `grep -n "Fill\|StateFilled" buscalls/buscalls.go`;
`grep -rln "findings" --include='*.go' views`; `grep -rn "func (s KeptState)" state.go`.
1. **What exists today.**
- The kept call: `Conn.CallKept`, `CallKeptOn`, `CallKeptWhileOpen` (`process/call.go:54-104`) over
`busretry.DoRepeatable` and `DoKept` (`busretry/busretry.go:81`, `:116`), with process-wide `Bound` 30 s,
`FirstWait` 250 ms, `MostWait` 4 s (`busretry.go:29-33`), no jitter, no ask id, no per-caller bound, no journal line
per seat. No `taken` helper.
- No seat error answer in mesh-sdk: error kinds are each seat definition's own (`git`'s `ErrorKind`: `refused`,
`not-found`, `failed`, in `mesh-delivery`'s contracts).
- The bundle's state page: `KeptState.Page(after, maxBytes, budget)` (`state.go:120`), served by the tool runner's
`mesh/state.page` in key order after a key (the mesh-tools map).
- No settings reader: each module reads `${config:<key>}` files its manifest names (for example the runner's
`askbounds.go:20-35` in `mesh-delivery`); the tool runner hands each bundle its module's words from
`MESH_TOOL_ENV` (`catalogue/runtime.go:39-43`).
- The findings writer keeps the state `findings` and says three events (`views/writer.go:23-125`); its history stream
is each module's manifest entry, not the writer's.
- A state write answers its revision only (`state.go:177`, `:190`); `buscalls.Fill` and `StreamFilled` exist for a
`fill` call (`buscalls/buscalls.go:87-92`, `:255-260`), not in a write's answer.
- The seat list's bootstrap copy of `git` is `seatlist/bootstrap/git.json`, with its test copy
`seatlist/seatlisttest/seats/git.json`.
- No fingerprint function: the indexer holds the one (`mesh-delivery`
`modules/mesh-delivery-indexer/internal/fingerprint/fingerprint.go:1-5`, "left mesh-sdk").
- The seat generator is not here (`mesh-delivery` `modules/mesh-delivery-sdk/seatgen`).
- The test bus is `testbus` (`testbus/testbus.go:36`, `:58`); no setup bound from the environment.
2. **What relies on each.** Every caller of `CallKept*` (the `mesh-delivery` map lists them; also `mesh-host`
`internal/link/engineseat.go`, `mesh-tools` `cmd/node-tools/approvals.go`, `mesh-catalog` `modules/restic`,
`modules/mesh-recovery`); every test that sets `busretry.Waits` (`busretry.go:35-45`); every user of `KeptState.Page`
(`views/views.go`, `views/tools.go`, the assigner's `store_pages.go`, the builder's tools' `republish.go`).
3. **Fates.** Each stays and gains what its line names; no line removes a part here. New parts and their lines: the pace
settings `kept-call-pace-first`, `kept-call-pace-max` (§775), the state `taken` (§775, §820), the kind `away` (§776),
the cursor `next` and `seen-again` (§779), the settings reader in a bundle (§781), `state_prune_now`, `state_keep`
(§812), the catalog's `check-needs` (§800; DMC-6), `MESH_TOOL_ENV`'s settings (§781).
## Rows
| line | files and functions | subtask | acceptance (cites) | test |
|---|---|---|---|---|
| §775 | `busretry/busretry.go` (pace from settings, jitter 20 %, the caller's bound), `process/call.go` (ask id carried), journal line per seat at first fault then at most once a minute | S1 kept call paced | no responders twice then answered returns the answer and logs one line; past its bound returns every try; a refusal returns at once (§775) | unit |
| §775, §820 | a helper keeping the ids an owner took, state `taken`, key `<seat>.<ask>`, TTL the ask's bound | S2 take once | a holder given the same ask id twice acts once (§775) | unit |
| §776 | the seat error answer kind `away` with `part`, `words` (waits DMC-2) | S3 `away` | callers read `away` as a transport fault (§776) | unit |
| §779 | `state.go` `KeptState.Page`, `stdio.go` (`next` opaque, `seen-again`) | S4 page by cursor (with mesh-tools T1) | §779 whole (tool runner) | whole |
| §781 | a settings reader for a process and a bundle (waits DMC-13) | S6 settings in a bundle | a tools bundle reads a setting the manifest sets (§781) | unit |
| §782 | the wrappers around one bus handle (waits DQ-3) | S7 safe for concurrent use | concurrent gets, puts and watches through one wrapper under the race detector (§782) | unit, `-race` |
| §783 | `views/writer.go` (the writer's `requires`: events template, 8 MiB, `findings-max-age`) | S8 findings history drops its oldest (waits DQ-5) | §783 whole (runner) | whole |
| §800 | `testbus` and the test helpers: setup bound half of `MESH_TEST_LEVEL_BOUND`; `catalogue` field `check-needs` | S9 setup bound; S10 `check-needs` (waits DMC-6) | a starved setup runs again (§800) | unit |
| §812 | a prune helper judging the fill from the write's answer at `prune-mark` to `prune-target`, the generic tools `state_prune_now`, `state_keep` written in the hand-act log (waits DMC-14) | S11 prune helper and tools | a write past 70 % prunes to 50 %; a kept key survives (§812) | unit, whole (bridge) |
| §814 | `catalogue`: what the manifest validator needs to refuse an uncapped delivery store | S12 caps in the catalog | §814 unit (validator) | unit |
| §796 | `seatlist/bootstrap/git.json`, `seatlist/seatlisttest/seats/git.json` | S13 bootstrap copy of `git` (uses `mesh-delivery` D5) | the copy equals the contract | unit |
| §802 | "mesh-sdk's one fingerprint function": none here (DMC-5) | none until answered | | |
## Order and writers
- S1, S2, S3 first (the kept call and its errors); S4 with mesh-tools T1 in one pair; S6, S8, S11 before every module's
use. S13 after `mesh-delivery` D5. One agent writes this repository; the mesh-tools T1 agent reads S4's commit.
- Every module builds against the latest published mesh-sdk (ADR 0573 §2): the order between repositories is the
package edges; S1 to S13 are published once before their users' check.
## Local facts
- Placement: as the `mesh-delivery` map says. Unit suite `go test ./...` in `go/`; the TypeScript half (`src/`) with
`npm test`, untouched by these rows except S3 if its answer puts `away` in the TypeScript seat helpers (DQ-15).
## Test budget (§819)
`go/` holds 331 unit and 38 integration top-level tests by `go test -list` (22:30 CET).
@@ -1,49 +0,0 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H2
updated: 2026-11-21
---
# 47 H2 build map: `mesh-tools` (the tool runner and the mesh MCP server)
Read at `origin/main` `02675a43eaf8` (2026-11-21 18:13 UTC), from an archive of that commit. Design: hq `35ddd45e`.
DMC-n and DQ-n are the entries at the end of [H2-the-delivery-systems-owed-work](../H2-the-delivery-systems-owed-work.md).
## What exists today
Searches as run, from `mesh-tools/node-tools/`: `grep -n "StatePage" internal/bus/state.go`; `grep -rn "mesh/state.page"
--include='*.go' .`; `grep -rln "mesh_wait" --include='*.go' .`; `grep -rn "UseSeats\|seatlist\." --include='*.go' .`;
`grep -rn "SIGTERM\|Shutdown\|drain" --include='*.go' cmd internal`; `grep -rn "NakWithDelay" --include='*.go' internal`.
1. **What exists today.**
- `mesh/state.page` (`internal/launch/launch.go:493`) is `Conn.StatePage` (`internal/bus/state.go:231-300`): the
values in key order after `after`, each page reading every current value of the bucket again (`currentOf`), with
`Next` the last key given.
- `mesh_wait` (`internal/console/wait.go:60-140`) resolves `<seat>.<event>` against the seat list the tool runner reads
live (`cmd/node-tools/seatlist.go:49-65`, `catalogue.UseSeats`) and a module's manifest events
(`wait.go:195-262`); an undeclared event of a known seat is waited on and said undeclared at the time-out.
- A stop: `signal.NotifyContext` on SIGTERM (`cmd/node-tools/main.go:58`); bundles get SIGTERM with the group
(`internal/launch/launch.go:173-181`, `:728-735`); no drain of calls in flight, no `drain-bound`.
- A seat ask a bundle did not take is offered again after `WorkBackoff` (5 s doubling to 10 minutes,
`internal/bus/seat.go:71-79`, `:315`); a bundle's own delay is `seat_pull.go:193` `NakWithDelay(delay)`.
2. **What relies on each.** `StatePage`: every bundle's `KeptState.Page` (the mesh-sdk map lists its users).
`WorkBackoff`: every seat work queue a bundle pulls.
3. **Fates.** `StatePage`'s key order and per-page replay go (§779). New parts: `drain-bound` (§813 (12)).
## Rows
| line | files and functions | subtask | acceptance (cites) | test |
|---|---|---|---|---|
| §779 | `internal/bus/state.go` `StatePage` (an ordered consumer after the cursor's sequence, 768 KB, `next`, `seen-again`), `internal/launch/launch.go:493` | T1 page by cursor (with mesh-sdk S4) | 10,000 keys read in pages deliver each kept message once; a key written again mid-read is marked `seen-again` (§779) | whole (tool runner) |
| §813 (12) | `cmd/node-tools/main.go:58`, `internal/launch`, `internal/console`: take no new call after the stop, finish in flight within `drain-bound`, cut and say past it | T2 drain at stop | a stop during a 20 s call finishes it and refuses a call after the stop; a 40 s call is cut at 30 s and said (§813 (12)) | whole (tool runner) |
| §799 | `internal/bus/seat_pull.go:193`, `seat.go:315`: the delay a run ended `again` is settled with (waits DMC-7) | T3 again-delays | §799 (kit) | unit |
| §821 | `internal/console/wait.go`: nothing to build while the seat list carries each event (§821 is built in the contracts and holders) | none | a wait by seat and event name is answered (§821) | whole (each holder) |
## Order and writers
T1 with mesh-sdk S4 (one pair, the contract of the call first); T2 and T3 independent. One agent.
## Test budget (§819)
`node-tools` holds 160 unit and 9 integration top-level tests by `go test -list` (22:30 CET).
@@ -1,203 +0,0 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H2
updated: 2026-11-21
decisions:
- "ADR 0682"
---
# 47, milestone H2: the prepare's design questions and where design met code
The prepare's two lists for milestone H2's part of [design 47](../47-delivery-from-commit-to-delivered.md), moved here
from [H2-the-delivery-systems-owed-work](H2-the-delivery-systems-owed-work.md) to keep that file within its bound. Each
entry names the lead's answer (H-A-349, H-A-350), and the lines of the part now carry those answers; a builder reads
the lines, and this file only for where an answer came from.
## Design questions
Found by H2's prepare (`mesh-preparer`, 2026-11-21 22:40 CET), for the lead's answers (playbook 07, step 0b). The code was
read at `origin/main`: `mesh-delivery` `7e597a623eb2`, `mesh-catalog` `553bfb0ccf7c`, `mesh-host` `637cfb1fd044`,
`mesh-sdk` `bdc5cff0d63d`, `mesh-contracts` `87eab81be134`, `mesh-tools` `02675a43eaf8`, `mesh-networking`
`19a04dfc602a` (a sibling for the build). The build maps are in [H2-build-maps](H2-build-maps/). Each recommendation is
the preparer's, said as one.
- **DQ-1** (§777) The line names the accepted kinds `build` on `mesh-builds` and `validate` and `compose` on `mesh-wants`;
both seats accept one kind, `step`, today (`mesh-delivery` `seats/mesh-builds/seat.json`, `seats/mesh-wants/seat.json`
`accepts`; the runner puts every step on `accept.step`, `cmd/mesh-delivery-pipeline/asks.go:27`). Left to the builder:
whether the kinds are renamed and split. Recommendation: keep the one kind `step` on each seat and read the line's
kinds as the step the ask names, so no subject and no reader changes.
answered: H-A-349 DQ-1.
- **DQ-2** (§777) The line rebuilds the `mesh-builds` stream empty through `nats_recreate`; the `mesh-wants` stream
`SEAT_MESH_WANTS` holds 1,598 messages and 0 consumers as well (live, `nats.nats_streams`, 22:25 CET), and `mesh-builds`'
1,558 now. Left: the fate of `SEAT_MESH_WANTS`' messages. Recommendation: rebuild both empty on the same warrant, before
the new builder and the new assigner start.
answered: H-A-349 DQ-2.
- **DQ-3** (§782) The line names "mesh-sdk's wrappers around one bus handle" without naming them; mesh-sdk holds several
(`process.Conn`'s state and stream calls, `stdio`'s `BusState` through the runtime, `views`). Recommendation: name the
wrapper row 137 met twice, by package and type, in the line.
answered: H-A-349 DQ-3.
- **DQ-4** (§777, §778) The runner's second put under `AgainID` with its bound key `ask2.` serves the build seats today
(`internal/pipeline/asks.go:27-60`, `:134-160`); the line says the runner puts again only on a transport fault but gives
`AgainID` and `ask2.` no fate. Recommendation: both go for every seat, by §777's rule.
answered: H-A-349 DQ-4.
- **DQ-5** (§783, §820) Which delivery modules are foundation parts (ADR 0619 §1, ADR 0666 §4) that declare their stores
in the old section, and which ask in `requires` by template, is not said; today the runner, the builder, the indexer and
the assigner use the old sections (`mesh-delivery-pipeline/module.json:205-240`, `mesh-delivery-builder/module.json:120-140`)
and the bridge uses `requires` (`mesh-delivery-forge-bridge/module.json:40-45`). Recommendation: the line lists the
foundation parts by module.
answered: H-A-349 DQ-5.
- **DQ-6** (§793) The work queue `publishes` (§820: work queue, 64 MiB, 7 days) names its subject and consumers per
holder and class, but not whether the consumers are declared in the builder's `requires` or derived by the broker, and
the move's message id `<holder>.<module>.<version>` names no class while `builder_publish_first` puts an item again as
`live` within the duplicates window. Recommendation: the builder declares the stream and its consumers in `requires`,
and `builder_publish_first` puts under an id carrying the class.
answered: H-A-349 DQ-6.
- **DQ-7** (§808, H-A-345) The vault's seat serves no write of a module's own secret, and its read `own` answers only the
node-engine of a machine, sealed to the machine's key, so a forge module process can neither write nor read its token
through `own` (`mesh-contracts` `identity-and-access/seats/mesh-vault/seat.json`, verbs `own`, `get`, `licence-put`;
live `mesh-vault.own`'s description, 22:27 CET). The write verb is a gap of this milestone (H-A-345); the read is a gap
too. Recommendation: add to the vault's seat a two-step sealed write of a module's own secret modelled on `licence-put`
(the module named by the caller's account, its newest generation kept), and read the token through `get`, sealed to the
process's key; built in `mesh-catalog` `modules/mesh-vault` and `mesh-contracts`, before the forge module's §808 work.
answered: H-A-349 DQ-7.
- **DQ-8** (§802) A mesh Go package that no module the indexer holds has published enters the fingerprint by the commit the
gate's source names for its repository (`mesh-delivery` `internal/index/form.go:113-125`, design 47 G A-365), and the
import form's versions are a holding module's published commit (`form.go:30-33`); the line does not say what such a
package enters by under ADR 0499 §2. Recommendation: a package of the module's own repository enters by its directory's
tree, as a directory replace does already (`form.go:39-41`); another repository's unpublished package leaves the module
without a fingerprint until it is published, said as today's `NoPackageVersion`.
answered: H-A-349 DQ-8.
- **DQ-9** (§815) The source-only registration has no module, while the state `registrations` is keyed `<module>` and a
registration requires `module`, `origin`, `path` and `branches` (`seats/mesh-catalog/seat.json` `defs.Registration`); the
line names `repository` and one `branch`. Left: its key, its field names against `origin` and `branches`, and its history
key. Recommendation: key `source.<owner>.<name>` in the same states, fields `origin`, `branches` (one), `policy`,
`check`, so readers of registrations read one form.
answered: H-A-349 DQ-9.
- **DQ-10** (§814, §820) The seat list as one object "in the indexer's objects, by digest" is a store §820's table does not
hold: its objects entry, cap, key life and deleter. Recommendation: the indexer's objects `seat-lists`, 64 MiB, one object
per digest, the indexer deleting every object but the newest two at each new list.
answered: H-A-349 DQ-10.
- **DQ-11** (§813 (4)) The node-engine marks each rule it writes `mesh-host <id> <digest>` and recognises its own rules and
stale ones by that mark (`mesh-host` `internal/firewall/firewall.go:415-427`, `:782`); the line's comment
`derived <module> <listen> scope <…>` gives the mark no fate. Recommendation: the scope words follow the mark in the one
comment, so the reconciling keeps reading the mark.
answered: H-A-349 DQ-11.
- **DQ-12** (§813 (1)) "A composition key" is not named: the state and key the holder of `mesh-wants` writes by
compare-and-set (its `wants` `want.<node>.<module>`, `compositions` `<group>.<heads>`, or the node-engine's composed
bucket), and `run`'s form: the node-engine contract already carries `run` as a string (`mesh-contracts`
`go/seats/nodeengine/contract.go:1764`) while the line says a pipeline sequence. Recommendation: name the state and key,
and keep the existing field `run` holding the sequence as a decimal string, so no form is raised.
answered: H-A-349 DQ-12.
- **DQ-12b** (§813 (3)) `engine_composition_diff` is "the node-engine's tool", but the node-engine serves only the seat
`node-engine`'s verbs and has no tools bundle (`mesh-host`: no `engine_` tool name in any file; live `ace/node-engine.*`
are seat verbs). Recommendation: a read verb `composition-diff` on the seat `node-engine`, beside `composition`.
answered: H-A-349 DQ-12b.
- **DQ-13** (§821) "The re-pin's" event is not named, and the runner's seat declares none for a re-pin today
(`seats/mesh-pipeline-runner/seat.json` events). Recommendation: the line names it (`re-pinned`, carrying the pipeline,
the mover and the revision).
answered: H-A-349 DQ-13.
- **DQ-14** (§819) The starting counts by `go test -list` without and with `-tags integration` (top-level functions, 22:30
CET) differ from the line's: the indexer 167 unit and 6 integration (line: 170 and 6), the assigner 86 and 9 (87 and 9),
the node-engine 1,715 and 11 (1,716 and 11); the runner 105 and 4 and the builder 167 and 18 agree. By the tag the NFS
server module holds 0 integration and 51 unit, the package manager module 3 and 118, where the line's 51 and 121 are the
build node's counts, which take untagged tests in. Recommendation: each pull request's check gives the starting count
at its base, and the line keeps its figures as a guess said as one.
answered: H-A-349 DQ-14.
- **DQ-15** (§776) The forge module is TypeScript; the line places `away` in mesh-sdk's seat error answer without saying
whether mesh-sdk's TypeScript seat helpers carry it. Recommendation: they do, in the same commit.
answered: H-A-349 DQ-15.
- **DQ-16** (§810) `class` is `core` "when it moves a core module of ADR 0282 §1"; the gate holds no list or field naming a
module's class (`grep -rn -i "core\|class" --include='*.go' mesh-catalog/modules/mesh-delivery-gate/cmd` finds none).
Left: where the gate reads it. Recommendation: the gate reads it from a setting `core-modules` (a list, default the
delivery system's modules and the node-engine), so the self-check's probe and the gate read one list.
answered: H-A-349 DQ-16.
## Design meets code
Each entry: the design line, the code (at the commits named above), which of the three it is, and the preparer's
recommendation, said as one.
- **DMC-1** (§777) *A form the code cannot take.* The seat definition's `accepts` carries no `max-age`, `max-msgs`, ack wait,
in-progress, max ack pending, max deliveries or duplicates window; the streams and the shared worker are derived by the
grants part with their own values (ack wait 60 s, max deliver 5, retain 7 days; `mesh-delivery`
`modules/mesh-grants/internal/buscompose/derived.go:86-110`, `:343-358`), and mesh-sdk keeps a second `buscompose`
(`mesh-sdk` `go/buscompose/nats.go:96-98`). Live max age is 168 hours. Recommendation: the seat definition's accepts gain
these settings, read by the one derivation in mesh-sdk's `buscompose`, which the grants part takes.
answered: H-A-350 DMC-1.
- **DMC-2** (§776) *A part the line assumes built that is not.* mesh-sdk has no seat error answer: error kinds are each
seat's own (`git`'s `ErrorKind`: `refused`, `not-found`, `failed`, `seats/git/seat.json`; `mesh-catalog`
`modules/gitea/seat.ts:71`). Recommendation: add `away` to the error kinds of every seat the delivery parts call
(`git` first), and mesh-sdk's kept call reads `away` as a transport fault by the answer's `error-kind`.
answered: H-A-350 DMC-2.
- **DMC-3** (§796) *A form the code cannot take.* The `tags` answer is a list of strings (`seats/git/seat.json` `tags`);
`commit` per tag makes each item an object, a form raised (§780) for every reader (`mesh-delivery-builder`
`internal/versions/claim.go:213`, `mesh-sdk` `seatlist/bootstrap/git.json`). Recommendation: items become `{tag, commit}`
with the seat's `form` 2, read tolerantly by §780.
answered: H-A-350 DMC-3.
- **DMC-4** (§780) *A part placed where it is not.* The seat generator is `mesh-delivery`'s
`modules/mesh-delivery-sdk/seatgen`, not mesh-sdk's; mesh-sdk's `seatdef` reads definitions only. Recommendation: build the
tolerant decoders and the `form` check in `seatgen`, and regenerate every seat in `mesh-delivery` and `mesh-contracts`.
answered: H-A-350 DMC-4.
- **DMC-5** (§802) *A part placed where it is not, and a form already built.* The one fingerprint function is the
indexer's (`mesh-delivery-indexer/internal/fingerprint/fingerprint.go:1-5`: "the indexer's own, and nobody else's"; the
builder reads what the indexer writes), not mesh-sdk's; and its tree input is already the directory's tree or the named
paths (`internal/index/inputs.go:97-118`); the commit enters through DQ-8's packages. Recommendation: build §802 in the
indexer's `fingerprint` and `form.go`, the builder taking nothing new but the release in one group.
answered: H-A-350 DMC-5.
- **DMC-6** (§800) *A rule in code the line breaks.* `check-needs` is a marker file in a package's directory, kept "not a
manifest field" on purpose (`mesh-catalog` `modules/mesh-build-go/cmd/mesh-build-go/digest.go:59-66`), read by
`mesh-delivery-sdk` `steprun.AskNeeds`; the line makes it a manifest field of a Go artifact. Recommendation: the line
holds: the manifest field replaces the marker file, whose fate (it goes, its readers moved) the line states.
answered: H-A-350 DMC-6.
- **DMC-7** (§799) *A part placed where it is not.* The delay before a run ended `again` is offered again is the tool
runner's `WorkBackoff` (5 s doubling to 10 minutes, `mesh-tools` `internal/bus/seat.go:71-79`, `:315`) or a bundle's own
`NakWithDelay` (`seat_pull.go:193`); the line says "the tool runner settles the ask with a delay of 15 s ... 60 s", a
build module's setting, built in the kit and the build modules. Recommendation: the build module passes its
`again-delays` with its `again` (the bundle's delay), so the tool runner changes nothing; mesh-tools' T3 then drops.
answered: H-A-350 DMC-7.
- **DMC-8** (§786, §789, §816) *Parts assumed built that are not.* The runner has no tools `runner_show`, `runner_cancel`
or `runner_movers` (`mesh-delivery-pipeline/module.json`, 14 tools; the verbs `show` and `cancel` exist on the seat).
Recommendation: `runner_show` and `runner_movers` are built in R8 as the tools table says; §816's `runner_cancel` reads as
the seat verb `cancel`.
answered: H-A-350 DMC-8.
- **DMC-9** (§814) *A part placed where it is not.* The validate step and `causedProblems` are the assigner's
(`mesh-delivery-assigner/cmd/mesh-delivery-assigner/validatestep.go:124`, `:203-230`), which counts every problem of a
touched module and only new ones of the rest; the line builds the counting in the indexer and names
`indexer_validate_before`. Recommendation: change `causedProblems` in the assigner and name the tool
`assigner_validate_before`.
answered: H-A-350 DMC-9.
- **DMC-10** (§813 (7)) *A part named that is not.* No seat `artifact-store`: the sweep holds `mesh-artifact-sweep`
(`artifact-store-tools`), the registry `mesh-artifact-store` and `oci-artifact-registry` (`distribution`); the registry's
`list` takes `name`, not `module` (`seats/oci-artifact-registry/seat.json`). Recommendation: read "the seat
`mesh-artifact-sweep`'s holder", and `list` takes `module` beside `name`.
answered: H-A-350 DMC-10.
- **DMC-11** (§813 (5)) *A part assumed built that is not.* No tool `nats_consumers`: the bus module has `nats_consumer` (one)
and `nats_backlog` (`mesh-catalog` `modules/nats/module.json`). Recommendation: `nats_consumers` is a new tool listing
consumers with the two sorts.
answered: H-A-350 DMC-11.
- **DMC-12** (§781, §813 (4)) *Parts assumed built that are not.* The node-engine seat has no `converged` and no verb with
`timeout` ("built in H1" in the line; `mesh-contracts` `seats/node-engine/seat.json`); the packet filter's holder
(`nftables`, TypeScript) serves `rules`, `reload`, `remove` and has no `allow`, asks no `converged` and holds no named
10 s (`mesh-catalog` `modules/nftables/client.ts`, `tools/index.ts`). Recommendation: the line says whether H2 builds
`converged` with its `timeout` and `allow`, or the clauses about them leave H2.
answered: H-A-350 DMC-12.
- **DMC-13** (§781) *A part assumed built that is not.* mesh-sdk has no settings reader: each module reads its
`${config:<key>}` files by names of its own (`mesh-delivery-pipeline/cmd/mesh-delivery-pipeline/askbounds.go:20-35`).
Recommendation: a reader in mesh-sdk takes a setting by its key from the words the node-engine composes, in a process
and in a bundle alike, and the runner's own readers move to it.
answered: H-A-350 DMC-13.
- **DMC-14** (§812) *A part assumed built that is not.* A state write answers its revision only (`mesh-sdk` `go/state.go:177`,
`:190`; `mesh-tools` `internal/bus/state.go:425`), and a publish's acknowledgement carries the stream and sequence, no
fill. Recommendation: the runtime's write answer carries the entry's `Fill` (`buscalls.Fill` exists), which the prune
helper judges.
answered: H-A-350 DMC-14.
- **DMC-15** (§778) *A part assumed built that is not.* "Drops its ask through the seat's `drop`": `mesh-builds` (verbs
`reserved`, `published`) and `mesh-wants` declare no `drop`; only the build-step part has one. Recommendation: D1 adds a
`drop` act to both seats, its holder ending the ask as the build seats' `drop` does.
answered: H-A-350 DMC-15.
- **DMC-16** (§791, §801) *A form the code cannot take as written.* The build-step part already has `output` (the whole
answer in chunks by `ask` and `call`) and `current` (the steps, capacity, paused) in other forms
(`mesh-delivery-contracts/parts/build-step.json`). Recommendation: the line's forms replace them with the part's `form`
raised, the runner's tool their one reader.
answered: H-A-350 DMC-16.
@@ -1,210 +0,0 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H2
updated: 2026-11-21
decisions:
- "ADR 0683"
- "ADR 0682"
- "ADR 0668"
- "ADR 0664"
- "ADR 0619"
- "ADR 0596"
- "ADR 0595"
- "ADR 0571"
- "ADR 0304"
- "ADR 0282"
- "ADR 0259"
---
# 47, milestone H2: the forge bridge, the gate, the parts beyond the chain, the stores and the tools
The second file of milestone H2's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
[H2-the-delivery-systems-owed-work](H2-the-delivery-systems-owed-work.md), whose introduction holds for this file too,
and both are read whole. Lines are cited as "design 47 H2 §n" whichever file holds them.
### The forge bridge, the gate and the forge module
- §807 **An owed act failing on a part away stays owed.** (H-A-300 (1), (4), H-A-338 (5); row 177) The forge bridge
performs an owed act of the gate's stream `owed` as a kept call (§775) through transport faults and `away` until
`owed-away-bound` (a setting of the bridge, default 60 minutes), and only then says `owed.ended` with
`could-not-be-performed`, naming its tries. `bridge_owed_again` gains `record` (a delivery record's source revision)
to perform again every act of that record that ended could-not-be-performed; it is written in the hand-act log, and
each act performed again checks its preconditions again (the pull request still open, the note not yet written)
before it acts. Built in H2 in the bridge. How it is checked: whole (bridge): with the forge away for 60 s, a note act
owed in that minute is performed after it, with no hand act; an act whose pull request closed meanwhile is ended,
not performed.
- §808 **One process mints the forge token at a time, and the token is a secret.** (ADR 0596; H-A-300 (3), H-A-338
(1), H-A-339 (8), H-A-340 (4), H-A-344 (2), (10), H-A-349 DQ-7; row 177) The forge module's processes share one
admin token, kept where the module keeps its secrets, its own in the vault: written through the seat `mesh-vault`'s
new two-step sealed write `own-put` and read through its `get`, sealed to the reading process's key (§822), never
into another module's store or plain in a state, with the TTL `token-ttl` (a setting, default
24 hours). A process the forge refuses first reads the vault's token; it takes the lease and mints only when the
refused token is the vault's current one, else it uses the vault's newer token, so a refusal of a stale token mints
nothing. A process that mints creates the lease key `mint` in the module's state `token-lease` (§820; create only, TTL
`mint-lease`, a setting, default 60 s), mints, writes the token through `own-put`, deletes at the forge the token
it replaces, and deletes `mint`. A process that finds the lease taken waits for the token to change, at most the
lease; past it, the lease has expired and the waiter creates the lease itself. `forge_token_lease` reads the lease's
holder and since when and the token's age, never the token, which every read tool masks. Fate: each process's own
mint goes. Built in H2 in the forge module, after §822. How it is checked: unit (forge module): two processes, one
holding the old token, both refused, mint one token in all; whole: the forge holds one token for the account after; a minter killed while holding the lease is replaced after
`mint-lease`.
- §822 **The vault's seat takes a module's own secret in two sealed steps.** (ADR 0596; principle 12; H-A-345, H-A-349
DQ-7) The seat `mesh-vault` gains the act `own-put`, modelled on `licence-put`: its first call (`name`) answers a key
made for the call and a `call` id; its second (`call`, the value sealed to that key) stores the secret as the calling
module's own under `name`, the module named by the caller's account, never by an argument, keeping its newest
generation only. `get` answers that secret to a process of the same module, sealed to the process's key. The holder
says each write in its own journal without the value. Built in H2 in the vault (`mesh-catalog` `modules/mesh-vault`)
and the seat's definition (`mesh-contracts`), before the forge module's §808. How it is checked: whole (vault): a
module puts a secret in two steps and reads it back through `get`; a second module's `get` of that name is refused; a
second put keeps only the newer generation.
- §809 **The gate's ledger keeps one entry per module and revision.** (ADR 0595 §3; H-A-299 (1), H-A-338 (10), H-A-340
(3), H-A-341 (3); row 176) The gate's ledger `records` (§820) writes one head entry per delivery record,
`<branch>.<source>` (its outcome, the count of its movers and the times of §810), and one entry per mover,
`<branch>.<source>.<module>` (its pipeline, version, machines and their `running` times); no entry names two modules.
The gate refuses an entry over 64 KiB with the finding `record-too-large` (scope delivery), cleared when that entry is
next written within 64 KiB or at the record's end. The ledger is never pruned; as a kept ledger it refuses when full
(ADR 0595 §3), and the bus module's fill condition speaks for it. `gate_record` and `gate_records` join the entries.
Fate: the whole-revision entry goes; the two records refused on 2026-11-21 are not written again. Built in H2 in the
gate (mesh-catalog). How it is checked: whole (gate): a record of 126 movers writes 127 entries, none over 64 KiB,
its head counting 126; an entry made too large raises `record-too-large`, and the record's end clears it.
- §810 **A delivery record keeps its delivery time; the self-check judges it against its budget.** (ADR 0282 §1, §6,
§7; ADR 0304; H-A-341 (1), H-A-349 DQ-16; row 111) At its end the gate writes on the head entry `delivery-time` (from `merge-called`
to the last `running` of its movers on every present placing machine), `class` (`core` when it moves a module whose
manifest's `class` field, carried by the indexer in its catalog entry, says `core`, else `leaf`; a module with no
class is a leaf; the gate keeps no list of its own) and the phases of §785. `gate_times` answers each class's budget, the last seven days'
median and worst, and every delivery over its budget with its longest phase (ADR 0282 §6's `times`), the budgets
being the gate's settings `budget-core` (default 10 minutes, ADR 0282) and `budget-leaf` (default 3 minutes, ADR
0304). As ADR 0282 §7 has it, the self-check's probe (the seat `mesh-self-check`) reads the gate's times and raises
`over-budget` with the class as its id, naming the source revision and its longest phase; the next delivery of that
class within its budget clears it; the gate raises nothing. Built in H2 in the gate and the self-check's probe. How it
is checked: whole (gate and probe): a core record ended 11 minutes after its `merge-called` raises `over-budget` for
the class `core`; the next core record within ten minutes clears it.
- §811 **Every read filters before it sizes.** (H-A-299 (3); row 176) Every read verb and read tool of a delivery
module applies its filters while it reads and answers at most 768 KB with `capped`, `total` and the cursor of §779,
never "too big": among them the gate's `deliveries` (filters `repository`, `module`, `outcome`, `since`) and the
bridge's `bridge_owed` by pull request (reading only that pull request's keys, in the bridge's process). How it is
checked: the tools table of each pull request (principle 4); unit (gate): `deliveries` by repository over 4 MB of
records answers under 768 KB.
- §812 **Every kept store has a cap its owner prunes toward, judged at its own writes.** (ADR 0595 §3, §5, §6; H-A-227,
H-A-299 (2), H-A-338 (10), H-A-339 (2), (8), H-A-340 (3), H-A-341 (2); rows 103, 176) Every state, log and objects
entry a delivery module asks for names its cap. At each write it makes to such an entry, its owner judges the entry's
fill from the figures the write's own answer gives (H-A-227, H-A-344 (7)), with no extra read, no poll and no timer, and when the fill passes `prune-mark` (a
setting, default 70 %, below the bus module's raise mark of 75 %) prunes it, oldest first, down to `prune-target`
(default 50 %), one journal line per prune. Ledgers, the hand-act log, `taken`, `unfinished`, `token-lease` and every state whose
deleter §820 names other than the prune are never pruned; such a store refuses when full, said in its owner's
journal (H-A-344 (1)). mesh-sdk's generic state
tools gain `state_prune_now` (entry, why: prunes to the target now) and `state_keep` (entry, key, until, why: a key
never pruned before its until), both written in the hand-act log; the fill is read and the limits applied through
the seat `mesh-broker`'s `list`, `show` and `apply`. First the bridge's state `performed` (full on 2026-11-21), which
also drops entries older than `performed-keep` (default 3 days). A forge tool, `forge_merged` (repository, from, to),
lists merged pull requests by number with merge commit, time and whether a merge call made it (row 103). Built in H2
in mesh-sdk (the prune helper and the tools), every delivery module and the forge module. How it is checked: the
manifest check of §814; whole (bridge): a write that takes `performed` past 70 % prunes it to 50 %; a key under
`state_keep` survives the prune.
### The assigner, the node-engine, the tool runner, the bus module, the registry and the teller
- §813 **The parts this milestone touches beyond the chain.** (each clause names its source)
1. *One writer per composition key, and the engine applies only a newer write* (H-A-302 (1) to (3), H-A-303,
H-A-306, H-A-338 (8), H-A-349 DQ-12; row 179): the composition key is the holder of `mesh-wants`' state
`compositions`, key `<group>.<heads>`; its write carries the node-engine contract's existing field `run`, a string
holding the composition run's pipeline sequence in decimal, so no form is raised, and the holder writes by
compare-and-set refusing a lower `run`; a run whose pipeline ended writes
nothing more; the node-engine applies a composition again only when a part it could read differs and its `run` is
newer than the one it applied, naming the run in its journal. The order is an edge of the module graph the delivery
derives (the composition value's form): the node-engine that reads `run` tolerantly (§780) runs before the
assigner writes it. Built in the assigner and the node-engine. Checked: unit (each).
2. *A failed keeping runs again* (row 137): a keeping of the assignment graph revisions that fails marks itself
wanted and runs again after `keeping-retry` (a setting, default 30 s, the holder's own deadline, ADR 0682 §11),
raising `keeping-failed` (scope module) at the third failure in a row, cleared at the next that succeeds;
`assigner_keep_now` (why) runs the keeping at once, written in the hand-act log (H-A-344 (4)). Checked: unit.
3. *Composed values read by resource* (H-A-306 (4), H-A-349 DQ-12b; row 181): the seat `node-engine` gains the
read verb `composition-diff` beside `composition` (the node-engine serves seat verbs and has no tools bundle):
given a module and a revision or digest, it answers, per resource, the entries that differ between the running composition
and the other, environment entries by name with secret values masked. Checked: unit.
4. *The render marks a derived rule's scope* (ADR 0683; H-A-319, H-A-349 DQ-11, H-A-350 DMC-12; row 188): the
node-engine keeps its mark `mesh-host <id> <digest>` on each rule it writes, by which it reconciles its own and
stale rules, and on each derived accept rule of the packet filter the scope words follow the mark in the one
comment, `derived <module> <listen> scope <any|private-network|local-network>`;
the holder of `node-packet-filter` reads a port's scope from `rules`, not from the rule's shape. The holder's `allow`
and `rules` are the packet filter group's, on main (ADR 0683); H2 adds only the scope words and their reading. Checked: unit
(node-engine render); whole (packet filter): `allow` without a source is refused for a `private-network` port.
5. *The bus module's tools read flow* (row 124; H-A-350 DMC-11): `nats_consumers`, a new tool beside the existing
`nats_consumer` (one consumer) and `nats_backlog`, lists consumers and sorts by `delivered-rate` (messages a second
measured over `rate-window`, an argument, default 10 s, within the one call) and by creation time;
`nats_connections` answers a connection's busiest subscriptions by messages. Checked: unit.
6. *The keeper withdraws a refused request's ask* (row 123): a drop or rebuild request the keeper refuses at once
cancels its ask on the seat `operator-channel` in the same pass (ADR 0259 §3's cancel). Checked: unit.
7. *The registry's list is paged, and it takes the sweep's removals* (ADR 0571 §2; ADR 0682 §10; H-A-250 (3), H-A-350
DMC-10; row 125): the seat `oci-artifact-registry`'s `list` takes `module` beside `name` and the cursor of §779 and
answers at most 768 KB; the sweep, holder of the seat `mesh-artifact-sweep`, reads it page by page once per pass;
the registry takes a removal from that seat's holder, and its refusal "not the sweep's" goes (every account may call every verb). Checked:
whole (sweep): a pass over 20,000 artifacts removes what it judges.
8. *The registry drops a deleted chunk's leftovers* (H-A-227): when it deletes chunks it purges their subjects from
the object store, so a store's kept descriptions equal its live objects. Checked: whole (registry): after 1,000
chunks are deleted, the store's messages equal its live objects.
9. *The usage view judges a build module by its running asks* (row 138): the status view reads a build module's
work from its seat's `current` (§801), not from the node-engine's held phase. Checked: unit (view).
10. *The teller's ask-again for want of room goes* (ADR 0682 §14; H-A-295): with A-424, the teller's ask-again for an
ask refused for room and its test are removed. Checked: the teller's suite holds no such test.
11. *The destroy-level answer's channel waits for its research* (ADR 0259; H-A-237, H-A-334 (2); row 114): the
bus module's keeper asks its drop and rebuild warrants at the approve level, as H-A-237 bends it, until a research
effort designs the channel that carries the destroy proof; H2 builds no such channel, and the bend's line in the
keeper's code names that research as its end. Checked: unit (keeper): a drop asks at the approve level.
12. *The tool runner drains at a stop* (H-A-342 (2); row 179): once told to stop, the tool runner takes no new call,
finishes the calls in flight within `drain-bound` (a setting, default 30 s), then exits; a call that outlives the
bound is cut, with a journal line naming the bundle, the verb and the call's age, and its caller sees a transport
fault. The node-engine, replacing the tool runner, waits the drain bound for the old one to exit before it starts
the new one. Built in the tool runner (mesh-tools) and the node-engine. Checked: whole (tool runner): a stop during a
20-second call finishes it and refuses a call made after the stop; a 40-second call is cut at 30 s and said; unit
(node-engine): the new tool runner starts only after the old one exits or the bound passes.
### The new stores
- §820 **Every store this part adds names its form, cap, key life and deleter.** (ADR 0595 §2, §3; H-A-338 (6),
H-A-339 (7), H-A-341 (7)) Each is asked for in its owner's `requires` by its template; a foundation part (ADR 0619 §1, ADR 0666 §4) declares
each of its stores (`unfinished`, `publishes`, `taken`, `dry-runs`, the findings stream) in its old section with the
same cap and life (H-A-229, H-A-344 (3)). A put refused because a store
or queue is full is said in the owner's journal and asked again at the kept-call pace (§775).
| store | owner | template | cap | life of a key | deleted by |
|---|---|---|---|---|---|
| `taken` | every holder of a kept call (§775) | state | 8 MiB | the ask's bound (TTL) | the TTL |
| asks of `mesh-builds` and `mesh-wants` | the broker, from the seats (§777) | work queue | 10,000 messages | 1 day | the holder's acknowledgement |
| `unfinished` | pipeline runner (§786) | state | 8 MiB | none | the runner, or `runner_unfinished_drop` |
| `outputs`, install archives included | each build module, their owner (§791, §800) | objects | 1 GiB | 7 days (the store's max-age) | the bus, at the max-age; no sweep |
| the findings stream | every module (§783) | events | 8 MiB | 7 days | the bus, oldest first |
| `publishes` | builder (§793) | work queue | 64 MiB | 7 days | the builder's acknowledgement or termination |
| `token-lease` | forge module (§808) | state | 1 MiB | `mint-lease` (TTL) | the minter, or the TTL |
| `dry-runs` | indexer (§804) | state | 16 MiB | 1 hour (TTL) | the indexer at the answer and at its start |
| `records` | gate (§809) | ledger | 1 GiB | none | never |
| `seat-lists` | indexer (§814) | objects | 64 MiB | one object per digest | the indexer, every object but the newest two at each new list |
How it is checked: the manifest check of §814 refuses each without its cap; each owner's whole test fills its store
to the mark and reads the prune or the refusal said.
### The tools this part adds
| tool | module | reads or steers | line |
|---|---|---|---|
| `builder_asks`, `builder_ask_drop`; `assigner_asks`, `assigner_ask_drop` | builder; assigner | what waits on and is taken from the seats' queues; one ask ended | §777 |
| `assigner_keep_now` | assigner | the keeping of the graph's revisions, now | §813 (2) |
| `runner_unfinished`, `runner_unfinished_drop`, `runner_unfinished_place` | pipeline runner | the movers put in a pipeline again; one placed now | §786 |
| `runner_health` (`registrations-read`) | pipeline runner | whether the registrations view is read | §788 |
| `runner_show`, `runner_movers` (both new; the seat verb `show` gains the filters) | pipeline runner | one pipeline in parts | §789 |
| `runner_step_output` and the build seats' `output` | pipeline runner, build modules | a step's output | §791 |
| `builder_publish_queue`, `builder_publish_drop`, `builder_publish_first` | builder | the publish queue | §793 |
| `builder_unbuildable` | builder | the plans no seat builds | §795 |
| `build_current` and the build seats' `current` | builder, build modules | what each holder takes and runs | §801 |
| `indexer_dry_runs` | indexer | the dry runs' scratch state | §804 |
| `indexer_registrations` | indexer | the registrations | §806 |
| `bridge_owed_again` (`record`) | forge bridge | every owed act of a record again | §807 |
| `forge_token_lease` | forge module | the token lease and the token's age | §808 |
| `gate_times` | gate | delivery times against their budgets | §810 |
| `state_prune_now`, `state_keep` | mesh-sdk, every module | prune now; keep a key from the prune | §812 |
| `forge_merged` | forge module | merged pull requests by number | §812 |
| the seat `node-engine`'s `composition-diff` | node-engine | composed values by resource | §813 (3) |
| `nats_consumers` (new), `nats_connections` (sorts) | bus module | flow per consumer and connection | §813 (5) |
| `seat-list` | indexer (seat `mesh-catalog`) | the seat list as one object | §814 |
| `assigner_validate_before` | assigner | the before case's problems validate did not count | §814 |
@@ -1,463 +0,0 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H2
updated: 2026-11-21
decisions:
- "ADR 0683"
- "ADR 0682"
- "ADR 0668"
- "ADR 0666"
- "ADR 0664"
- "ADR 0619"
- "ADR 0596"
- "ADR 0595"
- "ADR 0573"
- "ADR 0571"
- "ADR 0548"
- "ADR 0527"
- "ADR 0525"
- "ADR 0499"
- "ADR 0436"
- "ADR 0304"
- "ADR 0282"
- "ADR 0267"
---
# 47, milestone H2: the delivery system's owed work, as design lines
Milestone H2's part of [design 47](../47-delivery-from-commit-to-delivered.md), read whole by its builders with its
second file, [H2-stores-and-tools](H2-stores-and-tools.md) (the forge bridge, the gate and the forge module, the vault's
seat, the parts beyond the chain, the new stores and the tools); the prepare's questions and where design met code are
in [H2-prepare-questions](H2-prepare-questions.md), with the build maps in [H2-build-maps](H2-build-maps/). Milestone H1 (the clean state and the one chain,
[H-deliver-the-delivery-system](H-deliver-the-delivery-system.md)) ended at 19:31 on 2026-11-21 with both its proofs
shown; what its live run met and did not build is owed here: every item the lead's answers H-A-227 to H-A-331
([H-lead-answers](H-lead-answers.md)) name as owed to H2, every *Owed* of rows 103 to 199 of the plan's section 10,
and the answers to the four reviews by architectural domain (H-A-338 to H-A-341). The lines are numbered after
milestone H's §774 and cited as "design 47 H2 §n". Where an H2 line and an H line or a lead's answer differ, the H2
line holds. Every module named builds against the latest published mesh packages (ADR 0573 §2), so the order between
repositories is the module graph's (the package edges), not this part's. The records each line follows are named in
it; a choice within them that no record or answer made is this part's own, given with its reason. A line that changes
a shared form (a seat's definition, mesh-sdk's catalog) rebuilds every module that imports it, once, in H2's one
pipeline of every module (§818).
H2 is one release of playbook 07: prepared by `mesh-preparer`, built, reviewed once, checked once, and delivered by
its own pipelines, with no hand pack (section 7 of the plan). Its two proofs (§816, §817) close it.
### The asks between the delivery parts
- §775 **Every ask of a delivery part to a seat is a kept call, paced.** (ADR 0668 §1 to §3, §7; ADR 0664 §1; H-A-296,
H-A-300 (1), H-A-338 (6), H-A-339 (4), H-A-340 (2); rows 170, 177) The pipeline runner's asks (build, lint, unit,
integration, validate, composition, install and the seat `mesh-builds`' `published`), the holder of the seat
`mesh-wants`' `compose-candidate` asks to each node-engine, the forge bridge's owed acts on the seat `git` and the
builder's publish asks to the registry seats are made through mesh-sdk's kept-call form, marked safe to repeat: each
carries its ask id, and every holder takes an ask once by its id (ADR 0668 §2), keeping the ids it took in its own
state `taken`, key `<seat>.<ask>`, TTL the ask's bound (§820): the builder, the holder of `mesh-wants`, every
node-engine for `compose-candidate`, the forge module for the seat `git`'s verbs and each registry for its publish.
On a transport fault (ADR 0664 §1's classes, a call's own deadline, and the kind `away` of §776) the form calls
again after `kept-call-pace-first` (default 1 s), doubling to at most `kept-call-pace-max` (default 30 s), each wait
drawn within 20 % of its value so many callers do not call in step: settings every module using the form declares
with these defaults (principle 11), chosen so a holder between two lives (a restart takes 20 to 50 s, row 179) is
met within one minute without a call a second. It writes one journal line per seat at the first fault and then at
most once a minute, naming the seat, the verb, the asks waiting and the count of calls; it stops at the caller's
bound: the runner's `ask-unanswered-bound` (H-A-238, default 10 minutes), the holder's `compose-ask-bound` (a
setting, default 10 s), the bridge's `owed-away-bound` (§807). Past the bound the step ends could-not-run, or the act
could-not-be-performed, naming every call's time and words; `call-unanswered` is written at five minutes as ADR 0668
§3 has it. A refusal of what was asked ends at once, as today. Fate: the runner's and the holder's one-shot asks,
which ended a step at the first "no responders", go. Built in H2 in mesh-sdk (the pace, the `taken` state), the
pipeline runner, the assigner, the forge bridge and the builder (mesh-delivery), the node-engine, the forge module
and the registries. How it is checked: unit (mesh-sdk): a call met by no responders twice and then answered returns
the answer and logs one line; a call past its bound returns every try; a refusal returns at once; a holder given the
same ask id twice acts once. Whole (runner): a composition ask whose holder is away for 40 s passes its step with no
hand act.
- §776 **A holder says `away` when a part it depends on is away.** (ADR 0668 §1 and ADR 0664 §1 (insights of
2026-11-21, accepted); H-A-300 (2), H-A-301, H-A-334 (3), H-A-339 (5); rows 177, 178) Each seat the delivery parts call
gains the error kind `away` among its own error kinds, the seat `git` first, with `part` (what did not answer) and
`words`; mesh-sdk's kept call, in Go and in its TypeScript helpers alike, reads `away` from the answer's `error-kind`
as a transport fault, and the conformance kit of each seat tests it (H-A-349 DQ-15, H-A-350 DMC-2). The forge module, holder of the seat `git`,
answers `away` when the forge answers 401, 502 or 503 or a connection fault and the forge's own unauthenticated
version read fails or names its store unavailable; it answers `refused`, "the forge refuses the mesh's admin
account", only when that read succeeds and a freshly minted token (§808) is refused too, and it never words a refusal
as an account to create. Every caller reads `away` as a transport fault (§775). This adds one class, a holder's own
word that what it depends on is away, to the classes ADR 0664 §1 and ADR 0668 §1 list; the line rests on those two
insights, accepted on 2026-11-21. Built in H2 in the seats' definitions, mesh-sdk (Go and TypeScript) and the forge module
(mesh-catalog). How it is checked: unit (forge module): a 401 with the version read failing answers `away`; a 401
with the read passing and the fresh token refused answers `refused`. Whole (forge module): with the store stopped for
30 s, a merge call in that window answers `away` and lands when called again.
- §777 **The seats `mesh-builds` and `mesh-wants` take their asks from a work queue and say `ask-taken`.** (ADR 0525
§1, §2, §6; ADR 0436 §6; ADR 0664 §2; H-A-241, H-A-243 (1), (2), H-A-320 (2), H-A-338 (4), (7), H-A-339 (7), (8),
H-A-340 (1), H-A-341 (4), H-A-349 DQ-1, DQ-2, DQ-4, H-A-350 DMC-1; rows 118, 130, 189) Each seat keeps its one
accepted kind `step` (the step the ask names tells build, validate and compose apart), declared in its definition
(the delivery repository's contracts module) as a work-queue stream the broker derives, as ADR 0525 §2 has it for
the build seats. The definition's `accepts` gains the stream's and consumer's settings: `max-age` 1 day, `max-msgs`
10,000, one shared worker consumer its holder pulls, ack wait 60 s, in-progress every 20 s, max ack pending 1,000,
max deliveries 5 (above ADR 0664 §2's three) and a duplicates window of 2 minutes (ADR 0436 §6); they are derived
once, by mesh-sdk's `buscompose`, which the grants part takes, and the grants part's own copy of that derivation
(its `buscompose` with its own values) goes. The holder pulls every
ask waiting at once, never one at a time, acknowledges an ask when it says the ask's end, sends in-progress while it
works (ADR 0525 §6), and says `ask-taken` on the seat's family at the pull, subject `<seat>.ask-taken.<ask>`,
carrying `ask`, `node` and `at`; the definition declares `ask-taken`, so only the seat's holder publishes it. The
runner consumes both seats' `ask-taken`. An ask put while its holder is down waits on the stream. The runner puts an
ask again only when its put met a transport fault, under the same id; its second put under `AgainID` and the bound
keys `ask2.<seat>.<ask>` go, for every seat; a put refused by a full stream is said in the journal and asked
again at the kept-call pace (§775). `builder_asks` and `assigner_asks` read what waits and what is taken on their
seat's stream; `builder_ask_drop` and `assigner_ask_drop` (ask, why) end one ask, written in the hand-act log. Fate:
the holders' plain subscriptions go; the runner's putting again of every open ask on the holder's `running`
(H-A-243 (1)) goes; `ask-silent-bound` and its bound key (H-A-243 (2)) go; the mesh-builds and mesh-wants streams, which no consumer
took (1,558 and 1,598 asks on 2026-11-21), are rebuilt empty through the bus module's tool `nats_recreate`, on one
warrant of the operator (ADR 0595 §5), before the new builder and the new assigner start, so neither carries a
message.
Built in H2 in mesh-delivery (the contracts module, the builder, the assigner, the runner). How it is checked: whole
(builder): a build ask put while the builder is stopped is taken and ended after its start; whole (assigner): the
same for a validate ask; after a pipeline's end the streams' consumers hold 0 pending; unit (runner): a put refused
for a full stream is said and asked again.
- §778 **The unanswered bound counts from the pull.** (H-A-238 (5), H-A-320 (4), H-A-340 (1), H-A-341 (4); ADR 0664
§4; row 189) The runner keeps on each step of its record `asked-at` (when the ask is put) and `taken-at` (from the
seat's `ask-taken`), RFC 3339. The bound key `ask.<seat>.<ask>` is armed at `ask-taken` with the bound less the time
since `taken-at`, and again at every start for every open ask, so a restart never grants a fresh bound; an ask whose
time is spent at a start ends could-not-run at once. A step ended by its bound drops its ask through the seat's
`drop`, an act both seats gain (H-A-350 DMC-15), whose holder ends the ask as the build seats' `drop` does (ADR 0664
§4), so no holder works on it after. An ask not yet taken:
the runner's health names a step whose ask is untaken past `stalled-bound` (§790), and an ask still untaken
`ask-unanswered-bound` after its `asked-at` ends the step could-not-run "its ask was not taken: <seat>'s holder takes
none", so no slot is held without end (H-A-344 (6)). Built in H2 in the runner. How it is checked: unit (runner): an
ask taken 9 minutes before a restart, with a 10-minute bound, ends one minute after the start and is dropped; an ask
untaken for `stalled-bound` is named by the health; an ask untaken for the whole bound ends could-not-run naming the
holder as not taking.
### mesh-sdk: the shared forms
- §779 **A page read continues from an opaque cursor in sequence order.** (H-A-254, H-A-255 (2), H-A-292, H-A-293;
row 129) The state page read that the tool runner serves (`mesh/state.page`) reads a state's keys in sequence order
from an ordered consumer starting after the cursor's sequence, never a replay of the bucket per page. The cursor is
an opaque string the caller hands back (`next`, empty at the end); a page holds at most 768 KB, and a key written
again between two pages comes again in a later page with `seen-again` set, so a reader knows it. Every reader of a
large state may page; H-A-292's and H-A-293's one-page exception ends. Built in H2 in mesh-sdk (the call's contract
and client) and the tool runner (mesh-tools), and its callers in the same group. How it is checked: whole (tool
runner): a state of 10,000 keys read in pages delivers each kept message once across all pages; a key written again
mid-read is marked `seen-again`.
- §780 **A reader of another part's value decodes it tolerantly and says its form.** (H-A-309, H-A-338 (8), H-A-341
(6); row 183) Every seat value, event body and verb answer gains `form`, an integer the seat's definition raises at
every field added or removed; `form` is left out while it is 1, and an absent `form` reads as 1. mesh-sdk's
generated decoders for reading another part's value, event or answer keep unknown fields, never refuse them, and
return `form`; a tool whose record's `form` differs from the one it was built with says "form N, this reader knows M"
in its answer. A writer still validates its own value strictly before it writes. Fate: the runner's dropping of
`kept-revisions` before the seat's decode (row 190) goes. Built in H2 in the seat generator, mesh-delivery's
`modules/mesh-delivery-sdk/seatgen` (H-A-350 DMC-4), and every seat definition of mesh-delivery and mesh-contracts
(a regeneration). How it is checked: unit (mesh-sdk): a value, an event and an
answer with an unknown field decode and return their form; an absent `form` reads as 1; the seat generator's check
fails a definition whose fields changed with `form` unchanged.
- §781 **A tools program reads its module's settings.** (H-A-322, H-A-330, H-A-350 DMC-12, DMC-13; rows 190, 199)
The node-engine composes a module's settings into the module's slice of the tool runner's `MESH_TOOL_ENV` in the
same files it composes for the module's process. mesh-sdk gains one settings reader, which takes a setting by its key
from the words the node-engine composes, in a process and in a bundle alike; the runner's own readers of its
`${config:<key>}` files move to it. A bound one module keeps on another's verb is that verb's `timeout` in its seat
definition, read by the caller from the seat list: the node-engine seat's `converged` with its `timeout` and the
packet filter's `allow` are the packet filter group's (ADR 0683), on main since 2026-11-21; H2 builds none of them
and reads them from main, and the holder's named 10 s goes once it reads `converged`'s `timeout`. Built in H2 in the
node-engine (`mesh-host`), mesh-sdk, the runner and the packet filter module. How it is checked: unit (mesh-sdk): a
process and a tools bundle read the same setting the manifest sets; whole (runner): §790.
- §782 **The bus wrappers are safe for concurrent use.** (row 137, met twice; H-A-349 DQ-3) mesh-sdk's wrappers
around one bus handle, `process.Conn` (its state and stream calls), `stdio.BusState` (through the runtime) and the
`views` reader, guard each call the client does not allow at once with a lock inside the wrapper, so no module needs a
handle per goroutine (one place, principle 7). Built in H2 in mesh-sdk. How it is checked: unit under the race
detector: concurrent gets, puts and watches through one wrapper.
- §783 **A module's findings history drops its oldest.** (ADR 0595 §2, §3; H-A-227, H-A-344 (3), (5); row 104) The
stream a module's findings writer appends to (three stood full on 2026-11-21: the runner's, the builder's, the
node-engine's) is asked for by the events template, which drops the oldest when full, with `max-bytes` 8 MiB and
`findings-max-age` (default 7 days); a foundation part (ADR 0619 §1, ADR 0666 §4; the list is
§814's) declares it in its old section with the same cap and life (H-A-229). Its fill is read through the seat `mesh-broker`'s `show`. The findings state itself is unchanged. Built in H2 in mesh-sdk (the
writer's requires) and every delivery module's manifest. How it is checked: whole (runner): 10,000 findings written
past the cap refuse none.
### The pipeline runner (seat `mesh-pipeline-runner`; mesh-delivery-pipeline)
- §784 **An ask placed and a step's end are journal lines.** (H-A-320 (1), H-A-333, H-A-341 (5); row 189) The runner
writes one line when it places an ask, "`<pipeline>` `<mover>` `<step>` asked on `<seat>`", and one when a step ends,
"step ended `<pipeline>` `<mover>` `<step>` `<outcome>` in `<duration>`", the latter in the one place that says
`step-ended`, so every end writes it: the unanswered bound's, the end at placing, a supersede, a re-pin, the
approval's end, the start pass and the verbs that end a step. Beside these two lines per step only the per-mover wait
lines (H-A-326 (3), §787) and §775's fault lines are written. Built in H2. How it is checked: unit: each way a step
ends writes exactly that line once.
- §785 **`pipeline-ended` carries the pipeline's phases.** (ADR 0282 §1, §6; row 111) `pipeline-ended` gains
`phases`: `taken` (the take-in), `placed`, `ended`, and for each step kind (build, lint, unit, integration, validate,
composition) the earliest start and the latest end across its movers, RFC 3339. Each mover's own step times stay in
the step log, read with `runner_show` (§789). Built in H2 in the runner and the seat's definition. How it is checked:
unit: a pipeline of two movers ends with each step kind's span; the gate reads it (§810).
- §786 **A mover left unfinished by another's failure is put in a pipeline again.** (ADR 0682 §6; H-A-339 (7), (8);
rows 133, 147, 162, 167) When a pipeline ends `failed`, `cancelled` or `could-not-run`, each mover whose own required
steps all passed or never ran, and whose fingerprint no newer revision moved, is kept in the runner's state
`unfinished` (§820), key `<branch>.<module>`, value `fingerprint`, `revision`, `pipeline` and `outcome`, and named in
`pipeline-ended`'s new field `unfinished`. At the branch's next kept catalog revision of any `call-kind`, the runner
adds each such mover whose fingerprint is still its entry's there to that revision's pipeline, or starts one for them
alone when the revision moves nothing, with one journal line per mover added again. The key is deleted by the runner
when the mover's pipeline ends passed or a newer fingerprint moves it, or by `runner_unfinished_drop` (one key, with
`why`); `runner_unfinished_place` (one key, with `why`) puts the mover in a pipeline of its own at once; both are
written in the hand-act log, and `runner_unfinished` reads the state. A mover whose own required step failed waits
for its fingerprint to move, as today. Fate: the lead's probe merges of row 167 end. Built in H2. How it is checked:
whole (runner): of a pipeline of two movers one fails its unit step; `pipeline-ended` names the other in
`unfinished`, the next take-in's pipeline carries it, and it is wanted.
- §787 **A kept mover waiting on its revision says so.** (H-A-171, H-A-284, H-A-287) A kept mover whose kept revision
the runner's view does not hold yet carries `unplaced` `kept-revision-unread` with `revision`, said once in the
journal ("waits for its kept revision N to be read") and read with `runner_show`. Built in H2. How it is checked:
unit.
- §788 **The registration check waits for its view.** (H-A-262, H-A-265 (4), H-A-339 (8); row 141) The runner judges
`registration-missing` only once its registrations view's first read is in; before that it says "registrations not
yet read" once and places no step whose registration it has not read. `runner_health` answers
`registrations-read` (true or false, and since when). Built in H2. How it is checked: unit: a start with the view
unread raises no `registration-missing`, answers `registrations-read` false, and places the movers once it is read.
- §789 **A pipeline is read in parts.** (H-A-299 (3), H-A-350 DMC-8; rows 136, 142) The seat verb `show` and the runner's new tool `runner_show` take
`mover`, `step` and `state` filters applied while reading, and answer at most 768 KB with `capped`, `total` and the
cursor of §779; `runner_movers` (a pipeline's key) answers each mover with one word per step (`passed`, `failed`,
`running`, `waiting`, `not-run`), a new tool too; neither tool exists today. Built in H2. How it is checked: unit: one mover's steps of a record of 129 movers
answer under 64 KB; `runner_movers` of 1,000 movers answers under 768 KB.
- §790 **The stalled bound is a setting.** (H-A-311 (3), H-A-313, H-A-322; row 190) The five minutes after which the
runner's health names a running pipeline with nothing open, or a step whose ask is untaken (§778), become the
runner's setting `stalled-bound` (default 5 minutes, the rule nothing-moved-in-five-minutes), read by its process
and its tools program (§781). Built in H2. How it is checked: whole: with `stalled-bound` at one minute, the health
names such a pipeline after one minute, and no longer names it once a step is placed in it.
- §791 **A step's output is read where it is kept.** (H-A-294, H-A-341 (7), H-A-350 DMC-16; rows 144, 165, 168) A build module keeps a
run's output in its `outputs` objects (§820), named on its step key `<node>.<ask id>` (ADR 0525 §6); the build seats
`node-build-go`, `node-build-node` and `node-build-image` gain the read verb `output` (input `ask`; answer the
output's last 64 KB, its size, and the failing tests' names with their words, or "no longer kept" past the objects'
max-age), and the runner's tool `runner_step_output` (pipeline, mover, step) asks it of the holder on the node the
step key names. Fate: the build-step part's `output` (the whole answer in chunks by `ask` and `call`) is replaced by
this form, the part's `form` raised (§780), and the runner's tool is its one reader; the runner's objects
`step-outputs`, which hold 0 bytes, go, dropped through the bus module.
Built in H2 in the build seats' definitions, the three build modules (mesh-catalog) and the runner. How it is
checked: whole (Go build module): a failing unit test's words are read through `runner_step_output`; an output past
its max-age answers "no longer kept".
- §821 **Every event of the delivery parts is waited on by its seat and name.** (H-A-338 (4), H-A-343) Every event
the runner says (`pipeline-started`, `step-ended`, `pipeline-ended`, `wait-held`, `wait-ended` and `re-pinned`, new,
carrying `pipeline`, `mover` and `revision` when a kept mover is re-pinned, H-A-349 DQ-13), the
builder's `ask-taken` and `version-reserved` and the holder of `mesh-wants`' `ask-taken` are declared in their
seat's definition under the seat's events family, so a wait by seat and event name (`mesh_wait` with
`mesh-pipeline-runner.pipeline-ended`) is answered and no session reads a journal on a timer. Built in H2 in the
delivery repository's contracts module (the seat definitions) and the three holders. How it is checked: the seat list
carries each family and name; each holder's whole-module test waits on each of its events by name and is answered.
### The builder (seat `mesh-builds`; mesh-delivery-builder)
- §792 **An answered ask is a journal line.** (H-A-320 (1), H-A-333; row 189) The builder writes one line per build
ask it answers, "answered `<ask>` `<pipeline>` `<movers>` `<step>` `<outcome>`", in the one place an ask is answered
(its build step's finish), beside the line per entry saying an existing build or one built now; the holder of
`mesh-wants` one per validate or compose ask answered. Built in H2 (builder, assigner). How it is checked: unit.
- §793 **The publish queue is a work-queue stream.** (H-A-290, H-A-291, H-A-338 (5), H-A-349 DQ-6; row 158) The builder's publish
items travel on its work queue `publishes` (§820), subject `publish.<holder>.<class>.<module>.<version>` with class
`live` (a build a pipeline's step waits on) or `again` (asked again at a start), one consumer per holder and class,
declared with the stream in the builder's `requires`, that the builder pulls, `live` first, at most four sends in flight per holder (H-A-290 (3)); an item is acknowledged
when its publish is heard or confirmed (H-A-274), terminated when its build is withdrawn or superseded (H-A-290 (2),
H-A-291 (1)). `builder_publish_queue` reads the stream's counts per holder and class, the oldest and newest, and a
capped list; `builder_publish_drop` (module, version, why) terminates one item; `builder_publish_first` (module,
version, why) puts one item again as `live` under the message id
`<holder>.live.<module>.<version>` and terminates the old; both are written in the hand-act log. Fate: the
state bucket of publish items, its listing and its relisting go; its items are put on the stream once at the
builder's first start of this release, each with the message id `<holder>.<class>.<module>.<version>`, so a move started
twice puts each item once within the duplicates window; then the bucket is dropped through the bus module. Built in
H2. How it is checked: whole (builder): a live publish enqueued behind 100 `again` items is sent first; a dropped
item is never sent; a move run twice puts each item once.
- §794 **The builder's handling of an event costs one read and one write.** (H-A-269, H-A-271, H-A-280, H-A-340 (7);
row 152) A heard `published` or `package-published` costs one read of the index by digest (or by version on a miss,
H-A-271) and one write; the builder logs any event whose handling passed 100 ms, with its duration and why, and its
health names an events backlog whose oldest message is older than five minutes. Built in H2. How it is checked: unit
(builder): handling 1,000 published events over 2,000 reservations makes exactly one index read and one write each;
whole: a backlog held six minutes makes the health name it.
- §795 **A plan no seat can build is said once.** (H-A-226's owed; rows 101, 166) A module whose artifact no seat
builds is kept in the builder's memory with its language and kind, worked out again at every start and every change
of the seat list, and said in one summary line each time, "N modules have an artifact no seat builds:" with each
language and kind and its count; `builder_unbuildable` lists them. Fate: the line per module and definition goes.
Built in H2. How it is checked: unit: 6,500 unbuildable plans write one line.
- §796 **A tag names its commit; the builder reads it before it reserves.** (H-A-234 (2), H-A-245, H-A-246, H-A-341
(3), H-A-350 DMC-3; rows 73, 121) The seat `git`'s `tags` answer, a list of strings today, becomes a list of
items `{tag, commit}`, the seat's `form` raised to 2 and read tolerantly (§780) by every reader (the builder's
versions claim, mesh-sdk's bootstrap copy of the seat); its listing's description says a
missing directory answers `not-found` (H-A-232): one contract change, its holder the forge module and mesh-sdk's
bootstrap copies in one group. The builder reads a module's tags once per catalog revision it reserves under, and
skips a number whose tag stands at another commit, with the finding `version-tagged-elsewhere` (scope module),
cleared at the module's next `version-released`; a read that meets a transport fault or `away` (§776) lets the
reservation go on, said in the journal. A tag is never moved. The tag the builder writes for a Go package is
`<directory>/v<version>`, which the Go toolchain's direct fallback reads (row 73); the `go/v<version>` tags go from
new versions. Built in H2 in the seat `git`'s definition, the forge module, mesh-sdk's copies and the builder. How it
is checked: whole (builder): a tag standing at another commit makes the builder reserve the next number and raise
the finding, which clears at the next release.
- §797 **The build record carries its end.** (H-A-257) The builder's record of a build carries `ended` and `outcome`
when it ends, so a reader of the builds (the artifact store's sweep) reads no key history. Built in H2. How it is
checked: unit.
- §798 **A publish keeps its time.** (H-A-328, H-A-331; row 197) A reservation's published mark keeps `at` (when the
builder heard or confirmed the publish) and a kept release keeps the published `digest`; the verb `published` answers
both where kept and leaves them out for marks written before. Where H1's tail already built this, H2's prepare reads
it on main and builds only the rest. How it is checked: unit (builder): a publish heard now answers its time.
### The build modules (seats `node-build-go`, `node-build-node`, `node-build-image`)
- §799 **A fetch or a publish that meets its holder away is a transport fault.** (ADR 0668 §1 and ADR 0664 §1 (insights of 2026-11-21,
accepted); ADR 0664 §2; H-A-301, H-A-341 (8), H-A-342 (1); row 178) A build or check step whose fetch of its source meets a connection fault or a 401 or 5xx
answer of the forge, or whose publish to a registry seat meets no responders or a bundle that exited, ends its run
`again`, never the step (ADR 0664 §1), with no seat call to learn why. The build module passes its delay with
its `again` (the bundle's own delayed settle): 15 s after the first run and 60 s after the second (`again-delays`,
a setting of each build module, default "15s,60s", so three runs span the one-minute absence met on 2026-11-21);
the tool runner's own back-off changes nothing (H-A-350 DMC-7); and a third run's fault ends the step failed
with the why `fetch: <words>` or `publish: <words>`, whichever met the fault (ADR 0664 §2), which the builder and the runner say apart from a build's failure. Built
in H2 in the build seats' conformance kit (ADR 0664 §6) and the three build modules. How it is checked: the
conformance kit holds a fetch met by a 401 and a publish met by no responders to `again`, and three such runs to the step failed
with `fetch:` and with `publish:` respectively.
- §800 **A test that cannot run says NOT RUN; a starved setup runs again; a needed npm tree is installed.** (H-A-294,
H-A-327, H-A-338 (3), H-A-339 (6), H-A-340 (6), H-A-341 (7); rows 168, 170, 194) A step's summary counts `not-run`
apart from passed and failed, with each test's name and reason; a level whose tests passed or did not run passes,
its not-run listed; a test lacking tooling its step does not give says NOT RUN (H-A-294). A Go artifact may declare
`check-needs` with the value `node-modules` in its manifest, which replaces the marker file `check-needs` in a
package's directory in the same release: the marker goes and its readers (the Go build module's digest, the
delivery SDK's `steprun.AskNeeds`) read the field (H-A-350 DMC-6); the runner then asks the seat `node-build-node` a step of
the new accepted kind `install` (input: the module's package lock at the commit) before the integration level; the
Node build module installs from the npm registry seat with an integrity-checked install (`npm ci`) and no install
scripts, keeps the tree as an archive in its `outputs` under the lock's digest (§820), and the step's end carries the
archive object's name (ADR 0666 §16), which the integration ask names and the Go build module unpacks into the
workspace. Each level gets its bound in the environment as `MESH_TEST_LEVEL_BOUND`, and mesh-sdk's test helpers take a
setup bound of half of it, never a value in the test; a whole-module test whose setup wait on the bus passes that
bound ends its run `again` by §799's delays, and a third such run ends the step could-not-run "the bus did not answer
in setup within <bound> under load", never failed. An assertion that fails is never `again` and never NOT RUN. Fate:
the Node build module's and the recovery module's setup bounds in code go. Built in H2 in mesh-sdk (the helpers, the
catalog's `check-needs`), the build seats' definitions, the three build modules and those two modules' tests. How it
is checked: whole (Go build module): the forge module's whole-seat test runs with its npm tree; a test whose setup
is starved runs again and ends could-not-run at the third run; unit (Node build module): an install runs no script.
- §801 **Every build seat says what it takes and what runs.** (ADR 0525 §4, §10; H-A-302 (4), H-A-320 (3), H-A-350
DMC-16; rows 99, 179, 189) Each build seat's verb `current` (the build-step part's, its form replaced by this one and
the part's `form` raised) answers, per holder, whether it takes check asks and why not (`paused`,
`capacity 0`, `unhealthy`, with since when), and every ask it runs, whoever asked it (the builder's delivery asks
included); the build modules' steps read tools answer the steps state they keep, never empty while steps run;
`build_current` (the builder's tool) asks every holder and answers them together. Built in H2 in the three build
modules and the builder. How it is checked: whole (Go build module): an ask the builder put is listed by `current`
while it runs; a paused holder answers `paused`.
### The indexer (seat `mesh-catalog`'s holder; mesh-delivery-indexer)
- §802 **A module moves only when its own build source changes.** (ADR 0267 §1, §2; ADR 0499 §2; H-A-202, H-A-298 (1),
H-A-338 (9), H-A-349 DQ-8, H-A-350 DMC-5; row 175) A module's fingerprint tree input is ADR 0499 §2's (already
built so in the indexer's inputs): the hash over its manifest and its named
paths where every artifact names `paths`, else its directory's tree object at the commit, with the directories of
its same-repository requirements taken in as H-A-202 has it; never the repository's commit. A mesh package of the module's
own repository that no module has published yet enters by its directory's tree, never by the head commit the gate's
source names (the same source, the same fingerprint); a package of another repository not yet published leaves the
module without a fingerprint until it is, said as `NoPackageVersion` today. A commit outside them moves nothing. The
one fingerprint function is the indexer's (`internal/fingerprint`, `form.go`); the builder reads what the indexer
writes and takes only the release, in one group with it. Fate: the fingerprint
over the repository's commit goes; every module's fingerprint changes once, at H2's delivery (§818). Built in H2 in
the indexer. How it is checked: whole (indexer): a
commit touching two test files of two modules in a repository of 36 moves those two and their importers alone.
- §803 **A take-in says what it waits on.** (H-A-298 (2); row 175) A take-in waiting longer than a minute on another
part (the seat `git`'s listing, a package's versions, a registry) writes one journal line naming the part, the verb
and since when, and keeps it on its value in `takeins` as `waiting-on` (`part`, `verb`, `since`), read with
`indexer_pending`; past five minutes it raises the finding `take-in-waiting` (scope merge, id the source revision),
cleared when the wait ends. Built in H2. How it is checked: unit: a listing answered after 70 s writes one line and
`waiting-on`; one answered after six minutes raises `take-in-waiting`, which clears at the answer.
- §804 **A dry run keeps to its own scratch state.** (H-A-297, H-A-339 (7), (8); row 174) A dry run of a branch's
take-in writes only to the indexer's state `dry-runs` (§820), keys `<branch>.<call>.<kind>.<name>`, deleted by the
indexer when the dry run answers and every one at the indexer's start, and leaves the trunk's packages state
untouched; `indexer_dry_runs` reads the state. Built in H2. How it is checked: whole (indexer): a branch dry run
leaves the trunk's packages state byte for byte as before, and a start finds `dry-runs` empty.
- §805 **A release re-pins once, at its reservation.** (H-A-204, H-A-283's owed, H-A-338 (4); row 153) The builder says
`version-reserved` on the seat `mesh-builds`' family (`module`, `artifact`, `path`, `version`, `fingerprint`,
`revision`) when it reserves a package's number; the seat's definition declares the event, so only its holder
publishes it, and the indexer consumes it. The indexer re-pins every importer once at that event, and a
`package-published` of the pinned version keeps no revision; a withdrawn reservation re-pins to the series' newest
released version. Test steps still wait for the publish (H-A-206). Fate: the re-pin per publish goes. Built in H2 in
mesh-delivery (contracts, the builder, the indexer). How it is checked: whole (indexer): a release of a module
importing twenty packages of its own pipeline keeps one re-pin revision.
- §806 **The registrations are read in one call.** (row 140) `indexer_registrations` answers the registrations state
with `module` and `repository` filters applied while reading, at most 768 KB, with `capped` and the cursor of §779.
Built in H2. How it is checked: unit.
### The delivery repository
- §823 **The stale copies at the delivery repository's root go.** (H-A-350; principle 3, one copy per thing) The
directories `contracts/` and `sdk/` at mesh-delivery's root, copies of the delivery contracts module and the
delivery SDK that no module builds from, are removed in H2 as a subtask of their own, after every reader is moved to
`modules/mesh-delivery-contracts` and `modules/mesh-delivery-sdk`. How it is checked: the repository's check finds
no import of either path, and the indexer's module graph is unchanged by the removal.
### The catalog's checks
- §814 **The validator reads the mesh's seat list, counts only new problems, and refuses an uncapped store.**
(H-A-299 (2), H-A-329, H-A-338 (10), H-A-339 (1), (8), H-A-349 DQ-5, DQ-10, H-A-350 DMC-9; rows 196, 198) The
seat `mesh-catalog` gains the read verb `seat-list` answering the seat list the mesh holds as one object in the
indexer's objects `seat-lists` (§820), one object per digest (`digest`,
`size`, `object`), which the manifest validator program takes by address, so a run by hand reads what the live
validate reads. The step `validate`, the assigner's, counts for a module it touches only the problems new against its before case
(its `causedProblems`, which today counts every problem of a touched module); `assigner_validate_before` (pipeline,
module) answers the before case's problems it did not count.
The validator refuses a delivery module's state, log or objects entry with no cap (§812); a delivery module is one
whose manifest claims a seat of the delivery system, which the validator reads from the claims; the foundation parts among
the delivery modules are the indexer, the builder, the runner, the assigner, the gate, the teller and the delivery
contracts module (ADR 0619 §1), and a foundation part's old-section entry declares its cap in that section (H-A-229, ADR 0595 §10) and is never refused for lacking the new
form. Built in H2 in the indexer, the assigner, the manifest validator and mesh-sdk's catalog. How it is checked: whole (indexer): a
run by hand against `seat-list` gives the live validate's verdicts for the builder's and the runner's manifests; unit
(validator): a problem the before case holds is not counted; an uncapped entry of a delivery module is refused, a
foundation part's capped old-section entry is not.
- §819 **Every module H2 touches ends with fewer tests than it starts with.** (ADR 0548; the test budget, 50
integration and 500 unit per module; H-A-340 (8), H-A-349 DQ-14; rows 115 and the row of 18:40 on the budget) Each
module a pull request of H2 changes carries fewer tests at H2's end than at its start, as the check counts them: each
pull request's check reports the module's count at its base and at its head, and the budget is held to that way of
counting. The figures below are guesses, said as such, from two other ways of counting: by the build node at H1's end,
the indexer 538 integration, the assigner 64 integration, the node-engine 1,716 unit, the NFS server module 51
integration and the package manager module 121 integration; by top-level test functions on the trunks of
2026-11-21 (`go test -list`, with and without the integration tag), the indexer 6 integration and 167 unit, the
assigner 9 and 86, the runner 4 and 105, the builder 18 and 167, the node-engine 11 and 1,715, the NFS server module
0 and 51, the package manager module 3 and 118. The NFS server and package manager modules come within the budget
as the check counts them in H2. How it is checked: the check's counts per module in each pull request, read by its review
against the starting count.
### hq, a watched source with no module
- §815 **A repository with no module registers as a source alone, and merges like any other.** (ADR 0527 §1; ADR 0666
§11, §18; ADR 0682 §1, §3; H-A-332, H-A-334 (1), H-A-338 (2), H-A-339 (3); the operator, 2026-11-21 21:48: no merge
is put to them; rows 176, 177; H-A-349 DQ-9) A registration of the seat `mesh-catalog` takes a source-only form, kept in the
same states as a module's under the key `source.<owner>.<name>` (its history under the same key), with `origin`,
`branches` (one), `policy` and `check`, which names a build seat and a step kind (for hq: `node-build-go`, `unit`,
at the repository's root), never a free command; it names no module. The indexer keeps it with the registrations,
takes a move of that branch in as a take-in with no movers, and refuses a source-only registration whose repository
holds a manifest. The pipeline runner's run on request of a pull request's head (ADR 0666 §18) runs that one step on
the named seat, in its sandbox, as a pipeline step; `merge-pull` judges the head by the registration's `policy` from
the runner's step events, as it judges a module's (ADR 0666 §11), and merges it. The forge bridge says `head-moved`
for the branch and the gate watches it as any watched branch (`head-untaken`, ADR 0682 §3); the gate's record of
such a merge ends `nothing to deliver`. This closes a gap: ADR 0527 §1 has hq's checks run by the Go build module as
any repository's tests, but with the checker gone (design 47 G) nothing asked that run, and hq's pull requests were
merged by the operator at the forge with no mesh run. Fate: those merges at the forge end at H2's delivery; hq is
registered so once through the seat `mesh-catalog`'s verb `register`, the operator's channel saying it as a
registration change. Built in H2 in the indexer (the registration's source-only form and the seat's definition), the
runner, the forge module's `merge-pull` and the gate. How it is checked: whole (indexer, runner and gate): a
source-only registration's pull request is run on request, merged by one merge call, raises no `head-untaken` and
ends its record `nothing to deliver`; an hq pull request whose Go checks fail is refused by `merge-pull`, naming the
failed step.
### How H2 is proven
- §818 **H2's own delivery moves every module once, before the proofs.** (ADR 0499 §2; ADR 0682 §6; H-A-338 (9),
H-A-340 (5)) H2's merges are delivered by their pipelines; once the indexer and the builder of §802 run, the
indexer's recompute at its start (`call-kind` recompute, H-A-217) keeps one catalog revision in which every module's
fingerprint moved, and one pipeline carries every module as a mover: about 193 movers (the module graph at trunk
revision 512). A build whose content is unchanged is reused, not built again, and a node-engine restarts nothing
whose composition is unchanged. Its time is read from its `pipeline-ended` phases and quoted in the milestone's
report; a guess, said as one, is about 45 minutes, scaled from row 182's 126 movers in 29 minutes. It is held to no
delivery budget (it is not a change's delivery), only to `stalled-bound`. The proofs run after it ends passed. How it
is checked: the lead reads the pipeline's movers (`runner_movers`) and the node-engines' restarts during it.
- §816 **Proof 1: a one-line change to a delivery part runs everywhere within ten minutes, by its pipeline alone.**
(ADR 0282 §1; ADR 0682 §1, §6, §8; plan section 5, step 7; H-A-340 (10)) A one-line change (a comment) in one module
of the delivery system with lint, unit and composition steps, merged through one merge call (`merge-pull`), runs at
its new version on every present placing machine, reported healthy, within ten minutes of its `merge-called` (a core
module's budget). It is read from the gate's ended record (`gate_record`): `class` core, `delivery-time` under ten
minutes, no `over-budget` raised for it, quoted with its phases (§785); and from the hand-act log, empty for every
delivery part from `merge-called` to the last `running`; no other pipeline held the slot meanwhile. No hand act
touches the delivery system during it: no hand pack, no held put, no call of the seat verb `cancel` (H-A-350 DMC-8),
`runner_end_again`, rerun,
`builder_build_again` or `builder_publish_again`, and no start, stop or restart through the seat
`node-service-manager`; the only restart is the moved module's own, by its node-engine.
- §817 **Proof 2: a package and its importer in two repositories, one merge call, within ten minutes.** (ADR 0282 §1;
ADR 0682 §1, §2, §4; ADR 0573 §2; H-A-340 (10)) One merge call names two pull requests: a one-line change to a
package of the delivery repository whose importers are at most three, one of them the gate in the catalog repository
(read with the indexer's `indexer_package_users`), and a one-line change to the gate. The gate names one source
revision for both, one pipeline publishes the package and builds the gate against it, and every mover runs at its
new version on every present placing machine within ten minutes of `merge-called`, read and bound as §816, with no
hand act and no restart as §816 says. How it is checked for both: the lead reads each with the tools named and
quotes the times in the milestone's report; a proof over its ten minutes or with a hand act is not shown, and its
cause is fixed in its repository and delivered before it is run again.