diff --git a/03-DESIGN/01-to-be/47-milestones/H2-stores-and-tools.md b/03-DESIGN/01-to-be/47-milestones/H2-stores-and-tools.md index dfd7147a..7972fd7d 100644 --- a/03-DESIGN/01-to-be/47-milestones/H2-stores-and-tools.md +++ b/03-DESIGN/01-to-be/47-milestones/H2-stores-and-tools.md @@ -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 | diff --git a/03-DESIGN/01-to-be/47-milestones/H2-the-delivery-systems-owed-work.md b/03-DESIGN/01-to-be/47-milestones/H2-the-delivery-systems-owed-work.md index aeeba346..30a04f85 100644 --- a/03-DESIGN/01-to-be/47-milestones/H2-the-delivery-systems-owed-work.md +++ b/03-DESIGN/01-to-be/47-milestones/H2-the-delivery-systems-owed-work.md @@ -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: '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: ` (ADR 0664 §2), which the builder and the runner say apart from a build's failure. Built + with the why `fetch: ` or `publish: `, 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,