Design 47 H2: the second look's six items and notes as lines

H-A-344 closes what the four second looks found open: never-pruned stores,
the mint guard, foundation stores in old sections, the keeping tool, the
findings cap, the untaken ask's end.
This commit is contained in:
2026-11-21 22:17:42 +01:00
parent 38117a687c
commit 35ddd45e8a
2 changed files with 37 additions and 21 deletions
@@ -9,6 +9,8 @@ decisions:
- "ADR 0682"
- "ADR 0668"
- "ADR 0664"
- "ADR 0619"
- "ADR 0596"
- "ADR 0595"
- "ADR 0571"
- "ADR 0304"
@@ -32,16 +34,19 @@ and both are read whole. Lines are cited as "design 47 H2 §n" whichever file ho
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
- §808 **One process mints the forge token at a time, and the token is a secret.** (ADR 0596; H-A-300 (3), H-A-338
(1), H-A-339 (8), H-A-340 (4), H-A-344 (2), (10); row 177) The forge module's processes share one admin token, kept
where the module keeps its secrets, its own in the vault, written and read through the seat `mesh-vault`'s verb
`own` and never into another module's store or plain in a state, with the TTL `token-ttl` (a setting, default
24 hours). A process the forge refuses first reads the vault's token; it takes the lease and mints only when the
refused token is the vault's current one, else it uses the vault's newer token, so a refusal of a stale token mints
nothing. A process that mints 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 goes. Built in H2 in the forge module. How it is checked: unit (forge module): two processes, one
holding the old token, both refused, mint one token in all; whole: 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,
@@ -73,9 +78,11 @@ and both are read whole. Lines are cited as "design 47 H2 §n" whichever file ho
- §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
fill from the figures the write's own answer gives (H-A-227, H-A-344 (7)), with no extra read, 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
(default 50 %), one journal line per prune. Ledgers, the hand-act log, `taken`, `unfinished`, `token-lease` and every state whose
deleter §820 names other than the prune are never pruned; such a store refuses when full, said in its owner's
journal (H-A-344 (1)). 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
@@ -97,8 +104,8 @@ and both are read whole. Lines are cited as "design 47 H2 §n" whichever file ho
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.
raising `keeping-failed` (scope module) at the third failure in a row, cleared at the next that succeeds;
`assigner_keep_now` (why) runs the keeping at once, written in the hand-act log (H-A-344 (4)). 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.
@@ -138,7 +145,9 @@ and both are read whole. Lines are cited as "design 47 H2 §n" whichever file ho
### 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
H-A-339 (7), H-A-341 (7)) Each is asked for in its owner's `requires` by its template; a foundation part (ADR 0619 §1, ADR 0666 §4) declares
each of its stores (`unfinished`, `publishes`, `taken`, `dry-runs`, the findings stream) in its old section with the
same cap and life (H-A-229, H-A-344 (3)). 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 |
@@ -146,7 +155,8 @@ and both are read whole. Lines are cited as "design 47 H2 §n" whichever file ho
| `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 |
| `outputs`, install archives included | each build module, their owner (§791, §800) | objects | 1 GiB | 7 days (the store's max-age) | the bus, at the max-age; no sweep |
| the findings stream | every module (§783) | events | 8 MiB | 7 days | the bus, oldest first |
| `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 |
@@ -160,6 +170,7 @@ and both are read whole. Lines are cited as "design 47 H2 §n" whichever file ho
| 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 |
| `assigner_keep_now` | assigner | the keeping of the graph's revisions, now | §813 (2) |
| `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 |
@@ -10,6 +10,7 @@ decisions:
- "ADR 0668"
- "ADR 0666"
- "ADR 0664"
- "ADR 0619"
- "ADR 0596"
- "ADR 0595"
- "ADR 0573"
@@ -108,9 +109,12 @@ its own pipelines, with no hand pack (section 7 of the plan). Its two proofs (§
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.
the runner's health names a step whose ask is untaken past `stalled-bound` (§790), and an ask still untaken
`ask-unanswered-bound` after its `asked-at` ends the step could-not-run "its ask was not taken: <seat>'s holder takes
none", so no slot is held without end (H-A-344 (6)). 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; an ask untaken for the whole bound ends could-not-run naming the
holder as not taking.
### mesh-sdk: the shared forms
@@ -144,10 +148,11 @@ its own pipelines, with no hand pack (section 7 of the plan). Its two proofs (§
handle guard each call the client does not allow at once with a lock inside the wrapper, so no module needs a
handle per goroutine (one place, principle 7). Built in H2 in mesh-sdk. How it is checked: unit under the race
detector: concurrent gets, puts and watches through one wrapper.
- §783 **A module's findings history drops its oldest.** (ADR 0595 §2, §3; H-A-227; row 104) The stream a module's
findings writer appends to (three stood full on 2026-11-21: the runner's, the builder's, the node-engine's) is asked
for by the events template, which drops the oldest when full, with `findings-max-age` (default 7 days); its fill is
read through the seat `mesh-broker`'s `show`. The findings state itself is unchanged. Built in H2 in mesh-sdk (the
- §783 **A module's findings history drops its oldest.** (ADR 0595 §2, §3; H-A-227, H-A-344 (3), (5); row 104) The
stream a module's findings writer appends to (three stood full on 2026-11-21: the runner's, the builder's, the
node-engine's) is asked for by the events template, which drops the oldest when full, with `max-bytes` 8 MiB and
`findings-max-age` (default 7 days); a foundation part (ADR 0619 §1, ADR 0666 §4) declares it in its old section
with the same cap and life (H-A-229). Its fill is read through the seat `mesh-broker`'s `show`. The findings state itself is unchanged. Built in H2 in mesh-sdk (the
writer's requires) and every delivery module's manifest. How it is checked: whole (runner): 10,000 findings written
past the cap refuse none.
@@ -271,10 +276,10 @@ its own pipelines, with no hand pack (section 7 of the plan). Its two proofs (§
`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
with the why `fetch: <words>` or `publish: <words>`, whichever met the fault (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:`.
with `fetch:` and with `publish:` respectively.
- §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,