From b08147e5318db423c625249842a48d17adefddd5 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 03:00:44 +0100 Subject: [PATCH] Answer the questions of milestone G's final prepare in its part, so develop starts from the design alone The prepare found about a hundred places where G's lines left the builder a choice. Each answer is now a line of G-9 with its question and its check: one default of callers per verb class, so no verb is closed for lack of a list; the seat-definition forms; kept data and restore points; versions; steps and test counting; the readers and the gate's remaining parts. Earlier lines the answers change are amended in place. Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../47-delivery-from-commit-to-delivered.md | 2 +- .../G-1-pipelines-registration-and-steps.md | 2 +- .../G-2-pipelines-sizes-checks-and-tools.md | 2 +- .../G-4-revision-view-and-steps.md | 13 +- .../47-milestones/G-6-verbs-and-retires.md | 8 +- .../01-to-be/47-milestones/G-7-answers.md | 20 +- .../G-8-findings-heard-as-events.md | 6 +- .../47-milestones/G-9-prepare-answers.md | 250 ++++++++++++++++++ 03-DESIGN/01-to-be/47-milestones/G.md | 6 +- .../51-the-registries-keep-what-is-named.md | 2 +- 10 files changed, 283 insertions(+), 28 deletions(-) create mode 100644 03-DESIGN/01-to-be/47-milestones/G-9-prepare-answers.md diff --git a/03-DESIGN/01-to-be/47-delivery-from-commit-to-delivered.md b/03-DESIGN/01-to-be/47-delivery-from-commit-to-delivered.md index 267d5a29..2723d9da 100644 --- a/03-DESIGN/01-to-be/47-delivery-from-commit-to-delivered.md +++ b/03-DESIGN/01-to-be/47-delivery-from-commit-to-delivered.md @@ -1,7 +1,7 @@ --- layer: to-be status: in-progress -code: [mesh-controller, mesh-catalog modules/mesh-delivery-gate, mesh-catalog modules/gitea, mesh-delivery, mesh-host, mesh-sdk, mesh-vault, mesh-contracts, hq 00-META/checks] +code: [mesh-controller, mesh-catalog modules/mesh-delivery-gate, mesh-catalog modules/gitea, mesh-delivery, mesh-host, mesh-sdk, mesh-vault, mesh-contracts, mesh-tools, mesh-networking, hq 00-META/checks] updated: 2026-11-11 decisions: - "ADR 0667" diff --git a/03-DESIGN/01-to-be/47-milestones/G-1-pipelines-registration-and-steps.md b/03-DESIGN/01-to-be/47-milestones/G-1-pipelines-registration-and-steps.md index e6dcba40..068a18f7 100644 --- a/03-DESIGN/01-to-be/47-milestones/G-1-pipelines-registration-and-steps.md +++ b/03-DESIGN/01-to-be/47-milestones/G-1-pipelines-registration-and-steps.md @@ -255,7 +255,7 @@ check and deliver milestone G itself (ADR 0667 §2); each of them says so in a l revision the runner says one `group-ended` once every member's modules have ended, and the assigner writes the group's wants only on it: a member's own `pipeline-ended` writes nothing (ADR 0666 §9). - §30 **A failed `optional` step holds nothing.** It is shown in `pipeline-ended`, in the delivery record and in the runner's - `show`; a person may accept it by the runner's verb `accept`, recorded in the hand-act log with who and why. + `show`; the operator may accept it by the runner's verb `accept` (§394), recorded in the hand-act log with who and why. - §31 **A newer commit supersedes an older pipeline of a module whose fingerprint it changed.** On a newer commit of the same watched branch the runner ends a module's older running pipeline as `superseded` only when the newer commit changed that module's build-input fingerprint (ADR 0666 §9); a module the commit leaves as it was finishes its diff --git a/03-DESIGN/01-to-be/47-milestones/G-2-pipelines-sizes-checks-and-tools.md b/03-DESIGN/01-to-be/47-milestones/G-2-pipelines-sizes-checks-and-tools.md index ecd38119..b1b6cc7d 100644 --- a/03-DESIGN/01-to-be/47-milestones/G-2-pipelines-sizes-checks-and-tools.md +++ b/03-DESIGN/01-to-be/47-milestones/G-2-pipelines-sizes-checks-and-tools.md @@ -117,7 +117,7 @@ One file of milestone G's part of [design 47](../47-delivery-from-commit-to-deli - §68 **Callers per verb, in the seat's definition.** Each seat definition names, per verb, the callers allowed to call it, in its field `callers` (holder roles, modules, the operator, the healers), which the grants part reads as its one source of caller limits; the runner's verbs are the first (ADR 0666 §20). A verb whose definition names no `callers` - admits only the seat's holder roles and the operator, so a field left out opens nothing. It replaces the holder's + takes the default of its class (§391), so no verb is closed for lack of a list. It replaces the holder's trusted config value `callers` of the seat `git` and the package seats (design 51), which no holder set for most verbs. A format its running reader cannot read, so its reader is delivered first (ADR 0667 §4). - §69 **A step's result from its holder only.** The runner takes a step's result only from the bus account of that step's diff --git a/03-DESIGN/01-to-be/47-milestones/G-4-revision-view-and-steps.md b/03-DESIGN/01-to-be/47-milestones/G-4-revision-view-and-steps.md index b4cfe0a4..ace14f36 100644 --- a/03-DESIGN/01-to-be/47-milestones/G-4-revision-view-and-steps.md +++ b/03-DESIGN/01-to-be/47-milestones/G-4-revision-view-and-steps.md @@ -3,7 +3,7 @@ layer: to-be status: in-progress design: 47 milestone: G -updated: 2026-11-10 +updated: 2026-11-11 decisions: - "ADR 0667" - "ADR 0666" @@ -62,8 +62,8 @@ One file of milestone G's part of [design 47](../47-delivery-from-commit-to-deli indexer declares no state `modules` and serves neither its tool `indexer_read_modules` nor a view of it (*Reverted*, above), so every module that learns from it which modules exist moves in milestone G, not after: the watchman (its manifest findings), the status view (`view_reach`), the forge module (which repositories its account writes), the - holders of the seats `mesh-config`, `mesh-provisioner` and `mesh-self-check`, the claude-code module and the tool - runner. Each takes a first view of the catalog half by the seat `mesh-catalog`'s verb `revision` and follows its + holders of the seats `mesh-config`, `mesh-provisioner` and `mesh-self-check`, the claude-code module, the tool + runner and the node-engine (§421). Each takes a first view of the catalog half by the seat `mesh-catalog`'s verb `revision` and follows its event `catalog-revision`, through `meshcatalogclient` in Go or the seat's generated TypeScript contract in the forge module, names the seat and never the indexer, and keeps no list of its own (ADR 0656 §6, ADR 0596 §2; ADR 0615 §1, under which every reader of the indexer's state moves in one milestone). A reader that misses a `catalog-revision` @@ -266,9 +266,10 @@ and the assignment graph revisions; an entry taken in, built, checked, composed, entry's fingerprint and its node. The gate's delivery record is built from them. The seat's event comes first where the parts follow it through a seat (ADR 0656); a holder's own event stays under its own subject, declared in its own manifest's `streams` and published on `mesh.stream..event.` (ADR 0363 §1, §2). A seat's event is -declared in its definition and its holder's manifest claims the seat; a seat event's name has no dot, since it is read -as a subject's token, and it is kept on the stream `SEAT__`, which the grants part makes with its durable -consumers, keeping it by the age and cap the definition's `keep` names, 90 days unless it names less. **An event a node publishes carries the node in +declared in its definition and its holder's manifest claims the seat; an event whose definition names `keep` has no +dot in its name and is kept on the stream `SEAT__`, which the grants part makes with its durable +consumers, keeping it by the age and cap `keep` names (§396), and an event naming no `keep` stays on its seat's family +stream. **An event a node publishes carries the node in its subject**, and the grants part grants each node-engine's account only its own node's subjects, so one node cannot say another runs a build (ADR 0363 §2); the gate's events are granted to the gate's account alone. diff --git a/03-DESIGN/01-to-be/47-milestones/G-6-verbs-and-retires.md b/03-DESIGN/01-to-be/47-milestones/G-6-verbs-and-retires.md index 8e88fddd..e740f369 100644 --- a/03-DESIGN/01-to-be/47-milestones/G-6-verbs-and-retires.md +++ b/03-DESIGN/01-to-be/47-milestones/G-6-verbs-and-retires.md @@ -3,7 +3,7 @@ layer: to-be status: in-progress design: 47 milestone: G -updated: 2026-11-10 +updated: 2026-11-11 decisions: - "ADR 0667" - "ADR 0666" @@ -106,9 +106,9 @@ parts' manifests declare in `invokes` and `consumes` and what their code calls, | Event of the seat | Says | Heard by (today's event) | |---|---|---| -| `pull.updated`, `pull.merged`, `pull.closed` | a pull request's new head, its merge with the merge commit, its close | the forge bridge, the gate (`gitea.pull.*`) | -| `forge.pull`, `forge.status`, `forge.delete` | the forge's own webhook of a pull request, of a commit status, of a deleted branch | the gate (`forge.pull`, `forge.status`), the forge bridge (`forge.delete`) (`gitea.forge.*`) | -| `repo.writable` | a repository the forge can write again | the gate (`gitea.repo.writable`) | +| `pull-updated`, `pull-merged`, `pull-closed` (§396) | a pull request's new head, its merge with the merge commit, its close | the forge bridge, the gate (`gitea.pull.*`) | +| `forge-pull`, `forge-status`, `forge-delete` | the forge's own webhook of a pull request, of a commit status, of a deleted branch | the gate (`forge.pull`, `forge.status`), the forge bridge (`forge.delete`) (`gitea.forge.*`) | +| `repo-writable` | a repository the forge can write again | the gate (`gitea.repo.writable`) | | `branch-moved` | from milestone G's delivery: a branch's new head, by a merge or an admitted push, from the forge's push webhook | the forge bridge | §311 Each is said on `mesh.seat.git.event.`, declared in the seat's definition, and heard through the hearer's diff --git a/03-DESIGN/01-to-be/47-milestones/G-7-answers.md b/03-DESIGN/01-to-be/47-milestones/G-7-answers.md index 0714bc9f..581395ab 100644 --- a/03-DESIGN/01-to-be/47-milestones/G-7-answers.md +++ b/03-DESIGN/01-to-be/47-milestones/G-7-answers.md @@ -62,7 +62,7 @@ record it follows from, and replaces the builder's own choice where one was made unit step leaves the approval `not asked`; its passing rerun asks it, and once approved the second `pipeline-ended` writes the want. - §326 **A build seat keeps its `steps` answer.** The build module keeps each artifact's detected steps in its state - `steps`, from the template `state`, one key per artifact holding the answer for that artifact's newest build-input + `detected-steps` (§414), from the template `state`, one key per artifact holding the answer for that artifact's newest build-input fingerprint, replaced when a newer fingerprint is detected and by `steps` with `again`; a key whose artifact no longer exists is dropped by `steps` with `drop`, on a person's word, written in the hand-act log. With one key per artifact (about 120) the state needs no aging and no read time. Why: ADR 0666 §25 asks a tool for "the steps @@ -90,7 +90,8 @@ record it follows from, and replaces the builder's own choice where one was made 30 days each `kept` digest the entry names whose `last-read` is past 30 days; at 90 days the passed pipeline the entry names, unless it is its branch's newest. It then moves the sequence; nothing is scanned whole. Each delete writes a line in the runner's journal naming the key or object and its retention. A foundation part's sent store - (`sent-objects`) is aged the same way by its owner at each send, from the sequence of its own sends. Nothing waits on + (`sent-objects`) is aged the same way by its owner at each send, from the sequence of its own sends, which mesh-sdk's + sender keeps in the owner's old `state` section (§410). Nothing waits on a timer, and nothing but the owner deletes. Why: an old section cannot declare an age, and deleting one's own entries is the owner's act, not the removal of a store ADR 0595 §4 holds to a person's word; §57's rule that only the drop tool removes an object holds for a template's `-objects`, while the runner's `step-outputs` are its own old @@ -99,10 +100,10 @@ record it follows from, and replaces the builder's own choice where one was made - §331 **The kept event streams' caps, and when one is full.** On the seat `mesh-pipeline-runner`, each kept 90 days: `pipeline-started` 32 MiB, `pipeline-ended` 192 MiB, `group-ended` 64 MiB, `run-started` 16 MiB, `step-started` and `step-ended` 128 MiB each, `wait-held` and `wait-ended` 32 MiB each; the seat `git`'s `branch-moved` 64 MiB; each - build seat's `step-ended` 128 MiB; `mesh-wants`'s `step-ended` 32 MiB; `mesh-builds`' `package-published` and - `mesh-catalog`'s `registration-changed` 16 MiB each; `package-published` 128 MiB; `version-released` 128 MiB, - `version-delivered` 64 MiB, `toolchain-agreed` 16 MiB, and `versions-filled` 1 MiB with no age limit; all others - 90 days. At about 300 releases a day (a mesh-sdk publish rebuilding about 120 modules), `package-published` of about + build seat's `step-ended` 128 MiB; `mesh-wants`'s `step-ended` 32 MiB; `mesh-catalog`'s `registration-changed` 16 MiB; + `mesh-builds`' `package-published` 128 MiB; `mesh-delivery`'s `owed` 7 days and 64 MiB (§396); `version-released` 128 MiB, + `version-delivered` 64 MiB, `toolchain-agreed` 16 MiB, and `versions-filled` 1 MiB with no age limit; every other kept + event 90 days and 16 MiB (§396). At about 300 releases a day (a mesh-sdk publish rebuilding about 120 modules), `package-published` of about two artifacts each and `version-released` each say about 0.6 MiB a day, about 54 MiB in 90 days, and `version-delivered` about 27 MiB. Why: about 300 pipelines a day of about 6 steps (*The runner's kept data*) say about 1,800 step events a day of about 0.5 KiB, about 80 MiB in 90 days, and about 300 @@ -151,7 +152,8 @@ record it follows from, and replaces the builder's own choice where one was made `persons`, and every other text the names the design gives that verb. Why: ADR 0666 §20 makes the definition the grants part's one source of caller limits, in a form it reads; `invokers`, which ADR 0666 §20's list does not name, is the operator's choice for the verbs whose text said "any caller whose role grants it" (Telegram, 2026-11-11 02:13 - CET: "Any declaring module"), and by the same answer, that a verb open today stays open to any module declaring it, + CET: "Any declaring module"; every verb's default by its class is §391, a holder role and a module written + `seat:` and `module:`, §392), and by the same answer, that a verb open today stays open to any module declaring it, for the fifteen verbs of the Connectivity domain's seats that name no `callers` on main, which §68 would otherwise close to their holders and the operator: `node-hostname`'s `entries`, `add` and `remove`; `node-intrusion-prevention`'s `status`, `banned`, `ban` and `unban`; `node-packet-filter`'s `rules`, `reload` and @@ -175,7 +177,7 @@ record it follows from, and replaces the builder's own choice where one was made above. Why: one source of caller limits (ADR 0666 §20). How it is checked: the generator's test refuses an unknown entry. - §340 **The reader release first.** mesh-sdk's seat-definition reader released before G's check reads `callers` as text - or as a list; G's own reader refuses text. The same release carries mesh-sdk's manifest reader of the new words of + or as a list; G's own reader refuses text; it reads every new form G writes (§409). The same release carries mesh-sdk's manifest reader of the new words of §89 (`version`, a `*` emitter in `consumes`, an observer's finding stream), which the running checker's validator reads before G's manifests use them. Why: readers first (ADR 0667 §4), and every definition is a list from G; it is merged ahead of G's check because the running checker, which makes G's own check (ADR 0667 §2), must read G's definitions, the operator's choice of a @@ -384,7 +386,7 @@ record it follows from, and replaces the builder's own choice where one was made `builder_versions` also answers each reserved version with its artifacts' digests (§369), so a registry holder still on its version before G, which asks `builder_versions`, stores a publish of a reserved version made between the builder's delivery and its own (§381). The builder's state - `versions`, the floor and its tool `builder_floor_again`, the event `numbered`, `builder_versions`, and `tag-asks` are + `versions`, the floor and its tool `builder_floor_again` and `builder_versions` are removed in the first change after the first pipeline after G's delivery has delivered a change end to end, the state through `drop` on a person's word (ADR 0595 §4). Why: numbering reads only the catalog's released versions (§348), and without this every first version under G would start below today's and Go's `@latest` would never move (the design's choice, round 2 of the review by architectural domain, 2026-11-10). diff --git a/03-DESIGN/01-to-be/47-milestones/G-8-findings-heard-as-events.md b/03-DESIGN/01-to-be/47-milestones/G-8-findings-heard-as-events.md index 3daebf3a..d7d90e65 100644 --- a/03-DESIGN/01-to-be/47-milestones/G-8-findings-heard-as-events.md +++ b/03-DESIGN/01-to-be/47-milestones/G-8-findings-heard-as-events.md @@ -39,8 +39,8 @@ record says so in its Why. Round 3 of the review by architectural domain (2026-1 next statement of §384 covers a lost one), published on `mesh.stream..event..`, the node it runs on in the subject (ADR 0363 §2; §260). `finding-written` is said when a finding is raised or what it says changes, and only then (ADR 0289 §1, §4); `finding-cleared` when the observer no longer observes it. `finding-written` - carries `scope`, `id` and `kind` (the key `..` of ADR 0564 §2), `severity`, `subject`, `evidence`, - ADR 0253's words (`headline`, `explanation`), `since` and `at`; `finding-cleared` carries `scope`, `id`, `kind`, `at` + carries the finding's layout whole, plus `scope`, `id` and `kind` (the key `..` of ADR 0564 §2) and + `since` (§437); `finding-cleared` carries `scope`, `id`, `kind`, `at` and `why`. The observer and the node are the subject's alone: the grants part grants each module's account publish on its own stream's subjects of its own node's segment only, the keeper takes both from the subject, and it refuses an event whose body names another observer or node, said in its journal. mesh-sdk's finding writer (`go/views`' @@ -141,7 +141,7 @@ record says so in its Why. Round 3 of the review by architectural domain (2026-1 the catalog's holder stopped it raises and clears from its kept sources' events, raises `view-waits` after five minutes itself, and clears nothing with `module left the node` until the assignment half answers. - §389 **The watchman says a machine's presence as events.** The seat `mesh-watchdogs` gains the events `machine-away` - and `machine-back` (`mesh.seat.mesh-watchdogs.event.machine-away.`, `.machine-back.`, carrying the node, + and `machine-back` (`mesh.seat.mesh-watchdogs.event.machine-away.`, `.machine-back.`, §436, carrying the machine, `at` and since when it was last heard), said by the watchman when its presence key of a machine expires and when the machine is heard again (ADR 0564 §4), declared in the seat's definition and kept 90 days, 16 MiB. The keeper consumes them for `findings-unstated` (no machine away is named, and an ask is said again to a module of a machine diff --git a/03-DESIGN/01-to-be/47-milestones/G-9-prepare-answers.md b/03-DESIGN/01-to-be/47-milestones/G-9-prepare-answers.md new file mode 100644 index 00000000..1cbb06d6 --- /dev/null +++ b/03-DESIGN/01-to-be/47-milestones/G-9-prepare-answers.md @@ -0,0 +1,250 @@ +--- +layer: to-be +status: in-progress +design: 47 +milestone: G +updated: 2026-11-11 +decisions: + - "ADR 0670" + - "ADR 0668" + - "ADR 0667" + - "ADR 0666" + - "ADR 0656" + - "ADR 0636" + - "ADR 0625" + - "ADR 0615" + - "ADR 0596" + - "ADR 0595" + - "ADR 0564" + - "ADR 0363" +--- + +# 47, milestone G: the answers to the questions of G's final prepare + +One file of milestone G's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at +[G.md](G.md). Its design lines are numbered across every file of the part and cited as "design 47 G §n". + +## What G's final prepare found open, answered by this design (2026-11-11) + +*G's final prepare (lead-47, 2026-11-11) collected about a hundred questions from its preparers, each cited here by +its id in that prepare: Q1 to Q19 (mesh-contracts), S1 to S18 (mesh-sdk), Q-H1 to Q-H11 (`mesh-host`), Q-T1 to Q-T8 +(mesh-tools), C1 to C22 (mesh-catalog) and D1 to D19 (mesh-delivery). Each line is the design's own choice within the +records it cites, or the operator's intent already given, or the operator's answer, said as such. Where several +preparers asked one thing, one line answers all. A line that changes an earlier line amends it there; the earlier +line says so.* + +### Who may call a verb + +- §391 **Every verb takes a default of callers by its class.** From the operator's answers of 2026-11-11 (02:13 CET, + "Any declaring module"; 02:47 and 02:56 CET, "As proposed"), a verb's definition names its class in the field + `class`, and a verb whose definition names no `callers` takes its class's default, which the seat-definition reader + applies and the manifest validator says per verb ("`.` takes the default of ``"): a `read`, the + class a verb names none of, takes `invokers`, `persons` and `sessions`, so every verb open today stays open; an + `act` (a new act that changes what the mesh does: registers, sets a policy, watches or unwatches a branch, + recovers) takes `operator` and `sessions`; a `warrant` (a verb that runs on the operator's warrant) takes `operator` + and carries the approval mark; `accept` is the operator's alone (§394). A verb that names `callers` keeps them, so + no verb is closed by §68 for lack of a list. Why: ADR 0666 §20 makes the definition the one source of caller + limits; the operator asked on 2026-11-11 why caller questions kept coming, and answered them as one rule (Q1, S3, + C3, D2's reads, Q18). How it is checked: unit (seat-definition reader), a table test with one row per class, and a + row for a verb with `callers` of its own; unit (manifest validator), the default each verb took is said. +- §392 **A caller entry names its kind of name.** In `callers`, a holder role is written `seat:` and a module + `module:`, beside `operator`, `healers`, `persons`, `sessions`, `invokers` and `holder:@same-node` + (§336), since a name such as `mesh-grants` is both a seat and a module. Why: the design's choice (Q2). How it is + checked: unit (definition reader), a bare name refused, both prefixed forms accepted. +- §393 **The node-engine's eleven verbs name today's callers.** The eleven verbs of the seat `node-engine` that name + no `callers` on main get, in their definition, the callers the node-engine's compiled callers table names for each + on main, written in §392's forms, and that table goes from the node-engine's code: the definition is the one + source (§68). Why: the design's choice (Q-H8). How it is checked: unit (definition reader), each of the eleven names + its callers; the code review finds no callers table in the node-engine. +- §394 **The callers of G's new trusted acts.** `mesh-catalog`'s `register`, `policy`, `watch` and `unwatch`, and + `mesh-delivery`'s `recovery`, are of class `act`: the operator and sessions; `registrations` is a `read`. + `mesh-pipeline-runner`'s `review` is called by sessions, and refused from the change's author (§70); its `accept` by + the operator alone, which amends §30's "a person". `operator-channel`'s `ask-again` is a seat verb, its callers the + operator and the healers (§83, §40). Why: the operator, 2026-11-11 02:56 CET on Telegram, "As proposed" (S4, S10, + C18, D2, D3, D4). How it is checked: whole (indexer, runner, operator-channel), a call from any other caller is + refused by the bus; unit (definition reader), each verb's class and callers. +- §395 **An accepted kind naming no callers keeps today's grant.** `operator-channel`'s kinds `ask`, `cancel` and + `condition` keep the grant they have today, open to every asker, so the runner's approval (§37), the seed ask (§8) + and every other asker are not refused (§338). Why: the operator's intent, a verb open today stays open (Q18). How it + is checked: whole (operator-channel), an asker's `ask` is taken. + +### The forms of a seat's definition + +- §396 **A dot only where no stream is named from the event; `keep`'s form.** An event whose definition names `keep` + has no dot in its name, since its stream `SEAT__` is named from it; an event naming no `keep` stays on + its seat's family stream and may have a dot. `keep` is an object `{max-age-days, max-mib, last-per-subject}`, its age + 90 days and its cap 16 MiB unless it names others (§331). The seat `git`'s events take hyphens: `pull-updated`, + `pull-merged`, `pull-closed`, `forge-pull`, `forge-status`, `forge-delete` and `repo-writable` (§310), and `owed` is + kept on its seat stream 7 days and 64 MiB (§162). This amends §260. Why: the design's choice (Q3, Q4, S5, C1, C2). + How it is checked: unit (definition reader), a dotted event with `keep` refused, one without accepted, `keep`'s + defaults. +- §397 **The forms of `subject`, `acts.on` and `bound`.** `subject` is the words after `mesh.seat..event.` with + `` tokens, `` written out; `acts.on` is one string, `every`, a language, or `kind:image`; `bound` is a + duration such as `30m`. Why: the design's choice (Q5). How it is checked: unit (definition reader), each form + accepted and another refused. +- §398 **The step `place` is `mesh-wants`'.** The step `place` is declared in the definition of the seat `mesh-wants`, + where §260's table has the assigner's placing waits. Why: the design's choice (Q6). How it is checked: the seat's + fixtures. +- §399 **A binding names its objects and its sent store.** The binding of a state, as the seat `mesh-broker` answers + it, gains `objects`, the bus name of its `-objects` (§58), and a module's sent store is a binding entry + `sent-objects` (§59), so a module learns both names from its bindings. Why: the design's choice (Q7). How it is + checked: unit (mesh-broker's contract), a binding with both read. +- §400 **No new verb is optional.** A verb G adds is not `optional`: the order of its holder's delivery is §298's + edges, and a claim refused meanwhile is a gap of the delivery system built within G (§93). Why: the design's choice + (Q9). How it is checked: unit (definition reader), no verb G adds is marked `optional`. +- §401 **The seat `mesh-grants` has no verbs in G.** Its definition carries its rule and its four events only; its + module's tools `grants_waits`, `grants_release`, `grants_callers` and `grants_why_refused` stay its own. Why: the + design's choice (Q12). How it is checked: the seat's fixtures. +- §402 **A placement's `build` is a fingerprint, and `unwatch` waits for the placements.** A placement's `build` names a + fingerprint; `unwatch` refuses while a placement names the branch, naming the placement. Why: the design's choice + (Q13). How it is checked: whole (indexer), `unwatch` of a placed branch refused. +- §403 **A held-back ask.** A held-back ask (§83, design 46 §6) is answered in `asks` with the state `held-back` and the + field `held-since`, and no field `behind`. Why: the design's choice (Q14). How it is checked: the seat's fixtures. +- §404 **The node-engine's events' bodies.** `capabilities-changed` carries the node record's stated capabilities whole + and `at`; `composed` the module, the fingerprint and the composition's digest; `running` with `stopped` carries + `stopped: true` and no fingerprint (§365). Why: the design's choice (Q17). How it is checked: the seat's fixtures. + +### Kept data on the bus, restore points and the reader release + +- §405 **The bus module's restore points and node-backup's verbs.** The seat `mesh-broker` gains `snapshot-kept` and + `restore-kept`, their callers `holder:node-backup@same-node` (§337); the seat `node-backup`'s `now` and `restore` + gain `kept`, `form` and `fingerprint`, and say `ended.` and `restored.`, each keyed by the module, the + kept data, its form and the fingerprint; listing and discarding stay node-backup's `backed-up` and `discard-aside` + (§302). Test 36's whole case lives in `mesh-host`. Why: the design's choice, one answer to three preparers (Q8, S9, + Q-H6, C19's verb names). How it is checked: test 36; a call of `snapshot-kept` from another node's `node-backup` + holder is refused by the bus. +- §406 **A catch-up names its tool and arguments.** A restore point records the catch-up tool and its arguments whole + (§299), and the restored manifest grants that tool to `holder:node-engine@same-node`. Why: the design's choice (Q-H7). + How it is checked: whole (node-engine), a restore runs its recorded catch-up. +- §407 **The object store package.** mesh-sdk's object store package is `go/stateobjects`; it also takes a foundation + part's old `objects` section (§58, §346). A reply or event over the limit is made an object by that package through + §345's put session, and read back through the same session form for a get; the call that reads a sent object is + `mesh/objects.sent-get`, under the existing capability (§347). A foundation part's bundle is bound to its old + `objects` section as its states are (§176, §194). Why: the design's choice (S14, D17, Q-T3, S13, Q-T4, Q-T5). How it + is checked: unit (`go/stateobjects`), an old section and a template store each take a large value; whole (tool + runner), a large reply read back. +- §408 **The ledger's calls.** The ledger's fill and removal calls are in mesh-sdk's `buscalls`, under the existing + `ledger` calls (§155, §159, §181); no capability word `ledger-fill` is added. Why: the design's choice (S15, Q-T6). + How it is checked: the code review. +- §409 **The reader release reads every new form G writes.** The reader release of §340 reads every new definition + form and manifest word G writes: `callers`, `class`, `keep`, `subject`, `acts`, the step `pipeline`, `on` + `kind:image`, `version`, the `*` emitter, an observer's finding stream, and an artifact's `needs`; `check` stays + beside `pipeline` until the checker is removed (§97, §203). Why: readers first (ADR 0667 §4; S2, S18). How it is + checked: unit (the release's reader), each form read. +- §410 **A foundation part's sent store keeps its send sequence.** mesh-sdk's sender keeps the sequence of a foundation + part's sends in the owner's old `state` section and ages `sent-objects` from it at each send (§330). Why: an + `objects` section has no sequence (S7). How it is checked: unit (sender), a send past 7 days ages the oldest. + +### Versions + +- §411 **`version` replaces the old field, and `series` goes.** Every manifest's top-level `version` takes the + `MAJOR.MINOR` of §368 in the same change, replacing today's `"1"`, and each artifact's `series` goes, refused by the + manifest validator; a contracts module's version is `0.1` unless §372's fill gives higher. Why: one version per + module (§52, §374; Q15, S1, Q-H3, D14). How it is checked: unit (manifest validator), `series` refused. +- §412 **The first fill's sources.** §372's fill reads, per module, the packages its catalog entry names in their + ecosystems (the Go module path, the npm name); where the builder holds no version of a package, the forge's tags of + its repository (`go/vMAJOR.MINOR.PATCH`) are the floor. Why: the live builder answers none for mesh-sdk while the + forge holds `go/v0.1.14` (S17, C9). How it is checked: whole (indexer), a module with tags and no builder versions + fills from the tags. +- §413 **`tag-asks` and `version.numbered` go at G's delivery.** The builder's `tag-asks` and its event + `version.numbered` are removed at G's delivery, as §373 has for the tagged versions; the build modules consume + `version.numbered` no more from G. This amends §372. Why: the design's choice (D19). How it is checked: the + catalog's validation at G's heads finds no `consumes` of `version.numbered`. + +### Steps, tests and pipelines + +- §414 **The build seats' state is `detected-steps`.** The state §326 names `steps` is `detected-steps`, apart from + today's step keys `steps`. This amends §326. Why: the design's choice (C5, D13). How it is checked: whole (Go build + module), as §326. +- §415 **Kinds on the stream `check`, and a recovery's steps.** A step ask is the kind `check.step`, a run on request's + `check.run`; a recovery's steps are `delivery.step`, which the runner may publish (§86). Why: the design's choice + (D5, C6). How it is checked: whole (runner, Go build module), a recovery's step is taken from `delivery` first. +- §416 **A step ask carries the kept results.** The runner's step ask carries the kept results by package digest + (§25), so a build seat runs only the packages without one. Why: the design's choice (C7). How it is checked: whole + (Go build module), a carried package is not run. +- §417 **Go's lint is gofmt and vet.** Go's lint step runs gofmt and go vet, in the lint step only (§328). Why: the + design's choice (C8). How it is checked: whole (Go build module), a vet failure fails lint and no unit step. +- §418 **The repository checks run as a step.** Each repository's own checks, which the checker runs today, run as a + pipeline step of its build seat from G's delivery. Why: the checker goes (C20). How it is checked: whole (runner), + a failing repository check fails its step. +- §419 **How tests are counted.** A test is a top-level Go test function or a TypeScript `test(` call; an existing + module ends G with no more tests than it starts with, and the new runner within 50 integration and 500 unit tests; a + module over the budget at its start is named in the pipeline's end. Why: the test budget per module (S16, D6). How + it is checked: `pipeline-ended`'s counts. +- §420 **A run on request's key, and the step-run package.** A run on request is keyed by the run's id under its named + branch (§54, §64, §85); the step-run code is the delivery SDK's package `sdk/steprun`, and the runner's + client sits beside the other seats' clients; the runner's kept data layouts are the seat's `states` (§27, §306). Why: + the design's choice (D16, D8, D10). How it is checked: whole (runner), two runs of one commit are two pipelines. + +### Readers, branches and the node-engine + +- §421 **The node-engine reads the catalog half for its branch.** The node-engine joins §196's readers: it reads the + manifests and verdicts of the modules it composes from the catalog half, of the branch each module's placement + names, and the parts by digest from its want (§379); its reads of the indexer's and builder's states go. The tool + runner follows every watched branch's newest `catalog-revision`, as §365. Why: ADR 0596 §2 (Q-H1, Q-H2, Q-T8). How it + is checked: the node-engine's manifest reads no other module's state; test 61. +- §422 **The node-engine's first-view tools are seat verbs.** The node-engine serves its view's two tools as seat verbs + of `node-engine`, beside its seat-list verbs, since it serves no module tools. Why: the design's choice (Q-H4). How + it is checked: the seat's fixtures. +- §423 **A kept-build wait says the existing words.** A have waiting for a kept build (§271) says the existing phase and + words, with no new field. Why: the design's choice (Q-H10). How it is checked: whole (node-engine). +- §424 **Each process's own build, and each bundle's.** A process says `own build unknown` in its + `_first_views` (§205); each tools bundle's composed environment carries its module's fingerprint. Why: the + design's choice (S12, Q-T7). How it is checked: whole (tool runner), a bundle reads its fingerprint. +- §425 **A kept call asks again what its asker names.** An asker passes the kept-call form the ask's key and the event + that replaces it, and the form asks again only while that key is open and no replacing event was heard (§351). Why: + the design's choice (S11). How it is checked: unit (kept-call form). +- §426 **The tool runner keeps no waits list.** §74's session waits use `mesh_wait` on any event (ADR 0670), and + `gitea.forge.status` goes (§133). Why: ADR 0670 (Q-T2). How it is checked: the tool runner's manifest has no waits. + +### The gate, the forge and the move + +- §427 **The contracts and SDK folders move, importers in the group.** The delivery repository's contracts and SDK + move to `modules/mesh-delivery-contracts` and `modules/mesh-delivery-sdk`, their Go module paths and TypeScript names + renamed to match, and every importer moves in the same group. Why: design it as it should be (C4, D1). How it is + checked: the group's check builds every importer. +- §428 **The fixed names G removes.** Each name is read from the registrations, the catalog half or the seat list + (§7): in mesh-delivery, module names of the delivery parts, the forge module, the build modules, `mesh-grants`, + `mesh-config`, `mesh-vault`, `mesh-wireguard`, the tool runner and the bus module, and the branch `main`; in + mesh-catalog, the gate's merge branch, the SDK's repository and the teller's, view's and forge bridge's module + names, the forge module's base branch and the indexer's name and tool, and the build modules' indexer tool; in + `mesh-host`, the node-engine's own module name in its guard, compose and bootstrap; in mesh-sdk, the node-engine's + names (§364); in mesh-tools, the assigner's first views by name; in mesh-networking, `mesh-wireguard` and + `mesh-provisioner`. Why: the design's choice (Q-H9, C10, D7). How it is checked: the code review (§7). +- §429 **Lines "until G's delivery".** The new gate builds the forms from G's delivery and the switch (§156, §169) + alone; what holds only until G's delivery is not rebuilt. Why: the design's choice (C11). How it is checked: whole + (gate), test 36's gate half. +- §430 **The gate's sources before the first registrations.** The gate keeps `source.` per repository and + watched branch, the branch escaped as §73, following the registrations, and writes `source.` for + every repository from its start, before the first registrations (§15, §95). Why: the design's choice (C12, D18). + How it is checked: whole (gate), `source` answers before any registration. +- §431 **The fate of the gate's other parts.** From G's delivery the gate's `asks` go with the Approve per merge; + `deliveries`, `show`, `groups` and `stalled` are answered from the delivery records; `checks` and `settle` go with the + merge states, and the five verbs of release 6 leave the definition; the events `group` and `merged` go, their readers + moving to the seat `git`'s events, while `transition` stays; the reads of the teller's answers and the view's reach + are by their events, and of the checker's verdicts go with it. Readers of the gate's `source` move to the verb + `source` and `source-moved`, and the assigner reads no `merges`. Why: the design's choice (C13, C14, D9, D11). How it + is checked: whole (gate), each verb served or not as named. +- §432 **The edges a `needs` names.** An artifact's `needs` names artifact references `:` of the + catalog graph's edges (§95, §121). Why: the design's choice (C21). How it is checked: unit (manifest validator). +- §433 **The bus module reads the catalog half.** The bus module's `consumes` and its call of `indexer_bus_state` are + replaced by its view of the catalog half (§344). Why: ADR 0596 §2 (C22). How it is checked: its manifest. +- §434 **Findings name their owner and whom they wait on, and the keeper reads by events.** A finding of §33, §8 and + §75 carries `owner` and `waiting-on`; the keeper's other reads are by events or verbs, and no homes rows are added. + Hand-written finding code in Go moves to mesh-sdk's `FindingWriter`. Why: the design's choice (C16, C17, C15's Go + half). How it is checked: the code review; the keeper's manifest reads nothing. +- §435 **`compose-candidate` goes with the checker.** The node-engine's verb `compose-candidate`, whose caller is the + checker, is kept in G and removed in the change that removes the checker (§97), with the check's candidates. Why: + the design's choice (Q16, Q-H1's candidates). How it is checked: the seat's fixtures at G's heads keep it. +- §436 **A presence event names the machine, not its publisher.** `machine-away` and `machine-back` carry the machine + as a subject part named ``, which the grants part does not bind to the publisher's node, since the + watchman says them for another machine. This amends §389. Why: `` in a subject is the publishing node (§260; + S8). How it is checked: whole (watchman), the event for an away machine is published by the watchman's account. +- §437 **`finding-written` carries the finding's layout whole.** `finding-written` and each entry of `findings-stated` + carry the finding's layout as the state `findings` holds it whole (its `summary`, `source`, `observer`, `actions`, + `needs`, `resolver`, `ref` and `run` among it), plus `scope`, `id` and `since`, so a condition built from the event + alone loses nothing. This amends §383. Why: the design's choice (Q19). How it is checked: unit (writer), the event's + body holds every field of the key. +- §438 **The record names every repository G builds.** Design 47's milestones row and frontmatter `code:` name + mesh-tools and mesh-networking, and design 51's line on what a node-engine hears says it consumes the node-engine + seat's `running` (§199). Why: the design's choice (Q-T1, Q-H11). How it is checked: the index test. diff --git a/03-DESIGN/01-to-be/47-milestones/G.md b/03-DESIGN/01-to-be/47-milestones/G.md index de83d5c5..f1adc023 100644 --- a/03-DESIGN/01-to-be/47-milestones/G.md +++ b/03-DESIGN/01-to-be/47-milestones/G.md @@ -5,6 +5,7 @@ design: 47 milestone: G updated: 2026-11-11 decisions: + - "ADR 0670" - "ADR 0668" - "ADR 0667" - "ADR 0666" @@ -75,7 +76,7 @@ file on 2026-11-10, and is cited as "design 47 G §n". A sentence that holds a d stayed in the main file, and G builds what it says from G's delivery. A section named in italics is in this part, or, when it is not here, in the main file. -The part is eight files, each read whole, its design lines numbered across them: +The part is nine files, each read whole, its design lines numbered across them: - [G-1-pipelines-registration-and-steps](G-1-pipelines-registration-and-steps.md): pipelines per module: registration, watched branches, steps and policy, what holds a delivery, approval, groups, dependencies, a publish. - [G-2-pipelines-sizes-checks-and-tools](G-2-pipelines-sizes-checks-and-tools.md): pipelines per module: any size, the pipeline makes the check, who may say what, health, recovery, tools, kept data, how G itself is delivered, the choices under ADR 0666 and ADR 0667. @@ -84,4 +85,5 @@ The part is eight files, each read whole, its design lines numbered across them: - [G-5-acting-parts-check-and-kept-data](G-5-acting-parts-check-and-kept-data.md): the acting parts, the removed hold, the check on the change's own acting parts, after the merge, taken in, and kept data on the bus. - [G-6-verbs-and-retires](G-6-verbs-and-retires.md): the verbs G adds and what retires. - [G-7-answers](G-7-answers.md): the answers to the builders', the reviewers' and the operator's questions (§322 to §382). -- [G-8-findings-heard-as-events](G-8-findings-heard-as-events.md): the operator's answers of 2026-11-11, findings heard as events (§383 on). +- [G-8-findings-heard-as-events](G-8-findings-heard-as-events.md): the operator's answers of 2026-11-11, findings heard as events (§383 to §390). +- [G-9-prepare-answers](G-9-prepare-answers.md): the answers to the questions of G's final prepare (§391 on). diff --git a/03-DESIGN/01-to-be/51-the-registries-keep-what-is-named.md b/03-DESIGN/01-to-be/51-the-registries-keep-what-is-named.md index 0daf1a1c..9c15ff5c 100644 --- a/03-DESIGN/01-to-be/51-the-registries-keep-what-is-named.md +++ b/03-DESIGN/01-to-be/51-the-registries-keep-what-is-named.md @@ -239,7 +239,7 @@ the verb. matches `settled` by the holder its declaration names. A change of the seat's holder composes the declaration again, so the name it carries is the holder of now. The seat and the holder are not part of what a container is (they are not in its digest), so a declaration composed again for them replaces no container. **The seam that changes is the grants part's list of what a node-engine - hears** (`NodeAgentHears`; the node-engine declares no `consumes` of its own): it gains one entry, the status + hears** (`NodeAgentHears`; from design 47's milestone G the node-engine also declares its `consumes` of the node-engine seat's `running`, design 47 G §199, §438): it gains one entry, the status view's `settled` family, which the node-engine filters for the holder of the seat its failed image names. **At its own start** the node-engine also applies once more every have that failed naming an image of a store, so a restart or an absence across the swap misses nothing. A module already being applied is not applied a second time; a retry