Merge pull request 'Give ADR 0299 its home in to-be 47: a stop ends only its own change on a shared walk (issue 459)' (#316) from feat/459-a-stop-re-walks-the-others into main

03-DESIGN/01-to-be/47-delivery-from-commit-to-delivered.md

@@ -4,6 +4,7 @@ status: in-progress
 code: [mesh-controller, mesh-catalog modules/mesh-delivery]
 updated: 2026-10-11
 decisions:
+  - "ADR 0299"
   - "ADR 0298"
   - "ADR 0282"
   - "ADR 0276"
@@ -143,7 +144,8 @@ controller's `plan-moved` event, never inferred from time.
 - **The ends.** A walk done ends every delivery it answers: `delivered` for its own commits, `covered` for
   an earlier merge of a repository it carried later, naming that merge. A walk that failed fails its own
   commits' deliveries and marks none delivered; each earlier merge it answered is then walked on its own
-  commit, the newest first, one walk each, until one is delivered. A walk stopped stops them all.
+  commit, the newest first, one walk each, until one is delivered. A walk stopped stops every delivery whose
+  merge it walks again nowhere (below).
 - **A group inside a walk.** The pairs of a delivery group's order (ADR 0249) are edges of the walk's
   tiers beside the module graph. mesh-delivery gives a walk its word only when every delivery it carries is
   at its turn.
@@ -160,6 +162,48 @@ controller's `plan-moved` event, never inferred from time.
   answers within ten minutes is held with the true reason (the open walks of its repository and that none
   names its merge, or that the controller holds none) and listed by `stalled` at once.
 
+
+## A stop on a shared walk
+
+*2026-10-11, by ADR 0299 (issue 459), with its progressive insight of the same day.*
+
+One walk carries every merge of its batch, so ending a walk for one delivery ends it for every other
+delivery on it. A stop therefore ends only the change it is for:
+
+- **A group's stop.** When a member after a failed one is stopped and its walk is open, mesh-delivery asks
+  `delivery-stop` for that walk with the stopped members' merges to leave out, every member the same pass
+  stops on that walk in one ask. The controller ends the walk, said as stopped, and walks every other merge
+  it answered again.
+- **What is left out with it.** A later merge of the stopped merge's repository and branch contains it. A
+  module is built at its branch, so a merge that moves a module a left-out merge moves would deliver it too.
+  Each such merge is left out as well, until no more is, and its delivery ends `stopped`, naming the stopped
+  merge it contains or whose modules it shares. An earlier merge of that repository sharing no module is
+  walked again.
+- **Where the others go.** They join the open batch of their kind, where merges heard while the walk ran
+  already wait, so an older commit never walks after a newer one; only with none open do they form a new
+  batch. The stop closes that batch's window, so the unrelated merges in it, and any heard after the stop
+  before it is cut, are cut without the rest of their window. Its walk withholds the left-out merges' modules
+  where it would build them only as dependents, and its record names them. A batch not yet cut can be stopped without a merge too: the merge goes
+  to a stopped record of its own, and the batch goes on without it. The stopped record, the batch and every
+  merge moved are written in one transaction.
+- **The walk's record.** The stopped walk names the batch that walks its merges again, every merge it left
+  out, and each module it already sent that nothing walks again, with the machines it reached. A delivery
+  whose merge is walked again goes from `delivering` back to `published` (the row `rewalk`), or stays
+  `published`, and follows the fresh walk once it is cut. A delivery whose merge was left out, and every
+  delivery on a walk stopped whole, ends `stopped`, naming the walk and the stop.
+- **A stopped merge never ships by a walk.** mesh-delivery asks every open walk or batch that names a stopped
+  delivery's merge to leave it out, and never gives such a walk its word. When the controller refuses, it
+  stops the whole walk.
+- **A person's stop.** `stop` of a delivery whose open walk carries other deliveries does nothing at first: it
+  answers with each of them, which of them contain this merge and end either way, and two ways given with
+  `way`: `again` (the walk ended and the others walked again without this merge) or `walk` (the whole walk
+  stopped, every delivery on it with it). A delivery alone on its walk is stopped at once. A delivery is
+  marked stopped only once its walk is; a stop the controller refuses leaves it as it was.
+- **What it does not do.** What the stopped walk already sent stays on the machines it reached, and its
+  asked builds still register, so a later send may carry them further; the stop names the machines, and
+  putting them back is issue 509's. A merge of the same repository waiting elsewhere, or one that moves the
+  stopped merge's modules, contains the stopped change and delivers it when walked; the stop names each it
+  can see, and holding a merged change back for good is a revert's job.
 ## The delivery budget
 
 *Decided 2026-10-10 by ADR 0282.
@@ -231,7 +275,8 @@ only once it is built.
   A member published while its group's composed check is asked and not answered waits there for the answer;
   one held because that check had not passed is *lifted* back to `published` once it passes or warns for the
   heads that merged and its own walk is still open (ADR 0270).
-- **A failed member**: the members after it are `stopped`, naming it. The members before it stay delivered.
+- **A failed member**: the members after it are `stopped`, naming it, and each one's merge is left out of its
+  walk while the walk's other merges are walked again (ADR 0299). The members before it stay delivered.
   Its own builds were put back at its gate.
 
 A group's state is derived from its members and its composed check, and is shown, never stored apart from
@@ -270,12 +315,13 @@ In this order, each by its owner:
 | `stalled` | every delivery held past its bound, with the transition H2 may take, and every waiting walk no live delivery holds |
 | `recheck` | a rejected or ready delivery back to proposed, with why |
 | `release` | a held delivery to delivering, with why: a person's word |
-| `stop` | any delivery not final to stopped, with why; its walk is ended through the controller |
+| `stop` | any delivery not final to stopped, with why; its walk is ended through the controller. On a walk that carries other deliveries it first answers what ending the walk would take down, and acts on `way`: `again` or `walk` (ADR 0299) |
 | `close` | H2's only verb: the transition the table names for a stalled delivery, refused otherwise |
 | `retire-history` | held history to retired, with why: one by id, refused when the rule does not take it, or every held one, answering how many and naming those it left; `dry` changes nothing |
 
 **The controller's verbs for it** (on the mesh-controller seat): `delivery-plan`, `delivery-order`,
-`delivery-check` (a group's heads composed, or one head checked again), `deliver`, `delivery-stop`,
+`delivery-check` (a group's heads composed, or one head checked again), `deliver`, `delivery-stop` (which
+takes the merges to leave out and walks the walk's other merges again without them, ADR 0299),
 `delivery-walks`. A person has `plans go <plan> --why`, which does what `deliver` does under their name and
 is recorded as a hand act. The controller says every walk it keeps as `plan-moved`, from a verb's command
 too.