Merge pull request 'Design 47, milestone H: the design lines of the one model (§734 to §774), reviewed by architectural domain' (#738) from design/47-H-lines into main
This commit was merged in pull request #738.
This commit is contained in:
+45
-3
@@ -600,7 +600,46 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
|
||||
registering and changing one are trusted acts (ADR 0666 §2). The mesh knows modules, and a repository only as a
|
||||
module's git origin.
|
||||
- **watched branch** — a branch a module's registration names, whose commits start that module's pipeline and which a
|
||||
placement may choose for a node; registering one the forge does not protect is refused (ADR 0666 §3, §6).
|
||||
placement may choose for a node; from milestone H's delivery it need not be protected, and nothing reads its
|
||||
protection (ADR 0682 §13, which ends ADR 0666 §3's refusal and §11's judgement).
|
||||
- **merge call** — one call of the seat `git`'s verb `merge-pull` naming one or more pull requests, each at the head
|
||||
its caller names: from the delivery of design 47's milestone H the start of their delivery and, with two or more,
|
||||
their group; the forge module judges every member before it merges any and says the call as its event
|
||||
`merge-called`, from which the gate names the merged heads one source revision (ADR 0682). Not a merge made in the
|
||||
forge's own screen, which delivers nothing and leaves an **untaken head**.
|
||||
*Not:* ~~kick-off~~ (hq)
|
||||
- **untaken head** — a watched branch's head that the forge bridge said moved (`head-moved`) and that no source revision
|
||||
names within the gate's setting `untaken-bound`: a head moved outside the mesh, raised as the gate's finding
|
||||
`head-untaken` and delivered by nothing but a later merge call or the gate's hand take (ADR 0682; design 47 H §740).
|
||||
Not a pending revision, which is a source revision not yet taken in.
|
||||
*Not:* ~~merge-untaken~~ (hq)
|
||||
- **`merge-called`** — the seat `git`'s event saying one merge call: its members that landed, each at its merge
|
||||
commit, and those refused; the gate's one input that names a source revision (ADR 0682 §1; design 47 H §736).
|
||||
*Not:* ~~merge notice~~ (hq)
|
||||
- **`head-moved`** — the forge bridge's one message for a move of a watched branch's head, however it moved, heard by
|
||||
the gate's watchdog alone (ADR 0682 §3; design 47 H §739). It replaces the messages `merged` and `pushed`.
|
||||
*Not:* ~~pushed message~~ (hq)
|
||||
- **`head-untaken`** — the gate's finding for an **untaken head**, raised when `untaken-bound` passes (ADR 0682 §3).
|
||||
*Not:* ~~untaken merge~~ (hq)
|
||||
- **`untaken-bound`** — the gate's setting, default 10 minutes, after which a head moved and not named by a source
|
||||
revision is `head-untaken` (ADR 0682 §3).
|
||||
*Not:* ~~take-in bound~~ (hq)
|
||||
- **`pipelines-at-once`** — the runner's setting, 1 to 8, default 1: how many pipelines have their steps asked at
|
||||
once; the rest wait in order (ADR 0682 §7; design 47 H §748).
|
||||
*Not:* ~~concurrent pipelines~~ (hq)
|
||||
- **`tier-late`** — the assigner's finding when one tier of a pipeline's movers does not run on its present machines
|
||||
within `tier-bound`: no later tier is written and the delivery record ends `failed` (ADR 0682 §8, §9; design 47 H
|
||||
§751).
|
||||
*Not:* ~~late tier~~ (hq)
|
||||
- **take-in** — the indexer's act on one source revision of a watched branch: the commits it names, the
|
||||
build-input fingerprints of the modules registered for those repositories, and one catalog revision of that branch,
|
||||
said as `take-in.taken` naming the **movers**; it validates no manifest (that is the pipeline step `validate`) and
|
||||
holds nothing for a named indexer (ADR 0682; A-476). Not a merge: what is taken in is a source revision the gate named.
|
||||
*Not:* ~~merge take-in~~ (hq)
|
||||
- **mover** — a module whose build-input fingerprint changed in a take-in, or a code dependent of one (a module, in any
|
||||
repository, that imports a package of one): the modules a take-in's one pipeline runs and delivers (A-476a; ADR
|
||||
0573 §3; ADR 0682). Not every module of the revision.
|
||||
*Not:* ~~moving module~~ (hq)
|
||||
- **run on request** — a pipeline run for a named commit or group that delivers nothing, asked by the runner's verb
|
||||
`run`; the indexer builds its candidate from the runner's `run-started` (ADR 0666 §18).
|
||||
- **artifact reference** — an artifact written `<module>:<artifact>`, such as `mesh-grants:program`: the end of a
|
||||
@@ -816,7 +855,8 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
|
||||
level: a group holds deliveries, never groups. Its state is derived from its members, never set. From milestone G's
|
||||
delivery: a shared branch name carrying its issue number, complete when each member's commit has landed on its
|
||||
modules' watched branch, taken in as one source revision of that branch and run as one pipeline per watched branch
|
||||
(ADR 0666 §13).
|
||||
(ADR 0666 §13). From milestone H's delivery: the pull requests named in one **merge call**; no branch name and no
|
||||
pull request read after the call forms one (ADR 0682).
|
||||
- **hotfix** — one pull request in one repository, delivered at its merge (ADR 0401).
|
||||
- **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
|
||||
@@ -890,7 +930,9 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
|
||||
- **pending revision** — a source revision the running indexer has not taken in, because it names another build of
|
||||
the indexer or follows one that does: only the named indexer's own keys are written, the rest kept in the
|
||||
indexer's state `pending` until that indexer starts and takes it in (ADR 0633 §1 to §3). A group's members wait
|
||||
there too until the group's end, as members still gathered (§4).
|
||||
there too until the group's end, as members still gathered (§4). Ends at milestone H's delivery: a take-in holds
|
||||
nothing for a named indexer, and one that cannot be written waits as its unacknowledged `source-moved` (ADR 0682;
|
||||
design 47 H §744).
|
||||
- **canary** — the first node of a module's nodes, ordered by ring then name: a new fingerprint reaches it
|
||||
first and the module's other nodes only once it runs healthy there (ADR 0429 §6). Replaces sending to every
|
||||
machine at once from release 6 (§15); a fingerprint that fails there is held and the canary set back, or for
|
||||
|
||||
@@ -2,8 +2,10 @@
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
code: [mesh-controller, mesh-catalog modules/mesh-delivery-gate, mesh-catalog modules/gitea, mesh-delivery, mesh-host, mesh-sdk, mesh-vault, mesh-contracts, mesh-tools, mesh-networking, hq 00-META/checks]
|
||||
updated: 2026-11-17
|
||||
updated: 2026-11-20
|
||||
decisions:
|
||||
- "ADR 0682"
|
||||
- "ADR 0681"
|
||||
- "ADR 0673"
|
||||
- "ADR 0672"
|
||||
- "ADR 0668"
|
||||
@@ -195,6 +197,16 @@ acting parts, the kept data on the bus restored with a delivery, and the verbs a
|
||||
section this file names in italics and does not hold is there, under the same name. A sentence that holds a delivered
|
||||
line and G's change together stays here.
|
||||
|
||||
**From milestone H's delivery, a delivery starts at the merge through the mesh** (ADR 0682; the operator,
|
||||
2026-11-20). One **merge call** of the seat `git`'s verb `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 per watched branch and opens its delivery
|
||||
record, the indexer takes it in and names its **movers**, one pipeline runs per take-in and none in parallel, and a
|
||||
want names the newest released version whose pipeline passed. The forge bridge's one message per move of a watched
|
||||
branch's head is the gate's watchdog: a head no merge call delivered is an **untaken head**, said and delivered by
|
||||
nothing. Every line milestone H builds is in its part, opened by the plan
|
||||
[47-milestones/H-deliver-the-delivery-system.md](47-milestones/H-deliver-the-delivery-system.md) and cited as "design
|
||||
47 H §n" (§734 on); where an H line and a G line differ, the H line holds and the G line says so.
|
||||
|
||||
This is the delivery of [to-be 10](10-delivery.md) carried out. To-be 10 says what is built: the comparison
|
||||
of source and artifacts decides, and nothing here changes that. This design says who answers for one
|
||||
commit's journey, in what order the steps are allowed, and where each fact of it is kept. It was rewritten on
|
||||
@@ -1508,6 +1520,23 @@ way is written down before the switch (ADR 0526, which ADR 0522 §6 asked of R4g
|
||||
running versions are kept outside the artifact store on two nodes, each by digest with its module, artifact, commit, Go version and the
|
||||
steps that put it back, because the store's nightly collection removes a blob the controller did not record (ADR 0526 §6).
|
||||
|
||||
## Every delivery part wakes on its inputs alone
|
||||
|
||||
*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, 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 (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.
|
||||
|
||||
## Acceptance tests
|
||||
|
||||
What the build proves before this design is implemented (research 055's direction):
|
||||
@@ -1664,7 +1693,7 @@ list:
|
||||
performance is fixed; no check starts real builds.
|
||||
37. **Nothing is delivered ahead.** Research 085's milestone is delivered with no part delivered ahead of it, read
|
||||
from its delivery record (ADR 0656, How it is checked).
|
||||
38. **A newer indexer is reached.** A merged revision naming a newer indexer gives, from the running indexer, a catalog
|
||||
38. **A newer indexer is reached.** *(Retires at milestone H, design 47 H §764.)* A merged revision naming a newer indexer gives, from the running indexer, a catalog
|
||||
graph revision that is the previous one with only the indexer's entry replaced; no other want moves; the new
|
||||
indexer is wanted, granted, started, and takes the revision in.
|
||||
39. **Revisions are kept, and stores say their fill.** A revision pinned by two records stays until both free it, one
|
||||
@@ -1706,7 +1735,7 @@ Each change ADR 0656 makes in an earlier record, and its test:
|
||||
are read by the indexer's candidate pass and by no running part (whole).
|
||||
48. **A process reports its handed build** (ADR 0639 §7). A part started while its node's want differs from what runs
|
||||
reports the build it was started with, and the node-engine seat's verb `process-builds` reads it (whole, node-engine).
|
||||
49. **The forge bridge reads a group from the gate's verb** (ADR 0633 §4, §5). The forge bridge sets the group on each
|
||||
49. **The forge bridge reads a group from the gate's verb** *(Retires at milestone H, design 47 H §764.)* (ADR 0633 §4, §5). The forge bridge sets the group on each
|
||||
merged message and publishes a group's end again from the seat `mesh-delivery`'s verb `groups`, and its account
|
||||
holds no read of the gate's `merges` state, so a read of it is refused (whole, forge bridge).
|
||||
|
||||
@@ -1728,11 +1757,9 @@ What milestone G's prepare found, and its test:
|
||||
(whole, gate, checker and forge module).
|
||||
53. **What is owed is said, answered and kept.** An `owed` said while the forge bridge is stopped is performed once after
|
||||
its restart; the bridge stopped between an act and its `owed.ended` repeats it and the forge holds it once; an
|
||||
undecodable act is said `undecodable`; an act unanswered 15 minutes is listed by `stalled`; the switch with a merge
|
||||
handed and not yet merged opens no `forge-made` record; a merge made at the forge opens one, said as `transition`
|
||||
with why `forge-made`, and a later merge in its repository follows it; the checker's `mesh/check` is performed by
|
||||
the bridge from the checker's `owed`, and a checker status the forge refuses is recorded in the checker's own
|
||||
state and listed in its stalled read (whole, gate, checker and forge bridge).
|
||||
undecodable act is said `undecodable`; an act unanswered 15 minutes is listed by `stalled` (whole, gate and forge bridge). The rows of a `forge-made` record
|
||||
and of the checker's `mesh/check` went: no record is marked `forge-made` (design 47 G §151), a head moved outside
|
||||
the mesh is an untaken head (design 47 H §740), and the checker goes (corrected in place by design 47 H §763).
|
||||
54. **One reader of the seat list per part, and one view machinery.** Every part that reads the seat list has the two
|
||||
tools of ADR 0636 §7 from the runtime and no wiring of its own; every part that takes a first view answers its
|
||||
held and awaited revision in `<module>_first_views`. With the forge on its old build, serving no verb of the seat
|
||||
@@ -1865,9 +1892,9 @@ No module ends the milestone with more tests than it starts with, counted per ca
|
||||
|
||||
The failure paths:
|
||||
|
||||
81. **A group that never completes** raises `take-in-waits` at 30 minutes, and none of its members is delivered (whole,
|
||||
81. **A group that never completes** *(Retires at milestone H, design 47 H §764.)* raises `take-in-waits` at 30 minutes, and none of its members is delivered (whole,
|
||||
indexer and watchman).
|
||||
82. **An indexer whose manifest its validator refuses** leaves its revision pending, holds only its own watched branch,
|
||||
82. **An indexer whose manifest its validator refuses** *(Retires at milestone H, design 47 H §764.)* leaves its revision pending, holds only its own watched branch,
|
||||
raises `take-in-waits` at 60 minutes, a later merge on that branch waits behind it and is not taken in past it, and
|
||||
a revert taken in moves the branch on (whole, indexer).
|
||||
83. **A declined registration change, and an unprotected branch,** each write nothing: the first after its Decline, the
|
||||
@@ -1953,13 +1980,13 @@ ADR 0667's checks, of milestone G itself:
|
||||
package rebuilds it, started by the runner after its `outdated` ask, one that leaves its digest as it was rebuilds nothing, and a change of the Go build module's
|
||||
own code rebuilds no module; a `beta` build's entries compare by digest (whole, indexer, builder and runner,
|
||||
mesh-delivery).
|
||||
105. **One query finds what is behind** (design 47 G §375). With the runner stopped while mesh-sdk `0.1.16` is
|
||||
105. **One query finds what is behind** *(Retires at milestone H, design 47 H §764.)* (design 47 G §375). With the runner stopped while mesh-sdk `0.1.16` is
|
||||
released, `outdated` names the module's kind-1 edge at `0.1.15` against `0.1.16`, and at its restart the runner
|
||||
starts that module's pipeline once, keyed by mesh-sdk's source revision; `runner_catch_up` does it by hand and
|
||||
writes the hand-act log
|
||||
(whole, indexer and runner, mesh-delivery). After the first fill (§377), a mesh running its newest builds is
|
||||
answered with nothing behind.
|
||||
106. **A delivery is waited for mesh-wide** (design 47 G §376, §379, §380). A module ordered after a provider's
|
||||
106. **A delivery is waited for mesh-wide** *(Retires at milestone H, design 47 H §764.)* (design 47 G §376, §379, §380). A module ordered after a provider's
|
||||
new version is wanted only once `version-delivered` says every present machine placing the provider runs it; with
|
||||
one machine away the module's status reads "waiting for delivery of" the provider, naming the machine, and it
|
||||
catches up when that machine is back; with every placing machine away the provider reads "waiting for <machine>
|
||||
@@ -1993,9 +2020,64 @@ 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, §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
|
||||
|
||||
- From milestone H's delivery: everything design 47 H §764 lists (the per-pull-request paths of the gate and the forge
|
||||
bridge, the catch-up by comparison, the runner's sweep, the start-time `outdated`, the checker, the groups by branch
|
||||
name, the want holds A-478 ends), and the stale state H §765 drops once.
|
||||
|
||||
- The "release branches" and the controller's check of them (ADR 0358, superseded by ADR 0401).
|
||||
- The toolchain image and its module (ADR 0405).
|
||||
- The window cutter, the merge catch-up timer, the rollout ticker, mesh-delivery's tick, reconcile and
|
||||
@@ -2089,6 +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 §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
|
||||
|
||||
@@ -84,9 +84,10 @@ check and deliver milestone G itself (ADR 0667 §2); each of them says so in a l
|
||||
what moved); the verb `registrations` answers every registration, or one with its history. The indexer derives the
|
||||
modules it keeps from them, and the forge bridge its watched branches, each by a first view of `registrations` and
|
||||
then that event, never by reading the ledger (ADR 0666 §3, ADR 0596).
|
||||
- §5 **An unprotected branch is refused.** `register` and `watch` read a branch's protection through the seat `git`'s read
|
||||
verb `branch` (its head, and whether a rule refuses a direct push and admits only merges), and refuse a watched branch
|
||||
the forge does not protect, naming it (ADR 0666 §3).
|
||||
- §5 **An unprotected branch is not refused at registration** (corrected in place by design 47 H §763). `register`
|
||||
and `watch` read no branch's protection and refuse no watched branch for it: the operator approved removing the
|
||||
check on 2026-11-14 (G-23, *Met during G's start*), and ADR 0682 §13 ends ADR 0666 §3's refusal, `merge-pull`'s
|
||||
protection judgement and §17's `branch-unprotected` (design 47 H §735, §739).
|
||||
- §6 **The foundation parts are the manifest validator's list.** The manifest validator's list (ADR 0619 §3) holds
|
||||
exactly the foundation parts, ADR 0619 §1's, the runner, which joins them (ADR 0666 §4), and the forge and image
|
||||
registry modules (§584); the checker leaves the
|
||||
@@ -317,8 +318,10 @@ check and deliver milestone G itself (ADR 0667 §2); each of them says so in a l
|
||||
removed with the checker's buckets and bus account, after the first pipeline after G's delivery has delivered a change
|
||||
end to end and on the operator's word (ADR 0667 §12; *How milestone G itself is checked and delivered*); the forge bridge hears the landed commit as it hears every commit of a watched
|
||||
branch.
|
||||
- §40 **The operator-channel hides no ask.** It keeps design 46's three open asks per asker, never holds the newest back,
|
||||
and replaces an open ask by the same asker's ask with the same `about` (ADR 0666 §12; design 46 §6).
|
||||
- §40 **The operator-channel hides no ask.** It keeps no count of open asks per asker and holds none back: every ask
|
||||
is offered when it is raised (A-424, the operator, 2026-11-15 about 15:50 CET), and it replaces an open ask by the
|
||||
same asker's ask with the same `about` (ADR 0682 §14, which ends ADR 0666 §12's three open asks per asker; design 46 §6;
|
||||
corrected in place by design 47 H §763).
|
||||
- §41 **How it is checked.** Whole (forge module, forge bridge): a session's `merge-pull` at its head merges with no run yet,
|
||||
and with a passed one, and asks no Approve; with the runner stopped a head merges; a head at whose fingerprint any
|
||||
run failed a `required` step, a head that moved and a branch whose protection was removed since its last move are
|
||||
|
||||
@@ -242,8 +242,9 @@ each the design's choice with its reason, §468 to §479 those of the runner's,
|
||||
whole (forge module), a head that passed, then another commit at its fingerprint failed a `required` step, is
|
||||
refused; its `seen` key goes when the pull request closes.
|
||||
- §476 **`take-in.taken`'s body and its type.** (§493) The indexer's own `take-in.taken` carries, beside what it carries on
|
||||
main, `branch` (the watched branch), `source` (the source revision taken in) and `entries`, one `{module, commit,
|
||||
fingerprint}` per module of that revision. Its body is defined in the seat `mesh-catalog`'s definition, in its
|
||||
main, `branch` (the watched branch), `source` (the source revision taken in) and `entries`, one
|
||||
`{module, commit, fingerprint, repository}` per mover of that take-in (design 47 H §743; corrected in place by H §763, where this line
|
||||
said one entry per module of the revision). Its body is defined in the seat `mesh-catalog`'s definition, in its
|
||||
section `bodies` (§439, §454), so the generated contract carries the type the indexer writes and the runner reads,
|
||||
and neither imports the other (§333). Why: a body said on a module's own stream and read by others is a `bodies`
|
||||
entry (§439), never a client's hand-written type (develop question Q-RN4). How it is checked: unit (seat generator),
|
||||
|
||||
@@ -389,9 +389,10 @@ for several build maps is answered once, and the maps' names for it are given in
|
||||
(G-24 §720, §725), and from its `ask-taken` by its step's bound (A-466p). [mesh-delivery DQ-3.] How it is checked:
|
||||
whole (runner), a seat with no holder ends the pipeline at once, naming it; an ask a present holder has not taken
|
||||
past five minutes is not failed (test 109).
|
||||
- §648 **A `take-in.taken` entry carries the pull request.** (§476, §542) An entry is `{module, commit, fingerprint,
|
||||
repository, pull}`, the last two from a `merged` message and absent for a `pushed` one. [mesh-delivery DQ-5.] How it
|
||||
is checked: unit (indexer's contract).
|
||||
- §648 **A `take-in.taken` entry names its repository, never a pull request.** (§476) An entry is `{module, commit,
|
||||
fingerprint, repository}`, the repository from the gate's `source-moved` (design 47 H §743); the field `pull` goes,
|
||||
since nothing reads a pull request after the merge call (ADR 0682 §1; corrected in place by H §763). [mesh-delivery
|
||||
DQ-5.] How it is checked: unit (indexer's contract).
|
||||
- §649 **`ParseStepKey` answers the asker.** (§484) `buildstep.ParseStepKey(key)` answers `(asker, node, id, err)`,
|
||||
`asker` empty for main's form. [mesh-delivery DQ-8.] How it is checked: unit, both forms.
|
||||
- §650 **The `mesh-builds` client's name.** (§586) It is `contracts/go/clients/meshbuildsclient`, with `Reserved`.
|
||||
@@ -408,9 +409,8 @@ for several build maps is answered once, and the maps' names for it are given in
|
||||
|
||||
- §654 **The readers of the forge module's old events and tools move to the seat `git`.** (§310, §311, §313, §431;
|
||||
ADR 0659 §1) [mesh-catalog Q-F1.]
|
||||
- **mesh-config** consumes `git`'s `pull-merged` and `pull-closed` in place of `gitea.pull.merged`,
|
||||
`gitea.pull.closed` and `gitea.forge.pull-request.closed`, and invokes `seat:git.pull` in place of
|
||||
`gitea.gitea_get_pull_request`; **the records module** consumes `git.pull-merged`.
|
||||
- **mesh-config** consumes no pull request event and invokes no `seat:git.pull` (ADR 0681 §1, which replaces this
|
||||
bullet's first form; corrected in place by design 47 H §763); **the records module** consumes `git.pull-merged`.
|
||||
- **The order.** Main's forge module says its own `pull.merged`, not the seat's events, so each consumer of
|
||||
`git.pull-merged` or `pull-closed` is ordered after the forge module's version that says them, by the edge of kind
|
||||
6 its `consumes` gives (§558); its durable consumer is made from the stream's first message, so no merge said
|
||||
|
||||
@@ -1275,14 +1275,15 @@ the principle that settles it, cited as "design 47 G A-n".
|
||||
never at the revision its own view holds; while its view holds an older one, it waits for it (§200) and places no step.
|
||||
(Live, 2026-11-16: main.947 was started at revision 356 while its take-in made 357; its composition read 356 after
|
||||
the indexer had removed it.)
|
||||
- **A-449** (§153, §579, design 47's "kept while a delivery record pins it or it is current"; principle 7) A pipeline
|
||||
pins its catalog graph revision as a delivery record does: the runner says the seat `mesh-delivery`'s `pinned` when it
|
||||
starts a pipeline and `freed` when the pipeline ends, under the record id `pipeline.<key>`, so the indexer keeps the
|
||||
revision while any pipeline runs on it. No new mechanism; who may say them is a grant of the runner's account.
|
||||
- **A-449** (§153, §579, design 47's "kept while a delivery record pins it or it is current"; principle 7; corrected in
|
||||
place by design 47 H §763, H §749) A pipeline pins its catalog graph revision: the indexer pins it in the take-in's
|
||||
write (A-449a) or on the runner's `pipeline-started`, and frees it on the runner's `pipeline-ended`, so the indexer
|
||||
keeps the revision while any pipeline runs on it. The runner says no `pinned` or `freed` of the seat
|
||||
`mesh-delivery`; those stay the gate's alone (§153).
|
||||
- **A-449a** (completes A-449; principles 3 and 7) The indexer pins the revision a take-in made for each pipeline the
|
||||
take-in starts, under `pipeline.<key>` (`<branch>.<source>.<module>` of each entry), in the same write as it keeps the
|
||||
revision, so no later take-in can remove it before the runner hears of it. The runner's pin at a pipeline's start stays
|
||||
(a set: saying it twice is harmless) and its `freed` at the pipeline's end removes it.
|
||||
take-in starts, under `pipeline.<key>` (`<branch>.<source>`, the one pipeline of the take-in, design 47 H §746), in the
|
||||
same write as it keeps the revision, so no later take-in can remove it before the runner hears of it. Its free is on
|
||||
the runner's `pipeline-ended` (A-449 as corrected).
|
||||
- **A-226b** (completes A-226 and A-167; ADR 0593 §7; principles 7 and 9) The seat `node-engine`'s `compose-candidate`
|
||||
takes three key forms, parsed by one parser in the seat's client (`nodeengineclient`) that every caller builds its key
|
||||
with: a check's candidate `<group>.<heads hash>` (as today), a branch pipeline's revision `<branch>.<revision>` and a
|
||||
@@ -1862,7 +1863,7 @@ the principle that settles it, cited as "design 47 G A-n".
|
||||
- **A-475a** (A-475; principles 7, 2 and 11) "In a row" is counted on the pending revision's validation itself
|
||||
(`stale`, the stale ends since its last ask that was not stale), the only place that needs it. The catch-up waits
|
||||
while a validation ask of any repository is out, since every take-in moves the one revision a request is built from;
|
||||
it still compares the heads and raises A-463's merge-untaken condition meanwhile, and only its take-in waits.
|
||||
it still compares the heads and raises A-463's `merge-untaken` condition meanwhile, and only its take-in waits.
|
||||
`validate-tries` defaults to 3 and is at most 20. (From the develop and review of A-475.)
|
||||
- **A-476** (the operator, 2026-11-17 ~17:30 CET, from the delivery walkthrough: "no manifest check needed at this
|
||||
point"; "for each module that is registered in our module graph, for the affected repo -> check the fingerprints";
|
||||
|
||||
@@ -103,7 +103,9 @@ record says so in its Why. Round 3 of the review by architectural domain (2026-1
|
||||
`*.findings-stated` are the first. The manifest validator takes `*` only as the whole emitter, and only before an
|
||||
event that a seat's definition or a contract in mesh-sdk defines, with its fields (for the finding events, the seat `mesh-conditions`' definition, §439); it refuses `*.>` and `*` in part of an emitter's name, and a `*` entry before any other event keeps its meaning on main (§474). The grants part,
|
||||
from the catalog graph as it derives every grant (§59, §442), makes on each declaring module's stream one durable consumer
|
||||
for the consumer, named `<machine>_<module>` as ADR 0363 §5 names one, with its grants to read and acknowledge it and
|
||||
for each process of the consumer that hears it, named as A-397 names a process's durable (`<machine>_<module>` for
|
||||
its program, `<machine>_<module>_tools` for its tool runner, `<machine>_<module>_<process>` for another; corrected in
|
||||
place by design 47 H §763, where one per module stood), with its grants to read and acknowledge it and
|
||||
its membership's word to bind it; it drops that consumer when the module no longer declares the event, and makes one
|
||||
for a module that declares it later, with no change to the consumer's manifest. A `*` entry never reaches a
|
||||
restricted stream (one with a `grant`, ADR 0363 §4). Why: the keeper hears modules it finds in the catalog and its
|
||||
|
||||
@@ -0,0 +1,297 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H
|
||||
updated: 2026-11-20
|
||||
decisions:
|
||||
- "ADR 0682"
|
||||
- "ADR 0681"
|
||||
- "ADR 0667"
|
||||
- "ADR 0666"
|
||||
- "ADR 0656"
|
||||
- "ADR 0633"
|
||||
- "ADR 0596"
|
||||
- "ADR 0573"
|
||||
---
|
||||
# 47, milestone H: the merge call, the watchdog, the take-in and one pipeline at a time
|
||||
|
||||
One file of milestone H's part of [design 47](../47-delivery-from-commit-to-delivered.md); the plan that opens the part
|
||||
is [H-deliver-the-delivery-system](H-deliver-the-delivery-system.md). Its design lines continue the numbering of
|
||||
milestone G's part after §733 and are cited as "design 47 H §n". Each line says which release of the plan's section 6
|
||||
builds it (H1 to H5), how it is checked, and which line of G or lead's answer it replaces; where the code it lands in
|
||||
is named, it is named by module and function, from the gap tables of 2026-11-20, for the builder to find it.
|
||||
|
||||
*The operator, 2026-11-19 about 23:30 CET: "Nobody should 'take in a merge', only commits to the configured branch of
|
||||
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 (cited by the clause numbers of its version 8, fourteen clauses). 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
|
||||
bridge's one message per head move is heard only by the gate's watchdog, which raises an **untaken head** for a head
|
||||
no merge call delivered.*
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
S[session or operator] -->|git.merge-pull pulls| F[forge module, seat git]
|
||||
F -->|merge-called| G[gate, seat mesh-delivery]
|
||||
G -->|source-moved| I[indexer, seat mesh-catalog]
|
||||
I -->|take-in.taken: movers| R[runner, seat mesh-pipeline-runner]
|
||||
R -->|pipeline-ended| A[assigner, seat mesh-wants]
|
||||
F -->|branch-moved| B[forge bridge]
|
||||
B -->|head-moved| G
|
||||
G -.->|head-untaken| K[condition keeper]
|
||||
```
|
||||
|
||||
### The merge call
|
||||
|
||||
- §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 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, §13; ADR 0666 §11; principle 3) The verb judges
|
||||
each member as ADR 0666 §11 does, but for the branch protection (still the pull request's head; no run at the head's
|
||||
build-input fingerprint failed a `required` step), all of them first. It judges no branch protection: a watched
|
||||
branch need not be protected (ADR 0682 §13), and a head moved outside the mesh, a push included, is the watchdog's
|
||||
untaken head (§740). 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` (§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 §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. It
|
||||
reads no branch protection: an unprotected watched branch moves like any other, and `branch-unprotected` (G §17)
|
||||
ends (ADR 0682 §13). 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 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. 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. 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 §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
|
||||
(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.** (ADR 0682 §4; 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 keeps `take-in.pending`, `take-in-waits`, `indexer_pending` and `indexer_take_in_pending` and
|
||||
ends `indexer_drop_pending`.
|
||||
- §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).
|
||||
|
||||
### One take-in, one pipeline, none in parallel
|
||||
|
||||
- §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 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 (ADR 0682 §8; 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 (ADR 0682 §7): 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; 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: `JudgePins`; runner). How it is checked: whole (indexer): a restart while a pipeline runs on revision
|
||||
510 keeps 510. Corrects A-449 (§763).
|
||||
|
||||
@@ -0,0 +1,195 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H
|
||||
updated: 2026-11-20
|
||||
decisions:
|
||||
- "ADR 0682"
|
||||
- "ADR 0666"
|
||||
- "ADR 0656"
|
||||
- "ADR 0596"
|
||||
- "ADR 0595"
|
||||
- "ADR 0573"
|
||||
- "ADR 0548"
|
||||
- "ADR 0525"
|
||||
---
|
||||
# 47, milestone H: the want rule, the builder's lines, the reads of other parts and the missing read tools
|
||||
|
||||
One file of milestone H's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
|
||||
[H-deliver-the-delivery-system](H-deliver-the-delivery-system.md), and its lines are numbered after
|
||||
[H-1](H-1-the-merge-call-and-the-take-in.md)'s and cited as "design 47 H §n". These are items 8 and 11 to 13 of the
|
||||
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 §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 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 and read through that seat's verb
|
||||
`placement` (A-62), whose answer shows the `build` value beside the branch, 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.** (ADR 0682 §8, §9; H-A-10; 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; 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; 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; 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, 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 (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 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; ADR 0682 §8). 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 (acceptance test 119).
|
||||
|
||||
### Reads of another part's data become its events and verbs
|
||||
|
||||
- §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 and its first-view verb are read
|
||||
from the module's manifest at H4b's prepare, which writes them into this line.
|
||||
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
|
||||
is bounded at `window` plus 5 seconds, at most 65 seconds. A verb's call timeout is a bound per verb in its seat
|
||||
definition, `timeout`, defaulting to the tool runner's own (principle 11); `rates` names 70 seconds, and the tool
|
||||
runner waits a verb's `timeout` when its definition names one. 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) 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`; 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
|
||||
|
||||
None: the enrolment event's seat and first-view verb (§773) are owed to H4b's prepare.
|
||||
@@ -0,0 +1,125 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H
|
||||
updated: 2026-11-20
|
||||
decisions:
|
||||
- "ADR 0682"
|
||||
- "ADR 0681"
|
||||
- "ADR 0667"
|
||||
- "ADR 0666"
|
||||
- "ADR 0633"
|
||||
- "ADR 0595"
|
||||
---
|
||||
# 47, milestone H: the corrections made in place, the stale state, and what retires
|
||||
|
||||
One file of milestone H's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
|
||||
[H-deliver-the-delivery-system](H-deliver-the-delivery-system.md), and its lines follow
|
||||
[H-2](H-2-wants-builds-reads-and-tools.md)'s, cited as "design 47 H §n".
|
||||
|
||||
- §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 (ADR 0682 §13, which ends ADR 0666 §3; the operator,
|
||||
2026-11-14, G-23 *Met during G's start*). G §17, G §38's and G §41's protection judgement of `merge-pull`: no part
|
||||
reads a branch's protection (ADR 0682 §13, which ends ADR 0666 §11's protection judgement and §6's condition).
|
||||
- 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 and offers every ask (ADR 0682 §14, which ends
|
||||
ADR 0666 §12's three; A-424, the operator, 2026-11-15).
|
||||
- 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 to §4, §6, §8, §9, §13, §14; 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'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 branch protection (H1; ADR 0682 §13):** `merge-pull`'s judgement of a branch's protection, the bridge's
|
||||
read of it on every move and its finding `branch-unprotected` (G §17), and the protection rows of G §41's test.
|
||||
- **The operator channel's limit (ADR 0682 §14):** any count of open asks per asker, and ADR 0666 §25's tool for
|
||||
asks held back, which reads empty and goes.
|
||||
- **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`;
|
||||
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 (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
|
||||
(`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.
|
||||
- **Every seat contract (H1):** the `callers` lists (§752).
|
||||
- **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 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, 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, as the mesh's instruction
|
||||
*how-work-is-done* allows, 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). The counts above are per
|
||||
module; the count per release and the number of tests each retired test frees are each milestone's prepare's, written
|
||||
in its milestone file. How it is checked: each pull request of H states its module's counts against the
|
||||
budget; the review refuses a count over it.
|
||||
@@ -5,10 +5,17 @@ design: 47
|
||||
milestone: H
|
||||
updated: 2026-11-20
|
||||
decisions:
|
||||
- "ADR 0666"
|
||||
- "ADR 0667"
|
||||
- "ADR 0682"
|
||||
- "ADR 0681"
|
||||
- "ADR 0667"
|
||||
- "ADR 0666"
|
||||
- "ADR 0656"
|
||||
- "ADR 0633"
|
||||
- "ADR 0596"
|
||||
- "ADR 0595"
|
||||
- "ADR 0573"
|
||||
- "ADR 0548"
|
||||
- "ADR 0525"
|
||||
---
|
||||
# 47, milestone H — the plan to deliver the build-and-delivery system properly
|
||||
|
||||
@@ -26,6 +33,22 @@ against that specification, with what runs live on each machine). The readings a
|
||||
here, and every number below comes from them unless it says otherwise. The plan is the lead's; the operator reads it
|
||||
before any code is written.
|
||||
|
||||
**Milestone H's part.** This file opens the part; its design lines (section 4's items as lines, numbered after G's
|
||||
§733 and cited as "design 47 H §n") are in three files, each read whole:
|
||||
|
||||
- [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, 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, 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, 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.
|
||||
|
||||
## 1. Where the system stands (read 2026-11-20 00:05 to 00:30 CET)
|
||||
|
||||
**What works.** One pipeline delivered one module end to end with no hand act on 2026-11-19 at 22:48 (the image
|
||||
@@ -302,8 +325,8 @@ deleted at release 6 of ADR 0429 and replaced by ADR 0666's pipelines per module
|
||||
what remained open was how the mesh learns which commits belong together, since ADR 0666 §13 reads a shared branch
|
||||
name through pull requests. The operator, 01:15 CET: since every version is deployed by a merge into main, an action,
|
||||
they have no objection to kicking the build-and-delivery process off by hand instead of listening to the forge's
|
||||
hooks; the lead named principle 3 (a kick-off a person forgets is a silent non-delivery) and proposed the merge through
|
||||
the mesh as the kick-off with the forge's event kept as the watchdog; the operator chose it (01:20 CET, "A, go
|
||||
hooks; the lead named principle 3 (a start a person forgets is a silent non-delivery) and proposed the merge through
|
||||
the mesh as the start with the forge's event kept as the watchdog; the operator chose it (01:20 CET, "A, go
|
||||
ahead"): one call of the seat `git`'s verb `merge-pull` naming one or more pull requests is the delivery's start and
|
||||
the group; nothing reads a pull request after it; a head moved outside the mesh raises a condition and delivers
|
||||
nothing. Item 1 below is answered so; item 6 is written from it. The operator also said they would not mind a start from scratch; the lead's answer is in
|
||||
@@ -355,13 +378,12 @@ next:
|
||||
2. **Merge H1's set to main**, in this order, each reviewed: mesh-contracts #16 and mesh-sdk #200 (held), then
|
||||
mesh-catalog #708 and mesh-delivery #261 (held, mesh-config), mesh-tools #77 (held), and H1's own pull requests
|
||||
(indexer take-in, runner, gate, bridge, assigner, node-engine). mesh-delivery #262 is closed as superseded. The
|
||||
stopped runner starts nothing; the indexer takes the commits in and the gate follows.
|
||||
stopped runner starts nothing; the indexer takes the commits in and the gate follows, as the old programs still
|
||||
running during the freeze do. The new programs take every head in once, at the seed (step 5.9).
|
||||
3. **Build H1's programs from main** with the packs (the g-start phases, one per program), on 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
|
||||
@@ -378,12 +400,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
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H
|
||||
updated: 2026-11-20
|
||||
decisions:
|
||||
- "ADR 0682"
|
||||
---
|
||||
# 47, milestone H — the lead's answers
|
||||
|
||||
The lead's one-line answers to the questions the design writer and the builders could not answer from the records,
|
||||
each tested against the principles (`00-META/principles.md`) and naming the one that settles it (implement-the-design).
|
||||
A question no principle settles goes to the operator or to a record; it is marked so here.
|
||||
|
||||
## From the design writer (2026-11-20 01:36 CET)
|
||||
|
||||
- **H-A-1 A member refused after every member was judged** (a forge failure between the judgement and the last merge):
|
||||
the forge module says the members that landed, marks the call `refused` and raises the finding `merge-partial`;
|
||||
the landed members are taken in as one source revision, so what landed is delivered and what did not is loud.
|
||||
Principle 3.
|
||||
- **H-A-2 The delivery order once the want holds for nothing**: the runner's `pipeline-ended` carries its movers in
|
||||
ADR 0666 §14's delivery order, and the node-engine applies one pipeline's wants on its machine in that order
|
||||
(A-478b's order on one machine). The order travels in the event; no part reads another part's state for it.
|
||||
Principles 1 and 9.
|
||||
- **H-A-3 A `required` step whose run ends "nothing to run"** counts as passed for the want, as `bypass` does: a hold
|
||||
with nothing behind it protects nothing. Principle 7. A clause of ADR 0682 says it (asked of the record writer, 01:38).
|
||||
- **H-A-4 Reads whose owner says no event today** (the provisioner's provisions, the vault's bus accounts and node
|
||||
logins, the enrolment module's enrolments, the grants part's user list): each owner says one change event and the
|
||||
readers consume it, in milestone H4b; until then the read stands and is named a leftover in the gap table.
|
||||
Principle 1 (ADR 0596).
|
||||
- **H-A-5 A revert against the whole want rule**: a return to an earlier build stays one value in the placement, read
|
||||
by the assigner before the rule, the one exception; ADR 0682's review raised it and the record says it. Principle 4.
|
||||
- **H-A-6 The seat that serves `validate`**: the seat that runs the composition step, which G §22 names `mesh-wants`;
|
||||
ADR 0682 §4's "mesh-module-assigner" is corrected to that seat (asked of the record writer, 01:38). Principle 9.
|
||||
- **H-A-7 The main file's size** (258 KB against the 80 KB bound of playbook 02): the reshaping of design 47's main
|
||||
file into its milestones' parts is a change of its own after H0, not folded into this one (rules-are-weighed: the
|
||||
bound protects a reader, and the plan's reader has the three H part files; a 180 KB move in the same pull request
|
||||
would hide the lines under review). Said to the operator at 01:38.
|
||||
- **H-A-8 The build modules' queue order**: deliveries first (ADR 0525 §4), as §753 writes; the operator's yes to the
|
||||
turns of 2026-11-15 is in no record, so the record holds. If H2's prepare finds it, the record gets an insight.
|
||||
|
||||
## From the review by architectural domain (2026-11-20 01:40 to 01:44 CET; four reviewers, one round)
|
||||
|
||||
- **H-A-9 How the apply order reaches the node-engine**: the want carries its `pipeline` and its `rank` in that
|
||||
pipeline's delivery order, written by the assigner from `pipeline-ended`; the node-engine applies a pipeline's wants
|
||||
on its machine by rank and consumes no event of the runner. The apply-order read tool is the node-engine's.
|
||||
Principles 9 and 12.
|
||||
- **H-A-10 Order across machines** (ADR 0666 §14's "delivered before" edge between machines): the order lives inside the
|
||||
one pipeline, never as a hold of a want on another delivery (A-478 b: "the order between modules moves into the
|
||||
pipeline"): the assigner writes one pipeline's wants tier by tier in §14's order, a later tier once the earlier
|
||||
movers report `running` on their machines, with a bound per tier (a setting) whose end ends the delivery record `failed` with the finding `tier-late`,
|
||||
the pipeline's own outcome staying what its steps said; the
|
||||
composition step composed the whole graph before any want was written. ADR 0682 says it (the record writer, 01:50).
|
||||
Principles 3 and 7.
|
||||
- **H-A-11 Publishing an event family stays the producer's**: every account may call every verb (ADR 0682), but a
|
||||
module publishes only the events its manifest declares, as ADR 0666 §21 has it for a step's result; the mechanism
|
||||
stays whole, who is on which side is not asked (who-may-is-not-the-operators-question). An enrolling node's account
|
||||
keeps its own grant. Principle 6.
|
||||
- **H-A-12 The indexer's consumer and a blocked `source-moved`**: one durable consumer per watched branch; a
|
||||
`source-moved` the indexer cannot take in (the store full) is held, unacknowledged, until the bus module's `room`
|
||||
wakes it, never on the ack timer; a hand tool skips it with `why`, written in the hand-act log. `take-in.pending`,
|
||||
`take-in-waits` and `indexer_pending` stay (ADR 0633 §5). Principles 1, 3 and 4.
|
||||
- **H-A-13 A source revision written once per call**: the gate keys its write by the call id with compare-and-set, so a
|
||||
redelivered `merge-called` numbers nothing twice. Principle 3.
|
||||
- **H-A-14 The waiting queue of the runner**: ordered by the runner's own counter at the moment it writes the pipeline;
|
||||
placed at the runner's start from its own state and on every end, a cancel and a set-aside included; a finding when
|
||||
pipelines wait while none runs; a pipeline waiting on the operator's `approval` step does not count against
|
||||
`pipelines-at-once` and re-enters the queue first when approved; the queue's cap is a setting. Principles 3 and 11.
|
||||
- **H-A-15 The clean state's seams** (plan section 5): before the runner starts, every watched branch's current head is
|
||||
its first source revision with no movers (§745) and the newest catalog revision names it, read and counted; the state
|
||||
of the earlier model is dropped after the new programs run (after step 5.6), each item through the tool named for it,
|
||||
the backup snapshot being the rollback; every new durable consumer starts at the newest message and refuses an event
|
||||
of the old form with a journal line; the stopped runner's queue of old `take-in.taken` goes with the state; a machine
|
||||
away at the clean state gets its hand placement when it is back, before anything else; the forge's branch protections
|
||||
drop the required statuses `mesh/merge-gate` and `mesh/repo-check` in H1. Principles 2 and 3.
|
||||
- **H-A-16 Where H1's integration tests run before its merge**: once, locally against an embedded bus, said in each
|
||||
pull request (how-work-is-done allows it); the chain's live proof (plan step 7) is H1's check; from H1 on the
|
||||
pipeline makes the check. Rules-are-weighed, said.
|
||||
- **H-A-17 The whole tests**: one per module, in that module's repository; tests 110, 112 and 113 are split per module
|
||||
and the chain stays the live proof; the design gives the count per module per release and names the retired tests
|
||||
that free room (the budget is per module, 50 and 500).
|
||||
- **H-A-18 The forge module's call**: a call key written before the first merge and said again at start; `refused` in
|
||||
the event's body; `merge-partial` keyed by the call, cleared when a later call lands the refused members or by a
|
||||
hand clear; tools `forge_calls` and a say-again; `by` recorded beside the caller's bus account; `failed-steps` is
|
||||
written from the runner's `step-ended` (mover, commit, fingerprint). Principles 3 and 4.
|
||||
- **H-A-19 Small forms**: no pin for a take-in with no mover; a call with two members on one branch names the last
|
||||
member's commit in call order; `package-published` carries the source revision that published and its pipeline pins
|
||||
it and belongs to that merge call's delivery record; `pipeline-ended` carries per mover the released version and
|
||||
fingerprint and the delivery order, on the subject `...pipeline-ended.<branch>.<source revision>`; `pipeline-failed`
|
||||
is one finding per failing mover, cleared by that module's later passed pipeline; every fixed value (30 days, 64 MiB,
|
||||
60 minutes, 10 minutes) is a setting with that default; §765 drops every state §764 retires. Principles 7 and 11.
|
||||
- **H-A-20 The main file's size**, a must for three reviewers: the lead's bending of the bound (H-A-7) is said to the
|
||||
operator at 01:48 with the question whether the reshape follows H0 as its own change; until the answer the bound
|
||||
stands bent, said.
|
||||
Reference in New Issue
Block a user