Design 47 H2: the four reviews' answers as lines, the tool runner's drain and waits by event name
H-A-338 to H-A-343 settle the reviews by architectural domain and two faults met since; the part now leaves its builders no choice on stores, bounds, journal lines and tools. Split into a second file to keep each under 60 KB.
This commit is contained in:
@@ -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 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 §817): 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, hq a watched source | mesh-delivery, mesh-catalog, `mesh-host`, `mesh-tools`, `mesh-sdk` | H2 §816 and §817: 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 |
|
||||
| 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) and [H2-stores-and-tools](H2-stores-and-tools.md) (design 47 H2 §775 to §821): 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, hq a watched source | mesh-delivery, mesh-catalog, `mesh-host`, `mesh-tools`, `mesh-sdk` | H2 §816 and §817: 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,179 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H2
|
||||
updated: 2026-11-21
|
||||
decisions:
|
||||
- "ADR 0683"
|
||||
- "ADR 0682"
|
||||
- "ADR 0668"
|
||||
- "ADR 0664"
|
||||
- "ADR 0595"
|
||||
- "ADR 0571"
|
||||
- "ADR 0304"
|
||||
- "ADR 0282"
|
||||
- "ADR 0259"
|
||||
---
|
||||
# 47, milestone H2: the forge bridge, the gate, the parts beyond the chain, the stores and the tools
|
||||
|
||||
The second file of milestone H2's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
|
||||
[H2-the-delivery-systems-owed-work](H2-the-delivery-systems-owed-work.md), whose introduction holds for this file too,
|
||||
and both are read whole. Lines are cited as "design 47 H2 §n" whichever file holds them.
|
||||
|
||||
### 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), H-A-338 (5); 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; it is written in the hand-act log, and
|
||||
each act performed again checks its preconditions again (the pull request still open, the note not yet written)
|
||||
before it acts. 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; an act whose pull request closed meanwhile is ended,
|
||||
not performed.
|
||||
- §808 **One process mints the forge token at a time, and the token is a secret.** (H-A-300 (3), H-A-338 (1), H-A-339
|
||||
(8), H-A-340 (4); row 177) The forge module's processes share one admin token, kept where the module keeps its
|
||||
secrets (its own in the vault), never plain in a state, with the TTL `token-ttl` (a setting, default 24 hours). A
|
||||
process that needs one creates the lease key `mint` in the module's state `token-lease` (§820; create only, TTL
|
||||
`mint-lease`, a setting, default 60 s), mints, writes the token to its vault place, deletes at the forge the token
|
||||
it replaces, and deletes `mint`. A process that finds the lease taken waits for the token to change, at most the
|
||||
lease; past it, the lease has expired and the waiter creates the lease itself. `forge_token_lease` reads the lease's
|
||||
holder and since when and the token's age, never the token, which every read tool masks. 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,
|
||||
and the forge holds one token for the account after; a minter killed while holding the lease is replaced after
|
||||
`mint-lease`.
|
||||
- §809 **The gate's ledger keeps one entry per module and revision.** (ADR 0595 §3; H-A-299 (1), H-A-338 (10), H-A-340
|
||||
(3), H-A-341 (3); row 176) The gate's ledger `records` (§820) writes one head entry per delivery record,
|
||||
`<branch>.<source>` (its outcome, the count of its movers 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.
|
||||
The gate refuses an entry over 64 KiB with the finding `record-too-large` (scope delivery), cleared when that entry is
|
||||
next written within 64 KiB or at the record's end. The ledger is never pruned; as a kept ledger it refuses when full
|
||||
(ADR 0595 §3), and the bus module's fill condition speaks for it. `gate_record` and `gate_records` join the entries.
|
||||
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,
|
||||
its head counting 126; an entry made too large raises `record-too-large`, and the record's end clears it.
|
||||
- §810 **A delivery record keeps its delivery time; the self-check judges it against its budget.** (ADR 0282 §1, §6,
|
||||
§7; ADR 0304; H-A-341 (1); 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. `gate_times` answers each class's budget, the last seven days'
|
||||
median and worst, and every delivery over its budget with its longest phase (ADR 0282 §6's `times`), the budgets
|
||||
being the gate's settings `budget-core` (default 10 minutes, ADR 0282) and `budget-leaf` (default 3 minutes, ADR
|
||||
0304). As ADR 0282 §7 has it, the self-check's probe (the seat `mesh-self-check`) reads the gate's times and raises
|
||||
`over-budget` with the class as its id, naming the source revision and its longest phase; the next delivery of that
|
||||
class within its budget clears it; the gate raises nothing. Built in H2 in the gate and the self-check's probe. How it
|
||||
is checked: whole (gate and probe): a core record ended 11 minutes after its `merge-called` raises `over-budget` for
|
||||
the class `core`; the next core record within ten minutes 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, judged at its own writes.** (ADR 0595 §3, §5, §6; H-A-227,
|
||||
H-A-299 (2), H-A-338 (10), H-A-339 (2), (8), H-A-340 (3), H-A-341 (2); rows 103, 176) Every state, log and objects
|
||||
entry a delivery module asks for names its cap. At each write it makes to such an entry, its owner judges the entry's
|
||||
fill from the store's own figures (H-A-227), with no poll and no timer, and when the fill passes `prune-mark` (a
|
||||
setting, default 70 %, below the bus module's raise mark of 75 %) prunes it, oldest first, down to `prune-target`
|
||||
(default 50 %), one journal line per prune. Ledgers and the hand-act log are never pruned. mesh-sdk's generic state
|
||||
tools gain `state_prune_now` (entry, why: prunes to the target now) and `state_keep` (entry, key, until, why: a key
|
||||
never pruned before its until), both written in the hand-act log; the fill is read and the 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 and the tools), every delivery module and the forge module. How it is checked: the
|
||||
manifest check of §814; whole (bridge): a write that takes `performed` past 70 % prunes it to 50 %; a key under
|
||||
`state_keep` survives the prune.
|
||||
|
||||
### The assigner, the node-engine, the tool runner, 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, H-A-338 (8); 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. The order is an edge of the module graph the delivery
|
||||
derives (the composition value's form): the node-engine that reads `run` tolerantly (§780) runs before the
|
||||
assigner writes it. 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.
|
||||
11. *The destroy-level answer's channel waits for its research* (ADR 0259; H-A-237, H-A-334 (2); row 114): the
|
||||
bus module's keeper asks its drop and rebuild warrants at the approve level, as H-A-237 bends it, until a research
|
||||
effort designs the channel that carries the destroy proof; H2 builds no such channel, and the bend's line in the
|
||||
keeper's code names that research as its end. Checked: unit (keeper): a drop asks at the approve level.
|
||||
12. *The tool runner drains at a stop* (H-A-342 (2); row 179): once told to stop, the tool runner takes no new call,
|
||||
finishes the calls in flight within `drain-bound` (a setting, default 30 s), then exits; a call that outlives the
|
||||
bound is cut, with a journal line naming the bundle, the verb and the call's age, and its caller sees a transport
|
||||
fault. The node-engine, replacing the tool runner, waits the drain bound for the old one to exit before it starts
|
||||
the new one. Built in the tool runner (mesh-tools) and the node-engine. Checked: whole (tool runner): a stop during a
|
||||
20-second call finishes it and refuses a call made after the stop; a 40-second call is cut at 30 s and said; unit
|
||||
(node-engine): the new tool runner starts only after the old one exits or the bound passes.
|
||||
|
||||
### The new stores
|
||||
|
||||
- §820 **Every store this part adds names its form, cap, key life and deleter.** (ADR 0595 §2, §3; H-A-338 (6),
|
||||
H-A-339 (7), H-A-341 (7)) Each is asked for in its owner's `requires` by its template. A put refused because a store
|
||||
or queue is full is said in the owner's journal and asked again at the kept-call pace (§775).
|
||||
|
||||
| store | owner | template | cap | life of a key | deleted by |
|
||||
|---|---|---|---|---|---|
|
||||
| `taken` | every holder of a kept call (§775) | state | 8 MiB | the ask's bound (TTL) | the TTL |
|
||||
| asks of `mesh-builds` and `mesh-wants` | the broker, from the seats (§777) | work queue | 10,000 messages | 1 day | the holder's acknowledgement |
|
||||
| `unfinished` | pipeline runner (§786) | state | 8 MiB | none | the runner, or `runner_unfinished_drop` |
|
||||
| `outputs`, install archives included | each build module (§791, §800) | objects | 1 GiB | 7 days | the build module that keeps them, past 7 days |
|
||||
| `publishes` | builder (§793) | work queue | 64 MiB | 7 days | the builder's acknowledgement or termination |
|
||||
| `token-lease` | forge module (§808) | state | 1 MiB | `mint-lease` (TTL) | the minter, or the TTL |
|
||||
| `dry-runs` | indexer (§804) | state | 16 MiB | 1 hour (TTL) | the indexer at the answer and at its start |
|
||||
| `records` | gate (§809) | ledger | 1 GiB | none | never |
|
||||
|
||||
How it is checked: the manifest check of §814 refuses each without its cap; each owner's whole test fills its store
|
||||
to the mark and reads the prune or the refusal said.
|
||||
|
||||
### The tools this part adds
|
||||
|
||||
| tool | module | reads or steers | line |
|
||||
|---|---|---|---|
|
||||
| `builder_asks`, `builder_ask_drop`; `assigner_asks`, `assigner_ask_drop` | builder; assigner | what waits on and is taken from the seats' queues; one ask ended | §777 |
|
||||
| `runner_unfinished`, `runner_unfinished_drop`, `runner_unfinished_place` | pipeline runner | the movers put in a pipeline again; one placed now | §786 |
|
||||
| `runner_health` (`registrations-read`) | pipeline runner | whether the registrations view is read | §788 |
|
||||
| `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_dry_runs` | indexer | the dry runs' scratch state | §804 |
|
||||
| `indexer_registrations` | indexer | the registrations | §806 |
|
||||
| `bridge_owed_again` (`record`) | forge bridge | every owed act of a record again | §807 |
|
||||
| `forge_token_lease` | forge module | the token lease and the token's age | §808 |
|
||||
| `gate_times` | gate | delivery times against their budgets | §810 |
|
||||
| `state_prune_now`, `state_keep` | mesh-sdk, every module | prune now; keep a key from the prune | §812 |
|
||||
| `forge_merged` | forge module | merged pull requests by number | §812 |
|
||||
| `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) |
|
||||
| `seat-list`, `indexer_validate_before` | indexer (seat `mesh-catalog`) | the seat list as one object; the problems validate did not count | §814 |
|
||||
@@ -17,23 +17,27 @@ decisions:
|
||||
- "ADR 0548"
|
||||
- "ADR 0527"
|
||||
- "ADR 0525"
|
||||
- "ADR 0259"
|
||||
- "ADR 0499"
|
||||
- "ADR 0436"
|
||||
- "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.
|
||||
Milestone H2's part of [design 47](../47-delivery-from-commit-to-delivered.md), read whole by its builders with its
|
||||
second file, [H2-stores-and-tools](H2-stores-and-tools.md) (the forge bridge, the gate and the forge module, the parts
|
||||
beyond the chain, the new stores and the tools). 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, every *Owed* of rows 103 to 199 of the plan's section 10,
|
||||
and the answers to the four reviews by architectural domain (H-A-338 to H-A-341). 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. A line that changes
|
||||
a shared form (a seat's definition, mesh-sdk's catalog) rebuilds every module that imports it, once, in H2's one
|
||||
pipeline of every module (§818).
|
||||
|
||||
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 (§816, §817) close it.
|
||||
@@ -41,75 +45,94 @@ its own pipelines, with no hand pack (section 7 of the plan). Its two proofs (§
|
||||
### 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, insight proposed
|
||||
2026-11-21; H-A-300 (2), H-A-301, H-A-334 (3); 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, as the insight on ADR 0668 proposed 2026-11-21 says. 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.
|
||||
H-A-300 (1), H-A-338 (6), H-A-339 (4), H-A-340 (2); rows 170, 177) The pipeline runner's asks (build, lint, unit,
|
||||
integration, validate, composition, install 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), keeping the ids it took in its own
|
||||
state `taken`, key `<seat>.<ask>`, TTL the ask's bound (§820): the builder, the holder of `mesh-wants`, every
|
||||
node-engine for `compose-candidate`, the forge module for the seat `git`'s verbs and each registry for its publish.
|
||||
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), each wait
|
||||
drawn within 20 % of its value so many callers do not call in step: 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 one journal line per seat at the first fault and then at
|
||||
most once a minute, naming the seat, the verb, the asks waiting 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-ask-bound` (a
|
||||
setting, default 10 s), 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 `taken` state), the
|
||||
pipeline runner, the assigner, the forge bridge and the builder (mesh-delivery), the node-engine, the forge module
|
||||
and the registries. 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; a holder given the
|
||||
same ask id twice acts 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 and ADR 0668 §1, each with its insight
|
||||
proposed 2026-11-21; H-A-300 (2), H-A-301, H-A-334 (3), H-A-339 (5); 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). 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; the line rests on those two
|
||||
insights, accepted before H2's prepare starts. 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.
|
||||
§1, §2, §6; ADR 0436 §6; ADR 0664 §2; H-A-241, H-A-243 (1), (2), H-A-320 (2), H-A-338 (4), (7), H-A-339 (7), (8),
|
||||
H-A-340 (1), H-A-341 (4); 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, with ack wait 60 s, in-progress every 20 s, max ack pending 1,000, max
|
||||
deliveries 5 (above ADR 0664 §2's three) and a duplicates window of 2 minutes (ADR 0436 §6). The holder pulls every
|
||||
ask waiting at once, never one at a time, 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 at the pull, subject `<seat>.ask-taken.<ask>`,
|
||||
carrying `ask`, `node` and `at`; the definition declares `ask-taken`, so only the seat's holder publishes it. The
|
||||
runner consumes both seats' `ask-taken`. An ask put while its holder is down waits on the stream. The runner puts an
|
||||
ask again only when its put met a transport fault; a put refused by a full stream is said in the journal and asked
|
||||
again at the kept-call pace (§775). `builder_asks` and `assigner_asks` read what waits and what is taken on their
|
||||
seat's stream; `builder_ask_drop` and `assigner_ask_drop` (ask, why) end one ask, written in the hand-act log. 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 mesh-builds stream that no consumer
|
||||
took (1,524 asks on 2026-11-21) is rebuilt empty through the bus module's tool `nats_recreate`, on the operator's
|
||||
warrant (ADR 0595 §5), before the new builder and the new assigner start, so the rebuilt stream carries no message.
|
||||
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; unit (runner): a put refused
|
||||
for a full stream is said and asked again.
|
||||
- §778 **The unanswered bound counts from the pull.** (H-A-238 (5), H-A-320 (4), H-A-340 (1), H-A-341 (4); ADR 0664
|
||||
§4; row 189) The runner keeps on each step of its record `asked-at` (when the ask is put) and `taken-at` (from the
|
||||
seat's `ask-taken`), RFC 3339. The bound key `ask.<seat>.<ask>` is armed at `ask-taken` with the bound less the time
|
||||
since `taken-at`, and again at every start for every open ask, so a restart never grants a fresh bound; an ask whose
|
||||
time is spent at a start ends could-not-run at once. A step ended by its bound drops its ask through the seat's
|
||||
`drop` (as ADR 0664 §4 has it for the build seats), so no holder works on it after. An ask not taken counts no bound:
|
||||
the runner's health names a step whose ask is untaken past `stalled-bound` (§790). Built in H2 in the runner. How it
|
||||
is checked: unit (runner): an ask taken 9 minutes before a restart, with a 10-minute bound, ends one minute after the
|
||||
start and is dropped; an ask untaken for `stalled-bound` is named by the health.
|
||||
|
||||
### 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
|
||||
an opaque string the caller hands back (`next`, empty at the end); a page holds at most 768 KB, and a key written
|
||||
again between two pages comes again in a later page with `seen-again` set, so a reader knows it. 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
|
||||
runner): a state of 10,000 keys read in pages delivers each kept message once across all pages; a key written again
|
||||
mid-read is marked `seen-again`.
|
||||
- §780 **A reader of another part's value decodes it tolerantly and says its form.** (H-A-309, H-A-338 (8), H-A-341
|
||||
(6); row 183) Every seat value, event body and verb answer gains `form`, an integer the seat's definition raises at
|
||||
every field added or removed; `form` is left out while it is 1, and an absent `form` reads as 1. mesh-sdk's
|
||||
generated decoders for reading another part's value, event or answer 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.
|
||||
decoders) and every seat definition (a regeneration). How it is checked: unit (mesh-sdk): a value, an event and an
|
||||
answer with an unknown field decode and return their form; an absent `form` reads as 1; 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
|
||||
@@ -130,91 +153,108 @@ its own pipelines, with no hand pack (section 7 of the plan). Its two proofs (§
|
||||
|
||||
### The pipeline runner (seat `mesh-pipeline-runner`; mesh-delivery-pipeline)
|
||||
|
||||
- §784 **An ask placed and a step's end are journal lines.** (H-A-320 (1), H-A-333; row 189) The runner writes one
|
||||
line when it places an ask, "`<pipeline>` `<mover>` `<step>` asked on `<seat>`", and one when a step ends, "step
|
||||
ended `<pipeline>` `<mover>` `<step>` `<outcome>` in `<duration>`", the latter in the one place that says
|
||||
- §784 **An ask placed and a step's end are journal lines.** (H-A-320 (1), H-A-333, H-A-341 (5); row 189) The runner
|
||||
writes one line when it places an ask, "`<pipeline>` `<mover>` `<step>` asked on `<seat>`", and one when a step ends,
|
||||
"step ended `<pipeline>` `<mover>` `<step>` `<outcome>` in `<duration>`", the latter in the one place that says
|
||||
`step-ended`, so every end writes it: the unanswered bound's, the end at placing, a supersede, a re-pin, the
|
||||
approval's end, the start pass and the verbs that end a step. Nothing else is written per step. Built in H2. How it
|
||||
is checked: unit: each way a step ends writes exactly that line once.
|
||||
approval's end, the start pass and the verbs that end a step. Beside these two lines per step only the per-mover wait
|
||||
lines (H-A-326 (3), §787) and §775's fault lines are written. Built in H2. How it is checked: unit: each way a step
|
||||
ends writes exactly that line once.
|
||||
- §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.
|
||||
- §786 **A mover left unfinished by another's failure is put in a pipeline again.** (ADR 0682 §6; H-A-339 (7), (8);
|
||||
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` (§820), key `<branch>.<module>`, value `fingerprint`, `revision`, `pipeline` and `outcome`, and named in
|
||||
`pipeline-ended`'s new field `unfinished`. 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, with one journal line per mover added again. The key is deleted by the runner
|
||||
when the mover's pipeline ends passed or a newer fingerprint moves it, or by `runner_unfinished_drop` (one key, with
|
||||
`why`); `runner_unfinished_place` (one key, with `why`) puts the mover in a pipeline of its own at once; both are
|
||||
written in the hand-act log, and `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; `pipeline-ended` names the other in
|
||||
`unfinished`, the next take-in's pipeline carries it, 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
|
||||
- §788 **The registration check waits for its view.** (H-A-262, H-A-265 (4), H-A-339 (8); 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.
|
||||
yet read" once and places no step whose registration it has not read. `runner_health` answers
|
||||
`registrations-read` (true or false, and since when). Built in H2. How it is checked: unit: a start with the view
|
||||
unread raises no `registration-missing`, answers `registrations-read` false, 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.
|
||||
runner's health names a running pipeline with nothing open, or a step whose ask is untaken (§778), 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, and no longer names it once a step is placed in it.
|
||||
- §791 **A step's output is read where it is kept.** (H-A-294, H-A-341 (7); rows 144, 165, 168) A build module keeps a
|
||||
run's output in its `outputs` objects (§820), named on its step key `<node>.<ask id>` (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, or "no longer kept" past the objects'
|
||||
max-age), and the runner's tool `runner_step_output` (pipeline, mover, step) asks it of the holder on the node the
|
||||
step key names. 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`.
|
||||
checked: whole (Go build module): a failing unit test's words are read through `runner_step_output`; an output past
|
||||
its max-age answers "no longer kept".
|
||||
- §821 **Every event of the delivery parts is waited on by its seat and name.** (H-A-338 (4), H-A-343) Every event
|
||||
the runner says (`pipeline-started`, `step-ended`, `pipeline-ended`, `wait-held`, `wait-ended` and the re-pin's), the
|
||||
builder's `ask-taken` and `version-reserved` and the holder of `mesh-wants`' `ask-taken` are declared in their
|
||||
seat's definition under the seat's events family, so a wait by seat and event name (`mesh_wait` with
|
||||
`mesh-pipeline-runner.pipeline-ended`) is answered and no session reads a journal on a timer. Built in H2 in the
|
||||
delivery repository's contracts module (the seat definitions) and the three holders. How it is checked: the seat list
|
||||
carries each family and name; each holder's whole-module test waits on each of its events by name and is answered.
|
||||
|
||||
### 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>` `<pipeline>` `<movers>` `<step>` `<outcome>`", in the one place an ask is answered (its
|
||||
build step's finish), beside the line per entry saying an existing build or one built now (H-A-333); 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.
|
||||
- §792 **An answered ask is a journal line.** (H-A-320 (1), H-A-333; row 189) The builder writes one line per build
|
||||
ask it answers, "answered `<ask>` `<pipeline>` `<movers>` `<step>` `<outcome>`", in the one place an ask is answered
|
||||
(its build step's finish), beside the line per entry saying an existing build or one built now; 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, H-A-338 (5); row 158) The builder's publish
|
||||
items travel on its work queue `publishes` (§820), 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` (module,
|
||||
version, why) puts one item again as `live` and terminates the old; both are written in the hand-act log. 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, each with the message id `<holder>.<module>.<version>`, so a move started
|
||||
twice puts each item once within the duplicates window; 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; a move run twice puts each item once.
|
||||
- §794 **The builder's handling of an event costs one read and one write.** (H-A-269, H-A-271, H-A-280, H-A-340 (7);
|
||||
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, and its
|
||||
health names an events backlog whose oldest message is older than five minutes. Built in H2. How it is checked: unit
|
||||
(builder): handling 1,000 published events over 2,000 reservations makes exactly one index read and one write each;
|
||||
whole: a backlog held six minutes makes the health name it.
|
||||
- §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.
|
||||
builds is kept in the builder's memory with its language and kind, worked out again at every start and every change
|
||||
of the seat list, and said in one summary line each time, "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, H-A-341
|
||||
(3); 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. The builder reads a module's tags once per catalog revision it reserves under, and
|
||||
skips a number whose tag stands at another commit, with the finding `version-tagged-elsewhere` (scope module),
|
||||
cleared at the module's next `version-released`; 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, which clears at the next release.
|
||||
- §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.
|
||||
@@ -225,27 +265,33 @@ its own pipelines, with no hand pack (section 7 of the plan). Its two proofs (§
|
||||
|
||||
### 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.
|
||||
- §799 **A fetch or a publish that meets its holder away is a transport fault.** (ADR 0664 §1, §2; H-A-301, H-A-341
|
||||
(8), H-A-342 (1); row 178) A build or check step whose fetch of its source meets a connection fault or a 401 or 5xx
|
||||
answer of the forge, or whose publish to a registry seat meets no responders or a bundle that exited, ends its run
|
||||
`again`, never the step (ADR 0664 §1), with no seat call to learn why; 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 and a publish met by no responders to `again`, and three such runs to the step failed
|
||||
with `fetch:`.
|
||||
- §800 **A test that cannot run says NOT RUN; a starved setup runs again; a needed npm tree is installed.** (H-A-294,
|
||||
H-A-327, H-A-338 (3), H-A-339 (6), H-A-340 (6), H-A-341 (7); 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 test lacking tooling its step does not give says NOT RUN (H-A-294). A Go artifact may declare
|
||||
`check-needs` with the value `node-modules` in its manifest: the runner then asks the seat `node-build-node` a step of
|
||||
the new accepted kind `install` (input: the module's package lock at the commit) before the integration level; the
|
||||
Node build module installs from the npm registry seat with an integrity-checked install (`npm ci`) and no install
|
||||
scripts, keeps the tree as an archive in its `outputs` under the lock's digest (§820), and the step's end carries the
|
||||
archive object's name (ADR 0666 §16), which the integration ask names and the Go build module unpacks into the
|
||||
workspace. 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 its run `again` by §799's delays, and a third such run ends the step could-not-run "the bus did not answer
|
||||
in setup within <bound> under load", never failed. An assertion that fails is never `again` and never NOT RUN. Fate:
|
||||
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 build seats' definitions, 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 runs again and ends could-not-run at the third run; unit (Node build module): an install runs no script.
|
||||
- §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
|
||||
@@ -256,27 +302,29 @@ its own pipelines, with no hand pack (section 7 of the plan). Its two proofs (§
|
||||
|
||||
### 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.
|
||||
- §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),
|
||||
H-A-338 (9); 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. The indexer and the builder take the new fingerprint function in one release. Fate: the fingerprint
|
||||
over the repository's commit goes; every module's fingerprint changes once, at H2's delivery (§818). Built in H2 in
|
||||
the indexer, the builder 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
|
||||
`waiting-on`; one answered after six minutes raises `take-in-waiting`, which clears at the answer.
|
||||
- §804 **A dry run keeps to its own scratch state.** (H-A-297, H-A-339 (7), (8); row 174) A dry run of a branch's
|
||||
take-in writes only to the indexer's state `dry-runs` (§820), keys `<branch>.<call>.<kind>.<name>`, deleted by the
|
||||
indexer when the dry run answers and every one at the indexer's start, and leaves the trunk's packages state
|
||||
untouched; `indexer_dry_runs` reads the state. Built in H2. How it is checked: whole (indexer): a branch dry run
|
||||
leaves the trunk's packages state byte for byte as before, and a start finds `dry-runs` empty.
|
||||
- §805 **A release re-pins once, at its reservation.** (H-A-204, H-A-283's owed, H-A-338 (4); 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
|
||||
`revision`) when it reserves a package's number; the seat's definition declares the event, so only its holder
|
||||
publishes it, and the indexer consumes it. 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
|
||||
@@ -285,157 +333,81 @@ its own pipelines, with no hand pack (section 7 of the plan). Its two proofs (§
|
||||
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.
|
||||
11. *The destroy-level answer's channel waits for its research* (ADR 0259; H-A-237, H-A-334 (2); row 114): the
|
||||
bus module's keeper asks its drop and rebuild warrants at the approve level, as H-A-237 bends it, until a research
|
||||
effort designs the channel that carries the destroy proof; H2 builds no such channel, and the bend's line in the
|
||||
keeper's code names that research as its end. Checked: unit (keeper): a drop asks at the approve level.
|
||||
|
||||
### 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.
|
||||
(H-A-299 (2), H-A-329, H-A-338 (10), H-A-339 (1), (8); rows 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`); `indexer_validate_before` (pipeline, module) answers the before case's problems it did not count.
|
||||
The validator refuses a delivery module's state, log or objects entry with no cap (§812); a delivery module is one
|
||||
whose manifest claims a seat of the delivery system, which the validator reads from the claims; a foundation part's
|
||||
old-section entry declares its cap in that section (H-A-229, ADR 0595 §10) and is never refused for lacking the new
|
||||
form. Built in H2 in the indexer, the manifest validator and mesh-sdk's catalog. 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; an uncapped entry of a delivery module is refused, a
|
||||
foundation part's capped old-section entry is not.
|
||||
- §819 **Every module H2 touches ends with fewer tests than it starts with.** (ADR 0548; the test budget, 50
|
||||
integration and 500 unit per module; H-A-340 (8); rows 115 and the row of 18:40 on the budget) Each module a pull
|
||||
request of H2 changes carries fewer tests at H2's end than at its start, counted as the build node counts them
|
||||
(subtests included) and reported by each pull request's check. The starting counts: by the build node at H1's end,
|
||||
the indexer 538 integration, the assigner 64 integration, the node-engine 1,716 unit, the NFS server module 51
|
||||
integration and the package manager module 121 integration; by top-level test functions on the trunks of
|
||||
2026-11-21 (subtests not counted), the indexer 6 integration and 170 unit, the assigner 9 and 87, the runner 4 and
|
||||
105, the builder 18 and 167, the node-engine 11 and 1,716. The NFS server and package manager modules shrink to 50
|
||||
integration tests in H2. How it is checked: the check's counts per module in each pull request, read by its review
|
||||
against the starting count.
|
||||
|
||||
### hq, a watched source with no module
|
||||
|
||||
- §815 **A repository with no module registers as a source alone, and merges like any other.** (ADR 0527; ADR 0682
|
||||
§1, §3; H-A-332, H-A-334 (1); the operator, 2026-11-21 21:48: no merge is put to them; rows 176, 177) A registration
|
||||
of the seat `mesh-catalog` takes a source-only form: `repository`, its watched `branch` and `check`, the repository's
|
||||
own check command (for hq, its Go checks, ADR 0527), and names no module. The indexer keeps it with the
|
||||
registrations, takes a move of that branch in as a take-in with no movers, and refuses a source-only registration
|
||||
whose repository holds a manifest. The forge bridge says `head-moved` for it and the gate watches it as any watched
|
||||
branch (`head-untaken`, ADR 0682 §3); the checker runs `check` on each pull request's head and writes it as the
|
||||
status `mesh/check`; `merge-pull` merges its pull requests once that status passes, as for a module's, and the gate
|
||||
opens a delivery record that ends `nothing to deliver`. Fate: hq's pull requests merged by the operator at the
|
||||
forge end at H2's delivery; hq is registered so once through the seat `mesh-catalog`'s verb `register`, with the operator's channel saying it
|
||||
as a registration change. Built in H2 in the indexer (the registration's source-only form and the seat's
|
||||
definition), the gate and the checker. How it is checked: whole (indexer and gate): a source-only registration's
|
||||
merge call lands, raises no `head-untaken` and ends its record `nothing to deliver`; whole (checker): an hq pull
|
||||
request whose checks fail shows `mesh/check` failed and `merge-pull` refuses it.
|
||||
|
||||
### 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) |
|
||||
- §815 **A repository with no module registers as a source alone, and merges like any other.** (ADR 0527 §1; ADR 0666
|
||||
§11, §18; ADR 0682 §1, §3; H-A-332, H-A-334 (1), H-A-338 (2), H-A-339 (3); the operator, 2026-11-21 21:48: no merge
|
||||
is put to them; rows 176, 177) A registration of the seat `mesh-catalog` takes a source-only form: `repository`, its
|
||||
watched `branch`, `policy`, and `check`, which names a build seat and a step kind (for hq: `node-build-go`, `unit`,
|
||||
at the repository's root), never a free command; it names no module. The indexer keeps it with the registrations,
|
||||
takes a move of that branch in as a take-in with no movers, and refuses a source-only registration whose repository
|
||||
holds a manifest. The pipeline runner's run on request of a pull request's head (ADR 0666 §18) runs that one step on
|
||||
the named seat, in its sandbox, as a pipeline step; `merge-pull` judges the head by the registration's `policy` from
|
||||
the runner's step events, as it judges a module's (ADR 0666 §11), and merges it. The forge bridge says `head-moved`
|
||||
for the branch and the gate watches it as any watched branch (`head-untaken`, ADR 0682 §3); the gate's record of
|
||||
such a merge ends `nothing to deliver`. This closes a gap: ADR 0527 §1 has hq's checks run by the Go build module as
|
||||
any repository's tests, but with the checker gone (design 47 G) nothing asked that run, and hq's pull requests were
|
||||
merged by the operator at the forge with no mesh run. Fate: those merges at the forge end at H2's delivery; hq is
|
||||
registered so once through the seat `mesh-catalog`'s verb `register`, the operator's channel saying it as a
|
||||
registration change. Built in H2 in the indexer (the registration's source-only form and the seat's definition), the
|
||||
runner, the forge module's `merge-pull` and the gate. How it is checked: whole (indexer, runner and gate): a
|
||||
source-only registration's pull request is run on request, merged by one merge call, raises no `head-untaken` and
|
||||
ends its record `nothing to deliver`; an hq pull request whose Go checks fail is refused by `merge-pull`, naming the
|
||||
failed step.
|
||||
|
||||
### How H2 is proven
|
||||
|
||||
- §818 **H2's own delivery moves every module once, before the proofs.** (ADR 0499 §2; ADR 0682 §6; H-A-338 (9),
|
||||
H-A-340 (5)) H2's merges are delivered by their pipelines; once the indexer and the builder of §802 run, the
|
||||
indexer's recompute at its start (`call-kind` recompute, H-A-217) keeps one catalog revision in which every module's
|
||||
fingerprint moved, and one pipeline carries every module as a mover: about 193 movers (the module graph at trunk
|
||||
revision 512). A build whose content is unchanged is reused, not built again, and a node-engine restarts nothing
|
||||
whose composition is unchanged. Its time is read from its `pipeline-ended` phases and quoted in the milestone's
|
||||
report; a guess, said as one, is about 45 minutes, scaled from row 182's 126 movers in 29 minutes. It is held to no
|
||||
delivery budget (it is not a change's delivery), only to `stalled-bound`. The proofs run after it ends passed. How it
|
||||
is checked: the lead reads the pipeline's movers (`runner_movers`) and the node-engines' restarts during it.
|
||||
- §816 **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.
|
||||
(ADR 0282 §1; ADR 0682 §1, §6, §8; plan section 5, step 7; H-A-340 (10)) 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). It is read from the gate's ended record (`gate_record`): `class` core, `delivery-time` under ten
|
||||
minutes, no `over-budget` raised for it, quoted with its phases (§785); and from the hand-act log, empty for every
|
||||
delivery part from `merge-called` to the last `running`; no other pipeline held the slot meanwhile. 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.
|
||||
- §817 **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 §816, with no hand act and no
|
||||
restart as §816 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.
|
||||
ADR 0682 §1, §2, §4; ADR 0573 §2; H-A-340 (10)) 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 §816, with no
|
||||
hand act and no restart as §816 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