Design 47 and the glossary: the reviewer's findings (three work queues, a feature in one repository, what-if, ADR 0406 clause numbers, backups by protection, no suite-time claim, the Go module's judge account)

2026-10-16 23:44:59 +02:00
parent 6f0db74ee4
commit aa4bfe289e
2 changed files with 20 additions and 18 deletions
@@ -409,8 +409,9 @@ planner, the rollout). **Downstream of** Module, Core, Health and repair and Dat
  **builder**. Any node may hold the seat, so there is no build node by nature
  (ADR 0237).
  *Not:* ~~build machine~~
- **build queue** — the builds waiting to run, kept by the bus as two work queues: delivery builds, which every
-  builder takes first, and checks, one per pull request, the newest kept (ADR 0406); one entry in it is a
+- **build queue** — the builds waiting to run, kept by the bus as three work queues a builder takes in order:
+  delivery builds, then checks of pull requests marked ready, then every other check; each check queue keeps one
+  request per pull request, the newest (ADR 0406); one entry in it is a
  **build request**.
  The queue's verbs still say *ask* for an entry; the conversation's ask is another thing
  (see [Homonyms](#homonyms)).
@@ -454,8 +455,9 @@ planner, the rollout). **Downstream of** Module, Core, Health and repair and Dat
  repositories, delivered as one unit in an order declared (`after:`) or inferred by the planner. One
  level: a group holds deliveries, never groups. Its state is derived from its members, never set.
 - **hotfix** — one pull request in one repository, delivered at its merge (ADR 0401).
- **feature** — one branch name across its repositories, whose pull requests are one delivery group, merged and
-  delivered as one (ADR 0401). Work is never held back on a branch other than a trunk: the trunk is what runs.
+- **feature** — one branch name across its repositories: in two or more, its pull requests are one delivery group,
+  merged together and delivered member by member in the group's order; in one, a single pull request delivered as a
+  lone delivery (ADR 0401). Work is never held back on a branch other than a trunk: the trunk is what runs.
  *Not:* ~~release branch~~ (hq)
 - **toolchain** — a language's compiler and tools, installed by that language's build module on every node holding
  the build seat, pinned to one version that is the same on every builder; its version is part of a build's reuse
@@ -41,8 +41,8 @@ decisions:
 # 47 — Delivery: from a commit to delivered

 **A change reaches the machines in one of three ways, all owned by mesh-delivery: a hotfix (one pull request,
-delivered at its merge), a feature (one branch name across its repositories, merged and delivered as one
-delivery group), or an epic (a run of milestones, each delivered as a feature). The trunk is what runs; there
+delivered at its merge), a feature (one branch name across its repositories: in two or more, one delivery
+group merged together and delivered member by member in its order; in one, a lone delivery), or an epic (a run of milestones, each delivered as a feature). The trunk is what runs; there
 is no "release branch"** (ADR 0401).

 **Every step starts on an event, and the state lives on the bus.** The forge's events, the controller's
@@ -95,7 +95,7 @@ controller's delivery tables and the timers that polled them.
 | Way | What it is | How it is delivered |
 |---|---|---|
 | **hotfix** | one pull request in one repository | at its merge, as a lone delivery; a lone merge is cut at once (ADR 0282 §2, as ADR 0304 §1 changed it) |
-| **feature** | one branch name across its repositories; its pull requests are one delivery group | merged together once the group's composed check passes and every member is marked ready, then delivered in the group's order |
+| **feature** | one branch name across its repositories; in two or more, its pull requests are one delivery group; in one, a single pull request | a group is merged together once its composed check passes and every member is marked, reviewed and approved, then delivered member by member in its order (ADR 0239 §16); in one repository, as a lone delivery like a hotfix |
 | **epic** | a run of milestones in one design (playbook 04) | each milestone is a feature, delivered when its own group is ready; the next starts when the previous one's delivery plan is done |

 - **The trunk is what runs.** Every delivery is cut from a repository's trunk. A merge into any other branch
@@ -104,8 +104,8 @@ controller's delivery tables and the timers that polled them.
  branches held the controller for 55.7 h, and 28 of 68 other merges touched a held module (research 055,
  finding 3).
 - **A milestone is functional, its delivery shaped technically.** A milestone is named by what the operator or
-  the mesh can do once it is delivered; how it ships is shaped by the controller's what-if plan (`plans` for its
-  repositories and files): the modules it moves and their fan-out.
+  the mesh can do once it is delivered; how it ships is shaped by the delivery plan its changes would have, asked of
+  the controller's planner through mesh-delivery's `what-if` (ADR 0239 §3): the modules it moves and their fan-out.
 - **What a merge waits for.** mesh-delivery merges a group's members once the group's composed check passed at
  their heads, the independent reviewer marked each member ready (ADR 0364 §1, §2), each member carries the
  review ADR 0382 §6 asks, and the operator approved each merge into main (ADR 0398 §3). The operator's Approve is
@@ -126,7 +126,7 @@ Its id is `<owner>/<repository>@<twelve characters of its commit>`. It holds:

 **One key per pull request.** Beside the delivery, mesh-delivery keeps one key per open pull request on the
 bus: its head, the trunk commit its current check is asked against, and its verdict, written by
-compare-and-set (ADR 0406 §3). It writes a new head when the forge says one, and a new trunk commit only when it
+compare-and-set (ADR 0406 §4). It writes a new head when the forge says one, and a new trunk commit only when it
 asks the pull request's check again (ADR 0395 §1). A running check watches that key and stops when the head or
 the trunk commit in it moves.

@@ -144,7 +144,7 @@ allows.
 | ready | it passed; it waits to be merged | none | — |
 | rejected | it failed its check | none | — |
 | published | merged on its trunk, recorded in a batch; it waits for its plan to start | 30 minutes | `superseded` when a plan that does not answer its merge took over its plan; `go` when its plan started |
-| held | it waits for a person: a failed backup, a merge not ready, a policy of record; it ends by itself when it moves nothing or a later merge covers it (ADR 0270) | 1 day | nothing: it is the operator's |
+| held | it waits for a person: a failed backup (ADR 0404 §4), a policy of record; it ends by itself when it moves nothing or a later merge covers it (ADR 0270) | 1 day | nothing: it is the operator's |
 | delivering | its plan runs: backups, then builds asked and sent tier by tier | 2 hours | `delivered`, `failed` or `superseded`, as the plan's key says |
 | delivered, failed, superseded, stopped, retired, covered | final | — | — |

@@ -237,7 +237,7 @@ commit on the SDK's trunk or the head of an SDK pull request the forge holds, op
  controller member when it has one (ADR 0382 §3). Its verdict sets `mesh/delivery-group` and each member's
  `mesh/merge-gate`, and names every member it read. No gate runs for a member alone.
 - **Each member's own repository check stays required.** Each member's `mesh/repo-check` runs its repository's
-  suite with the siblings read beside it (ADR 0382 §2), in under a minute (ADR 0391, issue 890).
+  suite with the siblings read beside it (ADR 0382 §2).
 - **No composed verdict, no gate.** A member's gate is pending while no composed verdict at the members' current
  heads exists. A member's new head, close or base move puts the composed verdict out of date, and with it every
  member's gate. When mesh-delivery cannot say the groups, the pull request is checked alone and its verdict
@@ -291,8 +291,8 @@ event), and a failed check is said once and listed by `stalled`.
 *ADR 0214 §7, ADR 0233, ADR 0404.*

 When a delivery plan is ready to send, each node it reaches backs up, through its `node-backup` seat, every item
-the plan's moved modules keep there whose protection is a backup: an irreplaceable or valuable item, and a
-rebuildable one unless it says `backup: none`. A cache is never backed up. A node with no backup holder backs up
+the plan's moved modules keep there whose protection is a backup (a copy or a dump). An item protected by
+`redundancy`, one that says `backup: none`, and a cache are never asked, whatever their class. A node with no backup holder backs up
 nothing, and the plan says so for that node.

 - **The send waits for every backup.** The controller sends nothing of the plan to any node until every backup
@@ -305,7 +305,7 @@ nothing, and the plan says so for that node.

 ## The send and the rollout

-*ADR 0360, ADR 0362, ADR 0377, ADR 0406 §4.*
+*ADR 0360, ADR 0362, ADR 0377, ADR 0406 §5.*

 - **Every machine at once.** A plan's builds go to every machine that runs them in one step, tier by tier; a tier
  is asked once the tier before it is built and sent (ADR 0360 §1, §6). No machine goes first and nothing waits
@@ -360,7 +360,7 @@ delivery time.
 - **Builds and tests run directly**, as the build seat's own account on its node, in no container. A
  repository's `# mesh-check-toolchain` line selects which installed toolchain runs its check.
 - **A judge has an account of its own.** A judge built from a sibling's merge (ADR 0382 §3) is built and run as a
-  second account of the build module, whose home, configuration and cache the build seat's account cannot write,
+  second account of the Go build module, whose home, configuration and cache the build seat's account cannot write,
  so a check's script cannot change it.
 - **Every dependency comes by the version its lock file names**, checked against its checksum: the mesh's own
  code from the mesh's forge, its own packages from its package registry, any other from its public source.
@@ -417,7 +417,7 @@ In this order, each by its owner:
   on every member's head.

 A doubled step is refused by compare-and-set and by the bus's message de-duplication, which also replaces the
-forge module's files of what it announced (ADR 0406 §5).
+forge module's files of what it announced (ADR 0406 §6).

 ## The verbs

@@ -449,7 +449,7 @@ and its files). A person has `plans go <plan> --why`.
  controller's own, started by the merge; mesh-delivery records it (ADR 0239 §31).
 - Any other plan waits for `deliver` while the seat has a holder on record; with none, the controller starts it.
 - A replaced controller or mesh-delivery carries on from the bus: the keys, the queues and the durable
-  consumers hold every step, so nothing is lost or repeated (ADR 0406 §4).
+  consumers hold every step, so nothing is lost or repeated (ADR 0406 §6).

 ## Acceptance tests