Design 47 H2: the delivery system's owed work as design lines
H1's live run left owed items across the lead's answers H-A-227 to H-A-331 and section 10's rows 103 to 199; they get their own milestone part, so the H2 builders read one file whole and decide nothing.
This commit is contained in:
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
`<seat>.ask-taken.<ask>`, 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.<seat>.<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 `<pipeline>` `<mover>` `<step>` `<outcome>` in `<duration>`", 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
|
||||
`<branch>.<module>`, 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 `<ask>` `<module>` `<fingerprint>` `<outcome>`"; 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.<holder>.<class>.<module>.<version>`
|
||||
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 `<directory>/v<version>`, which the Go toolchain's direct fallback reads (row 73); the `go/v<version>`
|
||||
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: <words>` (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 <bound> 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 `<branch>.<call>.<kind>.<name>`, 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, `<branch>.<source>` (its outcome, counts and the times of
|
||||
§810), and one entry per mover, `<branch>.<source>.<module>` (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 <module> <listen> scope <any|private-network|local-network>`,
|
||||
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.
|
||||
Reference in New Issue
Block a user