Compare commits
10
Commits
e27fd02269
...
87827ebb82
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
87827ebb82 | ||
|
|
bfd5fd2c0b | ||
|
|
9f9cb58f54 | ||
|
|
9bcd0ad197 | ||
|
|
27c9c6f11f | ||
|
|
893d83d23b | ||
|
|
5df2eca59e | ||
|
|
b157283202 | ||
|
|
f215cb9207 | ||
|
|
c46669a17e |
+5
-3
@@ -916,12 +916,14 @@ becomes a message). **Decided by** ADR 0227, 0231, 0240, 0252, 0283, 0564, 0668.
|
||||
(ADR 0283).
|
||||
- **probe** — one look at one thing's health, run by whoever owns the verdict; what a probe returns is a
|
||||
**finding**, before it becomes a condition. A finding is kept as a key `<scope>.<id>.<kind>` in its observer's
|
||||
bucket `findings` until it is no longer observed (ADR 0564 §2).
|
||||
bucket `findings` until it is no longer observed (ADR 0564 §2); from design 47's milestone G the observer also says
|
||||
each as its own event, and states every finding it owns at its start, so the condition keeper hears findings and
|
||||
reads no observer's bucket (ADR 0596 §2; design 47 G §383, §384).
|
||||
- **node health report** — each node-engine's own report of its node's health, a key that node's engine writes
|
||||
and the watchman reads (ADR 0564, as its progressive insight of 2026-10-29 has it); its layout is mesh-sdk's.
|
||||
- **observer** — a part that writes findings for the condition keeper: the watchman, the self-check and the
|
||||
healers (ADR 0564 §2), and each caller of a kept call, for its `call-unanswered` (ADR 0668 §3). An observer never
|
||||
writes a condition.
|
||||
healers (ADR 0564 §2), and each caller of a kept call, for its `call-unanswered` (ADR 0668 §3); from design 47's
|
||||
milestone G, every module that writes findings (design 47 G §383). An observer never writes a condition.
|
||||
- **condition keeper** — the holder of the seat `mesh-conditions`: the one writer of the
|
||||
open conditions, raising each from an observer's finding and clearing it when the finding goes, and saying
|
||||
`condition-raised`, `condition-changed` and `condition-cleared` (ADR 0564 §2, §3). The controller keeps them
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
code: [mesh-controller, mesh-catalog modules/mesh-delivery-gate, mesh-catalog modules/gitea, mesh-delivery, mesh-host, mesh-sdk, mesh-vault, mesh-contracts, hq 00-META/checks]
|
||||
updated: 2026-11-10
|
||||
updated: 2026-11-11
|
||||
decisions:
|
||||
- "ADR 0667"
|
||||
- "ADR 0666"
|
||||
@@ -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
|
||||
@@ -1457,7 +1459,9 @@ the operator for the bus node's want (ADR 0539 §15).
|
||||
naming its fingerprint, which its node composes again (ADR 0547 §2).
|
||||
- **A build before its want.** Every module, the builder's own and the build modules among them, is wanted only
|
||||
from the builder's done key whose artifacts all name a reference; a module whose key is not yet done
|
||||
waits under the assigner's first rule and fails nothing (ADR 0524 §7, ADR 0539 §18).
|
||||
waits under the assigner's first rule and fails nothing (ADR 0524 §7, ADR 0539 §18). From G's delivery the assigner
|
||||
takes a build's digests from `version-released` and the builder's `build.ended`, never its done key (design 47 G
|
||||
§379).
|
||||
- **History: the switch to release 6 was one plan, release 5's last** (it is delivered; ADR 0547 takes the composing, signing and issuing it gave the controller away again). Release 5's controller ran
|
||||
the group's plan with the new node-engine and the new controller in one tier (issue 1942), so every node's last
|
||||
declaration named the new node-engine and carried the operator's public key, and the control-node's named the new
|
||||
@@ -1618,7 +1622,7 @@ list:
|
||||
that group's own heads, read from the check's record (ADR 0644, How it is checked), and no member of it was
|
||||
delivered ahead of it.
|
||||
27. **A new acting part needs no code elsewhere.** A fixture seat declaring a rule, with a fixture holder, gets its
|
||||
edges with no code change elsewhere, and a search of the delivery parts' code finds no other module's name.
|
||||
edges with no code change elsewhere; the code review reads that no delivery part's code names another module.
|
||||
28. **Waits stay within their step.** A cycle among waits within one step is refused; an acting part acting on
|
||||
itself, and two acting parts acting on each other in different steps, pass.
|
||||
29. **A failed acting part leaves the mesh on what runs.** A build module whose new build fails, and one whose wait
|
||||
@@ -1752,13 +1756,15 @@ What milestone G's prepare found, and its test:
|
||||
59. **A session hears an accepted record** (issue 595). An Approve that accepts a record makes the knowledge base say
|
||||
`reviewed` with what was accepted, by the operator and with the warrant, and the tool runner's account hears it, so
|
||||
a session waiting with `mesh_wait` wakes on it (whole, knowledge base; live).
|
||||
60. **The store's holder takes its own build when its seat is broken.** With a fixture holder of `oci-artifact-registry`
|
||||
that refuses every store, its new build is kept on the build node, named in the builder's done key, fetched by the
|
||||
node-engine through `kept-artifact`, and once it runs the next build is stored through the seat, with no hand act;
|
||||
a call of `kept-artifact` from an account other than a node-engine's is refused; it is refused for a module that
|
||||
does not claim `oci-artifact-registry`; fetched bytes that differ from the done key's digest are not applied; an
|
||||
artifact over the bus's value limit is fetched whole as an object; with the keeping node away, or the build swept,
|
||||
the want waits and the have says why (whole, builder, build module and node-engine).
|
||||
60. **The store's holder takes its own build when its seat is broken** (design 47 G §271). With a fixture holder of
|
||||
`oci-artifact-registry` that refuses every store, its new build is kept on the build node, the builder's
|
||||
`build.ended` naming it kept there with its digest, and the want naming that digest; the node-engine fetches it
|
||||
through `kept-artifact` and checks it against the want's digest, and once it runs the next build is stored through
|
||||
the seat, with no hand act; a call of `kept-artifact` from an account other than a node-engine's is refused; it is
|
||||
refused for a module that claims the seat but is not its holder in the seat list; fetched bytes that differ from
|
||||
the want's digest are not applied; an artifact over the bus's value limit is fetched whole as an object; with the
|
||||
keeping node away, or the build swept, the want waits, the have says why, `kept-build-waits` is raised after 60
|
||||
minutes and cleared once the have runs the want (whole, builder, build module and node-engine).
|
||||
61. **No module reads the indexer's `modules`.** The watchman's manifest findings, the status view's `view_reach`, the
|
||||
forge module's writable repositories and the reads of the holders of `mesh-config`, `mesh-provisioner` and
|
||||
`mesh-self-check`, of the claude-code module and of the tool runner each answer from the catalog half: after a
|
||||
@@ -1795,8 +1801,8 @@ integration test, which starts the module whole against the real bus and store;
|
||||
`modules/mesh-delivery-pipeline` in mesh-delivery, has one of its own. The checker's tests go with it at G's delivery,
|
||||
its whole-module test, its try test and the examiner's table among them, and so do the indexer's try-candidate rows and
|
||||
mesh-delivery's `tryevent`; tests 21 to 24, 26, 31, 41, 46, 52 and 58, which the checker proves, hold until then, and
|
||||
the runner's tests below restate what of them stays (22 in 73, 23 in 84, 46 in 84, 58 in 84). No repository ends the
|
||||
milestone with more tests than it starts with (research 085, Direction, One milestone; the test budget).
|
||||
the runner's tests below restate what of them stays (22 in 73, 23 in 84, 46 in 84, 58 in 84).
|
||||
No module ends the milestone with more tests than it starts with, counted per catalog module (research 085, Direction, One milestone; the test budget, per module, the operator 2026-11-11).
|
||||
|
||||
63. **R1, no hand act delivers a change.** A change to the indexer, the grants part and the tool runner is delivered end
|
||||
to end, and the hand-act log of the seat `mesh-hand-acts` names no act for it (live; mesh-delivery, mesh-tools).
|
||||
@@ -1814,9 +1820,8 @@ milestone with more tests than it starts with (research 085, Direction, One mile
|
||||
prerequisite; with one member passed and another still running no want is written until `group-ended` (whole,
|
||||
indexer, gate, runner and assigner, mesh-delivery and mesh-catalog; live).
|
||||
68. **R6, modules, never repositories.** A module whose watched branch is `beta` on one machine is delivered from it
|
||||
there only; the lint step refuses a module, branch or repository name in a string, a constant or a table, and not
|
||||
an import path (whole, assigner, mesh-delivery; unit, the Go build module's lint, mesh-catalog; live, a search of the
|
||||
delivery parts' code).
|
||||
there only (whole, assigner, mesh-delivery); the code review reads that no part fixes a module, branch or repository
|
||||
name in its code, a guideline (design 47 G §7).
|
||||
69. **R7, any size.** Values of one, ten and a hundred times the bus's per-value limit are stored, sent as a verb's reply
|
||||
and as an event, and read back whole by a caller the sender's seat definition names and a consumer declaring its
|
||||
event, and refused to a module that declares neither (whole, mesh-sdk, against the real bus).
|
||||
@@ -1866,7 +1871,9 @@ The failure paths:
|
||||
not run`, never passed; two modules owning one path are refused (whole, runner and assigner).
|
||||
85. **A forged step result**, from an account other than the step's seat holder's, or naming another commit or
|
||||
fingerprint, is refused and said; a `step-ended` on another node's subject is refused by the bus; a verb whose
|
||||
definition names no `callers` admits only the holder roles and the operator (whole, runner and grants part).
|
||||
definition names no `callers` admits only the holder roles and the operator; a change adding a new `invokes` of
|
||||
`node-packet-filter.remove`, a verb whose callers are `invokers`, names that grant in its `pipeline-ended`'s
|
||||
`widens` (whole, runner and grants part).
|
||||
86. **An author's own review** is refused; a reviewer's passes the step (whole, runner).
|
||||
87. **A step seat with no holder** ends its pipeline failed, naming the seat, within five minutes (whole, runner).
|
||||
88. **A runner stopped mid-step** takes its pipelines up again from its kept state when it starts, a replaced holder
|
||||
@@ -1925,7 +1932,40 @@ ADR 0667's checks, of milestone G itself:
|
||||
reporting it; with one of its two artifacts published `1.4.3` is not released, and `builder_publish_again`
|
||||
publishes the other under `1.4.3`, which the catalog then says `version-released` once; a new `1.5` builds as
|
||||
`1.5.0`; two builds close together reserve two versions; a `beta` build reserves none and is delivered; a manifest
|
||||
saying `1.4-beta` is refused (whole, builder, indexer and Go build module, mesh-delivery and mesh-catalog).
|
||||
saying `1.4-beta` is refused; `builder_publish_again` names `1.4.3`; a `1.4.2` artifact published after `1.4.3` is
|
||||
released late, said by no `version-released` and rebuilds nothing; a publish of an unreserved version is refused
|
||||
by the registry holder (whole, builder, indexer and Go build module, mesh-delivery and mesh-catalog).
|
||||
103. **A group's run on request publishes no version** (design 47 G §373). A run on request of a group changing a
|
||||
package and a module importing it builds the module against the package member's build by the digest the builder
|
||||
took from its own `build.ended`, the fetched bytes checked against it; a member whose build is not done holds the
|
||||
dependent with a `wait-held` naming it, and one whose build failed fails the dependent's step naming it; the run
|
||||
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 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 `package-published` of `0.1.16` that changes the imported
|
||||
package rebuilds it, started by the runner after its `outdated` ask, 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, keyed by mesh-sdk's source revision; `runner_catch_up` does it by hand 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 <machine>
|
||||
to be back" and nothing is raised; with a placing machine present that never runs it, `delivery-waits` is raised
|
||||
after 60 minutes naming it and its node-engine's version; 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`).
|
||||
107. **A finding is stated from its observer's truth** (design 47 G §383, §384, §388). A fixture observer's
|
||||
`finding-written` and `finding-cleared` raise and clear a condition; restarted after its cause has gone, it clears
|
||||
its finding at its start; restarted with a call unanswered for two hours, it says neither `condition-cleared` nor
|
||||
`condition-raised` (whole, condition keeper and a fixture observer, mesh-catalog and mesh-sdk). Live: after G's
|
||||
delivery, a node-engine restarted with the full seat list clears its `seat-list-unread`, read with
|
||||
`mesh-conditions.conditions`.
|
||||
|
||||
## What retires
|
||||
|
||||
@@ -2021,7 +2061,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.<module>.<fingerprint>` 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 102 | 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
|
||||
|
||||
@@ -3,7 +3,7 @@ layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: G
|
||||
updated: 2026-11-10
|
||||
updated: 2026-11-11
|
||||
decisions:
|
||||
- "ADR 0668"
|
||||
- "ADR 0667"
|
||||
@@ -92,10 +92,12 @@ check and deliver milestone G itself (ADR 0667 §2); each of them says so in a l
|
||||
list when it is removed (*How milestone G itself is checked and delivered*). A registration holds no foundation
|
||||
value. How it is checked: a unit test of the manifest validator refuses a template in the manifest of every part on
|
||||
its list, the runner's included, and judges every other part's manifest as any part's.
|
||||
- §7 **No part fixes a name.** Every branch, repository and module name a part needs is read from the registrations and the
|
||||
catalog graph; the lint step refuses such a name in a string, a constant or a table of code logic, a Go import path
|
||||
not being code logic (ADR 0666 §5). About 39 such names in 9 parts were found on 2026-11-09 (research 086, Findings);
|
||||
milestone G removes them.
|
||||
- §7 **No part fixes a name: a guideline the code review reads.** Every branch, repository and module name a part
|
||||
needs is read from the registrations and the catalog graph, never fixed in its code. This is a guideline, not a
|
||||
step: the code review reads it, and no lint step scans for names (the operator, 2026-11-11 about 00:05 CET: the scan was a flaky check; where
|
||||
guidelines live is research 087's). It departs from ADR 0666 §5's refusal by the lint step, by the operator's choice,
|
||||
and a later record brings it in line. The names G's own work removes (about 39 in 9 parts, found on 2026-11-09,
|
||||
research 086, Findings) are removed by its subtasks, each naming the name it removes.
|
||||
- §8 **The first registrations are one ask.** At its first start on G's build the indexer, holding no registration,
|
||||
proposes one registration for every module its trunk revision holds, from what it took in (the origin and path of
|
||||
each), its watched branch the repository's default branch read through the seat `git`, and the statuses the check
|
||||
@@ -123,8 +125,7 @@ check and deliver milestone G itself (ADR 0667 §2); each of them says so in a l
|
||||
the warrant writes nothing, and a declined one writes nothing; a change from `required` to `bypass` asks, showing
|
||||
that line; `registration-changed` is said and `registrations` answers the history; the first start proposes the seed
|
||||
as one ask, and `indexer_seed_again` asks it again after a Decline and after an expiry; a policy making code review
|
||||
`required` is refused. Unit (the Go build module's lint step): a module name in a string, a constant and a table is
|
||||
refused, an import path is not. Tests 75, 68 and 83.
|
||||
`required` is refused. Tests 75, 68 and 83.
|
||||
|
||||
### Watched branches and the catalog graph per branch
|
||||
|
||||
@@ -208,8 +209,10 @@ check and deliver milestone G itself (ADR 0667 §2); each of them says so in a l
|
||||
`mesh.seat.<seat>.event.step-ended.<node>`, the node that ran it in the subject and each holder's account granted only
|
||||
its own node's subject, through a durable consumer of its own, so a step outlives a restart of either side (ADR 0666
|
||||
§7, ADR 0363 §2). A build seat's holder restarted mid-step gets the step again from its work queue and finishes it
|
||||
(ADR 0664 §1). A unit or integration test step says its test counts in `step-ended`, and `pipeline-ended` names any
|
||||
repository over 50 integration or 500 unit tests, and any catalog module over them (ADR 0666 §8; the test budget). A step's outcome is one of `passed`, `failed`, `nothing to run`,
|
||||
(ADR 0664 §1). A unit or integration test step says its catalog module's test counts in `step-ended`; `pipeline-ended` carries each
|
||||
catalog module's counts against the test budget, which is counted per catalog module (at most 50 integration and
|
||||
500 unit tests each), and `pipeline-ended` names any catalog module over it (ADR 0666 §8; the test budget, per
|
||||
module, the operator 2026-11-11). A step's outcome is one of `passed`, `failed`, `nothing to run`,
|
||||
`bypassed`, `carried` (with the pipeline it was carried from), `could not run` (naming the part not heard),
|
||||
`waiting on <person>`, `accepted` (a failed `optional` step a person accepted, with who and why), `not asked` (an
|
||||
`approval` step after a failed `required` step), `superseded` and `cancelled`.
|
||||
@@ -391,9 +394,16 @@ check and deliver milestone G itself (ADR 0667 §2); each of them says so in a l
|
||||
starts, where ADR 0666 §15 numbers a package at its publication and design 51 publishes a held digest under a new
|
||||
number: a packed file carries its version, so it must be known before the build; the operator's choice, which a
|
||||
later research brings the records in line with. How it is checked: test 102.
|
||||
- §53 **Every dependent is rebuilt against it.** On `package-published` every artifact with a kind-1 edge to the package is
|
||||
rebuilt against the new version, and the runner, which consumes the event, starts its pipeline; nothing else is
|
||||
rebuilt, and a change to tests alone publishes nothing (ADR 0666 §15; research 086, R18).
|
||||
- §53 **Every dependent behind is rebuilt against it, on `package-published`.** The builder says `package-published`
|
||||
for every package build of a watched branch: with its released version on the registration's first watched branch,
|
||||
and on another watched branch by its digest alone, the build stored by digest with no version (§371). The runner,
|
||||
which consumes it, asks the catalog's verb `outdated` for that package on that branch, a kept call (ADR 0668 §1,
|
||||
§2), and starts a pipeline for each dependent by kind 1 whose recorded part digest differs from the published one:
|
||||
the catalog compares (§375), the runner starts, and no other part rebuilds anything. A `package-published` whose
|
||||
version is lower than the highest the catalog holds released for that module starts nothing (§382). Nothing else is
|
||||
rebuilt, and a change to tests alone publishes nothing (ADR 0666 §15; research 086, R18). Why: ADR 0666 §15 has the
|
||||
runner consume `package-published`; the digest comparison is the operator's (2026-11-10), and one event for both
|
||||
branches is the design's choice, round 2 of the review by architectural domain, 2026-11-10.
|
||||
- §54 **A second start writes nothing.** The runner starts a pipeline on two events, the indexer's `take-in.taken` (ADR
|
||||
0666 §13) and `package-published` (ADR 0666 §15). When both reach it for the same source revision and module, the
|
||||
second start writes nothing: the runner writes a pipeline's key (watched branch, source revision and module, *The
|
||||
|
||||
@@ -3,7 +3,7 @@ layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: G
|
||||
updated: 2026-11-10
|
||||
updated: 2026-11-11
|
||||
decisions:
|
||||
- "ADR 0667"
|
||||
- "ADR 0666"
|
||||
@@ -86,7 +86,7 @@ One file of milestone G's part of [design 47](../47-delivery-from-commit-to-deli
|
||||
- §64 **The run on request.** The runner's verb `run` takes one or more members, each a module at a named commit, runs them
|
||||
through their pipelines and delivers nothing, replacing the checker's try (ADR 0666 §18). Its callers are the
|
||||
sessions, as the agents' bus identities the tool runner proves, and the operator, and nothing else, since a run of a
|
||||
group builds and publishes its packages' tagged versions (design 51). The runner says `run-started`, the indexer builds
|
||||
group builds every member and its dependents on the build capacity (§373). The runner says `run-started`, the indexer builds
|
||||
the run's candidate from it, and the candidate's composition step writes no want (ADR 0656 §9); the candidate is
|
||||
dropped on that run's `pipeline-ended`. A step that could not run ends `could not run`, never as passed. A
|
||||
composition step for a node that sleeps passes it with a warning (ADR 0593 §9).
|
||||
@@ -162,7 +162,8 @@ One file of milestone G's part of [design 47](../47-delivery-from-commit-to-deli
|
||||
its members, and a merge behind a pending revision, are governed by their own bounds (ADR 0666 §24). At its start the
|
||||
watchman seeds its open waits from the runner's `stands`, as it seeds `take-in-waits` from `indexer_pending`.
|
||||
- §76 **The runner's own health.** Its manifest declares its health check, run outside its process (ADR 0240): the runner
|
||||
answers `show`, and its durable consumers of `step-ended`, `take-in.taken`, `package-published` and `decided` are
|
||||
answers `show`, and its durable consumers of `step-ended`, `take-in.taken`, `package-published`, `toolchain-agreed`
|
||||
and `decided` are
|
||||
each less than five minutes behind; a failed check names which.
|
||||
- §77 **The runner waits for its view.** With no revision view it says so in `<module>_first_views` and raises `view-waits`
|
||||
after five minutes, as every part does (ADR 0656 §6).
|
||||
@@ -223,6 +224,18 @@ and an estimated 2 mesh-sdk publishes a day, each rebuilding about 120 artifacts
|
||||
| the runner | `step-log`: one entry per step's start and end, its output, its pipeline and the `kept` digests it wrote or carried, by name | old `streams` section | by its age, 100 days, ten days past the longest retention it ages (§330) | 128 MiB; about 3,600 entries a day of about 0.2 KiB is about 70 MiB at 100 days |
|
||||
| the runner | `step-outputs`: a lint or test step's output | old `objects` section | 7 days | 1 GiB; about 1,200 steps run a day (the rest carried) of about 50 KiB is about 420 MiB at 7 days |
|
||||
| the runner | `kept`: a package's passing result per level, by digest, with `last-read`, written by each carry that reads it | old `state` section | 30 days after `last-read` | 128 MiB; a publish changes the digest of about 1,000 importing packages at two levels, so about 4,000 entries a day of about 0.3 KiB, about 36 MiB at 30 days |
|
||||
| the indexer | `versions`: one key per module and version, its artifacts' digests, the source revision and its edge entries (§349, §374) | old `state` section | a module's newest 100 versions, never its highest of a `MAJOR.MINOR`; the indexer deletes the older at each release | 64 MiB; about 120 modules of 100 versions at about 3 KiB is about 35 MiB; at the cap it records no release and says `full`, as *A store filling is said before it is full* |
|
||||
| the indexer | `build-edges`: the newest build's edge entries per module and watched branch other than the first | old `state` section | replaced by the next build; deleted when the branch is unwatched | under 1 MiB |
|
||||
| the builder | `reserved`: one key per module and `MAJOR.MINOR` (§369) | old `state` section | until its `version-released`, a release of another `MAJOR.MINOR` of the module, or `builder_reserved_drop` | a few KiB; at the cap the builder reserves nothing and says why |
|
||||
| the assigner | `written`: the last source revision and end count per module and watched branch (§352) | old `state` section | until the branch is unwatched | a few KiB |
|
||||
| the indexer and the assigner | `inputs`: a `run` ask's input by write time and sha256 (§354) | old `state` section | until the ask's `step-ended`, at most a day | 64 MiB; an estimated 300 asks a day of under 100 KiB each is under 30 MiB; at the cap the asker refuses the ask loudly, naming the store |
|
||||
| the runner and the assigner | `findings` (§355), read by their own read tools alone; the keeper hears the findings as events (§383) | old `state` section | an entry deleted when its finding clears | a few KiB |
|
||||
| every observer (§387) | the stream `<module>-findings`: `finding-written`, `finding-cleared`, `findings-stated` (§383) | old `streams` section for a foundation part, the module's `streams` otherwise | 7 days, its oldest dropped when full; the next statement covers a lost one (§384) | 16 MiB; an estimate of a few hundred findings a day of about 1 KiB is under 2 MiB a week |
|
||||
| the condition keeper | `findings-views`: one key per observer and node, its last stated set, pending keys and open asks (§388) | the form of its `conditions` | deleted when the module leaves the catalog or the node (§365) | under 1 MiB; about 30 observers on four machines |
|
||||
| the watchman, the keeper | `machine-away`, `machine-back` (§389); `findings-asked` (§390) | the seats' definitions | 90 days; 7 days | 16 MiB each |
|
||||
| the runner | `aged`: three step-log sequences (§330) | old `state` section | never deleted | bytes |
|
||||
| the teller | `widens-said` (§335) | the template `state` | until the branch is unwatched | a few KiB; the template's |
|
||||
| each build module | `steps` (§326) | the template `state` | one key per artifact, dropped by `steps` with `drop` | under 1 MiB; the template's |
|
||||
| the indexer | `registrations` and its stream `registration-history` | old `state` and `streams` sections | the life of the mesh, never derived again | 64 MiB (*A module's registration*) |
|
||||
| the indexer | catalog graph revisions, per watched branch | objects in the old form (ADR 0619 §2) | while a record pins it or it is its branch's current | 512 MiB, as *Two graphs, one source of truth*; a second watched branch on a few modules adds a few MiB |
|
||||
| the gate | `source`: one key per watched branch | its old `state` section, as today | 64 revisions of each key; a branch's key deleted when `registration-changed` says the last registration watching it unwatched it (`unwatch`) | a few KiB |
|
||||
@@ -259,7 +272,11 @@ step keys and the builder's build log, against the checker's last week (test 99)
|
||||
from the next change on; mesh-delivery's `contracts` and `sdk` move under its `modules/` folder (ADR 0667 §3).
|
||||
- §89 **Readers first** (ADR 0667 §4): an edge of kind 4 each, which the delivery plan derives: the indexer's manifest
|
||||
validator for the seat definitions' new fields (`callers`, `acts`, `subject`, `keep`) before any definition using
|
||||
them; on each node the node-engine that reads `form` and `catch-up` before any manifest writing them.
|
||||
them; the manifest validator for the manifests' new words (`version`, §368; a `*` emitter in `consumes`, §386; the
|
||||
finding stream an observer declares, §383, §387) and the grants part that makes a `*` entry's durable consumers
|
||||
(§386), before the keeper's or any observer's manifest using them; on each node the node-engine that reads `form`
|
||||
and `catch-up` before any manifest writing them. The running checker's validator makes G's own check, so the reading
|
||||
of these words goes in the reader release of §340, whether or not that validator already takes one of them.
|
||||
- §90 **The stream maker first** (ADR 0667 §5): the grants part, which makes each kept seat stream and its durable
|
||||
consumers, before the parts that hear a kept stream.
|
||||
- §91 **The bus module first** (ADR 0667 §6): the bus module, with `<state>-objects`, the sent store and the grant of each
|
||||
|
||||
@@ -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.<node>.<module>` 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
|
||||
@@ -126,7 +126,8 @@ names go, since every new acting part needed code changes elsewhere (research 08
|
||||
- While the keeping node is away, or its sweep removed the build, the want waits, and the node-engine says in its
|
||||
have that it waits for that node or for a build no longer kept. A want that waits so for 60 minutes, building's
|
||||
default bound, is the watchman's finding `kept-build-waits`, naming the module, the node and the build node; the
|
||||
operator or the healers recover it by `builder_build_again`, which builds and keeps it again.
|
||||
operator or the healers recover it by `builder_build_again`, which builds and keeps it again; the finding clears when
|
||||
the node's have runs the want.
|
||||
- A node-engine of before G does not know `kept-artifact`: the holder's want on its node waits for its new
|
||||
node-engine (ADR 0667 §9). A new node-engine is itself fetched from the store; while the store is broken it waits,
|
||||
so on a node that has neither the store's holder's new build nor G's node-engine, the want waits and
|
||||
@@ -140,11 +141,6 @@ names go, since every new acting part needed code changes elsewhere (research 08
|
||||
is checked: test 60, and whole (build module, node-engine): a module claiming the seat but not its holder in the
|
||||
seat list is refused; bytes differing from the want's digest are not applied; a want waiting 60 minutes raises
|
||||
`kept-build-waits` and `builder_build_again` ends it.
|
||||
|
||||
This is the one artifact the mesh delivers from a build node instead of the store, and only for the holder of
|
||||
`oci-artifact-registry`; the design's choice under ADR 0656 §3 (a wait skips what the holder's own new version needs) and ADR
|
||||
0526 §2, whose build by a session's call it makes a step of the delivery instead of a hand act. How it is checked:
|
||||
test 60.
|
||||
- §272 **The check refuses a cycle among the waits within one step** (ADR 0656, which changes ADR 0603 §2's refusal of a
|
||||
cycle), counted beside the edges ADR 0614 §3 and §6 list; a cycle through an acting part's edges across two steps, or
|
||||
through a holder's own inputs, is none.
|
||||
@@ -173,6 +169,7 @@ names go, since every new acting part needed code changes elsewhere (research 08
|
||||
| granting | the grants part | `grants_waits` | `grants_release` |
|
||||
| composing | the assigner, holding a node's other wants until its new node-engine runs there (*Composing waits per node*) | `assigner_waits` | `assigner_release` |
|
||||
| checking | the check's first tier | `checker_first_tier` | its ask-again (*The check on the change's own acting parts*) |
|
||||
| delivery of a dependency (kinds 2, 4 and 6), from G's delivery | the assigner, holding a dependent's new version until `version-delivered` of its dependency's (§376) | `assigner_waits` | `assigner_release` (want it now), and `assigner_delivered_again` |
|
||||
| pipeline, from G's delivery | the runner, holding the pipelines its new version is to run until it runs healthy | `runner_waits` | `runner_release` (run them with the running runner) |
|
||||
|
||||
Each release writes the hand-act log of the seat `mesh-hand-acts`, with who released and why.
|
||||
@@ -200,7 +197,8 @@ names go, since every new acting part needed code changes elsewhere (research 08
|
||||
(graph): an acting part acting on itself, two acting parts acting on each other in different steps, and a cycle
|
||||
through a build module's edge each pass the cycle check, each new version first in its own step; a cycle among
|
||||
waits within one step is refused. Unit (assigner): the Approve ask of a change that adds an acting rule, and of one
|
||||
that widens one, names the rule. Live: a search of the delivery parts' code finds no other module's name.
|
||||
that widens one, names the rule. The code review reads that no delivery part's code names
|
||||
another module (§7).
|
||||
|
||||
## Nothing merges into a repository under check: removed
|
||||
|
||||
|
||||
@@ -0,0 +1,207 @@
|
||||
---
|
||||
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.<repository>.<number>`, 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.<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` and `toolchain-agreed` and serves
|
||||
`reserved` (*A publish rebuilds*, §369, §376). From G's answers (G-7), `mesh-catalog` also gains the verbs `versions`
|
||||
and `outdated` and the events `version-released` and `versions-filled`, `mesh-wants` the event `version-delivered`, and
|
||||
the seat `git` the verb `tag` (§349, §372, §375, §376, §370).
|
||||
|
||||
§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.<node>.<module>` 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.<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
|
||||
`<module>_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; the fixed branch,
|
||||
repository and module names G's subtasks remove (§7); 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.
|
||||
@@ -1,509 +0,0 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: G
|
||||
updated: 2026-11-10
|
||||
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 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
|
||||
|
||||
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.<repository>.<number>`, 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.<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.<node>.<module>` 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.<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
|
||||
`<module>_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 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
|
||||
§1, §4, ADR 0635 §4, ADR 0548 §5, ADR 0363 §2; design 27, *Which module answers*. The operator, 2026-11-10: a small
|
||||
choice within what a record decides is the design's own, written here with its reason and reviewed by the reviewers
|
||||
by architectural domain.*
|
||||
|
||||
§322 Milestone G's prepare and develop met these questions (issue 1966). Each line is the design's choice, with the
|
||||
record it follows from, and replaces the builder's own choice where one was made.
|
||||
|
||||
### The runner and its steps
|
||||
|
||||
- §323 **A step's build seat is read from the artifact's language.** The catalog graph entry names each artifact's
|
||||
`language`, as its manifest's artifact entry says it and as the indexer's language map matches today; the runner
|
||||
reads it from the catalog half of its revision view and asks lint and the test steps of the build seat whose
|
||||
definition's acting rule `build` has `on` naming that language. With no such seat, or no holder of it, the pipeline
|
||||
ends failed, naming the seat (ADR 0666 §18). Why: the language is already in the manifest and the catalog half is
|
||||
the runner's one view (ADR 0666 §24, ADR 0596). How it is checked: whole (runner), a Go and a TypeScript fixture
|
||||
module each ask their own build seat, and one with no holder ends failed naming the seat.
|
||||
- §324 **An acting rule's `on` may name an artifact kind.** Beside `every` and a language, `on` may be `kind: image`,
|
||||
matched against the manifest's artifact entry's kind; the seat `node-build-image`'s rule says `kind: image`. Why: an
|
||||
image has no language, and the rule's fields are this design's (*What ADR 0656 leaves to this design*). How it is
|
||||
checked: a unit row of the definition reader accepts `kind: image` and refuses another kind.
|
||||
- §325 **An approval never asked ends `not asked`.** When a `required` step failed before the `approval` step was asked,
|
||||
the `approval` step ends `not asked`, naming the failed step, never as passed; a `rerun` that passes the failed step
|
||||
asks it then, and the pipeline ends again: the runner says `pipeline-ended` once more for it, its end count one
|
||||
higher, which the assigner takes (*What holds a delivery*). Why: approval comes last (above),
|
||||
and every end a step can have is said as itself (ADR 0666 §10). How it is checked: whole (runner, assigner), a failed
|
||||
unit step leaves the approval `not asked`; its passing rerun asks it, and once approved the second `pipeline-ended`
|
||||
writes the want.
|
||||
- §326 **A build seat keeps its `steps` answer.** The build module keeps each artifact's detected steps in its state
|
||||
`steps`, from the template `state`, one key per artifact holding the answer for that artifact's newest build-input
|
||||
fingerprint, replaced when a newer fingerprint is detected and by `steps` with `again`; a key whose artifact no
|
||||
longer exists is dropped by `steps` with `drop`, on a person's word, written in the hand-act log. With one key per
|
||||
artifact (about 120) the state needs no aging and no read time. Why: ADR 0666 §25 asks a tool for "the steps
|
||||
detected for an artifact and detect again", which a reply computed anew each time would not need; a build module is
|
||||
no foundation part, so the template form (ADR 0666 §4). How it is checked: whole (Go build module), `steps` answers
|
||||
from the key, a newer fingerprint and `again` replace it, and `drop` removes one.
|
||||
- §327 **The step code lives in the domain SDK.** The step run and the fetch-and-release code the three build modules
|
||||
share move, in this milestone, into a build-step package of `mesh-delivery-sdk`, which the Go, TypeScript and image
|
||||
build modules import; none keeps a copy. Why: code shared between modules lives in an SDK, and the delivery
|
||||
domain's shared code is `mesh-delivery-sdk`'s (ADR 0635 §4); the copies were met in develop. How it is checked: a
|
||||
search of the three build modules finds no fetch, release or step-run function of their own.
|
||||
- §328 **Lint per language.** Go's lint step is the Go build module's linter with the fixed-names rule; TypeScript's is the
|
||||
type-check with the fixed-names rule; an image's lint is the fixed-names rule over its build files;
|
||||
an image has no unit or integration test step, so `steps` answers none for it and the seed has those `bypass`
|
||||
(*A module's registration*). Why: ADR 0666 §5 has the lint step refuse fixed names in every language, and §7 lets a
|
||||
build seat answer only the steps an artifact can run. How it is checked: whole (TypeScript and image build modules),
|
||||
a fixture naming a module in code fails lint.
|
||||
- §329 **What the fixed-names rule exempts.** It exempts a Go import path, a comment and a test file (`_test.go`,
|
||||
`*.test.ts`), never a struct tag or any other string of code. Why: none of the three is code logic (ADR 0666 §5),
|
||||
and a test fixture names modules. How it is checked: unit (lint rule), a name in a comment and in a test file
|
||||
passes, in a struct tag fails.
|
||||
- §330 **The runner's own kept data age by its own deletes, in the step log's order.** The runner deletes its own
|
||||
`pipelines` keys, `kept` entries and `step-outputs` objects by the retentions of *The runner's kept data*. It keeps,
|
||||
in its old `state` section `aged`, three step-log sequences, one per retention (7, 30 and 90 days), each the last
|
||||
entry it aged at that retention. At each step's end it reads the step log onward from each sequence, at most 20
|
||||
entries per sequence, while the entry is past that retention: at 7 days it deletes the entry's output and the
|
||||
pipeline it names unless that pipeline ended passed on a watched branch or is its branch's newest for its module; at
|
||||
30 days each `kept` digest the entry names whose `last-read` is past 30 days; at 90 days the passed pipeline the
|
||||
entry names, unless it is its branch's newest. It then moves the sequence; nothing is scanned whole. Each delete
|
||||
writes a line in the runner's journal naming the key or object and its retention. A foundation part's sent store
|
||||
(`sent-objects`) is aged the same way by its owner at each send, from the sequence of its own sends. Nothing waits on
|
||||
a timer, and nothing but the owner deletes. Why: an old section cannot declare an age, and deleting one's own entries
|
||||
is the owner's act, not the removal of a store ADR 0595 §4 holds to a person's word; §57's rule that only the drop
|
||||
tool removes an object holds for a template's `<state>-objects`, while the runner's `step-outputs` are its own old
|
||||
section's objects. How it is checked: whole (runner), an output 7 days old is gone after the next step's end, a
|
||||
passed pipeline stays to 90 days, and one step's end deletes at most 20 per sequence.
|
||||
- §331 **The kept event streams' caps, and when one is full.** On the seat `mesh-pipeline-runner`, each kept 90 days:
|
||||
`pipeline-started` 32 MiB, `pipeline-ended` 192 MiB, `group-ended` 64 MiB, `run-started` 16 MiB, `step-started`
|
||||
and `step-ended` 128 MiB each, `wait-held` and `wait-ended` 32 MiB each; the seat `git`'s `branch-moved` 64 MiB; each
|
||||
build seat's `step-ended` 128 MiB; `mesh-wants`'s `step-ended` 32 MiB; `mesh-builds`' `package-published` and
|
||||
`mesh-catalog`'s `registration-changed` 16 MiB each; all 90 days. Why: about 300 pipelines a day of about 6 steps
|
||||
(*The runner's kept data*) say about 1,800 step events a day of about 0.5 KiB, about 80 MiB in 90 days, and about 300
|
||||
pipeline ends of about 4 KiB, about 105 MiB, 55 % of its cap; a build seat runs about 1,200 steps a day, about 54
|
||||
MiB; publications and registration changes are a few a day; estimates, read from the fill tools once G runs. A kept
|
||||
seat stream at its cap drops its oldest message, as a stream with a cap does; the grants part, which makes the
|
||||
streams, says `filling` on its seat `mesh-grants` past 80 % and `room` below 70 %, which the watchman's
|
||||
`store-filling` raises and clears as for every store (*A store filling is said before it is full*). How it is
|
||||
checked: each seat definition's fixtures name each stream's `keep`; whole (grants part), a stream past 80 % says
|
||||
`filling`.
|
||||
- §332 **A group's end is said under the group.** `group-ended` is said on
|
||||
`mesh.seat.mesh-pipeline-runner.event.group-ended.<branch>.<group>`, with no module part, since a group spans
|
||||
modules; a session that merged a group's member waits on `group-ended.<branch>.<group>` of its group after its own
|
||||
`pipeline-started` (*What a session hears after its merge*). Why: every other runner event names one module
|
||||
(*Health and going back*). How it is checked: the seat's
|
||||
fixtures.
|
||||
- §333 **The runner hears the indexer's own event.** The runner's manifest `consumes` the indexer's own event
|
||||
`take-in.taken` (ADR 0666 §13), which ADR 0596 §1 lets any module subscribe to; the indexer's name stands in that
|
||||
manifest only, never in the runner's code. Why: ADR 0666 §13, in force, names that event. How it is checked: a search
|
||||
of the runner's code finds no module name (lint).
|
||||
- §334 **A publication's pipelines and their key.** `package-published` carries the package's artifact reference
|
||||
(`<module>:<artifact>`, from the catalog entry), its version and digest, the watched branch and the source revision
|
||||
its build was made from. The runner reads the dependents from that revision's catalog graph, the artifacts with a
|
||||
kind-1 edge to the package, and starts each one's pipeline keyed by that branch, that source revision and the
|
||||
dependent module, the version in the pipeline's state; a `take-in.taken` of the same revision and module is the
|
||||
same pipeline (*A second start writes nothing*). Why: a pipeline's key is branch, source revision and module (above),
|
||||
and the publication is made from a revision of a watched branch (ADR 0666 §15). How it is checked: whole (builder,
|
||||
runner), a publish starts one pipeline per dependent, keyed by the publishing revision.
|
||||
- §335 **What the teller says of a widening.** Each entry of `widens` names what widens (`acting-rule`, `grant`,
|
||||
`credential` or `serving-part`), its name, the module and the commit. The teller says one message per
|
||||
`pipeline-ended` that carries any, on every channel, once per module, watched branch and commit: it keeps in its
|
||||
state `widens-said`, from the template `state`, one key per module and watched branch holding the last commit it
|
||||
said, replaced by the next and deleted when `registration-changed` says the branch is no longer watched; its tool
|
||||
`teller_widens_said` reads it. Why: ADR 0666 §23
|
||||
says a widening in the pipeline's end, and the teller passes it on (*Who may say what*). How it is checked: whole
|
||||
(teller), a `pipeline-ended` said twice with the same `widens` gives one message.
|
||||
|
||||
### Callers
|
||||
|
||||
- §336 **The forms of `callers`.** A verb's or an accepted kind's `callers` is a list whose entries are: a holder role (a
|
||||
seat's name), a module, `operator`, `healers`, `persons` (any person the tool runner proves), `sessions` (an agent
|
||||
session the tool runner proves), `invokers` (every module whose manifest declares the verb in `invokes`), and
|
||||
`holder:<seat>@same-node` (the holder of that seat on the node of the verb's holder). A definition whose `callers`
|
||||
today is text is given a list in this milestone: "any caller whose role grants it" becomes `invokers`, "a person"
|
||||
`persons`, and every other text the names the design gives that verb. Why: ADR 0666 §20 makes the definition the
|
||||
grants part's one source of caller limits, in a form it reads. How it is checked: unit (definition reader), each
|
||||
form accepted and any other entry refused; the grants part's table test grants each form.
|
||||
- §337 **The bus module's restore points.** The verbs the holder of `node-backup` on the bus module's node calls to take
|
||||
and restore a module's kept data on the bus name `holder:node-backup@same-node`. Why: only that holder takes them
|
||||
(*A backup before the apply: kept data on the bus*). How it is checked: a call from another node's `node-backup`
|
||||
holder is refused by the bus.
|
||||
- §338 **Callers on accepted kinds.** An accepted kind of a work queue carries `callers` as a verb does, and the grants part
|
||||
grants publish on its subject to them alone: the build seats' `step` the runner; `run` the runner, the indexer and
|
||||
the assigner, and the checker until its entry is removed with its buckets and bus account (ADR 0667 §12); `mesh-wants`'s
|
||||
`step` the runner. Verbs: `steps` the runner and the indexer (its seed); `drop` the runner and the builder; both
|
||||
`input` verbs (`mesh-catalog`'s and `mesh-wants`') the holders of the build seats. Why: a step's result is taken only
|
||||
from its seat holder (ADR 0666 §21), so the ask side is limited too. How it is checked: a `step` published by another
|
||||
account is refused by the bus.
|
||||
- §339 **The contract generator reads `callers` and makes nothing of it.** The generated contracts carry no caller check;
|
||||
the grants part reads `callers` from the definition, and the generator refuses a definition whose entry is no form
|
||||
above. Why: one source of caller limits (ADR 0666 §20). How it is checked: the generator's test refuses an unknown
|
||||
entry.
|
||||
- §340 **The reader release first.** mesh-sdk's seat-definition reader released before G's check reads `callers` as text
|
||||
or as a list; G's own reader refuses text. Why: readers first (ADR 0667 §4), and every definition is a list from G; it is merged ahead of G's check because the
|
||||
running checker, which makes G's own check (ADR 0667 §2), must read G's definitions, the operator's choice of a
|
||||
reader first (2026-11-09).
|
||||
How it is checked: unit rows for both forms in the release, and for the refusal in G.
|
||||
- §341 **TypeScript contracts as JavaScript.** The generator emits each seat's TypeScript contract as `index.js` with its
|
||||
`index.d.ts`, so a TypeScript module imports it with no build step of its own. Why: a seat's contract is generated
|
||||
from its definition (ADR 0625 §1), and a gap of the build system is built in it. How it is checked: a TypeScript
|
||||
module builds against a generated contract with no `tsc` of the contract.
|
||||
|
||||
### The catalog, the builder and the assigner
|
||||
|
||||
- §342 **A module not watched on a branch.** A watched branch's catalog graph takes each module not watched on that branch
|
||||
from the registration's first watched branch. `register` names a module's watched branches; with none named it takes
|
||||
the repository's default branch, read through the seat `git`. Why: a placement's default is the registration's first
|
||||
branch (ADR 0666 §6). How it is checked: whole (indexer), a `beta` revision holds a `main`-only module at `main`'s
|
||||
head.
|
||||
- §343 **Branch names the indexer's keys use.** `register` and `watch` refuse a watched branch named `candidate` or
|
||||
`entry`, naming why, since the catalog keeps its revisions under `<branch>.<revision>` beside those two key forms.
|
||||
How it is checked: whole (indexer), each is refused.
|
||||
- §344 **The bus module plans a sent store from what the catalog already says.** It plans `<module>_sent-objects` for a
|
||||
module of the new form whose catalog graph entry claims a seat whose definition has a verb or an event, or declares
|
||||
an event of its own, read from the catalog half of its revision view and the seat list; the indexer's event carries
|
||||
no field `sends`. When a seat's definition gains its first verb or event later, the bus module plans the store for
|
||||
its holders on the seat list's change. Why: no manifest field (*Any size*), and the catalog half is every part's view
|
||||
(ADR 0656 §6). How it is checked: whole (bus module), a module claiming a seat with a verb gets a sent store, one with
|
||||
neither gets none, and a definition gaining a verb gives its holder one.
|
||||
- §345 **A large value reaches the tool runner in chunks.** A bundle's put of a value over the bus's per-message limit is
|
||||
sent to the tool runner as a put session on the bundle's call subject, named by the call's id, in chunks under that
|
||||
limit, in order, each answered by the tool runner before the next is sent, and written as one object through the
|
||||
object store's own chunking; a put not sealed within the call's bound is dropped by the tool runner and its call
|
||||
fails, naming the object. No value is split over objects. Only modules that import the object store package are
|
||||
rebuilt for it. Why: one object per value (ADR 0666 §16), through the tool runner (ADR 0595 §9). How it is checked:
|
||||
whole (mesh-sdk), a value of a hundred times the limit is read back whole, and a put stopped half way fails naming
|
||||
the object and leaves none.
|
||||
- §346 **One object store package.** The assigner's and the indexer's object store code is mesh-sdk's small object store
|
||||
package, with no copy in either. Why: ADR 0595 §9. How it is checked: a search finds no second copy.
|
||||
- §347 **Reading sent objects is a bus state call.** mesh-sdk lists the call that reads a sent object under its existing
|
||||
bus state capability. Why: ADR 0595 §9 puts the calls in that package. How it is checked: the package's table test.
|
||||
- §348 **The builder reads the catalog through its seat.** The builder reads the registrations' watched branches through
|
||||
`mesh-catalog`'s `registrations` and `registration-changed`, the released versions it numbers from through
|
||||
`versions` and `version-released`, keeping no list of versions of its own, and a build seat's holder from the seat list; the
|
||||
manifests, the packages, each package's name in its ecosystem (the Go module path, the npm name, which the catalog
|
||||
graph entry's packages carry) and a run's candidate from the catalog half of its revision view, never the indexer's
|
||||
state. With no holder of a build seat, a build ends `could not run`, naming the seat, and is asked again on the seat
|
||||
list's change. Why: ADR 0596 §2. How it is checked: the builder's account holds no grant to the indexer's state.
|
||||
- §349 **The catalog holds released versions only, and says each.** The indexer keeps, for the seat `mesh-catalog`,
|
||||
each module's released versions in its old `state` section `versions`, one key per module and `MAJOR.MINOR` holding
|
||||
its released patches with each artifact's digest and the source revision built (issue 1961's catalog of versions).
|
||||
It hears every artifact's `package-published` (packages, images, bundles and archives alike) and records a version
|
||||
as released once every artifact the module's catalog entry names is published at it, then says `version-released`
|
||||
(the module, the version, its artifacts, the source revision) on `mesh.seat.mesh-catalog.event.version-released`,
|
||||
kept 90 days at 16 MiB; the verb `versions` answers a module's released versions, its callers the builder and any
|
||||
person or session. A reserved version is not in it. The builder's `version.numbered` is no longer said or heard.
|
||||
Why: the operator, 2026-11-10 about 21:40 CET (gaps items 23 and 43). How it is checked: whole (indexer), a version
|
||||
with one of two artifacts published is not released, and with both is, said once.
|
||||
- §350 **A superseded build's drop is a kept call.** The runner ends a superseded build's step `superseded` at once, and
|
||||
asks the build seat's `drop` as a kept call (ADR 0668 §1, §2), so it is asked again through every transport fault
|
||||
and said `call-unanswered` after five minutes in the runner's findings. How it is checked: whole (runner), a drop
|
||||
unanswered is asked again, and raises `call-unanswered` after five minutes.
|
||||
- §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
|
||||
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
|
||||
`assigner_written` reads it. How it is checked: whole (assigner), an older revision ending after a newer one writes
|
||||
nothing, and a later end of the same revision writes.
|
||||
- §353 **The assigner follows the registrations.** `mesh-delivery-contracts`' client `meshcatalogclient` carries a typed
|
||||
follower of `registrations`, a first view then `registration-changed`, built on `go/views`; the assigner and the
|
||||
forge module's merge switch on its first registrations (ADR 0667 §10). How it is checked: whole (assigner), it keeps
|
||||
the trunk-only want until the first `registration-changed`.
|
||||
- §354 **The assigner's composition step runs the composer in the sandbox.** It asks the seat `node-build-go` the ask `run`
|
||||
(*What ADR 0656 leaves to this design*), its step keys under `assigner.`, and serves the ask's input by its seat
|
||||
`mesh-wants`' verb `input`, as the checker's seat does today; the indexer does the same for its validation by
|
||||
`mesh-catalog`'s `input`. Both are foundation parts, so each keeps its inputs in an old `state` section `inputs`, one
|
||||
key per input named by its write time and its sha256, deleted when the build seat's `step-ended` of that ask is heard
|
||||
or a day after its write, whichever is first, the day judged at each new ask over at most 20 of the oldest keys;
|
||||
`assigner_inputs` and `indexer_inputs` read them. Both verbs' callers are the holders of the build seats. The Go build module reads no revision verb. Why: the
|
||||
composition step runs on parts built from the heads, in the sandbox (ADR 0666 §17). How it is checked: whole
|
||||
(assigner), a composition step's `run` is answered and its input read by digest.
|
||||
- §355 **The assigner says an unanswered `manifest-reads`.** The assigner, the one caller of the node-engine's
|
||||
`manifest-reads` from G, writes `call-unanswered` into its own findings state, and the condition keeper's reads gain
|
||||
it in the same change (ADR 0668 §3). The assigner and the runner each declare that state, `findings`, in their old
|
||||
`state` section, both being foundation parts. How it is checked: whole (assigner, runner, condition keeper), a node-engine
|
||||
that never answers raises `call-unanswered` after five minutes, and the keeper raises it.
|
||||
- §356 **Two acting parts in different steps make no cycle.** The assigner's cycle check counts waits within one step only
|
||||
(*A wait holds only within its step*). How it is checked: the unit rows there.
|
||||
- §357 **Which provider a requirement points to.** In the assignment graph, by design 27's order: the named seat's
|
||||
holder, a pin, the provider on the consumer's node, the only provider; otherwise the entry is held, naming the
|
||||
candidates, and nothing is guessed. A contribution edge runs from a consumer's entry to the provider its requirement
|
||||
resolves to, wherever that requirement carries values the consumer contributes. How it is checked: unit
|
||||
(assignment graph), each step of the order and a hold.
|
||||
- §358 **The catalog's shared view takes a branch.** The client's view of the catalog half is per watched branch, named by
|
||||
its caller. How it is checked: unit (client), two branches give two views.
|
||||
- §359 **`difference` names its revisions.** `difference` with none of `from`, `to` and `group` is refused, naming the
|
||||
missing argument. How it is checked: a unit row.
|
||||
- §360 **An approved ask binds the placement.** What an approved ask binds to includes the placement's watched branch and
|
||||
its `build`, beside the fingerprint. How it is checked: whole (assigner), a placement changed after the Approve asks
|
||||
again.
|
||||
- §361 **A placement's `build` is a held put.** A placement's `build` is written as a held put of that build, released when
|
||||
the placement drops it; a put a person wrote is never released by a placement change. How it is checked: whole
|
||||
(assigner), a placement's `build` holds that build on its nodes, removing it releases the put, and a person's put
|
||||
stays through a placement change.
|
||||
- §362 **The indexer's first-start catch-up runs apart from its source handler.** At its first start the indexer takes in
|
||||
the heads the gate's source names by its catch-up path before it starts its handler of `source-moved`. How it is
|
||||
checked: whole (indexer), a `source-moved` said during the catch-up is applied after it, once.
|
||||
- §363 **A stale ask is dropped, backups included.** The assigner drops an ask it raised once the want it asked for is
|
||||
replaced, a backup ask among them (built in mesh-delivery #200). Why: ADR 0596 and ADR 0668 §2. How it is checked:
|
||||
whole (assigner), a backup ask whose want was replaced is dropped and not asked again.
|
||||
|
||||
### The condition keeper and the node-engine
|
||||
|
||||
- §364 **The node-engine claims its seat.** The node-engine's manifest claims the node seat `node-engine` (ADR 0563), and
|
||||
the indexer and the node-engine's own guard read its holder from the seat list, keeping no module name. How it is
|
||||
checked: lint finds no module name in either.
|
||||
- §365 **The condition keeper reads its sources from the catalog.** The catalog graph entry carries each kept data a
|
||||
manifest declares (its name and its section or template); the keeper takes a first view of the catalog half and
|
||||
reads a module's `findings` wherever its entry declares a state `findings`, and the node-engine's holder from the
|
||||
seat list. It joins the readers of *Every other reader of which modules exist*, reading every watched branch's newest catalog
|
||||
revision, so a module watched on any branch is a source. A condition of a module that is in no branch's revision is
|
||||
cleared, said with the reason `module left the catalog`. Before its first view the keeper keeps raising from the
|
||||
sources it held, and says `view-waits` after five minutes (*A part with no view says it waits*). Why: no fixed names (ADR 0666 §5),
|
||||
and the keeper reads findings (ADR 0564 §2). How it is checked: whole (keeper), a fixture module declaring `findings`
|
||||
is read with no code change.
|
||||
|
||||
### From round 1 of the review by architectural domain (2026-11-10)
|
||||
|
||||
- §366 **The runner's stores say their fill.** *A store filling is said before it is full* holds for the runner's
|
||||
`pipelines`, `step-outputs` and `kept`: it says their fill in `show` and `kept`, `filling` past 80 % and `room` below
|
||||
70 % on its seat, and `full` at the cap, when it starts no new pipeline, says each start it refused, and takes them
|
||||
up on `room`; nothing is dropped to make room. Why: the runner joins the stores of *Two graphs, one source of truth*
|
||||
(ADR 0666 §24, ADR 0564 §2). How it is checked: whole (runner), a full `pipelines` refuses a start, said, and
|
||||
`room` starts it.
|
||||
- §367 **A forge bridge message is read again on a transport fault.** The indexer reads a message of the forge
|
||||
bridge's stream again when reading it met a transport fault, as main's `UnreadAgain` does (ADR 0668 §1, §4): the
|
||||
message is left unacknowledged and its read asked again on the bridge's next answer, while a message the bridge
|
||||
itself answered as lost stays lost, said in the indexer's journal and in `indexer_pending`. G's own change for it
|
||||
(`LostAgain`, commit 106fc16b) is not built. Why: one rule for kept calls (ADR 0668), already on main. How it is
|
||||
checked: the indexer's take-in table, a transport fault reads the message again and a lost answer does not.
|
||||
- §368 **A manifest says its `MAJOR.MINOR`.** Each module's manifest names `version`, two numbers `MAJOR.MINOR`; the
|
||||
manifest validator refuses any other form, a pre-release or custom suffix (`beta`, `alpha`) among them: no custom
|
||||
version exists for now. A manifest without it is refused once G's reader runs (ADR 0667 §4: the reader is delivered
|
||||
first). Why: the operator, 2026-11-10 about 21:40 CET. How it is checked: unit (manifest validator), `1.4` accepted,
|
||||
`1.4-beta` and `1.4.2` refused.
|
||||
- §369 **The reservation is one key per module and `MAJOR.MINOR`.** The builder, a foundation part, keeps in its old
|
||||
`state` section `reserved` one key per module and `MAJOR.MINOR`, the version its build reserved, written by
|
||||
compare-and-set at the build's start; a newer build of the module takes the next after the higher of the highest
|
||||
released and the one reserved, so two builds never share a version, and a superseded build's version is never
|
||||
released, leaving a gap in the patches. The builder deletes the key when the catalog says `version-released` for it;
|
||||
`builder_reserved` reads the keys. This is no list of released versions: numbering reads those only from the
|
||||
catalog. Why: the operator, 2026-11-10 (a version reserved when the build starts); the key and the gap are the
|
||||
design's choice. How it is checked: whole (builder), two builds close together reserve two versions, and the key
|
||||
goes on `version-released`.
|
||||
- §370 **The version reaches every artifact's build.** The build seat's ask carries the version, and the build module
|
||||
passes it to the artifact's build as the build argument `MESH_VERSION`: a Go package is tagged `vMAJOR.MINOR.PATCH`,
|
||||
an npm package's version is it, an image carries it as its tag and label, and a program reads it as its own version.
|
||||
A Go package's version is its tag: this departs from ADR 0573 §2, which has a Go package's version be its trunk
|
||||
commit, by the operator's choice of 2026-11-10, and a later research brings that record in line. How it is checked:
|
||||
whole (Go and TypeScript build modules), a built package and program carry the reserved version.
|
||||
- §371 **Only the first watched branch releases.** Only a build of the registration's first watched branch reserves and
|
||||
releases a version; a build of another watched branch reserves none, publishes no version and is delivered by its
|
||||
build, its fingerprint, as every want names one. Why: the operator, 2026-11-10. How it is checked: whole (builder),
|
||||
a `beta` build reserves nothing and is delivered.
|
||||
@@ -0,0 +1,516 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: G
|
||||
updated: 2026-11-11
|
||||
decisions:
|
||||
- "ADR 0668"
|
||||
- "ADR 0667"
|
||||
- "ADR 0666"
|
||||
- "ADR 0656"
|
||||
- "ADR 0636"
|
||||
- "ADR 0635"
|
||||
- "ADR 0625"
|
||||
- "ADR 0619"
|
||||
- "ADR 0603"
|
||||
- "ADR 0596"
|
||||
- "ADR 0595"
|
||||
- "ADR 0584"
|
||||
- "ADR 0573"
|
||||
- "ADR 0564"
|
||||
- "ADR 0563"
|
||||
- "ADR 0548"
|
||||
- "ADR 0363"
|
||||
- "ADR 0289"
|
||||
- "ADR 0253"
|
||||
---
|
||||
|
||||
# 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".
|
||||
|
||||
## 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
|
||||
§1, §4, ADR 0635 §4, ADR 0548 §5, ADR 0363 §2; design 27, *Which module answers*. The operator, 2026-11-10: a small
|
||||
choice within what a record decides is the design's own, written here with its reason and reviewed by the reviewers
|
||||
by architectural domain.*
|
||||
|
||||
§322 Milestone G's prepare and develop met these questions (issue 1966). Each line is the design's choice, with the
|
||||
record it follows from, and replaces the builder's own choice where one was made.
|
||||
|
||||
### The runner and its steps
|
||||
|
||||
- §323 **A step's build seat is read from the artifact's language.** The catalog graph entry names each artifact's
|
||||
`language`, as its manifest's artifact entry says it and as the indexer's language map matches today; the runner
|
||||
reads it from the catalog half of its revision view and asks lint and the test steps of the build seat whose
|
||||
definition's acting rule `build` has `on` naming that language. With no such seat, or no holder of it, the pipeline
|
||||
ends failed, naming the seat (ADR 0666 §18). Why: the language is already in the manifest and the catalog half is
|
||||
the runner's one view (ADR 0666 §24, ADR 0596). How it is checked: whole (runner), a Go and a TypeScript fixture
|
||||
module each ask their own build seat, and one with no holder ends failed naming the seat.
|
||||
- §324 **An acting rule's `on` may name an artifact kind.** Beside `every` and a language, `on` may be `kind: image`,
|
||||
matched against the manifest's artifact entry's kind; the seat `node-build-image`'s rule says `kind: image`. Why: an
|
||||
image has no language, and the rule's fields are this design's (*What ADR 0656 leaves to this design*). How it is
|
||||
checked: a unit row of the definition reader accepts `kind: image` and refuses another kind.
|
||||
- §325 **An approval never asked ends `not asked`.** When a `required` step failed before the `approval` step was asked,
|
||||
the `approval` step ends `not asked`, naming the failed step, never as passed; a `rerun` that passes the failed step
|
||||
asks it then, and the pipeline ends again: the runner says `pipeline-ended` once more for it, its end count one
|
||||
higher, which the assigner takes (*What holds a delivery*). Why: approval comes last (above),
|
||||
and every end a step can have is said as itself (ADR 0666 §10). How it is checked: whole (runner, assigner), a failed
|
||||
unit step leaves the approval `not asked`; its passing rerun asks it, and once approved the second `pipeline-ended`
|
||||
writes the want.
|
||||
- §326 **A build seat keeps its `steps` answer.** The build module keeps each artifact's detected steps in its state
|
||||
`steps`, from the template `state`, one key per artifact holding the answer for that artifact's newest build-input
|
||||
fingerprint, replaced when a newer fingerprint is detected and by `steps` with `again`; a key whose artifact no
|
||||
longer exists is dropped by `steps` with `drop`, on a person's word, written in the hand-act log. With one key per
|
||||
artifact (about 120) the state needs no aging and no read time. Why: ADR 0666 §25 asks a tool for "the steps
|
||||
detected for an artifact and detect again", which a reply computed anew each time would not need; a build module is
|
||||
no foundation part, so the template form (ADR 0666 §4). How it is checked: whole (Go build module), `steps` answers
|
||||
from the key, a newer fingerprint and `again` replace it, and `drop` removes one.
|
||||
- §327 **The step code lives in the domain SDK.** The step run and the fetch-and-release code the three build modules
|
||||
share move, in this milestone, into a build-step package of `mesh-delivery-sdk`, which the Go, TypeScript and image
|
||||
build modules import; none keeps a copy. Why: code shared between modules lives in an SDK, and the delivery
|
||||
domain's shared code is `mesh-delivery-sdk`'s (ADR 0635 §4); the copies were met in develop. How it is checked: a
|
||||
search of the three build modules finds no fetch, release or step-run function of their own.
|
||||
- §328 **Lint per language.** Go's lint step is the Go build module's linter; TypeScript's is the type-check; an image
|
||||
has no lint, unit or integration test step, so `steps` answers none for it and the seed has those `bypass` (*A
|
||||
module's registration*). No lint step scans for module, branch or repository names (§7). Why: ADR 0666 §7 lets a
|
||||
build seat answer only the steps an artifact can run; the scan's removal is the operator, 2026-11-11 about 00:05 CET. How it is checked: whole
|
||||
(TypeScript and image build modules), `steps` answers the type-check for a TypeScript artifact and nothing for an
|
||||
image.
|
||||
- §329 **Withdrawn.** It named what the fixed-names scan exempted; the scan goes (§7, the operator, 2026-11-11 about 00:05 CET).
|
||||
- §330 **The runner's own kept data age by its own deletes, in the step log's order.** The runner deletes its own
|
||||
`pipelines` keys, `kept` entries and `step-outputs` objects by the retentions of *The runner's kept data*. It keeps,
|
||||
in its old `state` section `aged`, three step-log sequences, one per retention (7, 30 and 90 days), each the last
|
||||
entry it aged at that retention. At each step's end it reads the step log onward from each sequence, at most 20
|
||||
entries per sequence, while the entry is past that retention: at 7 days it deletes the entry's output and the
|
||||
pipeline it names unless that pipeline ended passed on a watched branch or is its branch's newest for its module; at
|
||||
30 days each `kept` digest the entry names whose `last-read` is past 30 days; at 90 days the passed pipeline the
|
||||
entry names, unless it is its branch's newest. It then moves the sequence; nothing is scanned whole. Each delete
|
||||
writes a line in the runner's journal naming the key or object and its retention. A foundation part's sent store
|
||||
(`sent-objects`) is aged the same way by its owner at each send, from the sequence of its own sends. Nothing waits on
|
||||
a timer, and nothing but the owner deletes. Why: an old section cannot declare an age, and deleting one's own entries
|
||||
is the owner's act, not the removal of a store ADR 0595 §4 holds to a person's word; §57's rule that only the drop
|
||||
tool removes an object holds for a template's `<state>-objects`, while the runner's `step-outputs` are its own old
|
||||
section's objects. How it is checked: whole (runner), an output 7 days old is gone after the next step's end, a
|
||||
passed pipeline stays to 90 days, and one step's end deletes at most 20 per sequence.
|
||||
- §331 **The kept event streams' caps, and when one is full.** On the seat `mesh-pipeline-runner`, each kept 90 days:
|
||||
`pipeline-started` 32 MiB, `pipeline-ended` 192 MiB, `group-ended` 64 MiB, `run-started` 16 MiB, `step-started`
|
||||
and `step-ended` 128 MiB each, `wait-held` and `wait-ended` 32 MiB each; the seat `git`'s `branch-moved` 64 MiB; each
|
||||
build seat's `step-ended` 128 MiB; `mesh-wants`'s `step-ended` 32 MiB; `mesh-builds`' `package-published` and
|
||||
`mesh-catalog`'s `registration-changed` 16 MiB each; `package-published` 128 MiB; `version-released` 128 MiB,
|
||||
`version-delivered` 64 MiB, `toolchain-agreed` 16 MiB, and `versions-filled` 1 MiB with no age limit; all others
|
||||
90 days. At about 300 releases a day (a mesh-sdk publish rebuilding about 120 modules), `package-published` of about
|
||||
two artifacts each and `version-released` each say about 0.6 MiB a day, about 54 MiB in 90 days, and
|
||||
`version-delivered` about 27 MiB. Why: about 300 pipelines a day of about 6 steps
|
||||
(*The runner's kept data*) say about 1,800 step events a day of about 0.5 KiB, about 80 MiB in 90 days, and about 300
|
||||
pipeline ends of about 4 KiB, about 105 MiB, 55 % of its cap; a build seat runs about 1,200 steps a day, about 54
|
||||
MiB; registration changes are a few a day; estimates, read from the fill tools once G runs. A kept
|
||||
seat stream at its cap drops its oldest message, as a stream with a cap does; the grants part, which makes the
|
||||
streams, says `filling` on its seat `mesh-grants` past 80 % and `room` below 70 %, which the watchman's
|
||||
`store-filling` raises and clears as for every store (*A store filling is said before it is full*). How it is
|
||||
checked: each seat definition's fixtures name each stream's `keep`; whole (grants part), a stream past 80 % says
|
||||
`filling`.
|
||||
- §332 **A group's end is said under the group.** `group-ended` is said on
|
||||
`mesh.seat.mesh-pipeline-runner.event.group-ended.<branch>.<group>`, with no module part, since a group spans
|
||||
modules; a session that merged a group's member waits on `group-ended.<branch>.<group>` of its group after its own
|
||||
`pipeline-started` (*What a session hears after its merge*). Why: every other runner event names one module
|
||||
(*Health and going back*). How it is checked: the seat's
|
||||
fixtures.
|
||||
- §333 **The runner hears the indexer's own event.** The runner's manifest `consumes` the indexer's own event
|
||||
`take-in.taken` (ADR 0666 §13), which ADR 0596 §1 lets any module subscribe to; the indexer's name stands in that
|
||||
manifest only, never in the runner's code. Why: ADR 0666 §13, in force, names that event. How it is checked: the code review
|
||||
reads that no module name stands in the runner's code (§7).
|
||||
- §334 **A publication's pipelines and their key.** `package-published` carries the package's artifact reference
|
||||
(`<module>:<artifact>`, from the catalog entry), its version and digest, the watched branch and the source revision
|
||||
its build was made from. The runner asks `outdated` for that package on that branch and starts a pipeline for each
|
||||
dependent `outdated` names behind (§53), keyed by that branch, that source revision and the dependent module, the version in the pipeline's state; a `take-in.taken` of the same revision and module is the
|
||||
same pipeline (*A second start writes nothing*). A pipeline the runner starts from `outdated` (its start, §375, or
|
||||
`runner_catch_up`) is keyed by the dependency's watched branch, the dependency's source revision `outdated` names, and
|
||||
the dependent module, so it is the same pipeline the event would have started. Why: a pipeline's key is branch, source revision and module (above),
|
||||
and the publication is made from a revision of a watched branch (ADR 0666 §15). How it is checked: whole (builder,
|
||||
runner), a publish starts one pipeline per dependent, keyed by the publishing revision.
|
||||
- §335 **What the teller says of a widening.** Each entry of `widens` names what widens (`acting-rule`, `grant`,
|
||||
`credential` or `serving-part`), its name, the module and the commit. The teller says one message per
|
||||
`pipeline-ended` that carries any, on every channel, once per module, watched branch and commit: it keeps in its
|
||||
state `widens-said`, from the template `state`, one key per module and watched branch holding the last commit it
|
||||
said, replaced by the next and deleted when `registration-changed` says the branch is no longer watched; its tool
|
||||
`teller_widens_said` reads it. Why: ADR 0666 §23
|
||||
says a widening in the pipeline's end, and the teller passes it on (*Who may say what*). How it is checked: whole
|
||||
(teller), a `pipeline-ended` said twice with the same `widens` gives one message.
|
||||
|
||||
### Callers
|
||||
|
||||
- §336 **The forms of `callers`.** A verb's or an accepted kind's `callers` is a list whose entries are: a holder role (a
|
||||
seat's name), a module, `operator`, `healers`, `persons` (any person the tool runner proves), `sessions` (an agent
|
||||
session the tool runner proves), `invokers` (every module whose manifest declares the verb in `invokes`), and
|
||||
`holder:<seat>@same-node` (the holder of that seat on the node of the verb's holder). A definition whose `callers`
|
||||
today is text is given a list in this milestone: "any caller whose role grants it" becomes `invokers`, "a person"
|
||||
`persons`, and every other text the names the design gives that verb. Why: ADR 0666 §20 makes the definition the
|
||||
grants part's one source of caller limits, in a form it reads; `invokers`, which ADR 0666 §20's list does not name,
|
||||
is the operator's choice for the verbs whose text said "any caller whose role grants it" (Telegram, 2026-11-11 02:13
|
||||
CET: "Any declaring module"), and by the same answer, that a verb open today stays open to any module declaring it,
|
||||
for the fifteen verbs of the Connectivity domain's seats that name no `callers` on main, which §68 would otherwise
|
||||
close to their holders and the operator: `node-hostname`'s `entries`, `add` and `remove`;
|
||||
`node-intrusion-prevention`'s `status`, `banned`, `ban` and `unban`; `node-packet-filter`'s `rules`, `reload` and
|
||||
`remove`; `node-resolver`'s `routes`, `route` and `unroute`; `node-uplink`'s `resolvers` and `links`. Each of their
|
||||
definitions in `mesh-connectivity-contracts` names `invokers`, `persons` and `sessions` in this milestone, since
|
||||
sessions and persons call them today through the mesh MCP server. How it is checked: unit (definition reader), each
|
||||
form accepted and any other entry refused; the grants part's table test grants each form.
|
||||
- §337 **The bus module's restore points.** The verbs the holder of `node-backup` on the bus module's node calls to take
|
||||
and restore a module's kept data on the bus name `holder:node-backup@same-node`. Why: only that holder takes them
|
||||
(*A backup before the apply: kept data on the bus*). How it is checked: a call from another node's `node-backup`
|
||||
holder is refused by the bus.
|
||||
- §338 **Callers on accepted kinds.** An accepted kind of a work queue carries `callers` as a verb does, and the grants part
|
||||
grants publish on its subject to them alone: the build seats' `step` the runner; `run` the runner, the indexer and
|
||||
the assigner, and the checker until its entry is removed with its buckets and bus account (ADR 0667 §12); `mesh-wants`'s
|
||||
`step` the runner. Verbs: `steps` the runner and the indexer (its seed); `drop` the runner and the builder; both
|
||||
`input` verbs (`mesh-catalog`'s and `mesh-wants`') the holders of the build seats. Why: a step's result is taken only
|
||||
from its seat holder (ADR 0666 §21), so the ask side is limited too. How it is checked: a `step` published by another
|
||||
account is refused by the bus.
|
||||
- §339 **The contract generator reads `callers` and makes nothing of it.** The generated contracts carry no caller check;
|
||||
the grants part reads `callers` from the definition, and the generator refuses a definition whose entry is no form
|
||||
above. Why: one source of caller limits (ADR 0666 §20). How it is checked: the generator's test refuses an unknown
|
||||
entry.
|
||||
- §340 **The reader release first.** mesh-sdk's seat-definition reader released before G's check reads `callers` as text
|
||||
or as a list; G's own reader refuses text. The same release carries mesh-sdk's manifest reader of the new words of
|
||||
§89 (`version`, a `*` emitter in `consumes`, an observer's finding stream), which the running checker's validator
|
||||
reads before G's manifests use them. Why: readers first (ADR 0667 §4), and every definition is a list from G; it is merged ahead of G's check because the
|
||||
running checker, which makes G's own check (ADR 0667 §2), must read G's definitions, the operator's choice of a
|
||||
reader first (2026-11-09).
|
||||
How it is checked: unit rows for both forms in the release, and for the refusal in G.
|
||||
- §341 **TypeScript contracts as JavaScript.** The generator emits each seat's TypeScript contract as `index.js` with its
|
||||
`index.d.ts`, so a TypeScript module imports it with no build step of its own. Why: a seat's contract is generated
|
||||
from its definition (ADR 0625 §1), and a gap of the build system is built in it. How it is checked: a TypeScript
|
||||
module builds against a generated contract with no `tsc` of the contract.
|
||||
|
||||
### The catalog, the builder and the assigner
|
||||
|
||||
- §342 **A module not watched on a branch.** A watched branch's catalog graph takes each module not watched on that branch
|
||||
from the registration's first watched branch. `register` names a module's watched branches; with none named it takes
|
||||
the repository's default branch, read through the seat `git`. Why: a placement's default is the registration's first
|
||||
branch (ADR 0666 §6). How it is checked: whole (indexer), a `beta` revision holds a `main`-only module at `main`'s
|
||||
head.
|
||||
- §343 **Branch names the indexer's keys use.** `register` and `watch` refuse a watched branch named `candidate` or
|
||||
`entry`, naming why, since the catalog keeps its revisions under `<branch>.<revision>` beside those two key forms.
|
||||
How it is checked: whole (indexer), each is refused.
|
||||
- §344 **The bus module plans a sent store from what the catalog already says.** It plans `<module>_sent-objects` for a
|
||||
module of the new form whose catalog graph entry claims a seat whose definition has a verb or an event, or declares
|
||||
an event of its own, read from the catalog half of its revision view and the seat list; the indexer's event carries
|
||||
no field `sends`. When a seat's definition gains its first verb or event later, the bus module plans the store for
|
||||
its holders on the seat list's change. Why: no manifest field (*Any size*), and the catalog half is every part's view
|
||||
(ADR 0656 §6). How it is checked: whole (bus module), a module claiming a seat with a verb gets a sent store, one with
|
||||
neither gets none, and a definition gaining a verb gives its holder one.
|
||||
- §345 **A large value reaches the tool runner in chunks.** A bundle's put of a value over the bus's per-message limit is
|
||||
sent to the tool runner as a put session on the bundle's call subject, named by the call's id, in chunks under that
|
||||
limit, in order, each answered by the tool runner before the next is sent, and written as one object through the
|
||||
object store's own chunking; a put not sealed within the call's bound is dropped by the tool runner and its call
|
||||
fails, naming the object. No value is split over objects. Only modules that import the object store package are
|
||||
rebuilt for it. Why: one object per value (ADR 0666 §16), through the tool runner (ADR 0595 §9). How it is checked:
|
||||
whole (mesh-sdk), a value of a hundred times the limit is read back whole, and a put stopped half way fails naming
|
||||
the object and leaves none.
|
||||
- §346 **One object store package.** The assigner's and the indexer's object store code is mesh-sdk's small object store
|
||||
package, with no copy in either. Why: ADR 0595 §9. How it is checked: a search finds no second copy.
|
||||
- §347 **Reading sent objects is a bus state call.** mesh-sdk lists the call that reads a sent object under its existing
|
||||
bus state capability. Why: ADR 0595 §9 puts the calls in that package. How it is checked: the package's table test.
|
||||
- §348 **The builder reads the catalog through its seat.** The builder reads the registrations' watched branches through
|
||||
`mesh-catalog`'s `registrations` and `registration-changed`, the released versions it numbers from through
|
||||
`versions` and `version-released`, keeping no list of versions of its own, and a build seat's holder from the seat list; the
|
||||
manifests, the packages, each package's name in its ecosystem (the Go module path, the npm name, which the catalog
|
||||
graph entry's packages carry) and a run's candidate from the catalog half of its revision view, never the indexer's
|
||||
state. With no holder of a build seat, a build ends `could not run`, naming the seat, and is asked again on the seat
|
||||
list's change. Why: ADR 0596 §2. How it is checked: the builder's account holds no grant to the indexer's state.
|
||||
- §349 **The catalog holds released versions only, and says each.** The indexer keeps, for the seat `mesh-catalog`,
|
||||
each module's released versions in its old `state` section `versions`, one key per module and version holding each
|
||||
artifact's digest, the source revision built and its edge entries (§374) (issue 1961's catalog of versions). It hears
|
||||
every artifact's `package-published` (packages, images, bundles and archives alike) and records a version as
|
||||
released once every artifact the module's catalog entry names is published at it, then says `version-released` (the
|
||||
module, the version, each artifact's digest, the source revision) on
|
||||
`mesh.seat.mesh-catalog.event.version-released`. A version lower than the highest it holds released for that module
|
||||
is recorded, marked `released late`, and not said: no `version-released` is lower than the module's highest, and
|
||||
nothing follows one (§382). Each module keeps its newest 100 versions: at each release the indexer deletes that
|
||||
module's oldest beyond them, never its highest of any `MAJOR.MINOR`. The verb `versions` answers a module's released
|
||||
versions, its callers the builder, the holders of the registry seats and any person or session. A reserved version
|
||||
is not in it. The builder's `version.numbered` is no longer said or heard. Why: the operator, 2026-11-10 about 21:40 to 23:00 CET (gaps items 23 and 43); the
|
||||
key per version, the 100 kept and the late release are the design's choice, round 2 of the review by architectural domain, 2026-11-10. How it is checked: whole (indexer), a version with
|
||||
one of two artifacts published is not released, and with both is, said once; a late older version is not said.
|
||||
- §350 **A superseded build's drop is a kept call.** The runner ends a superseded build's step `superseded` at once, and
|
||||
asks the build seat's `drop` as a kept call (ADR 0668 §1, §2), so it is asked again through every transport fault
|
||||
and said `call-unanswered` after five minutes in the runner's findings. How it is checked: whole (runner), a drop
|
||||
unanswered is asked again, and raises `call-unanswered` after five minutes.
|
||||
- §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 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
|
||||
`assigner_written` reads it. How it is checked: whole (assigner), an older revision ending after a newer one writes
|
||||
nothing, and a later end of the same revision writes.
|
||||
- §353 **The assigner follows the registrations.** `mesh-delivery-contracts`' client `meshcatalogclient` carries a typed
|
||||
follower of `registrations`, a first view then `registration-changed`, built on `go/views`; the assigner and the
|
||||
forge module's merge switch on its first registrations (ADR 0667 §10). How it is checked: whole (assigner), it keeps
|
||||
the trunk-only want until the first `registration-changed`.
|
||||
- §354 **The assigner's composition step runs the composer in the sandbox.** It asks the seat `node-build-go` the ask `run`
|
||||
(*What ADR 0656 leaves to this design*), its step keys under `assigner.`, and serves the ask's input by its seat
|
||||
`mesh-wants`' verb `input`, as the checker's seat does today; the indexer does the same for its validation by
|
||||
`mesh-catalog`'s `input`. Both are foundation parts, so each keeps its inputs in an old `state` section `inputs`, one
|
||||
key per input named by its write time and its sha256, deleted when the build seat's `step-ended` of that ask is heard
|
||||
or a day after its write, whichever is first, the day judged at each new ask over at most 20 of the oldest keys;
|
||||
`assigner_inputs` and `indexer_inputs` read them. Both verbs' callers are the holders of the build seats. The Go build module reads no revision verb. Why: the
|
||||
composition step runs on parts built from the heads, in the sandbox (ADR 0666 §17). How it is checked: whole
|
||||
(assigner), a composition step's `run` is answered and its input read by digest.
|
||||
- §355 **The assigner says an unanswered `manifest-reads`.** The assigner, the one caller of the node-engine's
|
||||
`manifest-reads` from G, writes `call-unanswered` as its own finding and says it as an observer does (§383, §384),
|
||||
so the condition keeper hears it with no change of its own, departing from ADR 0668 §3's reads by the operator's
|
||||
answer of 2026-11-11. The assigner and
|
||||
the runner each declare their own state `findings` in their old `state` section, both being foundation parts, read
|
||||
by their own read tools alone. How it is checked: whole (assigner, runner, condition keeper), a node-engine that
|
||||
never answers makes the assigner say `finding-written` for `call-unanswered` after five minutes, and the keeper
|
||||
raises it from that event.
|
||||
- §356 **Two acting parts in different steps make no cycle.** The assigner's cycle check counts waits within one step only
|
||||
(*A wait holds only within its step*). How it is checked: the unit rows there.
|
||||
- §357 **Which provider a requirement points to.** In the assignment graph, by design 27's order: the named seat's
|
||||
holder, a pin, the provider on the consumer's node, the only provider; otherwise the entry is held, naming the
|
||||
candidates, and nothing is guessed. A contribution edge runs from a consumer's entry to the provider its requirement
|
||||
resolves to, wherever that requirement carries values the consumer contributes. How it is checked: unit
|
||||
(assignment graph), each step of the order and a hold.
|
||||
- §358 **The catalog's shared view takes a branch.** The client's view of the catalog half is per watched branch, named by
|
||||
its caller. How it is checked: unit (client), two branches give two views.
|
||||
- §359 **`difference` names its revisions.** `difference` with none of `from`, `to` and `group` is refused, naming the
|
||||
missing argument. How it is checked: a unit row.
|
||||
- §360 **An approved ask binds the placement.** What an approved ask binds to includes the placement's watched branch and
|
||||
its `build`, beside the fingerprint. How it is checked: whole (assigner), a placement changed after the Approve asks
|
||||
again.
|
||||
- §361 **A placement's `build` is a held put.** A placement's `build` is written as a held put of that build, released when
|
||||
the placement drops it; a put a person wrote is never released by a placement change. How it is checked: whole
|
||||
(assigner), a placement's `build` holds that build on its nodes, removing it releases the put, and a person's put
|
||||
stays through a placement change.
|
||||
- §362 **The indexer's first-start catch-up runs apart from its source handler.** At its first start the indexer takes in
|
||||
the heads the gate's source names by its catch-up path before it starts its handler of `source-moved`. How it is
|
||||
checked: whole (indexer), a `source-moved` said during the catch-up is applied after it, once.
|
||||
- §363 **A stale ask is dropped, backups included.** The assigner drops an ask it raised once the want it asked for is
|
||||
replaced, a backup ask among them (built in mesh-delivery #200). Why: ADR 0596 and ADR 0668 §2. How it is checked:
|
||||
whole (assigner), a backup ask whose want was replaced is dropped and not asked again.
|
||||
|
||||
### The condition keeper and the node-engine
|
||||
|
||||
- §364 **The node-engine claims its seat.** The node-engine's manifest claims the node seat `node-engine` (ADR 0563), and
|
||||
the indexer and the node-engine's own guard read its holder from the seat list, keeping no module name. How it is
|
||||
checked: the code review reads that neither fixes a module name (§7).
|
||||
- §365 **The condition keeper finds its sources in the catalog.** The catalog graph entry carries the events each
|
||||
manifest declares in its `streams`; the keeper takes a first view of the catalog half, and its sources are the
|
||||
modules whose entry declares the finding events of §383, the node-engine among them, its holder read from the seat
|
||||
list. It joins the readers of *Every other reader of which modules exist*, reading every watched branch's newest
|
||||
catalog revision, so a module watched on any branch is a source. A condition of a module that is in no branch's
|
||||
revision is cleared, said with the reason `module left the catalog`. A module's findings of a node are cleared,
|
||||
said with the reason `module left the node`, when the node-engine seat's `running.<node>.<module>` says the module no
|
||||
longer runs there and the newest assignment graph revision, from the keeper's first view of the assignment half
|
||||
(through `meshwantsclient`, following `assignment-revision` of `mesh-wants`), no longer places it there; never for a
|
||||
module no revision placed on that node. For it, `running.<node>.<module>` (§309) carries `stopped`, with no
|
||||
fingerprint, once the node-engine's have no longer holds the module, on the same subject, so the stream kept last per
|
||||
subject keeps it. Until its first view the keeper applies the events of the sources it keeps (§388) and says
|
||||
`view-waits` after five minutes (*A part with no view says it waits*), and a missing assignment half holds only the
|
||||
clears of `module left the node`. It reads no module's `findings` state (§383). Why: no part fixes
|
||||
a name (§7), and the keeper hears findings and reads no other module's state (ADR 0596 §2, §4), departing from
|
||||
ADR 0564 §2 by the operator's answer of 2026-11-11; the assignment half and `module left the node` are the design's
|
||||
choice, and so is `stopped`. How it is checked: whole (keeper, node-engine), a fixture module declaring the finding
|
||||
events is heard with no code change; a fixture module's condition on a node is cleared with `module left the node`
|
||||
once the node-engine says `stopped` for it and the assignment graph no longer places it, and is not cleared on the
|
||||
assignment revision alone; the catalog's validation finds no `findings` in the keeper's manifest `reads`.
|
||||
|
||||
### From round 1 of the review by architectural domain (2026-11-10)
|
||||
|
||||
- §366 **The runner's stores say their fill.** *A store filling is said before it is full* holds for the runner's
|
||||
`pipelines`, `step-outputs` and `kept`: it says their fill in `show` and `kept`, `filling` past 80 % and `room` below
|
||||
70 % on its seat, and `full` at the cap, when it starts no new pipeline, says each start it refused, and takes them
|
||||
up on `room`; nothing is dropped to make room. Why: the runner joins the stores of *Two graphs, one source of truth*
|
||||
(ADR 0666 §24, ADR 0564 §2). How it is checked: whole (runner), a full `pipelines` refuses a start, said, and
|
||||
`room` starts it.
|
||||
- §367 **A forge bridge message is read again on a transport fault.** The indexer reads a message of the forge
|
||||
bridge's stream again when reading it met a transport fault, as main's `UnreadAgain` does (ADR 0668 §1, §4): the
|
||||
message is left unacknowledged and its read asked again on the bridge's next answer, while a message the bridge
|
||||
itself answered as lost stays lost, said in the indexer's journal and in `indexer_pending`. G's own change for it
|
||||
(`LostAgain`, commit 106fc16b) is not built. Why: one rule for kept calls (ADR 0668), already on main. How it is
|
||||
checked: the indexer's take-in table, a transport fault reads the message again and a lost answer does not.
|
||||
- §368 **A manifest says its `MAJOR.MINOR`.** Each module's manifest names `version`, two numbers `MAJOR.MINOR`; the
|
||||
manifest validator refuses any other form, a pre-release or custom suffix (`beta`, `alpha`) among them: no custom
|
||||
version exists for now. A manifest without it is refused once G's reader runs (ADR 0667 §4: the reader is delivered
|
||||
first). G's change writes `version` into every existing manifest, the `MAJOR.MINOR` of the version §372 fills for that
|
||||
module, `0.1` for a module with none published, in the same group as the reader. Why: the operator, 2026-11-10 about
|
||||
21:40 CET; the values are the design's choice. How it is checked: unit (manifest validator), `1.4` accepted,
|
||||
`1.4-beta` and `1.4.2` refused; the catalog's validation finds no manifest without `version` at G's heads.
|
||||
- §369 **The reservation is one key per module and `MAJOR.MINOR`.** The builder, a foundation part, keeps in its old
|
||||
`state` section `reserved` one key per module and `MAJOR.MINOR`, the version its build reserved and each artifact's
|
||||
digest once built, written by compare-and-set at the build's start; a newer build of the module takes the next after
|
||||
the higher of the highest released and the one reserved, so two builds never share a version, and a superseded
|
||||
build's version is never released, leaving a gap in the patches. The builder deletes the key when the catalog says
|
||||
`version-released` for it, or when a version of another `MAJOR.MINOR` of the module is released (the manifest moved
|
||||
on); `builder_reserved` reads the keys and `builder_reserved_drop` drops one on a person's word, written in the
|
||||
hand-act log. A reserved version whose build ended with an artifact unpublished past the publish's 10-minute bound
|
||||
is the builder's finding `version-unreleased`, naming the module, the version and the missing artifacts, cleared by
|
||||
its `version-released`. `builder_publish_again` names the reserved version it publishes under. The builder reserves
|
||||
nothing until the catalog says `versions-filled` (§372); a build waiting for it says `wait-held` naming the fill. The
|
||||
seat `mesh-builds`' verb `reserved` answers a module's reserved version with each artifact's digest, its callers the
|
||||
holders of the registry seats (design 51, *Publishing*). This is no list of released versions: numbering reads those
|
||||
only from the catalog. Why: the operator, 2026-11-10 (a version reserved when the build starts); the key, the gap,
|
||||
the finding and the verb are the design's choices. How it is checked: whole (builder), two builds close together
|
||||
reserve two versions, the key goes on `version-released`, an unpublished artifact raises `version-unreleased`, and a
|
||||
builder started before the fill reserves nothing until `versions-filled`.
|
||||
- §370 **The version reaches every artifact's build.** The build seat's ask carries the version, and the build module
|
||||
passes it to the artifact's build as the build argument `MESH_VERSION`: a Go package is tagged `vMAJOR.MINOR.PATCH`,
|
||||
an npm package's version is it, an image carries it as its tag and label, and a program reads it as its own version.
|
||||
A Go package's version is its tag: this departs from ADR 0573 §2, which has a Go package's version be its trunk
|
||||
commit, by the operator's choice of 2026-11-10, and a later research brings that record in line. The git tag
|
||||
(`go/vMAJOR.MINOR.PATCH`, design 51) is written by the builder only on the catalog's `version-released`, through the
|
||||
seat `git`'s verb `tag`, whose callers are the builder alone, so a superseded build's reserved version is never
|
||||
tagged. How it is checked: whole (Go and TypeScript build modules), a built package and program carry the reserved
|
||||
version; whole (builder), the tag is written on `version-released` and never for a superseded build; whole (forge
|
||||
module), a `tag` from any caller but the builder's account is refused by the bus.
|
||||
- §371 **Only the first watched branch releases.** Only a build of the registration's first watched branch reserves and
|
||||
releases a version; a build of another watched branch reserves none, publishes no version and is delivered by its
|
||||
build, its fingerprint, as every want names one. Why: the operator, 2026-11-10. How it is checked: whole (builder),
|
||||
a `beta` build reserves nothing and is delivered.
|
||||
- §372 **The catalog's versions start from what is published.** At the new indexer's first start, `versions` is filled
|
||||
once, as released, for each module from the highest `published` version over every artifact of the module that the
|
||||
builder's state `versions` held (for mesh-sdk the higher of Go's `v0.1.14` and npm's `0.1.18`, so `0.1.18`), read by
|
||||
`builder_versions` as a kept call (ADR 0668 §1, §2), which the indexer's manifest names in its `invokes`
|
||||
(`mesh-delivery-builder.builder_versions`) until that tool goes, an unanswered call raising `call-unanswered` after five minutes;
|
||||
it is not filled again. Then the indexer says `versions-filled` on its seat, once, kept on its stream with no age
|
||||
limit, and the builder reserves nothing before it (§369). The builder keeps serving `builder_versions` until then: the
|
||||
running builder serves it already, and the new one serves it too, so no ordering edge is needed. The new builder's
|
||||
`builder_versions` also answers each reserved version with its artifacts' digests (§369), so a registry holder still
|
||||
on its version before G, which asks `builder_versions`, stores a publish of a reserved version made between the
|
||||
builder's delivery and its own (§381). The builder's state
|
||||
`versions`, the floor and its tool `builder_floor_again`, the event `numbered`, `builder_versions`, and `tag-asks` are
|
||||
removed in the first change after the first pipeline after G's delivery has delivered a change end to end, the state
|
||||
through `drop` on a person's word (ADR 0595 §4). Why: numbering reads only the catalog's released versions (§348),
|
||||
and without this every first version under G would start below today's and Go's `@latest` would never move (the design's choice, round 2 of the review by architectural domain, 2026-11-10).
|
||||
How it is checked: whole (indexer, builder), with Go `v0.1.14` and npm `0.1.18` published before G, the first G build
|
||||
of `0.1` is `0.1.19`, and a builder started before the indexer reserves nothing until `versions-filled`.
|
||||
- §373 **A group's run on request publishes no version.** A run on request of a group builds each member that
|
||||
depends on a package member against that member's build by its digest. The builder's build ask for such a member
|
||||
carries each package member's build digest, which the builder takes from its own `build.ended` of that member's
|
||||
build, its own fact (ADR 0596 §2); the build module fetches that build from the store by the digest, checks the
|
||||
fetched bytes against it, and lays it in the build's workspace as the module that package names (a Go workspace's
|
||||
replacement, a TypeScript local package), so nothing is fetched by a version, and no version is reserved, numbered
|
||||
or published for the run. A dependent whose package member's build is not done waits, said as the builder's
|
||||
`wait-held` naming the member, within building's 60-minute bound; a member's build that failed or is missing past
|
||||
that bound fails the dependent's step, naming the member. The tagged versions, `tag-wanted` (the checker's, and none
|
||||
of the runner's) and the builder's `tag-asks` with its tools `builder_tag`, `builder_tag_asks` 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; the digest's source
|
||||
and the wait are the design's choice, round 2 of the review by architectural domain, 2026-11-10. How it is checked: test 103.
|
||||
- §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 of its newest `version-delivered`
|
||||
when this release is itself first delivered (its own `version-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: the verb or manifest word used and the dependency's delivered
|
||||
version that serves it, written at the same first delivery.
|
||||
|
||||
The entries of kinds 2, 4 and 6 read `not yet delivered` until that first delivery, are written once then, and none
|
||||
is changed after; kinds 1, 3 and 5 are written at the release.
|
||||
|
||||
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, 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, written once. 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 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 of the builder's newest `toolchain-agreed`; for kinds
|
||||
2 and 4, it differs from the dependency's newest `version-delivered`; 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, 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 with its
|
||||
watched branch and source revision, what was recorded and what is newest, and the act. It may be asked for one
|
||||
dependency. Its callers are any person, an agent session, the healers and the runner. At its start the runner asks
|
||||
`outdated` once, a kept call raising `call-unanswered` after five minutes, and starts the rebuilds it names; the
|
||||
runner's tool `runner_catch_up`, for the operator and the healers and written in the hand-act log, does the same by
|
||||
hand, for one dependency or all. A restart or a missed event so leaves nothing behind. Why: the operator, 2026-11-10
|
||||
(issue 1961's "outdated"); `runner_catch_up` replaces the indexer's hand tool, which would have had to say another
|
||||
part's event (the design's choice, round 2 of the review by architectural domain, 2026-11-10). How it is checked: test 105.
|
||||
- §376 **A stale edge rebuilds on its event; a delivery is waited for mesh-wide.** The rebuilds start on two events
|
||||
the runner consumes: kind 1 on `package-published` (§53), and kind 3 on `toolchain-agreed`, which the builder says
|
||||
on its seat `mesh-builds` when the agreed toolchain of a language changes (ADR 0584 §1), naming the language, the
|
||||
version and the toolchain part's digest; for each, the runner asks `outdated` for that dependency and starts a
|
||||
pipeline for each dependent behind. `version-released` starts no rebuild. 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 assigner judges
|
||||
it, since placement is its own state: from its placements, the node-engine seat's `running` events and the
|
||||
watchman's `machine-away` and `machine-back` of each node (§389), never its state, judged again on each of them and on each placement change, and says
|
||||
`version-delivered` (the module, the version, its parts' digests and the machines away) on its seat `mesh-wants`
|
||||
(`mesh.seat.mesh-wants.event.version-delivered`) once every present machine placing it runs it healthy; the catalog
|
||||
hears it for its entries (§374), and the assigner writes the dependent's wants on it. The dependent's wait is the
|
||||
assigner's, said `wait-held` with a 60-minute bound from the dependency's `version-released` (*Each step's wait is its
|
||||
own part's*): past it, the watchman's finding `delivery-waits` names the dependency, the version and the machines not
|
||||
running it, with each one's node-engine version, so a node-engine from before G that never runs it is named. 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 <module>", naming the machines it waits for.
|
||||
When every machine that places the dependency is away, it is not delivered: its status reads "waiting for <machine>
|
||||
to be back", its dependents wait, and nothing is raised for a machine simply away, the bound counting only while a
|
||||
placing machine is present. `assigner_delivered_again`, for the operator and the healers and written in the
|
||||
hand-act log, says `version-delivered` again for one version when it holds. 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; who judges it, the event's seat, the bound and the tools are
|
||||
the design's choice, round 2 of the review by architectural domain, 2026-11-10. 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: 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 machine placing it runs, present or away, 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.<node>.<module>`
|
||||
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 assigner takes the digests from `version-released` for a released version, and from
|
||||
the builder's `build.ended`, which carries each artifact's digest and, for a kept build, its keeping node, for a build
|
||||
of another watched branch and for a kept build (§271); never from the builder's done key (ADR 0596 §2). It writes the
|
||||
two fields into a node's want only once that node runs G's node-engine, as it holds a node's other wants for its new
|
||||
node-engine (*Composing waits per node*), so the reader edge holds per node and a node away on an older node-engine
|
||||
gets its node-engine's want first. Why: the operator, 2026-11-10 about 22:30 to 23:00 CET; the sources and the edge per node are the design's choice, round 2 of the review by architectural domain, 2026-11-10. How it is checked:
|
||||
whole (assigner, node-engine), a want names the version and the parts' digests taken from those events, a node on an
|
||||
older node-engine gets no new field, 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). Its callers are any person, an agent session and the healers. 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.
|
||||
- §381 **A registry holder checks a publish against the reservation.** From G's delivery the holder of a registry
|
||||
seat asks the seat `mesh-builds`' verb `reserved` (§369), in place of `builder_versions`, whether the module, the
|
||||
version and the artifact's digest are reserved, and refuses loudly otherwise (ADR 0605 §4); a version the catalog
|
||||
already holds released for that digest is answered as held and stores nothing. Why: ADR 0605 §4 has the holder
|
||||
refuse a version the builder did not give, and the builder's list goes (§372); the design's choice, round 2 of the review by architectural domain, 2026-11-10.
|
||||
The order is a served-verb edge (kind 6) the delivery plan derives from the holder's new `invokes` of
|
||||
`mesh-builds.reserved`: the builder runs its new version, which serves `reserved`, before each registry holder's new
|
||||
version is delivered; until then the old holder asks `builder_versions`, which answers reserved versions (§372). How
|
||||
it is checked: whole (registry holder, builder), a publish of an unreserved version is refused, naming it; whole
|
||||
(builder, registry holder on its version before G), a publish made between the builder's delivery and the holder's
|
||||
is stored; the delivery plan of G names the edge from the builder to each registry holder.
|
||||
- §382 **An older version released after a newer starts nothing.** When every artifact of a version lower than the
|
||||
module's highest released is published late (a retry of an older reservation), the catalog records it `released
|
||||
late`, says no `version-released` for it, and the runner starts no rebuild on its `package-published` (§53). Why:
|
||||
a rebuild against an older part would move a dependent back; the design's choice, round 2 of the review by architectural domain, 2026-11-10. How it is checked: test 102.
|
||||
@@ -0,0 +1,167 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: G
|
||||
updated: 2026-11-11
|
||||
decisions:
|
||||
- "ADR 0668"
|
||||
- "ADR 0667"
|
||||
- "ADR 0666"
|
||||
- "ADR 0636"
|
||||
- "ADR 0603"
|
||||
- "ADR 0596"
|
||||
- "ADR 0595"
|
||||
- "ADR 0564"
|
||||
- "ADR 0363"
|
||||
- "ADR 0289"
|
||||
- "ADR 0253"
|
||||
---
|
||||
|
||||
# 47, milestone G: the operator's answers of 2026-11-11, findings heard as events
|
||||
|
||||
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 lines
|
||||
§336, §355 and §365, which these answers also change, stay in [G-7-answers](G-7-answers.md).
|
||||
|
||||
## The operator's answers to milestone G's design questions (2026-11-11)
|
||||
|
||||
*ADR 0596 §1, §2, §4, ADR 0564 §2, §4, §12, §13, ADR 0668 §1, §3, ADR 0636 §1, ADR 0666 §16, ADR 0667 §4, ADR 0363
|
||||
§1, §2, §5. The operator, 2026-11-11, through lead-47: the condition keeper reads no other module's state and hears
|
||||
each module's findings as events; a module states its findings from its own truth, NATS-native; the shared
|
||||
tool-runner account stays as it is in G; no record is written for these answers, so each line that departs from a
|
||||
record says so in its Why. Round 3 of the review by architectural domain (2026-11-11) completed these lines.*
|
||||
|
||||
- §383 **An observer says its findings as events on a stream of its own; the keeper reads no observer's state.** Every
|
||||
module that writes findings is an observer (§387 names them) and says each change of a finding on its own stream
|
||||
`<module>-findings` (ADR 0363 §1: under its name in capitals on the bus, its `events` `finding-written.*`,
|
||||
`finding-cleared.*` and `findings-stated.*`, kept 7 days and 16 MiB, its oldest message dropped when full, since the
|
||||
next statement of §384 covers a lost one), published on `mesh.stream.<module>.event.<event>.<node>`, the node it runs
|
||||
on in the subject (ADR 0363 §2; §260). `finding-written` is said when a finding is raised or what it says changes,
|
||||
and only then (ADR 0289 §1, §4); `finding-cleared` when the observer no longer observes it. `finding-written`
|
||||
carries `scope`, `id` and `kind` (the key `<scope>.<id>.<kind>` of ADR 0564 §2), `severity`, `subject`, `evidence`,
|
||||
ADR 0253's words (`headline`, `explanation`), `since` and `at`; `finding-cleared` carries `scope`, `id`, `kind`, `at`
|
||||
and `why`. The observer and the node are the subject's alone: the grants part grants each module's account publish
|
||||
on its own stream's subjects of its own node's segment only, the keeper takes both from the subject, and it refuses
|
||||
an event whose body names another observer or node, said in its journal. mesh-sdk's finding writer (`go/views`'
|
||||
`FindingWriter`) says them for every part, after the key it writes in the part's own state `findings`, which stays
|
||||
the owner's and is read only by the owner's read tool; a publish the bus does not acknowledge is sent again for one
|
||||
minute, then written in the part's journal as an error naming the finding, and the next statement covers it. The
|
||||
keeper takes a finding only from a source of its own list (§388) and raises or changes a condition on
|
||||
`finding-written` and clears it on `finding-cleared`, save while ADR 0564 §13 holds it; a condition's looks are those
|
||||
of its last event, and the observer's read tool shows its newest. What exists today goes in the same change: every
|
||||
`findings` entry of the keeper's manifest `reads`, its `consumes` of the assigner's and the indexer's
|
||||
`views.findings`, and its `invokes` of `assigner_read_findings` and `indexer_read_findings`; the assigner and the
|
||||
indexer no longer declare `views.findings`, which no reader follows; the read tools stay for persons and sessions.
|
||||
Why: only its owner reaches a module's state, and a part hears another's events (ADR 0596 §2, §4); this departs from
|
||||
ADR 0564 §2, where the keeper watches each observer's bucket, by the operator's answer of 2026-11-11. The stream, its
|
||||
age and cap, the subjects, the fields, the writer and its retry are the design's choice. How it is checked: unit
|
||||
(mesh-sdk's writer), a finding written and one cleared each say their event with these fields after the key, and an
|
||||
unacknowledged publish is sent again and then logged; whole (keeper, a fixture observer on an account of its own),
|
||||
`finding-written` raises a condition and `finding-cleared` clears it, the same event published by another module's
|
||||
account and by the same module's account on another node's subject are refused by the bus, and a body naming another
|
||||
observer or node is refused by the keeper; the catalog's validation finds no `findings` in the keeper's `reads`.
|
||||
- §384 **An observer states every finding it owns at its start and when the keeper asks; the keeper's view is
|
||||
rebuilt from those events alone.** At each start, and on each ask of the keeper, an observer judges every finding it
|
||||
owns anew from its own truth, the cause each kind watches (the seat list it holds, a call still unanswered, a wait
|
||||
still standing), never from what one process remembers, and says `findings-stated` on
|
||||
`mesh.stream.<module>.event.findings-stated.<node>`, carrying `at`, `asked` (the ask it answers, none at a start),
|
||||
`findings` (every finding it observes now, with `finding-written`'s fields) and `pending`. A wait's bound counts from
|
||||
the wait's own start, which the observer keeps in its own state when the wait begins (the `since` of its key in
|
||||
`findings`, written before the bound passes), never from the process's start, so a wait that began before a restart
|
||||
is judged against its whole age. `pending` names, with their `since` and their bound, the keys the observer cannot
|
||||
judge yet since its start (a kept call it has not yet made again, a wait it has not yet looked at). The keeper sets
|
||||
its view of that observer on that node to that set: it raises what is new, keeps each pending key's condition open
|
||||
and unchanged, saying nothing for it, and clears each other condition of that observer and node the set does not
|
||||
name, with the reason `not stated at <observer>'s start` or `not stated when asked`; a pending key is cleared only if
|
||||
neither a `finding-written` nor a later set names it within its bound after the set's `at`, with the reason `not
|
||||
judged within its bound`. For an observer whose catalog entry claims only seats held once for the mesh, the set
|
||||
replaces its findings of every node, and the keeper takes `finding-written` and `finding-cleared` of it only from
|
||||
the node the seat list names as its holder, and only with an `at` later than that holder's last `findings-stated`, so
|
||||
a holder that took over leaves no finding of the one before and an old holder's late event changes nothing. A set
|
||||
larger than one bus message goes in the observer's sent store (§59). The node-engine's `seat-list-unread` (ADR 0636
|
||||
§1) is stated so: a node-engine started with the full list states no `seat-list-unread`, and the keeper clears it at
|
||||
that start. Why: the node-engine's seat-list waiter kept only in its process that it had written its finding, so a
|
||||
node-engine restarted with the full list never cleared it, and two machines said they waited for the seat list for a
|
||||
day while both held it (issue 1966); this departs from ADR 0564 §2 by the operator's answer of 2026-11-11: the fix is
|
||||
NATS-native, from each observer's own truth. The event, its fields, `pending`, the kept start, the reasons and the
|
||||
rule for an observer held once are the design's choice. How it is checked: whole (the node-engine, and each observer
|
||||
through mesh-sdk's writer), a module restarted after raising a finding whose cause has gone clears it at its start,
|
||||
the node-engine's `seat-list-unread` among them, and an observer restarted with a call unanswered for two hours says
|
||||
neither `condition-cleared` nor `condition-raised`; whole (keeper), a condition the set does not name is cleared with
|
||||
its reason, a pending key past its bound is cleared, and in a take-over the new holder's set clears the old holder's
|
||||
findings and an old holder's later `finding-written` raises nothing; unit (mesh-sdk's writer), a start states the
|
||||
findings observed now and pends the rest. Test 107.
|
||||
- §385 **One tool-runner account for every module of a machine stays as it is.** On a machine where one tool runner
|
||||
serves every module's tools on one bus account, any tools bundle there may read any sent store (§59) that account is
|
||||
granted, call `merge-pull` or the runner's `run` as a session, and say the finding events of §383 of any module that
|
||||
account publishes for; G changes neither that account nor its grants, a known limit. Why: the operator, 2026-11-11;
|
||||
modules running as the machine's account are issue 1966's (note 193), whose fix carries its check. How it is checked:
|
||||
none in G; the limit is named on issue 1966.
|
||||
- §386 **A `*` emitter in `consumes` hears one event from every module that declares it.** A `consumes` entry
|
||||
`*.<event>` takes the event `<event>` from every module whose manifest declares it, and is the one generic form for
|
||||
hearing an event that many modules say; the keeper's `*.finding-written`, `*.finding-cleared` and
|
||||
`*.findings-stated` are the first. The manifest validator takes `*` only as the whole emitter, and only before an
|
||||
event that a seat's definition or a contract in mesh-sdk defines, with its fields (for the finding events, mesh-sdk's
|
||||
finding writer); it refuses `*` before any other event, `*.>`, and `*` in part of an emitter's name. The grants part,
|
||||
from the manifests as it derives every grant (§59), makes on each declaring module's stream one durable consumer
|
||||
for the consumer, named `<machine>_<module>` as ADR 0363 §5 names one, with its grants to read and acknowledge it and
|
||||
its membership's word to bind it; it drops that consumer when the module no longer declares the event, and makes one
|
||||
for a module that declares it later, with no change to the consumer's manifest. A `*` entry never reaches a
|
||||
restricted stream (one with a `grant`, ADR 0363 §4). Why: the keeper hears modules it finds in the catalog and its
|
||||
manifest names none (§7, §365); this departs from ADR 0363 §5, where an entry with a wildcard emitter never reaches
|
||||
a module's stream, by the operator's answer of 2026-11-11; the validator's rule and the per-module consumer are the
|
||||
design's choice. How it is checked: unit (manifest validator), `*.finding-written` accepted, `*.>`,
|
||||
`*x.finding-written` and `*` before an event no contract defines refused; the grants part's table test makes a
|
||||
`*.finding-written` consumer one durable consumer on each declaring module's stream and none on a restricted
|
||||
stream; whole (keeper, grants part), a fixture module that declares the events after the keeper started is heard,
|
||||
and a keeper stopped while findings change catches up from its durable consumers at its start.
|
||||
- §387 **G's change writes the finding stream into every observer's manifest.** In the same change G writes the stream
|
||||
`<module>-findings` of §383 into the manifest's `streams`, and `mesh-conditions.findings-asked` into its `consumes`,
|
||||
for every module that declares a state `findings` on main: `artifact-store-tools`, `claude-code`, `distribution`, `gitea`,
|
||||
`mesh-build-go`, `mesh-config`, `mesh-healers`, `mesh-knowledge`, `mesh-provisioner`, `mesh-self-check`, `mesh-vault`, `mesh-watcher`,
|
||||
`minio` and `nfs-server` in mesh-catalog; `mesh-delivery-assigner`, `mesh-delivery-builder`, `mesh-delivery-checker` (until its
|
||||
removal, ADR 0667 §12), `mesh-delivery-indexer`, `mesh-delivery-teller`, `mesh-delivery-view`, `mesh-delivery-watchman` and
|
||||
`mesh-enrolment` in mesh-delivery; `mesh-host`, the node-engine; `node-tools`, the tool runner, in mesh-tools; and the modules that gain
|
||||
findings in G, the runner (`mesh-delivery-pipeline`, §355) and the forge bridge (`mesh-delivery-forge-bridge`, for `branch-unprotected`, §17). The manifest
|
||||
validator refuses a manifest declaring the state `findings` without that stream and that `consumes`. Why: an
|
||||
observer whose stream is missing says nothing the keeper hears; the list is read from main on 2026-11-11 and the rule
|
||||
is the design's choice. How it is checked: unit (manifest validator), a manifest with `findings` and no finding
|
||||
stream refused; the catalog's validation at G's heads refuses none of these manifests.
|
||||
- §388 **The keeper keeps its sources in its own state, and raises its own findings itself.** The keeper keeps its
|
||||
list of sources (each module whose catalog entry declares the finding stream, with the nodes it heard and each
|
||||
observer's last stated set and open asks) in its own state `findings-views`, in the form of its `conditions`, one key
|
||||
per observer and node, deleted when the module leaves the catalog (§365) or the node (§365). At its start it applies
|
||||
the events of those sources at once from its durable consumers, before its first view of the catalog half; the view
|
||||
only adds and removes sources. A source new to the list is asked with `findings-asked` naming it once its durable
|
||||
consumer exists (§386). The keeper's own findings (`view-waits`, `findings-unstated`, `call-unanswered`) it raises and
|
||||
clears directly as the one writer of conditions, never through its own events. A missing assignment half holds only
|
||||
the clears of `module left the node`. Why: a keeper that waits for its view would hear nothing after a restart while
|
||||
the catalog is down; the state and its key are the design's choice. How it is checked: whole (keeper), started with
|
||||
the catalog's holder stopped it raises and clears from its kept sources' events, raises `view-waits` after five
|
||||
minutes itself, and clears nothing with `module left the node` until the assignment half answers.
|
||||
- §389 **The watchman says a machine's presence as events.** The seat `mesh-watchdogs` gains the events `machine-away`
|
||||
and `machine-back` (`mesh.seat.mesh-watchdogs.event.machine-away.<node>`, `.machine-back.<node>`, carrying the node,
|
||||
`at` and since when it was last heard), said by the watchman when its presence key of a machine expires and when the
|
||||
machine is heard again (ADR 0564 §4), declared in the seat's definition and kept 90 days, 16 MiB. The keeper
|
||||
consumes them for `findings-unstated` (no machine away is named, and an ask is said again to a module of a machine
|
||||
back), and the assigner for its judgement of `version-delivered` (§376); neither reads the watchman's state. Why:
|
||||
ADR 0596 §2; the events and their fields are the design's choice. How it is checked: whole (watchman), a machine
|
||||
whose presence expires says `machine-away` and one heard again `machine-back`; whole (keeper), an observer on a
|
||||
machine away is not named in `findings-unstated`.
|
||||
- §390 **The keeper's ask, its tools, and its hold.** The keeper asks with its seat's event `findings-asked`
|
||||
(`mesh.seat.mesh-conditions.event.findings-asked`, carrying `ask`, `at`, `by` and, to ask one, `module`), declared
|
||||
in the seat's definition, kept 7 days and 16 MiB; an observer hears it through mesh-sdk's writer on a consumer that
|
||||
starts from the newest ask, so an old ask is never answered again. The keeper asks after its start (§388) and on
|
||||
`resync` (ADR 0564 §12), which gains an optional `module` and so reads no state; its callers are the operator, the
|
||||
healers and agent sessions, and each call is written in the hand-act log of the seat `mesh-hand-acts`. An observer
|
||||
that states nothing within five minutes of an ask, its machine not away (§389), is the keeper's finding
|
||||
`findings-unstated`, naming the module and the node, cleared by its next `findings-stated`; its conditions stand
|
||||
meanwhile. `findings-unstated` is held under ADR 0564 §13's hold while its module is being delivered, and G's
|
||||
delivery plan says it may show while the observers move. The keeper's tool `conditions_findings_views` answers each
|
||||
observer and node of `findings-views`: its last stated set with its `at`, its pending keys and the open asks; its
|
||||
callers are any person, agent sessions and the healers. Why: ADR 0564 §12 has every act of the keeper started by
|
||||
hand, and the tools-first rule a read of all it keeps; the names, the callers and the bound are the design's choice.
|
||||
How it is checked: whole (keeper), `findings-unstated` is cleared by a `resync` naming that one module, the call is
|
||||
in the hand-act log, an observer restarted after an old ask answers only a new one, and the tool answers a fixture
|
||||
observer's set.
|
||||
@@ -3,7 +3,7 @@ layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: G
|
||||
updated: 2026-11-10
|
||||
updated: 2026-11-11
|
||||
decisions:
|
||||
- "ADR 0668"
|
||||
- "ADR 0667"
|
||||
@@ -59,7 +59,9 @@ decisions:
|
||||
- "ADR 0398"
|
||||
- "ADR 0391"
|
||||
- "ADR 0363"
|
||||
- "ADR 0289"
|
||||
- "ADR 0283"
|
||||
- "ADR 0253"
|
||||
- "ADR 0240"
|
||||
- "ADR 0235"
|
||||
- "ADR 0233"
|
||||
@@ -73,11 +75,13 @@ 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 eight 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 to §382).
|
||||
- [G-8-findings-heard-as-events](G-8-findings-heard-as-events.md): the operator's answers of 2026-11-11, findings heard as events (§383 on).
|
||||
|
||||
@@ -6,12 +6,12 @@ code:
|
||||
- mesh-catalog modules/artifact-store-tools (the store's tools), modules/distribution (its program, holding the two image seats)
|
||||
- mesh-catalog modules/gitea (package retention; the two package seats' verbs in its Go bundle)
|
||||
- mesh-catalog modules/mesh-build-go, modules/mesh-build-node, modules/mesh-build-image (publishing through the seats)
|
||||
- mesh-delivery modules/mesh-delivery-builder (versions, tag asks; from milestone G a package numbered at its publication, the seat `mesh-builds`), the forge bridge, the indexer, the checker, the assigner, modules/mesh-delivery-pipeline (`tag-wanted` from milestone G)
|
||||
- mesh-delivery modules/mesh-delivery-builder (versions, tag asks; from milestone G a module's version reserved at its build's start and released by the catalog, the seat `mesh-builds`), the forge bridge, the indexer, the checker, the assigner, modules/mesh-delivery-pipeline (no tagged version from milestone G)
|
||||
- mesh-sdk (the bus helper for sending in parts)
|
||||
- mesh-catalog modules/docker (image pruning)
|
||||
- mesh-host internal/apply (every new image of a module pulled before any of its containers is replaced; a failed pull applied again on the status view's `settled` for the store's holder, and at the node-engine's start), internal/compose (each routed image reference written with its seat and that seat's holder)
|
||||
- mesh-delivery modules/mesh-grants (what a node-engine hears: the status view's `settled`)
|
||||
updated: 2026-11-10
|
||||
updated: 2026-11-11
|
||||
decisions:
|
||||
- "ADR 0667"
|
||||
- "ADR 0666"
|
||||
@@ -130,7 +130,8 @@ the verb.
|
||||
▼
|
||||
registry seat's holder ── answers the parts it lacks
|
||||
│ the build module sends those parts, in chunks, by `publish`
|
||||
holder: hashes what it received, asks `builder_versions`,
|
||||
holder: hashes what it received, asks `builder_versions`
|
||||
(from milestone G of design 47: `mesh-builds`' `reserved`),
|
||||
stores in its own store, emits `published` or `refused`
|
||||
▼
|
||||
builder (durable consumer: entry, done key), indexer, status view, checker
|
||||
@@ -153,7 +154,9 @@ the verb.
|
||||
match its digest. At 80 % of the cap it writes a finding (cleared below 80 %); at the cap it refuses a new transfer
|
||||
with `refused` naming the cap. Its tool `registry_incoming` lists open transfers and the fill, and drops one by hand.
|
||||
- **The holder asks the builder**, through `builder_versions`, whether the name, version and digest are recorded, and
|
||||
refuses loudly otherwise (ADR 0605 §4). A rebuild of a held fingerprint answers the held version and stores nothing.
|
||||
refuses loudly otherwise (ADR 0605 §4). A rebuild of a held fingerprint answers the held version and stores nothing. From the delivery of
|
||||
design 47's milestone G the holder asks the seat `mesh-builds`' verb `reserved` instead, whether the module, the
|
||||
reserved version and the artifact's digest are reserved, and refuses loudly otherwise (design 47 G §381).
|
||||
- **How a publish ends**: the holder emits `published` or `refused`. The build module waits for one of them, matching
|
||||
on its transfer, name and version, at most
|
||||
10 minutes, narrating "waiting on <seat>" at least every five minutes; past the bound it writes the key refused,
|
||||
@@ -266,24 +269,30 @@ the verb.
|
||||
|
||||
### The versions
|
||||
|
||||
- **From the delivery of design 47's milestone G, a package is numbered when it is published** (ADR 0666 §15). The
|
||||
builder numbers a package's version at its publication, never only when its build is claimed: a package's trunk
|
||||
build is claimed with no number and built by its digest, and once its build is done the builder gives it the next
|
||||
count of its series, under compare-and-set, and says `numbered`, on which the build module calls `publish` with
|
||||
the version and the held digest, as below for a floor not yet known. A build of an older source revision of the
|
||||
same watched branch than one already numbered for that name is not numbered and publishes nothing, so a version never
|
||||
names older content than the one below it. When the holder says `published`, the builder says the publication as the
|
||||
event `package-published` of its seat `mesh-builds` (the name, the version, the fingerprint, the commit, the watched
|
||||
branch). On it every artifact with a "published before it builds" edge to the package is rebuilt against the new
|
||||
version, and the pipeline runner, which consumes the event, starts its pipeline (ADR 0666 §15; design 47, *A publish
|
||||
rebuilds*);
|
||||
nothing else is rebuilt, and a change to a package's tests alone publishes nothing. This removes the claim's wait
|
||||
for earlier merges' numbers below, which held a group on 2026-11-09 (research 086, Findings). Why at publication: a
|
||||
number given at the claim must wait for every earlier merge's number, and a build that never publishes keeps a
|
||||
number nothing holds. An image, bundle or archive keeps the rule below. How it is checked: in the builder's
|
||||
whole-module test a package's trunk build is numbered only once built, an older revision's build after a newer one
|
||||
publishes nothing, `package-published` is said once per publication, and only the importing artifacts rebuild
|
||||
(design 47, test 80).
|
||||
- **From the delivery of design 47's milestone G, a module's version is reserved at its build's start and released
|
||||
when every artifact is published** (the operator, 2026-11-10 about 21:40 CET; design 47 G §52, §348, §349, §368 to
|
||||
§371). A module's manifest says its `version`, `MAJOR.MINOR`, and no custom version (`beta`, `alpha`) exists for now
|
||||
(G §368). The patch is the next after the highest version the catalog holds released for that `MAJOR.MINOR`, 0 for
|
||||
one it holds none of; the builder reserves it when the module's build starts, in its key `reserved` for the module
|
||||
and `MAJOR.MINOR` (G §369), and passes it to the build of every artifact as a build argument, so code and packed
|
||||
files carry it (G §370): a Go package is tagged `vMAJOR.MINOR.PATCH`, in git under its module directory's prefix
|
||||
(`go/vMAJOR.MINOR.PATCH`), which departs from ADR 0573 §2 (a Go package's version is its trunk commit) by the
|
||||
operator's choice, a later research bringing the record in line. Each artifact published is said as
|
||||
`package-published` of the seat `mesh-builds` (ADR 0666 §15), on which every artifact with a "published before it
|
||||
builds" edge to it is rebuilt against the new version and its pipeline started (design 47, *A publish rebuilds*);
|
||||
nothing else is rebuilt, and a change to a package's tests alone publishes nothing. The version is released only
|
||||
once every artifact of the module is published at it: the catalog, the seat `mesh-catalog`, then holds it and says
|
||||
`version-released`, and its `versions` is the one list of released versions, which numbering alone reads (G §348,
|
||||
§349). A failed publish leaves the version reserved, and `builder_publish_again` publishes the missing artifacts
|
||||
under the same version. Only a build of the registration's first watched branch reserves and releases a version; a
|
||||
build of another watched branch is delivered by its build, with none (G §371). The builder no longer numbers a
|
||||
build at its claim or at its publication, says no `numbered` or `version.numbered` for a module's versions, and
|
||||
keeps no list of them of its own: the bullets below on the claim's numbering, the numbering per source revision, the
|
||||
builder's state `versions`, the floor and the event `numbered` hold until that delivery only. Numbering continues above what is published today, the catalog filled once from it (G §372). Why reserved before the build: a Go module zip and a TypeScript package carry their
|
||||
version inside the file, so a number given at publication could not be valid for a digest built before it; this
|
||||
departs from ADR 0666 §15's numbering at publication by the operator's choice. How it is checked: design 47's test
|
||||
102, and in the builder's whole-module test a version is reserved at the build's start, released once both of a
|
||||
module's artifacts are published, and published again under the same version after a failed publish.
|
||||
- **A build that cannot read the published packages refuses**, naming the unread state, never building against a guess
|
||||
(ADR 0666 §15; design 47, test 70).
|
||||
- **Until that delivery, the builder numbers every trunk build** of a package, image, bundle or archive at its claim: the package series
|
||||
@@ -339,13 +348,17 @@ the verb.
|
||||
|
||||
### Tagged versions
|
||||
|
||||
- **From the delivery of design 47's milestone G there are no tagged versions** (the operator, 2026-11-10 about 21:40
|
||||
CET: no custom versions for now; design 47 G §373). A group's run on request builds its members against each
|
||||
package member's build by its digest and publishes no version; the tagged versions, the events `tag-wanted` (the
|
||||
checker's and any runner's), the builder's state `tag-asks` and its tools `builder_tag`, `builder_tag_asks` and
|
||||
`builder_untag` go, and nothing is numbered below a next version. The bullets below hold until that delivery.
|
||||
Tagged versions already published stay until a branch's end removes them as below, and nothing new is tagged. How
|
||||
it is checked: design 47's test 103.
|
||||
- **Asked by an event, never by a push** (ADR 0610 §1). The checker emits `tag-wanted` (repository, branch, head,
|
||||
tag), on a family of its own, `checker.asks`, kept seven days, apart from its verdicts, so a waiter on a verdict does
|
||||
not wake on it, for each head of a delivery group member that declares a package; a person asks through `builder_tag`.
|
||||
From the delivery of design 47's milestone G the checker goes, and the pipeline runner says `tag-wanted` instead, on
|
||||
its own seat `mesh-pipeline-runner`, for each member that declares a package of a run on request of a group not yet
|
||||
merged (ADR 0666 §18): a group merged together is one source revision whose packages are published before its
|
||||
dependents build, so only a run on request needs a tagged version. The
|
||||
Until the delivery of design 47's milestone G (below). The
|
||||
builder consumes the event on a durable consumer and keeps the ask in its own state `tag-asks`, removed when its
|
||||
branch is merged or deleted, or its pull request closed. An ask the builder has not answered within five minutes is narrated in the build log
|
||||
with what it waits on.
|
||||
@@ -353,9 +366,8 @@ the verb.
|
||||
and Go's `@latest` skips it. A package new in a group is numbered from its floor (`0.1.0-feat-x.1`).
|
||||
- **A group's check builds after `published`**: Go members by the tagged version, TypeScript members with their lock
|
||||
naming it and the registry's integrity; nothing is packed for a check, and a lone pull request's check publishes
|
||||
nothing. No `published` within the publish's bound (10 minutes) fails the check naming the package. From the
|
||||
delivery of design 47's milestone G the same holds for a group's run on request, whose pipeline steps build after
|
||||
`published`, and a step that gets no `published` within the bound ends failed, naming the package.
|
||||
nothing. No `published` within the publish's bound (10 minutes) fails the check naming the package. Until the
|
||||
delivery of design 47's milestone G (below).
|
||||
- **Removed with its branch**: on the forge bridge's `merged` event, its pull `closed`, or its branch-deleted event,
|
||||
heard on a durable consumer, the builder
|
||||
calls each seat's `remove`. It acknowledges the event only once every seat emitted `removed`; until then it retries
|
||||
|
||||
Reference in New Issue
Block a user