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 33dbbbb4..dbe070ab 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 @@ -514,7 +514,9 @@ per module and node from the keys: provision `bus-state` holds no requirer for it (ADR 0614 §5, ADR 0429 §6). The rule reads what runs, never the phase of a want not yet applied: on 2026-11-09 a yes not yet asked on the bus held the delivery of every module asking bus state (issue 1966, note 150). How it is checked: whole (assigner), a provider whose new want waits for a yes, with its old - build running healthy, holds no consumer's want, and one whose running build is unhealthy holds it. + build running healthy, holds no consumer's want, and one whose running build is unhealthy holds it. From G's + delivery a new version ordered after its dependency's new version also waits until that version is delivered to + every present machine placing it (design 47 G §376). - **The canary before the rest.** A new fingerprint goes to the module's canary first, and to its other nodes once it runs healthy there, at most `step` of them ahead when `step` is above zero (rules 3 and 4). - **A credential and a composition before the want.** The module's credential and grant are written when its @@ -1930,18 +1932,23 @@ ADR 0667's checks, of milestone G itself: package and a module importing it builds the module against the package member's build by digest, publishes and reserves nothing, and no `tag-wanted` is said (whole, runner, builder and Go build module, mesh-delivery and mesh-catalog). -104. **A release records its dependencies, and each kind follows its event** (design 47 G §374, §376). A module - released at `1.4.3`, built against mesh-sdk `0.1.15` and delivered after a provider at `2.0.1`, holds those - versions with their artifacts' digests, the provider's per node; mesh-sdk's `version-released` of `0.1.16` that - changes the imported package rebuilds it, and one that leaves its digest as it was rebuilds nothing; the - provider's new build running on one node writes the module's want again on that node only, while another node - waits for its own; a `beta` build's entries compare by digest (whole, indexer, builder, assigner and runner, +104. **A release records its dependencies, and only a stale edge rebuilds** (design 47 G §374, §376, §378). A + module released at `1.4.3`, built against mesh-sdk `0.1.15` and delivered after a provider at `2.0.1`, holds + those versions with their parts' digests; mesh-sdk's `version-released` of `0.1.16` that changes the imported + package rebuilds it, one that leaves its digest as it was rebuilds nothing, and a change of the Go build module's + own code rebuilds no module; a `beta` build's entries compare by digest (whole, indexer, builder and runner, mesh-delivery). 105. **One query finds what is behind** (design 47 G §375). With the runner stopped while mesh-sdk `0.1.16` is released, `outdated` names the module's kind-1 edge at `0.1.15` against `0.1.16`, and at its restart the runner starts that module's pipeline once; `indexer_outdated_again` says the event again and writes the hand-act log (whole, indexer and runner, mesh-delivery). After the first fill (§377), a mesh running its newest builds is answered with nothing behind. +106. **A delivery is waited for mesh-wide** (design 47 G §376, §379, §380). A module ordered after a provider's + new version is wanted only once `version-delivered` says every present machine placing the provider runs it; with + one machine away the module's status reads "waiting for delivery of" the provider, naming the machine, and it + catches up when that machine is back; with every placing machine away the provider reads "waiting for + to be back" and nothing is raised; each want names the released version and its parts' digests; `indexer_edges` + answers the module's edges from both ends (whole, indexer, assigner and node-engine, mesh-delivery and `mesh-host`). ## What retires @@ -2037,7 +2044,7 @@ release reports the controller's code lines against research 063's baseline (acc | L6 | Provisioning leaves the controller (ADR 0570): every provision is one key of the seat `mesh-provisioner`, held by mesh-provisioner, holding a reference and never a value, and each placed module's provisioning plan a key of its state `plans`, both composed from placement, the wants and the manifests on change events; each provider acts once all a provision depends on is provided; the assigner moves a want only once its build's provisions are provided; a provision no want needs is retiring, and its account or credential is removed only on the operator's Approve, its data never; the vault mints each provision's secret sealed to the consumer's and the provider's node, and the consumer's node-engine writes it; a wait for a person is a provision's state, which the watchman reads; bus permissions stay with the grants part (ADR 0349, ADR 0230, ADR 0547 §11) | — | mesh-sdk, the node-engine (`mesh-host`), mesh-tools (the tool runner's provisioner client), mesh-catalog (mesh-provisioner, the vault, the provisioner client, postgres, keycloak, gitea, route-adapter), mesh-delivery (assigner, watchman) | 1954 | | L7 | History and records leave the controller (ADR 0571): the builder keeps its build log, one entry at a build's start and one at its end, from which build history and durations are read and the module mesh-catalog asks the builds it missed; the artifact sweep is the seat `mesh-artifact-sweep`, held by artifact-store-tools beside the artifact store, its keep set from the store's own listing, the wants and the build log, sweeping at each build's end from the lease write and recording each deletion in the hand-act log; disk readings are disk-load's own state on every node; who holds which seat is the state `seat-holders` of the seat `mesh-placement` (now `mesh-module-assigner`), and tools are found by the tool runners' announcements; what a node runs is its want and its have; the grants part writes `grants..` and keeps memberships in its own state; root-free is a probe of the self-check; no manifest but the controller's reads, invokes or consumes `mesh-controller`, but a named list kept to the lease write, so the lease write's check passes (ADR 0189, ADR 0547 §11, ADR 0549 §6) | — | mesh-sdk, mesh-controller (its pin only), mesh-delivery (builder, indexer, assigner, grants part, view), mesh-catalog (artifact-store-tools, disk-load, the backup seat's holder, mounts, nfs-server, minio, mesh-watcher, the messenger, the self-check, the module mesh-catalog, docker), mesh-tools (the tool runner) | 1955 | | B0 | The bootstrap delivery: every check, a lone pull request's as a group of one and a verdict carried after a trunk move included, is judged by a checking program built from the change's own heads in the build seat's sandbox, which also makes the heads' one seat list that the check hands the manifest validator and the composer; it brings no seat definition and no manifest field, so the running checker checks it (ADR 0644; *The bootstrap delivery, and the one milestone after it*) | 26 needs it | mesh-sdk (`go/delivery`: the seat `node-build-go`'s ask `run` and the checker's record of which checking program judged; `go/composer`: the request's seat list), mesh-catalog (mesh-build-go: the run step, the refused answer, the kept programs' tools and sweep), mesh-delivery (checker: the checking program and its command), hq (this design, the glossary) | 1921 | -| G | Two graphs and one revision view: the catalog graph and the assignment graph kept per revision, a change delivered as its graph difference, the acting parts' rules on their seats as bounded waits that hold their modules when the new version fails, the check on the change's own acting parts, the revision view and each process's own build, the gate's delivery record, and the trace's links (ADR 0656); no part reads a pull request's description (ADR 0659); every delivery part reaches the forge through the seat `git` and names no other module; nothing holds an approved merge for another check; and, one milestone with them, research 086's pipelines: a change of any module goes from a commit on a watched branch to the machines through its module's pipeline, its policy in its registration, ordered by edges between artifacts, with no Approve per merge and no hand act, the checker gone (ADR 0666, ADR 0667). Test counts at its start (G's prepare, 2026-11-09): mesh-delivery 665 unit and 68 integration, the node-engine (`mesh-host`) 1,742 unit; each other repository's and each catalog module's from the last check's verdict, read in the joint prepare | 26 to 62, 63 to 105 | mesh-sdk (the runtime: the fingerprint, the view, the definition reader, the seat list's one wiring), mesh-contracts and the domains' contracts modules (`acts`, the new verbs and events, the seat `mesh-grants`, the seat `git`'s verbs), mesh-delivery (indexer, assigner, checker until its removal, builder, grants part, gate's view, forge bridge, watchman, the new pipeline runner `mesh-delivery-pipeline`, `contracts` and `sdk` moved under `modules/`), mesh-catalog (the gate, the build modules, the forge module, mesh-issues, mesh-knowledge, the `node-backup` holder, the router, nats: a module's kept data on the bus as a backed-up item and the object store beside each state), mesh-sdk (also its small object store package, for values of any size), the node-engine (`mesh-host`), hq | 1966, 1961 (retargeted to this row's shape), 1660, 1972, 1721, 1783, 1785, 1794, 1791, 1373, 595; 1962 goes back with 1958, whose assignment entry it needs (ADR 0641 §3) | +| G | Two graphs and one revision view: the catalog graph and the assignment graph kept per revision, a change delivered as its graph difference, the acting parts' rules on their seats as bounded waits that hold their modules when the new version fails, the check on the change's own acting parts, the revision view and each process's own build, the gate's delivery record, and the trace's links (ADR 0656); no part reads a pull request's description (ADR 0659); every delivery part reaches the forge through the seat `git` and names no other module; nothing holds an approved merge for another check; and, one milestone with them, research 086's pipelines: a change of any module goes from a commit on a watched branch to the machines through its module's pipeline, its policy in its registration, ordered by edges between artifacts, with no Approve per merge and no hand act, the checker gone (ADR 0666, ADR 0667). Test counts at its start (G's prepare, 2026-11-09): mesh-delivery 665 unit and 68 integration, the node-engine (`mesh-host`) 1,742 unit; each other repository's and each catalog module's from the last check's verdict, read in the joint prepare | 26 to 62, 63 to 106 | mesh-sdk (the runtime: the fingerprint, the view, the definition reader, the seat list's one wiring), mesh-contracts and the domains' contracts modules (`acts`, the new verbs and events, the seat `mesh-grants`, the seat `git`'s verbs), mesh-delivery (indexer, assigner, checker until its removal, builder, grants part, gate's view, forge bridge, watchman, the new pipeline runner `mesh-delivery-pipeline`, `contracts` and `sdk` moved under `modules/`), mesh-catalog (the gate, the build modules, the forge module, mesh-issues, mesh-knowledge, the `node-backup` holder, the router, nats: a module's kept data on the bus as a backed-up item and the object store beside each state), mesh-sdk (also its small object store package, for values of any size), the node-engine (`mesh-host`), hq | 1966, 1961 (retargeted to this row's shape), 1660, 1972, 1721, 1783, 1785, 1794, 1791, 1373, 595; 1962 goes back with 1958, whose assignment entry it needs (ADR 0641 §3) | An issue is in one row only (ADR 0493 §2): where a row named an issue another row names too, the last row keeps it and the earlier row says so in words (the operator, 2026-10-26). Milestone M1 makes each row a record of the issue tracker diff --git a/03-DESIGN/01-to-be/47-milestones/G-5-acting-parts-check-and-kept-data.md b/03-DESIGN/01-to-be/47-milestones/G-5-acting-parts-check-and-kept-data.md index 5eab93ae..2c767215 100644 --- a/03-DESIGN/01-to-be/47-milestones/G-5-acting-parts-check-and-kept-data.md +++ b/03-DESIGN/01-to-be/47-milestones/G-5-acting-parts-check-and-kept-data.md @@ -73,7 +73,7 @@ names go, since every new acting part needed code changes elsewhere (research 08 Every other step's wait ends when the acting part's new version runs healthy, as the node-engine seat's `running` event says. - §268 **Composing waits per node, by the assigner.** A node's wants wait only for that node's own node-engine, never for - another node's, so a node away holds only itself (ADR 0603 §7). The want gains no field: the assigner, which writes + another node's, so a node away holds only itself (ADR 0603 §7). The want gains no field for it: the assigner, which writes the wants, holds a node's other wants until the node-engine seat's `running..` says the new node-engine version runs on that node, and writes that node-engine's own want first. A node-engine of before milestone G thus gets its own want first and every other want once it runs the new one, so an old node-engine never composes a module it 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 new file mode 100644 index 00000000..fc13b0f3 --- /dev/null +++ b/03-DESIGN/01-to-be/47-milestones/G-6-verbs-and-retires.md @@ -0,0 +1,204 @@ +--- +layer: to-be +status: in-progress +design: 47 +milestone: G +updated: 2026-11-10 +decisions: + - "ADR 0667" + - "ADR 0666" + - "ADR 0660" + - "ADR 0659" + - "ADR 0656" + - "ADR 0625" + - "ADR 0614" + - "ADR 0603" + - "ADR 0596" + - "ADR 0551" + - "ADR 0548" + - "ADR 0534" + - "ADR 0493" + - "ADR 0443" + - "ADR 0441" + - "ADR 0398" +--- + +# 47, milestone G: the verbs G adds and what retires + +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". + +## The verbs milestone G adds + +§304 From research 085's milestone the seat gains: + +| Verb or event | Answers or does | +|---|---| +| `groups` with a group | that group's members, which the forge bridge reads in place of the gate's `merges` state (ADR 0656), and the acts the gate said it owes the forge for it, each with its id and its recorded outcome (*What the gate owes the forge*) | +| `owed` | an act the gate owes the forge (a merge, a status, the delivery's view, a comment, a line on the commit's note), with its pull request, head and id, on `mesh.seat.mesh-delivery.event.owed..`, said only from the gate's account and heard by the forge bridge through a durable consumer (*What the gate owes the forge*) | +| `milestone-asked`, `milestone-withdrawn`, `milestone-answered` | until G's delivery: the one Approve ask per milestone (ADR 0493 §9 as ADR 0659 §1 changes it, issue 1783), held until it is answered, or withdrawn by a new head and asked again (ADR 0441 §1); said on `mesh.seat.mesh-delivery.event.`, the milestone in the event, apart from each delivery's `transition`, which stays as it is, so a waiter on one member's pull request wakes only on that member's `transition`. G's delivery ends the ask and its three events with the Approve per merge (ADR 0666 §10) | +| `record-opened` | a delivery record opened, which the watchman times for `record-open` | +| `pinned`, `freed`, `heads-replaced` | the events by which the indexer and the assigner keep or drop graph revisions, said only from the gate's account (*The delivery record*) | +| `record-ended`, `filling`, `full`, `room` | a delivery record ended; the ledger past 80 % of its cap; the ledger full; the ledger back below its cap (*The delivery record*) | + +§305 From milestone G's delivery the seat's `table`, `recheck` and `close` go with the merge states (*The state table*), +the milestone ask and its three events with the Approve per merge, and it gains (ADR 0666 §6, §26): + +| Verb or event | Answers or does | +|---|---| +| `source` with a watched branch | that branch's source revision; the indexer and the node-engine's catch-up read it, never the gate's state | +| `source-moved` | a new source revision of a watched branch | +| `recovery` | marks a merge its author names a recovery (the commit and why), its record marked `recovery` with the caller the runtime proves | +| `record-opened`, `recovery-merged` | a delivery record opened; a merge named a recovery, which the teller passes on to every channel | + +§306 **The seat `mesh-pipeline-runner`**, from milestone G's delivery, defined in `mesh-delivery-contracts` with the callers +of each verb (ADR 0666 §7, §20, §25): + +| Verb | Answers or does | Callers | +|---|---|---| +| `run` | the run on request of one or more members, each a module at a named commit; delivers nothing | the sessions (the agents' bus identities the tool runner proves) and the operator, nothing else | +| `start` | a delivering pipeline for a watched branch's head, by hand | the operator, the healers | +| `show`, `list`, `stands`, `why-carried`, `kept` | one pipeline whole with its step log; the pipelines and runs of a module, a branch or a commit; what stands still; where a result was carried from; the kept results | any person, an agent session, the healers | +| `review` | a code review's result for a commit and fingerprint | the reviewers the definition names; refused from the commit's author | +| `rerun`, `accept`, `cancel`, `ask-again` | one step again; a failed `optional` step accepted with why; a pipeline ended, its asks dropped; a declined `approval` asked again | the operator, the healers (`accept` and `ask-again` the operator) | + +§307 **The seat `mesh-catalog`** gains, from milestone G's delivery, `register`, `policy`, `watch`, `unwatch` and +`registrations`, and the event `registration-changed` (*A module's registration*), and `catalog-revision` names its +watched branch in its subject. **The build seats** gain the verb +`steps` and the accepted kind `step`, and **the seat `mesh-wants`** the kind `step`, each saying `step-ended`. **The +seat `mesh-builds`**, new and held once for the mesh, says `package-published` (*A publish rebuilds*). + +§308 **The seats `mesh-catalog` and `mesh-wants`** gain, from research 085's milestone, `revision` on each (the two halves +of the revision view, ADR 0656), and `entry` and `difference` on `mesh-wants` (ADR 0656), with the events of *What +each step says*. + +§309 **The seat `node-engine`**'s event `running..` carries, from research 085's milestone, the module, its +fingerprint and the digest of its build's manifest, so the node-engine of another node and the grants part decide a +seat's pass from it (ADR 0660 §2; *Who holds a seat is applied by one rule*). No verb is added. + +§310 **The seat `git`.** The seat `git` (design 26, *The git seat*), of the Delivery domain, defined in +`mesh-delivery-contracts`, holds no verb today, and the delivery parts and the gate reach the forge by naming the forge +module's own tools and events and guessing the shape of their answers (on 2026-11-09 one guess, an answer wrapped in a +`result` field, made 316 conditions stand, issue 1966). From research 085's milestone the seat's definition carries the +verbs and events below, their inputs and answers typed in its contract, served and said by the module that claims the +seat; every delivery part and the gate call and hear the seat, never the forge module by name (acceptance test 27). +They are this design's choice under ADR 0596 §1, §2 (a module's events are subscribed to and its data asked through +its seat verbs) and ADR 0625 §1 (a seat's contract is generated from its definition). The table is built from what the +parts' manifests declare in `invokes` and `consumes` and what their code calls, read on main on 2026-11-09 (mesh-delivery +042b8d1f, mesh-catalog's gate); a declaration nothing calls (the checker's `gitea_commits`, `gitea_compare`, +`gitea_list_branches`) gets no verb and is dropped from its manifest: + +| Verb | Answers or does | Called by (today's call) | +|---|---|---| +| `pull` | one pull request, by its repository and number or by its merge commit: number, base, head branch, head, merge commit, author, state, and `merging` while the forge merges it; an unknown one answers the error kind `not-found` | the forge bridge (a merge the gate did not make; `gitea_api`), the gate (a stalled line's author) | +| `branch` | from milestone G's delivery: a branch's head, and whether a protection rule refuses a direct push and admits only merges | the indexer (`register`, `watch`), the forge bridge (a watched branch's head) | +| `open-pulls` | every open pull request of every repository, its head and base, the statuses its base requires and those its head has | the forge bridge at its start and each reconnect (ADR 0443 §5), the indexer, the gate (`gitea_open_pulls`) | +| `tags` | a repository's tags, paged, the page's bound said when more exist | the forge bridge, for the builder's floor (`gitea_api`) | +| `trees` | the trees of one commit | the forge bridge, the checker, the indexer (`gitea_commit_trees`) | +| `file` | one file at one commit | the forge bridge, the checker, the indexer (`gitea_get_file`) | +| `contains` | whether one commit contains another | the indexer, the gate (`gitea_contains`) | +| `statuses` | the statuses a commit carries | the gate (`gitea_commit_statuses`) | +| `status`, `comment`, `view`, `note` | a commit status, a comment, the delivery's one view comment, a line on the commit's note under `refs/notes/mesh-plan`; a comment and a note line carry the act's id and an id already held is skipped | the forge bridge alone, performing the gate's and the checker's `owed` (`gitea_commit_status`, `gitea_add_comment`, `gitea_delivery_view`, `gitea_note_append`) | +| `merge-pull` | until G's delivery: merges a pull request at the head the operator's Approve names; refuses a head that moved, a branch no rule guards, a head the Approve does not name and a merge git refuses; judges no check (below). From G's delivery: merges with the forge tools' account (ADR 0398 §2) at the head the caller names, judging that it is still the pull request's head and that the branch's protection refuses a direct push, the protection read again on every `branch-moved`, and refusing a head when any run at its build-input fingerprint failed a `required` step, judged from its own state `failed-steps` heard from the runner's `step-ended`, never by a call; a head with no run yet or a passed one merges, it never waits for a run and never asks an Approve (ADR 0666 §11). A pull request already merged at that head is answered performed | until G's delivery the forge bridge alone (`gitea_merge_pull_request`); from it any session the tool runner proves, and the operator | + +| 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`) | +| `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 +`consumes` of the seat. + +- §312 **A failed read answers an error, never an empty answer.** When the forge does not answer, refuses or answers what + the contract cannot type, the verb answers an error naming why; an empty list or an absent file is answered only + when the forge said so. A caller never reads an error as "none". How it is checked: the seat's fixtures hold an + error answer for each verb, and each caller's unit table has a row for it (the forge bridge, the checker, the + indexer, the gate). +- §313 **Who may call an act.** The holder's trusted config value `callers`, which today names per verb who may call the + two package seats' verbs (design 51), gains a line per verb of the seat `git`: the act verbs name the forge bridge + alone, the reads name each part that declares them in `invokes`; the grants part grants by it, and the holder + refuses a caller it does not name. From G's delivery the callers per verb are the seat definition's field `callers`, + the grants part's one source (ADR 0666 §20): `status`, `comment`, `view` and `note` the forge bridge alone, + `merge-pull` the persons and agent sessions the tool runner proves, the reads the parts that declare them. The forge module's own acting tools (`gitea_merge_pull_request`, + `gitea_commit_status`, `gitea_delivery_view`, `gitea_note_append`, `gitea_add_comment`) retire with the milestone, + and so do its watch of the checker's state `owed` and its read of the gate's `source`, so the bridge stays the one + part that acts on the forge. How it is checked: test 51 reads the grants, not the code. +- §314 **`merge-pull` judges no check, and from G's delivery no Approve, only the runs at the head's fingerprint.** The operator's answer that no check gates delivery (Telegram, 2026-11-09 01:11 UTC, + "Remove them in G") covers the forge module's own setting `check-gates-merge` as well as the gate's: both are + removed, and `merge-pull` merges an approved head whatever its `mesh/check` says. The record that ends ADR 0551 and + ADR 0548 §2 to §4, §9 and §10 also changes ADR 0534 §4's judgement of `mesh/check` by the merge; it is to be accepted + before the push (*Nothing merges into a repository under check*). From G's delivery it judges no Approve either, its caller + is any session the tool runner proves, and it refuses a head when any run at its fingerprint failed a `required` step, + never waiting for one (ADR 0666 §11; *Approval is a step, and a session merges a pull request*). The reads the + gate would have needed to merge (the forge's word for a conflict, the base's required statuses, the merging account's + write access) are not added: no part of the mesh but `merge-pull` merges, and it answers git's own refusal of a merge + as refused. +- §315 **The order is the module graph's, and each step has its way back.** The verbs are a served-verb edge (ADR 0614): + the forge module's new build runs before the forge bridge's, and the forge bridge's before the gate's, since the + bridge calls the verbs and performs the gate's `owed`, and the gate says `owed` only to a bridge that hears it; all + three are ahead of the acting parts' steps, which read through the seat. While the new forge runs and the old bridge + still calls the retired acting tools, the old bridge's acts fail loudly and stay unperformed in the old gate's keys, + and the switch carries them (*What the gate owes the forge*). A revert goes back in the other order: the gate, then + the bridge, then the forge, each wanted only once the one after it in the forward order runs its reverted build, so + no part calls a verb nobody serves. ADR 0656 §3 stands beside it: the acting parts' new versions act first in their + own steps. Two things cover the gap while the forge is still on its old build and serves no verb of the seat: the + indexer starts on its kept definitions (below), and a check whose read through the seat `git` fails says `could not + run`, naming the forge, and is asked again on the forge module's `running` (*A check runs to its end*). +- §316 **A part that cannot read the forge keeps what it has, and says so.** The indexer, at its start, waits for the + seat `git` at most 2 minutes; with no answer it judges from the last definitions it kept, says in its + `_first_views` that it waits for `git` and since when, writes `view-waits` after five minutes, and reads the + definitions once the seat answers; it then judges again every manifest it judged from kept definitions. Two minutes is longer than a forge's restart, and short enough that a start is + not held behind a forge down for good. How it is checked: test 54. +- §317 **How it is checked.** The seat definition's conformance fixtures hold one answer and one error of each verb and one + of each event, and the forge module's tool tests answer each fixture; the forge bridge's, the checker's, the + indexer's and the gate's unit fakes answer from the same fixtures; a call of an act verb from an account other than + the forge bridge's is refused (test 51); live, a search of the delivery parts' and the gate's code finds no name of + the forge module's tools or events. + +§318 **Links of the trace.** No part reads a review line (ADR 0659 §1 to §3); who may review and the review verb's grant +stay issue 1782's, outside milestone G, and that verb gates nothing (ADR 0659 §2). The trace's links are this +design's choices under ADR 0656, so that one call traces research to the running build +with no text match (research 085, Findings 7). The issue tracker gains link kinds from an issue to the decision and to the research effort +it carries, made by a tool call and never by text, as ADR 0493 §4 has every link made; the knowledge base gains a +typed link from a decision to the milestone of the issue tracker that builds it, made by a tool call, which joins the +link kinds of its link-fits rule (design 55), beside the `became` link a research effort gets at its graduation +(playbook 02). How it is checked: whole (gate), one ask per milestone, withdrawn by a new head; +a waiter on one member's pull request wakes only on that member's transition. Whole (issue tracker, knowledge base): +an issue linked to a decision and to a research effort reads both back; a decision linked to its milestone reads it +back. Live: research 085's milestone's record reads back research 085 to its decisions, its milestone, its issues and +its pull requests with no text match. + +§319 **A session hears that a record was accepted** (issue 595). The knowledge base already says, on its holder's own +stream, the event `reviewed` for every judgement of a record; from milestone G that event carries, when the operator's +Approve accepts a record, that it was accepted and by the operator, with the warrant, and the tool runner's account is +granted to hear it, so a session waiting on a record wakes on it. The design's choice under ADR 0596 §1 (a module's +events are subscribed to): a new event of the seat `knowledge-base` would be a second path for the same fact (lead-47, +2026-11-09). How it is checked: in the knowledge base's whole-module test an Approve that accepts a record says +`reviewed` with what was accepted and by whom, and the tool runner's account hears it. + +## What retires at milestone G + +- §320 At research 085's milestone's delivery: the indexer's map from language to build module, and the checker's own + module names and its cases for a change to the manifest validator and to the Go build module (ADR 0656); a build + module's edge as a trigger, with the extra build per recipe change (ADR 0603 §3, as ADR 0656 changes it); composing + from manifests a module whose changed build module the check cannot run (ADR 0603 §10 and ADR 0614 §7, as ADR 0656 + changes them); the module graph's one key per module with five past values as what parts read (ADR 0603 §2, as + ADR 0656 changes it); the tiers worked out from five live sources (ADR 0603 §6, as ADR 0656 changes it); a seat + list compiled into a part, and every read of another module's bus state the revision view replaces (ADR 0656); the + gate's `merges`, carried into the delivery records and written no more, and its `owed`, said as events; the hold, + the merge turns, their stalled line and tools and the setting `check-gates-merge`, once their record is accepted; + the last three reads of a pull request's description (ADR 0659 §4); every delivery part's call of the forge module's + own tools, for the seat `git`'s verbs; and the four seat-list readers the delivery parts wire by hand. +- §321 At milestone G's delivery, from research 086 (ADR 0666, ADR 0667): the tagged versions, `tag-wanted` and + `tag-asks` (§373); the checker (`mesh-delivery-checker`), its seat, + its try with `tryevent` and the indexer's try candidates, its kept verdicts and carries (the runner's from then), the + checking program and `mesh/check`, and its buckets and bus account, removed with the gate's forge merge token only + after the first pipeline after G's delivery has delivered a change end to end and on the operator's one word, its + buckets through `drop` after a snapshot whose restore is tested (ADR 0667 §12); the bundle of steps run before a merge; the Approve per + merge, the milestone ask and its three events, and the gate's merges; the gate's merge states, one key per pull request and its verbs `table`, `recheck` and + `close`; the trunk-only want; `source.main`, for one source revision per watched branch; every fixed branch, + repository and module name in code logic; the recovery merge verb this design sketched, never built; and the holders' + trusted `callers` values, for the seat definitions' `callers`. The words **merge check**, **try**, **trunk commit** + and **merge turn** go to *Not:* lines with the as-is update after that delivery, as the glossary's entries say. diff --git a/03-DESIGN/01-to-be/47-milestones/G-6-verbs-retires-and-answers.md b/03-DESIGN/01-to-be/47-milestones/G-7-answers.md similarity index 56% rename from 03-DESIGN/01-to-be/47-milestones/G-6-verbs-retires-and-answers.md rename to 03-DESIGN/01-to-be/47-milestones/G-7-answers.md index 5a500219..23705ae9 100644 --- a/03-DESIGN/01-to-be/47-milestones/G-6-verbs-retires-and-answers.md +++ b/03-DESIGN/01-to-be/47-milestones/G-7-answers.md @@ -8,208 +8,26 @@ decisions: - "ADR 0668" - "ADR 0667" - "ADR 0666" - - "ADR 0660" - - "ADR 0659" - "ADR 0656" - "ADR 0635" - "ADR 0625" - "ADR 0619" - - "ADR 0614" - "ADR 0603" - "ADR 0596" - "ADR 0595" + - "ADR 0584" + - "ADR 0573" - "ADR 0564" - "ADR 0563" - - "ADR 0551" - "ADR 0548" - - "ADR 0534" - - "ADR 0493" - - "ADR 0443" - - "ADR 0441" - - "ADR 0398" - "ADR 0363" --- -# 47, milestone G: the verbs G adds, what retires, and the answers to the builders' and the reviewers' questions +# 47, milestone G: the answers to the builders', the reviewers' and the operator's questions 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". -## The verbs milestone G adds - -§304 From research 085's milestone the seat gains: - -| Verb or event | Answers or does | -|---|---| -| `groups` with a group | that group's members, which the forge bridge reads in place of the gate's `merges` state (ADR 0656), and the acts the gate said it owes the forge for it, each with its id and its recorded outcome (*What the gate owes the forge*) | -| `owed` | an act the gate owes the forge (a merge, a status, the delivery's view, a comment, a line on the commit's note), with its pull request, head and id, on `mesh.seat.mesh-delivery.event.owed..`, said only from the gate's account and heard by the forge bridge through a durable consumer (*What the gate owes the forge*) | -| `milestone-asked`, `milestone-withdrawn`, `milestone-answered` | until G's delivery: the one Approve ask per milestone (ADR 0493 §9 as ADR 0659 §1 changes it, issue 1783), held until it is answered, or withdrawn by a new head and asked again (ADR 0441 §1); said on `mesh.seat.mesh-delivery.event.`, the milestone in the event, apart from each delivery's `transition`, which stays as it is, so a waiter on one member's pull request wakes only on that member's `transition`. G's delivery ends the ask and its three events with the Approve per merge (ADR 0666 §10) | -| `record-opened` | a delivery record opened, which the watchman times for `record-open` | -| `pinned`, `freed`, `heads-replaced` | the events by which the indexer and the assigner keep or drop graph revisions, said only from the gate's account (*The delivery record*) | -| `record-ended`, `filling`, `full`, `room` | a delivery record ended; the ledger past 80 % of its cap; the ledger full; the ledger back below its cap (*The delivery record*) | - -§305 From milestone G's delivery the seat's `table`, `recheck` and `close` go with the merge states (*The state table*), -the milestone ask and its three events with the Approve per merge, and it gains (ADR 0666 §6, §26): - -| Verb or event | Answers or does | -|---|---| -| `source` with a watched branch | that branch's source revision; the indexer and the node-engine's catch-up read it, never the gate's state | -| `source-moved` | a new source revision of a watched branch | -| `recovery` | marks a merge its author names a recovery (the commit and why), its record marked `recovery` with the caller the runtime proves | -| `record-opened`, `recovery-merged` | a delivery record opened; a merge named a recovery, which the teller passes on to every channel | - -§306 **The seat `mesh-pipeline-runner`**, from milestone G's delivery, defined in `mesh-delivery-contracts` with the callers -of each verb (ADR 0666 §7, §20, §25): - -| Verb | Answers or does | Callers | -|---|---|---| -| `run` | the run on request of one or more members, each a module at a named commit; delivers nothing | the sessions (the agents' bus identities the tool runner proves) and the operator, nothing else | -| `start` | a delivering pipeline for a watched branch's head, by hand | the operator, the healers | -| `show`, `list`, `stands`, `why-carried`, `kept` | one pipeline whole with its step log; the pipelines and runs of a module, a branch or a commit; what stands still; where a result was carried from; the kept results | any person, an agent session, the healers | -| `review` | a code review's result for a commit and fingerprint | the reviewers the definition names; refused from the commit's author | -| `rerun`, `accept`, `cancel`, `ask-again` | one step again; a failed `optional` step accepted with why; a pipeline ended, its asks dropped; a declined `approval` asked again | the operator, the healers (`accept` and `ask-again` the operator) | - -§307 **The seat `mesh-catalog`** gains, from milestone G's delivery, `register`, `policy`, `watch`, `unwatch` and -`registrations`, and the event `registration-changed` (*A module's registration*), and `catalog-revision` names its -watched branch in its subject. **The build seats** gain the verb -`steps` and the accepted kind `step`, and **the seat `mesh-wants`** the kind `step`, each saying `step-ended`. **The -seat `mesh-builds`**, new and held once for the mesh, says `package-published` (*A publish rebuilds*). - -§308 **The seats `mesh-catalog` and `mesh-wants`** gain, from research 085's milestone, `revision` on each (the two halves -of the revision view, ADR 0656), and `entry` and `difference` on `mesh-wants` (ADR 0656), with the events of *What -each step says*. - -§309 **The seat `node-engine`**'s event `running..` carries, from research 085's milestone, the module, its -fingerprint and the digest of its build's manifest, so the node-engine of another node and the grants part decide a -seat's pass from it (ADR 0660 §2; *Who holds a seat is applied by one rule*). No verb is added. - -§310 **The seat `git`.** The seat `git` (design 26, *The git seat*), of the Delivery domain, defined in -`mesh-delivery-contracts`, holds no verb today, and the delivery parts and the gate reach the forge by naming the forge -module's own tools and events and guessing the shape of their answers (on 2026-11-09 one guess, an answer wrapped in a -`result` field, made 316 conditions stand, issue 1966). From research 085's milestone the seat's definition carries the -verbs and events below, their inputs and answers typed in its contract, served and said by the module that claims the -seat; every delivery part and the gate call and hear the seat, never the forge module by name (acceptance test 27). -They are this design's choice under ADR 0596 §1, §2 (a module's events are subscribed to and its data asked through -its seat verbs) and ADR 0625 §1 (a seat's contract is generated from its definition). The table is built from what the -parts' manifests declare in `invokes` and `consumes` and what their code calls, read on main on 2026-11-09 (mesh-delivery -042b8d1f, mesh-catalog's gate); a declaration nothing calls (the checker's `gitea_commits`, `gitea_compare`, -`gitea_list_branches`) gets no verb and is dropped from its manifest: - -| Verb | Answers or does | Called by (today's call) | -|---|---|---| -| `pull` | one pull request, by its repository and number or by its merge commit: number, base, head branch, head, merge commit, author, state, and `merging` while the forge merges it; an unknown one answers the error kind `not-found` | the forge bridge (a merge the gate did not make; `gitea_api`), the gate (a stalled line's author) | -| `branch` | from milestone G's delivery: a branch's head, and whether a protection rule refuses a direct push and admits only merges | the indexer (`register`, `watch`), the forge bridge (a watched branch's head) | -| `open-pulls` | every open pull request of every repository, its head and base, the statuses its base requires and those its head has | the forge bridge at its start and each reconnect (ADR 0443 §5), the indexer, the gate (`gitea_open_pulls`) | -| `tags` | a repository's tags, paged, the page's bound said when more exist | the forge bridge, for the builder's floor (`gitea_api`) | -| `trees` | the trees of one commit | the forge bridge, the checker, the indexer (`gitea_commit_trees`) | -| `file` | one file at one commit | the forge bridge, the checker, the indexer (`gitea_get_file`) | -| `contains` | whether one commit contains another | the indexer, the gate (`gitea_contains`) | -| `statuses` | the statuses a commit carries | the gate (`gitea_commit_statuses`) | -| `status`, `comment`, `view`, `note` | a commit status, a comment, the delivery's one view comment, a line on the commit's note under `refs/notes/mesh-plan`; a comment and a note line carry the act's id and an id already held is skipped | the forge bridge alone, performing the gate's and the checker's `owed` (`gitea_commit_status`, `gitea_add_comment`, `gitea_delivery_view`, `gitea_note_append`) | -| `merge-pull` | until G's delivery: merges a pull request at the head the operator's Approve names; refuses a head that moved, a branch no rule guards, a head the Approve does not name and a merge git refuses; judges no check (below). From G's delivery: merges with the forge tools' account (ADR 0398 §2) at the head the caller names, judging that it is still the pull request's head and that the branch's protection refuses a direct push, the protection read again on every `branch-moved`, and refusing a head when any run at its build-input fingerprint failed a `required` step, judged from its own state `failed-steps` heard from the runner's `step-ended`, never by a call; a head with no run yet or a passed one merges, it never waits for a run and never asks an Approve (ADR 0666 §11). A pull request already merged at that head is answered performed | until G's delivery the forge bridge alone (`gitea_merge_pull_request`); from it any session the tool runner proves, and the operator | - -| 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`) | -| `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 -`consumes` of the seat. - -- §312 **A failed read answers an error, never an empty answer.** When the forge does not answer, refuses or answers what - the contract cannot type, the verb answers an error naming why; an empty list or an absent file is answered only - when the forge said so. A caller never reads an error as "none". How it is checked: the seat's fixtures hold an - error answer for each verb, and each caller's unit table has a row for it (the forge bridge, the checker, the - indexer, the gate). -- §313 **Who may call an act.** The holder's trusted config value `callers`, which today names per verb who may call the - two package seats' verbs (design 51), gains a line per verb of the seat `git`: the act verbs name the forge bridge - alone, the reads name each part that declares them in `invokes`; the grants part grants by it, and the holder - refuses a caller it does not name. From G's delivery the callers per verb are the seat definition's field `callers`, - the grants part's one source (ADR 0666 §20): `status`, `comment`, `view` and `note` the forge bridge alone, - `merge-pull` the persons and agent sessions the tool runner proves, the reads the parts that declare them. The forge module's own acting tools (`gitea_merge_pull_request`, - `gitea_commit_status`, `gitea_delivery_view`, `gitea_note_append`, `gitea_add_comment`) retire with the milestone, - and so do its watch of the checker's state `owed` and its read of the gate's `source`, so the bridge stays the one - part that acts on the forge. How it is checked: test 51 reads the grants, not the code. -- §314 **`merge-pull` judges no check, and from G's delivery no Approve, only the runs at the head's fingerprint.** The operator's answer that no check gates delivery (Telegram, 2026-11-09 01:11 UTC, - "Remove them in G") covers the forge module's own setting `check-gates-merge` as well as the gate's: both are - removed, and `merge-pull` merges an approved head whatever its `mesh/check` says. The record that ends ADR 0551 and - ADR 0548 §2 to §4, §9 and §10 also changes ADR 0534 §4's judgement of `mesh/check` by the merge; it is to be accepted - before the push (*Nothing merges into a repository under check*). From G's delivery it judges no Approve either, its caller - is any session the tool runner proves, and it refuses a head when any run at its fingerprint failed a `required` step, - never waiting for one (ADR 0666 §11; *Approval is a step, and a session merges a pull request*). The reads the - gate would have needed to merge (the forge's word for a conflict, the base's required statuses, the merging account's - write access) are not added: no part of the mesh but `merge-pull` merges, and it answers git's own refusal of a merge - as refused. -- §315 **The order is the module graph's, and each step has its way back.** The verbs are a served-verb edge (ADR 0614): - the forge module's new build runs before the forge bridge's, and the forge bridge's before the gate's, since the - bridge calls the verbs and performs the gate's `owed`, and the gate says `owed` only to a bridge that hears it; all - three are ahead of the acting parts' steps, which read through the seat. While the new forge runs and the old bridge - still calls the retired acting tools, the old bridge's acts fail loudly and stay unperformed in the old gate's keys, - and the switch carries them (*What the gate owes the forge*). A revert goes back in the other order: the gate, then - the bridge, then the forge, each wanted only once the one after it in the forward order runs its reverted build, so - no part calls a verb nobody serves. ADR 0656 §3 stands beside it: the acting parts' new versions act first in their - own steps. Two things cover the gap while the forge is still on its old build and serves no verb of the seat: the - indexer starts on its kept definitions (below), and a check whose read through the seat `git` fails says `could not - run`, naming the forge, and is asked again on the forge module's `running` (*A check runs to its end*). -- §316 **A part that cannot read the forge keeps what it has, and says so.** The indexer, at its start, waits for the - seat `git` at most 2 minutes; with no answer it judges from the last definitions it kept, says in its - `_first_views` that it waits for `git` and since when, writes `view-waits` after five minutes, and reads the - definitions once the seat answers; it then judges again every manifest it judged from kept definitions. Two minutes is longer than a forge's restart, and short enough that a start is - not held behind a forge down for good. How it is checked: test 54. -- §317 **How it is checked.** The seat definition's conformance fixtures hold one answer and one error of each verb and one - of each event, and the forge module's tool tests answer each fixture; the forge bridge's, the checker's, the - indexer's and the gate's unit fakes answer from the same fixtures; a call of an act verb from an account other than - the forge bridge's is refused (test 51); live, a search of the delivery parts' and the gate's code finds no name of - the forge module's tools or events. - -§318 **Links of the trace.** No part reads a review line (ADR 0659 §1 to §3); who may review and the review verb's grant -stay issue 1782's, outside milestone G, and that verb gates nothing (ADR 0659 §2). The trace's links are this -design's choices under ADR 0656, so that one call traces research to the running build -with no text match (research 085, Findings 7). The issue tracker gains link kinds from an issue to the decision and to the research effort -it carries, made by a tool call and never by text, as ADR 0493 §4 has every link made; the knowledge base gains a -typed link from a decision to the milestone of the issue tracker that builds it, made by a tool call, which joins the -link kinds of its link-fits rule (design 55), beside the `became` link a research effort gets at its graduation -(playbook 02). How it is checked: whole (gate), one ask per milestone, withdrawn by a new head; -a waiter on one member's pull request wakes only on that member's transition. Whole (issue tracker, knowledge base): -an issue linked to a decision and to a research effort reads both back; a decision linked to its milestone reads it -back. Live: research 085's milestone's record reads back research 085 to its decisions, its milestone, its issues and -its pull requests with no text match. - -§319 **A session hears that a record was accepted** (issue 595). The knowledge base already says, on its holder's own -stream, the event `reviewed` for every judgement of a record; from milestone G that event carries, when the operator's -Approve accepts a record, that it was accepted and by the operator, with the warrant, and the tool runner's account is -granted to hear it, so a session waiting on a record wakes on it. The design's choice under ADR 0596 §1 (a module's -events are subscribed to): a new event of the seat `knowledge-base` would be a second path for the same fact (lead-47, -2026-11-09). How it is checked: in the knowledge base's whole-module test an Approve that accepts a record says -`reviewed` with what was accepted and by whom, and the tool runner's account hears it. - -## What retires at milestone G - -- §320 At research 085's milestone's delivery: the indexer's map from language to build module, and the checker's own - module names and its cases for a change to the manifest validator and to the Go build module (ADR 0656); a build - module's edge as a trigger, with the extra build per recipe change (ADR 0603 §3, as ADR 0656 changes it); composing - from manifests a module whose changed build module the check cannot run (ADR 0603 §10 and ADR 0614 §7, as ADR 0656 - changes them); the module graph's one key per module with five past values as what parts read (ADR 0603 §2, as - ADR 0656 changes it); the tiers worked out from five live sources (ADR 0603 §6, as ADR 0656 changes it); a seat - list compiled into a part, and every read of another module's bus state the revision view replaces (ADR 0656); the - gate's `merges`, carried into the delivery records and written no more, and its `owed`, said as events; the hold, - the merge turns, their stalled line and tools and the setting `check-gates-merge`, once their record is accepted; - the last three reads of a pull request's description (ADR 0659 §4); every delivery part's call of the forge module's - own tools, for the seat `git`'s verbs; and the four seat-list readers the delivery parts wire by hand. -- §321 At milestone G's delivery, from research 086 (ADR 0666, ADR 0667): the tagged versions, `tag-wanted` and - `tag-asks` (§373); the checker (`mesh-delivery-checker`), its seat, - its try with `tryevent` and the indexer's try candidates, its kept verdicts and carries (the runner's from then), the - checking program and `mesh/check`, and its buckets and bus account, removed with the gate's forge merge token only - after the first pipeline after G's delivery has delivered a change end to end and on the operator's one word, its - buckets through `drop` after a snapshot whose restore is tested (ADR 0667 §12); the bundle of steps run before a merge; the Approve per - merge, the milestone ask and its three events, and the gate's merges; the gate's merge states, one key per pull request and its verbs `table`, `recheck` and - `close`; the trunk-only want; `source.main`, for one source revision per watched branch; every fixed branch, - repository and module name in code logic; the recovery merge verb this design sketched, never built; and the holders' - trusted `callers` values, for the seat definitions' `callers`. The words **merge check**, **try**, **trunk commit** - and **merge turn** go to *Not:* lines with the as-is update after that delivery, as the glossary's entries say. - ## What milestone G's builders found open, answered by this design (2026-11-10) *ADR 0666, ADR 0667, ADR 0668; ADR 0656, ADR 0596, ADR 0595 §4, §9, ADR 0619 §1, §2, ADR 0563, ADR 0564 §2, ADR 0625 @@ -406,7 +224,7 @@ record it follows from, and replaces the builder's own choice where one was made - §351 **One rule for asking again.** mesh-sdk's kept-call form (ADR 0668 §7) asks an ask again only while it is open and not replaced, and every asker and every hand ask-again tool uses it. How it is checked: unit (mesh-sdk), a replaced ask is not asked again. -- §352 **The assigner's newer-revision check reads its own state.** The want gains no field (*Composing waits per +- §352 **The assigner's newer-revision check reads its own state.** The check adds no field to the want (*Composing waits per node*): the assigner keeps in its old `state` section `written` one key per module and watched branch, the source revision and end count it last wrote that module's wants from, compares a new `pipeline-ended` with it by compare-and-set, and deletes the key when `registration-changed` says the branch is no longer watched; its tool @@ -523,63 +341,80 @@ record it follows from, and replaces the builder's own choice where one was made and `builder_untag` go at G's delivery (design 51, *Tagged versions*). Why: the operator, 2026-11-10 about 21:40 CET, no custom versions for now, a tagged version being one; a run delivers nothing (ADR 0666 §18), so it needs no version. How it is checked: test 103. -- §374 **A release records, per edge, the part it was built against or delivered after.** The catalog records on - each released version (§349), in its key of `versions`, one entry per catalog-graph edge of the module's artifacts - (the six kinds of *Dependencies between artifacts*), a lockfile per released version. An entry names the kind, the - dependency's artifact reference and what the edge depended on: - - kinds 1 and 3 (built against): the dependency's version and the digest of that artifact, as the build used them. - The build module names each dependency it resolved, version and digest, in its step key, and the builder carries - them in each artifact's `package-published`, so the indexer reads no other part's state (ADR 0596). A build is on - one build node, so these entries are per release. - - kinds 2 and 4 (delivered after): per node, the dependency's version and artifact digest running on that node - when the released version first runs there, heard from the node-engine seat's `running` events through a durable - consumer of the indexer's own, the fingerprint mapped to its version and digest in `versions`. +- §374 **A release records, per edge, the part it was built against or delivered after.** One version per module + stays (§52), and an edge is judged by the digest of the part it points to. The catalog records on each released + version (§349), in its key of `versions`, one entry per catalog-graph edge of the module's artifacts (the six kinds + of *Dependencies between artifacts*), a lockfile per released version. An entry names the kind, whether the edge + makes the dependent stale or only orders it (§378), the manifest word it came from, the part it points to, and what + the edge depended on: + - kind 1 (an imported package) and kind 3 (the build toolchain): the dependency's version and the digest of the part, + as the build used them. The build module names each dependency it resolved, version and digest, in its step key, + and the builder carries them in each artifact's `package-published`, so the indexer reads no other part's state + (ADR 0596). Kind 3 points at the toolchain part the agreed toolchain names (ADR 0584 §1), never at the build + module's own program. + - kinds 2 and 4 (delivered after): the dependency's version and part digest the catalog last said + `version-delivered` for when the release is delivered (§376), one entry for the mesh. - kind 5 (has acted for): a fact, not a version: the acting part, its step, the build that acted and that the act was done (or released by hand), from the holder's `wait-ended` (*Each step's wait is its own part's*). - - kind 6 (runs a version that serves): a fact, per node: the verb or manifest word used and the dependency's build - on that node that serves it, from the node-engine seat's `running` and the catalog entry of that build. + - kind 6 (runs a version that serves): a fact: the verb or manifest word used and the dependency's delivered + version that serves it. A build of a watched branch other than the registration's first releases no version (§371): its entries are kept in the indexer's old `state` section `build-edges`, one key per module and watched branch holding the newest build's entries, keyed by its fingerprint, replaced by the next build and deleted when `registration-changed` says the - branch is no longer watched. The declared edge stays in the catalog graph; an entry is the release's or the build's - fact, never changed after. Why: the operator, 2026-11-10 about 22:10 CET (issue 1961); a version is per module and an - edge per artifact, so the artifact's digest is what an edge compares (the lead's review of these lines, same - evening). Each entry is about 0.1 KiB, about ten a version and four nodes for the delivery kinds, so `versions` - stays within its 64 MiB (an estimate). How it is checked: test 104. + branch is no longer watched, and they compare by the part's digest alike. The declared edge stays in the catalog + graph; an entry is the release's or the build's fact, never changed after. Why: the operator, 2026-11-10 about 22:30 to 23:00 CET and 22:10 CET (issue 1961), and + the lead's review of these lines. Each entry is about 0.1 KiB, about ten a version, so `versions` stays within its + 64 MiB (an estimate). How it is checked: test 104. - §375 **One query finds every edge behind, by the part's digest.** The seat `mesh-catalog`'s verb `outdated`, with - the indexer's tool `indexer_outdated`, answers every entry that is behind: for kinds 1 and 2, the recorded artifact - digest differs from that artifact's digest in the dependency's newest released version (for a build of another - branch, its newest build on that branch); for kinds 3 and 4, it differs from the digest the dependency's newest build - has where it acts (for kind 3 the agreed toolchain, for kind 4 what runs on that node); for kind 5, the newest version - of the acting part has not acted for the dependent's current build; for kind 6, the build on that node no longer - serves the verb or word. A dependency's newer version that left the artifact's digest as it was makes nothing behind, - so nothing is done twice for the same inputs. Each answer names the module and its version or build, the node for a - per-node entry, the kind, the dependency, what was recorded and what is newest, and the act that catches it up. Its - callers are any person, an agent session, the healers, the runner and the assigner; `indexer_outdated_again`, a hand - act written in the hand-act log, says the event that starts an entry's work again. At its start, the runner and the - assigner each ask `outdated` once and start the work it names, so a restart or a missed event leaves nothing behind. - Why: the operator, 2026-11-10 (issue 1961's "outdated"); events start the work, and the query finds what is behind - and answers a person. How it is checked: test 105. -- §376 **Each kind is checked on its own event, per node where it is delivered.** After a dependency's version is - released, on its `version-released`: the dependents by kind 1 whose entry is behind are rebuilt against it and their - pipelines started, as on `package-published` (§53), and those by kind 2 are delivered again on each node whose entry - is behind, the assigner writing that node's want again. After a dependency is delivered: by kind 3, when the agreed - toolchain names the build module's new build (*A build module's wait ends on the agreed toolchain*), its dependents - whose entry is behind are rebuilt; by kinds 4 and 6, on the node-engine seat's `running..` of the - dependency's new build on a node, the dependents on that node whose entry is behind are delivered again by their - wants there, so a dependent on one node follows its own node and waits for no other. The catalog also says - `version-delivered` (the module and the version, once every present node that places it runs it healthy, nodes away - named, ADR 0603 §7) on `mesh.seat.mesh-catalog.event.version-delivered`, kept 90 days at 16 MiB: the mesh-wide summary - a person and the status view read, which starts no per-node work. Kind 5 is held by the acting parts' waits - (*Within a revision the new version acts first*) and only shown by `outdated`. Why: the operator, 2026-11-10; the - events still start the work (ADR 0666 §14, §15); per node, since a node away holds only itself (ADR 0603 §7). How it - is checked: tests 104 and 105. + the indexer's tool `indexer_outdated`, answers every entry that is behind: for kind 1, the recorded digest differs + from the part's digest in the dependency's newest released version (for a build of another branch, its newest + build on that branch); for kind 3, it differs from the toolchain part the agreed toolchain names now; for kinds 2 and + 4, it differs from the dependency's newest delivered version; for kind 5, the newest version of the acting part has + not acted for the dependent's current build; for kind 6, the delivered version no longer serves the verb or word. A + dependency's newer version that left the part's digest as it was makes nothing behind, so nothing is done twice for + the same inputs. Only a stale edge (§378) that is behind has an act that catches it up, a rebuild; an ordering edge + behind is shown and starts nothing. Each answer names the module and its version or build, the kind, the + dependency, what was recorded and what is newest, and the act. Its callers are any person, an agent session, the + healers, the runner and the assigner; `indexer_outdated_again`, a hand act written in the hand-act log, says the + event that starts a stale entry's rebuild again. At its start, the runner asks `outdated` once and starts the + rebuilds it names, so a restart or a missed event leaves nothing behind. Why: the operator, 2026-11-10 (issue + 1961's "outdated"). How it is checked: test 105. +- §376 **A stale edge rebuilds on its event; a delivery is waited for mesh-wide.** On a dependency's `version-released`, + the dependents by kind 1 whose entry is behind are rebuilt against it and their pipelines started, as on + `package-published` (§53); when the agreed toolchain names a new toolchain part, the dependents by kind 3 whose entry + is behind are rebuilt. No other edge rebuilds or delivers anything again. A dependent's new version that a change + orders after its dependency's new version by kind 2, 4 or 6 is wanted only once that dependency's version is + delivered to every machine that places it and is present: the catalog says `version-delivered` (the module, the + version and its parts' digests) once every present machine placing it runs it healthy, from the node-engine seat's + `running`, on `mesh.seat.mesh-catalog.event.version-delivered`, kept 90 days at 16 MiB, and the assigner writes the + dependent's wants on it. A machine away is named and catches up when it is back (ADR 0603 §7); meanwhile the + dependent's status, in `assigner_why_not` and the status view, reads "waiting for delivery of ", naming + the machines it waits for. When every machine that places the dependency is away, it is not delivered: its status + reads "waiting for to be back" and its dependents wait; nothing is raised for a machine simply away. + Kind 5 is held by the acting parts' waits (*Within a revision the new version acts first*). Why: the operator, 2026-11-10 about 22:30 to 23:00 CET. How it is + checked: tests 104 and 106. - §377 **The first fill.** At the indexer's first start under G, after `versions` is filled (§372), each module's - newest version gets its entries once: the build kinds from the dependency version published latest before that - version's build was claimed, read with the times of `builder_versions`, and its digest; the delivery kinds, per - node, from the last `running` of each module on each node, which the node-engine seat's stream keeps last per - subject with no age limit; kind 5 as done for every acting part's running build; kind 6 from what each node runs. - Each filled entry is marked `filled`, so a person sees it was derived, not recorded. It is not filled again. Why: so - the first `outdated` does not find the whole mesh behind (the lead, 2026-11-10). How it is checked: whole + newest version gets its entries once: kinds 1 and 3 from the dependency version published latest before that + version's build was claimed, read with the times of `builder_versions`, and its part's digest; kinds 2, 4 and 6 from + the versions every present machine runs, read from the last `running` of each module on each node, which the + node-engine seat's stream keeps last per subject with no age limit; kind 5 as done for every acting part's running + build. Each filled entry is marked `filled`, so a person sees it was derived, not recorded. It is not filled again. + Why: so the first `outdated` does not find the whole mesh behind (the lead, 2026-11-10). How it is checked: whole (indexer), after the first fill `outdated` answers nothing for a mesh whose modules run their newest builds. +- §378 **Each edge kind makes its dependent stale or only orders it.** An edge makes the dependent stale when the + dependent is made from the dependency: kind 1, the dependency goes into it (an imported package), and kind 3, the + dependency builds it (its build toolchain part). Every other kind (2, 4, 5 and 6) only orders. A change to a build + module's own code, which is no toolchain part, rebuilds nothing. Why: the operator, 2026-11-10 about 22:30 to 23:00 CET. How it is checked: unit (indexer's + graph), each kind's stale-or-order, and a build module's code change rebuilds no module. +- §379 **A want names the released version and each part's digest.** From G's delivery a want `want..` + names, beside its fingerprint and source revision, the module's released version, for people (none for a build of + another watched branch), and the digest of each of its parts; the node-engine fetches and checks each part by its + digest, never by the version. The node-engine of G reads the two fields, its reader edge of kind 4 delivered before + any want writes them (ADR 0667 §4, §9). Why: the operator, 2026-11-10 about 22:30 to 23:00 CET. How it is checked: whole (assigner, node-engine), a want names + the version and the parts' digests, and a fetched part whose digest differs is not applied. +- §380 **`indexer_edges` answers both directions.** For any module or part, per watched branch, `indexer_edges` + answers what it depends on and what depends on it; per edge its kind, stale or order (§378), the manifest word it + came from, the part it points to, and what its newest release recorded (version and digest, or the fact for kinds 5 + and 6), and whether it is behind now (§375). Why: the operator, 2026-11-10 about 22:30 to 23:00 CET. How it is checked: whole (indexer), a fixture module's + edges are answered from both ends with their newest release's record. diff --git a/03-DESIGN/01-to-be/47-milestones/G.md b/03-DESIGN/01-to-be/47-milestones/G.md index 47810cf7..dc48292b 100644 --- a/03-DESIGN/01-to-be/47-milestones/G.md +++ b/03-DESIGN/01-to-be/47-milestones/G.md @@ -73,11 +73,12 @@ 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 six files, each read whole, its design lines numbered across them: +The part is seven 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. - [G-3-delivery-record-and-graphs](G-3-delivery-record-and-graphs.md): the delivery record, what the gate owes the forge, the state table, the two graphs and a change's graph difference. - [G-4-revision-view-and-steps](G-4-revision-view-and-steps.md): the revision view, what ADR 0656 leaves to this design, the choices under ADR 0656, what each step says and their tools. - [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-retires-and-answers](G-6-verbs-retires-and-answers.md): the verbs G adds, what retires, and the answers to the builders' and the reviewers' questions. +- [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 on).