diff --git a/03-DESIGN/01-to-be/47-milestones/H-deliver-the-delivery-system.md b/03-DESIGN/01-to-be/47-milestones/H-deliver-the-delivery-system.md index 8c7d1211..ab32c27a 100644 --- a/03-DESIGN/01-to-be/47-milestones/H-deliver-the-delivery-system.md +++ b/03-DESIGN/01-to-be/47-milestones/H-deliver-the-delivery-system.md @@ -3,7 +3,7 @@ layer: to-be status: in-progress design: 47 milestone: H -updated: 2026-11-20 +updated: 2026-11-21 decisions: - "ADR 0682" - "ADR 0681" @@ -425,7 +425,7 @@ own pipeline), in this order, the next starting when the previous one's delivery |---|---|---|---| | H0 | the design says the one model whole (section 4) | hq, the knowledge base | the four reviewers by architectural domain approve the batch; the operator's four answers are in | | H1 | the one chain works with no hand act (section 5) | `mesh-delivery`, `mesh-catalog`, `mesh-host`, `mesh-tools`, `mesh-sdk`, `mesh-contracts` | the two proofs of step 7 | -| H2 | the builder, the build modules and the registries follow the latest lines (section 3.4; versions, publish again, the floor, a step with nothing to run, a module with no registration) | mesh-delivery, mesh-catalog | a version is skipped by nothing; every registered module has a pipeline with steps | +| H2 | the work H1's live run owes, as the lines of its own part, [H2-the-delivery-systems-owed-work](H2-the-delivery-systems-owed-work.md) (design 47 H2 §775 to §816): every ask a kept call through a part away, the work queues and journal lines of the asks, the fingerprint over a module's own build source, the stores capped and read in parts, the gate's ledger per module and its delivery times | mesh-delivery, mesh-catalog, `mesh-host`, `mesh-tools`, `mesh-sdk` | H2 §815 and §816: a change to a delivery part, and a package with its importer in two repositories, each running everywhere within ten minutes of its merge call with no hand act | | H3 | the gate and the forge module carry only the one model; groups by the operator's answer; the forge module without its merge-check machinery | mesh-catalog, mesh-delivery | a group of two repositories delivers as one; every delivery record ends | | H4 | every delivery part wakes on its inputs alone and is steered by its tools (sections 3.6, 7): the shared wake-up shape (mesh-config's full pass per event and its reads through module tools, the indexer's re-read after every verdict, the node-engine's retry clocks, the build modules' idle pull), the view and the watchman without reads of another part's state, the SDK's generic state tools with the fill against a cap, the missing tools per module, rates on the bus | `mesh-sdk`, `mesh-delivery`, `mesh-catalog`, `mesh-host` | the bus's slow consumers and behind counts at 0 for an hour; every module's tools pass the principle-4 table | | H4b | the grants part says what it holds as events and reads nothing of another part's bus state (ADR 0596) | `mesh-delivery` | the grants part's own `filling` and `room` and no bucket watch in its code | diff --git a/03-DESIGN/01-to-be/47-milestones/H2-the-delivery-systems-owed-work.md b/03-DESIGN/01-to-be/47-milestones/H2-the-delivery-systems-owed-work.md new file mode 100644 index 00000000..4300a48d --- /dev/null +++ b/03-DESIGN/01-to-be/47-milestones/H2-the-delivery-systems-owed-work.md @@ -0,0 +1,415 @@ +--- +layer: to-be +status: in-progress +design: 47 +milestone: H2 +updated: 2026-11-21 +decisions: + - "ADR 0683" + - "ADR 0682" + - "ADR 0668" + - "ADR 0666" + - "ADR 0664" + - "ADR 0596" + - "ADR 0595" + - "ADR 0573" + - "ADR 0571" + - "ADR 0548" + - "ADR 0525" + - "ADR 0259" + - "ADR 0499" + - "ADR 0304" + - "ADR 0282" + - "ADR 0267" +--- +# 47, milestone H2: the delivery system's owed work, as design lines + +Milestone H2's part of [design 47](../47-delivery-from-commit-to-delivered.md), read whole by its builders. Milestone +H1 (the clean state and the one chain, [H-deliver-the-delivery-system](H-deliver-the-delivery-system.md)) ended at +19:31 on 2026-11-21 with both its proofs shown; what its live run met and did not build is owed here: every item the +lead's answers H-A-227 to H-A-331 ([H-lead-answers](H-lead-answers.md)) name as owed to H2, and every *Owed* of rows +103 to 199 of the plan's section 10. The lines are numbered after milestone H's §774 and cited as "design 47 H2 §n". +Where an H2 line and an H line or a lead's answer differ, the H2 line holds. Every module named builds against the +latest published mesh packages (ADR 0573 §2), so the order between repositories is the module graph's (the package +edges), not this part's. The records each line follows are named in it; a choice within them that no record or +answer made is this part's own, given with its reason. + +H2 is one release of playbook 07: prepared by `mesh-preparer`, built, reviewed once, checked once, and delivered by +its own pipelines, with no hand pack (section 7 of the plan). Its two proofs (§815, §816) close it. + +### The asks between the delivery parts + +- §775 **Every ask of a delivery part to a seat is a kept call, paced.** (ADR 0668 §1 to §3, §7; ADR 0664 §1; H-A-296, + H-A-300 (1); rows 170, 177) The pipeline runner's asks (build, lint, unit, integration, validate, composition and + the seat `mesh-builds`' `published`), the holder of the seat `mesh-wants`' `compose-candidate` asks to each + node-engine, the forge bridge's owed acts on the seat `git` and the builder's publish asks to the registry seats are + made through mesh-sdk's kept-call form, marked safe to repeat: each carries its ask id, and every holder takes an ask + once by its id (ADR 0668 §2). On a transport fault (ADR 0664 §1's classes, a call's own deadline, and the kind `away` + of §776) the form calls again after `kept-call-pace-first` (default 1 s), doubling to at most `kept-call-pace-max` + (default 30 s) between calls: settings every module using the form declares with these defaults (principle 11), + chosen so a holder between two lives (a restart takes 20 to 50 s, row 179) is met within one minute without a call + a second. It writes a journal line at the first fault and then at most once a minute, naming the seat, the verb, the + ask id and the count of calls; it stops at the caller's bound: the runner's `ask-unanswered-bound` (H-A-238, default + 10 minutes), the holder's compose bound, the bridge's `owed-away-bound` (§807). Past the bound the step ends + could-not-run, or the act could-not-be-performed, naming every call's time and words; `call-unanswered` is written at + five minutes as ADR 0668 §3 has it. A refusal of what was asked ends at once, as today. Fate: the runner's and the + holder's one-shot asks, which ended a step at the first "no responders", go. Built in H2 in mesh-sdk (the pace), the + pipeline runner, the assigner and the forge bridge (mesh-delivery) and the builder. How it is checked: unit + (mesh-sdk): a call met by no responders twice and then answered returns the answer and logs one line; a call past its + bound returns every try; a refusal returns at once. Whole (runner): a composition ask whose holder is away for 40 s + passes its step with no hand act. +- §776 **A holder says `away` when a part it depends on is away.** (ADR 0664 §1; ADR 0668 §1; H-A-300 (2), H-A-301; + rows 177, 178) mesh-sdk's seat error answer gains the kind `away`, with `part` (what did not answer) and `words`. + The forge module, holder of the seat `git`, answers `away` when the forge answers 401, 502 or 503 or a connection + fault and the forge's own unauthenticated version read fails or names its store unavailable; it answers `refused`, + "the forge refuses the mesh's admin account", only when that read succeeds and a freshly minted token (§808) is + refused too, and it never words a refusal as an account to create. Every caller reads `away` as a transport fault + (§775, §796). This adds one class, a holder's own word that what it depends on is away, to the classes ADR 0664 §1 + and ADR 0668 §1 list. Built in H2 in mesh-sdk (the error kinds) and the forge module (mesh-catalog). How it is + checked: unit (forge module): a 401 with the version read failing answers `away`; a 401 with the read passing and the + fresh token refused answers `refused`. Whole (forge module): with the store stopped for 30 s, a merge call in that + window answers `away` and lands when called again. +- §777 **The seats `mesh-builds` and `mesh-wants` take their asks from a work queue and say `ask-taken`.** (ADR 0525 + §1, §2, §6; H-A-241, H-A-243 (1), (2), H-A-320 (2); rows 118, 130, 189) Each seat's definition (the delivery + repository's contracts module) declares its accepted kinds as work-queue streams the broker derives, as ADR 0525 §2 + has it for the build seats: `build` on `mesh-builds`, `validate` and `compose` on `mesh-wants`; each `max-age` 1 day + and `max-msgs` 10,000, one shared worker consumer its holder pulls. The holder acknowledges an ask when it says the + ask's end, sends in-progress while it works (ADR 0525 §6), and says `ask-taken` on the seat's family, subject + `.ask-taken.`, carrying `ask`, `node` and `at`, the moment it takes one. An ask put while its holder is + down waits on the stream. H-A-241's bound ends at `ask-taken`. Fate: the holders' plain subscriptions go; the + runner's putting again of every open ask on the holder's `running` (H-A-243 (1)) goes; `ask-silent-bound` and its + bound key (H-A-243 (2)) go; the asks left on the mesh-builds stream that no consumer took (1,524 on 2026-11-21) are + dropped once at H2's delivery by the stream's rebuild through the bus module's tool `nats_recreate`, on the + operator's warrant (ADR 0595 §5). Built in H2 in mesh-delivery (the contracts module, the builder, the assigner, the + runner). How it is checked: whole (builder): a build ask put while the builder is stopped is taken and ended after + its start; whole (assigner): the same for a validate ask; after a pipeline's end the streams' consumers hold 0 + pending. +- §778 **The unanswered bound counts from the ask's placing.** (H-A-238 (5), H-A-320 (4); row 189) The runner keeps on + each step of its record `asked-at` (RFC 3339, written when the ask is put). The bound key `ask..` is + armed with the bound less the time since `asked-at`, at the put and again at every start for every open ask; an ask + whose time is spent at a start ends could-not-run at once. A restart never grants a fresh bound. Built in H2 in the + runner. How it is checked: unit (runner): an ask placed 9 minutes before a restart, with a 10-minute bound, ends one + minute after the start. + +### mesh-sdk: the shared forms + +- §779 **A page read continues from an opaque cursor in sequence order.** (H-A-254, H-A-255 (2), H-A-292, H-A-293; + row 129) The state page read that the tool runner serves (`mesh/state.page`) reads a state's keys in sequence order + from an ordered consumer starting after the cursor's sequence, never a replay of the bucket per page. The cursor is + an opaque string the caller hands back (`next`, empty at the end); a page holds at most 768 KB. Every reader of a + large state may page; H-A-292's and H-A-293's one-page exception ends. Built in H2 in mesh-sdk (the call's contract + and client) and the tool runner (mesh-tools), and its callers in the same group. How it is checked: whole (tool + runner): a state of 10,000 keys read in pages delivers each kept message once across all pages. +- §780 **A reader of another part's record decodes it tolerantly and says its form.** (H-A-309; row 183) Every seat + value form gains `form`, an integer starting at 1 that the seat's definition raises at every field added or removed. + mesh-sdk's generated decoders for reading another part's value keep unknown fields, never refuse them, and return + `form`; a tool whose record's `form` differs from the one it was built with says "form N, this reader knows M" in its + answer. A writer still validates its own value strictly before it writes. Fate: the runner's dropping of + `kept-revisions` before the seat's decode (row 190) goes. Built in H2 in mesh-sdk (the seat generator and its + decoders) and every seat definition (a regeneration). How it is checked: unit (mesh-sdk): a value with an unknown + field decodes and returns its form; the seat generator's check fails a definition whose fields changed with `form` + unchanged. +- §781 **A tools program reads its module's settings.** (H-A-322, H-A-330; rows 190, 199) The node-engine composes a + module's settings into the module's slice of the tool runner's `MESH_TOOL_ENV` in the same files it composes for the + module's process, and mesh-sdk's settings reader reads them in a tools bundle as in a process. A bound one module + keeps on another's verb is that verb's `timeout` in its seat definition (built in H1), read by the caller from the + seat list: the packet filter's holder asks the node-engine seat's `converged` within that verb's `timeout`, and its + named 10 s goes. Built in H2 in the node-engine (`mesh-host`), mesh-sdk and the packet filter module. How it is + checked: unit (mesh-sdk): a tools bundle reads a setting the manifest sets; whole (runner): §790. +- §782 **The bus wrappers are safe for concurrent use.** (row 137, met twice) mesh-sdk's wrappers around one bus + handle guard each call the client does not allow at once with a lock inside the wrapper, so no module needs a + handle per goroutine (one place, principle 7). Built in H2 in mesh-sdk. How it is checked: unit under the race + detector: concurrent gets, puts and watches through one wrapper. +- §783 **A module's findings history drops its oldest.** (ADR 0595 §2, §3; H-A-227; row 104) The stream a module's + findings writer appends to (three stood full on 2026-11-21: the runner's, the builder's, the node-engine's) is asked + for by the events template, which drops the oldest when full, with `findings-max-age` (default 7 days); its fill is + read through the seat `mesh-broker`'s `show`. The findings state itself is unchanged. Built in H2 in mesh-sdk (the + writer's requires) and every delivery module's manifest. How it is checked: whole (runner): 10,000 findings written + past the cap refuse none. + +### The pipeline runner (seat `mesh-pipeline-runner`; mesh-delivery-pipeline) + +- §784 **A step's end is a journal line.** (H-A-320 (1); row 189) The runner writes one line per step end, "step + ended `` `` `` `` in ``", and nothing else per step. Built in H2. How it is + checked: unit: a step end writes exactly that line. +- §785 **`pipeline-ended` carries the pipeline's phases.** (ADR 0282 §1, §6; row 111) `pipeline-ended` gains + `phases`: `taken` (the take-in), `placed`, `ended`, and for each step kind (build, lint, unit, integration, validate, + composition) the earliest start and the latest end across its movers, RFC 3339. Each mover's own step times stay in + the step log, read with `runner_show` (§789). Built in H2 in the runner and the seat's definition. How it is checked: + unit: a pipeline of two movers ends with each step kind's span; the gate reads it (§810). +- §786 **A mover left unfinished by another's failure is put in a pipeline again.** (ADR 0682 §6; rows 133, 147, 162, + 167) When a pipeline ends `failed`, `cancelled` or `could-not-run`, each mover whose own required steps all passed or + never ran, and whose fingerprint no newer revision moved, is kept in the runner's state `unfinished`, key + `.`, value `fingerprint`, `revision`, `pipeline` and `outcome`. At the branch's next kept catalog + revision of any `call-kind`, the runner adds each such mover whose fingerprint is still its entry's there to that + revision's pipeline, or starts one for them alone when the revision moves nothing. The key is deleted when the + mover's pipeline ends passed, when a newer fingerprint moves it, or by `runner_unfinished_drop` (one key, with `why`, + written in the hand-act log); `runner_unfinished` reads the state. A mover whose own required step failed waits for + its fingerprint to move, as today. Fate: the lead's probe merges of row 167 end. Built in H2. How it is checked: whole + (runner): of a pipeline of two movers one fails its unit step; the next take-in's pipeline carries the other, and it + is wanted. +- §787 **A kept mover waiting on its revision says so.** (H-A-171, H-A-284, H-A-287) A kept mover whose kept revision + the runner's view does not hold yet carries `unplaced` `kept-revision-unread` with `revision`, said once in the + journal ("waits for its kept revision N to be read") and read with `runner_show`. Built in H2. How it is checked: + unit. +- §788 **The registration check waits for its view.** (H-A-262, H-A-265 (4); row 141) The runner judges + `registration-missing` only once its registrations view's first read is in; before that it says "registrations not + yet read" once and places no step whose registration it has not read. Built in H2. How it is checked: unit: a start + with the view unread raises no `registration-missing` and places the movers once it is read. +- §789 **A pipeline is read in parts.** (H-A-299 (3); rows 136, 142) The verb `show` and the tool `runner_show` take + `mover`, `step` and `state` filters applied while reading, and answer at most 768 KB with `capped`, `total` and the + cursor of §779; `runner_movers` (a pipeline's key) answers each mover with one word per step (`passed`, `failed`, + `running`, `waiting`, `not-run`). Built in H2. How it is checked: unit: one mover's steps of a record of 129 movers + answer under 64 KB; `runner_movers` of 1,000 movers answers under 768 KB. +- §790 **The stalled bound is a setting.** (H-A-311 (3), H-A-313, H-A-322; row 190) The five minutes after which the + runner's health names a running pipeline with nothing open become the runner's setting `stalled-bound` (default + 5 minutes, the rule nothing-moved-in-five-minutes), read by its process and its tools program (§781). Built in H2. + How it is checked: whole: with `stalled-bound` at one minute, the health names such a pipeline after one minute. +- §791 **A step's output is read where it is kept.** (H-A-294; rows 144, 165, 168) A build module keeps a run's output + in its `outputs` objects, named on its step key (ADR 0525 §6); the build seats `node-build-go`, `node-build-node` and + `node-build-image` gain the read verb `output` (input `ask`; answer the output's last 64 KB, its size, and the + failing tests' names with their words), and the runner's tool `runner_step_output` (pipeline, mover, step) asks it by + the step's ask id. Fate: the runner's objects `step-outputs`, which hold 0 bytes, go, dropped through the bus module. + Built in H2 in the build seats' definitions, the three build modules (mesh-catalog) and the runner. How it is + checked: whole (Go build module): a failing unit test's words are read through `runner_step_output`. + +### The builder (seat `mesh-builds`; mesh-delivery-builder) + +- §792 **An answered ask is a journal line.** (H-A-320 (1); row 189) The builder writes one line per build ask it + answers, "answered `` `` `` ``"; the holder of `mesh-wants` one per validate or + compose ask answered. Built in H2 (builder, assigner). How it is checked: unit. +- §793 **The publish queue is a work-queue stream.** (H-A-290, H-A-291; row 158) The builder's publish items travel on + its work queue `publishes` (the work-queue template, ADR 0595 §2), subject `publish....` + with class `live` (a build a pipeline's step waits on) or `again` (asked again at a start), one consumer per holder + and class that the builder pulls, `live` first, at most four sends in flight per holder (H-A-290 (3)); an item is + acknowledged when its publish is heard or confirmed (H-A-274), terminated when its build is withdrawn or superseded + (H-A-290 (2), H-A-291 (1)). `builder_publish_queue` reads the stream's counts per holder and class, the oldest and + newest, and a capped list; `builder_publish_drop` (module, version, why) terminates one item; `builder_publish_first` + puts one item again as `live` and terminates the old. Fate: the state bucket of publish items, its listing and its + relisting go; its items are put on the stream once at the builder's first start of this release, then the bucket is + dropped through the bus module. Built in H2. How it is checked: whole (builder): a live publish enqueued behind 100 + `again` items is sent first; a dropped item is never sent. +- §794 **The builder's handling of an event costs one read.** (H-A-269, H-A-271, H-A-280; row 152) A heard + `published` or `package-published` costs one read of the index by digest (or by version on a miss, H-A-271) and one + write; the builder logs any event whose handling passed 100 ms, with its duration and why. Bound: a median of 50 ms + per event with 2,000 reservations kept, so the consumer drains over three times the peak rate met on 2026-11-21. + Built in H2. How it is checked: whole (builder): 1,000 published events over 2,000 reservations are handled in under + 50 s. +- §795 **A plan no seat can build is said once.** (H-A-226's owed; rows 101, 166) A module whose artifact no seat + builds is kept in the builder's memory with its language and kind and said in one summary line per start or per + change of the seat list, "N modules have an artifact no seat builds:" with each language and kind and its count; + `builder_unbuildable` lists them. Fate: the line per module and definition goes. Built in H2. How it is checked: + unit: 6,500 unbuildable plans write one line. +- §796 **A tag names its commit; the builder reads it before it reserves.** (H-A-234 (2), H-A-245, H-A-246; rows 73, + 121) The seat `git`'s `tags` answer gains `commit` per tag, and its listing's description says a missing directory + answers `not-found` (H-A-232): one contract change, its holder the forge module and mesh-sdk's bootstrap copies in + one group. Before it reserves a number the builder reads the module's tags and skips a number whose tag stands at + another commit, with the finding `version-tagged-elsewhere` (scope module); a read that meets a transport fault or + `away` (§776) lets the reservation go on, said in the journal. A tag is never moved. The tag the builder writes for a + Go package is `/v`, which the Go toolchain's direct fallback reads (row 73); the `go/v` + tags go from new versions. Built in H2 in the seat `git`'s definition, the forge module, mesh-sdk's copies and the + builder. How it is checked: whole (builder): a tag standing at another commit makes the builder reserve the next + number and raise the finding. +- §797 **The build record carries its end.** (H-A-257) The builder's record of a build carries `ended` and `outcome` + when it ends, so a reader of the builds (the artifact store's sweep) reads no key history. Built in H2. How it is + checked: unit. +- §798 **A publish keeps its time.** (H-A-328, H-A-331; row 197) A reservation's published mark keeps `at` (when the + builder heard or confirmed the publish) and a kept release keeps the published `digest`; the verb `published` answers + both where kept and leaves them out for marks written before. Where H1's tail already built this, H2's prepare reads + it on main and builds only the rest. How it is checked: unit (builder): a publish heard now answers its time. + +### The build modules (seats `node-build-go`, `node-build-node`, `node-build-image`) + +- §799 **A fetch that meets the forge away is a transport fault.** (ADR 0664 §1, §2; H-A-301; row 178) A build or check + step whose fetch of its source meets a connection fault or the forge's 401 or 5xx answers while the seat `git` says + `away` (§776) ends its run `again`, never the step (ADR 0664 §1); the tool runner settles the ask with a delay of + 15 s after the first run and 60 s after the second (`again-delays`, a setting of each build module, default "15s,60s", + so three runs span the one-minute absence met on 2026-11-21), and a third run's fault ends the step failed with the + why `fetch: ` (ADR 0664 §2), which the builder and the runner say apart from a build's failure. Built in H2 in + the build seats' conformance kit (ADR 0664 §6) and the three build modules. How it is checked: the conformance kit + holds a fetch met by a 401 with the forge away to `again`. +- §800 **A test that cannot run says NOT RUN, and the step says it.** (H-A-294, H-A-327; rows 168, 170, 194) A step's + summary counts `not-run` apart from passed and failed, with each test's name and reason; a level whose tests passed + or did not run passes, its not-run listed. A Go artifact may declare `check-needs` with the value `node-modules` in + its manifest: its integration level then receives the module's npm tree, installed by the seat `node-build-node`'s + new accepted kind `install` (input: the module's package lock at the commit; output: an archive in its `outputs`, + kept by the lock's digest) and unpacked into the workspace before the level runs. Each level gets its bound in the + environment as `MESH_TEST_LEVEL_BOUND`, and mesh-sdk's test helpers take a setup bound of half of it, never a value + in the test; a whole-module test whose setup wait on the bus passes that bound ends NOT RUN "the bus did not answer + in setup within under load", never failed. An assertion that fails is never NOT RUN. Fate: the forge + module's NOT RUN of H-A-294 runs on the mesh; the Node build module's and the recovery module's setup bounds in code + go. Built in H2 in mesh-sdk (the helpers, the catalog's `check-needs`), the three build modules and those two + modules' tests. How it is checked: whole (Go build module): the forge module's whole-seat test runs with its npm + tree; a test whose setup is starved ends NOT RUN. +- §801 **Every build seat says what it takes and what runs.** (ADR 0525 §4, §10; H-A-302 (4), H-A-320 (3); rows 99, + 179, 189) Each build seat's verb `current` answers, per holder, whether it takes check asks and why not (`paused`, + `capacity 0`, `unhealthy`, with since when), and every ask it runs, whoever asked it (the builder's delivery asks + included); the build modules' steps read tools answer the steps state they keep, never empty while steps run; + `build_current` (the builder's tool) asks every holder and answers them together. Built in H2 in the three build + modules and the builder. How it is checked: whole (Go build module): an ask the builder put is listed by `current` + while it runs; a paused holder answers `paused`. + +### The indexer (seat `mesh-catalog`'s holder; mesh-delivery-indexer) + +- §802 **A module moves only when its own build source changes.** (ADR 0267 §1, §2; ADR 0499 §2; H-A-202, H-A-298 (1); + row 175) A module's fingerprint tree input is ADR 0499 §2's: the hash over its manifest and its named paths where + every artifact names `paths`, else its directory's tree object at the commit, with the directories of its + same-repository requirements taken in as H-A-202 has it; never the repository's commit. A commit outside them moves + nothing. Fate: the fingerprint over the repository's commit goes; every module's fingerprint changes once at H2's + delivery, said as such. Built in H2 in the indexer and mesh-sdk's one fingerprint function (ADR 0499 §2). How it is + checked: whole (indexer): a commit touching two test files of two modules in a repository of 36 moves those two and + their importers alone. +- §803 **A take-in says what it waits on.** (H-A-298 (2); row 175) A take-in waiting longer than a minute on another + part (the seat `git`'s listing, a package's versions, a registry) writes one journal line naming the part, the verb + and since when, and keeps it on its value in `takeins` as `waiting-on` (`part`, `verb`, `since`), read with + `indexer_pending`; past five minutes it raises the finding `take-in-waiting` (scope merge, id the source revision), + cleared when the wait ends. Built in H2. How it is checked: unit: a listing answered after 70 s writes one line and + `waiting-on`. +- §804 **A dry run keeps to its own scratch state.** (H-A-297; row 174) A dry run of a branch's take-in writes only to + the indexer's state `dry-runs` (state template, cap 16 MiB), keys `...`, deleted by the + indexer when the dry run answers, and leaves the trunk's packages state untouched. Built in H2. How it is checked: + whole (indexer): a branch dry run leaves the trunk's packages state byte for byte as before. +- §805 **A release re-pins once, at its reservation.** (H-A-204, H-A-283's owed; row 153) The builder says + `version-reserved` on the seat `mesh-builds`' family (`module`, `artifact`, `path`, `version`, `fingerprint`, + `revision`) when it reserves a package's number; the indexer re-pins every importer once at that event, and a + `package-published` of the pinned version keeps no revision; a withdrawn reservation re-pins to the series' newest + released version. Test steps still wait for the publish (H-A-206). Fate: the re-pin per publish goes. Built in H2 in + mesh-delivery (contracts, the builder, the indexer). How it is checked: whole (indexer): a release of a module + importing twenty packages of its own pipeline keeps one re-pin revision. +- §806 **The registrations are read in one call.** (row 140) `indexer_registrations` answers the registrations state + with `module` and `repository` filters applied while reading, at most 768 KB, with `capped` and the cursor of §779. + Built in H2. How it is checked: unit. + +### The forge bridge, the gate and the forge module + +- §807 **An owed act failing on a part away stays owed.** (H-A-300 (1), (4); row 177) The forge bridge performs an owed + act of the gate's stream `owed` as a kept call (§775) through transport faults and `away` until `owed-away-bound` (a + setting of the bridge, default 60 minutes), and only then says `owed.ended` with `could-not-be-performed`, naming its + tries. `bridge_owed_again` gains `record` (a delivery record's source revision) to perform again every act of that + record that ended could-not-be-performed. Built in H2 in the bridge. How it is checked: whole (bridge): with the + forge away for 60 s, a note act owed in that minute is performed after it, with no hand act. +- §808 **One process mints the forge token at a time.** (H-A-300 (3); row 177) The forge module's processes share one + admin token: a process that needs one creates the lease key `mint` in the module's state `token` (create only, TTL + `mint-lease`, a setting, default 60 s), mints, writes the token under the key `admin` there and deletes `mint`; a + process that finds the lease taken waits for `admin` to change, at most the lease, and reads it. The state is the + forge module's own kept data, reached by its own processes alone (ADR 0595 §1). Fate: each process's own mint goes. + Built in H2 in the forge module. How it is checked: whole: two processes refused at once mint one token. +- §809 **The gate's ledger keeps one entry per module and revision.** (H-A-299 (1); row 176) The gate's ledger + `records` writes one head entry per delivery record, `.` (its outcome, counts and the times of + §810), and one entry per mover, `..` (its pipeline, version, machines and their `running` + times); no entry names two modules, and the gate refuses an entry over 64 KiB with the finding `record-too-large` + (scope delivery). `gate_record` and `gate_records` join them. Fate: the whole-revision entry goes; the two records + refused on 2026-11-21 are not written again. Built in H2 in the gate (mesh-catalog). How it is checked: whole (gate): + a record of 126 movers writes 127 entries, none over 64 KiB. +- §810 **A delivery record keeps its delivery time against its budget.** (ADR 0282 §1, §6, §7; ADR 0304; row 111) At + its end the gate writes on the head entry `delivery-time` (from `merge-called` to the last `running` of its movers on + every present placing machine), `class` (`core` when it moves a core module of ADR 0282 §1, else `leaf`) and the + phases of §785. A time over its class's budget (settings `budget-core`, default 10 minutes, ADR 0282; `budget-leaf`, + default 3 minutes, ADR 0304) raises the finding `over-budget` (scope delivery, id the source revision) naming the + longest phase, cleared at the class's next delivery within its budget (ADR 0282 §7). `gate_times` answers each + class's budget, the last seven days' median and worst, and every delivery over budget with its longest phase (ADR + 0282 §6's `times`). Built in H2 in the gate. How it is checked: whole (gate): a core record ended 11 minutes after + its `merge-called` raises `over-budget`; the next within ten clears it. +- §811 **Every read filters before it sizes.** (H-A-299 (3); row 176) Every read verb and read tool of a delivery + module applies its filters while it reads and answers at most 768 KB with `capped`, `total` and the cursor of §779, + never "too big": among them the gate's `deliveries` (filters `repository`, `module`, `outcome`, `since`) and the + bridge's `bridge_owed` by pull request (reading only that pull request's keys, in the bridge's process). How it is + checked: the tools table of each pull request (principle 4); unit (gate): `deliveries` by repository over 4 MB of + records answers under 768 KB. +- §812 **Every kept store has a cap its owner prunes toward.** (ADR 0595 §3, §5, §6; H-A-227, H-A-299 (2); row 176) + Every state, log and objects entry a delivery module asks for names its cap, and its owner prunes it, oldest first, + when its fill (the store's own figures, H-A-227) passes `prune-mark` (a setting, default 80 %) down to + `prune-target` (default 60 %), one journal line per prune; its fill is read and its limits applied through the seat + `mesh-broker`'s `list`, `show` and `apply`. First the bridge's state `performed` (full on 2026-11-21), which also + drops entries older than `performed-keep` (default 3 days). A forge tool, `forge_merged` (repository, from, to), + lists merged pull requests by number with merge commit, time and whether a merge call made it (row 103). Built in H2 + in mesh-sdk (the prune helper), every delivery module and the forge module. How it is checked: the manifest check of + §814; whole (bridge): `performed` past 80 % is pruned to 60 %. + +### The assigner, the node-engine, the bus module, the registry and the teller + +- §813 **The parts this milestone touches beyond the chain.** (each clause names its source) + 1. *One writer per composition key, and the engine applies only a newer write* (H-A-302 (1) to (3), H-A-303, + H-A-306; row 179): a composition write carries `run`, the composition run's pipeline sequence, and the holder of + `mesh-wants` writes by compare-and-set refusing a lower `run`; a run whose pipeline ended writes nothing more; the + node-engine applies a composition again only when a part it could read differs and its `run` is newer than the one + it applied, naming the run in its journal. Built in the assigner and the node-engine. Checked: unit (each). + 2. *A failed keeping runs again* (row 137): a keeping of the assignment graph revisions that fails marks itself + wanted and runs again after `keeping-retry` (a setting, default 30 s, the holder's own deadline, ADR 0682 §11), + raising `keeping-failed` (scope module) at the third failure in a row, cleared at the next that succeeds. Checked: + unit. + 3. *Composed values read by resource* (H-A-306 (4); row 181): the node-engine's tool `engine_composition_diff` + (module, a revision or digest) answers, per resource, the entries that differ between the running composition + and the other, environment entries by name with secret values masked. Checked: unit. + 4. *The render marks a derived rule's scope* (ADR 0683; H-A-319; row 188): the node-engine writes on each derived + accept rule of the packet filter the comment `derived scope `, + and the holder of `node-packet-filter` reads a port's scope from `rules`, not from the rule's shape. Checked: unit + (node-engine render); whole (packet filter): `allow` without a source is refused for a `private-network` port. + 5. *The bus module's tools read flow* (row 124): `nats_consumers` sorts by `delivered-rate` (messages a second + measured over `rate-window`, an argument, default 10 s, within the one call) and by creation time; + `nats_connections` answers a connection's busiest subscriptions by messages. Checked: unit. + 6. *The keeper withdraws a refused request's ask* (row 123): a drop or rebuild request the keeper refuses at once + cancels its ask on the seat `operator-channel` in the same pass (ADR 0259 §3's cancel). Checked: unit. + 7. *The registry's list is paged, and it takes the sweep's removals* (ADR 0571 §2; ADR 0682 §10; H-A-250 (3); row + 125): the artifact registry seat's `list` takes `module` and the cursor of §779 and answers at most 768 KB; the + artifact store's sweep reads it page by page once per pass; the registry takes a removal from the seat + `artifact-store`'s holder, and its refusal "not the sweep's" goes (every account may call every verb). Checked: + whole (sweep): a pass over 20,000 artifacts removes what it judges. + 8. *The registry drops a deleted chunk's leftovers* (H-A-227): when it deletes chunks it purges their subjects from + the object store, so a store's kept descriptions equal its live objects. Checked: whole (registry): after 1,000 + chunks are deleted, the store's messages equal its live objects. + 9. *The usage view judges a build module by its running asks* (row 138): the status view reads a build module's + work from its seat's `current` (§801), not from the node-engine's held phase. Checked: unit (view). + 10. *The teller's ask-again for want of room goes* (ADR 0682 §14; H-A-295): with A-424, the teller's ask-again for an + ask refused for room and its test are removed. Checked: the teller's suite holds no such test. + +### The catalog's checks + +- §814 **The validator reads the mesh's seat list, counts only new problems, and refuses an uncapped store.** + (H-A-299 (2), H-A-329; rows 115, 196, 198) The seat `mesh-catalog` gains the read verb `seat-list` answering the + seat list the mesh holds as one object in the indexer's objects, by digest (`digest`, `size`, `object`), which the + manifest validator program takes by address, so a run by hand reads what the live validate reads. The step + `validate` counts, for a module it touches, only the problems new against its before case (`causedProblems`). The + validator refuses a delivery module's state, log or objects entry with no cap (§812). The NFS server module (51 + integration tests) and the package manager module (121) shrink to 50 (the test budget; ADR 0548). Built in H2 in the + indexer, the manifest validator, mesh-sdk's catalog and those two modules. How it is checked: whole (indexer): a run + by hand against `seat-list` gives the live validate's verdicts for the builder's and the runner's manifests; unit + (validator): a problem the before case holds is not counted. + +### The tools this part adds + +| tool | module | reads or steers | line | +|---|---|---|---| +| `runner_unfinished`, `runner_unfinished_drop` | pipeline runner | the movers put in a pipeline again | §786 | +| `runner_movers`, `runner_show` (filters) | pipeline runner | one pipeline in parts | §789 | +| `runner_step_output` and the build seats' `output` | pipeline runner, build modules | a step's output | §791 | +| `builder_publish_queue`, `builder_publish_drop`, `builder_publish_first` | builder | the publish queue | §793 | +| `builder_unbuildable` | builder | the plans no seat builds | §795 | +| `build_current` and the build seats' `current` | builder, build modules | what each holder takes and runs | §801 | +| `indexer_registrations` | indexer | the registrations | §806 | +| `bridge_owed_again` (`record`) | forge bridge | every owed act of a record again | §807 | +| `gate_times` | gate | delivery times against their budgets | §810 | +| `forge_merged` | forge module | merged pull requests by number | §812 | +| `seat-list` | indexer (seat `mesh-catalog`) | the seat list as one object | §814 | +| `engine_composition_diff` | node-engine | composed values by resource | §813 (3) | +| `nats_consumers`, `nats_connections` (sorts) | bus module | flow per consumer and connection | §813 (5) | + +### How H2 is proven + +- §815 **Proof 1: a one-line change to a delivery part runs everywhere within ten minutes, by its pipeline alone.** + (ADR 0282 §1; ADR 0682 §1, §6, §8; plan section 5, step 7) A one-line change (a comment) in one module of the + delivery system with lint, unit and composition steps, merged through one merge call (`merge-pull`), runs at its new + version on every present placing machine, reported healthy, within ten minutes of its `merge-called` (a core + module's budget), read from the gate's ended record (`gate_record`: `delivery-time`, §810) and quoted with its + phases (§785). No hand act touches the delivery system during it: no hand pack, no held put, no `runner_cancel`, + `runner_end_again`, rerun, `builder_build_again` or `builder_publish_again`, and no start, stop or restart through the + seat `node-service-manager`; the only restart is the moved module's own, by its node-engine. +- §816 **Proof 2: a package and its importer in two repositories, one merge call, within ten minutes.** (ADR 0282 §1; + ADR 0682 §1, §2, §4; ADR 0573 §2) One merge call names two pull requests: a one-line change to a package of the + delivery repository whose importers are at most three, one of them the gate in the catalog repository (read with + the indexer's `indexer_package_users`), and a one-line change to the gate. The gate names one source revision for + both, one pipeline publishes the package and builds the gate against it, and every mover runs at its new version on + every present placing machine within ten minutes of `merge-called`, read and bound as §815, with no hand act and no + restart as §815 says. How it is checked for both: the lead reads each with the tools named and quotes the times in + the milestone's report; a proof over its ten minutes or with a hand act is not shown, and its cause is fixed in its + repository and delivered before it is run again.