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 891248ec..ef6f3b39 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 @@ -1522,17 +1522,18 @@ way is written down before the switch (ADR 0526, which ADR 0522 §6 asked of R4g ## Every delivery part wakes on its inputs alone -*ADR 0682 §9; issue 1982; the plan of milestone H, section 3.6.* A delivery part (the forge module, the forge +*ADR 0682 §11; issue 1982; the plan of milestone H, section 3.6.* A delivery part (the forge module, the forge bridge, the gate, the indexer, mesh-config, the runner, the builder, the build modules, the assigner, the node-engine, the grants part, the watchman, the condition keeper, the status view, the teller and the tool runner) keeps a watched copy of each of its own states, through one shape in mesh-sdk's state package (the shape the held pull request mesh-catalog #708 built for mesh-config, moved into mesh-sdk), and runs a pass only when an input it consumes changed, taking only the keys that input names. It keeps one timer, set to its earliest real deadline, a bound it states; it polls nothing, reads nothing of its own whole on a wake, and asks no call again on a timer. Which part moves onto the -shape in which release is design 47 H §762. How it is checked: the code review of every delivery module from milestone +shape in which release, and its cost (the shape's release in mesh-sdk rebuilds nearly every module, so H4 alone +carries it), is design 47 H §762. How it is checked: the code review of every delivery module from milestone H1 on refuses a timer that is no stated deadline, a poll and a whole re-read; mesh-sdk ships a test helper that counts -the requests a pass makes, and each delivery module's integration test that starts it whole against the bus (ADR -0548) asserts that a pass after one changed key requests that key alone; live, milestone H4 is proven by the bus's +the requests a pass makes, and each delivery module's integration test that starts it whole against the bus (the mesh's +instruction *how-work-is-done*) asserts that a pass after one changed key requests that key alone; live, milestone H4 is proven by the bus's slow consumers and consumers behind at 0 for an hour, read with `mesh-broker.rates` (H §760) and the bus module's consumer reads. @@ -2019,30 +2020,57 @@ ADR 0667's checks, of milestone G itself: and Go build module, mesh-delivery and mesh-catalog). Live: each module's test steps run once per level, read with `runner_test_runs`. A reader no part ends raises `pipeline-stands` within five minutes of its last sign of life (whole, watchman; design 47 G §732). -110. **One merge call is delivered end to end with no hand act** (design 47 H §734 to §738, §743, §746, §750). With - `pipelines-at-once` at 1, a merge call naming one pull request that changes one module says one `merge-called`; - the gate writes one source revision and opens one record; the indexer says one `take-in.taken` naming that module - alone; the runner runs one pipeline; once it passes and the version is released, the module is wanted on every - machine that places it, runs there, and the record ends (whole, forge module, gate, indexer, runner, assigner and - node-engine, mesh-catalog, mesh-delivery and `mesh-host`). Live: the plan's section 5, step 7, read with the tools - and quoted with its times. -111. **A head moved outside the mesh delivers nothing and is said** (design 47 H §739 to §742). A merge made in the - forge's screen gives one `head-moved`, no source revision and no pipeline; `head-untaken` is raised within - `untaken-bound`, naming the repository, branch and head; a later merge call in that repository clears it; and - `gate_head_take` delivers such a head by hand, written in the hand-act log (whole, forge bridge and gate, - mesh-delivery and mesh-catalog). -112. **Two repositories in one merge call are one pipeline, and pipelines run one at a time** (design 47 H §734, - §735, §743, §746 to §748). A merge call naming a mesh-sdk change and a module that imports it, both on one watched - branch, merges both or, with one member refused, neither; merged, it is one source revision, one `take-in.taken` - naming mesh-sdk, that module and mesh-sdk's other importers, and one pipeline in which every importer builds after - mesh-sdk's `package-published`; a second merge call made while it runs is said waiting and runs after its - `pipeline-ended`, and a restart of the runner starts no pipeline of its own (whole, forge module, gate, indexer and - runner). -113. **A want is the newest released version whose pipeline passed** (design 47 H §750, §751). A module released with - a passed pipeline is wanted on every placing machine at once, whatever build an acting part runs and whatever a - dependency's delivery; a released version whose pipeline failed is not wanted; an older version's end heard after - a newer one writes nothing; on one machine the bus module's and the backup holder's changed wants apply before the - others and the node-engine's last (whole, assigner and node-engine, mesh-delivery and `mesh-host`). +110. **One merge call is delivered end to end with no hand act** (design 47 H §734 to §738, §743, §746, §750, §751, + §771). This is the live proof of the chain (the plan's section 5, step 7), read with the tools and quoted with its + times, not one test: with `pipelines-at-once` at 1 and one placing machine away, a merge call naming one pull + request that changes one module says one `merge-called`; the gate writes one source revision and opens one record; + the indexer says one `take-in.taken` naming that module alone; the runner runs one pipeline; once it passes and the + version is released, the module is wanted and runs on every present placing machine, the record ends naming the + machine away, and that machine applies its want when back. Each part's half is a whole test in its own repository + (H-A-17): the forge module's (§734 to §736, §766), the gate's (§737, §738), the indexer's (§743), the runner's + (§746), the assigner's (§750, §751) and the node-engine's (§771). +111. **A head moved outside the mesh delivers nothing and is said** (design 47 H §739 to §742, §766). A merge made in + the forge's screen gives one `head-moved`, no source revision and no pipeline; `head-untaken` is raised within + `untaken-bound`, naming the repository, branch and head; a later merge call in that repository clears it; + `gate_head_take` delivers such a head by hand, written in the hand-act log; and a forge module stopped between its + last merge and the write of that member ends as an untaken head recovered so (whole, forge bridge and gate in + mesh-delivery and mesh-catalog; the stop case in the forge module's whole test). +112. **One take-in is one pipeline, and pipelines run one at a time** (design 47 H §743, §746 to §748). Split per + module (H-A-17): the forge module's whole test that a call naming a mesh-sdk change and an importer merges both or, + with one refused, neither; the indexer's that its `source-moved` names mesh-sdk, that importer and mesh-sdk's other + importers as movers; the runner's that they are one pipeline in which every importer builds after mesh-sdk's + `package-published`, that a second take-in waits and is placed on the first's end, on a cancel and on a set-aside, + that a pipeline waiting on its `approval` step does not count and is placed first when answered, that a newer + take-in moving the same module supersedes it in the waiting pipeline, that `pipelines-stalled` is raised when + pipelines wait and none runs, and that a restart starts no pipeline of its own. +113. **A want is the newest released version whose pipeline passed, written tier by tier** (design 47 H §750, §751, + §771, §772). The assigner's whole test: a module released with a passed pipeline is wanted on every placing + machine whatever build an acting part runs; a version whose pipeline failed is not wanted; an older end heard after + a newer one writes nothing; a placement `build` names the want's version; a consumer's want is written only after its + provider's tier runs, and a tier that does not run within `tier-bound` raises `tier-late`; a node-engine without the + want-by-version capability is said held. The node-engine's whole test: the bus module's and the backup holder's + changed wants apply first, then by `rank`, its own last. +114. **A head whose `required` step failed is refused** (design 47 H §735). The forge module's whole test: a runner's + `step-ended` naming a failed `required` step at a head's fingerprint makes `merge-pull` refuse that head, naming the + step; a later passed run asked again by the operator lets it merge. +115. **A member refused mid-call is said and raised** (design 47 H §767). The forge module's whole test against a + fixture forge that refuses the second merge: one `merge-called` with the first member and `refused`, `merge-partial` + raised by the call, cleared by a later call landing the refused member and by `forge_partial_clear`. +116. **A take-in held on a full store** (design 47 H §744). The indexer's whole test: with the catalog store full a + `source-moved` is held unacknowledged, said once as `take-in.pending`, not redelivered on a timer, and taken in on + `room`; another branch's take-in goes on meanwhile; `indexer_take_in_skip` ends it in the hand-act log. +117. **`validate` refuses a manifest problem and a cycle** (design 47 H §745). The assigner's and the runner's whole + tests: a take-in whose manifest names an unknown field fails `validate` with `manifest-refused` naming it and asks + no composition; one that makes a cycle fails it with `cycle` naming the cycle; the indexer's manifest runs no + validator. +118. **Every account calls every verb; a module publishes only what it declares** (design 47 H §752). The grants + part's whole test: a module calls a verb its manifest does not invoke and is answered, publishes an event its + manifest does not declare and is refused, and an enrolling node's account is held to its own grant. +119. **The builder's lines** (design 47 H §753 to §758). The Go build module's whole test takes the delivery queue + first; the builder's whole tests: a done, unreserved fingerprint asked by a build step ends carried with a version, + a failed 0.1.19 built again is 0.1.19, a catalog entry heard with no step ask builds nothing, `build.ended` names its + version; the runner's: a step with nothing to run ends `nothing to run` and its pipeline passes; the indexer's: a + registration with every step `bypass` is refused, naming them. ## What retires @@ -2143,7 +2171,7 @@ release reports the controller's code lines against research 063's baseline (acc | 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 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) | -| H | The build-and-delivery system delivers itself by its one model, in six releases (H0 to H5, the plan's section 6): one merge call of the seat `git`'s `merge-pull` naming one or more pull requests is a delivery's start and its group; the gate names the merged heads one source revision and opens its record; the indexer takes it in (a commit, the fingerprints of its repositories' modules, one catalog revision) and names the movers; one pipeline per take-in, none in parallel (`pipelines-at-once`, default 1); a want is the newest released version whose pipeline passed; the forge's event is the watchdog (`head-untaken`); every delivery part wakes on its inputs alone and reads no other part's state; the per-pull-request paths, the catch-up by comparison, the sweep and the checker go; one clean state placed by hand once, after which every release is delivered by its own pipeline (ADR 0682, ADR 0681, ADR 0666, ADR 0667; design 47 H §734 to §765) | 110 to 113 | mesh-delivery, mesh-catalog, `mesh-host`, mesh-tools, mesh-sdk, mesh-contracts, hq | opened by each release's prepare | +| H | The build-and-delivery system delivers itself by its one model, in six releases (H0 to H5, the plan's section 6): one merge call of the seat `git`'s `merge-pull` naming one or more pull requests is a delivery's start and its group; the gate names the merged heads one source revision and opens its record; the indexer takes it in (a commit, the fingerprints of its repositories' modules, one catalog revision) and names the movers; one pipeline per take-in, none in parallel (`pipelines-at-once`, default 1); a want is the newest released version whose pipeline passed; the forge's event is the watchdog (`head-untaken`); every delivery part wakes on its inputs alone and reads no other part's state; the per-pull-request paths, the catch-up by comparison, the sweep and the checker go; one clean state placed by hand once, after which every release is delivered by its own pipeline (ADR 0682, ADR 0681, ADR 0666, ADR 0667; design 47 H §734 to §774) | 110 to 119 | mesh-delivery, mesh-catalog, `mesh-host`, mesh-tools, mesh-sdk, mesh-contracts, hq | opened by each release's prepare | 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/H-1-the-merge-call-and-the-take-in.md b/03-DESIGN/01-to-be/47-milestones/H-1-the-merge-call-and-the-take-in.md index 2f2f5f23..7a8fbc31 100644 --- a/03-DESIGN/01-to-be/47-milestones/H-1-the-merge-call-and-the-take-in.md +++ b/03-DESIGN/01-to-be/47-milestones/H-1-the-merge-call-and-the-take-in.md @@ -26,7 +26,7 @@ is named, it is named by module and function, from the gap tables of 2026-11-20, registered modules." 2026-11-20 about 01:10 CET: "parallel pipelines sounds like a very bad idea". 01:15 to 01:20 CET: a delivery is started by hand by the merge it already needs, the lead named principle 3 (a start a person forgets is a silent non-delivery), and the operator chose "A": the merge through the mesh is the start and the group, and the -forge's event is the watchdog. ADR 0682 records it. The chain these lines build, in one sentence: a **merge call** +forge's event is the watchdog. ADR 0682 records it (cited by the clause numbers of its version 5). The chain these lines build, in one sentence: a **merge call** (the seat `git`'s `merge-pull` naming one or more pull requests) merges the heads, the gate names them one source revision per watched branch and opens its delivery record, the indexer takes that revision in and names the movers, the runner runs one pipeline for it when no other runs, and the assigner wants the newest passed release; the forge @@ -47,196 +47,259 @@ flowchart LR ### The merge call -- §734 **One merge call is a delivery's start and its group.** (ADR 0682 §1, ADR 0666 §11; the operator, 2026-11-20 +- §734 **One merge call is a delivery's start and its group.** (ADR 0682 §1, §2; ADR 0666 §11; the operator, 2026-11-20 01:20 CET; principle 3) The seat `git`'s verb `merge-pull` takes `pulls`, a list of one or more members - `{repository, number, head}` (the head the caller names, as ADR 0666 §11 has it), and `by`, the caller as who@node. - The members named in one call are one delivery and, when there are two or more, its group; nothing else makes a group. - The verb's single-pull form goes: a call naming one pull request is a list of one. Built in H1 in the forge module's - `merge-pull` handler and the seat `git`'s contract in mesh-delivery-contracts. How it is checked: whole (forge - module): a call naming two pull requests in two repositories merges both and says one `merge-called` (§736). - Replaces G §38's one-pull form. -- §735 **Every member is judged before any is merged.** (ADR 0666 §11; principle 3) The verb judges each member as - ADR 0666 §11 does (still the pull request's head, a branch protection that refuses a direct push, read again; no run - at the head's build-input fingerprint failed a `required` step, from the forge module's own `failed-steps`), all of - them first. When one member is refused, none is merged, and the answer names every refused member and why. Then it - merges the members in the order the call names them. Why this order: a group merged in part would land half a - delivery (ADR 0666 §13's "none delivered if one fails", kept for the call's group). What the call says when the - forge refuses a member after all were judged is question 1 of *Questions this file leaves open*. Built in H1 (forge - module). How it is checked: whole (forge module): a call whose second member's head moved merges neither and names - it. -- §736 **The merge call says one event.** (ADR 0682 §1; principle 1) When every member is merged, the forge module says - the seat `git`'s event `merge-called` on `mesh.seat.git.event.merge-called.`, kept on the stream - `SEAT_git_merge-called` for 30 days and up to 64 MiB, its body in the seat's `bodies`: `call` (an id the forge module - makes once per call: 16 lowercase hex), `by`, `at` (the time of the last merge) and `members`, one - `{repository, number, branch, head, commit}` per member, where `branch` is the pull request's base (a watched - branch) and `commit` the merge commit the forge records for that pull request. Only the forge module says it. Its - one consumer is the gate (§737), on a durable consumer of its program. Why 30 days: the gate takes in a call heard - after a long stop, and the forge module's `seen` keys are kept as long (G §585). Built in H1 (forge module, seat - `git`'s definition and contract). How it is checked: unit (the seat definition: the event and its body); - whole (forge module) as §734. -- §737 **The gate names the merged heads one source revision and opens the record.** (ADR 0682 §1; principles 1 - and 12) The gate consumes `merge-called`. For each watched branch its members name, it writes `source.` once, - by compare-and-set: the branch's previous heads with each member's repository at its `commit`, numbered one above - the branch's newest, carrying `call`. It opens one delivery record per such revision, keyed `.` - (A-33 stands), its members the call's members on that branch, `call` and `by` in its trace, and says `source-moved` - with `branch`, `source`, `call`, `start` (false; true only for A-401's start pass of a newly watched branch, which - stays) and `heads` (the repositories it moved, each `{repository, commit}`). A - `merge-called` heard again writes nothing: its record's key exists. A call whose members name two branches is two - source revisions and two records, each naming the same `call`. The gate numbers every source revision; no other part - keeps a number of its own. Built in H1 in the gate: its `moveSource` moves from the `take-in.taken` handler to a - `merge-called` handler; `ForgeMerged`, `moveHead` and the tool `gate_source_follow` go (§764). How it is checked: - whole (gate): a `merge-called` with two members on one branch gives one revision, one record and one - `source-moved`; the same event heard twice gives one. Replaces A-34 (the source moved on `take-in.taken`), G §291, - A-431's numbering by the indexer, and A-464 to A-464e. + `{repository, number, head}` (the head the caller names, as ADR 0666 §11 has it), and `by`, the caller as who@node; + the forge module records `by` beside the bus account the tool runner proves for the call. The members named in one + call are one delivery and, with two or more, its group; nothing else makes a group. The verb's single-pull form goes: + a call naming one pull request is a list of one, and its callers change with it in H1 (the tool runner's + `merge-pull` tool and its description, the claude-code module's instructions and playbook 07's merge step, which name + one pull request). The verb answers `call` (§766) at once and the members' outcome when the call ends. Built in H1 in + the forge module's `merge-pull` handler and the seat `git`'s contract in mesh-delivery-contracts. How it is checked: + whole (forge module): a call naming two pull requests in two repositories merges both and says one `merge-called` + (§736). Replaces G §38's one-pull form. +- §735 **Every member is judged before any is merged.** (ADR 0682 §1; ADR 0666 §11; principle 3) The verb judges each + member as ADR 0666 §11 does (still the pull request's head; a branch protection that refuses a direct push, read + again; no run at the head's build-input fingerprint failed a `required` step), all of them first. When one member is + refused, none is merged, and the answer names every refused member and why. Then it merges the members in the order + the call names them. The forge module's `failed-steps` that this judges is written from the runner's `step-ended`, + whose body names the mover, its commit and its build-input fingerprint (H-A-18). Why judging first: a group merged in + part lands half a delivery. Built in H1 (forge module). How it is checked: whole (forge module): a call whose second + member's head moved merges neither and names it; a head at whose fingerprint a `required` step failed is refused, + naming the step (acceptance test 114). +- §766 **The call is written before its first merge and said again at the forge module's start.** (H-A-18; principles + 3 and 4) Before it merges anything, the forge module writes the call's key `call.` in its own template state + `calls` (value: `by`, the bus account, `at`, the members, each with `state` `judged`, `merged` with its commit, or + `refused` with why), and updates each member as it merges. At its start it reads every call whose event it has not + said (`said` false) and says `merge-called` for what landed, so a stop between the last merge and the event loses + nothing it recorded. A call is kept `call-retention` (a setting, default 30 days), then deleted by the forge module. + Its tools: `forge_calls` (the calls, newest first, with each member's state) and `forge_call_say_again` (with `call` + and `why`, says its `merge-called` again, written in the hand-act log). A stop between a merge and the write of that + member's `merged` leaves a head the call never names: it is an untaken head (§740), recovered with `gate_head_take` + (§742). Built in H1 (forge module). How it is checked: whole (forge module): a restart after the second of three + merges says one `merge-called` naming the two that landed; acceptance test 111's stop case. +- §767 **A member refused after every member was judged is said and raised.** (H-A-1; principle 3) When the forge + refuses a member after all were judged (a conflict that appears between the judging and its merge, the forge down + mid-call), the forge module stops merging, says `merge-called` with the members that landed and `refused`, one + `{repository, number, why}` per member not merged, and raises the finding `merge-partial`, scope `delivery`, id the + call, naming each refused member. The landed members are delivered as any call's. It clears the finding when a later + call lands every refused member (read from its own `calls`), or by its tool `forge_partial_clear` with `call` and + `why`, written in the hand-act log. A call that landed no member says no `merge-called`. Built in H1 (forge module). + How it is checked: whole (forge module): a fixture forge that refuses the second merge gives one `merge-called` with + the first member and `refused`, and `merge-partial` raised and cleared by a later call (acceptance test 115). +- §736 **The merge call says one event.** (ADR 0682 §1; principles 1 and 11) Once its members are merged or refused, + the forge module says the seat `git`'s event `merge-called` on `mesh.seat.git.event.merge-called.`, kept on + the stream `SEAT_git_merge-called` for `merge-called-retention` (a setting, default 30 days) and up to + `merge-called-cap` (a setting, default 64 MiB), its body in the seat's `bodies`: `call` (16 lowercase hex, made once + per call), `by`, `account`, `at` (the time of the last merge), `members`, one `{repository, number, branch, head, + commit}` per landed member, where `branch` is the pull request's base (a watched branch) and `commit` the merge + commit the forge records for that pull request, and `refused` (§767). Only the forge module says it. Its one consumer + is the gate (§737), on a durable consumer of its program. Why 30 days: the gate takes in a call heard after a long + stop, as the forge module's `seen` keys are kept (G §585). Built in H1 (forge module, the seat `git`'s definition and + contract). How it is checked: unit (the seat definition: the event and its body); whole (forge module) as §734. +- §737 **The gate names the merged heads one source revision per call and opens the record.** (ADR 0682 §1, §2; H-A-13, + H-A-19; principles 1, 3 and 12) The gate consumes `merge-called`. For each watched branch its members name, it writes + `source.` once, by compare-and-set keyed by the call (the revision carries `call`, and a revision of that + branch already carrying that call writes nothing): the branch's previous heads with each member's repository at its + `commit`, where two members of one repository on one branch name the last member's commit in call order, numbered one + above the branch's newest. It opens one delivery record per such revision, keyed `.` (A-33 stands), + its members the call's members on that branch, `call`, `by` and `account` in its trace; says `record-opened` on + `mesh.seat.mesh-delivery.event.record-opened.` with `branch` and `source`, so the session that called can wait + on its own call; and says `source-moved` on `mesh.seat.mesh-delivery.event.source-moved..` with + `branch`, `source`, `call`, `start` (false; true only for a branch's first revision, §768) and `heads` (the + repositories it moved, each `{repository, commit}`). A call whose members name two branches is two source revisions + and two records, each naming the call. The gate numbers every source revision; no other part keeps a number of its + own. `source-moved` is kept for `source-moved-retention` (a setting, default 30 days). Built in H1 in the gate: its + `moveSource` moves from the `take-in.taken` handler to a `merge-called` handler; `ForgeMerged`, `moveHead` and + `gate_source_follow` go (§764). How it is checked: whole (gate): a `merge-called` with two members on one branch gives + one revision, one record and one `source-moved`; heard twice it gives one; two members of one repository give its + last member's commit. Replaces A-34, G §291, A-431's numbering by the indexer, and A-464 to A-464e. - §738 **A delivery record follows its pipeline to the machines.** (ADR 0666 §9; G §141 to §147) The record opened by §737 is the record of G §141 to §147, one per source revision: it consumes the runner's `pipeline-started` and - `pipeline-ended`, the parts' `wait-held` and `wait-ended`, and the node-engine seat's `running`, on the gate's own - durable consumer, writes its trace (the assignment graph revisions it moved between, from the assigner's `wanted`), - and ends as G §147 says. A take-in with no movers (§741) ends its record at once as `nothing to deliver`. Built in - H3 in the gate's consumer (`stepFamilies`) and record (`SetTrace`, `EndIfRun`). How it is checked: whole (gate): - a record of a one-module delivery ends when the module runs on every placing machine (acceptance test 110). + `pipeline-ended` (§746) of its source revision, and of the pipelines `package-published` starts from it (§747), the + parts' `wait-held` and `wait-ended`, the assigner's `wanted` and the node-engine seat's `running`, on the gate's own + durable consumer; writes its trace (the assignment graph revisions it moved between, from `wanted`); and ends as G §147 + says, or `failed` when the assigner says a tier late (§751). A take-in with no movers ends its record at once as + `nothing to deliver`. Built in H3 in the gate's consumer (`stepFamilies`) and record (`SetTrace`, `EndIfRun`). How it + is checked: whole (gate): a record of a one-module delivery ends when the module runs on every present placing + machine. ### The forge bridge's one message, and the watchdog -- §739 **The forge bridge says one message per move of a watched branch's head.** (ADR 0682 §2, ADR 0666 §6; G §11, - A-236) On every `git.branch-moved` of a watched branch, and at its start for every watched branch's head, the bridge - reads the head through `git.branch` (never the event's body) and writes one message `head-moved` on its stream - `forge`, subject `forge...head-moved`: `repository`, `branch`, `head`, `before` (the head it held - for that branch in its state `heads`, empty the first time) and `start` (true when said at its start). It writes it - whether the head moved by a merge call, a merge in the forge's screen or an admitted push: it reads no pull request - and no tree. A head equal to the one it holds writes nothing. An unprotected watched branch writes nothing and is - said as `branch-unprotected` (G §17 stands). Its one consumer is the gate (§740). Built in H1 in the bridge; the - messages `merged` and `pushed`, their `base`, their trees in its state `inputs`, and its call of `git.pull` for a - merged commit go (§764). How it is checked: whole (bridge): a merge, an admitted push and a restart each give one - `head-moved`; a head heard twice gives one. Replaces G §509 and §714's message form; this is item 6 of the plan's - section 4. -- §740 **A head no merge call delivered is an untaken head.** (ADR 0682 §2; principles 1 and 3) The gate consumes - `head-moved` and keeps, in its template state `heads` (one key `.`, value `{head, since}`, the - key deleted by the gate when `source.` names that head), each head that `source.` does not name for - that repository. When `untaken-bound` (a setting of the gate, default 10 minutes, at least 1) passes and - `source.` still does not name that head, the gate raises the finding `head-untaken`, scope `delivery`, id +- §739 **The forge bridge says one message per move of a watched branch's head.** (ADR 0682 §3; G §11, A-236) On every + `git.branch-moved` of a watched branch, and at its start for every watched branch's head, the bridge reads the head + through `git.branch` (never the event's body) and writes one message `head-moved` on its stream `forge`, subject + `forge...head-moved`, kept `head-moved-retention` (a setting, default 7 days): `repository`, + `branch`, `head`, `before` (the head it held for that branch in its state `heads`, empty the first time) and `start` + (true when said at its start). It writes it whether the head moved by a merge call, a merge in the forge's screen or + an admitted push: it reads no pull request and no tree. A head equal to the one it holds writes nothing. An + unprotected watched branch writes nothing and is said as `branch-unprotected` (G §17 stands). Its one consumer is the + gate (§740). Built in H1 in the bridge; the messages `merged` and `pushed`, their `base`, their trees in its state + `inputs`, and its call of `git.pull` for a merged commit go (§764). How it is checked: whole (bridge): a merge, an + admitted push and a restart each give one `head-moved`; a head heard twice gives one. Replaces G §509 and §714's + message form. +- §740 **A head no merge call delivered is an untaken head.** (ADR 0682 §3; principles 1, 3 and 11) The gate consumes + `head-moved` and keeps, in its template state `heads` (one key `.`, value `{head, since}`, deleted + by the gate when `source.` names that head), each head that `source.` does not name for that + repository. When `untaken-bound` (a setting of the gate, default 10 minutes, at least 1) passes and `source.` + still does not name that head, the gate raises the finding `head-untaken`, scope `delivery`, id `.`, naming the repository, the branch, the head, since when, and "moved outside the mesh: delivered by nothing". It clears it when `source.` names that repository at the newest head `head-moved` - said (a later merge call delivers it). The gate keeps one deadline timer, set to the earliest `since` plus the bound, - and no other clock. Built in H1 in the gate. How it is checked: whole (gate, bridge): a head moved by a merge call - raises nothing; a head pushed outside the mesh raises `head-untaken` within the bound, starts no pipeline, and + said (a later merge call or §742's hand take). The gate keeps one deadline timer, set to the earliest `since` plus the + bound, and no other clock. Built in H1 in the gate. How it is checked: whole (gate, bridge): a head moved by a merge + call raises nothing; a head pushed outside the mesh raises `head-untaken` within the bound, starts no pipeline, and clears when a later merge call takes its repository in (acceptance test 111). Replaces A-463's `merge-untaken` and - the head half of G §12 (§741 keeps its step half). -- §741 **`pipeline-stands` times a pipeline's steps, not a head.** (ADR 0666 §24; principle 7) The watchman's finding - `pipeline-stands` (G §12, §75) is raised for a pipeline step standing still five minutes; a watched branch's head - that starts no pipeline is the gate's `head-untaken` (§740) alone, so the watchman learns no head. A pipeline waiting - its turn (§746) is progress not owed and raises neither. Built in H1 in the watchman's `takein` and `signals` parts. - How it is checked: whole (watchman): a pipeline waiting behind another raises nothing. Answers question 6 of - specification A. -- §742 **Taking an untaken head in by hand.** (ADR 0682 §2; principle 4) The gate's tool `gate_heads` reads the state + the head half of G §12. An acknowledge tool that silences a known `head-untaken` without delivering it was proposed + by the review and is not built: no record or answer asks for it (noted for H4's tools table). +- §741 **`pipeline-stands` times a pipeline's steps, not a head.** (ADR 0682 §7; ADR 0666 §24; principle 7) The + watchman's finding `pipeline-stands` (G §12, §75) is raised for a pipeline step standing still five minutes; a watched + branch's head that starts no pipeline is the gate's `head-untaken` (§740) alone, so the watchman learns no head. A + pipeline waiting its turn (§748) is progress not owed and raises neither. Built in H1 in the watchman's `takein` and + `signals` parts. How it is checked: whole (watchman): a pipeline waiting behind another raises nothing. +- §742 **Taking an untaken head in by hand.** (ADR 0682 §3; principle 4) The gate's tool `gate_heads` reads the state `heads` with each head's since and finding; `gate_head_take`, with `repository`, `branch` and `why`, names that head a source revision as §737 does, its `call` `hand..