Write the review's findings and the lead's answers into milestone H's lines

The four reviewers by architectural domain asked changes on the first
version of design 47 H; the lead answered them in H-A-1 to H-A-20. The
lines now carry the merge call's kept key, its partial refusal and its
tools, the clean state's seed and drop order, one consumer per branch
for the take-in, the runner's queue and per-revision events, wants
written tier by tier with a rank the node-engine applies, the producer's
publish limit, the four owners' change events, the tests split per
module with their counts against the budget, and ADR 0682 cited by its
version 5 clause numbers.

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-20 01:50:25 +01:00
parent 5f49bfd818
commit f9d3ecf2c7
5 changed files with 512 additions and 347 deletions
@@ -1522,17 +1522,18 @@ way is written down before the switch (ADR 0526, which ADR 0522 §6 asked of R4g
## Every delivery part wakes on its inputs alone
*ADR 0682 §9; issue 1982; the plan of milestone H, section 3.6.* A delivery part (the forge module, the forge
*ADR 0682 §11; issue 1982; the plan of milestone H, section 3.6.* A delivery part (the forge module, the forge
bridge, the gate, the indexer, mesh-config, the runner, the builder, the build modules, the assigner, the node-engine,
the grants part, the watchman, the condition keeper, the status view, the teller and the tool runner) keeps a watched
copy of each of its own states, through one shape in mesh-sdk's state package (the shape the held pull request
mesh-catalog #708 built for mesh-config, moved into mesh-sdk), and runs a pass only when an input it consumes changed,
taking only the keys that input names. It keeps one timer, set to its earliest real deadline, a bound it states; it
polls nothing, reads nothing of its own whole on a wake, and asks no call again on a timer. Which part moves onto the
shape in which release is design 47 H §762. How it is checked: the code review of every delivery module from milestone
shape in which release, and its cost (the shape's release in mesh-sdk rebuilds nearly every module, so H4 alone
carries it), is design 47 H §762. How it is checked: the code review of every delivery module from milestone
H1 on refuses a timer that is no stated deadline, a poll and a whole re-read; mesh-sdk ships a test helper that counts
the requests a pass makes, and each delivery module's integration test that starts it whole against the bus (ADR
0548) asserts that a pass after one changed key requests that key alone; live, milestone H4 is proven by the bus's
the requests a pass makes, and each delivery module's integration test that starts it whole against the bus (the mesh's
instruction *how-work-is-done*) asserts that a pass after one changed key requests that key alone; live, milestone H4 is proven by the bus's
slow consumers and consumers behind at 0 for an hour, read with `mesh-broker.rates` (H §760) and the bus module's
consumer reads.
@@ -2019,30 +2020,57 @@ ADR 0667's checks, of milestone G itself:
and Go build module, mesh-delivery and mesh-catalog). Live: each module's test steps run once per level, read with
`runner_test_runs`. A reader no part ends raises `pipeline-stands` within five minutes of its last sign of life
(whole, watchman; design 47 G §732).
110. **One merge call is delivered end to end with no hand act** (design 47 H §734 to §738, §743, §746, §750). With
`pipelines-at-once` at 1, a merge call naming one pull request that changes one module says one `merge-called`;
the gate writes one source revision and opens one record; the indexer says one `take-in.taken` naming that module
alone; the runner runs one pipeline; once it passes and the version is released, the module is wanted on every
machine that places it, runs there, and the record ends (whole, forge module, gate, indexer, runner, assigner and
node-engine, mesh-catalog, mesh-delivery and `mesh-host`). Live: the plan's section 5, step 7, read with the tools
and quoted with its times.
111. **A head moved outside the mesh delivers nothing and is said** (design 47 H §739 to §742). A merge made in the
forge's screen gives one `head-moved`, no source revision and no pipeline; `head-untaken` is raised within
`untaken-bound`, naming the repository, branch and head; a later merge call in that repository clears it; and
`gate_head_take` delivers such a head by hand, written in the hand-act log (whole, forge bridge and gate,
mesh-delivery and mesh-catalog).
112. **Two repositories in one merge call are one pipeline, and pipelines run one at a time** (design 47 H §734,
§735, §743, §746 to §748). A merge call naming a mesh-sdk change and a module that imports it, both on one watched
branch, merges both or, with one member refused, neither; merged, it is one source revision, one `take-in.taken`
naming mesh-sdk, that module and mesh-sdk's other importers, and one pipeline in which every importer builds after
mesh-sdk's `package-published`; a second merge call made while it runs is said waiting and runs after its
`pipeline-ended`, and a restart of the runner starts no pipeline of its own (whole, forge module, gate, indexer and
runner).
113. **A want is the newest released version whose pipeline passed** (design 47 H §750, §751). A module released with
a passed pipeline is wanted on every placing machine at once, whatever build an acting part runs and whatever a
dependency's delivery; a released version whose pipeline failed is not wanted; an older version's end heard after
a newer one writes nothing; on one machine the bus module's and the backup holder's changed wants apply before the
others and the node-engine's last (whole, assigner and node-engine, mesh-delivery and `mesh-host`).
110. **One merge call is delivered end to end with no hand act** (design 47 H §734 to §738, §743, §746, §750, §751,
§771). This is the live proof of the chain (the plan's section 5, step 7), read with the tools and quoted with its
times, not one test: with `pipelines-at-once` at 1 and one placing machine away, a merge call naming one pull
request that changes one module says one `merge-called`; the gate writes one source revision and opens one record;
the indexer says one `take-in.taken` naming that module alone; the runner runs one pipeline; once it passes and the
version is released, the module is wanted and runs on every present placing machine, the record ends naming the
machine away, and that machine applies its want when back. Each part's half is a whole test in its own repository
(H-A-17): the forge module's (§734 to §736, §766), the gate's (§737, §738), the indexer's (§743), the runner's
(§746), the assigner's (§750, §751) and the node-engine's (§771).
111. **A head moved outside the mesh delivers nothing and is said** (design 47 H §739 to §742, §766). A merge made in
the forge's screen gives one `head-moved`, no source revision and no pipeline; `head-untaken` is raised within
`untaken-bound`, naming the repository, branch and head; a later merge call in that repository clears it;
`gate_head_take` delivers such a head by hand, written in the hand-act log; and a forge module stopped between its
last merge and the write of that member ends as an untaken head recovered so (whole, forge bridge and gate in
mesh-delivery and mesh-catalog; the stop case in the forge module's whole test).
112. **One take-in is one pipeline, and pipelines run one at a time** (design 47 H §743, §746 to §748). Split per
module (H-A-17): the forge module's whole test that a call naming a mesh-sdk change and an importer merges both or,
with one refused, neither; the indexer's that its `source-moved` names mesh-sdk, that importer and mesh-sdk's other
importers as movers; the runner's that they are one pipeline in which every importer builds after mesh-sdk's
`package-published`, that a second take-in waits and is placed on the first's end, on a cancel and on a set-aside,
that a pipeline waiting on its `approval` step does not count and is placed first when answered, that a newer
take-in moving the same module supersedes it in the waiting pipeline, that `pipelines-stalled` is raised when
pipelines wait and none runs, and that a restart starts no pipeline of its own.
113. **A want is the newest released version whose pipeline passed, written tier by tier** (design 47 H §750, §751,
§771, §772). The assigner's whole test: a module released with a passed pipeline is wanted on every placing
machine whatever build an acting part runs; a version whose pipeline failed is not wanted; an older end heard after
a newer one writes nothing; a placement `build` names the want's version; a consumer's want is written only after its
provider's tier runs, and a tier that does not run within `tier-bound` raises `tier-late`; a node-engine without the
want-by-version capability is said held. The node-engine's whole test: the bus module's and the backup holder's
changed wants apply first, then by `rank`, its own last.
114. **A head whose `required` step failed is refused** (design 47 H §735). The forge module's whole test: a runner's
`step-ended` naming a failed `required` step at a head's fingerprint makes `merge-pull` refuse that head, naming the
step; a later passed run asked again by the operator lets it merge.
115. **A member refused mid-call is said and raised** (design 47 H §767). The forge module's whole test against a
fixture forge that refuses the second merge: one `merge-called` with the first member and `refused`, `merge-partial`
raised by the call, cleared by a later call landing the refused member and by `forge_partial_clear`.
116. **A take-in held on a full store** (design 47 H §744). The indexer's whole test: with the catalog store full a
`source-moved` is held unacknowledged, said once as `take-in.pending`, not redelivered on a timer, and taken in on
`room`; another branch's take-in goes on meanwhile; `indexer_take_in_skip` ends it in the hand-act log.
117. **`validate` refuses a manifest problem and a cycle** (design 47 H §745). The assigner's and the runner's whole
tests: a take-in whose manifest names an unknown field fails `validate` with `manifest-refused` naming it and asks
no composition; one that makes a cycle fails it with `cycle` naming the cycle; the indexer's manifest runs no
validator.
118. **Every account calls every verb; a module publishes only what it declares** (design 47 H §752). The grants
part's whole test: a module calls a verb its manifest does not invoke and is answered, publishes an event its
manifest does not declare and is refused, and an enrolling node's account is held to its own grant.
119. **The builder's lines** (design 47 H §753 to §758). The Go build module's whole test takes the delivery queue
first; the builder's whole tests: a done, unreserved fingerprint asked by a build step ends carried with a version,
a failed 0.1.19 built again is 0.1.19, a catalog entry heard with no step ask builds nothing, `build.ended` names its
version; the runner's: a step with nothing to run ends `nothing to run` and its pipeline passes; the indexer's: a
registration with every step `bypass` is refused, naming them.
## What retires
@@ -2143,7 +2171,7 @@ release reports the controller's code lines against research 063's baseline (acc
| L7 | History and records leave the controller (ADR 0571): the builder keeps its build log, one entry at a build's start and one at its end, from which build history and durations are read and the module mesh-catalog asks the builds it missed; the artifact sweep is the seat `mesh-artifact-sweep`, held by artifact-store-tools beside the artifact store, its keep set from the store's own listing, the wants and the build log, sweeping at each build's end from the lease write and recording each deletion in the hand-act log; disk readings are disk-load's own state on every node; who holds which seat is the state `seat-holders` of the seat `mesh-placement` (now `mesh-module-assigner`), and tools are found by the tool runners' announcements; what a node runs is its want and its have; the grants part writes `grants.<module>.<fingerprint>` and keeps memberships in its own state; root-free is a probe of the self-check; no manifest but the controller's reads, invokes or consumes `mesh-controller`, but a named list kept to the lease write, so the lease write's check passes (ADR 0189, ADR 0547 §11, ADR 0549 §6) | — | mesh-sdk, mesh-controller (its pin only), mesh-delivery (builder, indexer, assigner, grants part, view), mesh-catalog (artifact-store-tools, disk-load, the backup seat's holder, mounts, nfs-server, minio, mesh-watcher, the messenger, the self-check, the module mesh-catalog, docker), mesh-tools (the tool runner) | 1955 |
| B0 | The bootstrap delivery: every check, a lone pull request's as a group of one and a verdict carried after a trunk move included, is judged by a checking program built from the change's own heads in the build seat's sandbox, which also makes the heads' one seat list that the check hands the manifest validator and the composer; it brings no seat definition and no manifest field, so the running checker checks it (ADR 0644; *The bootstrap delivery, and the one milestone after it*) | 26 needs it | mesh-sdk (`go/delivery`: the seat `node-build-go`'s ask `run` and the checker's record of which checking program judged; `go/composer`: the request's seat list), mesh-catalog (mesh-build-go: the run step, the refused answer, the kept programs' tools and sweep), mesh-delivery (checker: the checking program and its command), hq (this design, the glossary) | 1921 |
| G | Two graphs and one revision view: the catalog graph and the assignment graph kept per revision, a change delivered as its graph difference, the acting parts' rules on their seats as bounded waits that hold their modules when the new version fails, the check on the change's own acting parts, the revision view and each process's own build, the gate's delivery record, and the trace's links (ADR 0656); no part reads a pull request's description (ADR 0659); every delivery part reaches the forge through the seat `git` and names no other module; nothing holds an approved merge for another check; and, one milestone with them, research 086's pipelines: a change of any module goes from a commit on a watched branch to the machines through its module's pipeline, its policy in its registration, ordered by edges between artifacts, with no Approve per merge and no hand act, the checker gone (ADR 0666, ADR 0667). Test counts at its start (G's prepare, 2026-11-09): mesh-delivery 665 unit and 68 integration, the node-engine (`mesh-host`) 1,742 unit; each other repository's and each catalog module's from the last check's verdict, read in the joint prepare | 26 to 62, 63 to 106 | mesh-sdk (the runtime: the fingerprint, the view, the definition reader, the seat list's one wiring), mesh-contracts and the domains' contracts modules (`acts`, the new verbs and events, the seat `mesh-grants`, the seat `git`'s verbs), mesh-delivery (indexer, assigner, checker until its removal, builder, grants part, gate's view, forge bridge, watchman, the new pipeline runner `mesh-delivery-pipeline`, `contracts` and `sdk` moved under `modules/`), mesh-catalog (the gate, the build modules, the forge module, mesh-issues, mesh-knowledge, the `node-backup` holder, the router, nats: a module's kept data on the bus as a backed-up item and the object store beside each state), mesh-sdk (also its small object store package, for values of any size), the node-engine (`mesh-host`), hq | 1966, 1961 (retargeted to this row's shape), 1660, 1972, 1721, 1783, 1785, 1794, 1791, 1373, 595; 1962 goes back with 1958, whose assignment entry it needs (ADR 0641 §3) |
| H | The build-and-delivery system delivers itself by its one model, in six releases (H0 to H5, the plan's section 6): one merge call of the seat `git`'s `merge-pull` naming one or more pull requests is a delivery's start and its group; the gate names the merged heads one source revision and opens its record; the indexer takes it in (a commit, the fingerprints of its repositories' modules, one catalog revision) and names the movers; one pipeline per take-in, none in parallel (`pipelines-at-once`, default 1); a want is the newest released version whose pipeline passed; the forge's event is the watchdog (`head-untaken`); every delivery part wakes on its inputs alone and reads no other part's state; the per-pull-request paths, the catch-up by comparison, the sweep and the checker go; one clean state placed by hand once, after which every release is delivered by its own pipeline (ADR 0682, ADR 0681, ADR 0666, ADR 0667; design 47 H §734 to §765) | 110 to 113 | mesh-delivery, mesh-catalog, `mesh-host`, mesh-tools, mesh-sdk, mesh-contracts, hq | opened by each release's prepare |
| H | The build-and-delivery system delivers itself by its one model, in six releases (H0 to H5, the plan's section 6): one merge call of the seat `git`'s `merge-pull` naming one or more pull requests is a delivery's start and its group; the gate names the merged heads one source revision and opens its record; the indexer takes it in (a commit, the fingerprints of its repositories' modules, one catalog revision) and names the movers; one pipeline per take-in, none in parallel (`pipelines-at-once`, default 1); a want is the newest released version whose pipeline passed; the forge's event is the watchdog (`head-untaken`); every delivery part wakes on its inputs alone and reads no other part's state; the per-pull-request paths, the catch-up by comparison, the sweep and the checker go; one clean state placed by hand once, after which every release is delivered by its own pipeline (ADR 0682, ADR 0681, ADR 0666, ADR 0667; design 47 H §734 to §774) | 110 to 119 | mesh-delivery, mesh-catalog, `mesh-host`, mesh-tools, mesh-sdk, mesh-contracts, hq | opened by each release's prepare |
An issue is in one row only (ADR 0493 §2): where a row named an issue another row names too, the last row keeps it and the
earlier row says so in words (the operator, 2026-10-26). Milestone M1 makes each row a record of the issue tracker
@@ -26,7 +26,7 @@ is named, it is named by module and function, from the gap tables of 2026-11-20,
registered modules." 2026-11-20 about 01:10 CET: "parallel pipelines sounds like a very bad idea". 01:15 to 01:20 CET:
a delivery is started by hand by the merge it already needs, the lead named principle 3 (a start a person forgets is
a silent non-delivery), and the operator chose "A": the merge through the mesh is the start and the group, and the
forge's event is the watchdog. ADR 0682 records it. The chain these lines build, in one sentence: a **merge call**
forge's event is the watchdog. ADR 0682 records it (cited by the clause numbers of its version 5). The chain these lines build, in one sentence: a **merge call**
(the seat `git`'s `merge-pull` naming one or more pull requests) merges the heads, the gate names them one source
revision per watched branch and opens its delivery record, the indexer takes that revision in and names the movers,
the runner runs one pipeline for it when no other runs, and the assigner wants the newest passed release; the forge
@@ -47,196 +47,259 @@ flowchart LR
### The merge call
- §734 **One merge call is a delivery's start and its group.** (ADR 0682 §1, ADR 0666 §11; the operator, 2026-11-20
- §734 **One merge call is a delivery's start and its group.** (ADR 0682 §1, §2; ADR 0666 §11; the operator, 2026-11-20
01:20 CET; principle 3) The seat `git`'s verb `merge-pull` takes `pulls`, a list of one or more members
`{repository, number, head}` (the head the caller names, as ADR 0666 §11 has it), and `by`, the caller as who@node.
The members named in one call are one delivery and, when there are two or more, its group; nothing else makes a group.
The verb's single-pull form goes: a call naming one pull request is a list of one. Built in H1 in the forge module's
`merge-pull` handler and the seat `git`'s contract in mesh-delivery-contracts. How it is checked: whole (forge
module): a call naming two pull requests in two repositories merges both and says one `merge-called` (§736).
Replaces G §38's one-pull form.
- §735 **Every member is judged before any is merged.** (ADR 0666 §11; principle 3) The verb judges each member as
ADR 0666 §11 does (still the pull request's head, a branch protection that refuses a direct push, read again; no run
at the head's build-input fingerprint failed a `required` step, from the forge module's own `failed-steps`), all of
them first. When one member is refused, none is merged, and the answer names every refused member and why. Then it
merges the members in the order the call names them. Why this order: a group merged in part would land half a
delivery (ADR 0666 §13's "none delivered if one fails", kept for the call's group). What the call says when the
forge refuses a member after all were judged is question 1 of *Questions this file leaves open*. Built in H1 (forge
module). How it is checked: whole (forge module): a call whose second member's head moved merges neither and names
it.
- §736 **The merge call says one event.** (ADR 0682 §1; principle 1) When every member is merged, the forge module says
the seat `git`'s event `merge-called` on `mesh.seat.git.event.merge-called.<call>`, kept on the stream
`SEAT_git_merge-called` for 30 days and up to 64 MiB, its body in the seat's `bodies`: `call` (an id the forge module
makes once per call: 16 lowercase hex), `by`, `at` (the time of the last merge) and `members`, one
`{repository, number, branch, head, commit}` per member, where `branch` is the pull request's base (a watched
branch) and `commit` the merge commit the forge records for that pull request. Only the forge module says it. Its
one consumer is the gate (§737), on a durable consumer of its program. Why 30 days: the gate takes in a call heard
after a long stop, and the forge module's `seen` keys are kept as long (G §585). Built in H1 (forge module, seat
`git`'s definition and contract). How it is checked: unit (the seat definition: the event and its body);
whole (forge module) as §734.
- §737 **The gate names the merged heads one source revision and opens the record.** (ADR 0682 §1; principles 1
and 12) The gate consumes `merge-called`. For each watched branch its members name, it writes `source.<branch>` once,
by compare-and-set: the branch's previous heads with each member's repository at its `commit`, numbered one above
the branch's newest, carrying `call`. It opens one delivery record per such revision, keyed `<branch>.<source>`
(A-33 stands), its members the call's members on that branch, `call` and `by` in its trace, and says `source-moved`
with `branch`, `source`, `call`, `start` (false; true only for A-401's start pass of a newly watched branch, which
stays) and `heads` (the repositories it moved, each `{repository, commit}`). A
`merge-called` heard again writes nothing: its record's key exists. A call whose members name two branches is two
source revisions and two records, each naming the same `call`. The gate numbers every source revision; no other part
keeps a number of its own. Built in H1 in the gate: its `moveSource` moves from the `take-in.taken` handler to a
`merge-called` handler; `ForgeMerged`, `moveHead` and the tool `gate_source_follow` go (§764). How it is checked:
whole (gate): a `merge-called` with two members on one branch gives one revision, one record and one
`source-moved`; the same event heard twice gives one. Replaces A-34 (the source moved on `take-in.taken`), G §291,
A-431's numbering by the indexer, and A-464 to A-464e.
`{repository, number, head}` (the head the caller names, as ADR 0666 §11 has it), and `by`, the caller as who@node;
the forge module records `by` beside the bus account the tool runner proves for the call. The members named in one
call are one delivery and, with two or more, its group; nothing else makes a group. The verb's single-pull form goes:
a call naming one pull request is a list of one, and its callers change with it in H1 (the tool runner's
`merge-pull` tool and its description, the claude-code module's instructions and playbook 07's merge step, which name
one pull request). The verb answers `call` (§766) at once and the members' outcome when the call ends. Built in H1 in
the forge module's `merge-pull` handler and the seat `git`'s contract in mesh-delivery-contracts. How it is checked:
whole (forge module): a call naming two pull requests in two repositories merges both and says one `merge-called`
(§736). Replaces G §38's one-pull form.
- §735 **Every member is judged before any is merged.** (ADR 0682 §1; ADR 0666 §11; principle 3) The verb judges each
member as ADR 0666 §11 does (still the pull request's head; a branch protection that refuses a direct push, read
again; no run at the head's build-input fingerprint failed a `required` step), all of them first. When one member is
refused, none is merged, and the answer names every refused member and why. Then it merges the members in the order
the call names them. The forge module's `failed-steps` that this judges is written from the runner's `step-ended`,
whose body names the mover, its commit and its build-input fingerprint (H-A-18). Why judging first: a group merged in
part lands half a delivery. Built in H1 (forge module). How it is checked: whole (forge module): a call whose second
member's head moved merges neither and names it; a head at whose fingerprint a `required` step failed is refused,
naming the step (acceptance test 114).
- §766 **The call is written before its first merge and said again at the forge module's start.** (H-A-18; principles
3 and 4) Before it merges anything, the forge module writes the call's key `call.<call>` in its own template state
`calls` (value: `by`, the bus account, `at`, the members, each with `state` `judged`, `merged` with its commit, or
`refused` with why), and updates each member as it merges. At its start it reads every call whose event it has not
said (`said` false) and says `merge-called` for what landed, so a stop between the last merge and the event loses
nothing it recorded. A call is kept `call-retention` (a setting, default 30 days), then deleted by the forge module.
Its tools: `forge_calls` (the calls, newest first, with each member's state) and `forge_call_say_again` (with `call`
and `why`, says its `merge-called` again, written in the hand-act log). A stop between a merge and the write of that
member's `merged` leaves a head the call never names: it is an untaken head (§740), recovered with `gate_head_take`
(§742). Built in H1 (forge module). How it is checked: whole (forge module): a restart after the second of three
merges says one `merge-called` naming the two that landed; acceptance test 111's stop case.
- §767 **A member refused after every member was judged is said and raised.** (H-A-1; principle 3) When the forge
refuses a member after all were judged (a conflict that appears between the judging and its merge, the forge down
mid-call), the forge module stops merging, says `merge-called` with the members that landed and `refused`, one
`{repository, number, why}` per member not merged, and raises the finding `merge-partial`, scope `delivery`, id the
call, naming each refused member. The landed members are delivered as any call's. It clears the finding when a later
call lands every refused member (read from its own `calls`), or by its tool `forge_partial_clear` with `call` and
`why`, written in the hand-act log. A call that landed no member says no `merge-called`. Built in H1 (forge module).
How it is checked: whole (forge module): a fixture forge that refuses the second merge gives one `merge-called` with
the first member and `refused`, and `merge-partial` raised and cleared by a later call (acceptance test 115).
- §736 **The merge call says one event.** (ADR 0682 §1; principles 1 and 11) Once its members are merged or refused,
the forge module says the seat `git`'s event `merge-called` on `mesh.seat.git.event.merge-called.<call>`, kept on
the stream `SEAT_git_merge-called` for `merge-called-retention` (a setting, default 30 days) and up to
`merge-called-cap` (a setting, default 64 MiB), its body in the seat's `bodies`: `call` (16 lowercase hex, made once
per call), `by`, `account`, `at` (the time of the last merge), `members`, one `{repository, number, branch, head,
commit}` per landed member, where `branch` is the pull request's base (a watched branch) and `commit` the merge
commit the forge records for that pull request, and `refused` (§767). Only the forge module says it. Its one consumer
is the gate (§737), on a durable consumer of its program. Why 30 days: the gate takes in a call heard after a long
stop, as the forge module's `seen` keys are kept (G §585). Built in H1 (forge module, the seat `git`'s definition and
contract). How it is checked: unit (the seat definition: the event and its body); whole (forge module) as §734.
- §737 **The gate names the merged heads one source revision per call and opens the record.** (ADR 0682 §1, §2; H-A-13,
H-A-19; principles 1, 3 and 12) The gate consumes `merge-called`. For each watched branch its members name, it writes
`source.<branch>` once, by compare-and-set keyed by the call (the revision carries `call`, and a revision of that
branch already carrying that call writes nothing): the branch's previous heads with each member's repository at its
`commit`, where two members of one repository on one branch name the last member's commit in call order, numbered one
above the branch's newest. It opens one delivery record per such revision, keyed `<branch>.<source>` (A-33 stands),
its members the call's members on that branch, `call`, `by` and `account` in its trace; says `record-opened` on
`mesh.seat.mesh-delivery.event.record-opened.<call>` with `branch` and `source`, so the session that called can wait
on its own call; and says `source-moved` on `mesh.seat.mesh-delivery.event.source-moved.<branch>.<source>` with
`branch`, `source`, `call`, `start` (false; true only for a branch's first revision, §768) and `heads` (the
repositories it moved, each `{repository, commit}`). A call whose members name two branches is two source revisions
and two records, each naming the call. The gate numbers every source revision; no other part keeps a number of its
own. `source-moved` is kept for `source-moved-retention` (a setting, default 30 days). Built in H1 in the gate: its
`moveSource` moves from the `take-in.taken` handler to a `merge-called` handler; `ForgeMerged`, `moveHead` and
`gate_source_follow` go (§764). How it is checked: whole (gate): a `merge-called` with two members on one branch gives
one revision, one record and one `source-moved`; heard twice it gives one; two members of one repository give its
last member's commit. Replaces A-34, G §291, A-431's numbering by the indexer, and A-464 to A-464e.
- §738 **A delivery record follows its pipeline to the machines.** (ADR 0666 §9; G §141 to §147) The record opened by
§737 is the record of G §141 to §147, one per source revision: it consumes the runner's `pipeline-started` and
`pipeline-ended`, the parts' `wait-held` and `wait-ended`, and the node-engine seat's `running`, on the gate's own
durable consumer, writes its trace (the assignment graph revisions it moved between, from the assigner's `wanted`),
and ends as G §147 says. A take-in with no movers (§741) ends its record at once as `nothing to deliver`. Built in
H3 in the gate's consumer (`stepFamilies`) and record (`SetTrace`, `EndIfRun`). How it is checked: whole (gate):
a record of a one-module delivery ends when the module runs on every placing machine (acceptance test 110).
`pipeline-ended` (§746) of its source revision, and of the pipelines `package-published` starts from it (§747), the
parts' `wait-held` and `wait-ended`, the assigner's `wanted` and the node-engine seat's `running`, on the gate's own
durable consumer; writes its trace (the assignment graph revisions it moved between, from `wanted`); and ends as G §147
says, or `failed` when the assigner says a tier late (§751). A take-in with no movers ends its record at once as
`nothing to deliver`. Built in H3 in the gate's consumer (`stepFamilies`) and record (`SetTrace`, `EndIfRun`). How it
is checked: whole (gate): a record of a one-module delivery ends when the module runs on every present placing
machine.
### The forge bridge's one message, and the watchdog
- §739 **The forge bridge says one message per move of a watched branch's head.** (ADR 0682 §2, ADR 0666 §6; G §11,
A-236) On every `git.branch-moved` of a watched branch, and at its start for every watched branch's head, the bridge
reads the head through `git.branch` (never the event's body) and writes one message `head-moved` on its stream
`forge`, subject `forge.<repository>.<branch>.head-moved`: `repository`, `branch`, `head`, `before` (the head it held
for that branch in its state `heads`, empty the first time) and `start` (true when said at its start). It writes it
whether the head moved by a merge call, a merge in the forge's screen or an admitted push: it reads no pull request
and no tree. A head equal to the one it holds writes nothing. An unprotected watched branch writes nothing and is
said as `branch-unprotected` (G §17 stands). Its one consumer is the gate (§740). Built in H1 in the bridge; the
messages `merged` and `pushed`, their `base`, their trees in its state `inputs`, and its call of `git.pull` for a
merged commit go (§764). How it is checked: whole (bridge): a merge, an admitted push and a restart each give one
`head-moved`; a head heard twice gives one. Replaces G §509 and §714's message form; this is item 6 of the plan's
section 4.
- §740 **A head no merge call delivered is an untaken head.** (ADR 0682 §2; principles 1 and 3) The gate consumes
`head-moved` and keeps, in its template state `heads` (one key `<repository>.<branch>`, value `{head, since}`, the
key deleted by the gate when `source.<branch>` names that head), each head that `source.<branch>` does not name for
that repository. When `untaken-bound` (a setting of the gate, default 10 minutes, at least 1) passes and
`source.<branch>` still does not name that head, the gate raises the finding `head-untaken`, scope `delivery`, id
- §739 **The forge bridge says one message per move of a watched branch's head.** (ADR 0682 §3; G §11, A-236) On every
`git.branch-moved` of a watched branch, and at its start for every watched branch's head, the bridge reads the head
through `git.branch` (never the event's body) and writes one message `head-moved` on its stream `forge`, subject
`forge.<repository>.<branch>.head-moved`, kept `head-moved-retention` (a setting, default 7 days): `repository`,
`branch`, `head`, `before` (the head it held for that branch in its state `heads`, empty the first time) and `start`
(true when said at its start). It writes it whether the head moved by a merge call, a merge in the forge's screen or
an admitted push: it reads no pull request and no tree. A head equal to the one it holds writes nothing. An
unprotected watched branch writes nothing and is said as `branch-unprotected` (G §17 stands). Its one consumer is the
gate (§740). Built in H1 in the bridge; the messages `merged` and `pushed`, their `base`, their trees in its state
`inputs`, and its call of `git.pull` for a merged commit go (§764). How it is checked: whole (bridge): a merge, an
admitted push and a restart each give one `head-moved`; a head heard twice gives one. Replaces G §509 and §714's
message form.
- §740 **A head no merge call delivered is an untaken head.** (ADR 0682 §3; principles 1, 3 and 11) The gate consumes
`head-moved` and keeps, in its template state `heads` (one key `<repository>.<branch>`, value `{head, since}`, deleted
by the gate when `source.<branch>` names that head), each head that `source.<branch>` does not name for that
repository. When `untaken-bound` (a setting of the gate, default 10 minutes, at least 1) passes and `source.<branch>`
still does not name that head, the gate raises the finding `head-untaken`, scope `delivery`, id
`<repository>.<branch>`, naming the repository, the branch, the head, since when, and "moved outside the mesh:
delivered by nothing". It clears it when `source.<branch>` names that repository at the newest head `head-moved`
said (a later merge call delivers it). The gate keeps one deadline timer, set to the earliest `since` plus the bound,
and no other clock. Built in H1 in the gate. How it is checked: whole (gate, bridge): a head moved by a merge call
raises nothing; a head pushed outside the mesh raises `head-untaken` within the bound, starts no pipeline, and
said (a later merge call or §742's hand take). The gate keeps one deadline timer, set to the earliest `since` plus the
bound, and no other clock. Built in H1 in the gate. How it is checked: whole (gate, bridge): a head moved by a merge
call raises nothing; a head pushed outside the mesh raises `head-untaken` within the bound, starts no pipeline, and
clears when a later merge call takes its repository in (acceptance test 111). Replaces A-463's `merge-untaken` and
the head half of G §12 (§741 keeps its step half).
- §741 **`pipeline-stands` times a pipeline's steps, not a head.** (ADR 0666 §24; principle 7) The watchman's finding
`pipeline-stands` (G §12, §75) is raised for a pipeline step standing still five minutes; a watched branch's head
that starts no pipeline is the gate's `head-untaken` (§740) alone, so the watchman learns no head. A pipeline waiting
its turn (§746) is progress not owed and raises neither. Built in H1 in the watchman's `takein` and `signals` parts.
How it is checked: whole (watchman): a pipeline waiting behind another raises nothing. Answers question 6 of
specification A.
- §742 **Taking an untaken head in by hand.** (ADR 0682 §2; principle 4) The gate's tool `gate_heads` reads the state
the head half of G §12. An acknowledge tool that silences a known `head-untaken` without delivering it was proposed
by the review and is not built: no record or answer asks for it (noted for H4's tools table).
- §741 **`pipeline-stands` times a pipeline's steps, not a head.** (ADR 0682 §7; ADR 0666 §24; principle 7) The
watchman's finding `pipeline-stands` (G §12, §75) is raised for a pipeline step standing still five minutes; a watched
branch's head that starts no pipeline is the gate's `head-untaken` (§740) alone, so the watchman learns no head. A
pipeline waiting its turn (§748) is progress not owed and raises neither. Built in H1 in the watchman's `takein` and
`signals` parts. How it is checked: whole (watchman): a pipeline waiting behind another raises nothing.
- §742 **Taking an untaken head in by hand.** (ADR 0682 §3; principle 4) The gate's tool `gate_heads` reads the state
`heads` with each head's since and finding; `gate_head_take`, with `repository`, `branch` and `why`, names that head
a source revision as §737 does, its `call` `hand.<by>.<time>`, written in the hand-act log, and the chain follows.
Nothing else delivers an untaken head. Why: a merge in the forge's screen leaves a head the mesh holds no record
of; the operator may want it delivered without a new pull request (principle 4, recover without help). Built in H1
(gate tools). How it is checked: unit (gate tools); whole (gate): a hand take writes one revision and clears the
finding.
Nothing else delivers an untaken head. Built in H1 (gate tools). How it is checked: unit (gate tools); whole (gate):
a hand take writes one revision and clears the finding.
- §768 **The clean state seeds every watched branch's first source revision.** (H-A-15; ADR 0682 §12; principles 2 and
3) Before the runner starts at milestone H1's clean state (the plan's section 5), the gate's tool `gate_source_seed`
(with `why`, written in the hand-act log) writes, for every watched branch the registrations name, one source
revision at each repository's current head read through `git.branch`, with `start` true and `call`
`seed.<by>.<time>`, and says `source-moved`; the indexer takes each in with no mover (§743), so the newest catalog
revision of every branch names those heads, and the forge bridge's `head-moved` at its start then matches
`source.<branch>` and no `head-untaken` is raised mesh-wide. The tool answers the branches and repositories it wrote,
counted. A branch newly watched later starts the same way, by A-401's start pass, which stays and writes through this
path. Built in H1 (gate tools; indexer). How it is checked: whole (gate, indexer, bridge): after the seed a bridge
restart raises no `head-untaken`; live, the counts read at plan step 5.
- §769 **`predefined` is read from the take-in of the catalog's commit.** (ADR 0681 §2; ADR 0682 §1) The indexer's state
`predefined`, which ADR 0681 §2 has it read from the forge bridge's merged message of the catalog repository, is read
at the take-in of a source revision that moves the catalog repository, from that commit's trees (§743), the merged
message being gone (§739). Built in H1 (indexer). How it is checked: whole (indexer): a merge call landing a catalog
commit that changes a predefined key rewrites `predefined`. ADR 0681 §2's words "the forge bridge's merged message"
are owed an insight in that record.
### The take-in
- §743 **The indexer takes in what the gate names.** (ADR 0682 §3; A-476, A-476a; principles 7 and 10) The indexer
consumes the gate's `source-moved`, on its own durable consumer, one message at a time, acknowledged once its catalog
- §743 **The indexer takes in what the gate names.** (ADR 0682 §4; A-476, A-476a; principles 7 and 10) The indexer
consumes the gate's `source-moved` on one durable consumer per watched branch, named `<node>_<indexer>_<branch>` (the
branch's name escaped as a key's name is), each delivering one message at a time, acknowledged once its catalog
revision and `take-in.taken` are written. For each repository the event moves it reads the trees at the named commit
through `git.trees` (one of its kept calls, A-190), computes the build-input fingerprints of the modules registered
for that repository (a registration's git origin), and takes as **movers** those whose fingerprint differs from
their entry in the branch's newest catalog revision, and every module, in any repository, that imports a package of
one of them (its code dependents, A-476a; ADR 0573 §3). It writes one catalog revision of that branch, pins it for the
pipeline of §745 in the same write (A-449a, key `pipeline.<branch>.<source>`), and says `take-in.taken` once, with
`branch`, `source`, `revision`, `call` and `entries`, one `{module, commit, fingerprint, repository}` per mover (§763
corrects G §476 and §648: no `pull`). It validates no manifest and holds nothing for the indexer a revision names;
it takes in with the build it runs (A-476 (a), (b)). A `source-moved` with no mover says `take-in.taken` with no
entries. A branch's first source revision (the gate's start pass for a newly watched branch, A-401 and A-403,
said as `source-moved` with `start` true) is taken in with no mover: its entries are the base the branch's later
take-ins are held against, and nothing of it is delivered, since every module is already wanted by its newest passed
release (§750). Built in H1: the indexer's take-in part written again (today `Arrive`, `evaluate`, `takeInWhole`,
`takenWhat`, `nextSource` and `ApplyBranchSource`, fed by the bridge's messages); its storage, entries, pins'
state, versions and verbs (`KeepView`, `keepBranchEntries`) stay. How it is checked: whole (indexer): a
`source-moved` naming a mesh-sdk commit names mesh-sdk and its importers; one changing only a document names no
mover; a restart between the revision's write and the event's acknowledgement writes no second revision (the
revision is keyed `<branch>.<source>` by compare-and-set). Replaces G §16, §19, §509, §712 to §715 and the main
file's *Taken in by the indexer it names* (§764).
- §744 **A take-in that cannot be written waits, said and bounded.** (ADR 0633 §5's revision bound, kept for what
still waits; principle 3) A take-in that cannot be written (the catalog store `full`, G §181; `git.trees`
unanswered) leaves its `source-moved` unacknowledged, so the bus delivers it again, says `take-in.pending` with
`branch`, `source` and `why`, and the watchman raises `take-in-waits` when no `take-in.taken` for that source follows
within 60 minutes (G §497). Take-ins of one branch go in source order, since the consumer delivers one at a time.
The state `pending`, its keys `m.<sequence>` and `g.<group>`, and `indexer_take_in_pending` and
`indexer_drop_pending` go (§764); `indexer_pending` reads the one waiting `source-moved` and why. Built in H1
(indexer). How it is checked: whole (indexer): with the store full a `source-moved` waits, is said, and is taken in
on `room`.
- §745 **Manifest validation is the pipeline step `validate`.** (ADR 0682 §4; A-476 (a); ADR 0666 §17) The step
`validate` is served by the assigner on the seat `mesh-module-assigner`, as an accepted kind `step` on that seat's
work queue, asked by the runner for each mover as the step before its composition step: the assigner runs the manifest validator built from the take-in's own heads,
in the sandbox, as it runs the composer (G §718), over the revision's manifests, refusing only a problem in a
manifest the revision alters or one between manifests an altered one takes part in (ADR 0578 §2). It ends `failed`
with the reason `manifest-refused` naming each problem, or `cycle` naming the cycle the revision makes (the cycle
refusal A-326 and G §569 made at the take-in), and `passed` otherwise. Its status is `required` in every policy by
default: the seed (A-441) writes it, and §22's list of steps gains it. The indexer's events `manifest-refused` and
`manifest-accepted` (G §500, §668) go; their readers read the step's end. Built in H1 (assigner: the step; runner:
the order; indexer: the seed's default). How it is checked: whole (assigner, runner): a take-in whose manifest names
an unknown field fails `validate` and asks no composition; a take-in that validates no manifest at the indexer is
shown by the indexer's manifest declaring no validator run. G §22 serves the composition step itself on the seat
`mesh-wants` (question 2 below).
through `git.trees` (one of its kept calls, A-190), computes the build-input fingerprints of the modules registered for
that repository (a registration's git origin), and takes as movers those whose fingerprint differs from their entry
in the branch's newest catalog revision, and every module, in any repository, that imports a package of one of them
(A-476a; ADR 0573 §3). It writes one catalog revision of that branch, keyed `<branch>.<source>` by compare-and-set,
pins it for the pipeline of §746 in the same write (A-449a, key `pipeline.<branch>.<source>`) when it has a mover,
and says `take-in.taken` once, with `branch`, `source`, `revision`, `call` and `entries`, one `{module, commit,
fingerprint, repository}` per mover (§763 corrects G §476 and §648: no `pull`). It validates no manifest and holds
nothing for the indexer a revision names; it takes in with the build it runs (A-476 (a), (b)). A `source-moved` with
no mover, a branch's first revision (`start` true, §768) included, says `take-in.taken` with no entries and pins
nothing (H-A-19); its entries are the base the branch's later take-ins are held against. Built in H1: the indexer's
take-in part written again (today `Arrive`, `evaluate`, `takeInWhole`, `takenWhat`, `nextSource` and
`ApplyBranchSource`, fed by the bridge's messages); its storage, entries, pins' state, versions and verbs
(`KeepView`, `keepBranchEntries`) stay. How it is checked: whole (indexer): a `source-moved` naming a mesh-sdk commit
names mesh-sdk and its importers; one changing only a document names no mover and pins nothing; a restart between
the revision's write and the acknowledgement writes no second revision. Replaces G §16, §19, §509, §712 to §715 and
the main file's *Taken in by the indexer it names* (§764).
- §744 **A take-in that cannot be written is held, said and skippable.** (H-A-12; principles 1, 3 and 4) A take-in that
cannot be written (the catalog store `full`, G §181) is held: its `source-moved` stays unacknowledged and is not
redelivered on the acknowledgement timer (the consumer's wait for an acknowledgement is longer than any hold, and it
is redelivered with no delay only when the indexer asks); the indexer takes it again when the bus module's `room` for
that store wakes it, with no timer. A `git.trees` call unanswered is its kept call's own (A-190) and holds the same
way. While held the indexer says `take-in.pending` once per source, with `branch`, `source` and `why`, and the
watchman raises `take-in-waits` when no `take-in.taken` for that source follows within `take-in-bound` (a setting,
default 60 minutes; G §497). Take-ins of one branch go in source order; another branch's go on. `indexer_pending`
reads each branch's held `source-moved` and why; `indexer_take_in_pending` takes it again now; `indexer_take_in_skip`,
with `branch`, `source` and `why`, acknowledges it unwritten, says `take-in.taken` with no entries and `skipped`, and
writes the hand-act log. The state `pending`, its keys `m.<sequence>` and `g.<group>`, and `indexer_drop_pending` go
(§764). Built in H1 (indexer). How it is checked: whole (indexer): with the store full a `source-moved` is held, said
once, taken in on `room`; a second branch's take-in goes on meanwhile; a skip ends it in the hand-act log (acceptance
test 116). ADR 0682 §4 at version 5 ends `take-in.pending`, `take-in-waits`' bound and `indexer_pending`, which H-A-12
keeps (question 1 below).
- §745 **Manifest validation is the pipeline step `validate`.** (ADR 0682 §5; H-A-6; A-476 (a); ADR 0666 §17) The step
`validate` is served by the assigner as an accepted kind `step` of the seat `mesh-wants`, the seat that serves the
composition step (G §22), asked by the runner for each mover as the step before its composition step: the assigner
runs the manifest validator built from the take-in's own heads, in the sandbox, as it runs the composer (G §718), over
the revision's manifests, refusing only a problem in a manifest the revision alters or one between manifests an
altered one takes part in (ADR 0578 §2). It ends `failed` with the reason `manifest-refused` naming each problem, or
`cycle` naming the cycle the revision makes (the cycle refusal A-326 and G §569 made at the take-in), and `passed`
otherwise. Its status is `required` in every policy by default: the seed (A-441) writes it, and §22's list of steps
gains it. The indexer's events `manifest-refused` and `manifest-accepted` (G §500, §668) go; their readers read the
step's end (§764). Built in H1 (assigner: the step; runner: the order; indexer: the seed's default). How it is
checked: whole (assigner, runner): a take-in whose manifest names an unknown field fails `validate` naming it and asks
no composition; a take-in making a cycle fails it naming the cycle (acceptance test 117). ADR 0682 §5 at version 5
still names `mesh-module-assigner`; H-A-6 asks the record writer to correct it.
### One take-in, one pipeline, none in parallel
- §746 **One take-in is one pipeline.** (ADR 0682 §5; the operator, 2026-11-20 01:10 CET; ADR 0666 §1, §7, §9 read per
- §746 **One take-in is one pipeline.** (ADR 0682 §6; the operator, 2026-11-20 01:10 CET; ADR 0666 §1, §7, §9 read per
source revision) On a `take-in.taken` with entries the runner starts exactly one pipeline, keyed `<branch>.<source>`
by compare-and-set on its absence, whose movers are the event's entries. It asks each mover's pipeline steps in the
catalog graph's build order (a mover's build waits for the `package-published` of each mover it has a "published
before it builds" edge to, toolchain edges first), and its end lists the movers in ADR 0666 §14's delivery order. The
pipeline passes when every mover's `required` steps passed, and fails when one did not; `pipeline-ended` is said
once, keyed by the source revision, with every mover's step results and the pipeline's outcome. A single commit is
the case of one take-in. The runner says no `group-ended`: every pipeline is per source revision. How the order of
delivery is kept once wants are written is question 3 below. Built in H1 in the runner: the pipeline key
`<branch>.<source>.<module>` becomes `<branch>.<source>`, its step keys gain the mover. How it is checked: whole
(runner): a take-in naming mesh-sdk and one importer is one pipeline whose importer builds after mesh-sdk's
`package-published`, and one `pipeline-ended` (acceptance test 112). Replaces G §44's pipeline per watched branch
of a group and G §332's `group-ended`.
- §747 **A start names an event, never a sweep or a comparison.** (ADR 0682 §5; G §12, §112; principle 1) The runner
starts a pipeline on `take-in.taken` with entries, and on `package-published` only when no pipeline of the
publishing source revision runs (a publish again of an older build, G §588): that pipeline is keyed
`<branch>.published.<package>.<version>` and its movers are the package's kind-1 dependents. A publish from a
running pipeline starts nothing; that pipeline's dependents wait for it as §746 says. A hand `start`, `run` and the
set-aside keys of A-446 stay. The sweep (`StartUnstarted`, `Unstarted`, `StartHeld` of the held pull request
mesh-delivery #262), the start-time `outdated` of G §375 and `runner_catch_up` go: the runner's durable consumer of
`package-published` delivers a publish heard after a stop. Built in H1 (runner: `Starter`, `run`'s `resume`). How
it is checked: whole (runner): a restart with modules whose fingerprint has no pipeline starts none; a publish heard
after a stop starts its dependents once.
- §748 **At most `pipelines-at-once` pipelines run.** (ADR 0682 §6; the operator, 2026-11-20 01:10 CET; principle
11) The runner's setting `pipelines-at-once` (a config key of its module, default 1, from 1 to 8) bounds the
pipelines whose steps are asked at once. A pipeline started over the bound is written with no step asked, state
`waiting`, and says `wait-held` with `step` `pipeline` and `on` `pipelines-at-once`; the runner places the waiting
pipelines oldest first, by the sequence of the event that started them, each on its own `pipeline-ended` of a running
one, with no timer, and says `wait-ended`. A waiting pipeline is progress not owed (§741). A newer pipeline never
replaces a waiting one; a mover's running steps are superseded only as G §31 says. The runner's tool `runner_waiting`
before it builds" edge to, toolchain edges first), and computes the movers' delivery order in ADR 0666 §14's order as
tiers (acting parts first, providers before their consumers; movers no edge orders share a tier). The pipeline passes
when every mover's `required` steps passed, a `required` step ending `nothing to run` counting as passed (H-A-3), and
fails when one did not. Its events (G §73) move to `mesh.seat.mesh-pipeline-runner.event.<event>.<branch>.<source>`
for `pipeline-started` and `pipeline-ended`: `pipeline-started` names `pipeline`, `branch`, `source`, `call`,
`revision` and the movers; `pipeline-ended` is said once with `pipeline`, `branch`, `source`, `call`, `revision`, the
outcome and, per mover, `module`, `fingerprint`, the released `version` (absent when none was released), its step
results and its `tier`. The step events keep their subject per module (`...<event>.<module>.<branch>.<commit>`) and
gain `pipeline`. Who hears them now: the assigner (wants, §750, §751), the gate (the record, §738), the indexer (pins,
§749), the status view, and a session, which waits on `record-opened.<call>` (§737) and then on
`pipeline-ended.<branch>.<source>`, never per module (G §74's wait per module and G-4's subject row are corrected so,
§763). The runner says no `group-ended`. Built in H1 in the runner (the key `<branch>.<source>.<module>` becomes
`<branch>.<source>`, its step keys gain the mover) and in the seat's definition. How it is checked: whole (runner):
a take-in naming mesh-sdk and one importer is one pipeline whose importer builds after mesh-sdk's
`package-published`, and one `pipeline-ended` naming both with their tiers (acceptance test 112).
- §770 **`pipeline-failed` is one finding per failing mover.** (H-A-19; ADR 0666 §24; ADR 0505 §5, §6) The runner's
finding `pipeline-failed` (G §33, §113) has id `<module>.<branch>`, one per mover whose `required` step failed or
could not run, naming the pipeline and the step, the commit's author's for two hours then the operator's; it is
cleared by that module's next passed pipeline on that branch. Built in H1 (runner). How it is checked: whole (runner):
a pipeline with two failing movers raises two findings; a later pipeline passing one clears that one.
- §747 **A start names an event, never a sweep or a comparison.** (ADR 0682 §6; H-A-19; G §12, §112; principle 1) The
runner starts a pipeline on `take-in.taken` with entries, and on `package-published`, whose body gains `branch` and
`source`, the source revision whose pipeline published: when that pipeline runs and moves the dependent, the
dependent waits in it (§746) and nothing starts; otherwise (a publish again of an older build, G §588, or a kind-1
dependent that pipeline does not move) one pipeline keyed `<branch>.<source>.published.<package>.<version>` starts,
its movers the package's kind-1 dependents it does not move. That pipeline pins the publishing source's catalog
revision and belongs to that source's delivery record (§738). A hand `start`, `run`, the runner's other verbs (ADR
0666 §10, §18, §25) and its taking up of pipelines in flight after a restart (§19) stay, as do the set-aside keys of
A-446. The sweep (`StartUnstarted`, `Unstarted`; `StartHeld` of the held pull request mesh-delivery #262), the
start-time `outdated` of G §375 and `runner_catch_up` go: the runner's durable consumer of `package-published`
delivers a publish heard after a stop. Built in H1 (runner: `Starter`, `run`'s `resume`). How it is checked: whole
(runner): a restart with modules whose fingerprint has no pipeline starts none; a publish heard after a stop starts
its dependents once.
- §748 **At most `pipelines-at-once` pipelines run; the others wait in order.** (ADR 0682 §7; H-A-14; the operator,
2026-11-20 01:10 CET; principles 3 and 11) The runner's setting `pipelines-at-once` (default 1, from 1 to 8) bounds
the pipelines whose steps are asked at once. A pipeline written over the bound gets `seq`, the next value of the
runner's own counter in its state (one key `queue.next`, written by compare-and-set), and state `waiting`, with no
step asked; it says `wait-held` with `step` `pipeline` and `on` `pipelines-at-once`. The runner places the lowest `seq`
waiting at its start, from its own state, and on every end of a running one: `pipeline-ended`, a cancel and a
set-aside alike, with no timer, and says `wait-ended`. A pipeline waiting on the operator's `approval` step does not
count against the bound, and when its approval is answered it is placed first, ahead of every `seq`. When pipelines
wait and none runs after a placing, the runner raises its finding `pipelines-stalled`, naming the first waiting, and
clears it when one runs. At most `pipelines-waiting-cap` pipelines wait (a setting, default 64): a start over it
leaves its `take-in.taken` unacknowledged, raises `queue-full`, and is taken on the next end. Superseding: a waiting
pipeline's mover that a newer waiting pipeline of the same branch also moves leaves the older one, which ends
`superseded` when no mover is left; a running pipeline runs to its end (G §31's supersession of running steps no
longer applies across pipelines). A waiting pipeline is progress not owed (§741). The runner's tool `runner_waiting`
lists the waiting pipelines in their order; `runner_place`, with a pipeline's key and `why`, places one ahead of its
turn, written in the hand-act log. Built in H1 (runner). How it is checked: whole (runner): two take-ins in a row
run one after the other, the second said waiting, with `pipelines-at-once` at 1 (acceptance test 112). This is the
bound specification C found missing.
turn, written in the hand-act log. Built in H1 (runner). How it is checked: whole (runner): two take-ins in a row run
one after the other, the second said waiting; a cancel places the next; an approval answered places first; a newer
take-in moving the same module supersedes it in the waiting one (acceptance test 112).
- §749 **A pipeline's pins are the indexer's, freed on its end.** (ADR 0666 §9; A-449a; principle 12) The indexer pins
a take-in's revision in the take-in's write (§743), and a pipeline §747 starts on its `pipeline-started`, which
carries `revision`; it frees the pin on that pipeline's `pipeline-ended`, both heard on durable consumers of its own.
At its start it judges each kept revision against the pins its own state holds, never against a count of pins
stated. The runner says no `pinned` or `freed`; §153's rule that only the gate's account says them stands. Built in
H1 (indexer: `pins.go`'s `JudgePins`; runner). How it is checked: whole (indexer): a restart while a pipeline runs
on revision 510 keeps 510. Corrects A-449 (§763).
H1 (indexer: `JudgePins`; runner). How it is checked: whole (indexer): a restart while a pipeline runs on revision
510 keeps 510. Corrects A-449 (§763).
### Questions this file leaves open
1. **A member the forge refuses after every member was judged** (a conflict appearing between the judging and the
merge, or the forge down mid-call). ADR 0682 makes the call the group; it does not say whether the landed members
are delivered. Recommendation: the call says `merge-called` with the landed members and a field `refused` naming
the rest, the gate takes the landed members in, and the forge module raises `merge-partial` naming the call, since
a landed head that is not delivered would raise `head-untaken` anyway.
2. **The seat of the composition step.** ADR 0682 §4 serves `validate` on `mesh-module-assigner` "as the step before
its composition step", while G §22 serves the composition step on `mesh-wants`. Recommendation: both steps on one
seat; which one is a seat-definition choice for the lead (principle 9).
3. **How the delivery order of §746 is kept** when A-478 ends every want hold for another module's delivery.
Recommendation: the assigner writes every mover's want at once, and each node-engine applies the wants of one
pipeline in the order `pipeline-ended` lists them (the one-machine order of A-478b, §751); nothing orders across
machines.
1. **What stays of ADR 0633 §5 for a held take-in.** ADR 0682 §4 at version 5 ends `take-in.pending`, the bound of
`take-in-waits`, `indexer_pending` and the hand acts with the pending revision; H-A-12 keeps them for a take-in held
on a full store, as §744 writes. The record and §744 must agree before H1's prepare: either the clause keeps them for
a held take-in, or §744 drops them and `head-untaken` is the only bound.
2. **Records behind three answers.** H-A-3 (`nothing to run` counts as passed), H-A-10 (wants tier by tier, §751) and
the supersession of a waiting pipeline (§748) are said to be in ADR 0682, and version 5's clauses do not say them;
§746, §748 and §751 are written from the answers.
@@ -22,142 +22,175 @@ One file of milestone H's part of [design 47](../47-delivery-from-commit-to-deli
plan's section 4, and A-434 as a line. The wake-up rule (item 9) is one rule for every delivery part and is in the
main file, *Every delivery part wakes on its inputs alone*; §762 here says which part moves onto it where.
### The want rule
- §750 **A want names the newest released version whose pipeline passed.** (ADR 0682 §7; A-478; the operator,
- §750 **A want names the newest released version whose pipeline passed.** (ADR 0682 §8, §9; A-478; the operator,
2026-11-17 about 21:45 CET; principles 2 and 7) For every machine whose assignment places module M on watched branch
B, the assigner writes `want.<node>.<M>` naming `version`, the highest version of M released on B (`version-released`)
whose pipeline's `pipeline-ended` passed; it writes it on either event, by compare-and-set on a newer version, so an
older end heard later writes nothing (G §352's state `written` keeps, per module and branch, the newest passed
version). A want names a version, never a part's digest (A-430): A-436's stand-in ends, and G §379's digests go. The
want is held for nothing else. These holds end, with their states, findings and tools: the canary and the "at most
`step` ahead" rule, every provider healthy, the grant exists, the served verb, the bus state (rule 8), the acting
part's new version first (G §266, §268, §269, §274, §276: `acting-part-late`, `assigner_waits`'s acting rows,
`assigner_release`), the dependency's `version-delivered` (G §376, A-189, A-246, A-250: `delivery-waits`,
`assigner_delivered_again`, the event `version-delivered` itself, read by nothing else), and the parts check (G §524,
the `want-parts` capability). The backup before the apply, the operator's yes on a failed backup and on a held revert
are the node-engine's and the asker's (A-478 (c); G §296, §710), never a hold of the want. Built in H1: the
assigner's want rule (`wants.go` and the want half of its pass) written again; the old holds deleted. How it is
checked: whole (assigner): a module released with a passed pipeline is wanted on every placing machine at once,
whatever build an acting part runs and whatever a dependency's delivery; a version whose pipeline failed is not
wanted; an older version's end heard after a newer one writes nothing (acceptance test 113). Replaces G §29's
per-revision want, §291, §292 in their want half, and design 47's six rules in *Where it goes*.
- §751 **The order on one machine is the node-engine's apply order.** (ADR 0682 §7; A-478b; principles 2 and 7) The
assigner writes a machine's changed wants at once. The node-engine, which applies its wants one module at a time
(R6), takes the changed ones in this order: the holder of the seat `node-backup` and the bus module first, then the
movers of one pipeline in the order its `pipeline-ended` lists them, then the rest by name, its own want last; at a
revert, the module whose take-in is reverted first. The assigner's order waits (`order.<node>.<module>.<part>` in
its state `waits`, step `placing`, G §298, A-245, A-258 to A-260) go. Why the node-engine: an order that holds a
want is the hold A-478 ends, and the node-engine is the one part that applies (principle 12). Built in H1 (node-engine
apply pass; assigner). How it is checked: whole (node-engine): wants of the bus module, the backup holder and two
movers changed at once are applied in that order.
B (the placement's branch, the registration's first by default), the assigner writes `want.<node>.<M>` naming
`version`, the highest version of M released on B (`version-released`) whose pipeline's `pipeline-ended` passed, with
`pipeline` (the pipeline's key) and `rank` (the mover's tier in it, §746); it writes it as §751 orders, by
compare-and-set on a newer version, so an older end heard later writes nothing (G §352's state `written` keeps, per
module and branch, the newest passed version). A want names a version, never a part's digest (A-430): A-436's
stand-in ends, and G §379's digests go. The one exception is a return to an earlier build: the placement's value
`build` (G §361), set through the seat `mesh-module-assigner`'s `propose` like any placement change, is read before
the rule and names the want's version (H-A-5; ADR 0682 §8). The want is held for nothing else. These holds end, with
their states, findings and tools: the canary and the "at most `step` ahead" rule, every provider healthy, the grant
exists (ADR 0429 §6), the served verb, the bus state (rule 8), the acting part's new version first (ADR 0656 §4; G
§266, §268, §269, §274, §276: `acting-part-late`, `assigner_waits`'s acting rows, `assigner_release`), the
dependency's `version-delivered` (G §376, A-189, A-246, A-250: `delivery-waits`, `assigner_delivered_again`, the event
`version-delivered`), and the parts check (G §524, the `want-parts` capability). The backup before the apply and the
operator's yes on a failed backup and on a held revert are the node-engine's and the asker's (A-478 (c); G §296,
§710); a failing new version holds on its own machine while the old runs, by its node-engine's apply (ADR 0682 §9).
Built in H1: the assigner's want rule (`wants.go` and the want half of its pass) written again; the old holds
deleted. How it is checked: whole (assigner, in mesh-delivery): a module released with a passed pipeline is wanted on
every placing machine, whatever build an acting part runs; a version whose pipeline failed is not wanted; an older
end heard after a newer one writes nothing; a placement `build` names the want's version (acceptance test 113).
Replaces G §29's per-revision want, §291 and §292 in their want half, and design 47's six rules in *Where it goes*.
- §751 **One pipeline's wants are written tier by tier.** (H-A-10; ADR 0682 §9; ADR 0666 §14; principles 3 and 7) On a
passed `pipeline-ended` the assigner writes the wants of its tier-1 movers on every placing machine; once each of them
reports `running` at that version on every present placing machine (the node-engine seat's `running`), it writes the
next tier's, and so on. Each tier has `tier-bound` (a setting of the assigner, default 30 minutes): a tier whose
movers do not all run within it ends the delivery loudly: the assigner writes no later tier, raises its finding
`tier-late`, scope `delivery`, id the pipeline, naming the movers and machines not running, and says `wanted` with
`outcome` `tier-late`, on which the gate ends the record `failed` (§738). A machine away is not waited for; it
applies its wants when back. The validate and composition steps composed the candidate against the whole graph
before any want (ADR 0682 §9). The wants of one tier are written at once. Built in H1 (assigner). How it is checked:
whole (assigner, in mesh-delivery): a pipeline of a provider and its consumer writes the consumer's want only after the
provider's `running`; a provider that never runs raises `tier-late` within the bound and writes no consumer want.
- §771 **The order on one machine is the node-engine's apply order, by rank.** (H-A-9; ADR 0682 §9; A-478b; principles
9 and 12) The node-engine, which applies its wants one module at a time (R6), takes its changed wants in this order:
the holder of the seat `node-backup` and the bus module first; then each pipeline's wants by `rank`; then the rest by
name; its own want last; at a revert, the reverted module first. It reads the order from the wants alone and consumes
no event of the runner. The assigner's order waits (`order.<node>.<module>.<part>` in its state `waits`, step
`placing`, G §298, A-245, A-258 to A-260) go. The node-engine's tool `engine_apply_order` answers the order it will
apply its changed wants in, with why; the assigner's `assigner_delivery_order` of the first version of this part is
not built. Built in H1 (node-engine apply pass; assigner). How it is checked: whole (node-engine, in `mesh-host`):
wants of the bus module, the backup holder and two movers of ranks 2 and 1 changed at once apply in that order.
- §772 **A machine away at the clean state is placed by hand when it is back.** (H-A-15; principle 2) A machine away at
milestone H1's clean state runs a node-engine that cannot read a want without digests, so the assigner keeps its wants
held, said as `held` with why `awaits its hand placement`, until its node-engine says, through the seat
`node-engine`'s capability event `manifest-reads-changed` (G §590), that it reads a want by version; when the machine
is back, its hand placement (the plan's section 5, step 5) runs before anything else on it. Built in H1 (assigner).
How it is checked: whole (assigner): a node whose node-engine lacks the capability gets no want of the new form and is
said held; live, plan step 5 reads it.
### Accounts
- §752 **Every account may call every verb.** (ADR 0682 §8; A-434; principle 6) Until a record on the mesh's
accounts says otherwise, the grants part grants every module's account every verb and every event; no seat
definition names callers, and the `callers` lists of every seat contract go (G §610's class defaults are not built).
Acceptance tests 40, 51 (its callers row) and 85 are not checked while this holds. Built in H1 (seat contracts in
mesh-contracts and mesh-delivery-contracts; grants part). How it is checked: unit (seat definition reader: a
definition naming callers is refused); whole (grants part): a module calls a verb its manifest does not invoke and
is answered.
- §752 **Every account may call every verb; a module publishes only what it declares.** (ADR 0682 §10; A-434, H-A-11;
ADR 0666 §21; principle 6) The grants part grants every module's account every verb and every subscription; it grants
a module's account publication only of the events, step results and state its manifest declares (ADR 0666 §21 stays),
and an enrolling node's account keeps its own grant. No seat definition names callers, and the `callers` lists of
every seat contract go (G §610's class defaults are not built); approval marks stay. Acceptance tests 40, 51 (its
callers row) and 85 are not checked. Built in H1 (seat contracts in mesh-contracts and mesh-delivery-contracts; the
grants part). How it is checked: unit (seat definition reader: a definition naming callers is refused); whole (grants
part, in mesh-delivery): a module calls a verb its manifest does not invoke and is answered; it publishes an event
its manifest does not declare and is refused; an enrolling node's account is held to its grant (acceptance test 118).
### Builds and the builder
- §753 **A build module takes deliveries first.** (ADR 0525 §4; G §86) Each build module pulls its delivery queue
- §753 **A build module takes deliveries first.** (ADR 0525 §4; G §86; H-A-8) Each build module pulls its delivery queue
first, then its check queue, then its recheck queue, taking from a later queue only while the earlier is empty, and
waits on the bus's pull with no idle re-pull: the five-second idle pull of the shared step runner in
mesh-delivery-sdk goes. The turns the code takes today cite an operator's yes of 2026-11-15 that no record holds
(asked of the knowledge base on 2026-11-20): ADR 0525 §4 is in force, so the line follows it. Built in H2
(mesh-delivery-sdk's step runner, `buildrun`). How it is checked: whole (Go build module): with three queues full
the delivery asks run first.
mesh-delivery-sdk goes. The turns the code takes today cite an operator's yes of 2026-11-15 that no record holds; if
H2's prepare finds it, ADR 0525 gets an insight. Built in H2 (mesh-delivery-sdk's step runner, `buildrun`). How it is
checked: whole (Go build module, in mesh-catalog): with three queues full the delivery asks run first (acceptance
test 119).
- §754 **A done build with no reservation is reserved by the builder itself.** (G §369, A-455; principle 3) When the
runner's build step asks a fingerprint whose build is done and carries no reserved version (a build made before
reservations, or one whose reservation was lost), the builder reserves the next version for it at that ask, as
`builder_reserve_done` does by hand, says it in its journal and in the step's end, and answers the step carried.
Nothing else reserves an old build: the builder looks for none by itself. Built in H2 (builder: its reserver and the
look that writes "done build no version reserved"). How it is checked: whole (builder): a build step for a done,
unreserved fingerprint ends carried with a version.
runner's build step asks a fingerprint whose build is done and carries no reserved version, the builder reserves the
next version for it at that ask, says it in its journal and in the step's end, and answers the step carried. Nothing
else reserves an old build. Built in H2 (builder: its reserver, and the look that writes "done build no version
reserved", which goes). How it is checked: whole (builder, in mesh-delivery): a build step for a done, unreserved
fingerprint ends carried with a version (acceptance test 119).
- §755 **A failed fingerprint built again keeps its reservation.** (G §369, A-490b; principle 7) When a key is built
again (by a step ask, an event or `builder_build_again`), the reserver takes that key's own standing reservation as
its number; a key with none takes one above the higher of the highest released and the highest any other key
reserved. No number is skipped. Built in H2 (builder's reserver). How it is checked: unit (reserver): a failed
0.1.19 built again is 0.1.19.
again (a step ask, an event or `builder_build_again`), the reserver takes that key's own standing reservation as its
number; a key with none takes one above the higher of the highest released and the highest any other key reserved.
No number is skipped. Built in H2 (builder's reserver). How it is checked: unit (reserver): a failed 0.1.19 built
again is 0.1.19; acceptance test 119.
- §756 **A build is entered only by the runner's build step.** (G §473, A-97) The builder builds only what a pipeline's
build step asks: it builds no catalog entry it hears and follows no gate `source`; the pre-G numbering beside the
reservations (design 51's, replaced) goes, with its floor wait. `build.ended` carries the reserved `version`
(A-430b), for every watched branch. Built in H2 (builder). How it is checked: whole (builder): a catalog entry heard
with no step ask builds nothing; `build.ended` names its version.
- §757 **The steps a mover can run are asked at every pipeline.** (ADR 0666 §7; G §8, §22) At each pipeline's start the
runner asks each build seat's `steps` for each mover's artifacts, never only at the seed; a step the answer says
has nothing to do ends `nothing to run`. Whether a `required` step ending so holds the delivery is question 1
below. Built in H2 (runner). How it is checked: whole (runner): a library module whose unit tests vanish ends that
step `nothing to run` at its next pipeline.
reservations goes, with its floor wait. `build.ended` carries the reserved `version` (A-430b), for every watched
branch. Built in H2 (builder). How it is checked: whole (builder): a catalog entry heard with no step ask builds
nothing; `build.ended` names its version (acceptance test 119).
- §757 **The steps a mover can run are asked at every pipeline.** (ADR 0666 §7; G §8, §22; H-A-3) At each pipeline's
start the runner asks each build seat's `steps` for each mover's artifacts, never only at the seed; a step the answer
says has nothing to do ends `nothing to run`, which counts as passed for the pipeline (§746). Built in H2 (runner).
How it is checked: whole (runner): a library module whose unit tests vanish ends that step `nothing to run` and its
pipeline passes (acceptance test 119).
- §758 **A registration whose pipeline would have no step is refused.** (ADR 0666 §2; acceptance test 67) `register`
and `policy` refuse a registration whose policy, read against the build seats' `steps` for its artifacts, leaves no
step that runs, naming each artifact and step. A package module with no registration has no pipeline and is never
built; the seed (A-441) registers every package module the graph holds, `mesh-delivery-sdk` among them. Built in H2
(indexer: `register`, `policy`, the seed). How it is checked: whole (indexer): a registration with every step
`bypass` is refused naming them.
`bypass` is refused naming them (acceptance test 119).
### Reads of another part's data become its events and verbs
- §759 **The status view, the watchman and the grants part read no other part's bus state.** (ADR 0596 §2, §4;
principles 1 and 9) Each read of another module's bucket becomes the owner's event, and for a first view the
owner's seat verb:
- **the status view's twelve bucket watches**, each retried every five seconds: the node-engine's `have` becomes the
seat `node-engine`'s event `running`; the watchman's `presence` and `stuck` become the seat `mesh-watchdogs`'
verbs `presence` and `stuck` and the findings it says (`*.finding-written`, `*.finding-cleared`, G §386's form);
the builder's `builds` becomes the seat `mesh-builds`' `build.ended`; the indexer's `taken` becomes
`take-in.taken`; the indexer's `candidates` and the teller's `answers` go with their uses (G §512). Built in H4.
- **the watchman's** read of the provisioner's `provisions` and its watch of the grants part's bucket. Built in H4.
- **the grants part's** reads of the node-engine's `have`, the vault's `bus-accounts` and `node-logins`, the
enrolment module's `enrolments` and mesh-config's `resolved`, and its calls of the bus module by module name,
which become the seat `mesh-broker`'s verbs. Built in H4b.
A read whose owner says no event for it today stops that subtask as a design question for the lead (question 2
below lists the ones known). How it is checked: unit (each manifest declares no `reads` of another module); whole
(view, watchman, grants part) against the owners' events.
- §759 **The status view and the watchman read no other part's bus state.** (ADR 0596 §2, §4; principles 1 and 9)
Each read of another module's bucket becomes the owner's event, and the first view the owner's seat verb, in H4:
the node-engine's `have` becomes the seat `node-engine`'s event `running` and, for the first view, the verb `haves`
the seat gains (what the node runs per module, from its own state); the builder's `builds` becomes the seat
`mesh-builds`' `build.ended` and the verb `builds` with `since`; the indexer's `taken` becomes `take-in.taken` and the
seat `mesh-catalog`'s verb `revision`; the watchman's `presence` and `stuck` become the seat `mesh-watchdogs`' verbs
`presence` and `stuck` and the findings it says (`*.finding-written`, `*.finding-cleared`, G §386's form); the
indexer's `candidates` and the teller's `answers` go with their uses (G §512). The watchman's read of the
provisioner's `provisions` becomes §773's event. Every other bucket watch of the view the H4 prepare lists against an
owner's event; one with none stops that subtask for the lead. How it is checked: unit (each manifest declares no
`reads` of another module); whole (view, watchman, in mesh-delivery) against the owners' events.
- §773 **Four owners say their changes as events, for H4b.** (H-A-4; ADR 0596; principle 1) Each is a seat event kept
on its seat's stream for 7 days (a setting of its owner), with a first-view verb; until H4b builds them, the reads
they replace stand and are named leftovers in the gap table:
- the seat `mesh-provisioner`: `provision-changed` on `mesh.seat.mesh-provisioner.event.provision-changed.<provision>`,
body `{provision, reference, state, at}`; first view its verb `provisions`;
- the seat `mesh-vault`: `account-changed` on `mesh.seat.mesh-vault.event.account-changed.<user>`, body `{user, hash,
at}`, and `node-login-changed` on `...node-login-changed.<node>`, body `{node, hash, at}`; first view its verbs
`accounts` and `node-logins`;
- the seat `mesh-grants`: `user-list-changed` on `mesh.seat.mesh-grants.event.user-list-changed`, body `{revision,
users, at}`, consumed by the bus node's agent in place of its watch of the key `user-list`; first view its verb
`user-list`;
- the enrolment module: `enrolment-changed`, body `{node, state, at}` (its seat is question 1 below).
The grants part then consumes them, and calls the bus module only through the seat `mesh-broker`'s verbs (`list`,
`show`, and `users` and `streams`, which the seat gains in place of the module tools `nats_users` and `nats_streams`
the grants part calls today). Built in H4b. How it is checked: unit (the owners' seat definitions); whole (grants
part): a changed account reaches the user list with no read of the vault's bucket.
- §760 **Rates on the bus are read on the seat `mesh-broker`.** (ADR 0595 §5; principle 4) The seat `mesh-broker`
gains the read verb `rates`, with `window` (seconds, default 10, from 1 to 60): it reads the bus server's counters of
each connection and each stream twice, `window` apart, within the call, and answers per connection (its account's
module and node) and per stream the messages and bytes in and out per second, and the slow consumers counted, its
call bounded at `window` plus 5 seconds. Built in H4 (seat definition in mesh-contracts; the bus module). How it is
checked: whole (bus module): a fixture publishing 100 messages a second reads about 100.
module and node) and per stream the messages and bytes in and out per second, and the slow consumers counted. Its call
is bounded at `window` plus 5 seconds, at most 65 seconds, which must sit inside the tool runner's call timeout
(question 2 below). Built in H4 (seat definition in mesh-contracts; the bus
module). How it is checked: whole (bus module): a fixture publishing 100 messages a second reads between 90 and 110.
### The read tools found missing
- §761 **One revision, narrowed, and its differences, in the indexer.** (ADR 0666 §25; principle 4; one-question-one-tool)
The indexer gains the tools `indexer_revision` (`branch`, `revision`, optional `module` and `kind`: one catalog
revision of any watched branch, narrowed to a module's entries and edges or to one edge kind), `indexer_difference`
(`branch`, `from`, `to`: the modules and edges that differ), `indexer_build_order` (`branch`, `modules`: the order
the catalog graph's build edges give, its cycles named) and `indexer_built_from` (`fingerprint`: the source revision
and commit it was taken in at); `indexer_edges` (G §380) gains `kind`. The assigner gains `assigner_delivery_order`
(`node`, optional `modules`: the order §751 applies on that machine), and the node-engine `engine_build` (its own
fingerprint, version and commit). An answer over the bus's per-message limit is an object's name (ADR 0666 §16).
The callers of tools no part serves go with their callers: the checker's of `indexer_read_candidates` (it goes,
§764), and the health checks' and the first views' of `indexer_read_modules`. Built in H4. How it is checked: unit
(each tool's answer); the principle-4 table of each module's pull request.
- §762 **Every delivery part moves onto the wake-up shape.** (ADR 0682 §9; main file, *Every delivery part wakes on
- §761 **One revision, narrowed, and its differences, in the indexer.** (ADR 0666 §25; principle 4) The indexer gains
the tools `indexer_revision` (`branch`, `revision`, optional `module` and `kind`: one catalog revision of any watched
branch, narrowed to a module's entries and edges or to one edge kind), `indexer_difference` (`branch`, `from`, `to`:
the modules and edges that differ), `indexer_build_order` (`branch`, `modules`: the order the build edges give, its
cycles named) and `indexer_built_from` (`fingerprint`: the source revision and commit it was taken in at);
`indexer_edges` (G §380) gains `kind`. The node-engine's `engine_build` answers its own fingerprint, version and
commit, and `engine_apply_order` is §771's. An answer over the bus's per-message limit is an object's name (ADR 0666
§16). The callers of tools no part serves go: the checker's of `indexer_read_candidates` (it goes, §764), and the
health checks' and the first views' of `indexer_read_modules`. Built in H4. How it is checked: unit (each tool's
answer); the principle-4 table of each module's pull request.
- §762 **Every delivery part moves onto the wake-up shape.** (ADR 0682 §11; main file, *Every delivery part wakes on
its inputs alone*) The parts and what goes, from the gap table of 2026-11-20 (part F, question 2): mesh-config's
key-by-key pass, five-minute sweep and minute's read (`sources`, the held pull request mesh-catalog #708, H1); the
grants part's whole recompose (`Compose`, H4b); the indexer's re-read of every module, graph key and manifest after
each write (`KeepView`, `viewEntries`, `heldModules`, H4); the builder's start sweep and `builder_stuck`'s read of
every key (`Sweep`, the stuck read: it answers from the builder's own index of what builds, H4); the assigner's input
sweep and its ten-second poll of `backed-up` (`inputKeeper.sweep`, `snapshotTheBus`, H4); the watchman's
five-minute recount of dead letters (H4); the build modules' stale round and idle pull (`EndStaleRound`, §753, H2);
mesh-sdk's first view asked again with a backoff (`views` reader, H4); the view's five-second retries (§759, H4); the
forge module's one-minute poll and ten-minute timer (H3). The decided pulses (G §496's minute of `step-progress`,
G §606) are real deadlines and stay. How it is checked: as the main file's rule says.
every key (`Sweep`; it answers from the builder's own index of what builds, H4); the assigner's input sweep and its
ten-second poll of `backed-up` (`inputKeeper.sweep`, `snapshotTheBus`, H4); the watchman's five-minute recount of
dead letters (H4); the build modules' stale round and idle pull (`EndStaleRound`, §753, H2); mesh-sdk's first view
asked again with a backoff (`views` reader, H4); the view's five-second retries (§759, H4); the forge module's
one-minute poll and ten-minute timer (H3). The decided pulses (G §496's minute of `step-progress`, G §606) are real
deadlines and stay. Its cost: the shape lives in mesh-sdk's state package, so its release rebuilds nearly every
module (every module that imports that package, about 120 by the graph of 2026-11-20); it is carried by H4 alone, one
release, delivered by the pipelines of the movers it names. How it is checked: as the main file's rule says.
### Questions this file leaves open
1. **A `required` step ending `nothing to run`.** ADR 0666 §9 lets a want follow only a revision whose `required` steps
passed, and G §22 says `nothing to run` is never passed, so such a module is held for good (specification D,
question 3). Recommendation: a `required` step that ends `nothing to run` holds nothing in that pipeline, as the
seed's `bypass` does, since it ran everything the module has; it needs a clause, since ADR 0666 §9 says "passed".
2. **Reads whose owner says no event today**: the watchman's of the provisioner's `provisions`, the grants part's of
the vault's `bus-accounts` and `node-logins` and of the enrolment module's `enrolments`, and the agent's watch of
the grants part's `user-list` (ADR 0547 §7, §9). Recommendation: each owner says a change event of its own (the
provisioner `provision-changed`, the vault `account-changed`, the enrolment module `enrolled`, the grants part
`user-list-changed`) and answers its first view by a read verb; these are four records' clauses (ADR 0547 §7, §9 are
in force), not lines this file can write.
1. **The enrolment module's seat** for `enrolment-changed` and its first view (§773): no record or answer names it.
Recommendation: the seat the enrolment module claims in its manifest, read by H4b's prepare and written here then.
2. **The tool runner's call timeout for `rates`.** §760's call takes up to 65 seconds; no line says the tool runner's
timeout per verb or whether a seat definition can raise it. Recommendation: a verb's definition names its bound and
the tool runner waits that bound plus 5 seconds, a seat-definition field the H4 prepare checks exists.
@@ -10,7 +10,7 @@ decisions:
- "ADR 0667"
- "ADR 0666"
- "ADR 0633"
- "ADR 0548"
- "ADR 0595"
---
# 47, milestone H: the corrections made in place, the stale state, and what retires
@@ -21,64 +21,98 @@ One file of milestone H's part of [design 47](../47-delivery-from-commit-to-deli
- §763 **The small contradictions are corrected in place.** (plan item 10; each line names its source) These lines of
milestone G and the main file now say what holds, each marked "corrected in place by design 47 H §763":
- G §5: `register` and `watch` refuse no unprotected branch (the operator, 2026-11-14, G-23 *Met during G's start*).
ADR 0666 §3 still states the refusal: a clause owed, named in the report of this amendment.
ADR 0666 §3 still states the refusal: a clause owed.
- G §654: mesh-config consumes no pull request event and calls no `git.pull` (ADR 0681 §1).
- A-449 and A-449a: the runner says no `pinned` or `freed`; the indexer pins and frees a pipeline's revision (§749).
- Acceptance test 53: its `forge-made` and checker rows go (G §151; §740; the checker goes).
- G §476 and §648: `take-in.taken` carries one entry per mover, `{module, commit, fingerprint, repository}`, no
`pull` (§743).
- G §40: the operator channel keeps no count of open asks per asker (A-424, the operator, 2026-11-15). ADR 0666 §12
still says three: a clause owed, named in the report.
still says three: a clause owed.
- G §386: the grants part makes one durable consumer per process that hears a `*` event, named as A-397 names it.
- G §73's subject table and G-4's row of the runner's events, and G §74's wait per module: `pipeline-started` and
`pipeline-ended` are said per source revision and waited for so (§746).
How it is checked: hq's review of this amendment reads each corrected line against its source.
- §764 **What retires at milestone H's delivery.** (ADR 0682 §1, §2, §3, §5, §7; ADR 0681; ADR 0667 §12) Each
is removed in the release named, with its code, its state (dropped by §765 where it holds keys), its tools, its
events in the seat definitions, and its tests; nothing of it is kept unread.
- §764 **What retires at milestone H's delivery.** (ADR 0682 §1 to §4, §6, §8, §9; ADR 0681; ADR 0667 §12) Each is
removed in the release named, with its code, its state (dropped by §765), its tools, its events in the seat
definitions, its readers and its tests; nothing of it is kept unread.
- **The forge module (H1, H3):** the single-pull form of `merge-pull` (§734); the merge-check machinery: the
`mesh/merge-gate` pending statuses, the weighing of trunk and sibling moves (`announceHead`, `passPulls`,
`trunksMoved`, `siblingMoves`, `GateWriter`) and its files on disk, its one-minute poll and ten-minute timer (H3).
- **The forge bridge (H1):** the messages `merged` and `pushed` and their `base` (§739); its state `inputs` and its
read of trees; its call of `git.pull` for a merged commit; the group it sets on a member, `forge.group.merged`,
`bridge_groups` and `bridge_group_end_again` (G §43, §45, §157, §715); its hearing of the checker's `owed` and the
merge act of a switched key (`OwedActMerge`, its `invokes` of `seat:git.merge-pull`, G §510).
The forge's branch protections drop the required statuses `mesh/merge-gate` and `mesh/repo-check` in H1, through
the forge module's protection setting, so no merge waits on a status nothing writes (H-A-15).
- **The forge bridge (H1):** the messages `merged` and `pushed` and their `base` (§739), with their readers, the
indexer's take-in and the gate's `ForgeMerged`; its state `inputs` and its read of trees; its call of `git.pull`
for a merged commit; the group it sets on a member, `forge.group.merged`, `bridge_groups` and
`bridge_group_end_again` (G §43, §45, §157, §715); its hearing of the checker's `owed` and the merge act of a
switched key (`OwedActMerge`, its `invokes` of `seat:git.merge-pull`, G §510).
- **The gate (H1, H3):** the source per merged message (A-464 to A-464e: `ForgeMerged`, `moveHead`,
`gate_source_follow`, the start's comparison with the forge's heads) and its consumption of the bridge's `merged`
(G §592's rule now holds); the source moved on `take-in.taken` (A-34; §737); the groups from a branch name (G §42,
§716, A-279): its states `deliveries` and `groups`, its consumption of `pull-updated`, `pull-merged` and
`pull-closed`, its start reconciliation through `open-pulls` and `pull`, and the verb `groups` (the verbs
`deliveries` and `show` answer from the records, A-24); the switch and the carried approval (G §156, §169, §542,
A-281: `approval-carried`, `approval-carried-open`), since §765 drops what they carried; the states `merges`,
`owed` (the old bucket), `asks`, `pulls` and `turns`, and the seat definition's entries for them.
`gate_source_follow`, the start's comparison with the forge's heads) and its consumption of the bridge's `merged`;
the source moved on `take-in.taken` (A-34; §737); the groups from a branch name (G §42, §716, A-279): its states
`deliveries` and `groups`, its consumption of `pull-updated`, `pull-merged` and `pull-closed`, its start
reconciliation through `open-pulls` and `pull`, and the verb `groups` (the verbs `deliveries` and `show` answer
from the records, A-24); the switch and the carried approval (G §156, §169, §542, A-281: `approval-carried`,
`approval-carried-open`); the states `merges`, `owed` (the old bucket), `asks`, `pulls` and `turns`, and the seat
definition's entries for them.
- **The indexer (H1):** the take-in fed by the bridge's messages; the state `pending` with its keys `m.<sequence>`
and `g.<group>`; the hold for the indexer a revision names and its hand acts (ADR 0633 §1, the main file's *Taken in
by the indexer it names*; `indexer_take_in_pending`, `indexer_drop_pending`); the validation at the take-in
(G §16, §19, §237, §712, §713; A-475, A-475a), which becomes §745's step; its events `manifest-refused` and
`manifest-accepted`; the catch-up by comparison (A-463, A-463a, A-490k, G §177's first-start half, G §362:
`kickBehind`, `TakeInBehind`, `sayUntaken`, `takeInHeads`, `kickCatchUp`, `CatchUp`) and its condition
`merge-untaken`; the source numbering in memory (A-431, `nextSource`); the 30-minute group wait of `take-in-waits`;
the field `pull`; mesh-config's config candidates (ADR 0681 §2).
- **The runner (H1):** the sweep (`StartUnstarted`, `Unstarted`; `StartHeld` of mesh-delivery #262, closed unmerged);
the start-time `outdated` (G §375) and `runner_catch_up`, never built; `group-ended` (G §332) and its stream; the
pipeline key per module; its `pinned` and `freed`.
and `g.<group>`; the hold for the indexer a revision names (ADR 0633 §1, the main file's *Taken in by the indexer it
names*) and `indexer_drop_pending`; the validation at the take-in (G §16, §19, §237, §712, §713; A-475, A-475a),
which becomes §745's step; its events `manifest-refused` and `manifest-accepted`, with their reader, the watchman's
findings `manifest-refused` and `manifest-outgrown` raised from them; the catch-up by comparison (A-463, A-463a,
A-490k, G §177's first-start half, G §362: `kickBehind`, `TakeInBehind`, `sayUntaken`, `takeInHeads`,
`kickCatchUp`, `CatchUp`) and its condition `merge-untaken`; the source numbering in memory (A-431,
`nextSource`); the 30-minute group wait of `take-in-waits`; the field `pull`; the config candidates (ADR 0681 §2).
- **The runner (H1):** the sweep (`StartUnstarted`, `Unstarted`; `StartHeld` of mesh-delivery #262, closed
unmerged); the start-time `outdated` (G §375) and `runner_catch_up`, never built; `group-ended` (G §332) and its
stream `SEAT_mesh-pipeline-runner_group-ended`; the pipeline key per module; its `pinned` and `freed`.
- **The assigner (H1):** the holds §750 names, with `acting-part-late`, `delivery-waits`, `version-delivered`,
`assigner_delivered_again`, the acting rows of `assigner_waits` and `assigner_release`, the order waits (§751), the
parts check and the `want-parts` capability, and A-436's digests in a want.
`assigner_delivered_again`, the acting rows of `assigner_waits` and `assigner_release`; the order waits
(`order.<node>.<module>.<part>` in its state `waits`, §771); the parts check and the `want-parts` capability; A-436's
digests in a want.
- **mesh-config (H1):** its pull request path (ADR 0681 §1, §7) and A-490l's pull sweep.
- **The checker (H1):** `mesh-delivery-checker` whole, with its verdict verb, its calls of
`indexer_read_candidates`, `mesh/check` and its try; it is not placed at the clean state, and its buckets and bus
account go with §765 on the operator's word of 2026-11-20 (ADR 0667 §12).
`indexer_read_candidates`, `mesh/check` and its try; it is not placed at the clean state.
- **Every seat contract (H1):** the `callers` lists (§752).
- **Acceptance tests:** 38, 49, 81, 82, 105 and 106 as written; tests 110 to 113 hold what remains of them, and test
- **Acceptance tests:** 38, 49, 81, 82, 105 and 106 as written; tests 110 to 119 hold what remains of them, and test
67 is read with a merge call naming its three repositories.
How it is checked: after each release, a search of the trunks of mesh-catalog, mesh-delivery, mesh-sdk,
mesh-contracts, `mesh-host` and mesh-tools for each name above finds it in no file outside tests that assert its
absence, and `mesh-broker.list` shows no bucket of a state above.
- §765 **The stale state of the earlier model goes once, at the clean state.** (ADR 0682 §10; the operator,
absence, and `mesh-broker.list` shows no bucket or stream of a state above.
- §765 **The stale state goes once, after the new programs run.** (ADR 0682 §12; H-A-15, H-A-19; the operator,
2026-11-20 about 01:10 CET: "I don't care about old data at this moment, I want a working mesh again") At milestone
H1's clean state (the plan's section 5, step 4): the gate's buckets `merges`, `owed`, `asks`, `pulls` and `turns`
and its 833 open records; the indexer's pins that name no running pipeline; the pipelines of the earlier model still
running; every held or failed want; the checker's buckets. Each goes as ADR 0595 §4 removes kept data, on that word:
through its module's tool where one exists, otherwise, once no running module declares the state (an orphan
`orphans` lists), through the seat `mesh-broker`'s `drop` after its stream snapshot, the pack saying what it
deleted, counted. The delivery records of the one model start from the clean state. How it is checked: the lead reads
`mesh-broker.list` and each module's read tools before and after, and quotes the counts.
H1's clean state, after the new programs run on every present machine (the plan's section 5, after step 5.6) and
before the runner starts, every state §764 retires goes, and with it: the gate's 833 open records; the indexer's pins
that name no running pipeline; the pipelines of the earlier model; the stopped runner's queue of `take-in.taken` of
the old form, with the consumer that holds it; every held or failed want. Each goes as ADR 0595 §4 removes kept data,
on that word, through the tool named for it: a record through `gate_record_end`, a pin through the indexer's
`indexer_pin_drop` (with `key` and `why`, which H1 adds), a pipeline through the runner's `cancel`, a held or failed
want through the assigner's `assigner_want_drop` (with `node`, `module` and `why`, which H1 adds), and every retired
state, once no running module declares it (an orphan `orphans` lists), through the seat `mesh-broker`'s `drop`. The
bus module's stream snapshot taken before the first drop is the rollback. The pack says what it deleted, counted.
Every durable consumer the new programs make starts at the newest message of its stream and refuses an event of the
old form (one with no field its new form requires) with a journal line naming it. The delivery records of the one
model start from the clean state. How it is checked: the lead reads `mesh-broker.list` and each module's read tools
before and after, and quotes the counts; the snapshot's restore is tested before the first drop (ADR 0595 §4).
- §774 **Tests per module, against the budget, and where H1's run before its merge.** (H-A-16, H-A-17; the test
budget, 50 integration and 500 unit tests per module) Each acceptance test of H is one whole test per module, in that
module's repository (tests 110 to 119 name which); the chain of test 110 is the live proof. The counts, read from the
gap tables of 2026-11-20 (unit, then integration), and what H adds:
| module | today | H adds (whole tests) | H retires |
|---|---|---|---|
| forge module (seat `git`) | 177 Go and 196 TypeScript, 1 | 1 TypeScript whole test of the seat `git` (§734 to §736, §766, §767; tests 114, 115) | the merge-check machinery's tests |
| forge bridge | 45, 8 | none: its whole test is rewritten for `head-moved` | the `merged`, `pushed`, group and owed-merge tests |
| gate | 38, 2 | 1 (the merge call, the record, the watchdog; tests 110, 111) | the source-follow, group and switch tests |
| indexer | 194, 13 | none: its whole test is rewritten for the take-in (tests 112, 116) | the pending, catch-up, validation and group tests |
| runner | 78, 3 | 1 (the queue; test 112) | the sweep's tests and `group-ended`'s |
| assigner | 126, 13 | none: its whole test is rewritten for §750 and §751 (tests 113, 117) | `TestEachRuleHoldsTheWantBack` and the hold tests |
| node-engine | 1,719, 10 | 1 (the apply order; test 113) | the want-parts tests; over the unit budget, every H change to it deletes at least as many unit tests as it adds |
| grants part | 78, 1 | none: its whole test gains §752's cases (test 118) | — |
| builder | 154, 18 | none: its whole test gains §754 to §756 (test 119) | the pre-G numbering's tests |
| tool runner | 152, 7 | 1 that starts it whole (H-A-16's gap) | — |
Every module stays within 50 integration tests; acceptance tests 38, 49, 81, 82, 105 and 106 retire (§764). Before
H1's merge its integration tests are run once locally against an embedded bus, and each pull request says so; the
chain's live proof (the plan's section 5, step 7) is H1's check, and from H1 on the pipeline makes the check
(H-A-16, a rule weighed and said). How it is checked: each pull request of H states its module's counts against the
budget; the review refuses a count over it.
@@ -38,12 +38,13 @@ before any code is written.
- [H-1-the-merge-call-and-the-take-in](H-1-the-merge-call-and-the-take-in.md): the merge call, the gate's source
revision and record, the forge bridge's one message and the watchdog, the take-in, the step `validate`, one pipeline
per take-in and none in parallel, a pipeline's pins (§734 to §749).
per take-in and none in parallel, a pipeline's pins, the clean state's seed (§734 to §749, §766 to §770).
- [H-2-wants-builds-reads-and-tools](H-2-wants-builds-reads-and-tools.md): the want rule, the order on one machine,
every account may call every verb, the builder's lines, the reads of other parts made events, rates on the bus, the
missing read tools, and which part moves onto the wake-up shape in which release (§750 to §762).
missing read tools, which part moves onto the wake-up shape in which release, the four owners' events and a machine
away at the clean state (§750 to §762, §771 to §773).
- [H-3-corrections-and-what-retires](H-3-corrections-and-what-retires.md): the contradictions corrected in place, what
retires, and the stale state dropped once (§763 to §765).
retires, the stale state dropped once, and the tests per module against the budget (§763 to §765, §774).
The wake-up rule itself is in the main file, *Every delivery part wakes on its inputs alone*. Where an H line and a G
line or lead's answer differ, the H line holds, and the G line it corrects in place says so.
@@ -380,10 +381,8 @@ next:
stopped runner starts nothing; the indexer takes the commits in and the gate follows.
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. **Drop the stale state** (question 2's yes): the buckets, the records, the pins, the stuck pipelines, the held and
failed wants, through each module's tools where one exists (the surveyor found none for the bucket contents; the
pack carries the one-off deletion and says what it deleted, counted). The drop-ins are removed and the units the
node-engine writes take their place as the wants compose.
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.
5. **Place the programs** in the order the graph gives (derived by the reader of 00:54 CET from the package,
toolchain and provision edges; no tool answers it yet), each step read with the tools before the next:
1. keep the bus, the forge and the image registry running; make the bus module's have `running` (else the
@@ -400,12 +399,20 @@ next:
6. place the watchman, the status view, the teller, the grants part and the hand-act log on the control node;
the checker is not placed (it goes, section 1);
7. after each machine, read its health, its first views, its `process-builds` against its haves, and the bus's
consumers.
consumers;
8. **drop the stale state** (question 2's yes), now that the new programs run: every state design 47 H §764
retires, the records, the pins, the pipelines of the earlier model, the stopped runner's queue of old
`take-in.taken`, the held and failed wants, each through the tool H §765 names, the pack saying what it
deleted, counted;
9. **seed every watched branch's first source revision** with `gate_source_seed` (H §768): each branch's current
heads, taken in with no mover, so the newest catalog revision names them; read and counted, and a bridge
restart then raises no `head-untaken`;
10. a machine away at this moment gets its hand placement when it is back, before anything else (H §772).
6. **Start the runner last**, with `pipelines-at-once` at 1.
7. **Prove it.** One single-module change (a comment in a module with lint, unit and composition steps only), merged
to main, followed from `take-in.taken` through `pipeline-ended` to the node-engine's `running` and the gate's
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), the same way. Each proof read with the tools and quoted with its times.
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.
## 6. The milestones after the clean state