Compare commits
478
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
61f7a12f58 | ||
|
|
dfaabb6c77 | ||
|
|
00d6446fea | ||
|
|
1540d297b4 | ||
|
|
f3d57662c6 | ||
|
|
f1164f49ff | ||
|
|
f0559b3a71 | ||
|
|
d42bbc6138 | ||
|
|
7c21fef8e8 | ||
|
|
9b16d3fa07 | ||
|
|
53f72a6740 | ||
|
|
ffcf21d5bb | ||
|
|
a653f39e2e | ||
|
|
6d7217619f | ||
|
|
fbff9aa306 | ||
|
|
198d44382a | ||
|
|
4bebb4c1ed | ||
|
|
1fe45361c1 | ||
|
|
3af51ed4a1 | ||
|
|
ef446d6d8b | ||
|
|
3176501000 | ||
|
|
6ea3bcd416 | ||
|
|
0afc44ea6f | ||
|
|
c06d4dd03a | ||
|
|
162c721f08 | ||
|
|
508faf0cf6 | ||
|
|
853b3ae819 | ||
|
|
b93bf48739 | ||
|
|
0cf71a5515 | ||
|
|
f599b76165 | ||
|
|
3c2cd089e8 | ||
|
|
49f08c9e83 | ||
|
|
8c94adf744 | ||
|
|
307168a778 | ||
|
|
7319cc5e1b | ||
|
|
6fde0ff09d | ||
|
|
13be7087dc | ||
|
|
3433db0efb | ||
|
|
996cd3c391 | ||
|
|
38fdb88994 | ||
|
|
9c7fa01851 | ||
|
|
0f8c0812d9 | ||
|
|
fabb927f26 | ||
|
|
eea237e45b | ||
|
|
e428f47913 | ||
|
|
2cc1da4357 | ||
|
|
a000df7dbe | ||
|
|
91266f3007 | ||
|
|
0d18ad2daf | ||
|
|
0cef3fc826 | ||
|
|
50e6d16381 | ||
|
|
4b4802df52 | ||
|
|
c836029155 | ||
|
|
960cc77a7c | ||
|
|
69a8854835 | ||
|
|
b59a5893dd | ||
|
|
62d60bf43d | ||
|
|
922f7017b8 | ||
|
|
0bebde8bfe | ||
|
|
55da6d1af7 | ||
|
|
f6b2837e0a | ||
|
|
c55ea604d1 | ||
|
|
d17fa4efa7 | ||
|
|
77b05c2381 | ||
|
|
0cef71532a | ||
|
|
33208b3cd9 | ||
|
|
d33b17351c | ||
|
|
8c0b04e33c | ||
|
|
c8fc134444 | ||
|
|
f3e205fa72 | ||
|
|
7425b11b34 | ||
|
|
6cacd527e3 | ||
|
|
e95cc598a0 | ||
|
|
81e1964d0c | ||
|
|
287871724b | ||
|
|
2c6c7c03d3 | ||
|
|
1a25538c0a | ||
|
|
76cc85de24 | ||
|
|
4dabb3015a | ||
|
|
e19d61a4b0 | ||
|
|
1bea97bed2 | ||
|
|
df47ba6a22 | ||
|
|
a6b6c6aab9 | ||
|
|
1d8f7f06a2 | ||
|
|
dd3d82905c | ||
|
|
ae7fc40ad4 | ||
|
|
0631f43f25 | ||
|
|
0cbff22c6e | ||
|
|
43aac6b785 | ||
|
|
92592c9375 | ||
|
|
9d0d941190 | ||
|
|
94fe792721 | ||
|
|
c2b897e28c | ||
|
|
cc20946308 | ||
|
|
1c9a24a06d | ||
|
|
372123e744 | ||
|
|
6179eb5a7d | ||
|
|
0bf11925c4 | ||
|
|
2a0222bdbb | ||
|
|
2f1512bd1d | ||
|
|
ba1265100c | ||
|
|
b4563e5256 | ||
|
|
49c216e299 | ||
|
|
18feae5df3 | ||
|
|
a0cb55cfd3 | ||
|
|
ce96602bd9 | ||
|
|
bdecac13d6 | ||
|
|
67f21a7b7e | ||
|
|
d7a45777a4 | ||
|
|
b4dcdbc93d | ||
|
|
96bb5261f3 | ||
|
|
bd6c89af74 | ||
|
|
daa666d40a | ||
|
|
d6318938af | ||
|
|
5ecc060ff1 | ||
|
|
b24a4dc6f6 | ||
|
|
56b4225bcc | ||
|
|
3ce936a16a | ||
|
|
386079389e | ||
|
|
b123fb5a28 | ||
|
|
4d7921a087 | ||
|
|
34ac44de75 | ||
|
|
6a4fbb7892 | ||
|
|
66a8a7bc02 | ||
|
|
0732501b22 | ||
|
|
4f3268f6bb | ||
|
|
76ddab3ea7 | ||
|
|
551da194b7 | ||
|
|
166ad75748 | ||
|
|
f9d3ecf2c7 | ||
|
|
5f49bfd818 | ||
|
|
dae41a142f | ||
|
|
689ab797a1 | ||
|
|
4baf34c7c3 | ||
|
|
e6a73d8f59 | ||
|
|
ee0b4a271f | ||
|
|
6b07fe2041 | ||
|
|
44975de2e1 | ||
|
|
cb6cabdf5e | ||
|
|
bfa93e5f48 | ||
|
|
50c9123d9e | ||
|
|
f081c9a23b | ||
|
|
1c75f01a1c | ||
|
|
a09270d6b8 | ||
|
|
bbeb890399 | ||
|
|
ccacffdc90 | ||
|
|
0928ed52be | ||
|
|
a6f811fce0 | ||
|
|
39f7ecce8d | ||
|
|
0b3974d773 | ||
|
|
9c39e6be55 | ||
|
|
bbc65d5e7a | ||
|
|
43dc902a0c | ||
|
|
adbf113aa8 | ||
|
|
514eeb2a2e | ||
|
|
bdd86986de | ||
|
|
cff74e8419 | ||
|
|
4ac1cfb0b1 | ||
|
|
9ae68e0dc0 | ||
|
|
1dd4daf184 | ||
|
|
9bde22296e | ||
|
|
325bf58483 | ||
|
|
9ad9511791 | ||
|
|
ef87d14e27 | ||
|
|
d28cabd28e | ||
|
|
7d2c80b9c0 | ||
|
|
eb0e67753f | ||
|
|
1e309472da | ||
|
|
420f2fd9c1 | ||
|
|
57c1404701 | ||
|
|
686bff9021 | ||
|
|
25df48ad70 | ||
|
|
96be83fcfc | ||
|
|
61bf1215e7 | ||
|
|
6938f6053d | ||
|
|
c1bd8d113f | ||
|
|
2378f3f6c8 | ||
|
|
51e3c7b4d8 | ||
|
|
b37b330221 | ||
|
|
532aa1a379 | ||
|
|
80d44d8547 | ||
|
|
3868280be2 | ||
|
|
8f9954bc5d | ||
|
|
ca8e13a306 | ||
|
|
5d9961a789 | ||
|
|
180a096a3e | ||
|
|
9581cd5e26 | ||
|
|
e69b81b8ea | ||
|
|
2c95a12b8f | ||
|
|
4b8ef634ba | ||
|
|
b5d19f3972 | ||
|
|
7225f752c6 | ||
|
|
4eabfba370 | ||
|
|
bb04c5b089 | ||
|
|
a3bb692725 | ||
|
|
56b3cd6bc3 | ||
|
|
7de86e7af9 | ||
|
|
2359aea5e0 | ||
|
|
91d0ba10a2 | ||
|
|
5502609780 | ||
|
|
89865f27d8 | ||
|
|
ff43506156 | ||
|
|
a74591dc71 | ||
|
|
1942c23c4a | ||
|
|
580678e948 | ||
|
|
b6b4e0232c | ||
|
|
dd89b437d2 | ||
|
|
b27004f74d | ||
|
|
d757200010 | ||
|
|
b463a1518e | ||
|
|
21004f50e2 | ||
|
|
0ca76cf54f | ||
|
|
75857d9eb7 | ||
|
|
d433411fcd | ||
|
|
8f08ef178f | ||
|
|
2eb4059897 | ||
|
|
fd3d7371bc | ||
|
|
3982c57e98 | ||
|
|
513920b66b | ||
|
|
945a74b6f2 | ||
|
|
ecf2a05179 | ||
|
|
f906b7c8b3 | ||
|
|
0347a77bcb | ||
|
|
16316da868 | ||
|
|
284c32062e | ||
|
|
96dadc6fde | ||
|
|
cc1c5cd5e1 | ||
|
|
a622019bd5 | ||
|
|
fa97929f21 | ||
|
|
76c92e4c1e | ||
|
|
bdb4efc160 | ||
|
|
68148d886b | ||
|
|
304ae5a5fb | ||
|
|
aa52fa5345 | ||
|
|
e671d865d3 | ||
|
|
62b03ab4cd | ||
|
|
5edbcdac6c | ||
|
|
19e7da66d8 | ||
|
|
c1c7353191 | ||
|
|
59cf3c25fd | ||
|
|
cd3428755a | ||
|
|
7f846906ee | ||
|
|
42e9484261 | ||
|
|
83fab59cac | ||
|
|
384ceb714d | ||
|
|
9ea4b009ed | ||
|
|
72bc73df27 | ||
|
|
60e23053c3 | ||
|
|
d71cbe8b49 | ||
|
|
c79c69bfff | ||
|
|
93a3e46923 | ||
|
|
b269b5f3fa | ||
|
|
c6943ee76f | ||
|
|
6e43789deb | ||
|
|
ff60461f5b | ||
|
|
3608c10b5c | ||
|
|
10d6d75902 | ||
|
|
16c2f1339c | ||
|
|
e2e464a046 | ||
|
|
8a45d966bd | ||
|
|
8231fd0acb | ||
|
|
14a0c6c44f | ||
|
|
bb99034295 | ||
|
|
fd8c4aaeb7 | ||
|
|
12a3ef6960 | ||
|
|
79181abfa7 | ||
|
|
520e95a10c | ||
|
|
12b7e246e4 | ||
|
|
328e17112e | ||
|
|
36b66c0b54 | ||
|
|
f62a73d757 | ||
|
|
ff464265b9 | ||
|
|
8884fc9ee7 | ||
|
|
c94cbff169 | ||
|
|
2ed3c5d368 | ||
|
|
5880f85e5b | ||
|
|
9bfb8b0211 | ||
|
|
9c23309b38 | ||
|
|
e88cce45dd | ||
|
|
be550d1790 | ||
|
|
92f967f542 | ||
|
|
c2aae05b59 | ||
|
|
cbf12d3380 | ||
|
|
849a4012d6 | ||
|
|
32302e0bd1 | ||
|
|
017e20504a | ||
|
|
d7321df3e5 | ||
|
|
e82887d67c | ||
|
|
605e0878a5 | ||
|
|
cebac2e791 | ||
|
|
661fb8a742 | ||
|
|
6b7adc5ec2 | ||
|
|
77318ca60e | ||
|
|
31cd62aeec | ||
|
|
2407183c70 | ||
|
|
399ac934f6 | ||
|
|
a550fb9256 | ||
|
|
ec6aae9997 | ||
|
|
1ac43e4ddf | ||
|
|
cb1ce7291f | ||
|
|
8fd85c6768 | ||
|
|
0fc357c96b | ||
|
|
d84b7cbb57 | ||
|
|
36d5b50d5b | ||
|
|
64ff3fd4e9 | ||
|
|
2b59494c30 | ||
|
|
782f90c003 | ||
|
|
f0a940463b | ||
|
|
5385c798c0 | ||
|
|
cf08f6e69b | ||
|
|
163fe51f96 | ||
|
|
c81a186a3d | ||
|
|
acd7f1f588 | ||
|
|
6664193aac | ||
|
|
d47f617ad5 | ||
|
|
84ef09d4b4 | ||
|
|
709ad9de59 | ||
|
|
a4d7d44cd0 | ||
|
|
47332934b8 | ||
|
|
b6c99f171d | ||
|
|
e34c74c2f8 | ||
|
|
f44b0fc90b | ||
|
|
c91aafb6dd | ||
|
|
1209008aba | ||
|
|
25449d1d4f | ||
|
|
dcaad0c6a4 | ||
|
|
66b3d0c7f6 | ||
|
|
92929d55ef | ||
|
|
0bb30e6bc9 | ||
|
|
e69d2693de | ||
|
|
b90489afc7 | ||
|
|
bca45ea0df | ||
|
|
f48d5f5091 | ||
|
|
2ff96d1b7e | ||
|
|
e68d3a892e | ||
|
|
de9d3378af | ||
|
|
547006dd59 | ||
|
|
2945e57a4a | ||
|
|
fc5ec32b90 | ||
|
|
242bae0d0c | ||
|
|
928aa7e5ba | ||
|
|
4d4815c83d | ||
|
|
975f83f045 | ||
|
|
acc54c16b9 | ||
|
|
77cf51b4c7 | ||
|
|
5f90d599c6 | ||
|
|
987283dd30 | ||
|
|
0da67d6323 | ||
|
|
2ecb831355 | ||
|
|
59d9f397e2 | ||
|
|
7b1607d933 | ||
|
|
bfc7272b3c | ||
|
|
37fdc292f7 | ||
|
|
21ab7b1bdf | ||
|
|
e17cffa59e | ||
|
|
dcdfbc12a6 | ||
|
|
7dd6563ab5 | ||
|
|
eb5cc23a86 | ||
|
|
d07de2840d | ||
|
|
2ab0507440 | ||
|
|
c47f9ea48e | ||
|
|
dd462aa1ff | ||
|
|
c0736710e8 | ||
|
|
bedc92e251 | ||
|
|
d93dddf5b3 | ||
|
|
2a52d91cc6 | ||
|
|
ecaf070846 | ||
|
|
2631a11447 | ||
|
|
39f7ae7203 | ||
|
|
6517bbebf0 | ||
|
|
4de493a784 | ||
|
|
79214618f3 | ||
|
|
8fa037074c | ||
|
|
f07c337c22 | ||
|
|
d595d08042 | ||
|
|
eaa6de7faf | ||
|
|
2d4b34c51c | ||
|
|
d4c31d4ff0 | ||
|
|
71cb172953 | ||
|
|
fa74c6d594 | ||
|
|
97c8c81e82 | ||
|
|
b5e5a35460 | ||
|
|
3c0389f74e | ||
|
|
99e2966bb7 | ||
|
|
42054c599c | ||
|
|
f887e777b2 | ||
|
|
bc9ba62959 | ||
|
|
4353e7c018 | ||
|
|
ca8cda69d9 | ||
|
|
a7b72d49d2 | ||
|
|
2c399ac708 | ||
|
|
8c307e0e7a | ||
|
|
2d6da3f34d | ||
|
|
45b43ce81c | ||
|
|
13ad18268f | ||
|
|
5be43e0193 | ||
|
|
4e0f340916 | ||
|
|
12c0f66fab | ||
|
|
6ccd7c3edf | ||
|
|
ea02e537a3 | ||
|
|
60872e67e9 | ||
|
|
9cf4d63c9c | ||
|
|
1a2d31b82f | ||
|
|
267f1ef0de | ||
|
|
23cba849e3 | ||
|
|
3723b2ea41 | ||
|
|
62e3715af4 | ||
|
|
18ce04f6e8 | ||
|
|
91f60c7075 | ||
|
|
4169ded5cd | ||
|
|
d9dd5dab67 | ||
|
|
2829a47ea0 | ||
|
|
09cf7d609d | ||
|
|
547eec3373 | ||
|
|
d2094f657e | ||
|
|
ee80b4d84b | ||
|
|
14c3e90332 | ||
|
|
cac334e749 | ||
|
|
aad8f7c921 | ||
|
|
b20b382cd9 | ||
|
|
8abbb539fd | ||
|
|
f988c23d1e | ||
|
|
fd45f01929 | ||
|
|
f0b9c73a9f | ||
|
|
17ab2d028e | ||
|
|
9a60a312a0 | ||
|
|
1de67e76ed | ||
|
|
1088d86e5c | ||
|
|
2ce9268504 | ||
|
|
39ab7efb6b | ||
|
|
6c5f8aabb0 | ||
|
|
3d56f25942 | ||
|
|
9da181e12d | ||
|
|
8b9b450855 | ||
|
|
16f4fd8696 | ||
|
|
ee543b8601 | ||
|
|
7981d72d9b | ||
|
|
842071859a | ||
|
|
11054da240 | ||
|
|
46b6b74148 | ||
|
|
706e76b566 | ||
|
|
4b2eb0bcf4 | ||
|
|
634b4ea49e | ||
|
|
b6380d0958 | ||
|
|
dbe9d711ea | ||
|
|
de9f6d3353 | ||
|
|
d5e7d42d17 | ||
|
|
232454cf76 | ||
|
|
f55a6e7927 | ||
|
|
f6f82721d5 | ||
|
|
98e8bc395b | ||
|
|
ed95207361 | ||
|
|
525a9590cd | ||
|
|
6bc258db0d | ||
|
|
5f04a5e3af | ||
|
|
087e17c799 | ||
|
|
19f5ad86d2 | ||
|
|
5d7a96fe66 | ||
|
|
5aa4510f0f | ||
|
|
c1a647e9bb | ||
|
|
8dffde7f33 | ||
|
|
240f6401ce | ||
|
|
77a6a9aa68 | ||
|
|
9e619006c7 | ||
|
|
8af69b2082 | ||
|
|
2c67b2e53b | ||
|
|
be264026b5 | ||
|
|
a95c0d6d98 | ||
|
|
c1065d9868 | ||
|
|
0e9b6e5286 | ||
|
|
64b9ffe8c1 | ||
|
|
c5adb7fe48 | ||
|
|
61149124f8 | ||
|
|
591297f02e | ||
|
|
e9a2aaf253 | ||
|
|
904f5bfac5 | ||
|
|
da161cdbf1 | ||
|
|
916be3a63c |
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: gap-surveyor
|
||||
description: Holds the code on main of the Novox mesh against one part's specification (a spec-reader's file) and writes that part's gap table (hq playbook 07, before a prepare, when a design's parts are to be delivered again) - per design line what is built, built otherwise, contradicted or missing, where in code, how big the gap is, the leftovers of an earlier model, and which build runs live on each machine against main. Read-only on the mesh and every working copy; writes only the one file the caller names.
|
||||
tools: Read, Grep, Glob, Bash, Write, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search
|
||||
model: opus
|
||||
---
|
||||
|
||||
You hold the code of the Novox mesh against the specification of one part of a design and write the gap table
|
||||
the lead plans from. The caller names the part, its specification file, the repositories and modules that hold
|
||||
it, the facts about what runs live on the machines that the caller already knows, and the file to write.
|
||||
|
||||
Read first: hq's glossary (`00-META/glossary.md`) and principles (`00-META/principles.md`), then the
|
||||
specification file whole. Then the code.
|
||||
|
||||
How you read:
|
||||
|
||||
- **Code on main only, never a working copy's checkout.** Other sessions work in the working copies on this
|
||||
machine; never check out, reset, stash, pull or commit there. Run `git fetch origin` in the repository and
|
||||
read with `git show origin/main:<path>`, `git grep <words> origin/main`, `git ls-tree -r origin/main` and
|
||||
`git log origin/main`. A branch the caller names (a held pull request) is read the same way as
|
||||
`origin/<branch>`, and every fact from it is said to be from that branch.
|
||||
- **Each fact with its source:** the repository, the short commit of `origin/main` you read, the module and the
|
||||
function or type; never a line number.
|
||||
- **What runs live** you read through the mesh MCP server with read tools only: `mesh_machine` for a machine's
|
||||
modules, a module's own read tools and the seat verbs that read its state (find them with `mesh_search`).
|
||||
Call no verb that writes, starts, cancels or restarts anything.
|
||||
- **The tests count:** per module, how many unit tests and how many integration tests (`//go:build
|
||||
integration`) main holds, and whether one integration test starts the module whole against a bus and a store.
|
||||
|
||||
Write the file the caller names, in this shape:
|
||||
|
||||
1. **The gap table**, one row per design line of the specification, in its order: the citation; its status, one
|
||||
of *built* (the code does what the line says, by its contract), *built otherwise* (the outcome is there but by
|
||||
another path: a poll, a timer, a direct call, a shared file, a read of another part's state, a comparison in
|
||||
place of an event), *contradicts* (the code does something the line forbids or that a replaced line said),
|
||||
*missing*, or *not judged* (say why); where it lives (repository, module, function or type); what the code
|
||||
does instead, in one sentence, when it is not *built*; and the size of the gap, S (one function, under an
|
||||
hour), M (one module's part, a day), L (the part's shape, more than a day).
|
||||
2. **The leftovers**: every mechanism in these modules that no line of the specification asks for, or that a
|
||||
replaced line asked for: what it is, where, what it does, and which line it contradicts or none. A sweep, a
|
||||
poll, a retry loop, a stand-in, a hand-act path, a per-merge path count.
|
||||
3. **Live against main**, a table per module of the part: the machine, the build that runs (its version or
|
||||
fingerprint as the machine's tools say it), whether that build is main's or a hand-placed one, and what main
|
||||
has that it lacks.
|
||||
4. **The tests**: per module, the counts, whether an integration test starts the module whole, and what the
|
||||
tests would not catch of the gaps above.
|
||||
5. **Fix in place or write again**, one paragraph per module: your judgement from the table, with the reason:
|
||||
the share of lines *built*, how many gaps are L, whether the module's shape is the specification's (its
|
||||
events, verbs, kept data) or an earlier model's. A recommendation, not a decision.
|
||||
6. **What you could not read**, and every fact you guessed, said as a guess with how to check it.
|
||||
|
||||
Report to the caller in under 400 words: the file's path, the counts per status, the three gaps that matter most,
|
||||
your fix-or-rewrite recommendation per module in one line each, and what you could not read. Plain words in the
|
||||
glossary's words.
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: mesh-code-reviewer
|
||||
description: Reviews one change of the Novox mesh before it is pushed (hq playbook 07, the review; at most three rounds): each commit against the design lines it cites, code no design line asks for, the build maps' What exists today, and whether its tests prove it. Read-only; reports findings, never fixes, and never re-judges the design.
|
||||
description: Reviews one change of the Novox mesh before it is pushed (hq playbook 07, the review; at most three rounds): each commit against the design lines it cites, code no design line asks for, the build maps' What exists today, whether its tests prove it without standing in for another part of the mesh, and each changed module against the live mesh with the order of delivery it needs. Read-only; reports findings, never fixes, and never re-judges the design.
|
||||
tools: Read, Grep, Glob, Bash, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search
|
||||
model: opus
|
||||
---
|
||||
@@ -26,10 +26,22 @@ questions are.
|
||||
- an interaction the design does not place that is not a mesh path: one module naming another, reading another's
|
||||
internals or being special-cased in another part; a module's name in shared code; state only in memory; a poll or
|
||||
a timer where an event exists;
|
||||
- a value written into the code that can differ between machines, modules or over time (a port, a path, a bound, a
|
||||
cap, a name, a time) and is not a setting with a default (principle 11); name the setting it should be, eagerly;
|
||||
- a module that writes another module's file or state, or anything in another module's place, instead of giving it
|
||||
through a provision or a contribution that module declares (principle 12);
|
||||
- an effect or a reader of the build map's `What exists today` whose fate the diff does not carry out (run its
|
||||
searches again on the reviewed tree), or one the search finds and the answer omits;
|
||||
- a test that does not fail without its change (check it by taking the change out in a copy), an acceptance
|
||||
criterion with no test, a new test function where the repository is over budget, real sleeping;
|
||||
- **a test that stands in for another part of the mesh, by rule** (playbook 07 step 2, item 11): one that creates a
|
||||
stream, a consumer or a process taking a work queue's asks where the bus module, the grants part or the
|
||||
node-engine should, or fakes a seat's holder in a whole test. The fix is composing what it needs with the parts' own
|
||||
composers from the module's bus-shape sheet (step 0, item 11); a composer it cannot import is a gap of the build and
|
||||
delivery system, named for the lead. List every new or changed test that creates bus state or fakes a seat's
|
||||
holder, each with the composer that should make it;
|
||||
- a changed module whose bus shape differs from its bus-shape sheet (its manifest sections, accounts, streams and
|
||||
subjects, work queues and who takes their asks, who creates each);
|
||||
- vet or tests that fail: run `go vet ./...`, `go vet -tags integration ./...` and `go test ./...` in every
|
||||
touched module, with the siblings placed as the build map's one placement says;
|
||||
- a change to any `module.json` reported without the manifest validator's verdicts (every manifest whose verdict
|
||||
@@ -40,6 +52,16 @@ questions are.
|
||||
principle you know of, name the line and why in a note; the lead brings it to the operator. The code follows the
|
||||
line until the design changes.
|
||||
|
||||
**Read each changed module against the live mesh, and name the order of delivery** (playbook 07 step 2, item 12;
|
||||
the operator, 2026-11-22). Through the mesh MCP server's tools, read what runs on the nodes now: each node's haves of
|
||||
every module the change touches or relies on, and which parts still carry the form the change replaces (the tool
|
||||
runner, the build modules, the node-engine, the indexer and its manifest validator, the grants part). For each, ask
|
||||
whether its running version can take in, judge, build, compose or page the new form. Write a section `Live mesh`:
|
||||
each such part with the build read on each node and the time read, then the order of delivery the change needs (the
|
||||
parts that judge, build, compose or page first, then the modules that use them), each step an ordering edge the
|
||||
delivery plan derives, or a gap of the build and delivery system for the lead. A part on the old form that no step of
|
||||
the order brings over is a finding.
|
||||
|
||||
**Prove it against the live mesh, never a re-creation.** When the change answers a fault seen on the machines,
|
||||
check what it claims against the state the mesh itself uses, read through its tools (the manifest validator's own verdicts in the indexer,
|
||||
the packages state, the store, a node's haves), never against a copy you rebuilt: a manifest validator run without the seat list,
|
||||
@@ -49,5 +71,6 @@ such in the report.
|
||||
Anything else (hardening, a further case, a nicer form) is a note, never a round. Read only: no edits, no git
|
||||
write, no verb that writes, never ssh. Use a temporary directory under `/var/tmp`.
|
||||
|
||||
Answer playbook 07 step 2 item 10's two questions, one line each. Answer **APPROVED at** the full commit ids, or numbered findings each with file:line, the design line it concerns,
|
||||
what is wrong, and the fix; design questions and notes apart. Under 25 lines, glossary words only.
|
||||
Answer playbook 07 step 2 item 10's two questions, one line each; then the list of tests of item 11 and the section
|
||||
`Live mesh` of item 12 (a report without them is not an approval). Answer **APPROVED at** the full commit ids, or numbered findings each with file:line, the design line it concerns,
|
||||
what is wrong, and the fix; design questions and notes apart. Under 40 lines, glossary words only.
|
||||
|
||||
@@ -35,7 +35,11 @@ A fact the build map got wrong (a file moved, a function renamed) you say to the
|
||||
**How you work.** Worktrees from `origin/main` on the branch the handover names, subtasks in the build map's order:
|
||||
one that uses a contract, type, verb or package another subtask adds starts from that subtask's commit. Commit per
|
||||
subtask, its label in the subject and a line `Builds: design NN M §n, …` in the body, locally only: never push, never open a pull request, never call a verb that writes on the mesh (reads are fine). Never
|
||||
ssh, never a shell helper for the mesh. Tests: every change carries a test that fails without it (check it);
|
||||
ssh, never a shell helper for the mesh. Tests: every change carries a test that fails without it (check it), and no test stands in for another part of the
|
||||
mesh (playbook 07 step 2, item 11): none creates a stream, a consumer or a process taking a work queue's asks that the
|
||||
bus module, the grants part or the node-engine should, and none fakes a seat's holder in a whole test; compose what a
|
||||
test needs with the parts' own composers from the module's bus-shape sheet, and a composer you cannot import is a
|
||||
question for the lead;
|
||||
rows or subtests in existing tests where the repository is over the test budget the instructions set; no real
|
||||
sleeping. Run `go vet ./...`, `go vet -tags integration ./...` and `go test ./...` in every touched module as
|
||||
the running checker places siblings (playbook 07). Once per head you report, not per commit, also run the integration tests of
|
||||
|
||||
@@ -1,13 +1,14 @@
|
||||
---
|
||||
name: mesh-preparer
|
||||
description: Prepares one milestone or small fix of the Novox mesh before any code is written (hq playbook 07, the prepare step; playbook 08), from the milestone's part of its design and the design's main file, read whole, then the code each design line lands in - one build map per repository (where each design line lands in code, what exists there today and what relies on it, the subtasks and their order), the list of design questions the design does not answer, and the list of places where a design line and the code disagree. Decides nothing; writes only its build maps and the milestone file's two lists.
|
||||
description: Prepares one milestone or small fix of the Novox mesh before any code is written (hq playbook 07, the prepare step; playbook 08), from the milestone's part of its design and the design's main file, read whole, then the code each design line lands in - one build map per repository (where each design line lands in code, what exists there today and what relies on it, the subtasks and their order), the list of design questions the design does not answer, and the list of places where a design line and the code disagree. Decides nothing; writes only its build maps, the milestone file's two lists and a bus-shape sheet per module.
|
||||
tools: Read, Grep, Glob, Bash, Write, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search, SendMessage
|
||||
model: opus
|
||||
---
|
||||
|
||||
You prepare one change of the Novox mesh for the lead who started you. The caller's handover names the issue, the
|
||||
design and its milestone part at an hq commit, and where your files go (playbook 07, step 0). You write the build
|
||||
maps and the milestone file's sections `Design questions` and `Design meets code`, nothing else; you call no verb that writes and make no git
|
||||
maps, the milestone file's sections `Design questions` and `Design meets code`, and a bus-shape sheet per module with
|
||||
the test that composes it, in your own worktree, nothing else; you call no verb that writes and make no git
|
||||
write.
|
||||
|
||||
**The design is your only input for what is built.** Read the milestone part and the design's main file whole, at the commit the
|
||||
@@ -38,6 +39,17 @@ code`: the design line, the code (file:line at the commit read, each repository'
|
||||
which of the three it is, and your recommendation, said as one. The lead answers these against the principles before
|
||||
develop starts, as it does the design questions; you answer none.
|
||||
|
||||
**End with a bus-shape sheet per module, composed in a test** (playbook 07 step 0, item 11; the operator,
|
||||
2026-11-22). For each module the milestone adds or changes, write `.work/<slug>/<module>.bus.md`: its manifest
|
||||
sections (each process, its `bus`, `serves` and `requires`), its bus accounts, its streams and their subjects, its
|
||||
work queues and the process that takes each queue's asks, its durable consumers, and who creates each (the bus module
|
||||
from `requires`, the grants part, the module's own process), every row citing its design line. Then judge it in a
|
||||
test in a worktree of your own under `/var/tmp`: the manifest validator with the live seat list, and the grants part's
|
||||
composer and the node-engine's composer (the composition of `mesh-delivery-sdk`) composing the manifests the sheet
|
||||
describes. A refusal is an entry under `Design meets code`; a row no design line gives is a design question; a composer
|
||||
the test cannot import you report to the lead as a gap of the build and delivery system. Name the test and its result
|
||||
at the top of the sheet.
|
||||
|
||||
**Everything the design does not say is a design question, never your answer.** A reader or an effect with no fate,
|
||||
a field's form, a key and who deletes it, a bound, a caller, an owner, a tool for a new state, an interaction whose
|
||||
seat, verb, event or provision the design does not name, a live state that contradicts a design line: list
|
||||
@@ -47,6 +59,7 @@ anything should be, no finding of your own and no ruling; where you think a desi
|
||||
principles, it is a design question too, and you map the line as written.
|
||||
|
||||
Report to the caller in under 30 lines: the build maps' paths, the count of design lines mapped per repository and
|
||||
any line not mapped, the subtasks' order, the design questions and the entries of `Design meets code`, one line each with your
|
||||
recommendation. Glossary
|
||||
any line not mapped, the subtasks' order, the bus-shape sheets' paths and their tests' results, the design questions and the entries of
|
||||
`Design meets code`, one line each with your recommendation, and their count: more than ten together send the
|
||||
milestone back to its design (step 0b, item 5). Glossary
|
||||
words only; a guess is said as one.
|
||||
|
||||
@@ -23,6 +23,12 @@ without that read on each machine the module is wanted on.
|
||||
Loop: wait with `mesh_wait` on the event family (its answer only wakes you), then read the state from the verb
|
||||
the handover names; never report a state you did not read in that round.
|
||||
|
||||
**A state that does not change is not "nothing happened".** A reservation, a queue or a key can stay as it was while
|
||||
the work behind it already failed. Each round, also read the journal of the program that does the work
|
||||
(`<node>/node-service-manager.journal` with its unit, the last lines since your previous read) and report any failure
|
||||
line word for word. A verb that times out or refuses twice is a finding of its own: report it at once, never read
|
||||
around it. You have no clock: take times from the tools' answers, never guess them.
|
||||
|
||||
**A report along the way does not end you.** Your final message ends you, and then nothing watches. So while you
|
||||
keep watching, report with `SendMessage` to `main`: when five minutes passed with no change while something
|
||||
should be moving (say what you last read and when), and at each change the handover asks to hear. Then go on
|
||||
|
||||
@@ -25,7 +25,9 @@ write.
|
||||
What you judge:
|
||||
|
||||
- Seams: where each piece of state lives on the bus (key-value bucket, stream, object store) and which module owns it; which seat, verb or event joins two parts; any link that is not NATS-native (a poll, a timer, HTTP between modules, a shared file, state only in memory); whether a form the manifest lacks is named with its cost (a mesh-sdk change rebuilds every module).
|
||||
- Seams inside a module, at run time: for every event, queue and piece of state the subject adds or changes, which processes read it on each node (a module's program, its tool runner, any other process its manifest names, the same module on several nodes), and whether each gets every item it needs. A NATS durable consumer or a queue group hands each message to one reader only: two processes reading under one name split the messages silently, and the bus refuses nothing. A design line that names one reading place per module where more than one process reads is a **must**; only a work queue, where one reader per item is the point, is shared. (The operator, 2026-11-14: on ace the assigner's program and its tool runner read one durable consumer, and the runner took all 178 first registrations the program acts on; lead answer A-397.)
|
||||
- Settings and ownership: every value that can differ between machines, modules or over time is a setting with a
|
||||
default, never hard-coded (principle 11), and the design names it; no module writes another module's file or state:
|
||||
what one module needs from another goes through a provision or a contribution that module declares (principle 12).
|
||||
- Tools: for every new piece of state a tool that reads it, and for every new behaviour a tool that steers it (do by hand, ask again, drop, repair, re-check), as the instruction tools-are-how-a-module-is-spoken-to says.
|
||||
|
||||
Judge only whether the settled direction or design is complete and sound in your two architectural domains,
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
name: spec-reader
|
||||
description: Reads one part of a to-be design of the Novox mesh with the records that decide it, and writes that part's specification as a list of its design lines with their checks (hq playbook 07, before a prepare, when a design's parts are to be delivered again) - what the part does, the seats, verbs, events and kept data it names, which later answers amend each line, and what the design leaves open. Reads no code; writes only the one file the caller names.
|
||||
tools: Read, Grep, Glob, Bash, Write, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search
|
||||
model: opus
|
||||
---
|
||||
|
||||
You read one part of a to-be design of the Novox mesh and write its specification: everything the design and
|
||||
its records say that part does, as a list a builder and a surveyor can hold code against. The caller names the
|
||||
part, the design's files and sections to read, the records to read in the knowledge base, the other parts (so you
|
||||
know where your part ends), and the file to write.
|
||||
|
||||
Read first: hq's glossary (`00-META/glossary.md`) and principles (`00-META/principles.md`), then the design's
|
||||
main file sections the caller names, then the milestone part's files whole where the caller says whole, and the
|
||||
answer files (the later design lines and the lead's answers) where they name your part: find them with `grep`
|
||||
for the part's words (its seat, its module, its verbs, its events) and read each matching answer whole. Then the
|
||||
records: `knowledge-base.get` with `reasoning: true` and `bound: 65536` for each record the caller names, and
|
||||
`knowledge-base.ask` for the part's words to find records the caller did not name.
|
||||
|
||||
Never read code, a working copy or a repository's history: the specification says what should be, and the code
|
||||
is the surveyor's job. Through the mesh MCP server only reads of the knowledge base.
|
||||
|
||||
Write the file the caller names, in this shape:
|
||||
|
||||
1. **What the part does**, in ten lines or fewer, in the glossary's words: its seat, the module that holds it,
|
||||
its verbs, the events it publishes and consumes, the kept data it owns on the bus (state, streams, objects),
|
||||
and the parts it talks to.
|
||||
2. **The design lines**, a table, one row per line: the line's citation (`design 47 §n`, `design 47 G §n`,
|
||||
`A-n`), one sentence of what it says, the record that decides it (`ADR nnnn §k`), how it is checked (the
|
||||
acceptance test, the tool that reads it, the event that says it), and the later line or answer that amends or
|
||||
replaces it, when one does. A line a later line replaced is kept in the table, marked replaced, so the
|
||||
surveyor can tell a leftover from a build.
|
||||
3. **The interactions**, one row per edge with another part: the event or verb, who publishes or serves, who
|
||||
consumes or calls, and the line that decides it. A direct call, a shared file or a read of another part's state
|
||||
is marked as such: it is a finding for the review, never a solution.
|
||||
4. **What retires** at this part's delivery, with its line.
|
||||
5. **What the design leaves open** for this part: a question no line answers, each in one sentence, with the
|
||||
principle you think settles it or "no principle settles it". Decide nothing.
|
||||
6. **What you could not read**: a record the knowledge base cut, a file you did not reach.
|
||||
|
||||
Report to the caller in under 400 words: the file's path, the counts (lines, interactions, open questions), the
|
||||
three findings that matter most for delivering this part again, and what you could not read. Separate fact from
|
||||
guess. Plain words in the glossary's words.
|
||||
+63
-6
@@ -600,7 +600,46 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
|
||||
registering and changing one are trusted acts (ADR 0666 §2). The mesh knows modules, and a repository only as a
|
||||
module's git origin.
|
||||
- **watched branch** — a branch a module's registration names, whose commits start that module's pipeline and which a
|
||||
placement may choose for a node; registering one the forge does not protect is refused (ADR 0666 §3, §6).
|
||||
placement may choose for a node; from milestone H's delivery it need not be protected, and nothing reads its
|
||||
protection (ADR 0682 §13, which ends ADR 0666 §3's refusal and §11's judgement).
|
||||
- **merge call** — one call of the seat `git`'s verb `merge-pull` naming one or more pull requests, each at the head
|
||||
its caller names: from the delivery of design 47's milestone H the start of their delivery and, with two or more,
|
||||
their group; the forge module judges every member before it merges any and says the call as its event
|
||||
`merge-called`, from which the gate names the merged heads one source revision (ADR 0682). Not a merge made in the
|
||||
forge's own screen, which delivers nothing and leaves an **untaken head**.
|
||||
*Not:* ~~kick-off~~ (hq)
|
||||
- **untaken head** — a watched branch's head that the forge bridge said moved (`head-moved`) and that no source revision
|
||||
names within the gate's setting `untaken-bound`: a head moved outside the mesh, raised as the gate's finding
|
||||
`head-untaken` and delivered by nothing but a later merge call or the gate's hand take (ADR 0682; design 47 H §740).
|
||||
Not a pending revision, which is a source revision not yet taken in.
|
||||
*Not:* ~~merge-untaken~~ (hq)
|
||||
- **`merge-called`** — the seat `git`'s event saying one merge call: its members that landed, each at its merge
|
||||
commit, and those refused; the gate's one input that names a source revision (ADR 0682 §1; design 47 H §736).
|
||||
*Not:* ~~merge notice~~ (hq)
|
||||
- **`head-moved`** — the forge bridge's one message for a move of a watched branch's head, however it moved, heard by
|
||||
the gate's watchdog alone (ADR 0682 §3; design 47 H §739). It replaces the messages `merged` and `pushed`.
|
||||
*Not:* ~~pushed message~~ (hq)
|
||||
- **`head-untaken`** — the gate's finding for an **untaken head**, raised when `untaken-bound` passes (ADR 0682 §3).
|
||||
*Not:* ~~untaken merge~~ (hq)
|
||||
- **`untaken-bound`** — the gate's setting, default 10 minutes, after which a head moved and not named by a source
|
||||
revision is `head-untaken` (ADR 0682 §3).
|
||||
*Not:* ~~take-in bound~~ (hq)
|
||||
- **`pipelines-at-once`** — the runner's setting, 1 to 8, default 1: how many pipelines have their steps asked at
|
||||
once; the rest wait in order (ADR 0682 §7; design 47 H §748).
|
||||
*Not:* ~~concurrent pipelines~~ (hq)
|
||||
- **`tier-late`** — the assigner's finding when one tier of a pipeline's movers does not run on its present machines
|
||||
within `tier-bound`: no later tier is written and the delivery record ends `failed` (ADR 0682 §8, §9; design 47 H
|
||||
§751).
|
||||
*Not:* ~~late tier~~ (hq)
|
||||
- **take-in** — the indexer's act on one source revision of a watched branch: the commits it names, the
|
||||
build-input fingerprints of the modules registered for those repositories, and one catalog revision of that branch,
|
||||
said as `take-in.taken` naming the **movers**; it validates no manifest (that is the pipeline step `validate`) and
|
||||
holds nothing for a named indexer (ADR 0682; A-476). Not a merge: what is taken in is a source revision the gate named.
|
||||
*Not:* ~~merge take-in~~ (hq)
|
||||
- **mover** — a module whose build-input fingerprint changed in a take-in, or a code dependent of one (a module, in any
|
||||
repository, that imports a package of one): the modules a take-in's one pipeline runs and delivers (A-476a; ADR
|
||||
0573 §3; ADR 0682). Not every module of the revision.
|
||||
*Not:* ~~moving module~~ (hq)
|
||||
- **run on request** — a pipeline run for a named commit or group that delivers nothing, asked by the runner's verb
|
||||
`run`; the indexer builds its candidate from the runner's `run-started` (ADR 0666 §18).
|
||||
- **artifact reference** — an artifact written `<module>:<artifact>`, such as `mesh-grants:program`: the end of a
|
||||
@@ -620,6 +659,15 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
|
||||
- **composition step** — the pipeline step that composes each machine's declaration with a change, by the composer built
|
||||
from its heads in the sandbox, refusing a change in which two modules own one path; served by the seat `mesh-wants`
|
||||
(ADR 0666 §17). From milestone G's delivery it replaces the **composition check**.
|
||||
- **composition run** — the one run of the composer for one candidate on one machine, started by the first
|
||||
composition step of that candidate that needs the machine and kept by the assigner in its state `composition-runs`;
|
||||
every composition step of the candidate whose module is placed on the machine reads its verdict (design 47 G §718).
|
||||
Not a **composition**, one module's resources composed for one node; nor the **composition step**, the pipeline
|
||||
step that reads one composition run per machine.
|
||||
- **test run** — the one run of a lint, unit test or integration test pipeline step for one candidate, one level and
|
||||
one set of tested packages at their digests, kept by the runner in its state `test-runs`; every artifact's pipeline step of that candidate
|
||||
naming the same packages reads its result (design 47 G §724). Not a **pipeline step**, each artifact's own, nor a **run
|
||||
on request**, a whole pipeline that delivers nothing.
|
||||
- **merge check** — what a pull request carries before it may merge, judging the merge of its head into a
|
||||
named **trunk commit**, made in a clone of its own on a build node and never pushed (ADR 0323). One status,
|
||||
`mesh/check`, written by the checker: the change's tests, run by the language's build module, and the
|
||||
@@ -698,10 +746,16 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
|
||||
word goes to that entry's *Not:* line with the as-is update after that delivery.
|
||||
- **dry run** — a session's run, before a release is pushed, of the parts that will take it in, build it and merge it,
|
||||
as they run live, on the revision as the merge will make it: in process on the session's machine, reading the mesh
|
||||
and writing nothing there. It holds four items: the live take-in run whole with the seat list it will read, every
|
||||
build against the packages as published, the gate's merge path read for the group, and no item left open (hq
|
||||
playbook 07, step 2b). Not a **try** nor a **run on request**, which the mesh runs and which deliver a verdict; a dry
|
||||
and writing nothing there. It holds five items: the live take-in run whole with the seat list it will read, every
|
||||
build against the packages as published, the gate's merge path read for the group, the reviewed heads delivered once
|
||||
in the lab of one machine from take-in to `delivered`, and no item left open (hq playbook 07, step 2b). A change
|
||||
of a delivery module, the node-engine, the tool runner, the bus module or the SDK's bus packages never skips it. Not a **try** nor a **run on request**, which the mesh runs and which deliver a verdict; a dry
|
||||
run owes the forge nothing and is not a check.
|
||||
- **bus-shape sheet** — the prepare's list, per module a milestone adds or changes, of what the module will be on the
|
||||
bus: its manifest sections, bus accounts, streams and their subjects, work queues and the process that takes each
|
||||
queue's asks, durable consumers, and which part creates each; judged by the manifest validator and composed by the
|
||||
grants part's composer and the node-engine's composer in a test before any code (hq playbook 07, step 0, item 11).
|
||||
Not a **build map**, which says where each design line lands in code.
|
||||
- **trunk commit** — the commit of the trunk a merge check's verdict was judged against: the trunk's head when
|
||||
the build module cloned it. The verdict holds for that commit only, goes out of date when the trunk moves, and
|
||||
is then carried to the new commit (ADR 0323, ADR 0548). Goes at milestone G's delivery with the merge check: a pipeline
|
||||
@@ -807,7 +861,8 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
|
||||
level: a group holds deliveries, never groups. Its state is derived from its members, never set. From milestone G's
|
||||
delivery: a shared branch name carrying its issue number, complete when each member's commit has landed on its
|
||||
modules' watched branch, taken in as one source revision of that branch and run as one pipeline per watched branch
|
||||
(ADR 0666 §13).
|
||||
(ADR 0666 §13). From milestone H's delivery: the pull requests named in one **merge call**; no branch name and no
|
||||
pull request read after the call forms one (ADR 0682).
|
||||
- **hotfix** — one pull request in one repository, delivered at its merge (ADR 0401).
|
||||
- **feature** — one branch name across its repositories: in two or more, its pull requests are one delivery group,
|
||||
merged together and delivered member by member in the group's order; in one, a single pull request delivered as a
|
||||
@@ -881,7 +936,9 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
|
||||
- **pending revision** — a source revision the running indexer has not taken in, because it names another build of
|
||||
the indexer or follows one that does: only the named indexer's own keys are written, the rest kept in the
|
||||
indexer's state `pending` until that indexer starts and takes it in (ADR 0633 §1 to §3). A group's members wait
|
||||
there too until the group's end, as members still gathered (§4).
|
||||
there too until the group's end, as members still gathered (§4). Ends at milestone H's delivery: a take-in holds
|
||||
nothing for a named indexer, and one that cannot be written waits as its unacknowledged `source-moved` (ADR 0682;
|
||||
design 47 H §744).
|
||||
- **canary** — the first node of a module's nodes, ordered by ring then name: a new fingerprint reaches it
|
||||
first and the module's other nodes only once it runs healthy there (ADR 0429 §6). Replaces sending to every
|
||||
machine at once from release 6 (§15); a fingerprint that fails there is held and the canary set back, or for
|
||||
|
||||
+12
-3
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: canonical
|
||||
updated: 2026-11-11
|
||||
updated: 2026-11-16
|
||||
---
|
||||
|
||||
# The principles
|
||||
@@ -22,9 +22,18 @@ add, sharpen or drop a principle in a pull request to this file.
|
||||
6. **Nothing is exposed publicly.** No data leaves the mesh unasked: no secret in a record, a log or a public
|
||||
repository, no service reachable from outside unless it is meant to be. Inside the mesh, every agent and module
|
||||
is trusted; who may do what is not a question to ask.
|
||||
7. **The simplest thing that works.** Prefer what already exists. No new mechanism unless it is needed, and fewer
|
||||
parts over more.
|
||||
7. **No part without a need.** Every mechanism, field, seat and step exists because something needs it; prefer what
|
||||
exists over a new one, and remove what no longer serves. Never a shortcut instead of the right shape.
|
||||
8. **One word per thing**, from the [glossary](glossary.md).
|
||||
9. **Depend on the contract, at the level it is interchangeable.** A module depends on a seat where the mesh means
|
||||
more than one module to be able to fill the need, and on a module where only that module does; never on another
|
||||
module's internals.
|
||||
10. **The module is the unit.** Everything is done per module, never per repository. A repository is only where a
|
||||
module's files are kept; a merge moves only the modules it changes.
|
||||
11. **Configurable, never hard-coded.** A value that can differ between machines, modules or over time (a port, a
|
||||
path, a bound, a cap, a name, a time) is a setting with a default, never written into the code.
|
||||
12. **A module writes only its own.** A module writes its own files and state alone; what another module needs from it
|
||||
goes through a provision or a contribution that module declares, never a file written in its place.
|
||||
|
||||
How it is checked: the one code review of a milestone checks the code against these principles and the design's
|
||||
shape; an answer to a develop question names the principle that settles it.
|
||||
|
||||
@@ -112,10 +112,7 @@ the four reviewer agents in `.claude/agents/` (`review-security-and-upgrade`, `r
|
||||
link that is not NATS-native. Each piece of state is kept in the bus storage form that fits it (a key-value
|
||||
bucket, a stream, an object store); a form the manifest lacks is added to mesh-sdk, and the review names that change
|
||||
and its cost (a mesh-sdk change rebuilds every module) to the operator, never folds it in silently (the
|
||||
operator, 2026-11-02). Inside a module too: which of its processes (its program, its tool runner, another process
|
||||
its manifest names) read each event, queue and piece of state at run time, and whether each gets every item it
|
||||
needs: a durable consumer or a queue group hands each message to one reader only, so a reading place shared by two
|
||||
processes splits the messages silently (the operator, 2026-11-14; lead answer A-397);
|
||||
operator, 2026-11-02);
|
||||
- **running qualities**: build capacity, speed, storage growth, and what happens while a part, the bus or the
|
||||
control-node is down;
|
||||
- **health**: what each part's health check says, which conditions are raised and cleared, and whether any
|
||||
|
||||
@@ -67,22 +67,34 @@ A small fix (one repository, one issue, about an hour of work) follows
|
||||
own indexer and five more modules with the live seat list, and its trunk builds waited on renamed packages only the
|
||||
take-in would publish. The dry run (step 2b) now runs the live take-in, the builds against what is published and the
|
||||
gate's merge path, and holds the push while any item is open.
|
||||
- **A change of the delivery system proven only on the live mesh.** On 2026-11-21 and 2026-11-22 milestone H2 of
|
||||
design 47 was delivered after a review that approved it, and about 25 faults showed only on the machines: the
|
||||
node-engine's composer stripped one manifest section of a process and kept another, so the declaration read refused
|
||||
the milestone's own manifests; a stream's subject was not widened, so an approved registration was never written; a
|
||||
work queue had no process taking its asks; and a durable consumer left behind for each old form set off the grants
|
||||
part's alarm. The tests had passed because they created the streams, consumers and takers of asks the broker should
|
||||
have, or a stand-in for a seat's holder, and the review read the code against the design, not against what the nodes
|
||||
ran: the tool runner, the build modules and the node-engine still carried the old form, and the parts that judge,
|
||||
build and compose had to reach the machines first. The prepare now ends with a bus-shape sheet composed in a test
|
||||
(step 0, item 11), a test that stands in for a part of the mesh is a finding (step 2, item 11), the review reads the
|
||||
live mesh and names the order of delivery (step 2, item 12), and the dry run delivers the reviewed heads once in the
|
||||
lab before any pull request opens (step 2b, item 4; the operator, 2026-11-22).
|
||||
- **A module proven only after it reached the machines.** The mail modules were delivered with unit tests
|
||||
only, then failed live three times (issues 859, 865, 868) and took five more hours of fixes.
|
||||
|
||||
## The shape
|
||||
|
||||
One feature is **one branch name**, **one worktree per repository**, **one pull request per repository**,
|
||||
opened **once**, after the review, and **one check** (ADR 0548). It runs in five steps, with the design completed between the first two (step 0b) and, for a change of what judges, builds or merges it, a dry run between the review and the check (step 2b), and its time is bounded. A milestone has no phases
|
||||
opened **once**, after the review, and **one check** (ADR 0548). It runs in five steps, with the design completed between the first two (step 0b) and, for a change of what judges, builds, composes or delivers it, a dry run between the review and the check (step 2b), and its time is bounded. A milestone has no phases
|
||||
(the operator, 2026-10-17): these are its steps, and a report names the step it is in:
|
||||
|
||||
| Step | What happens | Bound |
|
||||
|---|---|---|
|
||||
| 0. Prepare | from the milestone part and the design's main file, read whole, then the code each design line lands in: where each line lands, what exists there today and what relies on it, as one build map per repository; every design question, the design's silences, listed; and every place where a design line and the code disagree, listed | 15 minutes, longer when what exists is large: code never starts on an incomplete answer |
|
||||
| 0b. Design complete | every design question and every place where design and code disagree is answered: by the lead in one line against the principles, or, where no principle settles it, by the operator or `hq-design-writer` (step 0); each answer is written down (the lead's in the milestone's lead-answers file, the others into the milestone part, playbook 02) and its build map rows added | until the list is empty: develop never starts before |
|
||||
| 0. Prepare | from the milestone part and the design's main file, read whole, then the code each design line lands in: where each line lands, what exists there today and what relies on it, as one build map per repository; every design question, the design's silences, listed; every place where a design line and the code disagree, listed; and a bus-shape sheet per module, composed in a test | 15 minutes, longer when what exists is large: code never starts on an incomplete answer |
|
||||
| 0b. Design complete | every design question and every place where design and code disagree is answered: by the lead in one line against the principles, or, where no principle settles it, by the operator or `hq-design-writer` (step 0); each answer is written down (the lead's in the milestone's lead-answers file, the others into the milestone part, playbook 02) and its build map rows added; more than ten questions send the milestone back to its design | until the list is empty: develop never starts before |
|
||||
| 1. Develop | one fixing agent per repository builds every design line of its build map locally, each commit citing the lines it builds, the whole unit suite before every commit, the integration tests compiled, and once per head it reports those of the packages it touched and their importers run against an embedded bus (below); nothing is pushed | the milestone's issues, 30 minutes each |
|
||||
| 2. Review | one reviewer reads all of it, the local commits, judging the integration tests by reading them against the code; reports go both ways; at most 3 rounds | 15 minutes |
|
||||
| 2b. Dry run | for a release that changes a part judging a change, or a module path, a package or a manifest form the take-in reads: the live take-in run whole with the seat list it will read, every build against the packages as published, the gate's merge path read for the group, and no item left open | until no item is open: nothing is pushed before |
|
||||
| 2. Review | one reviewer reads all of it, the local commits, judging the integration tests by reading them against the code, a test that stands in for a part of the mesh a finding, each changed module read against the live mesh and the order of delivery named; reports go both ways; at most 3 rounds | 15 minutes |
|
||||
| 2b. Dry run | for a release that changes a part judging a change, or a module path, a package or a manifest form the take-in reads, and always for one that changes a delivery module, the node-engine, the tool runner, the bus module or the SDK's bus packages: the live take-in run whole with the seat list it will read, every build against the packages as published, the gate's merge path read for the group, the reviewed heads delivered once in the lab from take-in to `delivered`, and no item left open | until no item is open: nothing is pushed before |
|
||||
| 3. Check | push the reviewed heads once and open the pull requests together; the checker's one check runs the integration tests; no further review unless the check fails | one check run |
|
||||
| 4. Deliver | merge; the source revision moves, each module is built once and wanted on its nodes, its canary first | until the view says the source revision `delivered` |
|
||||
|
||||
@@ -314,7 +326,24 @@ of the prepare the lead names at the next report.
|
||||
Then, under `Design meets code`, every place item 3 found where a design line and the code disagree, each with
|
||||
the design line, the code (file:line at the `origin/main` commit read), which of the three it is (a form the code
|
||||
cannot take, a part the line assumes built that is not, a rule in code the line would break), and the preparer's
|
||||
recommendation, said as a recommendation. The two lists are the prepare's last output and step 0b's input.
|
||||
recommendation, said as a recommendation. The two lists and the bus-shape sheets (item 11) are the prepare's last
|
||||
output and step 0b's input.
|
||||
11. **Write a bus-shape sheet per module, and compose it in a test, before any code** (the operator, 2026-11-22). For
|
||||
each module the milestone adds or changes, `.work/<slug>/<module>.bus.md` lists what the module will be on the bus
|
||||
once the change runs: its manifest sections (each process, its `bus`, `serves` and `requires`), its bus accounts,
|
||||
its streams with their subjects, its work queues with the process that takes each queue's asks, its durable
|
||||
consumers, and for each of these who creates it (the bus module from the module's `requires`, the grants part, the
|
||||
module's own process at its start). Each row cites the design line that gives it; a row no design line gives is a
|
||||
design question (item 10). The sheet is judged as the mesh will judge it, in a test in the preparer's worktree: the
|
||||
manifest validator judges the manifests the sheet describes, with the live seat list, and the grants part's
|
||||
composer and the node-engine's composer (the composition of `mesh-delivery-sdk`) compose them; each must take the
|
||||
sheet as written. A refusal is an entry under `Design meets code`. A composer a test cannot import is a gap of the
|
||||
build and delivery system, said to the lead and built there before develop (the grants part's composer belongs in
|
||||
the SDK, beside the composition of `mesh-delivery-sdk`); never a sheet left unjudged. The sheet is what the
|
||||
developers' tests and the reviewer's reading of the live mesh (step 2, items 11 and 12) hold the change to.
|
||||
How it is checked: every module a build map changes has its sheet, with the test that composed it and its result
|
||||
(`ls .work/<slug>/*.bus.md`); a fault of the bus's shape met after the push that the sheet omits is a miss of the
|
||||
prepare, named at the next report.
|
||||
|
||||
## Step 0b — Design complete
|
||||
|
||||
@@ -339,6 +368,13 @@ answer is written down before the code; 2026-11-11: the lead answers it against
|
||||
answers it.
|
||||
4. **The design is complete** when every entry of both lists names its answering commit. Then step 1 starts, from the milestone
|
||||
part at that commit.
|
||||
5. **More than ten design questions send the milestone back to its design** (the operator, 2026-11-22). When the
|
||||
prepare leaves more than ten entries in `Design questions` and `Design meets code` together, the milestone part is
|
||||
not ready to be built: the lead answers none of them one by one, hands them all to `hq-design-writer` as one
|
||||
amendment of the milestone part (playbook [02](02-graduation.md)), read by the four reviewers by architectural
|
||||
domain, and the prepare runs again on the amended part. Develop starts only from a prepare that left ten or fewer.
|
||||
How it is checked: the milestone file's two lists, counted at the prepare's end (`grep -c`), and the hq commit of
|
||||
the amendment when they held more than ten.
|
||||
|
||||
**A question met later stops only its part.** A developer or the reviewer who meets a question the milestone part
|
||||
does not answer stops the subtasks that need the answer, says the question to the lead with the design line and
|
||||
@@ -371,7 +407,10 @@ an answer no hq commit holds, is a finding of the review (step 2, item 2a).
|
||||
the test calls what the change adds, the agent takes out the change's effect (the line that does it, not the new
|
||||
function), sees the test fail, and puts it back (2026-10-19: a check request's new field was proven by a test of
|
||||
its helper alone, and dropping the field from the request passed every test); `gofmt`, `go vet` and the whole unit suite stay green. **The tests are written from the issue's
|
||||
acceptance criteria**: one test or more per criterion at the level it names, each test's comment citing
|
||||
acceptance criteria**, and **a test never stands in for another part of the mesh** (step 2, item 11): it creates no
|
||||
stream, consumer or taker of a work queue's asks that the bus module or the grants part should create, and fakes no
|
||||
seat's holder in a whole test; it composes what it needs with the parts' own composers, from the bus-shape sheet
|
||||
(step 0, item 11). One test or more per criterion at the level it names, each test's comment citing
|
||||
the criterion it proves by its label (`// 1118/AC2`), and no criterion left without its test; an integration criterion is a test
|
||||
that compiles and is run by the pull request's one check. The integration tests (those that start a store, a bus
|
||||
or a process) are compiled with `go vet -tags integration ./...` while developing and run by that check. **Once per head it
|
||||
@@ -510,15 +549,41 @@ an answer no hq commit holds, is a finding of the review (step 2, item 2a).
|
||||
the record behind it, the lead brings it to the operator as a design question, and the code waits for the answer
|
||||
in the design. How it is checked: the review report has a line for each question with its answer, and the lead reads both before the
|
||||
push; a report without them is not an approval.
|
||||
11. **A test that stands in for another part of the mesh is a finding, by rule** (the operator, 2026-11-22). A test
|
||||
that creates a stream, a consumer or a process taking a work queue's asks where the bus module, the grants part
|
||||
or the node-engine should, or that fakes a seat's holder in a whole test, proves what the test made, not what the
|
||||
mesh will make: on 2026-11-21 milestone H2's tests passed on streams and takers they created themselves, and the
|
||||
live broker made neither. The fix is the test composing what it needs with the parts' own composers (the grants
|
||||
part's and the composition of `mesh-delivery-sdk`), from the module's bus-shape sheet (step 0, item 11); a
|
||||
composer it cannot import is a gap of the build and delivery system, built there in the milestone, never a stand-in
|
||||
kept. A unit test's fake of a function's own collaborator is not this; a stand-in for a part another module
|
||||
holds is. How it is checked: the review report lists every new or changed test that creates bus state or fakes a
|
||||
seat's holder, each with the composer that should make it, and a report without that list is not an approval.
|
||||
12. **Each changed module is read against the live mesh, not only the design** (the operator, 2026-11-22). The
|
||||
reviewer reads, through the mesh MCP server's tools, what runs on the nodes today: each node's haves of every
|
||||
module the change touches or relies on, and which parts still carry the form the change replaces (the tool runner,
|
||||
the build modules, the node-engine, the indexer and its manifest validator, the grants part). For each, it asks
|
||||
whether the running version can take in, judge, build, compose or page the change's new form. Then it names, in
|
||||
its report, **the order of delivery the change needs**: the parts that judge, build, compose or page the new form
|
||||
first, then the modules that use it, each step an ordering edge of the module graph the delivery plan derives
|
||||
(instruction design-it-as-it-should-be), or, where no edge carries it, a gap of the build and delivery system for
|
||||
the lead to bring to the operator. A part still on the old form that no step of the order brings over makes the
|
||||
change wrong. How it is checked: the review report holds a section `Live mesh` naming each node's build read for
|
||||
each such part, with its time, and the order of delivery; the lead copies the order into the milestone file and
|
||||
the dry run (step 2b, item 4) delivers in it. A fault met after the merge from a part on the old form is named at
|
||||
the next report.
|
||||
|
||||
## Step 2b — Dry run (a change of the delivery system, or of what the take-in reads)
|
||||
|
||||
**When it runs.** After the review approves the heads and before the push of step 3, for every release that changes a
|
||||
part judging a change (step 3, item 3: the indexer and its manifest validator, the gate, the builder, a build module,
|
||||
the checker or the pipeline runner, the node-engine, a seat definition), and for every release that adds or renames a
|
||||
module path or a package other modules take, or changes the form of manifests the take-in reads. The prepare step's
|
||||
milestone file says per release whether it runs and why (`Dry run: yes` or `no`, with the reason); the review refuses a
|
||||
group that lists a judging part with no such line. The operator, 2026-11-13: "remember the mistake and make sure our
|
||||
module path or a package other modules take, or changes the form of manifests the take-in reads. **A release that
|
||||
changes a delivery module, the node-engine, the tool runner, the bus module or the SDK's bus packages never skips it**,
|
||||
and no rule is weighed against that (the operator, 2026-11-22: milestone H2's faults would each have shown in one
|
||||
delivery off the machines). The prepare step's milestone file says per release whether it runs and why (`Dry run: yes`
|
||||
or `no`, with the reason); the review refuses a group that lists a judging part with no such line, and a `no` for a
|
||||
release that changes one of the parts just named. The operator, 2026-11-13: "remember the mistake and make sure our
|
||||
pipeline catches this".
|
||||
|
||||
**What it is.** A dry run runs the parts that will take the change in, build it and merge it, as they run live, on the
|
||||
@@ -526,7 +591,7 @@ revision as the merge will make it: in process on the session's machine, reading
|
||||
asking no try and no check. An agent of hq's definitions runs it, read-only on the mesh and on every working copy; the
|
||||
lead writes only the handover. Everything live it uses (the builds the nodes run, the seat list, the published
|
||||
versions, the trunks) is read in the same hour as the push, and read again, with the dry run run again, when a head,
|
||||
a main or a live build moves before the push. Four items, each held before any push:
|
||||
a main or a live build moves before the push. Five items, each held before any push:
|
||||
|
||||
1. **The live take-in, run whole.** The indexer that will take the revision in (the running one, read from the view's
|
||||
reach of its module; for a revision that names another build of the indexer, the running one, which keeps it
|
||||
@@ -554,7 +619,18 @@ a main or a live build moves before the push. Four items, each held before any p
|
||||
another base is moved to the gate's branch or left out of the group, a group the gate holds closed is pushed under a
|
||||
new branch name, and an Approve ask that names fewer members than the group is ended and said to the operator,
|
||||
never answered.
|
||||
4. **No item open.** The dry run's report says of each item what ran, at which heads and on which live builds, and its
|
||||
4. **The reviewed heads delivered once in the lab, from take-in to delivery** (the operator, 2026-11-22). The lab of
|
||||
one machine raises the mesh's four node roles on the session's machine (the control-node's parts, a build node's,
|
||||
the bus module and a node-engine with its tool runner), with an embedded bus and store, from the builds the nodes
|
||||
run now (item 1's reading). The reviewed heads are merged there and run the whole way once: the take-in, the
|
||||
pipeline and its steps, the builds, the grants part's memberships, the compositions, the wants, the node-engine's
|
||||
apply and the tool runner's start, in the order of delivery the review named (step 2, item 12), until the lab's
|
||||
view says the source revision `delivered` and every changed module runs healthy and answers its tools. A step that
|
||||
refuses, holds or stands still is a fault of the release, fixed and reviewed before the push. Where the lab cannot
|
||||
yet raise a part (no bed for it), that is a gap of the build and delivery system, built in the lab in the same
|
||||
milestone or before it and said to the operator; the item is never closed as "not run". The pull requests open
|
||||
only after this item passed.
|
||||
5. **No item open.** The dry run's report says of each item what ran, at which heads and on which live builds, and its
|
||||
counts ("ran: 193 manifests, 0 refused, seat list read at 13:05"). An item said "not run", "not known" or "read, not
|
||||
run" is closed, by running it or by showing why it does not apply, or the push is held: **a dry run with an open
|
||||
item is not a pass**, and no rule is weighed against it. Before the push the lead says to the operator, in one line
|
||||
@@ -568,7 +644,8 @@ take-in publishes; no dry run had built a trunk module against the published pac
|
||||
merged a group one member at a time with no undo, stopped at a member whose base was not main, and asked an Approve
|
||||
while a group was still forming and per member of a closed group.
|
||||
|
||||
**How it is checked.** The milestone file holds a section `Dry run` with each item's result, the reviewed heads it ran
|
||||
**How it is checked.** The milestone file holds a section `Dry run` with each of the five items' result, the lab
|
||||
run's source revision and its `delivered` time among them, the reviewed heads it ran
|
||||
on and its time (`grep -n -A6 '^## Dry run' .work/<slug>/milestone.md`), older than the push (the forge branch's
|
||||
first push of the heads) and with no item open; the pull requests' description names it in one line. A push of a
|
||||
release whose milestone file lists a judging part with no such section, or with an item open, is this step skipped;
|
||||
@@ -676,7 +753,8 @@ a fault met after the merge that an item would have shown is named at the next r
|
||||
4. **The milestone's acceptance is proven by its check.** A milestone that adds or changes a module
|
||||
carries an integration test that starts the module whole, its process against the real bus and store, and
|
||||
shows the milestone's acceptance sentence; the forge's checks run it (ADR 0391 §1, §6). Unit tests alone are not
|
||||
that proof; the mesh has no end-to-end tests yet, and the lab is not used (the operator, 2026-10-16).
|
||||
that proof; the mesh has no end-to-end tests yet, and the lab is used only for the dry run's delivery (step 2b,
|
||||
item 4; the operator, 2026-10-16 and 2026-11-22).
|
||||
**A new manifest word's test goes through the first composition that meets it, not only the verb that fills it.**
|
||||
On 2026-10-19 release 1 of feature mail-sender tested a process's own bus account through `module issue`
|
||||
alone; the first push after mesh-mail declared the process composed a random 40-character stand-in for the
|
||||
@@ -943,8 +1021,15 @@ issues in `fixing` that nobody works on reads to the operator as stuck work.
|
||||
item 6b). A fixing agent started on a file without the section, or an effect of a removed or moved part met only
|
||||
after the delivery, is the prepare step skipped, named in the next detailed report and written into the playbook's
|
||||
lessons here.
|
||||
- A release whose milestone file lists a part judging a change holds a `Dry run` section with all four items closed,
|
||||
older than its push (step 2b); one pushed without it, or with an item open, is that step skipped.
|
||||
- A release whose milestone file lists a part judging a change, or that changes a delivery module, the node-engine,
|
||||
the tool runner, the bus module or the SDK's bus packages, holds a `Dry run` section with all five items closed, the
|
||||
lab's delivery among them, older than its push (step 2b); one pushed without it, or with an item open, is that step
|
||||
skipped.
|
||||
- Every module a build map changes has its bus-shape sheet with the test that composed it (step 0, item 11); a
|
||||
milestone developed from a prepare that left more than ten design questions, with no amendment of its part between,
|
||||
is step 0b item 5 skipped.
|
||||
- Every review report holds the list of tests that create bus state or fake a seat's holder (step 2, item 11) and the
|
||||
section `Live mesh` with the order of delivery (step 2, item 12); a report without either is not an approval.
|
||||
- No issue of a running milestone is sized over an hour in its prepare note; an issue whose fixing agent passes
|
||||
twice its bound was not split.
|
||||
- Every issue of a running milestone has a note from the prepare step naming its files and tests (file:line), how
|
||||
|
||||
@@ -476,11 +476,11 @@ const P = [
|
||||
{n:"07",name:"Features",kind:"build",c:"--build",
|
||||
trig:"Work that changes code across issues or repositories, too large for a small fix.",
|
||||
who:"A lead (larger model), one fixing agent per repository (smaller), one reviewer (larger).",
|
||||
steps:["Prepare: name the branch, make the worktrees, read the milestone part and the design's main file whole, then the code each design line lands in. (new)","List every place where a design line and the code disagree, beside the design questions. (new)","Every agent is one of hq's definitions (mesh-preparer, mesh-developer, mesh-code-reviewer, mesh-watcher); the lead writes only the handover. (new)","The prepare's only output: a build map per repository, each row a design line and where it lands, and the design questions. No rulings. (new)","Design complete: the lead answers every question against the principles; one no principle settles goes to the operator or the design writer; then develop. (new)","Read what exists today from the code and the live mesh: every effect of what is removed or moved, every reader of each, what happens to each and its test. No code before it is complete; the review refuses work without it. (new)","The build map opens with what exists today; subtasks ordered contract first, one writer per file.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Answer three questions in the milestone file: who deletes each new key and stream, how the switch-over is tried on one node first, what the one check does not cover. The review checks them. (new)","List every part the change reaches; copy fixtures from the real writer.","Develop: one agent per repository, one commit per subtask, each citing its design lines; a question stops only its subtask. (new)","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk; nothing is pushed, no try runs. (new)","Review all of it against the design lines, code no line asks for a finding, reading the integration tests against the code; at most 3 rounds; the report answers the state-and-seams and mesh-agnostic questions. (new)","Dry run, for a change of what judges, builds or merges it: the live take-in run whole with the seat list it will read, every build against the packages as published, the gate's merge path read for the group; an item left open holds the push. (new)","A group pins the group's own mesh-sdk head in every member. (new)","Push the reviewed heads once and read each forge head against the reviewed commit; no draft pull request, no fix round on an open one. (new)","Open one pull request per repository, together, with Reviewed-by and Pushed-by; the one check runs. A failed check is read, fixed, reviewed, pushed once more. (new)","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery in the status view (moving, settled, stuck, delivered) to done; resolve the issues; clean up. (new)","When the builder cannot deliver its own fix: revert, a build by a session's call, a registration at the terminal, copies kept outside the store; a broken controller is put back by a want the operator writes, a hand build by mesh-hand-compose and a want. (new)"],
|
||||
steps:["Prepare: name the branch, make the worktrees, read the milestone part and the design's main file whole, then the code each design line lands in. (new)","List every place where a design line and the code disagree, beside the design questions. (new)","Every agent is one of hq's definitions (mesh-preparer, mesh-developer, mesh-code-reviewer, mesh-watcher); the lead writes only the handover. (new)","The prepare's only output: a build map per repository, each row a design line and where it lands, and the design questions. No rulings. (new)","Design complete: the lead answers every question against the principles; one no principle settles goes to the operator or the design writer; then develop. (new)","Read what exists today from the code and the live mesh: every effect of what is removed or moved, every reader of each, what happens to each and its test. No code before it is complete; the review refuses work without it. (new)","The build map opens with what exists today; subtasks ordered contract first, one writer per file.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Answer three questions in the milestone file: who deletes each new key and stream, how the switch-over is tried on one node first, what the one check does not cover. The review checks them. (new)","List every part the change reaches; copy fixtures from the real writer.","End the prepare with a bus-shape sheet per module (manifest sections, accounts, streams and subjects, work queues and who takes their asks, who creates each), judged by the manifest validator and composed by the grants part's and the node-engine's composers in a test; more than ten design questions send the milestone back to its design. (new)","Develop: one agent per repository, one commit per subtask, each citing its design lines; a question stops only its subtask. (new)","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk; nothing is pushed, no try runs. (new)","Review all of it against the design lines, code no line asks for a finding, reading the integration tests against the code; at most 3 rounds; the report answers the state-and-seams and mesh-agnostic questions. (new)","A test that stands in for another part of the mesh (a stream, consumer or taker of asks it creates, a faked seat's holder) is a finding; the review reads each changed module against the live mesh and names the order of delivery: the parts that judge, build, compose or page first. (new)","Dry run, for a change of what judges, builds or merges it: the live take-in run whole with the seat list it will read, every build against the packages as published, the gate's merge path read for the group, the reviewed heads delivered once in the lab of one machine from take-in to delivered; an item left open holds the push, and a change of a delivery module, the node-engine, the tool runner, the bus module or the SDK's bus packages never skips it. (new)","A group pins the group's own mesh-sdk head in every member. (new)","Push the reviewed heads once and read each forge head against the reviewed commit; no draft pull request, no fix round on an open one. (new)","Open one pull request per repository, together, with Reviewed-by and Pushed-by; the one check runs. A failed check is read, fixed, reviewed, pushed once more. (new)","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery in the status view (moving, settled, stuck, delivered) to done; resolve the issues; clean up. (new)","When the builder cannot deliver its own fix: revert, a build by a session's call, a registration at the terminal, copies kept outside the store; a broken controller is put back by a want the operator writes, a hand build by mesh-hand-compose and a want. (new)"],
|
||||
prod:"One pull request per repository, one source revision delivered, resolved issues, no branch or worktree left.",
|
||||
next:"02 (when it ships)",bounds:"Prepare 15 min · 30 min per issue · review 15 min, ≤ 3 rounds · one check, pushed once",
|
||||
prev:["Pull requests as scratchpads","Context bought again and again","A change built on what was remembered, not on what runs","Review rounds spent on what a run would show","A node agent's bus reads, proven only by review","A dry run with an open item, taken as a pass"],
|
||||
check:"The checker's one status, mesh/check; the review record; the dry run's section in the milestone file; the tracker's move."},
|
||||
next:"02 (when it ships)",bounds:"Prepare 15 min, at most ten design questions · 30 min per issue · review 15 min, ≤ 3 rounds · one check, pushed once",
|
||||
prev:["Pull requests as scratchpads","Context bought again and again","A change built on what was remembered, not on what runs","Review rounds spent on what a run would show","A node agent's bus reads, proven only by review","A dry run with an open item, taken as a pass","A change of the delivery system proven only on the live mesh"],
|
||||
check:"The checker's one status, mesh/check; the review record; the dry run's section in the milestone file, the lab's delivery among its items; the bus-shape sheets; the review's Live mesh section; the tracker's move."},
|
||||
{n:"08",name:"Small fixes",kind:"build",c:"--build",
|
||||
trig:"One issue in one repository, about an hour of work.",
|
||||
who:"The session, with one reviewer on the larger model.",
|
||||
|
||||
@@ -8,8 +8,9 @@ code:
|
||||
- mesh-sdk go/catalogue (the manifest's shapes)
|
||||
- mesh-sdk go/declaration (the node-engine's resource vocabulary)
|
||||
- mesh-contracts
|
||||
updated: 2026-11-12
|
||||
updated: 2026-11-18
|
||||
decisions:
|
||||
- "ADR 0680"
|
||||
- "ADR 0578"
|
||||
- "ADR 0595"
|
||||
- "ADR 0619"
|
||||
@@ -169,7 +170,7 @@ since a package is a build input and runs nowhere.
|
||||
|---|---|---|
|
||||
| **tools** | a `bundle` with `loads` naming what the runtime loads (for a Go bundle its `binary`), and the module's `tools` listing every tool it serves; `replaces` for the shell commands a tool replaces | the node's tool runner (ADR 0175); with `runs-as`, a **runtime of its own** under the module's account (below) |
|
||||
| **a long-running service of its own code** | a `process` resource: `artifact` (a bundle), `name` (what the unit is called), `run` (the command, relative to the unpacked bundle), `user`, `env` and `env-file`, `restart-on`, `health`, `yields`, `replaces` (the ids it takes over from) | the node-engine, as a unit that stays up |
|
||||
| **its own bus account for a process** | the process's `bus`: the `emits`, `state`, `queues`, `invokes` and `asks` it is granted, a subset of what the manifest declares; an own secret holding the account, owned by the process's `user` (ADR 0436 §1) | the grants part composes the account from it |
|
||||
| **its own bus account for a process** | the process's `bus`: the `emits`, `state`, `queues`, `invokes` and `asks` it is granted, a subset of what the manifest declares; an own secret holding the account, owned by the account the process runs as, whatever that account (ADR 0680 §1; *Whose a process's own secrets are*, below) | the grants part composes the account from it |
|
||||
| **a scheduled job** | a `process` or `container` resource with `schedule`, a five-field cron; never with `run-once`; a process with no `restart-on`, `replaces` or `witness`; a scheduled container may name `while-stopped` (below) | the node-engine, again on each fire (ADR 0053) |
|
||||
| **a one-time step** (a seed, a first-start step, a validator of a file) | a `process` or `container` resource with `run-once` true: a **run-once step**, which gates every resource after it; `restart-on` makes it run again when what it names changes (ADR 0052, ADR 0099) | the node-engine, to completion |
|
||||
| **a migration of its own state before a new version runs** | `prepares` true, and a `container` or `process` that stays up running an artifact the module built: the mesh runs that program in its preparation mode (ADR 0135); never a run-once step written by hand for it | the node-engine, before the new version starts |
|
||||
@@ -178,6 +179,39 @@ since a package is a build input and runs nowhere.
|
||||
| **a host program from the operating system** | a `package` resource (`package`, `absent`) and a `service` resource per unit it ships (`unit`, `state`, `boot`, `scope`, `restart-on`, `reload-on`, `health`); never an `action` | the node's package manager and service manager |
|
||||
| **files** | `file` and `directory` resources (a directory by `place` or `path`), an `archive` resource unpacking an `archive` artifact, template files in the module's `templates` directory | the node-engine and the provisioner client |
|
||||
|
||||
**Whose a process's own secrets are** (ADR 0680). *Amended 2026-11-18.* Every own secret a process reads, its bus
|
||||
credential first, is owned by the account that process runs as, whatever that account is: an account the module
|
||||
makes (a `user` resource of that name), the operator account (`${machine:account}`), or root (ADR 0680 §1). The
|
||||
manifest names it, as the secret's `owner` or the module's `secrets-owner`, and the process runs as it (its `user`)
|
||||
or as root, as the second rule below holds; the node-engine writes the secret owned by it at mode 0600 (ADR 0680 §1). An account the module makes stays
|
||||
the usual case, not a rule; a process that declares `bus` still names the account it runs as. ADR 0436 §1's "never
|
||||
root and never the operator account" no longer holds for a process that declares `bus`, and the manifest validator's
|
||||
two rules that refused them (as an own secret's owner and as a `bus` process's account) are gone (ADR 0680 §2). The
|
||||
manifest validator holds two rules instead:
|
||||
|
||||
- **Every account named is one the mesh knows.** An own secret's `owner`, a `secrets-owner` and the account of a
|
||||
process that declares `bus` are each the operator account, root or an account the module makes; any other is
|
||||
refused, and so is a `bus` process naming no account (ADR 0680 §2).
|
||||
- **A process can read every own secret it names.** A process resource that names an own secret (its path in the
|
||||
process's `run` or `env`) and runs as neither that secret's resolved owner (its `owner`, else `secrets-owner`) nor
|
||||
root is refused (ADR 0680 §3). A container module is excepted, since a container reads its secrets as its own
|
||||
account, and a process account's secret needs no such rule, since it is delivered owned by the process's account
|
||||
(ADR 0436 §2).
|
||||
|
||||
A secret owned by the operator account is as private as what runs as that account on its node: the node's tool
|
||||
runner, and through it every agent session there (ADR 0436 §9). That exposure is accepted (ADR 0680 §1); what bounds
|
||||
a process account's credential is its grants, which answer no tool and no seat's verb (ADR 0436 §3). A module's
|
||||
`runs-as` is unchanged: it names an account the module makes (ADR 0259 §8, below).
|
||||
|
||||
*How it is checked:* the node-engine's tests write an own secret owned by the account its manifest names, at mode
|
||||
0600, for an account the module makes, for the operator account and for root; the manifest validator's tests, run on
|
||||
every change of the validator and over every manifest a change of mesh-catalog touches, accept an own secret owned by
|
||||
`${machine:account}` or root, a `bus` process running as either, a process running as the resolved owner of the own
|
||||
secret it names (also through `secrets-owner`), a process running as root, and a container module naming another
|
||||
account's own secret, and refuse a `bus` process naming no account or one the module does not make, and a process
|
||||
naming another account's own secret; the controller's grant test still finds no process account able to answer a
|
||||
call (ADR 0680 §4).
|
||||
|
||||
**A runtime of its own.** A module that says `runs-as` names an account it makes (a `user` resource of that name,
|
||||
never root nor the operator's); its tools bundle is then served by a runtime of its own, as that account, on a bus
|
||||
account of its own (ADR 0259 §8), whose readiness is the manifest's `runtime-health` (ADR 0366). Its secrets belong to
|
||||
|
||||
@@ -3,9 +3,10 @@ layer: to-be
|
||||
status: in-progress
|
||||
design: 42
|
||||
milestone: zfs-owns-zfs
|
||||
updated: 2026-11-13
|
||||
updated: 2026-11-18
|
||||
decisions:
|
||||
- "ADR 0679"
|
||||
- "ADR 0680"
|
||||
---
|
||||
# 42, milestone zfs-owns-zfs — the lead's answers to the prepare's questions
|
||||
|
||||
@@ -136,6 +137,8 @@ settles it (`00-META/principles.md`), cited as "design 42 zfs-owns-zfs A-n". The
|
||||
calls: emit an event, put or delete a key of those states, and invoke one of those three. The root processes say
|
||||
everything they say on the bus through it; with the keeper not answering they act as with the bus down (A-8), and
|
||||
warn. The module's tools keep their own account as today.
|
||||
*Amended 2026-11-18:* ADR 0680 §1 ends ADR 0436 §1's "never root" for a process that declares `bus`, so this
|
||||
answer's premise no longer holds; the keeper stands as the milestone builds it, a choice the records no longer force.
|
||||
- **A-38** (A-37, §25, §26, met in develop; ADR 0436 §1, ADR 0595 §1, §2; the operator's "a case the delivery cannot
|
||||
handle is a gap in the build and delivery system") A process's `bus` today is judged and granted only against the
|
||||
module-level `emits` and `state`, which ADR 0595 replaced by what a module asks for in `requires`. In this
|
||||
|
||||
@@ -2,8 +2,10 @@
|
||||
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, mesh-tools, mesh-networking, hq 00-META/checks]
|
||||
updated: 2026-11-11
|
||||
updated: 2026-11-20
|
||||
decisions:
|
||||
- "ADR 0682"
|
||||
- "ADR 0681"
|
||||
- "ADR 0673"
|
||||
- "ADR 0672"
|
||||
- "ADR 0668"
|
||||
@@ -195,6 +197,16 @@ acting parts, the kept data on the bus restored with a delivery, and the verbs a
|
||||
section this file names in italics and does not hold is there, under the same name. A sentence that holds a delivered
|
||||
line and G's change together stays here.
|
||||
|
||||
**From milestone H's delivery, a delivery starts at the merge through the mesh** (ADR 0682; the operator,
|
||||
2026-11-20). One **merge call** of the seat `git`'s verb `merge-pull`, naming one or more pull requests, is a delivery's
|
||||
start and its group; the gate names the merged heads one source revision per watched branch and opens its delivery
|
||||
record, the indexer takes it in and names its **movers**, one pipeline runs per take-in and none in parallel, and a
|
||||
want names the newest released version whose pipeline passed. The forge bridge's one message per move of a watched
|
||||
branch's head is the gate's watchdog: a head no merge call delivered is an **untaken head**, said and delivered by
|
||||
nothing. Every line milestone H builds is in its part, opened by the plan
|
||||
[47-milestones/H-deliver-the-delivery-system.md](47-milestones/H-deliver-the-delivery-system.md) and cited as "design
|
||||
47 H §n" (§734 on); where an H line and a G line differ, the H line holds and the G line says so.
|
||||
|
||||
This is the delivery of [to-be 10](10-delivery.md) carried out. To-be 10 says what is built: the comparison
|
||||
of source and artifacts decides, and nothing here changes that. This design says who answers for one
|
||||
commit's journey, in what order the steps are allowed, and where each fact of it is kept. It was rewritten on
|
||||
@@ -1508,6 +1520,23 @@ way is written down before the switch (ADR 0526, which ADR 0522 §6 asked of R4g
|
||||
running versions are kept outside the artifact store on two nodes, each by digest with its module, artifact, commit, Go version and the
|
||||
steps that put it back, because the store's nightly collection removes a blob the controller did not record (ADR 0526 §6).
|
||||
|
||||
## Every delivery part wakes on its inputs alone
|
||||
|
||||
*ADR 0682 §11; issue 1982; the plan of milestone H, section 3.6.* A delivery part (the forge module, the forge
|
||||
bridge, the gate, the indexer, mesh-config, the runner, the builder, the build modules, the assigner, the node-engine,
|
||||
the grants part, the watchman, the condition keeper, the status view, the teller and the tool runner) keeps a watched
|
||||
copy of each of its own states, through one shape in mesh-sdk's state package (the shape the held pull request
|
||||
mesh-catalog #708 built for mesh-config, moved into mesh-sdk), and runs a pass only when an input it consumes changed,
|
||||
taking only the keys that input names. It keeps one timer, set to its earliest real deadline, a bound it states; it
|
||||
polls nothing, reads nothing of its own whole on a wake, and asks no call again on a timer. Which part moves onto the
|
||||
shape in which release, and its cost (the shape's release in mesh-sdk rebuilds nearly every module, so H4 alone
|
||||
carries it), is design 47 H §762. How it is checked: the code review of every delivery module from milestone
|
||||
H1 on refuses a timer that is no stated deadline, a poll and a whole re-read; mesh-sdk ships a test helper that counts
|
||||
the requests a pass makes, and each delivery module's integration test that starts it whole against the bus (the mesh's
|
||||
instruction *how-work-is-done*) asserts that a pass after one changed key requests that key alone; live, milestone H4 is proven by the bus's
|
||||
slow consumers and consumers behind at 0 for an hour, read with `mesh-broker.rates` (H §760) and the bus module's
|
||||
consumer reads.
|
||||
|
||||
## Acceptance tests
|
||||
|
||||
What the build proves before this design is implemented (research 055's direction):
|
||||
@@ -1664,7 +1693,7 @@ list:
|
||||
performance is fixed; no check starts real builds.
|
||||
37. **Nothing is delivered ahead.** Research 085's milestone is delivered with no part delivered ahead of it, read
|
||||
from its delivery record (ADR 0656, How it is checked).
|
||||
38. **A newer indexer is reached.** A merged revision naming a newer indexer gives, from the running indexer, a catalog
|
||||
38. **A newer indexer is reached.** *(Retires at milestone H, design 47 H §764.)* A merged revision naming a newer indexer gives, from the running indexer, a catalog
|
||||
graph revision that is the previous one with only the indexer's entry replaced; no other want moves; the new
|
||||
indexer is wanted, granted, started, and takes the revision in.
|
||||
39. **Revisions are kept, and stores say their fill.** A revision pinned by two records stays until both free it, one
|
||||
@@ -1706,7 +1735,7 @@ Each change ADR 0656 makes in an earlier record, and its test:
|
||||
are read by the indexer's candidate pass and by no running part (whole).
|
||||
48. **A process reports its handed build** (ADR 0639 §7). A part started while its node's want differs from what runs
|
||||
reports the build it was started with, and the node-engine seat's verb `process-builds` reads it (whole, node-engine).
|
||||
49. **The forge bridge reads a group from the gate's verb** (ADR 0633 §4, §5). The forge bridge sets the group on each
|
||||
49. **The forge bridge reads a group from the gate's verb** *(Retires at milestone H, design 47 H §764.)* (ADR 0633 §4, §5). The forge bridge sets the group on each
|
||||
merged message and publishes a group's end again from the seat `mesh-delivery`'s verb `groups`, and its account
|
||||
holds no read of the gate's `merges` state, so a read of it is refused (whole, forge bridge).
|
||||
|
||||
@@ -1728,11 +1757,9 @@ What milestone G's prepare found, and its test:
|
||||
(whole, gate, checker and forge module).
|
||||
53. **What is owed is said, answered and kept.** An `owed` said while the forge bridge is stopped is performed once after
|
||||
its restart; the bridge stopped between an act and its `owed.ended` repeats it and the forge holds it once; an
|
||||
undecodable act is said `undecodable`; an act unanswered 15 minutes is listed by `stalled`; the switch with a merge
|
||||
handed and not yet merged opens no `forge-made` record; a merge made at the forge opens one, said as `transition`
|
||||
with why `forge-made`, and a later merge in its repository follows it; the checker's `mesh/check` is performed by
|
||||
the bridge from the checker's `owed`, and a checker status the forge refuses is recorded in the checker's own
|
||||
state and listed in its stalled read (whole, gate, checker and forge bridge).
|
||||
undecodable act is said `undecodable`; an act unanswered 15 minutes is listed by `stalled` (whole, gate and forge bridge). The rows of a `forge-made` record
|
||||
and of the checker's `mesh/check` went: no record is marked `forge-made` (design 47 G §151), a head moved outside
|
||||
the mesh is an untaken head (design 47 H §740), and the checker goes (corrected in place by design 47 H §763).
|
||||
54. **One reader of the seat list per part, and one view machinery.** Every part that reads the seat list has the two
|
||||
tools of ADR 0636 §7 from the runtime and no wiring of its own; every part that takes a first view answers its
|
||||
held and awaited revision in `<module>_first_views`. With the forge on its old build, serving no verb of the seat
|
||||
@@ -1865,9 +1892,9 @@ No module ends the milestone with more tests than it starts with, counted per ca
|
||||
|
||||
The failure paths:
|
||||
|
||||
81. **A group that never completes** raises `take-in-waits` at 30 minutes, and none of its members is delivered (whole,
|
||||
81. **A group that never completes** *(Retires at milestone H, design 47 H §764.)* raises `take-in-waits` at 30 minutes, and none of its members is delivered (whole,
|
||||
indexer and watchman).
|
||||
82. **An indexer whose manifest its validator refuses** leaves its revision pending, holds only its own watched branch,
|
||||
82. **An indexer whose manifest its validator refuses** *(Retires at milestone H, design 47 H §764.)* leaves its revision pending, holds only its own watched branch,
|
||||
raises `take-in-waits` at 60 minutes, a later merge on that branch waits behind it and is not taken in past it, and
|
||||
a revert taken in moves the branch on (whole, indexer).
|
||||
83. **A declined registration change, and an unprotected branch,** each write nothing: the first after its Decline, the
|
||||
@@ -1953,13 +1980,13 @@ ADR 0667's checks, of milestone G itself:
|
||||
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
|
||||
105. **One query finds what is behind** *(Retires at milestone H, design 47 H §764.)* (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
|
||||
106. **A delivery is waited for mesh-wide** *(Retires at milestone H, design 47 H §764.)* (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>
|
||||
@@ -1972,9 +1999,85 @@ ADR 0667's checks, of milestone G itself:
|
||||
`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`.
|
||||
108. **One composition run per candidate and machine** (design 47 G §718 to §723, §727 to §733). Two composition
|
||||
steps of one candidate started at once make one key, one request and one run ask; three steps of one revision on
|
||||
two machines start two runs, each step reading both verdicts. A machine whose verdict blames one module fails that
|
||||
module's composition step alone and says it as a warning in the others; a verdict with no `blamed` is judged as
|
||||
today, naming no culprits. A run with no `step-ended` within its bound ends `could not run` with its readers; steps
|
||||
asked again together start one run per machine that did not pass and move every former reader, a reopened
|
||||
pipeline saying `pipeline-ended` again; a run that keeps saying its progress past 30 minutes is not ended, and a
|
||||
taken ask silent for 30 minutes ends `could not run`. Both drop tools end
|
||||
the readers, and a reader-only account calling one is refused (whole, assigner and the node-engine's composer,
|
||||
mesh-delivery and `mesh-host`). Live: in the first publish after G's delivery, the composition run asks of a
|
||||
revision number at most its machines, read with `assigner_compositions` and `assigner_inputs`.
|
||||
109. **One test run per level and tested packages** (design 47 G §724 to §733). A module whose program and tools
|
||||
bundle test one directory runs its unit and integration tests once per level, both artifacts' pipeline steps
|
||||
ending with that result and naming it in `shared`, a failing test failing once, and `pipeline-ended` counting the
|
||||
module's tests once. A rerun that passes moves both artifacts' steps and the pipeline ends again; a runner
|
||||
restarted during a run takes it up again; a replaced reader leaves the ask to the others; at the cap a step ends
|
||||
`could not run` naming the fill; a second revision with the same digests runs a failed test again; a test run queued past five minutes with a
|
||||
holder present is not failed (design 47 G A-466y) (whole, runner
|
||||
and Go build module, mesh-delivery and mesh-catalog). Live: each module's test steps run once per level, read with
|
||||
`runner_test_runs`. A reader no part ends raises `pipeline-stands` within five minutes of its last sign of life
|
||||
(whole, watchman; design 47 G §732).
|
||||
110. **One merge call is delivered end to end with no hand act** (design 47 H §734 to §738, §743, §746, §750, §751,
|
||||
§771). This is the live proof of the chain (the plan's section 5, step 7), read with the tools and quoted with its
|
||||
times, not one test: with `pipelines-at-once` at 1 and one placing machine away, a merge call naming one pull
|
||||
request that changes one module says one `merge-called`; the gate writes one source revision and opens one record;
|
||||
the indexer says one `take-in.taken` naming that module alone; the runner runs one pipeline; once it passes and the
|
||||
version is released, the module is wanted and runs on every present placing machine, the record ends naming the
|
||||
machine away, and that machine applies its want when back. Each part's half is a whole test in its own repository
|
||||
(H-A-17): the forge module's (§734 to §736, §766), the gate's (§737, §738), the indexer's (§743), the runner's
|
||||
(§746), the assigner's (§750, §751) and the node-engine's (§771).
|
||||
111. **A head moved outside the mesh delivers nothing and is said** (design 47 H §739 to §742, §766). A merge made in
|
||||
the forge's screen gives one `head-moved`, no source revision and no pipeline; `head-untaken` is raised within
|
||||
`untaken-bound`, naming the repository, branch and head; a later merge call in that repository clears it;
|
||||
`gate_head_take` delivers such a head by hand, written in the hand-act log; and a forge module stopped between its
|
||||
last merge and the write of that member ends as an untaken head recovered so (whole, forge bridge and gate in
|
||||
mesh-delivery and mesh-catalog; the stop case in the forge module's whole test).
|
||||
112. **One take-in is one pipeline, and pipelines run one at a time** (design 47 H §743, §746 to §748). Split per
|
||||
module (H-A-17): the forge module's whole test that a call naming a mesh-sdk change and an importer merges both or,
|
||||
with one refused, neither; the indexer's that its `source-moved` names mesh-sdk, that importer and mesh-sdk's other
|
||||
importers as movers; the runner's that they are one pipeline in which every importer builds after mesh-sdk's
|
||||
`package-published`, that a second take-in waits and is placed on the first's end, on a cancel and on a set-aside,
|
||||
that a pipeline waiting on its `approval` step does not count and is placed first when answered, that a newer
|
||||
take-in moving the same module supersedes it in the waiting pipeline, that `pipelines-stalled` is raised when
|
||||
pipelines wait and none runs, and that a restart starts no pipeline of its own.
|
||||
113. **A want is the newest released version whose pipeline passed, written tier by tier** (design 47 H §750, §751,
|
||||
§771, §772). The assigner's whole test: a module released with a passed pipeline is wanted on every placing
|
||||
machine whatever build an acting part runs; a version whose pipeline failed is not wanted; an older end heard after
|
||||
a newer one writes nothing; a placement `build` names the want's version; a consumer's want is written only after its
|
||||
provider's tier runs, and a tier that does not run within `tier-bound` raises `tier-late`; a node-engine without the
|
||||
want-by-version capability is said held. The node-engine's whole test: the bus module's and the backup holder's
|
||||
changed wants apply first, then by `rank`, its own last.
|
||||
114. **A head whose `required` step failed is refused** (design 47 H §735). The forge module's whole test: a runner's
|
||||
`step-ended` naming a failed `required` step at a head's fingerprint makes `merge-pull` refuse that head, naming the
|
||||
step; a later passed run asked again by the operator lets it merge.
|
||||
115. **A member refused mid-call is said and raised** (design 47 H §767). The forge module's whole test against a
|
||||
fixture forge that refuses the second merge: one `merge-called` with the first member and `refused`, `merge-partial`
|
||||
raised by the call, cleared by a later call landing the refused member and by `forge_partial_clear`.
|
||||
116. **A take-in held on a full store** (design 47 H §744). The indexer's whole test: with the catalog store full a
|
||||
`source-moved` is held unacknowledged, said once as `take-in.pending`, not redelivered on a timer, and taken in on
|
||||
`room`; another branch's take-in goes on meanwhile; `indexer_take_in_skip` ends it in the hand-act log.
|
||||
117. **`validate` refuses a manifest problem and a cycle** (design 47 H §745). The assigner's and the runner's whole
|
||||
tests: a take-in whose manifest names an unknown field fails `validate` with `manifest-refused` naming it and asks
|
||||
no composition; one that makes a cycle fails it with `cycle` naming the cycle; the indexer's manifest runs no
|
||||
validator.
|
||||
118. **Every account calls every verb; a module publishes only what it declares** (design 47 H §752). The grants
|
||||
part's whole test: a module calls a verb its manifest does not invoke and is answered, publishes an event its
|
||||
manifest does not declare and is refused, and an enrolling node's account is held to its own grant.
|
||||
119. **The builder's lines** (design 47 H §753 to §758). The Go build module's whole test takes the delivery queue
|
||||
first; the builder's whole tests: a done, unreserved fingerprint asked by a build step ends carried with a version,
|
||||
a failed 0.1.19 built again is 0.1.19, a catalog entry heard with no step ask builds nothing, `build.ended` names its
|
||||
version; the runner's: a step with nothing to run ends `nothing to run` and its pipeline passes; the indexer's: a
|
||||
registration with every step `bypass` is refused, naming them.
|
||||
|
||||
## What retires
|
||||
|
||||
- From milestone H's delivery: everything design 47 H §764 lists (the per-pull-request paths of the gate and the forge
|
||||
bridge, the catch-up by comparison, the runner's sweep, the start-time `outdated`, the checker, the groups by branch
|
||||
name, the want holds A-478 ends), and the stale state H §765 drops once.
|
||||
|
||||
- The "release branches" and the controller's check of them (ADR 0358, superseded by ADR 0401).
|
||||
- The toolchain image and its module (ADR 0405).
|
||||
- The window cutter, the merge catch-up timer, the rollout ticker, mesh-delivery's tick, reconcile and
|
||||
@@ -2068,6 +2171,7 @@ release reports the controller's code lines against research 063's baseline (acc
|
||||
| L7 | History and records leave the controller (ADR 0571): the builder keeps its build log, one entry at a build's start and one at its end, from which build history and durations are read and the module mesh-catalog asks the builds it missed; the artifact sweep is the seat `mesh-artifact-sweep`, held by artifact-store-tools beside the artifact store, its keep set from the store's own listing, the wants and the build log, sweeping at each build's end from the lease write and recording each deletion in the hand-act log; disk readings are disk-load's own state on every node; who holds which seat is the state `seat-holders` of the seat `mesh-placement` (now `mesh-module-assigner`), and tools are found by the tool runners' announcements; what a node runs is its want and its have; the grants part writes `grants.<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 106 | mesh-sdk (the runtime: the fingerprint, the view, the definition reader, the seat list's one wiring), mesh-contracts and the domains' contracts modules (`acts`, the new verbs and events, the seat `mesh-grants`, the seat `git`'s verbs), mesh-delivery (indexer, assigner, checker until its removal, builder, grants part, gate's view, forge bridge, watchman, the new pipeline runner `mesh-delivery-pipeline`, `contracts` and `sdk` moved under `modules/`), mesh-catalog (the gate, the build modules, the forge module, mesh-issues, mesh-knowledge, the `node-backup` holder, the router, nats: a module's kept data on the bus as a backed-up item and the object store beside each state), mesh-sdk (also its small object store package, for values of any size), the node-engine (`mesh-host`), hq | 1966, 1961 (retargeted to this row's shape), 1660, 1972, 1721, 1783, 1785, 1794, 1791, 1373, 595; 1962 goes back with 1958, whose assignment entry it needs (ADR 0641 §3) |
|
||||
| H | The build-and-delivery system delivers itself by its one model, in six releases (H0 to H5, the plan's section 6): one merge call of the seat `git`'s `merge-pull` naming one or more pull requests is a delivery's start and its group; the gate names the merged heads one source revision and opens its record; the indexer takes it in (a commit, the fingerprints of its repositories' modules, one catalog revision) and names the movers; one pipeline per take-in, none in parallel (`pipelines-at-once`, default 1); a want is the newest released version whose pipeline passed; the forge's event is the watchdog (`head-untaken`); every delivery part wakes on its inputs alone and reads no other part's state; the per-pull-request paths, the catch-up by comparison, the sweep and the checker go; one clean state placed by hand once, after which every release is delivered by its own pipeline (ADR 0682, ADR 0681, ADR 0666, ADR 0667; design 47 H §734 to §774) | 110 to 119 | mesh-delivery, mesh-catalog, `mesh-host`, mesh-tools, mesh-sdk, mesh-contracts, hq | opened by each release's prepare |
|
||||
|
||||
An issue is in one row only (ADR 0493 §2): where a row named an issue another row names too, the last row keeps it and the
|
||||
earlier row says so in words (the operator, 2026-10-26). Milestone M1 makes each row a record of the issue tracker
|
||||
|
||||
@@ -84,9 +84,10 @@ check and deliver milestone G itself (ADR 0667 §2); each of them says so in a l
|
||||
what moved); the verb `registrations` answers every registration, or one with its history. The indexer derives the
|
||||
modules it keeps from them, and the forge bridge its watched branches, each by a first view of `registrations` and
|
||||
then that event, never by reading the ledger (ADR 0666 §3, ADR 0596).
|
||||
- §5 **An unprotected branch is refused.** `register` and `watch` read a branch's protection through the seat `git`'s read
|
||||
verb `branch` (its head, and whether a rule refuses a direct push and admits only merges), and refuse a watched branch
|
||||
the forge does not protect, naming it (ADR 0666 §3).
|
||||
- §5 **An unprotected branch is not refused at registration** (corrected in place by design 47 H §763). `register`
|
||||
and `watch` read no branch's protection and refuse no watched branch for it: the operator approved removing the
|
||||
check on 2026-11-14 (G-23, *Met during G's start*), and ADR 0682 §13 ends ADR 0666 §3's refusal, `merge-pull`'s
|
||||
protection judgement and §17's `branch-unprotected` (design 47 H §735, §739).
|
||||
- §6 **The foundation parts are the manifest validator's list.** The manifest validator's list (ADR 0619 §3) holds
|
||||
exactly the foundation parts, ADR 0619 §1's, the runner, which joins them (ADR 0666 §4), and the forge and image
|
||||
registry modules (§584); the checker leaves the
|
||||
@@ -317,8 +318,10 @@ check and deliver milestone G itself (ADR 0667 §2); each of them says so in a l
|
||||
removed with the checker's buckets and bus account, after the first pipeline after G's delivery has delivered a change
|
||||
end to end and on the operator's word (ADR 0667 §12; *How milestone G itself is checked and delivered*); the forge bridge hears the landed commit as it hears every commit of a watched
|
||||
branch.
|
||||
- §40 **The operator-channel hides no ask.** It keeps design 46's three open asks per asker, never holds the newest back,
|
||||
and replaces an open ask by the same asker's ask with the same `about` (ADR 0666 §12; design 46 §6).
|
||||
- §40 **The operator-channel hides no ask.** It keeps no count of open asks per asker and holds none back: every ask
|
||||
is offered when it is raised (A-424, the operator, 2026-11-15 about 15:50 CET), and it replaces an open ask by the
|
||||
same asker's ask with the same `about` (ADR 0682 §14, which ends ADR 0666 §12's three open asks per asker; design 46 §6;
|
||||
corrected in place by design 47 H §763).
|
||||
- §41 **How it is checked.** Whole (forge module, forge bridge): a session's `merge-pull` at its head merges with no run yet,
|
||||
and with a passed one, and asks no Approve; with the runner stopped a head merges; a head at whose fingerprint any
|
||||
run failed a `required` step, a head that moved and a branch whose protection was removed since its last move are
|
||||
|
||||
@@ -242,8 +242,9 @@ each the design's choice with its reason, §468 to §479 those of the runner's,
|
||||
whole (forge module), a head that passed, then another commit at its fingerprint failed a `required` step, is
|
||||
refused; its `seen` key goes when the pull request closes.
|
||||
- §476 **`take-in.taken`'s body and its type.** (§493) The indexer's own `take-in.taken` carries, beside what it carries on
|
||||
main, `branch` (the watched branch), `source` (the source revision taken in) and `entries`, one `{module, commit,
|
||||
fingerprint}` per module of that revision. Its body is defined in the seat `mesh-catalog`'s definition, in its
|
||||
main, `branch` (the watched branch), `source` (the source revision taken in) and `entries`, one
|
||||
`{module, commit, fingerprint, repository}` per mover of that take-in (design 47 H §743; corrected in place by H §763, where this line
|
||||
said one entry per module of the revision). Its body is defined in the seat `mesh-catalog`'s definition, in its
|
||||
section `bodies` (§439, §454), so the generated contract carries the type the indexer writes and the runner reads,
|
||||
and neither imports the other (§333). Why: a body said on a module's own stream and read by others is a `bodies`
|
||||
entry (§439), never a client's hand-written type (develop question Q-RN4). How it is checked: unit (seat generator),
|
||||
|
||||
@@ -384,12 +384,15 @@ that round are written into the lines they name, here. Questions that an earlier
|
||||
- §535 **A missing build seat and a seat with no holder, each read where it shows.** The runner reads that no build
|
||||
seat serves an artifact's language from the catalog half of its revision view: no entry whose `acts`, the acting
|
||||
rules of the seats it claims, hold a rule `build` with `on` naming that language (§323); the pipeline then ends
|
||||
failed at once, naming the language and the missing build seat. It reads that a seat has no holder from the step
|
||||
itself: an ask on that seat's work queue whose `step-started` is not heard within five minutes ends the pipeline
|
||||
failed, naming the seat (§32). It reads neither from the seat list, which answers definitions alone (§527), nor
|
||||
from any holding. Why: §32 already ends a pipeline whose step nothing starts, and the catalog half is the runner's
|
||||
one view (develop question Q-RN7). How it is checked: whole (runner), a fixture language with no build seat ends at
|
||||
once, naming it; a seat whose holder is stopped ends within five minutes, naming the seat.
|
||||
failed at once, naming the language and the missing build seat. *Amended by A-466y and A-466z (2026-11-17):* it reads that
|
||||
a seat has no holder only when the seat `mesh-module-assigner`'s view `seat-holders` names none for it (G-21 §717's
|
||||
follower; never the seat list, which answers definitions alone, §527), and a seat with none ends the pipeline failed
|
||||
at once, naming it; an ask waiting for an existing holder is timed by §86's `build-capacity-waits` and A-466s's
|
||||
`run-untaken-bound` (G-24 §720, §725), never by five minutes from the ask. Why: §32 already ends a pipeline whose
|
||||
step nothing starts, and the catalog half is the runner's one view (develop question Q-RN7); a queued step ended
|
||||
failed for "no holder" while its holder is present would say what is not true (principle 3). How it is checked:
|
||||
whole (runner), a fixture language with no build seat ends at once, naming it; a seat the seat-holders view names
|
||||
no holder for ends at once, naming the seat; a step queued past five minutes with a holder present is not failed.
|
||||
- §539 **The runner's tools are named `runner_`.** The runner's module, `mesh-delivery-pipeline`, names its tools with
|
||||
the prefix `runner_`, so the design's `runner_catch_up`, `runner_waits`, `runner_release` and `runner_health`
|
||||
stand, and its first-view tool is `runner_first_views`; `<module>_first_views` (§205) carries the prefix the
|
||||
|
||||
@@ -378,12 +378,21 @@ for several build maps is answered once, and the maps' names for it are given in
|
||||
- §646 **The runner's bodies name `fingerprint`.** (§585) The runner's `step-ended`, pipeline and wait bodies name the
|
||||
build-input fingerprint `fingerprint`, not `fp`, as §585 reads it. [mesh-delivery DQ-2.] How it is checked: unit
|
||||
(runner's contract).
|
||||
- §647 **The runner times an ask from `ask-taken`.** (§535, §602) §535's five minutes run from the ask until the build
|
||||
seat holder's `ask-taken` (§602), which the runner consumes; `step-started` is the runner's own. [mesh-delivery
|
||||
DQ-3.] How it is checked: whole (runner), an ask no holder takes ends its pipeline after the setting.
|
||||
- §648 **A `take-in.taken` entry carries the pull request.** (§476, §542) An entry is `{module, commit, fingerprint,
|
||||
repository, pull}`, the last two from a `merged` message and absent for a `pushed` one. [mesh-delivery DQ-5.] How it
|
||||
is checked: unit (indexer's contract).
|
||||
- §647 **The runner times an ask from `ask-taken`.** (§535, §602; A-466y) The runner consumes the build seat holder's
|
||||
`ask-taken` (§602); `step-started` is the runner's own. *Amended by A-466y and A-466z (2026-11-17):* §535's five
|
||||
minutes from the ask until `ask-taken` go. A seat for which the seat `mesh-module-assigner`'s view `seat-holders`
|
||||
names no holder ends the pipeline failed at once, naming it, judged only once that view's first view is read, never
|
||||
from the not-ready picture `FollowSeat` answers before it (principle 3). The runner's manifest gains the `consumes`
|
||||
entry `seat:mesh-module-assigner.views.seat-holders` (on main it has none: its `invokes` names only
|
||||
`seat:mesh-module-assigner.assignments`); an
|
||||
ask waiting for an existing holder is timed by §86's `build-capacity-waits` and by A-466s's `run-untaken-bound`
|
||||
(G-24 §720, §725), and from its `ask-taken` by its step's bound (A-466p). [mesh-delivery DQ-3.] How it is checked:
|
||||
whole (runner), a seat with no holder ends the pipeline at once, naming it; an ask a present holder has not taken
|
||||
past five minutes is not failed (test 109).
|
||||
- §648 **A `take-in.taken` entry names its repository, never a pull request.** (§476) An entry is `{module, commit,
|
||||
fingerprint, repository}`, the repository from the gate's `source-moved` (design 47 H §743); the field `pull` goes,
|
||||
since nothing reads a pull request after the merge call (ADR 0682 §1; corrected in place by H §763). [mesh-delivery
|
||||
DQ-5.] How it is checked: unit (indexer's contract).
|
||||
- §649 **`ParseStepKey` answers the asker.** (§484) `buildstep.ParseStepKey(key)` answers `(asker, node, id, err)`,
|
||||
`asker` empty for main's form. [mesh-delivery DQ-8.] How it is checked: unit, both forms.
|
||||
- §650 **The `mesh-builds` client's name.** (§586) It is `contracts/go/clients/meshbuildsclient`, with `Reserved`.
|
||||
@@ -400,9 +409,8 @@ for several build maps is answered once, and the maps' names for it are given in
|
||||
|
||||
- §654 **The readers of the forge module's old events and tools move to the seat `git`.** (§310, §311, §313, §431;
|
||||
ADR 0659 §1) [mesh-catalog Q-F1.]
|
||||
- **mesh-config** consumes `git`'s `pull-merged` and `pull-closed` in place of `gitea.pull.merged`,
|
||||
`gitea.pull.closed` and `gitea.forge.pull-request.closed`, and invokes `seat:git.pull` in place of
|
||||
`gitea.gitea_get_pull_request`; **the records module** consumes `git.pull-merged`.
|
||||
- **mesh-config** consumes no pull request event and invokes no `seat:git.pull` (ADR 0681 §1, which replaces this
|
||||
bullet's first form; corrected in place by design 47 H §763); **the records module** consumes `git.pull-merged`.
|
||||
- **The order.** Main's forge module says its own `pull.merged`, not the seat's events, so each consumer of
|
||||
`git.pull-merged` or `pull-closed` is ordered after the forge module's version that says them, by the edge of kind
|
||||
6 its `consumes` gives (§558); its durable consumer is made from the stream's first message, so no merge said
|
||||
|
||||
@@ -3,7 +3,7 @@ layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: G
|
||||
updated: 2026-11-11
|
||||
updated: 2026-11-17
|
||||
decisions:
|
||||
- "ADR 0667"
|
||||
- "ADR 0666"
|
||||
@@ -149,7 +149,7 @@ One file of milestone G's part of [design 47](../47-delivery-from-commit-to-deli
|
||||
| `pipeline-started`, `pipeline-ended` | a pipeline's start, and its end with every step's result, its test counts, the source revision and `widens` |
|
||||
| `group-ended` | a group's one pipeline's end, on which alone its wants are written |
|
||||
| `run-started` | a run on request's start, with its members at their commits |
|
||||
| `step-started`, `step-ended` | each step's start and end: the step, its status in the policy, its outcome, its build-input fingerprint, its test counts, for a carried result what it was carried from, and for a rerun that it is one and the caller the runtime proved; a bypassed step too |
|
||||
| `step-started`, `step-ended` | each step's start and end: the step, its status in the policy, its outcome, its build-input fingerprint, its test counts, for a carried result what it was carried from, and for a rerun that it is one and the caller the runtime proved, for a step that read a test run or a composition run another step asked its `shared` (G-24 §729); a bypassed step too |
|
||||
| `wait-held`, `wait-ended` | a step's wait: on a person (approval, code review), on a build node, on the revision view |
|
||||
|
||||
- §74 **What a session hears after its merge.** Between its `merge-pull` and the delivery, a session waits with `mesh_wait`
|
||||
@@ -195,14 +195,14 @@ four lines a module's tools answer; every read tool of a store also answers its
|
||||
|
||||
| Part (seat) | Read everything it holds | Do by hand what it does itself | Recover without help |
|
||||
|---|---|---|---|
|
||||
| the runner (`mesh-pipeline-runner`) | `show` (one pipeline whole, its steps, step log and outputs), `list` (the pipelines of a module, a branch or a commit), `stands` (what stands still, since when), `why-carried` (where a step's result was carried from), `kept` (the kept results by digest) | `start` (a delivering pipeline for a watched branch's head), `run` (the run on request), `rerun` (one step again) | `accept` (a failed `optional` step, with why), `cancel` (a pipeline, dropping its asks), `ask-again` (a declined `approval`) |
|
||||
| the runner (`mesh-pipeline-runner`) | `show` (one pipeline whole, its steps, step log and outputs), `list` (the pipelines of a module, a branch or a commit), `stands` (what stands still, since when), `why-carried` (where a step's result was carried from), `kept` (the kept results by digest), `runner_test_runs` (each test run, G-24 §728) | `start` (a delivering pipeline for a watched branch's head), `run` (the run on request), `rerun` (one step again) | `accept` (a failed `optional` step, with why), `cancel` (a pipeline, dropping its asks), `ask-again` (a declined `approval`), `runner_test_runs_drop` |
|
||||
| the indexer (`mesh-catalog`) | `registrations` (with each one's history); `indexer_edges` (an artifact's edges per watched branch), `indexer_order` (the order of a change, its cycles named), `indexer_catalog_difference` (two revisions); `indexer_pending` (a group with its missing members) | `register`, `policy`, `watch`, `unwatch` (each on the operator's Approve) | `indexer_seed_again` (the first registrations' ask raised again), `indexer_take_in_pending` (a group taken in as gathered), `indexer_drop_pending` (dropped) |
|
||||
| the gate (`mesh-delivery`) | `source` with a branch (`gate_source`: every branch's source revision) | — | `gate_source_again` (say `source-moved` again for a branch) |
|
||||
| the forge module (`git`) | `git_failed_steps` (the failed `required` steps it holds, by module and fingerprint, with the run that failed each) | — | `git_failed_steps_drop` (drop one, with why) |
|
||||
| the grants part (`mesh-grants`) | `grants_callers` (the callers each verb admits, read from the seat definitions) | — | `grants_why_refused` (for an account and a verb, the grant it lacks and the definition's line that leaves it out) |
|
||||
| the build seats | `steps` (the steps detected for an artifact) | `steps` with `again` (detect again) | `drop` (ADR 0664 §4) |
|
||||
| the builder (`mesh-builds`) | `builder_reserved` (each module's reserved version, §369); the released versions are the catalog's `versions` | `builder_publish_again` (publish the missing artifacts under the reserved version) | — |
|
||||
| the assigner (`mesh-wants`) | `assigner_why_not` (why a module is not on a machine yet: the pipeline it waits for, its hold, the placement, the node's last `running`) | — | `assigner_release` |
|
||||
| the assigner (`mesh-wants`) | `assigner_why_not` (why a module is not on a machine yet: the pipeline it waits for, its hold, the placement, the node's last `running`), `assigner_compositions` (each composition run, G-24 §728) | — | `assigner_release`, `assigner_compositions_drop` |
|
||||
| the watchman | `watchman_views` (how far behind each part's view is, from each part's `view-waits` and first-view tools) | — | each part's `<module>_first_view_again` |
|
||||
| the operator-channel | `asks` (with each asker's asks held back) | — | `ask-again` (offer a held-back ask now) |
|
||||
| every module that imports mesh-sdk's small object store package | `<module>_state_objects`, `<module>_sent_objects` | — | `<module>_state_objects_drop`, `<module>_sent_objects_drop` |
|
||||
@@ -230,6 +230,8 @@ and an estimated 2 mesh-sdk publishes a day, each rebuilding about 120 artifacts
|
||||
| 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 assigner | `composition-runs`: one key per candidate and machine, its program, input, ask, readers and verdict (G-24 §719) | old `state` section, `max-mib` the setting `composition-runs-cap-mib` | the setting `composition-runs-kept` (default 24 hours) after its end; deleted by the assigner (§719) | default 16 MiB; an estimated 30 candidates a day on four machines, 120 keys of at most 8 KiB, is under 1 MiB a day |
|
||||
| the runner | `test-runs`: one key per candidate, level and tested packages, its ask, readers, outcome and counts (G-24 §725) | old `state` section, `max-mib` the setting `test-runs-cap-mib` | the setting `test-runs-kept` (default 7 days) after its end, deleted by the runner in the step log's order with its output object in `test-runs-objects` (§330) | default 16 MiB; an estimated 1,000 test runs a day of about 1 KiB is about 7 MiB at 7 days |
|
||||
| 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 |
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,209 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: G
|
||||
updated: 2026-11-17
|
||||
decisions:
|
||||
- "ADR 0667"
|
||||
---
|
||||
# 47, milestone G — what is owed once G is delivered
|
||||
|
||||
The list of what waits for G's delivery: the operator's remarks deferred while G was brought up, the stand-ins the
|
||||
lead's answers mark to go after G, the hand state of G's live start, and the faults met on the way. It is checked when
|
||||
G is delivered: each item is then removed, taken into a design or a record through its playbook, or noted on the issue
|
||||
that covers it (asking the operator before a new issue). An item is struck from this list in the same pull request that
|
||||
deals with it, which is how the list is kept true.
|
||||
|
||||
## The operator's remarks (2026-11-14, deferred until G is live)
|
||||
|
||||
1. **Two graphs only:** the catalog graph and the assignment graph. Each node's modules publish the state they own and
|
||||
the version they run on the bus; a gap between the assignments and what a node says is closed by the node-engine.
|
||||
2. **What a node can run is checked only on assignment and un-assignment** (for the modules that depend on it), never
|
||||
as an input to every computation. The glossary's *assignment graph* and ADR 0656 say the assigner computes from the
|
||||
catalog graph, the placements and the nodes' capabilities: check the record and the code against this.
|
||||
3. **Assignments enter as commands** (the seat `mesh-module-assigner`'s `propose`: place, take off, ...); the assigner
|
||||
computes no placement, it only derives each placed module's version from the catalog graph into the wants. Check the
|
||||
glossary's wording against this.
|
||||
4. **A pin** ("use this provider for this provision") may not belong in the assignments at all: question it, and what
|
||||
the provision wiring should be instead.
|
||||
5. **Who says a node's running versions:** the node-engine (its haves) or each module itself. The operator's picture
|
||||
is each module; check which the design means.
|
||||
6. **One address for a seat's view.** A reader's manifest names the assigner's view by its seat, the reader's code asks
|
||||
the holder module's tool by its module name, and the grants part translates one into the other (and gave only the
|
||||
events, not the right to ask: the indexer's first view was refused at G's live start). One address, the same in
|
||||
manifest, code and rights.
|
||||
7. **A registration is part of the module graph, not a list beside it.** After G's start the module graph held 178
|
||||
modules while the registrations held none, with a seed ask to copy them from the old registry. Check the design
|
||||
against one graph whose entries are the registrations and what each registered repository says.
|
||||
8. **One bookmark (durable consumer) per process, never shared** (A-397). A module's program and its tool runner read
|
||||
events under one durable name; the runner took all 178 first registrations and the program heard none, silently.
|
||||
Share a durable name only for shared work (a queue). Owed: amend design 19's "one durable consumer per module"
|
||||
(written when a module was one process) and the lines of designs 25, 32 §3, 57, G-5 and G-8 that follow it; build
|
||||
per-process names in the grants part, mesh-sdk's process hub and the tool runner, with a start refusal and a log
|
||||
line; the test of two processes of one module both hearing one event on a real bus; a check that a durable has one
|
||||
reader; and a design-review playbook question: "what if two processes of one module do this?"
|
||||
9. **The same mistake elsewhere.** A survey at G's start found it live in three modules (the assigner, the indexer and
|
||||
the grants part: the runner acks and drops what no tool view wants) and possible in every module whose tool runner
|
||||
arrives later (builder, checker, forge bridge, pipeline runner, teller, view, watchman, distribution, recovery).
|
||||
Already avoided: the bus and zfs keepers (A-340), the node-engine, work queues. Also: a seat verb served by both a
|
||||
program and its runner in one queue group splits the answers between them; durables nothing reads keep pending
|
||||
messages.
|
||||
10. **`registration-changed` is said for a first registration too:** check the event's name against what it says.
|
||||
11. **Silent waits met during G's start:** the indexer's first versions fill returns without a word while another fill
|
||||
runs, so a hung fill held every later one silently for two hours; `grants_membership` and `grants_assert` time out
|
||||
after 30 seconds with no log line; the tool runner says a dropped event once per key.
|
||||
12. **The module graph's edges are dependencies, never verbs or bus subjects** (2026-11-16; principle 9): a manifest
|
||||
says what its module depends on, a seat where the need is meant to be interchangeable and otherwise a module (a
|
||||
build dependency on a package module, a program needing another module), and the graph's edges come from that
|
||||
alone. The verb edges of ADR 0614 §2 and §3, and the cycle exceptions they needed (A-361, A-428, A-437), go; whether
|
||||
`invokes`, `uses` and the `views` forms stay in a manifest at all is asked with the research on the mesh's
|
||||
accounts, and "each fact is declared in one place".
|
||||
|
||||
13. **A full delivery cycle by hand** (the operator, 2026-11-17 about 09:00: "make sure that every part of the
|
||||
build-and-delivery system is also doable by hand via mcp tools", "so you can fully take control of a full cycle";
|
||||
asked when, "after G"; principle 4). A survey of 2026-11-17 found, along the cycle merge, the gate's source,
|
||||
take-in, entries, pipeline, steps, release, wants, grants, put and running: about 52 acts a module does by itself
|
||||
with no hand tool, about 110 bus states with no per-key clear and 26 with no read tool, all but one of about 25 capped
|
||||
states with no fill against their cap, and 14 recoveries with no tool. One milestone: the SDK's state tools for
|
||||
every declared state (read, fill against cap, clear a key, drop key-gone objects), the missing hand acts per module,
|
||||
a summary of the pipeline runner's pipelines by outcome, `source-moved` and the runner's `ended` declared so they
|
||||
can be waited on, and the catalog check that refuses a module whose state or act has no tool. Also a consumer
|
||||
composed from the union of the want's and the trunk's manifests, as grants already are (a bundle's new `consumes`
|
||||
is unbound until a want names its build).
|
||||
|
||||
14. **No pass waits on a call** (principle 1; from the node-engine's #233 (`mesh-host`), A-461b): the node-engine's composer asks the seat
|
||||
mesh-catalog's `module` for a trunk build at the top of every pass and waits up to the call's bound, so a seat that
|
||||
answers slowly stalls every pass. The ask goes beside the pass, which composes with what it holds and takes the
|
||||
answer at the next pass.
|
||||
|
||||
## Met during G's start (2026-11-14)
|
||||
|
||||
- **The seed of registrations** left out modules whose manifest lives in the application's own repository on its
|
||||
watched branch, so they were assigned but unheld and the assigner refused every proposal (ADR 0567 §2). The seed
|
||||
should register every assigned module from where its manifest is.
|
||||
- **The indexer's catch-up and take-in** say nothing in the indexer program's journal.
|
||||
- **The provisioner** drops a published composition with neither plan nor refusal silently and then removes the
|
||||
node's plans; no read tool shows a node's composition.
|
||||
- **The node-engine** is refused the builder's `build.ended` by the bus every five minutes: the grants part does not
|
||||
give it; to fix before builds matter.
|
||||
- **The register verb refuses an unprotected watched branch:** the operator approved removing the check (from the
|
||||
seat `mesh-catalog`'s definition and the indexer that serves `register`).
|
||||
|
||||
## Stand-ins the lead's answers mark to go after G (2026-11-16)
|
||||
|
||||
- **A-436 with A-430b:** a want carries parts beside its version for a node-engine that reads parts, and a module
|
||||
wanted with no passed pipeline names the parts its `build.ended` made until its release is heard.
|
||||
- **A-438:** for an acting wait, a running have whose node-engine states no health counts as healthy, and an online
|
||||
node runs its node-engine; goes when every node-engine states health.
|
||||
- **A-439:** `assigner_written` with `why` answering for `assigner_why`.
|
||||
- **A-434:** every account may do everything, and every seat verb admits every caller, until the research on the
|
||||
mesh's accounts replaces it (the operator, 2026-11-15: three accounts, mesh, agent and operator; approval only as a
|
||||
per-tool mark for agent calls).
|
||||
|
||||
## Hand state of G's live start (2026-11-16)
|
||||
|
||||
- **Runtime drop-ins on the control-node** that pin a hand-made fingerprint (and the tool runner's environment) for
|
||||
the grants part, the teller, the forge bridge and the tool runner. A delivery does not remove them: each goes before
|
||||
its module restarts on the delivered build, or the module believes it runs the old one.
|
||||
- **Hand-placed builds** (the indexer and its tools, the tool runner, the control-node's node-engine, the assigner) are
|
||||
replaced only by their deliveries; check each is.
|
||||
- **About 80 hand-built modules on the control-node have no catalog entry:** their first move is held for a backup
|
||||
(the kept-form hold).
|
||||
|
||||
## Faults met on the way (2026-11-16; note each on the issue that covers it)
|
||||
|
||||
- `node-files.delete` cannot move a root-owned file to the trash; `node-service-manager` has no daemon-reload.
|
||||
- The indexer does not stop on SIGTERM: it keeps draining build-log entries until systemd kills it.
|
||||
- The backup ask's headline says "backup failed" for a kept-form hold.
|
||||
- The assigner logs a line naming about 140 modules every one to three seconds, and did not raise the backup ask
|
||||
again after a restart.
|
||||
- `mesh_wait` refuses the operator channel's events: `operator-channel` is neither a seat nor a module of the catalog
|
||||
half.
|
||||
- Four tests of mesh-delivery fail on main, reading files that do not exist there: `sdk`'s
|
||||
`TestThePackageArtifactNamesNoPathForTheWholeDirectory`, `sdk/buildstep`'s two fixture tests and
|
||||
`meshdeliveryclient`'s `TestTheRemovedVerbsAreTheDefinitionsRemovedRows`.
|
||||
- The node-engine's repository holds about 1721 unit tests against the budget of 500.
|
||||
- The live indexer was seen refusing the assigner's manifest for claiming `mesh-placement`, which neither main nor
|
||||
G's branch claims: confirm the verdict after G's take-in.
|
||||
|
||||
## Tests run against what runs (the operator, 2026-11-16 about 13:00 CET)
|
||||
|
||||
- **A test runs against the bus as the mesh composes it.** The pipeline runner's integration test made its own
|
||||
shared event stream catching every seat event, so a step's end reached the runner there; on the live bus a step's
|
||||
end is a kept event on a stream of its own, which the runner never bound, and no pipeline could pass (fixed in the
|
||||
runner at G's start, 2026-11-16). Wanted: a principle ("a test runs against what the module runs against: the bus as
|
||||
the mesh composes it from the manifest, never a layout written in the test"); the shared library gives an
|
||||
integration test the streams, kept streams and consumers the composition makes for the module's manifest; every
|
||||
integration test that creates its own streams moves onto it (count them first); the runner's test publishes a step's
|
||||
end on the kept stream.
|
||||
- **A handler of a kept event is heard or fails loudly.** Starting a program's events binds only the shared stream;
|
||||
kept seat events need a second call, and a program that registers a handler for one and never makes it hears
|
||||
nothing and says nothing. The shared library binds the kept streams of every registered handler itself, or refuses
|
||||
to start.
|
||||
|
||||
## One way of asking work (2026-11-16)
|
||||
|
||||
- The builder, the pipeline runner, the indexer (its validation before a take-in) and the checker each ask the build
|
||||
seats in a shape of their own; the validation rides the check queue behind pipeline steps (a 6-second validation
|
||||
waited over 20 minutes). Parked by the operator for research right after G: one generic pipeline for work and gates.
|
||||
- An ask given again after a fix keeps its old form (a step asked with no module directory came back without one).
|
||||
- The builder asks a failing build again every two to three minutes, reserving a new version each time.
|
||||
- The builder's queue tool lists only the oldest 50 waiting entries (left over from 2026-11-14), so it cannot show
|
||||
what waits now.
|
||||
- The pipeline runner serves no tools on the control-node and logs nothing per step; the build seat's step events say
|
||||
no pipeline before a step ends; `mesh_wait` refuses the build seats' and the runner's events; the bus's stream reader
|
||||
cuts a body at 4 KiB; a running test step logs nothing.
|
||||
- `TestTheBuildModulesKeepNoCopyOfTheDeliverySDKsStepCode` fails on mesh-catalog's main (the empty
|
||||
`modules/mesh-build-go/buildstep` directory); the seven `checks/` tests, nats-tools and distribution fail in a run over
|
||||
the whole of mesh-catalog.
|
||||
- The glossary's **pipeline** and **pipeline step** entries leave out the build, which the runner asks as the step
|
||||
`build` of the seat `mesh-builds`: correct them.
|
||||
- A pipeline the runner set aside before A-446 with steps already written (`main.940.mesh-delivery-sdk`) is started
|
||||
again by neither of the runner's start paths.
|
||||
- The node-engine's journal and the have's phases say a module is "held" and that the node "keeps running what it
|
||||
runs" for one thing: a module left on the build it runs, its new build not applied. The operator, 2026-11-17, wants
|
||||
those words gone: retire "held" and "kept" in that sense from the node-engine's lines and the glossary, with one
|
||||
glossary word in their place.
|
||||
- A composition that passes on every machine as "not judged: the composer was handed no seat list" is reported as
|
||||
passed: a composition step that judged nothing must fail or say so (principle 3).
|
||||
|
||||
## From the composition runs of 2026-11-17
|
||||
|
||||
- **The node-engine answers `compose-candidate` with different bytes for one candidate.** Within 30 seconds the
|
||||
assigner kept twelve inputs of exactly 1,491,623 bytes with different digests for the same revision. The bytes differ
|
||||
in the node-engine's answer, not in the assigner's request; a guess, not checked: a slice whose order changes between
|
||||
asks, perhaps `ComposedHow.Running`. Under design 47 G §718 one composition run per candidate and machine asks each
|
||||
node once, so this no longer multiplies anything and stays out of G (principle 7; the coordinator, 2026-11-17). After
|
||||
G: find it by comparing two kept inputs of one node, read by digest through `mesh-wants`' `input`, and decide whether
|
||||
the answer must be the same bytes while the node is unchanged.
|
||||
- **Design 47's main file and G-22 are split** (playbook 02, *The shape of a design*). The main file is about 250 KB
|
||||
against its 80 KB bound, and G-22 about 165 KB against a milestone file's 60 KB. The operator decided at 10:31 CET on
|
||||
2026-11-17 that the split comes after G, as a separate amendment.
|
||||
|
||||
## Faults met on the way (2026-11-17; note each on the issue that covers it)
|
||||
|
||||
- **The assigner's long line, met a second time.** On 2026-11-17 from 11:02 CET the assigner on the stable node logs,
|
||||
several times a minute, that "the manifest of the running build of" about 100 modules "cannot be read, so what the
|
||||
module graph says they serve is counted as served". Cause not yet known: nearly every module is named, so the
|
||||
assigner reads the running builds' manifests where none is kept. Being the second meeting, its fix is folded into
|
||||
G-24's assigner change once A1 to A7 are built. Cause found the same day: the assigner reads a running build's
|
||||
manifest only from the builder's end in its stream, which the builder has said only since 2026-11-11, so no build
|
||||
made before then has one. G-24 says the list once per change of the set; after G, the builder says the end of each
|
||||
build it keeps into its stream once (principle 1; the alternative, reading the catalog entry at that fingerprint,
|
||||
reads another module's data).
|
||||
- **The Node build modules disagree on their toolchain.** On 2026-11-17 shanks's recipe differed from the other three
|
||||
nodes', and g14 ran Node v26.13.1 against v26.13.0, so no version and recipe held a majority, and lidarr, radarr and
|
||||
gitea had no fingerprint at revision 449 (A-470j keeps that from leaving whole machines not judged). After G: one
|
||||
version and one recipe declared through the mesh on every build node.
|
||||
- **The catalog had not taken in the node-engine's merge #234** by revision 450 (2026-11-17 about 11:50 CET), and the
|
||||
indexer's module reads answered "no responders": read why after G-24's delivery.
|
||||
- **The builder's and teller's integration tests fail only the 30 s setup bound under load**, and pass idle: the bound's
|
||||
kind (a setup bound judged on a busy build node) is decided after G.
|
||||
- The runner's journal floods with ends that name `pipeline ""`: the build seats' run asks are heard on the runner's
|
||||
subjects.
|
||||
- `TestAProposalIsAnsweredApprovedAndWritten` (assigner) fails on main; `TestTheNodeComposesItsWantsFromTheBus`
|
||||
(node-engine) fails now and then.
|
||||
- `mesh-enrolment` is placed on no node, so its composition step can never run and it never releases.
|
||||
- `claude_code_wait`'s `said` refused a wait past its bound; `mesh_wait` cannot wait on the gate's `source-moved` nor on
|
||||
the runner's events.
|
||||
@@ -0,0 +1,290 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: G
|
||||
updated: 2026-11-17
|
||||
decisions:
|
||||
- "ADR 0667"
|
||||
- "ADR 0666"
|
||||
- "ADR 0596"
|
||||
- "ADR 0564"
|
||||
- "ADR 0267"
|
||||
---
|
||||
|
||||
# 47, milestone G: one composition run per candidate and machine, one test run per level and tested packages
|
||||
|
||||
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".
|
||||
|
||||
*§718 to §733 come from milestone G's live delivery of 2026-11-17. The 24 pipelines of one catalog revision asked 96
|
||||
composition runs, one per pipeline and machine, and 80 more when they were asked again. Each run kept its own copy of
|
||||
a node's input of 1.1 to 1.5 MB in the assigner's state `inputs`, which reached its 64 MiB cap twice. The indexer's
|
||||
and the teller's same failing tests failed once per artifact. The operator, 2026-11-17 about 10:20 CET: "In G, now".
|
||||
Each line is a choice within ADR 0666 §7, §8 and §17, settled by the principle it names. The review by architectural
|
||||
domain of 2026-11-17 was answered by the lead in A-466 to A-466l (G-22), each cited at the line it settles.*
|
||||
|
||||
### Composition runs
|
||||
|
||||
- §718 **One composition run per candidate and machine.** (§354, A-226, A-243, A-252, A-466l; ADR 0666 §17; principle
|
||||
7) The assigner, holding the seat `mesh-wants`, composes each machine once per candidate, whatever number of
|
||||
composition steps name it. The candidate is named by its key (A-226): `<branch>.<revision>` for a branch pipeline,
|
||||
`run-<id>` for a run on request. The first composition step of a candidate that needs a machine starts that machine's
|
||||
composition run: one `compose-candidate` ask of the node, its request kept once in `inputs`, one `run` ask on
|
||||
`node-build-go`. Every other composition step of that candidate whose module is placed on that machine (A-252) reads
|
||||
that run's verdict, under §720's rules. The request carries the candidate's manifests, verdicts and seat
|
||||
definitions, depth compose, the one machine and the case `change`, and the node's own `compose-candidate` answer at
|
||||
the moment the run started; it carries nothing of the module whose pipeline asked it. A step of the same candidate
|
||||
that comes later so reuses a verdict composed from the node's answer of that earlier moment, knowingly: within one
|
||||
candidate, that answer is the machine as the candidate is judged on it (A-466l). The composer program is chosen once,
|
||||
when the run starts, by A-252's and A-451's rule, and recorded in the run. This replaces "one run ask per machine" for
|
||||
each composition step (A-243, A-252) with one per candidate and machine.
|
||||
- §719 **Kept in the assigner's state `composition-runs`.** (§354, §85; ADR 0666 §4, §7; A-466e; principles 1, 2, 7 and
|
||||
11) Each composition run is one key of the assigner's old `state` section `composition-runs`, whose `max-mib` is the
|
||||
assigner's setting `composition-runs-cap-mib`, default 16. The key is `<candidate key>.<machine>`, each part escaped as
|
||||
a key's name (`keys.EscapeName`). The step that starts the run writes the key create-only, so two steps of one
|
||||
candidate starting at once start one run and the second reads it. The value holds:
|
||||
- `candidate` and `machine`;
|
||||
- `program`: repository, commit, directory, and the node-engine fingerprint it was chosen from;
|
||||
- `input`: the digest of the kept request;
|
||||
- `ask`: the id of the build seat's run ask;
|
||||
- `started`;
|
||||
- `readers`: the step keys of the composition steps reading the run, each added and removed by compare-and-set;
|
||||
- at the run's end, `ended`, `outcome` (`passed`, `failed` or `could not run`, with its words) and `verdict` (that
|
||||
machine's composer verdict, §721).
|
||||
|
||||
A step waiting on a running composition run hears its end through the assigner's own watch of that key (a module
|
||||
watches its own state, principle 1). At its start the assigner takes up again each key with no `ended`, by its
|
||||
`ask`'s `step-ended` (A-240) and the bound of §720. The assigner deletes a key once the time its setting
|
||||
`composition-runs-kept`, default 24 hours, names has passed since its `ended`; both this and the bound are judged as
|
||||
the state `inputs` is (A-465b). At the cap no run is started, and its steps end `could not run`, naming the fill (as
|
||||
A-465a).
|
||||
- §720 **What a run's result serves, and its bound.** (§75, §86, §718; ADR 0666 §8, §17; ADR 0596; ADR 0564 §2;
|
||||
A-466, A-466b, A-466n, A-466p, A-466q, A-466s; principles 1 and 3)
|
||||
- **Within its candidate only.** An ended run's verdict is read only by composition steps of the same candidate. A
|
||||
step of another candidate starts a run of its own; nothing composed for one candidate crosses to another.
|
||||
- **`could not run` is never read.** A step that finds an ended run whose outcome is `could not run` starts a new
|
||||
run, replacing the key by compare-and-set; its former readers have already ended `could not run` with it.
|
||||
- **The bound times owed progress, not run length** (§75; ADR 0564 §2; A-466n, A-466p). A run has one clock: a bound
|
||||
key `bound.<run key>` in `composition-runs`, with its own time to live (A-77, A-101). The assigner writes it at
|
||||
the build seat's `ask-taken` of the run's ask, and writes it again at each `step-progress` of that ask, its time
|
||||
to live the assigner's setting `composition-step-bound`, default 30 minutes. An ask still waiting in the queue has
|
||||
no clock: it is timed by §86's build-capacity finding, since a `could not run` for a run that only waited for a
|
||||
build node would say what is not true. A run that runs past 30 minutes and keeps saying its progress is never
|
||||
ended by it.
|
||||
- **When the clock ends.** Its expiry, heard as the bus's event, ends the run: the assigner drops its ask (§119,
|
||||
A-182), writes `ended` with `could not run` naming the ask and the bound, and ends every reader `could not run`
|
||||
with it. A `step-ended` of that ask heard later is ignored, said in its journal with the ask and the run's key.
|
||||
- **A run never taken** (A-466s). A run whose ask has no `ask-taken` within the assigner's setting
|
||||
`run-untaken-bound` after its `started`, default 24 hours, ends `could not run` the same way, naming the bound;
|
||||
§86's `build-capacity-waits` says it meanwhile.
|
||||
- **What the assigner hears** (A-240, A-466q). Its manifest gains `consumes` entries for the build seats'
|
||||
`ask-taken` and `step-progress`, heard on its durable consumer as A-240 hears `step-ended`. The assigner never
|
||||
reads the build seat's state (ADR 0596).
|
||||
- §721 **A machine's verdict names the modules it blames.** (ADR 0666 §17; A-452, A-466g, A-466h, A-466r, A-466u; principles 10, 3, 7
|
||||
and 11) The composer's verdict of a machine (mesh-delivery-sdk's `composer.Machine`, answered by the node-engine's
|
||||
`mesh-compose`) gains `blamed`, a list of `{module, problem}`.
|
||||
- **What it names.** Each module that the candidate's composition of the machine holds or refuses and the
|
||||
composition without the candidate does not (the modules in its input's `HeldBefore` are left out). Two modules
|
||||
owning one path are each blamed, with that path. `composes` stays false when the machine does not compose with
|
||||
every module of the candidate. A machine that does not compose and blames no module fails on the node's own
|
||||
account (its own composition, or no module composed at all, as A-452 has it).
|
||||
- **How culprits are found, and its bound.** Only the candidate's changed modules placed on the machine (those whose
|
||||
entry in the candidate differs from the composition without it) are held, one at a time, each try composing once
|
||||
more; the search ends at the first module whose hold ends the problem, as the indexer's validator names a manifest
|
||||
whose removal ends a problem. It composes at most once per such module plus once, never more than `blame-tries`, the
|
||||
assigner's setting, default 20, carried in the run's request to the composer (the request's field
|
||||
`blame-tries`), since the composer program has no settings of its own (A-466r); past that bound, the modules not yet tried are named in `blamed` with the words
|
||||
"not tried: the search reached its bound".
|
||||
- **An old composer.** A verdict with no `blamed` field (a node-engine's composer from before this line) is judged as
|
||||
today: a machine that does not compose fails every composition step placing a module on it, with the warning "the
|
||||
composer names no culprits".
|
||||
- **No order between them.** mesh-delivery-sdk's `composer` package is published before the node-engine and the
|
||||
assigner build (an edge of kind 1, as for every package); nothing orders the node-engine's composer before the
|
||||
assigner, since an assigner meeting an old composer judges as today (A-466u).
|
||||
- §722 **One module's fault fails only its own pipelines.** (§721; ADR 0666 §9, §17; A-452; principles 10 and 3) A
|
||||
composition step judges each of its machines from that machine's verdict:
|
||||
- `failed` when the verdict blames the step's module, or when the machine does not compose and blames no module;
|
||||
- `could not run` when the composition run could not run;
|
||||
- `passed` otherwise, with a warning for each module blamed there that is not the step's own (`<machine> holds
|
||||
<module>: <problem>`). Another module's fault is so said in every pipeline it touches and fails none of them.
|
||||
|
||||
The step's outcome then follows from its machines, as today: failed before could not run before passed (§354). A
|
||||
machine that is away passes with a warning and is not composed (§64).
|
||||
- §723 **How a composition run ends and is said.** (§73, §116, §119, §496, A-182; ADR 0666 §7, §21; A-466j;
|
||||
principles 1, 7 and 8) A composition run says no event of its own. Its end is the build seat's `step-ended` of its
|
||||
`ask`, which the assigner alone hears (A-240). Each composition step reading the run says its own `step-ended` on
|
||||
`mesh-wants`, as today, with its own build-input fingerprint and `shared` (§729), naming per machine the run it read,
|
||||
that run's `ask` and its verdict: the result was taken from the build seat's holder once, at that ask, and the step
|
||||
names it, as §25's carry names where a carried result came from (ADR 0666 §21). Each reading step says its
|
||||
`step-progress` once a minute while it waits (A-262), naming the runs' asks in `shared`. A step that is superseded or
|
||||
cancelled leaves `readers`. The run's `ask` is dropped (§119, A-182) only when no reader is left, so a superseded
|
||||
pipeline never takes away another pipeline's composition run.
|
||||
|
||||
### Test runs
|
||||
|
||||
- §724 **One test run per level and tested packages.** (§22, §25, §27, §416; ADR 0666 §8, §17; ADR 0267 §1; A-466,
|
||||
A-466d; principles 3 and 7) The runner asks a lint, unit test or integration test step of a build seat once per
|
||||
candidate, level and tested packages, whatever number of artifacts' steps name them. A test step's candidate is its
|
||||
pipeline's in A-226's form: `<branch>.<revision>`, or `run-<id>` for a run on request. A module's program and its
|
||||
tools bundle are built from different import closures (ADR 0267 §1), but their test steps run the packages of one
|
||||
directory (the build seat's `steps`, §22), so one set of tests is run. The share digest is the sha256 of:
|
||||
- the step's build-input fingerprint with the artifact's own part left out (its program's package and recipe), so two
|
||||
artifacts of one directory meet;
|
||||
- the step's status in the policy (§23), so the key is §25's carry key: two artifacts whose policies differ do not
|
||||
share;
|
||||
- the sorted lines `<package>@<digest>`, one for each package the step would run after its carry (§25: those with no
|
||||
kept result for their digest), the digests being those the runner already reads for its carry (§416).
|
||||
|
||||
The first step of a key puts the build seat's `step` ask; every other step of the same candidate with that key reads
|
||||
its result. An ended run's result is read only within its candidate; a step of another candidate asks a new run, and
|
||||
a passed result crosses candidates only as §25's carry, through `kept`. A `could not run` result is never read: a
|
||||
step finding one asks a new run, replacing the key by compare-and-set. So within a candidate the same failing tests
|
||||
fail once, not once per artifact, and a second revision with the same digests runs a failed test again.
|
||||
- §725 **Kept in the runner's state `test-runs`.** (§27, §85, §330; ADR 0666 §4; A-466e, A-466f, A-466p, A-466v; principles 1, 2, 3, 7
|
||||
and 11) Each test run is one key of the runner's old `state` section `test-runs`, whose `max-mib` is the runner's setting
|
||||
`test-runs-cap-mib`, default 16. The key is `<candidate key>.<level>.<digest>`, each part escaped as a key's name,
|
||||
written create-only by the step that asks the run. The value holds:
|
||||
- `level` and `digest`; the list of packages with their digests is in the run's output object, never in the key or
|
||||
the value;
|
||||
- `seat` and `ask`, and `node` once a holder has taken the ask;
|
||||
- `started`;
|
||||
- `readers`: each reading step's pipeline key and artifact, added and removed by compare-and-set;
|
||||
- at the run's end, `ended`, `outcome`, its test counts, and the name of its output object.
|
||||
|
||||
A test run's output object is kept in the state's own object store `test-runs-objects`, an old `objects` section
|
||||
with no age of its own, so it lives exactly as long as its key, whatever `step-outputs`' 7 days (A-466v); a step's
|
||||
own output stays in `step-outputs` as today. A reader whose run's object is gone (a drop, a fault) answers its run
|
||||
without the packages, saying "the run's output is gone".
|
||||
|
||||
The runner hears the run's end as the build seat's `step-ended` of its `ask`, on its durable consumer, as it hears
|
||||
every step (§24). A test run has §720's one clock, a bound key `bound.<run key>` in `test-runs`, written at the
|
||||
build seat's `ask-taken` of its ask and again at each `step-progress` of it, its time to live the runner's setting
|
||||
`test-step-bound`, default 30 minutes; an ask still in the queue is timed by §86's build-capacity finding alone. Its
|
||||
expiry ends the run as §720's does: the ask dropped (§119), every reader ended `could not run`, a later
|
||||
`step-ended` of the ask ignored and said in the journal. A run whose ask is never taken ends `could not run` at the
|
||||
runner's setting `run-untaken-bound`, default 24 hours after its `started` (A-466n, A-466p, A-466s). The runner
|
||||
consumes `ask-taken` already (§647); its manifest gains `step-progress` where it does not consume it. At its start the runner takes up again each key with no `ended`, by its
|
||||
`ask` and that bound. It deletes a key once the time its setting `test-runs-kept`, default 7 days, names has passed
|
||||
since its `ended`, in the step log's order as §330 ages its `pipelines`, and deletes the run's output object from
|
||||
`test-runs-objects` with the key, after the last reader's end. At the cap no run is asked, and the step ends `could not run`, naming the fill, as
|
||||
§719 has it, with no condition of its own. A passed run's results go into `kept` per package, as today (§27), so a
|
||||
step asked after the key is deleted carries them.
|
||||
- §726 **How a test run ends and is said.** (§24, §73, §119, §419, §496; ADR 0666 §8, §21; A-466i, A-466j; principles
|
||||
3, 7 and 1)
|
||||
- **Each reading step is said.** Each step reading a test run says its own `step-started` and `step-ended`, with its
|
||||
own build-input fingerprint and `shared` (§729). Its `step-ended` carries the run's outcome and counts. Its
|
||||
`step-started` names the run's `ask`, so the watchman times it from that ask's `step-progress` (§496). The result
|
||||
was taken from the build seat's holder once, at that ask, which the step names, as §25's carry does (ADR 0666 §21).
|
||||
- **Counted once.** `pipeline-ended` counts a module's tests once per pipeline and test run, never once per step
|
||||
reading it (§24, §419).
|
||||
- **Dropped only with its last reader.** A step that is superseded or cancelled leaves `readers`, and the run's ask
|
||||
is dropped (§119) only when no reader is left.
|
||||
|
||||
### For both kinds
|
||||
|
||||
- §727 **Asking a run again moves every reader.** (§30, §73, §83 `rerun`, §29; ADR 0666 §9, §11, §24; A-466a;
|
||||
principle 3) One rule for composition runs and test runs. A `rerun` of a composition step (for each machine whose
|
||||
verdict in it was not `passed`) or of a test step joins the run of its key while that run is running, reads one that
|
||||
started after the step's last end, or otherwise starts a new run, replacing the ended key by compare-and-set and
|
||||
carrying the former run's `readers` into the new value. The new run's end moves every step that read the former run
|
||||
and did not pass: each says `step-ended` again with the new outcome, marked as a rerun with the caller of the step
|
||||
asked again (§73). A moved step reopens its pipeline, which says `pipeline-ended` again with a higher end count; the
|
||||
assigner writes wants only from a pipeline's latest end (§29). A step a person `accepted` (§30) does not move: a
|
||||
person's act stands. A machine that passed in a composition step keeps its verdict. A step left reading a failed
|
||||
result would say what is no longer true. So twenty composition steps of one revision asked again together start one
|
||||
run per machine.
|
||||
- §728 **The tools.** (§83, §391; ADR 0666 §25; A-466c; principle 4) Two for each new state, in §83's table:
|
||||
- `assigner_compositions` (class `read`) takes a candidate, a machine, or neither, and answers each composition run
|
||||
with its program, input digest, ask, readers, outcome and verdict, and the state's fill against its cap.
|
||||
- `assigner_compositions_drop` (class `act`, §391's default callers) takes `{candidate, machine, why}`. It writes the
|
||||
hand-act log first, drops the run's ask, ends each reader `could not run` naming the drop, and deletes the key.
|
||||
- `runner_test_runs` (class `read`) takes a candidate, a level, a digest, a module, or none of them, and answers each
|
||||
test run with its packages (read from its output object), ask, node, readers, outcome and counts, and the state's
|
||||
fill against its cap.
|
||||
- `runner_test_runs_drop` (class `act`, §391's default callers) takes `{key, why}` and does the same as
|
||||
`assigner_compositions_drop`, deleting the run's output object with the key.
|
||||
- §729 **`shared` in the seat contracts.** (§73, §116, §496; ADR 0666 §21, §24; A-466j; principles 1 and 8) The seat
|
||||
definitions in mesh-delivery's `mesh-delivery-contracts` change, and the contracts' code is generated from them by
|
||||
`seatgen`, never edited by hand:
|
||||
- **`mesh-wants`' `step-ended`** gains `shared`: a list of `{machine, run, ask}`, one per machine composed, `run` the
|
||||
`composition-runs` key and `ask` its run ask's id, all strings.
|
||||
- **The composer's request** (mesh-delivery-sdk's `composer.Request`) gains `blame-tries` (a number, §721).
|
||||
- **`mesh-wants`' `step-progress`** gains the same `shared` list, naming the runs the step waits on.
|
||||
- **`mesh-pipeline-runner`'s `step-started`** gains `shared`: `{run, ask}` for a test step, `run` the `test-runs` key
|
||||
and `ask` its build seat ask's id, strings.
|
||||
- **`mesh-pipeline-runner`'s `step-ended`** gains `shared`: `{run, ask, asked-by}`, `asked-by` being `{pipeline,
|
||||
artifact}` of the step that asked the run (strings), left out for that step itself.
|
||||
- **`mesh-pipeline-runner`'s `stands`** answer: each entry gains `ask` (string) and `shared` (`{run, ask}`, strings,
|
||||
where the runner knows it), as §731 says.
|
||||
|
||||
A step that names `shared` names its own build-input fingerprint beside it, as every `step-ended` does (§73). A
|
||||
composition step's `step-started` is said by the runner when it asks the assigner, before any run is chosen, so it
|
||||
cannot name the runs' asks; the assigner, the part that knows them, names them in its `step-progress`, and the
|
||||
watchman times a composition step from that (§496, A-262, A-466m).
|
||||
- §730 **What runs in flight, and going back.** (§65, §78; ADR 0666 §19, §24; ADR 0667 §9; A-466k; principle 3) A
|
||||
composition step or test step asked before the new assigner or the new runner runs ends by the path it was asked
|
||||
under, one run per step; composition runs and test runs are made only for steps asked after the new part runs. A
|
||||
return to an earlier build (§78) leaves `composition-runs` and `test-runs` unread; their readers are ended `could not
|
||||
run` by the bound of §720 and §725 once the new build runs again. Until then the earlier build applies no such bound,
|
||||
and a reader standing still is said by the watchman as `pipeline-stands`, by §732 (A-466o).
|
||||
- §731 **The runner's `stands` names what a reading step waits on.** (§75, §83; A-466t; principles 3 and 4) `stands`
|
||||
already answers every pipeline step started and not ended whose outcome is running or waiting (mesh-delivery's
|
||||
runner on main, its `Stands` read), so a composition step waiting on the assigner is in it. Each of its entries
|
||||
gains `ask`, the step's own ask (§496), and `shared` where the runner knows it (§729, a test step's run key and
|
||||
ask). At its start the watchman seeds §732's open steps from it, each clock begun at that moment, and times each by
|
||||
those asks from then on.
|
||||
- §732 **The watchman times every step that reads a run.** (§75, §496, §602; ADR 0564 §2, §4; ADR 0666 §24; A-466o;
|
||||
principles 3 and 1) §75 and §496 time each pipeline step from its `step-started` or its latest `step-progress`, but
|
||||
the watchman on main times only a build seat's running ask (its `ask-taken` and `step-progress`) and a step queued
|
||||
for a build node; a step whose run has ended, or a composition step waiting on the assigner, is timed by nothing.
|
||||
From G the watchman also:
|
||||
- **hears** the runner's `step-started` and `step-ended` of every pipeline step (it consumes them already, for the
|
||||
build capacity), and `mesh-wants`' `step-progress`, a `consumes` entry its manifest gains;
|
||||
- **keeps** each started step with no `step-ended` in memory under `<pipeline>/<step>`, its clock begun at its
|
||||
`step-started` and begun again at each `step-progress` whose `ask` is the step's own ask (§496) or an ask its
|
||||
`shared` names (§729), and at the `step-ended` of the run's ask a test step names;
|
||||
- **raises** `pipeline-stands` for that step when its clock passes the watchman's existing five-minute progress bound
|
||||
(§75), naming the pipeline, the step and the ask it last heard of, and clears it at the step's `step-ended`. A
|
||||
step said waiting on a person, or queued for a build node (§86), is owed no progress, as today;
|
||||
- **seeds** its open steps at its start from the runner's `stands`, as §75 has it.
|
||||
|
||||
So a reader that neither the assigner nor the runner ends, after a return to an earlier build or any fault, is said
|
||||
within five minutes of its last sign of life.
|
||||
- §733 **How it is checked.** Tests 108 and 109.
|
||||
- **Whole (assigner, mesh-delivery), test 108.** Two composition steps of one candidate started at once make one key,
|
||||
one request and one run ask. Three composition steps of one revision on two machines start two runs, and each step
|
||||
reads both verdicts. A machine whose verdict blames module A fails A's composition step and passes B's, with a
|
||||
warning naming A; a machine that does not compose and blames no module fails both; a verdict with no `blamed` is
|
||||
judged as today and says "the composer names no culprits". A step of another candidate starts its own run, and a
|
||||
`could not run` result starts a new one. A taken ask with no `step-ended` and no `step-progress` for 30 minutes
|
||||
ends `could not run`, with its readers and its ask dropped, and a `step-ended` of that ask heard later is ignored
|
||||
and said in the journal; a run past 30 minutes that keeps saying its progress is not ended; an ask never taken
|
||||
ends `could not run` at `run-untaken-bound`. Steps asked again together start one run per machine that did not
|
||||
pass, and move every former reader; a reopened pipeline says `pipeline-ended` again. A superseded step leaves the run running for its other readers. An assigner restarted during a run takes it
|
||||
up again by its ask. At the cap a step ends `could not run`, naming the fill. `assigner_compositions_drop` ends the
|
||||
readers and deletes the key, and a reader-only account calling it is refused.
|
||||
- **Whole (the node-engine's composer, `mesh-host`).** A fixture module whose manifest is refused on the machine is
|
||||
blamed by name, two modules owning one path are both blamed, and the search past the request's `blame-tries` names
|
||||
the untried.
|
||||
- **Whole (runner and Go build module, mesh-delivery and mesh-catalog), test 109.** A module whose program and bundle
|
||||
test one directory asks one unit step and one integration step, and both artifacts' steps end with that result and
|
||||
`shared`. A failing test fails once, and `pipeline-ended` counts the module's tests once. A rerun of one artifact's
|
||||
failed step that passes moves the other artifact's step to passed too, and the pipeline says `pipeline-ended` again;
|
||||
an `accepted` step does not move. A runner restarted during a run takes it up again by its ask. A replaced reader
|
||||
leaves the ask to the other readers. At the cap a step ends `could not run`, naming the fill. A run past 30
|
||||
minutes that keeps saying its progress is not ended, and a taken ask silent for 30 minutes ends `could not run`
|
||||
with its readers. A test run queued past five minutes with a holder present is not failed (A-466y). A second
|
||||
revision with the same digests runs a failed test again. `runner_test_runs_drop` deletes the key and its output object, and a
|
||||
reader-only account calling it is refused.
|
||||
- **Unit (runner).** A test run whose output object is gone is answered by `runner_test_runs` and its readers
|
||||
without its packages, saying "the run's output is gone"; the object outlives `step-outputs`' 7 days while its
|
||||
key lives.
|
||||
- **Whole (watchman), tests 108 and 109.** A composition step whose `mesh-wants` `step-progress` stops raises
|
||||
`pipeline-stands` within five minutes; a test step whose run's ask ended with no `step-ended` of the step raises it
|
||||
five minutes later; each clears at the step's `step-ended`; a step waiting on a person raises nothing; a watchman
|
||||
restarted while a composition step waits on the assigner seeds it from `stands` and raises it if no progress
|
||||
follows.
|
||||
- **Live.** In the first publish after G's delivery, the composition run asks of each revision number at most its
|
||||
machines, read with `assigner_compositions` and `assigner_inputs`; each module's test steps run once per level, read
|
||||
with `runner_test_runs`.
|
||||
@@ -103,7 +103,9 @@ record says so in its Why. Round 3 of the review by architectural domain (2026-1
|
||||
`*.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, the seat `mesh-conditions`' definition, §439); it refuses `*.>` and `*` in part of an emitter's name, and a `*` entry before any other event keeps its meaning on main (§474). The grants part,
|
||||
from the catalog graph as it derives every grant (§59, §442), 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
|
||||
for each process of the consumer that hears it, named as A-397 names a process's durable (`<machine>_<module>` for
|
||||
its program, `<machine>_<module>_tools` for its tool runner, `<machine>_<module>_<process>` for another; corrected in
|
||||
place by design 47 H §763, where one per module stood), 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
|
||||
|
||||
@@ -3,7 +3,7 @@ layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: G
|
||||
updated: 2026-11-12
|
||||
updated: 2026-11-17
|
||||
decisions:
|
||||
- "ADR 0500"
|
||||
- "ADR 0673"
|
||||
@@ -88,7 +88,7 @@ file on 2026-11-10, and is cited as "design 47 G §n". A sentence that holds a d
|
||||
stayed in the main file, and G builds what it says from G's delivery. A section named in italics is in this part, or,
|
||||
when it is not here, in the main file.
|
||||
|
||||
The part is twenty-two files, each read whole, its design lines numbered across them:
|
||||
The part is twenty-four 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.
|
||||
@@ -112,5 +112,7 @@ The part is twenty-two files, each read whole, its design lines numbered across
|
||||
- [G-20-lead-answers](G-20-lead-answers.md): the lead's one-line answers to develop's questions, each tested against the principles (A-1 on).
|
||||
- [G-21-provider-and-revert-ask](G-21-provider-and-revert-ask.md): the provider a requirement points to, the named seat and the contribution edge (§708, §709, completing §357), and the assigner's ask of a held revert (§710, completing §300), the edge an acting rule gives (§711, completing §47's kind 5), the validation before take-in (§712, §713, completing §16), the take-in and groups of every watched branch (§714, §715), where the gate keeps a group's members (§716) and the seats of the status view's and the assigner's views, followed before their holder is known (§717).
|
||||
- [G-22-lead-answers-2](G-22-lead-answers-2.md): the lead's answers continued, from A-182.
|
||||
- [G-23-after-delivery](G-23-after-delivery.md): what is owed once G is delivered.
|
||||
- [G-24-composition-runs-and-test-runs](G-24-composition-runs-and-test-runs.md): one composition run per candidate and machine, one test run per level and tested packages, from G's live delivery of 2026-11-17 (§718 to §733).
|
||||
|
||||
Design 34's milestone [every-event](../34-milestones/every-event.md) and design 46's milestone [7-approval-mark](../46-milestones/7-approval-mark.md) ship in milestone G's release, built in its repositories beside G's lines (lead-47, 2026-11-11 15:30 CET); where one of their lines and a line of G differ, G's later line holds and the other is corrected in place (§624 to §626).
|
||||
|
||||
@@ -0,0 +1,297 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H
|
||||
updated: 2026-11-20
|
||||
decisions:
|
||||
- "ADR 0682"
|
||||
- "ADR 0681"
|
||||
- "ADR 0667"
|
||||
- "ADR 0666"
|
||||
- "ADR 0656"
|
||||
- "ADR 0633"
|
||||
- "ADR 0596"
|
||||
- "ADR 0573"
|
||||
---
|
||||
# 47, milestone H: the merge call, the watchdog, the take-in and one pipeline at a time
|
||||
|
||||
One file of milestone H's part of [design 47](../47-delivery-from-commit-to-delivered.md); the plan that opens the part
|
||||
is [H-deliver-the-delivery-system](H-deliver-the-delivery-system.md). Its design lines continue the numbering of
|
||||
milestone G's part after §733 and are cited as "design 47 H §n". Each line says which release of the plan's section 6
|
||||
builds it (H1 to H5), how it is checked, and which line of G or lead's answer it replaces; where the code it lands in
|
||||
is named, it is named by module and function, from the gap tables of 2026-11-20, for the builder to find it.
|
||||
|
||||
*The operator, 2026-11-19 about 23:30 CET: "Nobody should 'take in a merge', only commits to the configured branch of
|
||||
registered modules." 2026-11-20 about 01:10 CET: "parallel pipelines sounds like a very bad idea". 01:15 to 01:20 CET:
|
||||
a delivery is started by hand by the merge it already needs, the lead named principle 3 (a start a person forgets is
|
||||
a silent non-delivery), and the operator chose "A": the merge through the mesh is the start and the group, and the
|
||||
forge's event is the watchdog. ADR 0682 records it (cited by the clause numbers of its version 8, fourteen clauses). The chain these lines build, in one sentence: a **merge call**
|
||||
(the seat `git`'s `merge-pull` naming one or more pull requests) merges the heads, the gate names them one source
|
||||
revision per watched branch and opens its delivery record, the indexer takes that revision in and names the movers,
|
||||
the runner runs one pipeline for it when no other runs, and the assigner wants the newest passed release; the forge
|
||||
bridge's one message per head move is heard only by the gate's watchdog, which raises an **untaken head** for a head
|
||||
no merge call delivered.*
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
S[session or operator] -->|git.merge-pull pulls| F[forge module, seat git]
|
||||
F -->|merge-called| G[gate, seat mesh-delivery]
|
||||
G -->|source-moved| I[indexer, seat mesh-catalog]
|
||||
I -->|take-in.taken: movers| R[runner, seat mesh-pipeline-runner]
|
||||
R -->|pipeline-ended| A[assigner, seat mesh-wants]
|
||||
F -->|branch-moved| B[forge bridge]
|
||||
B -->|head-moved| G
|
||||
G -.->|head-untaken| K[condition keeper]
|
||||
```
|
||||
|
||||
### The merge call
|
||||
|
||||
- §734 **One merge call is a delivery's start and its group.** (ADR 0682 §1, §2; ADR 0666 §11; the operator, 2026-11-20
|
||||
01:20 CET; principle 3) The seat `git`'s verb `merge-pull` takes `pulls`, a list of one or more members
|
||||
`{repository, number, head}` (the head the caller names, as ADR 0666 §11 has it), and `by`, the caller as who@node;
|
||||
the forge module records `by` beside the bus account the tool runner proves for the call. The members named in one
|
||||
call are one delivery and, with two or more, its group; nothing else makes a group. The verb's single-pull form goes:
|
||||
a call naming one pull request is a list of one, and its callers change with it in H1 (the tool runner's
|
||||
`merge-pull` tool and its description, the claude-code module's instructions and playbook 07's merge step, which name
|
||||
one pull request). The verb answers `call` (§766) at once and the members' outcome when the call ends. Built in H1 in
|
||||
the forge module's `merge-pull` handler and the seat `git`'s contract in mesh-delivery-contracts. How it is checked:
|
||||
whole (forge module): a call naming two pull requests in two repositories merges both and says one `merge-called`
|
||||
(§736). Replaces G §38's one-pull form.
|
||||
- §735 **Every member is judged before any is merged.** (ADR 0682 §1, §13; ADR 0666 §11; principle 3) The verb judges
|
||||
each member as ADR 0666 §11 does, but for the branch protection (still the pull request's head; no run at the head's
|
||||
build-input fingerprint failed a `required` step), all of them first. It judges no branch protection: a watched
|
||||
branch need not be protected (ADR 0682 §13), and a head moved outside the mesh, a push included, is the watchdog's
|
||||
untaken head (§740). When one member is
|
||||
refused, none is merged, and the answer names every refused member and why. Then it merges the members in the order
|
||||
the call names them. The forge module's `failed-steps` that this judges is written from the runner's `step-ended`,
|
||||
whose body names the mover, its commit and its build-input fingerprint (H-A-18). Why judging first: a group merged in
|
||||
part lands half a delivery. Built in H1 (forge module). How it is checked: whole (forge module): a call whose second
|
||||
member's head moved merges neither and names it; a head at whose fingerprint a `required` step failed is refused,
|
||||
naming the step (acceptance test 114).
|
||||
- §766 **The call is written before its first merge and said again at the forge module's start.** (H-A-18; principles
|
||||
3 and 4) Before it merges anything, the forge module writes the call's key `call.<call>` in its own template state
|
||||
`calls` (value: `by`, the bus account, `at`, the members, each with `state` `judged`, `merged` with its commit, or
|
||||
`refused` with why), and updates each member as it merges. At its start it reads every call whose event it has not
|
||||
said (`said` false) and says `merge-called` for what landed, so a stop between the last merge and the event loses
|
||||
nothing it recorded. A call is kept `call-retention` (a setting, default 30 days), then deleted by the forge module.
|
||||
Its tools: `forge_calls` (the calls, newest first, with each member's state) and `forge_call_say_again` (with `call`
|
||||
and `why`, says its `merge-called` again, written in the hand-act log). A stop between a merge and the write of that
|
||||
member's `merged` leaves a head the call never names: it is an untaken head (§740), recovered with `gate_head_take`
|
||||
(§742). Built in H1 (forge module). How it is checked: whole (forge module): a restart after the second of three
|
||||
merges says one `merge-called` naming the two that landed; acceptance test 111's stop case.
|
||||
- §767 **A member refused after every member was judged is said and raised.** (H-A-1; principle 3) When the forge
|
||||
refuses a member after all were judged (a conflict that appears between the judging and its merge, the forge down
|
||||
mid-call), the forge module stops merging, says `merge-called` with the members that landed and `refused`, one
|
||||
`{repository, number, why}` per member not merged, and raises the finding `merge-partial`, scope `delivery`, id the
|
||||
call, naming each refused member. The landed members are delivered as any call's. It clears the finding when a later
|
||||
call lands every refused member (read from its own `calls`), or by its tool `forge_partial_clear` with `call` and
|
||||
`why`, written in the hand-act log. A call that landed no member says no `merge-called`. Built in H1 (forge module).
|
||||
How it is checked: whole (forge module): a fixture forge that refuses the second merge gives one `merge-called` with
|
||||
the first member and `refused`, and `merge-partial` raised and cleared by a later call (acceptance test 115).
|
||||
- §736 **The merge call says one event.** (ADR 0682 §1; principles 1 and 11) Once its members are merged or refused,
|
||||
the forge module says the seat `git`'s event `merge-called` on `mesh.seat.git.event.merge-called.<call>`, kept on
|
||||
the stream `SEAT_git_merge-called` for `merge-called-retention` (a setting, default 30 days) and up to
|
||||
`merge-called-cap` (a setting, default 64 MiB), its body in the seat's `bodies`: `call` (16 lowercase hex, made once
|
||||
per call), `by`, `account`, `at` (the time of the last merge), `members`, one `{repository, number, branch, head,
|
||||
commit}` per landed member, where `branch` is the pull request's base (a watched branch) and `commit` the merge
|
||||
commit the forge records for that pull request, and `refused` (§767). Only the forge module says it. Its one consumer
|
||||
is the gate (§737), on a durable consumer of its program. Why 30 days: the gate takes in a call heard after a long
|
||||
stop, as the forge module's `seen` keys are kept (G §585). Built in H1 (forge module, the seat `git`'s definition and
|
||||
contract). How it is checked: unit (the seat definition: the event and its body); whole (forge module) as §734.
|
||||
- §737 **The gate names the merged heads one source revision per call and opens the record.** (ADR 0682 §1, §2; H-A-13,
|
||||
H-A-19; principles 1, 3 and 12) The gate consumes `merge-called`. For each watched branch its members name, it writes
|
||||
`source.<branch>` once, by compare-and-set keyed by the call (the revision carries `call`, and a revision of that
|
||||
branch already carrying that call writes nothing): the branch's previous heads with each member's repository at its
|
||||
`commit`, where two members of one repository on one branch name the last member's commit in call order, numbered one
|
||||
above the branch's newest. It opens one delivery record per such revision, keyed `<branch>.<source>` (A-33 stands),
|
||||
its members the call's members on that branch, `call`, `by` and `account` in its trace; says `record-opened` on
|
||||
`mesh.seat.mesh-delivery.event.record-opened.<call>` with `branch` and `source`, so the session that called can wait
|
||||
on its own call; and says `source-moved` on `mesh.seat.mesh-delivery.event.source-moved.<branch>.<source>` with
|
||||
`branch`, `source`, `call`, `start` (false; true only for a branch's first revision, §768) and `heads` (the
|
||||
repositories it moved, each `{repository, commit}`). A call whose members name two branches is two source revisions
|
||||
and two records, each naming the call. The gate numbers every source revision; no other part keeps a number of its
|
||||
own. `source-moved` is kept for `source-moved-retention` (a setting, default 30 days). Built in H1 in the gate: its
|
||||
`moveSource` moves from the `take-in.taken` handler to a `merge-called` handler; `ForgeMerged`, `moveHead` and
|
||||
`gate_source_follow` go (§764). How it is checked: whole (gate): a `merge-called` with two members on one branch gives
|
||||
one revision, one record and one `source-moved`; heard twice it gives one; two members of one repository give its
|
||||
last member's commit. Replaces A-34, G §291, A-431's numbering by the indexer, and A-464 to A-464e.
|
||||
- §738 **A delivery record follows its pipeline to the machines.** (ADR 0666 §9; G §141 to §147) The record opened by
|
||||
§737 is the record of G §141 to §147, one per source revision: it consumes the runner's `pipeline-started` and
|
||||
`pipeline-ended` (§746) of its source revision, and of the pipelines `package-published` starts from it (§747), the
|
||||
parts' `wait-held` and `wait-ended`, the assigner's `wanted` and the node-engine seat's `running`, on the gate's own
|
||||
durable consumer; writes its trace (the assignment graph revisions it moved between, from `wanted`); and ends as G §147
|
||||
says, or `failed` when the assigner says a tier late (§751). A take-in with no movers ends its record at once as
|
||||
`nothing to deliver`. Built in H3 in the gate's consumer (`stepFamilies`) and record (`SetTrace`, `EndIfRun`). How it
|
||||
is checked: whole (gate): a record of a one-module delivery ends when the module runs on every present placing
|
||||
machine.
|
||||
|
||||
### The forge bridge's one message, and the watchdog
|
||||
|
||||
- §739 **The forge bridge says one message per move of a watched branch's head.** (ADR 0682 §3; G §11, A-236) On every
|
||||
`git.branch-moved` of a watched branch, and at its start for every watched branch's head, the bridge reads the head
|
||||
through `git.branch` (never the event's body) and writes one message `head-moved` on its stream `forge`, subject
|
||||
`forge.<repository>.<branch>.head-moved`, kept `head-moved-retention` (a setting, default 7 days): `repository`,
|
||||
`branch`, `head`, `before` (the head it held for that branch in its state `heads`, empty the first time) and `start`
|
||||
(true when said at its start). It writes it whether the head moved by a merge call, a merge in the forge's screen or
|
||||
an admitted push: it reads no pull request and no tree. A head equal to the one it holds writes nothing. It
|
||||
reads no branch protection: an unprotected watched branch moves like any other, and `branch-unprotected` (G §17)
|
||||
ends (ADR 0682 §13). Its one consumer is the gate (§740). Built in H1 in the bridge; the messages `merged` and `pushed`, their `base`, their trees in its state
|
||||
`inputs`, and its call of `git.pull` for a merged commit go (§764). How it is checked: whole (bridge): a merge, an
|
||||
admitted push and a restart each give one `head-moved`; a head heard twice gives one. Replaces G §509 and §714's
|
||||
message form.
|
||||
- §740 **A head no merge call delivered is an untaken head.** (ADR 0682 §3; principles 1, 3 and 11) The gate consumes
|
||||
`head-moved` and keeps, in its template state `heads` (one key `<repository>.<branch>`, value `{head, since}`, deleted
|
||||
by the gate when `source.<branch>` names that head), each head that `source.<branch>` does not name for that
|
||||
repository. When `untaken-bound` (a setting of the gate, default 10 minutes, at least 1) passes and `source.<branch>`
|
||||
still does not name that head, the gate raises the finding `head-untaken`, scope `delivery`, id
|
||||
`<repository>.<branch>`, naming the repository, the branch, the head, since when, and "moved outside the mesh:
|
||||
delivered by nothing". It clears it when `source.<branch>` names that repository at the newest head `head-moved`
|
||||
said (a later merge call or §742's hand take). The gate keeps one deadline timer, set to the earliest `since` plus the
|
||||
bound, and no other clock. Built in H1 in the gate. How it is checked: whole (gate, bridge): a head moved by a merge
|
||||
call raises nothing; a head pushed outside the mesh raises `head-untaken` within the bound, starts no pipeline, and
|
||||
clears when a later merge call takes its repository in (acceptance test 111). Replaces A-463's `merge-untaken` and
|
||||
the head half of G §12. An acknowledge tool that silences a known `head-untaken` without delivering it was proposed
|
||||
by the review and is not built: no record or answer asks for it (noted for H4's tools table).
|
||||
- §741 **`pipeline-stands` times a pipeline's steps, not a head.** (ADR 0682 §7; ADR 0666 §24; principle 7) The
|
||||
watchman's finding `pipeline-stands` (G §12, §75) is raised for a pipeline step standing still five minutes; a watched
|
||||
branch's head that starts no pipeline is the gate's `head-untaken` (§740) alone, so the watchman learns no head. A
|
||||
pipeline waiting its turn (§748) is progress not owed and raises neither. Built in H1 in the watchman's `takein` and
|
||||
`signals` parts. How it is checked: whole (watchman): a pipeline waiting behind another raises nothing.
|
||||
- §742 **Taking an untaken head in by hand.** (ADR 0682 §3; principle 4) The gate's tool `gate_heads` reads the state
|
||||
`heads` with each head's since and finding; `gate_head_take`, with `repository`, `branch` and `why`, names that head
|
||||
a source revision as §737 does, its `call` `hand.<by>.<time>`, written in the hand-act log, and the chain follows.
|
||||
Nothing else delivers an untaken head. Built in H1 (gate tools). How it is checked: unit (gate tools); whole (gate):
|
||||
a hand take writes one revision and clears the finding.
|
||||
- §768 **The clean state seeds every watched branch's first source revision.** (H-A-15; ADR 0682 §12; principles 2 and
|
||||
3) Before the runner starts at milestone H1's clean state (the plan's section 5), the gate's tool `gate_source_seed`
|
||||
(with `why`, written in the hand-act log) writes, for every watched branch the registrations name, one source
|
||||
revision at each repository's current head read through `git.branch`, with `start` true and `call`
|
||||
`seed.<by>.<time>`, and says `source-moved`; the indexer takes each in with no mover (§743), so the newest catalog
|
||||
revision of every branch names those heads, and the forge bridge's `head-moved` at its start then matches
|
||||
`source.<branch>` and no `head-untaken` is raised mesh-wide. The tool answers the branches and repositories it wrote,
|
||||
counted. A branch newly watched later starts the same way, by A-401's start pass, which stays and writes through this
|
||||
path. Built in H1 (gate tools; indexer). How it is checked: whole (gate, indexer, bridge): after the seed a bridge
|
||||
restart raises no `head-untaken`; live, the counts read at plan step 5.
|
||||
- §769 **`predefined` is read from the take-in of the catalog's commit.** (ADR 0681 §2; ADR 0682 §1) The indexer's state
|
||||
`predefined`, which ADR 0681 §2 has it read from the forge bridge's merged message of the catalog repository, is read
|
||||
at the take-in of a source revision that moves the catalog repository, from that commit's trees (§743), the merged
|
||||
message being gone (§739). Built in H1 (indexer). How it is checked: whole (indexer): a merge call landing a catalog
|
||||
commit that changes a predefined key rewrites `predefined`. ADR 0681 §2's words "the forge bridge's merged message"
|
||||
are owed an insight in that record.
|
||||
|
||||
### The take-in
|
||||
|
||||
- §743 **The indexer takes in what the gate names.** (ADR 0682 §4; A-476, A-476a; principles 7 and 10) The indexer
|
||||
consumes the gate's `source-moved` on one durable consumer per watched branch, named `<node>_<indexer>_<branch>` (the
|
||||
branch's name escaped as a key's name is), each delivering one message at a time, acknowledged once its catalog
|
||||
revision and `take-in.taken` are written. For each repository the event moves it reads the trees at the named commit
|
||||
through `git.trees` (one of its kept calls, A-190), computes the build-input fingerprints of the modules registered for
|
||||
that repository (a registration's git origin), and takes as movers those whose fingerprint differs from their entry
|
||||
in the branch's newest catalog revision, and every module, in any repository, that imports a package of one of them
|
||||
(A-476a; ADR 0573 §3). It writes one catalog revision of that branch, keyed `<branch>.<source>` by compare-and-set,
|
||||
pins it for the pipeline of §746 in the same write (A-449a, key `pipeline.<branch>.<source>`) when it has a mover,
|
||||
and says `take-in.taken` once, with `branch`, `source`, `revision`, `call` and `entries`, one `{module, commit,
|
||||
fingerprint, repository}` per mover (§763 corrects G §476 and §648: no `pull`). It validates no manifest and holds
|
||||
nothing for the indexer a revision names; it takes in with the build it runs (A-476 (a), (b)). A `source-moved` with
|
||||
no mover, a branch's first revision (`start` true, §768) included, says `take-in.taken` with no entries and pins
|
||||
nothing (H-A-19); its entries are the base the branch's later take-ins are held against. Built in H1: the indexer's
|
||||
take-in part written again (today `Arrive`, `evaluate`, `takeInWhole`, `takenWhat`, `nextSource` and
|
||||
`ApplyBranchSource`, fed by the bridge's messages); its storage, entries, pins' state, versions and verbs
|
||||
(`KeepView`, `keepBranchEntries`) stay. How it is checked: whole (indexer): a `source-moved` naming a mesh-sdk commit
|
||||
names mesh-sdk and its importers; one changing only a document names no mover and pins nothing; a restart between
|
||||
the revision's write and the acknowledgement writes no second revision. Replaces G §16, §19, §509, §712 to §715 and
|
||||
the main file's *Taken in by the indexer it names* (§764).
|
||||
- §744 **A take-in that cannot be written is held, said and skippable.** (ADR 0682 §4; H-A-12; principles 1, 3 and 4) A take-in that
|
||||
cannot be written (the catalog store `full`, G §181) is held: its `source-moved` stays unacknowledged and is not
|
||||
redelivered on the acknowledgement timer (the consumer's wait for an acknowledgement is longer than any hold, and it
|
||||
is redelivered with no delay only when the indexer asks); the indexer takes it again when the bus module's `room` for
|
||||
that store wakes it, with no timer. A `git.trees` call unanswered is its kept call's own (A-190) and holds the same
|
||||
way. While held the indexer says `take-in.pending` once per source, with `branch`, `source` and `why`, and the
|
||||
watchman raises `take-in-waits` when no `take-in.taken` for that source follows within `take-in-bound` (a setting,
|
||||
default 60 minutes; G §497). Take-ins of one branch go in source order; another branch's go on. `indexer_pending`
|
||||
reads each branch's held `source-moved` and why; `indexer_take_in_pending` takes it again now; `indexer_take_in_skip`,
|
||||
with `branch`, `source` and `why`, acknowledges it unwritten, says `take-in.taken` with no entries and `skipped`, and
|
||||
writes the hand-act log. The state `pending`, its keys `m.<sequence>` and `g.<group>`, and `indexer_drop_pending` go
|
||||
(§764). Built in H1 (indexer). How it is checked: whole (indexer): with the store full a `source-moved` is held, said
|
||||
once, taken in on `room`; a second branch's take-in goes on meanwhile; a skip ends it in the hand-act log (acceptance
|
||||
test 116). ADR 0682 §4 keeps `take-in.pending`, `take-in-waits`, `indexer_pending` and `indexer_take_in_pending` and
|
||||
ends `indexer_drop_pending`.
|
||||
- §745 **Manifest validation is the pipeline step `validate`.** (ADR 0682 §5; H-A-6; A-476 (a); ADR 0666 §17) The step
|
||||
`validate` is served by the assigner as an accepted kind `step` of the seat `mesh-wants`, the seat that serves the
|
||||
composition step (G §22), asked by the runner for each mover as the step before its composition step: the assigner
|
||||
runs the manifest validator built from the take-in's own heads, in the sandbox, as it runs the composer (G §718), over
|
||||
the revision's manifests, refusing only a problem in a manifest the revision alters or one between manifests an
|
||||
altered one takes part in (ADR 0578 §2). It ends `failed` with the reason `manifest-refused` naming each problem, or
|
||||
`cycle` naming the cycle the revision makes (the cycle refusal A-326 and G §569 made at the take-in), and `passed`
|
||||
otherwise. Its status is `required` in every policy by default: the seed (A-441) writes it, and §22's list of steps
|
||||
gains it. The indexer's events `manifest-refused` and `manifest-accepted` (G §500, §668) go; their readers read the
|
||||
step's end (§764). Built in H1 (assigner: the step; runner: the order; indexer: the seed's default). How it is
|
||||
checked: whole (assigner, runner): a take-in whose manifest names an unknown field fails `validate` naming it and asks
|
||||
no composition; a take-in making a cycle fails it naming the cycle (acceptance test 117).
|
||||
|
||||
### One take-in, one pipeline, none in parallel
|
||||
|
||||
- §746 **One take-in is one pipeline.** (ADR 0682 §6; the operator, 2026-11-20 01:10 CET; ADR 0666 §1, §7, §9 read per
|
||||
source revision) On a `take-in.taken` with entries the runner starts exactly one pipeline, keyed `<branch>.<source>`
|
||||
by compare-and-set on its absence, whose movers are the event's entries. It asks each mover's pipeline steps in the
|
||||
catalog graph's build order (a mover's build waits for the `package-published` of each mover it has a "published
|
||||
before it builds" edge to, toolchain edges first), and computes the movers' delivery order in ADR 0666 §14's order as
|
||||
tiers (acting parts first, providers before their consumers; movers no edge orders share a tier). The pipeline passes
|
||||
when every mover's `required` steps passed, a `required` step ending `nothing to run` counting as passed (ADR 0682 §8; H-A-3), and
|
||||
fails when one did not. Its events (G §73) move to `mesh.seat.mesh-pipeline-runner.event.<event>.<branch>.<source>`
|
||||
for `pipeline-started` and `pipeline-ended`: `pipeline-started` names `pipeline`, `branch`, `source`, `call`,
|
||||
`revision` and the movers; `pipeline-ended` is said once with `pipeline`, `branch`, `source`, `call`, `revision`, the
|
||||
outcome and, per mover, `module`, `fingerprint`, the released `version` (absent when none was released), its step
|
||||
results and its `tier`. The step events keep their subject per module (`...<event>.<module>.<branch>.<commit>`) and
|
||||
gain `pipeline`. Who hears them now: the assigner (wants, §750, §751), the gate (the record, §738), the indexer (pins,
|
||||
§749), the status view, and a session, which waits on `record-opened.<call>` (§737) and then on
|
||||
`pipeline-ended.<branch>.<source>`, never per module (G §74's wait per module and G-4's subject row are corrected so,
|
||||
§763). The runner says no `group-ended`. Built in H1 in the runner (the key `<branch>.<source>.<module>` becomes
|
||||
`<branch>.<source>`, its step keys gain the mover) and in the seat's definition. How it is checked: whole (runner):
|
||||
a take-in naming mesh-sdk and one importer is one pipeline whose importer builds after mesh-sdk's
|
||||
`package-published`, and one `pipeline-ended` naming both with their tiers (acceptance test 112).
|
||||
- §770 **`pipeline-failed` is one finding per failing mover.** (H-A-19; ADR 0666 §24; ADR 0505 §5, §6) The runner's
|
||||
finding `pipeline-failed` (G §33, §113) has id `<module>.<branch>`, one per mover whose `required` step failed or
|
||||
could not run, naming the pipeline and the step, the commit's author's for two hours then the operator's; it is
|
||||
cleared by that module's next passed pipeline on that branch. Built in H1 (runner). How it is checked: whole (runner):
|
||||
a pipeline with two failing movers raises two findings; a later pipeline passing one clears that one.
|
||||
- §747 **A start names an event, never a sweep or a comparison.** (ADR 0682 §6; H-A-19; G §12, §112; principle 1) The
|
||||
runner starts a pipeline on `take-in.taken` with entries, and on `package-published`, whose body gains `branch` and
|
||||
`source`, the source revision whose pipeline published: when that pipeline runs and moves the dependent, the
|
||||
dependent waits in it (§746) and nothing starts; otherwise (a publish again of an older build, G §588, or a kind-1
|
||||
dependent that pipeline does not move) one pipeline keyed `<branch>.<source>.published.<package>.<version>` starts,
|
||||
its movers the package's kind-1 dependents it does not move. That pipeline pins the publishing source's catalog
|
||||
revision and belongs to that source's delivery record (§738). A hand `start`, `run`, the runner's other verbs (ADR
|
||||
0666 §10, §18, §25) and its taking up of pipelines in flight after a restart (§19) stay, as do the set-aside keys of
|
||||
A-446. The sweep (`StartUnstarted`, `Unstarted`; `StartHeld` of the held pull request mesh-delivery #262), the
|
||||
start-time `outdated` of G §375 and `runner_catch_up` go: the runner's durable consumer of `package-published`
|
||||
delivers a publish heard after a stop. Built in H1 (runner: `Starter`, `run`'s `resume`). How it is checked: whole
|
||||
(runner): a restart with modules whose fingerprint has no pipeline starts none; a publish heard after a stop starts
|
||||
its dependents once.
|
||||
- §748 **At most `pipelines-at-once` pipelines run; the others wait in order.** (ADR 0682 §7; H-A-14; the operator,
|
||||
2026-11-20 01:10 CET; principles 3 and 11) The runner's setting `pipelines-at-once` (default 1, from 1 to 8) bounds
|
||||
the pipelines whose steps are asked at once. A pipeline written over the bound gets `seq`, the next value of the
|
||||
runner's own counter in its state (one key `queue.next`, written by compare-and-set), and state `waiting`, with no
|
||||
step asked; it says `wait-held` with `step` `pipeline` and `on` `pipelines-at-once`. The runner places the lowest `seq`
|
||||
waiting at its start, from its own state, and on every end of a running one: `pipeline-ended`, a cancel and a
|
||||
set-aside alike, with no timer, and says `wait-ended`. A pipeline waiting on the operator's `approval` step does not
|
||||
count against the bound, and when its approval is answered it is placed first, ahead of every `seq`. When pipelines
|
||||
wait and none runs after a placing, the runner raises its finding `pipelines-stalled`, naming the first waiting, and
|
||||
clears it when one runs. At most `pipelines-waiting-cap` pipelines wait (a setting, default 64): a start over it
|
||||
leaves its `take-in.taken` unacknowledged, raises `queue-full`, and is taken on the next end. Superseding (ADR 0682 §7): a waiting
|
||||
pipeline's mover that a newer waiting pipeline of the same branch also moves leaves the older one, which ends
|
||||
`superseded` when no mover is left; a running pipeline runs to its end (G §31's supersession of running steps no
|
||||
longer applies across pipelines). A waiting pipeline is progress not owed (§741). The runner's tool `runner_waiting`
|
||||
lists the waiting pipelines in their order; `runner_place`, with a pipeline's key and `why`, places one ahead of its
|
||||
turn, written in the hand-act log. Built in H1 (runner). How it is checked: whole (runner): two take-ins in a row run
|
||||
one after the other, the second said waiting; a cancel places the next; an approval answered places first; a newer
|
||||
take-in moving the same module supersedes it in the waiting one (acceptance test 112).
|
||||
- §749 **A pipeline's pins are the indexer's, freed on its end.** (ADR 0666 §9; A-449a; principle 12) The indexer pins
|
||||
a take-in's revision in the take-in's write (§743), and a pipeline §747 starts on its `pipeline-started`, which
|
||||
carries `revision`; it frees the pin on that pipeline's `pipeline-ended`, both heard on durable consumers of its own.
|
||||
At its start it judges each kept revision against the pins its own state holds, never against a count of pins
|
||||
stated. The runner says no `pinned` or `freed`; §153's rule that only the gate's account says them stands. Built in
|
||||
H1 (indexer: `JudgePins`; runner). How it is checked: whole (indexer): a restart while a pipeline runs on revision
|
||||
510 keeps 510. Corrects A-449 (§763).
|
||||
|
||||
@@ -0,0 +1,197 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H
|
||||
updated: 2026-11-20
|
||||
decisions:
|
||||
- "ADR 0682"
|
||||
- "ADR 0666"
|
||||
- "ADR 0656"
|
||||
- "ADR 0596"
|
||||
- "ADR 0595"
|
||||
- "ADR 0573"
|
||||
- "ADR 0548"
|
||||
- "ADR 0525"
|
||||
---
|
||||
# 47, milestone H: the want rule, the builder's lines, the reads of other parts and the missing read tools
|
||||
|
||||
One file of milestone H's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
|
||||
[H-deliver-the-delivery-system](H-deliver-the-delivery-system.md), and its lines are numbered after
|
||||
[H-1](H-1-the-merge-call-and-the-take-in.md)'s and cited as "design 47 H §n". These are items 8 and 11 to 13 of the
|
||||
plan's section 4, and A-434 as a line. The wake-up rule (item 9) is one rule for every delivery part and is in the
|
||||
main file, *Every delivery part wakes on its inputs alone*; §762 here says which part moves onto it where.
|
||||
|
||||
|
||||
### The want rule
|
||||
|
||||
- §750 **A want names the newest released version whose pipeline passed.** (ADR 0682 §8, §9; A-478; the operator,
|
||||
2026-11-17 about 21:45 CET; principles 2 and 7) For every machine whose assignment places module M on watched branch
|
||||
B (the placement's branch, the registration's first by default), the assigner writes `want.<node>.<M>` naming
|
||||
`version`, the highest version of M released on B (`version-released`) whose pipeline's `pipeline-ended` passed, with
|
||||
`pipeline` (the pipeline's key) and `rank` (the mover's tier in it, §746); it writes it as §751 orders, by
|
||||
compare-and-set on a newer version, so an older end heard later writes nothing (G §352's state `written` keeps, per
|
||||
module and branch, the newest passed version). A want names a version, never a part's digest (A-430): A-436's
|
||||
stand-in ends, and G §379's digests go. The one exception is a return to an earlier build: the placement's value
|
||||
`build` (G §361), set through the seat `mesh-module-assigner`'s `propose` like any placement change and read through that seat's verb
|
||||
`placement` (A-62), whose answer shows the `build` value beside the branch, is read before
|
||||
the rule and names the want's version (H-A-5; ADR 0682 §8). The want is held for nothing else. These holds end, with
|
||||
their states, findings and tools: the canary and the "at most `step` ahead" rule, every provider healthy, the grant
|
||||
exists (ADR 0429 §6), the served verb, the bus state (rule 8), the acting part's new version first (ADR 0656 §4; G
|
||||
§266, §268, §269, §274, §276: `acting-part-late`, `assigner_waits`'s acting rows, `assigner_release`), the
|
||||
dependency's `version-delivered` (G §376, A-189, A-246, A-250: `delivery-waits`, `assigner_delivered_again`, the event
|
||||
`version-delivered`), and the parts check (G §524, the `want-parts` capability). The backup before the apply and the
|
||||
operator's yes on a failed backup and on a held revert are the node-engine's and the asker's (A-478 (c); G §296,
|
||||
§710); a failing new version holds on its own machine while the old runs, by its node-engine's apply (ADR 0682 §9).
|
||||
Built in H1: the assigner's want rule (`wants.go` and the want half of its pass) written again; the old holds
|
||||
deleted. How it is checked: whole (assigner, in mesh-delivery): a module released with a passed pipeline is wanted on
|
||||
every placing machine, whatever build an acting part runs; a version whose pipeline failed is not wanted; an older
|
||||
end heard after a newer one writes nothing; a placement `build` names the want's version (acceptance test 113).
|
||||
Replaces G §29's per-revision want, §291 and §292 in their want half, and design 47's six rules in *Where it goes*.
|
||||
- §751 **One pipeline's wants are written tier by tier.** (ADR 0682 §8, §9; H-A-10; ADR 0666 §14; principles 3 and 7) On a
|
||||
passed `pipeline-ended` the assigner writes the wants of its tier-1 movers on every placing machine; once each of them
|
||||
reports `running` at that version on every present placing machine (the node-engine seat's `running`), it writes the
|
||||
next tier's, and so on. Each tier has `tier-bound` (a setting of the assigner, default 30 minutes): a tier whose
|
||||
movers do not all run within it ends the delivery loudly: the assigner writes no later tier, raises its finding
|
||||
`tier-late`, scope `delivery`, id the pipeline, naming the movers and machines not running, and says `wanted` with
|
||||
`outcome` `tier-late`, on which the gate ends the record `failed` (§738). A machine away is not waited for; it
|
||||
applies its wants when back. The validate and composition steps composed the candidate against the whole graph
|
||||
before any want (ADR 0682 §9). The wants of one tier are written at once. Built in H1 (assigner). How it is checked:
|
||||
whole (assigner, in mesh-delivery): a pipeline of a provider and its consumer writes the consumer's want only after the
|
||||
provider's `running`; a provider that never runs raises `tier-late` within the bound and writes no consumer want.
|
||||
- §771 **The order on one machine is the node-engine's apply order, by rank.** (H-A-9; ADR 0682 §9; A-478b; principles
|
||||
9 and 12) The node-engine, which applies its wants one module at a time (R6), takes its changed wants in this order:
|
||||
the holder of the seat `node-backup` and the bus module first; then each pipeline's wants by `rank`; then the rest by
|
||||
name; its own want last; at a revert, the reverted module first. It reads the order from the wants alone and consumes
|
||||
no event of the runner. The assigner's order waits (`order.<node>.<module>.<part>` in its state `waits`, step
|
||||
`placing`, G §298, A-245, A-258 to A-260) go. The node-engine's tool `engine_apply_order` answers the order it will
|
||||
apply its changed wants in, with why; the assigner's `assigner_delivery_order` of the first version of this part is
|
||||
not built. Built in H1 (node-engine apply pass; assigner). How it is checked: whole (node-engine, in `mesh-host`):
|
||||
wants of the bus module, the backup holder and two movers of ranks 2 and 1 changed at once apply in that order.
|
||||
- §772 **A machine away at the clean state is placed by hand when it is back.** (H-A-15; principle 2) A machine away at
|
||||
milestone H1's clean state runs a node-engine that cannot read a want without digests, so the assigner keeps its wants
|
||||
held, said as `held` with why `awaits its hand placement`, until its node-engine says, through the seat
|
||||
`node-engine`'s capability event `manifest-reads-changed` (G §590), that it reads a want by version; when the machine
|
||||
is back, its hand placement (the plan's section 5, step 5) runs before anything else on it. Built in H1 (assigner).
|
||||
How it is checked: whole (assigner): a node whose node-engine lacks the capability gets no want of the new form and is
|
||||
said held; live, plan step 5 reads it.
|
||||
|
||||
### Accounts
|
||||
|
||||
- §752 **Every account may call every verb; a module publishes only what it declares.** (ADR 0682 §10; A-434, H-A-11;
|
||||
ADR 0666 §21; principle 6) The grants part grants every module's account every verb and every subscription; it grants
|
||||
a module's account publication only of the events, step results and state its manifest declares (ADR 0666 §21 stays),
|
||||
and an enrolling node's account keeps its own grant. No seat definition names callers, and the `callers` lists of
|
||||
every seat contract go (G §610's class defaults are not built); approval marks stay. Acceptance tests 40, 51 (its
|
||||
callers row) and 85 are not checked. Built in H1 (seat contracts in mesh-contracts and mesh-delivery-contracts; the
|
||||
grants part). How it is checked: unit (seat definition reader: a definition naming callers is refused); whole (grants
|
||||
part, in mesh-delivery): a module calls a verb its manifest does not invoke and is answered; it publishes an event
|
||||
its manifest does not declare and is refused; an enrolling node's account is held to its grant (acceptance test 118).
|
||||
|
||||
### Builds and the builder
|
||||
|
||||
- §753 **A build module takes deliveries first.** (ADR 0525 §4; G §86; H-A-8) Each build module pulls its delivery queue
|
||||
first, then its check queue, then its recheck queue, taking from a later queue only while the earlier is empty, and
|
||||
waits on the bus's pull with no idle re-pull: the five-second idle pull of the shared step runner in
|
||||
mesh-delivery-sdk goes. The turns the code takes today cite an operator's yes of 2026-11-15 that no record holds; if
|
||||
H2's prepare finds it, ADR 0525 gets an insight. Built in H2 (mesh-delivery-sdk's step runner, `buildrun`). How it is
|
||||
checked: whole (Go build module, in mesh-catalog): with three queues full the delivery asks run first (acceptance
|
||||
test 119).
|
||||
- §754 **A done build with no reservation is reserved by the builder itself.** (G §369, A-455; principle 3) When the
|
||||
runner's build step asks a fingerprint whose build is done and carries no reserved version, the builder reserves the
|
||||
next version for it at that ask, says it in its journal and in the step's end, and answers the step carried. Nothing
|
||||
else reserves an old build. Built in H2 (builder: its reserver, and the look that writes "done build no version
|
||||
reserved", which goes). How it is checked: whole (builder, in mesh-delivery): a build step for a done, unreserved
|
||||
fingerprint ends carried with a version (acceptance test 119).
|
||||
- §755 **A failed fingerprint built again keeps its reservation.** (G §369, A-490b; principle 7) When a key is built
|
||||
again (a step ask, an event or `builder_build_again`), the reserver takes that key's own standing reservation as its
|
||||
number; a key with none takes one above the higher of the highest released and the highest any other key reserved.
|
||||
No number is skipped. Built in H2 (builder's reserver). How it is checked: unit (reserver): a failed 0.1.19 built
|
||||
again is 0.1.19; acceptance test 119.
|
||||
- §756 **A build is entered only by the runner's build step.** (G §473, A-97) The builder builds only what a pipeline's
|
||||
build step asks: it builds no catalog entry it hears and follows no gate `source`; the pre-G numbering beside the
|
||||
reservations goes, with its floor wait. `build.ended` carries the reserved `version` (A-430b), for every watched
|
||||
branch. Built in H2 (builder). How it is checked: whole (builder): a catalog entry heard with no step ask builds
|
||||
nothing; `build.ended` names its version (acceptance test 119).
|
||||
- §757 **The steps a mover can run are asked at every pipeline.** (ADR 0666 §7; G §8, §22; H-A-3) At each pipeline's
|
||||
start the runner asks each build seat's `steps` for each mover's artifacts, never only at the seed; a step the answer
|
||||
says has nothing to do ends `nothing to run`, which counts as passed for the pipeline (§746; ADR 0682 §8). Built in H2 (runner).
|
||||
How it is checked: whole (runner): a library module whose unit tests vanish ends that step `nothing to run` and its
|
||||
pipeline passes (acceptance test 119).
|
||||
- §758 **A registration whose pipeline would have no step is refused.** (ADR 0666 §2; acceptance test 67) `register`
|
||||
and `policy` refuse a registration whose policy, read against the build seats' `steps` for its artifacts, leaves no
|
||||
step that runs, naming each artifact and step. A package module with no registration has no pipeline and is never
|
||||
built; the seed (A-441) registers every package module the graph holds, `mesh-delivery-sdk` among them. Built in H2
|
||||
(indexer: `register`, `policy`, the seed). How it is checked: whole (indexer): a registration with every step
|
||||
`bypass` is refused naming them (acceptance test 119).
|
||||
|
||||
### Reads of another part's data become its events and verbs
|
||||
|
||||
- §759 **The status view and the watchman read no other part's bus state.** (ADR 0596 §2, §4; principles 1 and 9)
|
||||
Each read of another module's bucket becomes the owner's event, and the first view the owner's seat verb, in H4:
|
||||
the node-engine's `have` becomes the seat `node-engine`'s event `running` and, for the first view, the verb `haves`
|
||||
the seat gains (what the node runs per module, from its own state); the builder's `builds` becomes the seat
|
||||
`mesh-builds`' `build.ended` and the verb `builds` with `since`; the indexer's `taken` becomes `take-in.taken` and the
|
||||
seat `mesh-catalog`'s verb `revision`; the watchman's `presence` and `stuck` become the seat `mesh-watchdogs`' verbs
|
||||
`presence` and `stuck` and the findings it says (`*.finding-written`, `*.finding-cleared`, G §386's form); the
|
||||
indexer's `candidates` and the teller's `answers` go with their uses (G §512). The watchman's read of the
|
||||
provisioner's `provisions` becomes §773's event. Every other bucket watch of the view the H4 prepare lists against an
|
||||
owner's event; one with none stops that subtask for the lead. How it is checked: unit (each manifest declares no
|
||||
`reads` of another module); whole (view, watchman, in mesh-delivery) against the owners' events.
|
||||
- §773 **Four owners say their changes as events, for H4b.** (H-A-4; ADR 0596; principle 1) Each is a seat event kept
|
||||
on its seat's stream for 7 days (a setting of its owner), with a first-view verb; until H4b builds them, the reads
|
||||
they replace stand and are named leftovers in the gap table:
|
||||
- the seat `mesh-provisioner`: `provision-changed` on `mesh.seat.mesh-provisioner.event.provision-changed.<provision>`,
|
||||
body `{provision, reference, state, at}`; first view its verb `provisions`;
|
||||
- the seat `mesh-vault`: `account-changed` on `mesh.seat.mesh-vault.event.account-changed.<user>`, body `{user, hash,
|
||||
at}`, and `node-login-changed` on `...node-login-changed.<node>`, body `{node, hash, at}`; first view its verbs
|
||||
`accounts` and `node-logins`;
|
||||
- the seat `mesh-grants`: `user-list-changed` on `mesh.seat.mesh-grants.event.user-list-changed`, body `{revision,
|
||||
users, at}`, consumed by the bus node's agent in place of its watch of the key `user-list`; first view its verb
|
||||
`user-list`;
|
||||
- the enrolment module: `enrolment-changed`, body `{node, state, at}`; its seat and its first-view verb are read
|
||||
from the module's manifest at H4b's prepare, which writes them into this line.
|
||||
The grants part then consumes them, and calls the bus module only through the seat `mesh-broker`'s verbs (`list`,
|
||||
`show`, and `users` and `streams`, which the seat gains in place of the module tools `nats_users` and `nats_streams`
|
||||
the grants part calls today). Built in H4b. How it is checked: unit (the owners' seat definitions); whole (grants
|
||||
part): a changed account reaches the user list with no read of the vault's bucket.
|
||||
- §760 **Rates on the bus are read on the seat `mesh-broker`.** (ADR 0595 §5; principle 4) The seat `mesh-broker`
|
||||
gains the read verb `rates`, with `window` (seconds, default 10, from 1 to 60): it reads the bus server's counters of
|
||||
each connection and each stream twice, `window` apart, within the call, and answers per connection (its account's
|
||||
module and node) and per stream the messages and bytes in and out per second, and the slow consumers counted. Its call
|
||||
is bounded at `window` plus 5 seconds, at most 65 seconds. A verb's call timeout is a bound per verb in its seat
|
||||
definition, `timeout`, defaulting to the tool runner's own (principle 11); `rates` names 70 seconds, and the tool
|
||||
runner waits a verb's `timeout` when its definition names one. The field, its schema, the tool runner's wait and
|
||||
`merge-pull`'s 120 seconds are built in H1 (H-A-43: a merge call of several members is cut at a fixed 30 seconds
|
||||
otherwise); the `rates` verb itself in H4 (the bus module). How it is checked: whole (bus module): a fixture publishing 100 messages a second reads between 90 and 110.
|
||||
|
||||
### The read tools found missing
|
||||
|
||||
- §761 **One revision, narrowed, and its differences, in the indexer.** (ADR 0666 §25; principle 4) The indexer gains
|
||||
the tools `indexer_revision` (`branch`, `revision`, optional `module` and `kind`: one catalog revision of any watched
|
||||
branch, narrowed to a module's entries and edges or to one edge kind), `indexer_difference` (`branch`, `from`, `to`:
|
||||
the modules and edges that differ), `indexer_build_order` (`branch`, `modules`: the order the build edges give, its
|
||||
cycles named) and `indexer_built_from` (`fingerprint`: the source revision and commit it was taken in at);
|
||||
`indexer_edges` (G §380) gains `kind`. The node-engine's `engine_build` answers its own fingerprint, version and
|
||||
commit, and `engine_apply_order` is §771's. An answer over the bus's per-message limit is an object's name (ADR 0666
|
||||
§16). The callers of tools no part serves go: the checker's of `indexer_read_candidates` (it goes, §764), and the
|
||||
health checks' and the first views' of `indexer_read_modules`. Built in H4. How it is checked: unit (each tool's
|
||||
answer); the principle-4 table of each module's pull request.
|
||||
- §762 **Every delivery part moves onto the wake-up shape.** (ADR 0682 §11; main file, *Every delivery part wakes on
|
||||
its inputs alone*) The parts and what goes, from the gap table of 2026-11-20 (part F, question 2): mesh-config's
|
||||
key-by-key pass, five-minute sweep and minute's read (`sources`, the held pull request mesh-catalog #708, H1); the
|
||||
grants part's whole recompose (`Compose`, H4b); the indexer's re-read of every module, graph key and manifest after
|
||||
each write (`KeepView`, `viewEntries`, `heldModules`, H4); the builder's start sweep and `builder_stuck`'s read of
|
||||
every key (`Sweep`; it answers from the builder's own index of what builds, H4); the assigner's input sweep and its
|
||||
ten-second poll of `backed-up` (`inputKeeper.sweep`, `snapshotTheBus`, H4); the watchman's five-minute recount of
|
||||
dead letters (H4); the build modules' stale round and idle pull (`EndStaleRound`, §753, H2); mesh-sdk's first view
|
||||
asked again with a backoff (`views` reader, H4); the view's five-second retries (§759, H4); the forge module's
|
||||
one-minute poll and ten-minute timer (H3). The decided pulses (G §496's minute of `step-progress`, G §606) are real
|
||||
deadlines and stay. Its cost: the shape lives in mesh-sdk's state package, so its release rebuilds nearly every
|
||||
module (every module that imports that package, about 120 by the graph of 2026-11-20); it is carried by H4 alone, one
|
||||
release, delivered by the pipelines of the movers it names; H1's mesh-sdk change is only the seat definitions' copies
|
||||
and the `timeout` field (H-A-42, H-A-43), published first. How it is checked: as the main file's rule says.
|
||||
|
||||
### Questions this file leaves open
|
||||
|
||||
None: the enrolment event's seat and first-view verb (§773) are owed to H4b's prepare.
|
||||
@@ -0,0 +1,125 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H
|
||||
updated: 2026-11-20
|
||||
decisions:
|
||||
- "ADR 0682"
|
||||
- "ADR 0681"
|
||||
- "ADR 0667"
|
||||
- "ADR 0666"
|
||||
- "ADR 0633"
|
||||
- "ADR 0595"
|
||||
---
|
||||
# 47, milestone H: the corrections made in place, the stale state, and what retires
|
||||
|
||||
One file of milestone H's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
|
||||
[H-deliver-the-delivery-system](H-deliver-the-delivery-system.md), and its lines follow
|
||||
[H-2](H-2-wants-builds-reads-and-tools.md)'s, cited as "design 47 H §n".
|
||||
|
||||
- §763 **The small contradictions are corrected in place.** (plan item 10; each line names its source) These lines of
|
||||
milestone G and the main file now say what holds, each marked "corrected in place by design 47 H §763":
|
||||
- G §5: `register` and `watch` refuse no unprotected branch (ADR 0682 §13, which ends ADR 0666 §3; the operator,
|
||||
2026-11-14, G-23 *Met during G's start*). G §17, G §38's and G §41's protection judgement of `merge-pull`: no part
|
||||
reads a branch's protection (ADR 0682 §13, which ends ADR 0666 §11's protection judgement and §6's condition).
|
||||
- G §654: mesh-config consumes no pull request event and calls no `git.pull` (ADR 0681 §1).
|
||||
- A-449 and A-449a: the runner says no `pinned` or `freed`; the indexer pins and frees a pipeline's revision (§749).
|
||||
- Acceptance test 53: its `forge-made` and checker rows go (G §151; §740; the checker goes).
|
||||
- G §476 and §648: `take-in.taken` carries one entry per mover, `{module, commit, fingerprint, repository}`, no
|
||||
`pull` (§743).
|
||||
- G §40: the operator channel keeps no count of open asks per asker and offers every ask (ADR 0682 §14, which ends
|
||||
ADR 0666 §12's three; A-424, the operator, 2026-11-15).
|
||||
- G §386: the grants part makes one durable consumer per process that hears a `*` event, named as A-397 names it.
|
||||
- G §73's subject table and G-4's row of the runner's events, and G §74's wait per module: `pipeline-started` and
|
||||
`pipeline-ended` are said per source revision and waited for so (§746).
|
||||
How it is checked: hq's review of this amendment reads each corrected line against its source.
|
||||
- §764 **What retires at milestone H's delivery.** (ADR 0682 §1 to §4, §6, §8, §9, §13, §14; ADR 0681; ADR 0667 §12) Each is
|
||||
removed in the release named, with its code, its state (dropped by §765), its tools, its events in the seat
|
||||
definitions, its readers and its tests; nothing of it is kept unread.
|
||||
- **The forge module (H1, H3):** the single-pull form of `merge-pull` (§734); the merge-check machinery: the
|
||||
`mesh/merge-gate` pending statuses, the weighing of trunk and sibling moves (`announceHead`, `passPulls`,
|
||||
`trunksMoved`, `siblingMoves`, `GateWriter`) and its files on disk, its one-minute poll and ten-minute timer (H3).
|
||||
The forge's branch protections drop the required statuses `mesh/merge-gate` and `mesh/repo-check` in H1, through
|
||||
the forge module's protection setting, so no merge waits on a status nothing writes (H-A-15).
|
||||
- **The branch protection (H1; ADR 0682 §13):** `merge-pull`'s judgement of a branch's protection, the bridge's
|
||||
read of it on every move and its finding `branch-unprotected` (G §17), and the protection rows of G §41's test.
|
||||
- **The operator channel's limit (ADR 0682 §14):** any count of open asks per asker, and ADR 0666 §25's tool for
|
||||
asks held back, which reads empty and goes.
|
||||
- **The forge bridge (H1):** the messages `merged` and `pushed` and their `base` (§739), with their readers, the
|
||||
indexer's take-in and the gate's `ForgeMerged`; its state `inputs` and its read of trees; its call of `git.pull`
|
||||
for a merged commit; the group it sets on a member, `forge.group.merged`, `bridge_groups` and
|
||||
`bridge_group_end_again` (G §43, §45, §157, §715); its hearing of the checker's `owed` and the merge act of a
|
||||
switched key (`OwedActMerge`, its `invokes` of `seat:git.merge-pull`, G §510).
|
||||
- **The gate (H1, H3):** the source per merged message (A-464 to A-464e: `ForgeMerged`, `moveHead`,
|
||||
`gate_source_follow`, the start's comparison with the forge's heads) and its consumption of the bridge's `merged`;
|
||||
the source moved on `take-in.taken` (A-34; §737); the groups from a branch name (G §42, §716, A-279): its states
|
||||
`deliveries` and `groups`, its consumption of `pull-updated`, `pull-merged` and `pull-closed`, its start
|
||||
reconciliation through `open-pulls` and `pull`, and the verb `groups` (the verbs `deliveries` and `show` answer
|
||||
from the records, A-24); the switch and the carried approval (G §156, §169, §542, A-281: `approval-carried`,
|
||||
`approval-carried-open`); the states `merges`, `owed` (the old bucket), `asks`, `pulls` and `turns`, and the seat
|
||||
definition's entries for them.
|
||||
- **The indexer (H1):** the take-in fed by the bridge's messages; the state `pending` with its keys `m.<sequence>`
|
||||
and `g.<group>`; the hold for the indexer a revision names (ADR 0633 §1, the main file's *Taken in by the indexer it
|
||||
names*) and `indexer_drop_pending`; the validation at the take-in (G §16, §19, §237, §712, §713; A-475, A-475a),
|
||||
which becomes §745's step; its events `manifest-refused` and `manifest-accepted`, with their reader, the watchman's
|
||||
findings `manifest-refused` and `manifest-outgrown` raised from them; the catch-up by comparison (A-463, A-463a,
|
||||
A-490k, G §177's first-start half, G §362: `kickBehind`, `TakeInBehind`, `sayUntaken`, `takeInHeads`,
|
||||
`kickCatchUp`, `CatchUp`) and its condition `merge-untaken`; the source numbering in memory (A-431,
|
||||
`nextSource`); the 30-minute group wait of `take-in-waits`; the field `pull`; the config candidates (ADR 0681 §2).
|
||||
- **The runner (H1):** the sweep (`StartUnstarted`, `Unstarted`; `StartHeld` of mesh-delivery #262, closed
|
||||
unmerged); the start-time `outdated` (G §375) and `runner_catch_up`, never built; `group-ended` (G §332) and its
|
||||
stream `SEAT_mesh-pipeline-runner_group-ended`; the pipeline key per module; its `pinned` and `freed`.
|
||||
- **The assigner (H1):** the holds §750 names, with `acting-part-late`, `delivery-waits`, `version-delivered`,
|
||||
`assigner_delivered_again`, the acting rows of `assigner_waits` and `assigner_release`; the order waits
|
||||
(`order.<node>.<module>.<part>` in its state `waits`, §771); the parts check and the `want-parts` capability; A-436's
|
||||
digests in a want.
|
||||
- **mesh-config (H1):** its pull request path (ADR 0681 §1, §7) and A-490l's pull sweep.
|
||||
- **The checker (H1):** `mesh-delivery-checker` whole, with its verdict verb, its calls of
|
||||
`indexer_read_candidates`, `mesh/check` and its try; it is not placed at the clean state.
|
||||
- **Every seat contract (H1):** the `callers` lists (§752).
|
||||
- **Acceptance tests:** 38, 49, 81, 82, 105 and 106 as written; tests 110 to 119 hold what remains of them, and test
|
||||
67 is read with a merge call naming its three repositories.
|
||||
How it is checked: after each release, a search of the trunks of mesh-catalog, mesh-delivery, mesh-sdk,
|
||||
mesh-contracts, `mesh-host` and mesh-tools for each name above finds it in no file outside tests that assert its
|
||||
absence, and `mesh-broker.list` shows no bucket or stream of a state above.
|
||||
- §765 **The stale state goes once, after the new programs run.** (ADR 0682 §12; H-A-15, H-A-19; the operator,
|
||||
2026-11-20 about 01:10 CET: "I don't care about old data at this moment, I want a working mesh again") At milestone
|
||||
H1's clean state, after the new programs run on every present machine (the plan's section 5, after step 5.6) and
|
||||
before the runner starts, every state §764 retires goes, and with it: the gate's 833 open records; the indexer's pins
|
||||
that name no running pipeline; the pipelines of the earlier model; the stopped runner's queue of `take-in.taken` of
|
||||
the old form, with the consumer that holds it; every held or failed want. Each goes as ADR 0595 §4 removes kept data,
|
||||
on that word, through the tool named for it: a record through `gate_record_end`, a pin through the indexer's
|
||||
`indexer_pin_drop` (with `key` and `why`, which H1 adds), a pipeline through the runner's `cancel`, a held or failed
|
||||
want through the assigner's `assigner_want_drop` (with `node`, `module` and `why`, which H1 adds), and every retired
|
||||
state, once no running module declares it (an orphan `orphans` lists), through the seat `mesh-broker`'s `drop`. The
|
||||
bus module's stream snapshot taken before the first drop is the rollback. The pack says what it deleted, counted.
|
||||
Every durable consumer the new programs make starts at the newest message of its stream and refuses an event of the
|
||||
old form (one with no field its new form requires) with a journal line naming it. The delivery records of the one
|
||||
model start from the clean state. How it is checked: the lead reads `mesh-broker.list` and each module's read tools
|
||||
before and after, and quotes the counts; the snapshot's restore is tested before the first drop (ADR 0595 §4).
|
||||
- §774 **Tests per module, against the budget, and where H1's run before its merge.** (H-A-16, H-A-17; the test
|
||||
budget, 50 integration and 500 unit tests per module) Each acceptance test of H is one whole test per module, in that
|
||||
module's repository (tests 110 to 119 name which); the chain of test 110 is the live proof. The counts, read from the
|
||||
gap tables of 2026-11-20 (unit, then integration), and what H adds:
|
||||
|
||||
| module | today | H adds (whole tests) | H retires |
|
||||
|---|---|---|---|
|
||||
| forge module (seat `git`) | 177 Go and 196 TypeScript, 1 | 1 TypeScript whole test of the seat `git` (§734 to §736, §766, §767; tests 114, 115) | the merge-check machinery's tests |
|
||||
| forge bridge | 45, 8 | none: its whole test is rewritten for `head-moved` | the `merged`, `pushed`, group and owed-merge tests |
|
||||
| gate | 38, 2 | 1 (the merge call, the record, the watchdog; tests 110, 111) | the source-follow, group and switch tests |
|
||||
| indexer | 194, 13 | none: its whole test is rewritten for the take-in (tests 112, 116) | the pending, catch-up, validation and group tests |
|
||||
| runner | 78, 3 | 1 (the queue; test 112) | the sweep's tests and `group-ended`'s |
|
||||
| assigner | 126, 13 | none: its whole test is rewritten for §750 and §751 (tests 113, 117) | `TestEachRuleHoldsTheWantBack` and the hold tests |
|
||||
| node-engine | 1,719, 10 | 1 (the apply order; test 113) | the want-parts tests; over the unit budget, every H change to it deletes at least as many unit tests as it adds |
|
||||
| grants part | 78, 1 | none: its whole test gains §752's cases (test 118) | — |
|
||||
| builder | 154, 18 | none: its whole test gains §754 to §756 (test 119) | the pre-G numbering's tests |
|
||||
| tool runner | 152, 7 | 1 that starts it whole (H-A-16's gap) | — |
|
||||
|
||||
Every module stays within 50 integration tests; acceptance tests 38, 49, 81, 82, 105 and 106 retire (§764). Before
|
||||
H1's merge its integration tests are run once locally against an embedded bus, as the mesh's instruction
|
||||
*how-work-is-done* allows, and each pull request says so; the chain's live proof (the plan's section 5, step 7) is
|
||||
H1's check, and from H1 on the pipeline makes the check (H-A-16, a rule weighed and said). The counts above are per
|
||||
module; the count per release and the number of tests each retired test frees are each milestone's prepare's, written
|
||||
in its milestone file. How it is checked: each pull request of H states its module's counts against the
|
||||
budget; the review refuses a count over it.
|
||||
@@ -0,0 +1,479 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H
|
||||
updated: 2026-11-20
|
||||
decisions:
|
||||
- "ADR 0682"
|
||||
- "ADR 0681"
|
||||
- "ADR 0667"
|
||||
- "ADR 0666"
|
||||
- "ADR 0656"
|
||||
- "ADR 0633"
|
||||
- "ADR 0596"
|
||||
- "ADR 0595"
|
||||
- "ADR 0573"
|
||||
- "ADR 0548"
|
||||
- "ADR 0525"
|
||||
---
|
||||
# 47, milestone H — the plan to deliver the build-and-delivery system properly
|
||||
|
||||
The operator, 2026-11-19 about 23:30 CET: "This mess has been going on for too long and I want to fix it properly.
|
||||
Write out a plan to deliver our mesh build-and-delivery system. Thoroughly. The research and design 47 should have
|
||||
all the details of what it should look like and what it should do. Unfortunately, the code is very very poor. So we
|
||||
need to fix it. What is our best approach? I'm willing to do some hand-deploys to get us into a clean state." And:
|
||||
"Nobody should 'take in a merge', only commits to the configured branch of registered modules."
|
||||
|
||||
This file is that plan. It was written by the lead (lead-47) on 2026-11-20 between 00:00 and 01:00 CET from seven
|
||||
readings by agents: one specification per part of the design (what design 47, its milestone G, research 086 and their
|
||||
records say the part does; no code read) and one gap table per part (main's code of 2026-11-19 held line by line
|
||||
against that specification, with what runs live on each machine). The readings are in the working folder
|
||||
`.work/plan-47/` of the lead's hq working copy (`spec/`, `gaps/`, `live-state.md`); their findings are summarised
|
||||
here, and every number below comes from them unless it says otherwise. The plan is the lead's; the operator reads it
|
||||
before any code is written.
|
||||
|
||||
**Milestone H's part.** This file opens the part; its design lines (section 4's items as lines, numbered after G's
|
||||
§733 and cited as "design 47 H §n") are in three files, each read whole:
|
||||
|
||||
- [H-1-the-merge-call-and-the-take-in](H-1-the-merge-call-and-the-take-in.md): the merge call, the gate's source
|
||||
revision and record, the forge bridge's one message and the watchdog, the take-in, the step `validate`, one pipeline
|
||||
per take-in and none in parallel, a pipeline's pins, the clean state's seed (§734 to §749, §766 to §770).
|
||||
- [H-2-wants-builds-reads-and-tools](H-2-wants-builds-reads-and-tools.md): the want rule, the order on one machine,
|
||||
every account may call every verb, the builder's lines, the reads of other parts made events, rates on the bus, the
|
||||
missing read tools, which part moves onto the wake-up shape in which release, the four owners' events and a machine
|
||||
away at the clean state (§750 to §762, §771 to §773).
|
||||
- [H-3-corrections-and-what-retires](H-3-corrections-and-what-retires.md): the contradictions corrected in place, what
|
||||
retires, the stale state dropped once, and the tests per module against the budget (§763 to §765, §774).
|
||||
|
||||
The wake-up rule itself is in the main file, *Every delivery part wakes on its inputs alone*. Where an H line and a G
|
||||
line or lead's answer differ, the H line holds, and the G line it corrects in place says so.
|
||||
|
||||
## 1. Where the system stands (read 2026-11-20 00:05 to 00:30 CET)
|
||||
|
||||
**What works.** One pipeline delivered one module end to end with no hand act on 2026-11-19 at 22:48 (the image
|
||||
registry, main.1039). The shape of the design is in the code: of 619 table rows of design lines held against main, 413 are built by their contract: 78
|
||||
per cent of the 527 rows judged (the rest belong to another part's code) (per part: runner 87 of 100 judged, gate and bridge 71 of 93, indexer 70 of
|
||||
89, assigner and node-engine 56 of 76). No part needs to be written again whole.
|
||||
|
||||
**What does not work.** The system cannot deliver itself today:
|
||||
|
||||
| symptom (live) | count | cause (from the gap tables) |
|
||||
|---|---|---|
|
||||
| wants held or failed on the four machines | 205 held, 66 failed | the catalog half holds no entry for their fingerprints; the node-engines compose nothing new |
|
||||
| compositions fail on shanks | entries `asked` since 2026-11-18 03:09, unready answers seen from 2026-11-19 11:56 | an entry ask that failed in transport is never asked again; the node-engine's shadow waits on it without bound (the surveyor's reading); other compositions failed on the removed revision trunk.510 and on a call-token refusal |
|
||||
| delivery records open, none ended | 833 open, 0 ended since 2026-11-14 | the gate hears only `take-in.taken`; nothing writes a record's trace, so its difference is never known |
|
||||
| pipelines about to start at the next take-in | about 60 (reasoned from the sweep's rule; no tool reads the runner's waiting starts) | the runner's sweep starts a pipeline for every module whose fingerprint has none (b9c50ef0, 2026-11-16); no design line allows it |
|
||||
| source revision moved twice | both paths on main | A-464 (per merged message) wins live over A-34 (on the take-in): a group's members become separate revisions; a pushed commit reaches the source only through the take-in or the gate's comparison at its next start |
|
||||
| catalog revision removed while pipelines name it | trunk.510 at 22:51 | pins are judged at restart against a key written once; only the take-in pins pipelines |
|
||||
| stale bus state | 753 merges, 6,951 owed, 898 asks, 1,256 pulls keys; 5 pipelines running since midday; 31 stale pin records | buckets of the pre-G model never dropped; no tool reads their contents |
|
||||
| bus load | 98 slow consumers, 117 consumers behind; the watchman 39,037 events behind | mesh-config passes every 5 minutes and polls every minute on main (fixed on the held pull requests); the forge module polls every minute |
|
||||
| hand-placed programs | every delivery module but the indexer, the image registry and the tool runner (on ace and g14) | G's live start of 2026-11-16 and after; 16 drop-in files under `/run/systemd/system` on the four machines (4 of them `.pre-g` copies), lost at a reboot |
|
||||
|
||||
**Every node, every module** (the assigner's assignments at revision 339, unchanged since 2026-11-18 02:08 UTC; the
|
||||
node-engines' haves; read 00:47 to 00:54 CET):
|
||||
|
||||
| machine | placed | running | held | failed |
|
||||
|---|---|---|---|---|
|
||||
| the control node | 90 | 10 | 53 (entry missing) | 24 |
|
||||
| the build node | 80 | 12 | 59 (entry asked) | 7 |
|
||||
| the desktop | 83 | 24 | 33 (entry missing) | 26 |
|
||||
| the laptop | 76 | 6 | 60 (45 entry asked, 15 entry missing) | 9 |
|
||||
|
||||
65 of the 66 failed wants fail for one reason: the want names no digest for the module's files, code or tools (the
|
||||
A-430 stand-in, a want naming its parts, left half built). The one other is the desktop's node-engine ("operation not
|
||||
permitted" unpacking a version). No service is failed on any machine; the 25 open conditions are warnings. Every
|
||||
delivery module's want is held by the assigner's rule 2 (no passed pipeline at the graph's fingerprint); before it,
|
||||
rule 8 held the 23 bus-state modules because the bus module's have is held although the bus runs. The haves are wrong
|
||||
about what runs for three modules (the tool runner on two machines, the indexer): `node-engine.process-builds` is the
|
||||
tool that says it, found only in this second reading.
|
||||
|
||||
**The module graph** (the indexer, trunk revision 512, source 1038): 193 modules; 269 package edges (published before
|
||||
it builds), 178 toolchain edges, 208 provider and requirement edges, 212 served-verb edges (19 verbs served by no
|
||||
module), 30 await edges; the acting-part and contribution edges are not in the graph's state. The other watched branches
|
||||
stand at revision 1 since 2026-11-14. No tool answers a build order or a deploy order for a set of modules, the
|
||||
difference between two revisions, a revision narrowed by module or edge kind, or which source commit a fingerprint was
|
||||
built from; the whole revision is 1.3 MB, over the bus's message size. Those reads are tools milestone H4 builds in the
|
||||
indexer and the assigner (one-question-one-tool; section 4, item 12).
|
||||
|
||||
**No pull request is checked today.** The checker's verdict verb asks the indexer `indexer_read_candidates`, which no
|
||||
running indexer answers (503 no responders), so no `mesh/check` status is ever set; the forge calls every pull request
|
||||
mergeable because main requires no status. Nine open conditions ask `indexer_read_modules` the same way. Tools were
|
||||
removed or renamed while their callers still name them; by design 47 G the pipeline makes the check and the checker
|
||||
goes (G-2), which milestone H1 builds for hq too (hq is a registered module whose one step is its Go checks).
|
||||
|
||||
**The root of it, in one sentence.** The design settled on one model (a change is a commit on a watched branch of a
|
||||
registered module; the forge bridge says it, the indexer takes it in per branch, the runner starts exactly the movers,
|
||||
the gate follows), but the code carries that model and the earlier per-pull-request model side by side, and the live
|
||||
patches of 2026-11-16 and 2026-11-17 (the sweep, the source per merged message, the catch-up by comparison) were
|
||||
written on the earlier one. Every list above is a consequence.
|
||||
|
||||
## 2. The approach, decided
|
||||
|
||||
1. **One model, no leftovers.** A change is a commit on a watched branch of a registered module (design 47 G §11,
|
||||
ADR 0666 §6). The forge bridge says every move of a watched branch's head, and at its start reads every watched
|
||||
branch's head and says it (G §11, A-236). The indexer takes a move in per watched branch (A-476: the commit, the
|
||||
fingerprints of that repository's modules, a catalog revision; `take-in.taken` names the movers by A-476a). The
|
||||
runner starts one pipeline per mover and nothing else (G §12, §112: never by a sweep). The gate moves the
|
||||
source revision on `take-in.taken` alone (A-34, G §592). Everything of the earlier model goes: the gate's and the
|
||||
bridge's pull-request paths, the source per merged message (A-464 series), the catch-up by comparison (A-463,
|
||||
A-490k), the runner's sweep, the start-time `outdated` by digest comparison (G §375; a kind-1 dependent is started
|
||||
by `package-published`, which the runner's durable consumer delivers also after a stop), the forge module's
|
||||
merge-check machinery and its polls. Principles 1 and 7 settle this; design 10 names a change found by comparison
|
||||
as a failure mode.
|
||||
2. **Fix in place, every module; write one part again.** Each gap table judged its modules by the share of lines
|
||||
built and by whether their events, verbs and kept data are the design's. All say fix in place, mostly by deletion,
|
||||
but two parts: the assigner's want rule (about 2,600 lines of `wants.go` and the want half of its pass, written again
|
||||
to A-478) and the indexer's take-in part (about 3,400 of its 34,000 lines: pending, source numbering, behind, the
|
||||
branch take-in, the pull-request candidates and previews) is written again as one take-in per watched branch fed
|
||||
by the forge stream alone; its storage, entries, pins, versions and verbs stay.
|
||||
3. **The design first, then code.** Where the operator's words and the lead's live answers departed from the
|
||||
written lines and records, the lines and records are brought in line before any code (implement-the-design,
|
||||
design-it-as-it-should-be): section 4 lists them. No lead answer patches a design question this time.
|
||||
4. **One clean state by hand, once.** The system cannot deliver the fixes to itself, so milestone H1's programs are
|
||||
built from main after its merges and placed by hand on the four machines as one mutually consistent set, the
|
||||
stale bus state is dropped, and from that moment nothing is placed by hand again: every later milestone is
|
||||
delivered by a pipeline, and that delivery is its proof (principle 5). Section 5 is the step list.
|
||||
5. **Milestones in dependency order, one release each**, each proven by one pipeline delivering it, with the
|
||||
guards of section 7 so it does not rot again.
|
||||
|
||||
## 3. The six parts: findings and the decision per module
|
||||
|
||||
Each part's specification and gap table hold the line-by-line detail; this is the summary a reader needs to judge
|
||||
the plan.
|
||||
|
||||
### 3.1 The forge bridge and the gate (mesh-delivery: the bridge and both seat contracts; mesh-catalog: the gate and the forge module)
|
||||
|
||||
Built 71, built otherwise 5, contradicts 10, missing 7, not judged 15 (of 108). No gap is large alone.
|
||||
|
||||
- **No delivery record ever ends.** The gate consumes only `take-in.taken`. It must consume the runner's
|
||||
`pipeline-ended`, the node-engines' `running`, the `wait-held` and `wait-ended` events and the assigner's families
|
||||
(G §5, §146) to write a record's trace and end it (G-3 "The delivery record").
|
||||
- **Two paths move the source revision**; the per-merge one (A-464, about 330 lines) acts live and the design's
|
||||
(A-34, about 75 lines) is left without effect. A-464 goes.
|
||||
- **The per-pull-request model** is about 1,300 of the gate's 5,475 lines and about 1,050 of the bridge's 4,281.
|
||||
It goes, apart from what the operator's answer on groups keeps (section 4, question 1).
|
||||
- **The forge module** holds no failed pipeline step (`failed-steps` has 0 entries, so `merge-pull` refuses
|
||||
nothing), and still runs the old merge-check machinery: `mesh/merge-gate` statuses, weighing kept in files on disk,
|
||||
a one-minute poll and a ten-minute timer. All of it goes.
|
||||
- **Decision:** fix in place, mostly deletion. Gate: consume the two events, end records, one source path, drop the
|
||||
pull-request model. Bridge: drop the pull-message path, the checker's owed acts and the merge act. Forge module:
|
||||
drop the merge-check machinery and the polls; find why `seen` is empty (the surveyor's guess: the hand-placed
|
||||
runner says `step-ended` without commit and fingerprint). Seat contracts: drop `asks` and `turns` and the callers
|
||||
lists (small).
|
||||
|
||||
### 3.2 The indexer and mesh-config (mesh-delivery: the indexer; mesh-catalog: mesh-config)
|
||||
|
||||
Built 70, built otherwise 8, contradicts 7, missing 4, not judged 18 (of 107). Seven medium gaps in the indexer are
|
||||
one problem: the take-in's shape.
|
||||
|
||||
- **The take-in is the trunk's alone, fed by two paths**: a `merged` or `pushed` message of any branch lands in the
|
||||
trunk's one view (a `pushed` message has no base), other watched branches get revisions only by comparing against
|
||||
the gate's `source-moved`, one `pending` holds every branch, and the catch-up takes heads in outside `pending`.
|
||||
- **Revisions are made at every keep, not only at a take-in**: "27 changed" counts entries whose stored form differs
|
||||
from the newest kept revision; two revisions were kept at the 22:51 restart with no `take-in.taken`.
|
||||
- **Pins** are judged at restart against a `made` key written once in the state's life and against the server's
|
||||
pending count, which is 0 at start, so the last restatement counts at once and trunk.510 was removed while
|
||||
pipelines named it. Source numbers live in memory and restart from the gate's number while later pipelines exist.
|
||||
- **mesh-config** on main passes every 5 minutes, polls every minute and reads its states key by key (issue 1982);
|
||||
the held pull requests mesh-catalog #708, mesh-contracts #16, mesh-sdk #200 and mesh-delivery #261 make it wake
|
||||
on events and one deadline timer, reading from watched copies, and remove its pull-request path (ADR 0681).
|
||||
- **Decision:** write the take-in part again (one take-in per watched branch, from the forge stream alone, movers by
|
||||
A-476a, source numbers on the bus, pins restated by every asker and judged against what is pinned now, never
|
||||
against a count); keep storage, entries, pins' state, versions and verbs. mesh-config: merge the four held pull
|
||||
requests; its reads of the indexer and the assigner through module tools (principle 9) and its full pass per
|
||||
event are a later milestone's.
|
||||
|
||||
### 3.3 The pipeline runner (mesh-delivery: mesh-delivery-pipeline)
|
||||
|
||||
Built 87, built otherwise 5, contradicts 2, missing 6, not judged 19 (of 119). No large gap; 4 medium, 9 small.
|
||||
|
||||
- **The sweep** (`StartUnstarted`) runs after every take-in and at every start; removing it is small. The held pull
|
||||
request mesh-delivery #262 adds a third start path (`StartHeld`); it is closed, not merged.
|
||||
- **The refused step ends naming an empty pipeline** are the assigner's composition runs on the Go build seat: the
|
||||
runner reads the pipeline field before the asker field. Skip an end whose asker is not the runner (small).
|
||||
- **Missing, medium each:** `toolchain-agreed` starts no kind-3 rebuild (G §376); nothing consumes `approval-carried`
|
||||
(G §542); each repository's own checks are not a step (G-2); the start-time `outdated` and `runner_catch_up` (G §375)
|
||||
do not exist, and by decision 1 they are not built: a kind-1 dependent is started by `package-published`, which the
|
||||
durable consumer delivers also after a stop (section 4, item 7 says it as a line).
|
||||
- **A bound on pipelines at once** has no design line; principle 11 makes it a setting (`pipelines-at-once`). A start
|
||||
over the bound is written with no steps and placed when the runner's own `pipeline-ended` comes, no timer
|
||||
(medium). What a waiting pipeline reports against G §12's `pipeline-stands` is a design line (section 4).
|
||||
- **Timers found:** mesh-sdk's view catch-up asks again on a timer (against A-490k's "no timer"); a one-minute
|
||||
ticker while the step log is full. Both go in the class fix of section 3.6.
|
||||
- **Decision:** fix in place. The self-hold A-446 removed is already gone from main (commit 070a5dd3).
|
||||
|
||||
### 3.4 Builds, the builder and the registries (mesh-delivery: the builder, the artifact holder; mesh-catalog: the build modules, the forge's package registry, the image registry)
|
||||
|
||||
Built 73, built otherwise 3, contradicts 8, missing 2, not judged 24 (of 110). 85 per cent of the judged rows
|
||||
built; no large gap, five medium.
|
||||
|
||||
- **A failed key taken again skips a version** (G §369): the reserver treats a key's own standing reservation as its
|
||||
floor unless the source says rebuild, and only the hand tool `builder_build_again` says so; a failed key taken again
|
||||
by a look, an event or the start moves its number on by one. This is the 0.1.19 skip. Small.
|
||||
- **The pre-G numbering still runs beside the reservations** (design 51's versions, replaced): it numbers every trunk
|
||||
build from its own state and floor, can hold a build waiting for that floor, and its late look writes the live "done
|
||||
build no version reserved" line. Medium; it goes.
|
||||
- **The builder is not entered only through the runner's `build` step** (G §473, A-97): it builds every catalog entry
|
||||
it hears and still follows the gate's `source`. Medium; it goes.
|
||||
- **`build.ended` carries no version** (A-430b), and builds of other branches reserve nothing.
|
||||
- **The build modules** pull their three queues in turns, not deliveries first (ADR 0525 §4, G §86; a code comment
|
||||
cites an operator's yes of 2026-11-15; the surveyor did not search the knowledge base for it, so H2's prepare does: if
|
||||
the yes was recorded, the record and the lines are out of date, not the code), and when idle re-pull every 5 seconds, a poll. The artifact
|
||||
store is read by raw HTTP in group runs; the registries are reached through bus verbs. Two copies of the client that
|
||||
asks `reserved` differ (the forge's and the image registry's).
|
||||
- **The publish again** runs in one shape, A-457's retried items with A-473's ask at build end as their first try;
|
||||
§588's event path is gone and its queue remains as plumbing. Live, all 42 publish retries ended after 8 tries,
|
||||
unreleased, and 37 reservations built since 2026-11-18 were never published (cause a guess, in the table).
|
||||
- **From the specification:** a module with no registration has no pipeline and is never built, so
|
||||
mesh-delivery-sdk's missing registration blocks mesh-delivery-contracts by design; a `required` step ending
|
||||
`nothing to run` holds the delivery and no line works it out again later; no line has the builder reserve an old done
|
||||
build by itself. Each is a design line to write (section 4, item 11).
|
||||
- **Decision:** fix in place, all three. Builder: remove the numbering, the gate-source follow, the builds without a
|
||||
step ask and the other pre-G mechanisms the table lists; fix the reserver's floor and the version on `build.ended`.
|
||||
Build modules: deliveries first and no idle poll in the shared step runner; the store read over the bus. Registries:
|
||||
one `reserved` client, the forge's form moved into `mesh-delivery-contracts` as the surveyor recommends. The delivery
|
||||
budget (G-2) is checked by nothing; medium, H2.
|
||||
|
||||
### 3.5 The assigner, the node-engine and the tool runner (mesh-delivery: the assigner; `mesh-host`: the node-engine; `mesh-tools`: the tool runner)
|
||||
|
||||
Built 56, built otherwise 8, contradicts 9, missing 3, not judged 7 (of 83). Assigner 31 of 44 built, node-engine
|
||||
17 of 27, tool runner 8 of 12.
|
||||
|
||||
- **The want rule A-478 is not built** (the newest released version whose pipeline passed, on every machine that
|
||||
places the module; the operator, 2026-11-17). Every old rule still holds wants: canary, grant, provisions, served
|
||||
verbs, bus state, the acting-part waits (about 450 lines), the `version-delivered` holds (about 500), the parts
|
||||
check (about 250), the rest about 300. All of it goes; the backup, the yes on a failed backup or a held revert, and
|
||||
A-478b's order waits on one machine stay (the order waits reshaped to order one machine's apply, not hold wants).
|
||||
- **The assigner reads every have** whole and with history (§520 says it goes); wants are not written from the kept assignment graph revision. Medium each, H1. (The node-engine's read of
|
||||
every node's record stays: it feeds the composer; H-A-60 corrects the earlier reading of §459.)
|
||||
- **The shanks shadow fault**: the entries client leaves an entry `asked` after a transport failure and never asks
|
||||
again; about 110 entries on shanks have stood `asked` since 2026-11-18 03:09. Ask again on failure, with a bound
|
||||
(small). The surveyor's reading, to be confirmed by `entry-again` on one entry during the clean state.
|
||||
- **The tool runner:** A-490m is ready on mesh-tools #77 (merge); it lacks a test that starts it whole.
|
||||
- **Tests:** the node-engine has 1,719 unit tests against a budget of 500; every change to it shrinks that.
|
||||
- **Decision:** fix in place, all three. The want rule is rewritten to A-478 in `wants.go` and the want half of the
|
||||
pass; the old holds are deleted.
|
||||
|
||||
### 3.6 The status view, the watchman, health, the tools and the grants part (mesh-delivery: the view, the watchman, the grants part; mesh-catalog: the bus's module; mesh-tools; mesh-sdk)
|
||||
|
||||
Built 56, built otherwise 11, contradicts 5, missing 11, not judged 9 (of 92).
|
||||
|
||||
- **The status view, the watchman and the grants part read other modules' buckets directly**, against ADR 0596: the
|
||||
view watches twelve such buckets, retries each every 5 seconds, and still follows the teller's answers and the gate's
|
||||
source, which §512 retires. Large, with the want rule, the take-in and the SDK's generic state tools (the fill against
|
||||
a cap in every module's tools, the grants part's `filling` and `room`) the large gaps of the survey.
|
||||
- **The kind of fault behind issue 1982 is in more modules than mesh-config.** The grants part recomposes everything
|
||||
and reads its own states key by key on every change; the indexer re-reads every module, every graph key and every
|
||||
manifest after each verdict, import or source move (its modules state stands at revision 1,789,962); the view
|
||||
retries twelve watches every 5 seconds; the forge module polls every minute; the build modules re-pull every 5
|
||||
seconds when idle; mesh-sdk's view catch-up asks again on a timer. The gap table's section 5 has the table of
|
||||
modules, functions and intervals. The fix belongs in mesh-sdk, for every module at once (fix-a-bug-met-twice).
|
||||
- **`builder_stuck` times out** for a fixed cost, measured in the tool runner's journal on shanks: 1,010 values took
|
||||
52.5 seconds and 53 values took 44.5 seconds. Each call starts a tool process that lists every key of `builds` and of
|
||||
every build seat's `steps`, then reads one value per request. The builder keeps its own index of what is building
|
||||
and answers from it. Medium.
|
||||
- **The runner's live seat serves five read verbs and no act**; main has them all (commit 8fa1b8ae). The surveyors'
|
||||
guess is a hand-placed build from before it, or an older tools bundle; the clean state ends either.
|
||||
- **Who may call what** stands in two forms: §610's class defaults and A-434's stand-in that every account may do
|
||||
everything. **The lead's answer: principle 6 settles it** (inside the mesh every module is trusted, who may do what
|
||||
is not a question): A-434 stands, the callers lists go from every seat contract, and tests 40, 51 and 85 are not
|
||||
checked while it holds.
|
||||
- **No line names rates on the bus**; the bus's module gives connections and consumers, not rates. A tool to build in
|
||||
the bus's module (principle 4), named in section 4 so the design says it.
|
||||
- **Decision:** fix in place, every module. View: replace the bucket watches with events (the large gap, H4).
|
||||
Watchman (16 of 23 built) and condition keeper (14 of 18): fix in place; their live builds predate milestone G. Grants
|
||||
part: the re-read through the SDK shape in H4, its move from reads to events a release of its own (H4b). Bus module and tool runner: the
|
||||
rate read and the SDK's generic state tools.
|
||||
- **The wake-up rule is a class fix:** one shared shape in mesh-sdk (watched copies of a module's own states, a pass
|
||||
only on a changed input, one deadline timer for its real deadlines, no poll), every delivery module moved onto it in
|
||||
H4, and the review refuses a timer, a poll or a full re-read in any delivery module from H1 on.
|
||||
|
||||
## 4. What the design must say before code (milestone H0)
|
||||
|
||||
The design's lines and the records carry the operator's later words only in the lead's answers, and in places not
|
||||
at all. Before any code, `hq-design-writer` writes these as design lines in this milestone's part and
|
||||
`hq-record-writer` proposes the records, in one batch read by the four reviewers by architectural domain (playbook
|
||||
02). The lead decides none of them.
|
||||
|
||||
**Questions for the operator** (each changes how the operator works or removes data; the lead's recommendation first):
|
||||
|
||||
1. **How a change across repositories lands together.** The design forms a group from pull requests' head branch
|
||||
names (G §42, §716); the operator's rule is that the mesh knows only commits on watched branches. Recommendation:
|
||||
a group is a trailer in each member commit's message (`Mesh-Group: <name>`, the name chosen by the author); the
|
||||
forge bridge reads it from the commit and the gate forms the group from it; nothing is read from a pull request.
|
||||
The alternative is no groups at all, with the order between modules left to the artifact dependency edges, which
|
||||
does not cover a seat contract change that several modules must follow at once.
|
||||
2. **Data the clean state removes:** the gate's `merges`, `owed`, `asks` and `pulls` buckets, its 833 open records,
|
||||
the indexer's stale pins and the 5 pipelines running since 2026-11-19 midday, every held or failed want, and the
|
||||
19 drop-in files. Recommendation: remove all of it; none is a record anyone reads (no tool reads what the buckets
|
||||
hold), and the delivery records of the one model start from the clean state.
|
||||
3. **Pipelines one at a time** until the operator raises it: the setting `pipelines-at-once` with default 1.
|
||||
Recommendation: yes for the clean state and the first milestones; the operator raises it when the chain has proven
|
||||
itself on about ten deliveries.
|
||||
4. **The one hand placement** of milestone H1 at the operator's terminal, one command at a time as before, after
|
||||
which no pack is run again except the ones this plan names. Recommendation: yes; it is what the operator offered.
|
||||
|
||||
**The operator's answers (2026-11-20 about 01:10 CET).** Question 2: "I don't care about old data at this moment, I want
|
||||
a working mesh again": the stale state goes. Question 3: "for my part, pipelines don't exist, or a group of commits
|
||||
form one big pipeline, but parallel pipelines sounds like a very bad idea": no two pipelines run at once, and one
|
||||
take-in is one pipeline (design 47 G §44 already says it for a group: one source revision, one pipeline per watched
|
||||
branch; the single commit is the case of one member); the setting of item 7 keeps the bound at one by its default and
|
||||
the design says serial. Question 4: "I don't mind doing hand placements": yes. Question 1: the operator's first idea was a
|
||||
build plan and a deploy plan per change (ADR 0238 §2, "one commit, one change plan", the glossary's *delivery plan*,
|
||||
deleted at release 6 of ADR 0429 and replaced by ADR 0666's pipelines per module ordered by edges, from research 086);
|
||||
what remained open was how the mesh learns which commits belong together, since ADR 0666 §13 reads a shared branch
|
||||
name through pull requests. The operator, 01:15 CET: since every version is deployed by a merge into main, an action,
|
||||
they have no objection to kicking the build-and-delivery process off by hand instead of listening to the forge's
|
||||
hooks; the lead named principle 3 (a start a person forgets is a silent non-delivery) and proposed the merge through
|
||||
the mesh as the start with the forge's event kept as the watchdog; the operator chose it (01:20 CET, "A, go
|
||||
ahead"): one call of the seat `git`'s verb `merge-pull` naming one or more pull requests is the delivery's start and
|
||||
the group; nothing reads a pull request after it; a head moved outside the mesh raises a condition and delivers
|
||||
nothing. Item 1 below is answered so; item 6 is written from it. The operator also said they would not mind a start from scratch; the lead's answer is in
|
||||
section 2 (fix in place, two parts written again) with the reason: 78 per cent of the lines are built by their contract,
|
||||
and the parts that are the earlier model are named and bounded.
|
||||
|
||||
**Design lines and records to write** (no operator decision; `hq-design-writer` and `hq-record-writer`):
|
||||
|
||||
5. The take-in by A-476, as a record: it changes ADR 0666 §6 and ends ADR 0633 §1's hold for manifest validation
|
||||
and the "pending revision"; the manifest validation becomes a pipeline step with a name, a server and a policy
|
||||
default (A-476 names none), and `manifest-refused` and the cycle refusal move with it.
|
||||
6. The forge bridge's one message for a watched branch's head moving, replacing the `merged`/`pushed` pair where
|
||||
they differ (a `pushed` message carries no base today), and the end of A-464 to A-464e, A-463 and A-490k.
|
||||
7. One take-in, one pipeline, and no two at once: the pipeline is per source revision of a watched branch, its steps per
|
||||
mover in the graph's build order, delivered in the deploy order (the operator, 2026-11-20); the setting
|
||||
`pipelines-at-once` with default 1 (principle 11), the order waiting take-ins are placed in, and that a waiting
|
||||
pipeline is not owed progress under G §12. A record, since ADR 0666 §1 and §7 speak per module.
|
||||
8. The want rule A-478 and A-478b as design lines, with the list of holds they end (§266, §268, §269, §376, A-189,
|
||||
§524) and the reshaped order wait on one machine.
|
||||
9. The wake-up rule for every delivery part (section 3.6) as a design line in design 47's main file, with how it is
|
||||
checked (the review and the integration test that starts the module whole).
|
||||
10. The small contradictions the specifications list, corrected in place: G §5's unprotected-branch refusal (removed
|
||||
by the operator, still in ADR 0666 §3), G §654 (replaced by ADR 0681 §1), A-449's `pinned`/`freed` publisher,
|
||||
test 53's `forge-made`, G §476's "one entry per module of that revision", ADR 0666 §12's three open asks (A-424),
|
||||
§386's per-module durable consumer (A-397).
|
||||
11. The builder's lines the specification found missing: a done build with no reservation is reserved by the builder
|
||||
itself (not only by a hand tool); a failed fingerprint built again keeps its reservation; a `required` step with
|
||||
nothing to run is worked out again at every pipeline, not only at the seed; a registered module whose pipeline has
|
||||
no steps is refused at registration, naming the step (test 67); and the record of the build modules' queue order
|
||||
(deliveries first, ADR 0525, or the turns the code takes on an operator's yes no record holds).
|
||||
12. The reads the status view, the watchman and the grants part make of other parts' buckets, each turned into the
|
||||
event or verb of the part that owns the data (ADR 0596), and the rate read on the seat `mesh-broker`.
|
||||
13. The read tools the second live reading found missing (one-question-one-tool): in the indexer, one revision
|
||||
narrowed by module or edge kind, a non-trunk branch's revision, the edges by kind, the difference between two
|
||||
revisions, a build order for a set of modules, the source commit a fingerprint was built from; in the assigner, a
|
||||
deploy order per machine; in the node-engine, its own build. Also the checker's and the conditions' calls of
|
||||
indexer tools no indexer serves (`indexer_read_candidates`, `indexer_read_modules`), removed with their callers.
|
||||
|
||||
## 5. The clean state, by hand once (milestone H1's delivery)
|
||||
|
||||
Milestone H1 is "the one chain": the smallest set of fixes that makes a commit on a watched branch reach a running
|
||||
module through the design's path with no hand act, in every module of the chain. It is built, reviewed and merged
|
||||
like any milestone, but its delivery is by hand, because the running system cannot carry it. The steps, in order;
|
||||
the operator runs each pack one command at a time and says "done"; the lead checks each with the tools before the
|
||||
next:
|
||||
|
||||
1. **Freeze.** No merge to any delivery repository but H1's own. The runner on novox is stopped through the service
|
||||
seat so no take-in starts a pipeline during the freeze; the assigner stays, so nothing moves.
|
||||
2. **Merge H1's set to main**, in this order, each reviewed: mesh-contracts #16 and mesh-sdk #200 (held), then
|
||||
mesh-catalog #708 and mesh-delivery #261 (held, mesh-config), mesh-tools #77 (held), and H1's own pull requests
|
||||
(indexer take-in, runner, gate, bridge, assigner, node-engine). mesh-delivery #262 is closed as superseded. The
|
||||
stopped runner starts nothing; the indexer takes the commits in and the gate follows, as the old programs still
|
||||
running during the freeze do. The new programs take every head in once, at the seed (step 5.9).
|
||||
3. **Build H1's programs from main** with the packs (the g-start phases, one per program), on shanks and novox as
|
||||
before, from main's head after step 2 so that main is what runs.
|
||||
4. **Take the stream snapshot that is the drop's rollback** (design 47 H §765) and test its restore; nothing is
|
||||
dropped yet. The drop-ins are removed and the units the node-engine writes take their place as the wants compose.
|
||||
5. **Place the programs** in the order the graph gives (derived by the reader of 00:54 CET from the package,
|
||||
toolchain and provision edges; no tool answers it yet), each step read with the tools before the next:
|
||||
1. keep the bus, the forge and the image registry running; make the bus module's have `running` (else the
|
||||
assigner's rule 8 holds the 23 bus-state modules);
|
||||
2. the packages first: `mesh-sdk`, `mesh-contracts`, `mesh-delivery-sdk` published (every Go module needs them;
|
||||
`mesh-delivery-sdk` needs its registration first, section 3.4);
|
||||
3. build with the running Go build module (it is what breaks the cycle "every Go module, the build module itself
|
||||
included, is built by a running build module"), the builder first, then the indexer, the forge bridge, the
|
||||
runner, the assigner; then the three build modules (they need the builder's package), the gate (needs the
|
||||
indexer's and the bridge's packages) and the grants part; then the node-engine;
|
||||
4. place on the control node: the indexer, the forge bridge, the gate, the forge module, mesh-config; on the build
|
||||
node the builder; on the desktop the assigner;
|
||||
5. place the node-engines: the control node, then the build node, the desktop, the laptop;
|
||||
6. place the watchman, the status view, the teller, the grants part and the hand-act log on the control node;
|
||||
the checker is not placed (it goes, section 1);
|
||||
7. after each machine, read its health, its first views, its `process-builds` against its haves, and the bus's
|
||||
consumers;
|
||||
8. **drop the stale state** (question 2's yes), now that the new programs run: every state design 47 H §764
|
||||
retires, the records, the pins, the pipelines of the earlier model, the stopped runner's queue of old
|
||||
`take-in.taken`, the held and failed wants, each through the tool H §765 names, the pack saying what it
|
||||
deleted, counted;
|
||||
9. **seed every watched branch's first source revision** with `gate_source_seed` (H §768): each branch's current
|
||||
heads, taken in with no mover, so the newest catalog revision names them; read and counted, and a bridge
|
||||
restart then raises no `head-untaken`;
|
||||
10. a machine away at this moment gets its hand placement when it is back, before anything else (H §772).
|
||||
6. **Start the runner last**, with `pipelines-at-once` at 1.
|
||||
7. **Prove it.** One single-module change (a comment in a module with lint, unit and composition steps only), merged
|
||||
to main through a merge call (`merge-pull`, design 47 H §734), followed from `take-in.taken` through `pipeline-ended` to the node-engine's `running` and the gate's
|
||||
ended record, with no hand act; then one two-module change along a dependency edge (mesh-sdk and a module that
|
||||
requires it published), merged in one merge call, the same way. Each proof read with the tools and quoted with its times.
|
||||
8. **Lift the freeze.** From here every merge is delivered by its pipeline; a hand pack is a breach the lead names.
|
||||
|
||||
## 6. The milestones after the clean state
|
||||
|
||||
Each is one release of playbook 07 (prepare by `mesh-preparer`, develop, one review, one check, delivered by its
|
||||
own pipeline), in this order, the next starting when the previous one's delivery is read on the machines:
|
||||
|
||||
| # | outcome | repositories | proof |
|
||||
|---|---|---|---|
|
||||
| H0 | the design says the one model whole (section 4) | hq, the knowledge base | the four reviewers by architectural domain approve the batch; the operator's four answers are in |
|
||||
| H1 | the one chain works with no hand act (section 5) | `mesh-delivery`, `mesh-catalog`, `mesh-host`, `mesh-tools`, `mesh-sdk`, `mesh-contracts` | the two proofs of step 7 |
|
||||
| H2 | the builder, the build modules and the registries follow the latest lines (section 3.4; versions, publish again, the floor, a step with nothing to run, a module with no registration) | mesh-delivery, mesh-catalog | a version is skipped by nothing; every registered module has a pipeline with steps |
|
||||
| H3 | the gate and the forge module carry only the one model; groups by the operator's answer; the forge module without its merge-check machinery | mesh-catalog, mesh-delivery | a group of two repositories delivers as one; every delivery record ends |
|
||||
| H4 | every delivery part wakes on its inputs alone and is steered by its tools (sections 3.6, 7): the shared wake-up shape (mesh-config's full pass per event and its reads through module tools, the indexer's re-read after every verdict, the node-engine's retry clocks, the build modules' idle pull), the view and the watchman without reads of another part's state, the SDK's generic state tools with the fill against a cap, the missing tools per module, rates on the bus | `mesh-sdk`, `mesh-delivery`, `mesh-catalog`, `mesh-host` | the bus's slow consumers and behind counts at 0 for an hour; every module's tools pass the principle-4 table |
|
||||
| H4b | the grants part says what it holds as events and reads nothing of another part's bus state (ADR 0596) | `mesh-delivery` | the grants part's own `filling` and `room` and no bucket watch in its code |
|
||||
| H5 | tests to budget and one integration test per module that starts it whole (ADR 0548); the catalog check that refuses a module whose state has no read tool | every delivery repository, mesh-catalog's check | the check reports each module's counts within budget |
|
||||
|
||||
Milestone H1 is large for one release (six repositories); it is not cut (how-work-is-done), its subtasks are split
|
||||
at the prepare, one developer per repository on the larger model for the indexer and the gate (their parts meet at
|
||||
`take-in.taken` and the source revision), the smaller model for the rest.
|
||||
|
||||
## 7. The guards, so it does not rot again
|
||||
|
||||
- **An integration test per module that starts it whole** against a real bus and store (ADR 0548), run in the one
|
||||
check per release, and the change to how a module runs carries it in the same commit.
|
||||
- **The review reads against the one model:** a sweep, a poll, a timer for another part, a comparison in place of an
|
||||
event, a read of another part's state or a per-pull-request path is a finding that fails the review.
|
||||
- **The tools table per module** (principle 4) in every pull request of a delivery module, and the catalog check of
|
||||
H5 that refuses a module without its read tool.
|
||||
- **No hand pack after the clean state.** A delivery that fails is fixed in its repository and delivered by its
|
||||
pipeline; a pack is a breach the lead names, with the one exception the operator grants in words.
|
||||
- **The test budget** per module (50 integration, 500 unit) reported by the check; a module over it shrinks with
|
||||
every change.
|
||||
- **Live answers become design lines the same day** (implement-the-design): a lead answer that patches a model
|
||||
question is a breach the reviewer reports.
|
||||
|
||||
## 8. What the plan does not do
|
||||
|
||||
- It does not merge the six held pull requests now; they merge in H1's step 2, and one (#262) is closed.
|
||||
- It does not touch the controller, the vault or the recovery module beyond what the chain needs; the recovery
|
||||
module is not placed and is a later milestone's.
|
||||
- It does not change the catalog's module set or the build nodes (novox's build agent stays paused).
|
||||
- It leaves what the surveyors could not read as named guesses, each with how to check it, in the gap tables'
|
||||
last sections; the prepare of each milestone checks them.
|
||||
|
||||
## 9. H1's develop: who builds what, and why (the lead, 2026-11-20 02:27 CET)
|
||||
|
||||
Six `mesh-developer` agents, one branch each, from the six build maps of the prepare (the lead's working folder,
|
||||
`prepare/H1-*.md`) and the lead's answers H-A-21 to H-A-62; each commits locally and cites its lines; none pushes before
|
||||
the one review (`mesh-code-reviewer`, at most three rounds).
|
||||
|
||||
| repository | branch | scope | model and reason |
|
||||
|---|---|---|---|
|
||||
| `mesh-delivery` | feat/47-H1-contracts-indexer-bridge | the seat contracts (C0 to C3, C-R, C-W), the indexer's take-in written again, the forge bridge | larger: its parts meet at `source-moved`, `take-in.taken` and the contracts every other branch starts from |
|
||||
| `mesh-delivery` | feat/47-H1-runner-assigner | the runner's queue and events, the assigner's want rule and tiers | larger: it meets the indexer at the pins and `take-in.taken`, and the node-engine at the want's form |
|
||||
| `mesh-catalog` | feat/47-H1-gate-forge | the gate's merge-call path and record, the forge module's merge call and `merge-called`, #708 onto main | larger: the gate and the forge module meet at `merge-called` and the bridge at `head-moved` |
|
||||
| `mesh-host` | feat/47-H1-node-engine | the entries asked again, the apply by rank and `apply-order`, the want by version | smaller: a leaf, its contract given |
|
||||
| `mesh-tools` | feat/47-H1-tool-runner (from #77) | the per-verb `timeout`, no `admitted` hook, the whole test | smaller: a leaf |
|
||||
| `mesh-sdk` and `mesh-contracts` | feat/47-H1-seats (from #200 and #16) | the copies, `timeout` in `seatdef`, no `Callers`, `placement`'s `build`, `apply-order`, `held-back` gone | smaller: contracts and copies, published first |
|
||||
|
||||
The order between branches is the prepare's dependency table: contracts and copies first (published as the next
|
||||
mesh-sdk and mesh-contracts versions at the clean state's step 5.2), then the modules; the runner-and-assigner branch
|
||||
rebases onto the contracts commits before the review.
|
||||
@@ -0,0 +1,570 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H
|
||||
updated: 2026-11-20
|
||||
decisions:
|
||||
- "ADR 0682"
|
||||
---
|
||||
# 47, milestone H — the lead's answers
|
||||
|
||||
The lead's one-line answers to the questions the design writer and the builders could not answer from the records,
|
||||
each tested against the principles (`00-META/principles.md`) and naming the one that settles it (implement-the-design).
|
||||
A question no principle settles goes to the operator or to a record; it is marked so here.
|
||||
|
||||
## From the design writer (2026-11-20 01:36 CET)
|
||||
|
||||
- **H-A-1 A member refused after every member was judged** (a forge failure between the judgement and the last merge):
|
||||
the forge module says the members that landed, marks the call `refused` and raises the finding `merge-partial`;
|
||||
the landed members are taken in as one source revision, so what landed is delivered and what did not is loud.
|
||||
Principle 3.
|
||||
- **H-A-2 The delivery order once the want holds for nothing**: the runner's `pipeline-ended` carries its movers in
|
||||
ADR 0666 §14's delivery order, and the node-engine applies one pipeline's wants on its machine in that order
|
||||
(A-478b's order on one machine). The order travels in the event; no part reads another part's state for it.
|
||||
Principles 1 and 9.
|
||||
- **H-A-3 A `required` step whose run ends "nothing to run"** counts as passed for the want, as `bypass` does: a hold
|
||||
with nothing behind it protects nothing. Principle 7. A clause of ADR 0682 says it (asked of the record writer, 01:38).
|
||||
- **H-A-4 Reads whose owner says no event today** (the provisioner's provisions, the vault's bus accounts and node
|
||||
logins, the enrolment module's enrolments, the grants part's user list): each owner says one change event and the
|
||||
readers consume it, in milestone H4b; until then the read stands and is named a leftover in the gap table.
|
||||
Principle 1 (ADR 0596).
|
||||
- **H-A-5 A revert against the whole want rule**: a return to an earlier build stays one value in the placement, read
|
||||
by the assigner before the rule, the one exception; ADR 0682's review raised it and the record says it. Principle 4.
|
||||
- **H-A-6 The seat that serves `validate`**: the seat that runs the composition step, which G §22 names `mesh-wants`;
|
||||
ADR 0682 §4's "mesh-module-assigner" is corrected to that seat (asked of the record writer, 01:38). Principle 9.
|
||||
- **H-A-7 The main file's size** (258 KB against the 80 KB bound of playbook 02): the reshaping of design 47's main
|
||||
file into its milestones' parts is a change of its own after H0, not folded into this one (rules-are-weighed: the
|
||||
bound protects a reader, and the plan's reader has the three H part files; a 180 KB move in the same pull request
|
||||
would hide the lines under review). Said to the operator at 01:38.
|
||||
- **H-A-8 The build modules' queue order**: deliveries first (ADR 0525 §4), as §753 writes; the operator's yes to the
|
||||
turns of 2026-11-15 is in no record, so the record holds. If H2's prepare finds it, the record gets an insight.
|
||||
|
||||
## From the review by architectural domain (2026-11-20 01:40 to 01:44 CET; four reviewers, one round)
|
||||
|
||||
- **H-A-9 How the apply order reaches the node-engine**: the want carries its `pipeline` and its `rank` in that
|
||||
pipeline's delivery order, written by the assigner from `pipeline-ended`; the node-engine applies a pipeline's wants
|
||||
on its machine by rank and consumes no event of the runner. The apply-order read tool is the node-engine's.
|
||||
Principles 9 and 12.
|
||||
- **H-A-10 Order across machines** (ADR 0666 §14's "delivered before" edge between machines): the order lives inside the
|
||||
one pipeline, never as a hold of a want on another delivery (A-478 b: "the order between modules moves into the
|
||||
pipeline"): the assigner writes one pipeline's wants tier by tier in §14's order, a later tier once the earlier
|
||||
movers report `running` on their machines, with a bound per tier (a setting) whose end ends the delivery record `failed` with the finding `tier-late`,
|
||||
the pipeline's own outcome staying what its steps said; the
|
||||
composition step composed the whole graph before any want was written. ADR 0682 says it (the record writer, 01:50).
|
||||
Principles 3 and 7.
|
||||
- **H-A-11 Publishing an event family stays the producer's**: every account may call every verb (ADR 0682), but a
|
||||
module publishes only the events its manifest declares, as ADR 0666 §21 has it for a step's result; the mechanism
|
||||
stays whole, who is on which side is not asked (who-may-is-not-the-operators-question). An enrolling node's account
|
||||
keeps its own grant. Principle 6.
|
||||
- **H-A-12 The indexer's consumer and a blocked `source-moved`**: one durable consumer per watched branch; a
|
||||
`source-moved` the indexer cannot take in (the store full) is held, unacknowledged, until the bus module's `room`
|
||||
wakes it, never on the ack timer; a hand tool skips it with `why`, written in the hand-act log. `take-in.pending`,
|
||||
`take-in-waits` and `indexer_pending` stay (ADR 0633 §5). Principles 1, 3 and 4.
|
||||
- **H-A-13 A source revision written once per call**: the gate keys its write by the call id with compare-and-set, so a
|
||||
redelivered `merge-called` numbers nothing twice. Principle 3.
|
||||
- **H-A-14 The waiting queue of the runner**: ordered by the runner's own counter at the moment it writes the pipeline;
|
||||
placed at the runner's start from its own state and on every end, a cancel and a set-aside included; a finding when
|
||||
pipelines wait while none runs; a pipeline waiting on the operator's `approval` step does not count against
|
||||
`pipelines-at-once` and re-enters the queue first when approved; the queue's cap is a setting. Principles 3 and 11.
|
||||
- **H-A-15 The clean state's seams** (plan section 5): before the runner starts, every watched branch's current head is
|
||||
its first source revision with no movers (§745) and the newest catalog revision names it, read and counted; the state
|
||||
of the earlier model is dropped after the new programs run (after step 5.6), each item through the tool named for it,
|
||||
the backup snapshot being the rollback; every new durable consumer starts at the newest message and refuses an event
|
||||
of the old form with a journal line; the stopped runner's queue of old `take-in.taken` goes with the state; a machine
|
||||
away at the clean state gets its hand placement when it is back, before anything else; the forge's branch protections
|
||||
drop the required statuses `mesh/merge-gate` and `mesh/repo-check` in H1. Principles 2 and 3.
|
||||
- **H-A-16 Where H1's integration tests run before its merge**: once, locally against an embedded bus, said in each
|
||||
pull request (how-work-is-done allows it); the chain's live proof (plan step 7) is H1's check; from H1 on the
|
||||
pipeline makes the check. Rules-are-weighed, said.
|
||||
- **H-A-17 The whole tests**: one per module, in that module's repository; tests 110, 112 and 113 are split per module
|
||||
and the chain stays the live proof; the design gives the count per module per release and names the retired tests
|
||||
that free room (the budget is per module, 50 and 500).
|
||||
- **H-A-18 The forge module's call**: a call key written before the first merge and said again at start; `refused` in
|
||||
the event's body; `merge-partial` keyed by the call, cleared when a later call lands the refused members or by a
|
||||
hand clear; tools `forge_calls` and a say-again; `by` recorded beside the caller's bus account; `failed-steps` is
|
||||
written from the runner's `step-ended` (mover, commit, fingerprint). Principles 3 and 4.
|
||||
- **H-A-19 Small forms**: no pin for a take-in with no mover; a call with two members on one branch names the last
|
||||
member's commit in call order; `package-published` carries the source revision that published and its pipeline pins
|
||||
it and belongs to that merge call's delivery record; `pipeline-ended` carries per mover the released version and
|
||||
fingerprint and the delivery order, on the subject `...pipeline-ended.<branch>.<source revision>`; `pipeline-failed`
|
||||
is one finding per failing mover, cleared by that module's later passed pipeline; every fixed value (30 days, 64 MiB,
|
||||
60 minutes, 10 minutes) is a setting with that default; §765 drops every state §764 retires. Principles 7 and 11.
|
||||
- **H-A-20 The main file's size**, a must for three reviewers: the lead's bending of the bound (H-A-7) is said to the
|
||||
operator at 01:48 with the question whether the reshape follows H0 as its own change; until the answer the bound
|
||||
stands bent, said.
|
||||
|
||||
## From H1's prepare (2026-11-20 01:55 to 02:20 CET; six build maps, 92 questions merged in the lead's working folder)
|
||||
|
||||
Each answer names the item of the merged list (Q1 to Q92), then the principle. "Both" means the preparers agreed.
|
||||
Where two preparers disagreed, the chosen one is named.
|
||||
|
||||
- **H-A-21 (Q1)** `merge-pull` answers once, at the call's end, naming `call` and each member's outcome. P1.
|
||||
- **H-A-22 (Q2)** Its caller `id` goes (the call names it); an already-merged member is refused `already-merged` with
|
||||
its commit; the answer is `{repository, number, state, commit|why}` per member; `protected` goes; `calls` is declared
|
||||
in the seat definition. P3, P7.
|
||||
- **H-A-23 (Q3)** A kept stream's age and cap are its definition's `keep` (30 days, 64 MiB as defaults there); the
|
||||
word "setting" is dropped from those lines. H-A-19 is read so: a value stated once outside code. P11.
|
||||
- **H-A-24 (Q4)** A call is 16 lowercase hex characters, one subject token; `hand`, `seed`, `by` and the time live in the
|
||||
record's trace (sdk). P8.
|
||||
- **H-A-25 (Q5)** `record-opened` and `record-ended` carry `branch`, `source`, `call`; `milestone` stays as
|
||||
`<branch>.<source>` for the teller and the watchman (cat); the verb `source` answers `call`. P7.
|
||||
- **H-A-26 (Q6)** `source-moved`'s wildcard has two tokens; its body as §737 with `v`; every decoding reader is named
|
||||
with its change in its repository's map. P7.
|
||||
- **H-A-27 (Q7)** `head-moved` on `forge.<owner>.<name>.<escaped branch>.head-moved` under the module stream prefix; its
|
||||
form in `forgemsg`, series 0.1. P8.
|
||||
- **H-A-28 (Q8)** Everything of the earlier model leaves in H1: the gate's states and `approval-carried`, `groups` and the
|
||||
group model, the forge module's merge-check machinery, the knowledge base's `groups` invoke (cat); `heads` is declared
|
||||
in the seat definition. One model, no second one left running. P7; ADR 0682 §2.
|
||||
- **H-A-29 (Q9)** §738's delivery record is built in H1: the gate consumes the new `take-in.taken` for entries and
|
||||
outcome and reads a record by its key `<branch>.<source>`, never every record. P3.
|
||||
- **H-A-30 (Q10)** The grants part makes one durable consumer per registered watched branch from the registrations
|
||||
(`MaxAckPending` 1), as it makes every consumer today; mesh-sdk binds a consumer by the name its caller gives;
|
||||
`source-moved` gets a kept stream (sdk, with ib's stream). P7 over P12 here: the maker of consumers exists, and a
|
||||
second maker would be a second mechanism.
|
||||
- **H-A-31 (Q11)** `take-in.taken` and `take-in.pending` carry only the lines' fields, plus `by` and `why` for a hand act;
|
||||
readers pair by `<branch>.<source>`. P7.
|
||||
- **H-A-32 (Q12)** The catalog revision's number is the source's; its name `<escaped branch>.<source>` for every branch,
|
||||
the trunk included; written once by read-before-write under the branch's one-at-a-time consumer. P3.
|
||||
- **H-A-33 (Q13)** The source value carries `source` and `call`; the next number is the branch's newest plus one; a
|
||||
`merge-called` whose call the newest already carries writes nothing. P3 (with H-A-13).
|
||||
- **H-A-34 (Q14)** The assigner builds the validator from the change's heads on `node-build-go` as it builds the
|
||||
composer, its input on `mesh-wants`' `input`; `RefusedCycle` moves to `mesh-delivery-sdk/graph` first; the program's
|
||||
source stays where it is until a later cleanup (ra). P9; ADR 0682 §5.
|
||||
- **H-A-35 (Q15)** A pipeline's kept value holds `movers` as `{module, commit, fingerprint, repository, tier}`; each step
|
||||
result names its module; `list` filters by a mover; the runner's contract lands first. P7, P10.
|
||||
- **H-A-36 (Q16)** A runner state `queue` holds `queue.next` and one key per waiting pipeline; the pipeline's outcome
|
||||
value is `waiting`; an over-cap start is acknowledged and kept there, never left unacknowledged. P1, P3.
|
||||
- **H-A-37 (Q17)** A want keeps `fp`, `hold` and `words`; `parts`, `rule`, `newest`, `kept-on` and `composed` go; `rank`
|
||||
is an integer from 1, absent for a placement's `build` and for the node's own want (host's set, ra's drops). P7;
|
||||
ADR 0682 §8 ("never digests" reads `fp` as the build's name).
|
||||
- **H-A-38 (Q18)** A candidate's `added` names a version alone; the shadow resolves it as it resolved parts; `parts`
|
||||
leaves the assigner seat's contract. P7.
|
||||
- **H-A-39 (Q19)** `ModulePlacement` gains `build` (one row per branch and build), a fingerprint; the assigner wants the
|
||||
version released at it. P7 (with H-A-5).
|
||||
- **H-A-40 (Q20)** The next tier is released on `running` matched by the mover's fingerprint from `pipeline-ended`;
|
||||
`running` gains no version in H1 (ra). P7.
|
||||
- **H-A-41 (Q21)** The callers type and functions, every holder's list, the step runner's asker judgement and the tool
|
||||
runner's `admitted` hook go in H1, in one group; the vault's enrolment caller stays; a step run carries `asker`. P6;
|
||||
ADR 0682 §10.
|
||||
- **H-A-42 (Q22)** H1 carries a mesh-sdk change beside #200: the new byte-equal copies of the seat definitions and the
|
||||
checker's copy dropped, published first as the next version; §762's "mesh-sdk in H4" is read as the wake shape alone
|
||||
and corrected in place in this branch. P5.
|
||||
- **H-A-43 (Q23, Q24)** The per-verb `timeout` is built in H1 (a merge call of several members is cut at a fixed 30 s
|
||||
otherwise): the field in the seat definition and its schema, whole seconds 1 to 600, others refused; `merge-pull`
|
||||
names 120; the tool runner's own default is the setting `call-timeout`, 30 s; every caller and the serving runner wait
|
||||
it; module processes through mesh-sdk. §760's "H4" is corrected in place. P3, P11.
|
||||
- **H-A-44 (Q25)** Writers the maps did not name: the watchman's and the view's take-in readers, `sourcebranches` and
|
||||
`meshcatalogclient` are the indexer-and-bridge developer's; the teller, the knowledge base's and the issue tracker's
|
||||
readers are the gate-and-forge developer's; mesh-sdk's copies are the sdk developer's; the knowledge base reads
|
||||
`pipeline-ended` in place of `group-ended`. The lead's order of work.
|
||||
- **H-A-45 (Q26)** The word is `want:version`, a constant of the node-engine seat contract, stated in `manifest-reads`
|
||||
and read from `manifest-reads-changed` alone; the assigner holds any node not stating it (host). P8, P1.
|
||||
- **H-A-46 (Q27)** The apply order is a read verb `apply-order` on the seat `node-engine` (contract and sdk copy first),
|
||||
one row per unapplied changed want: `module, pipeline, rank, position, why, waits`; H-A-9's "read tool" is read so.
|
||||
P4, P9.
|
||||
- **H-A-47 (Q28 to Q36)** A member whose base is no watched branch is refused at judging, naming the base (P3). The
|
||||
call's value gains `said` (P3). A call past retention is deleted on each new call's write, oldest first (P1). A merge
|
||||
call with no caller account the tool runner proved is refused, saying why (P3). FORGE-1 builds `step-unread`; the
|
||||
clean state reads `failed-steps` after the first failed step; a one-event read tool is H4's (P3, P4). A session reads
|
||||
its record by `call` through the gate's verbs after the answer, then waits on `pipeline-ended`, re-reading (P1).
|
||||
"The tool runner's `merge-pull` tool" reads as the seat `git`'s definition and its sdk copy (P8). The seed opens no
|
||||
record (P7). `gate_source_start` and `gate_source_again` stay, the first writing through the seed's path (P4).
|
||||
- **H-A-48 (Q37 to Q43)** Every indexer and bridge part no line names (`Src` stamps, the builder-log index,
|
||||
`TakeInMerge`, the own-build hold, previews, `taken`, the `pull` and `open` messages, the bridge's finding writer) goes
|
||||
in H1 and is added to §764's lists (P7). `pins-stated`, `heads-replaced`, `pinned`, `freed` and the gate's pin
|
||||
operations go; the indexer pins in its own state (P7). The gate's stalled conditions go, the watchman's `record-open`
|
||||
being the one signal; `untaken-bound` runs on the gate's one timer; the start loops are waits for the bus, said (P7;
|
||||
ADR 0682 §11). `transition` leaves `emits` (P7). A record's member is `<repository>@<number>` for a call and
|
||||
`<repository>@<commit 12>` for a hand take (P8). The bridge's `heads` gets a read tool, no say-again (P4).
|
||||
`git.branch` becomes a kept call that waits on the holder's return, no redelivery timer (P1).
|
||||
- **H-A-49 (Q44, Q45)** Every reader of `manifest-accepted` and `manifest-refused` (the builder's floor, the watchman,
|
||||
mesh-config on #708, the tool runner's ledgers, membership) reads the mover's entry on `take-in.taken`; #708 moves to
|
||||
`catalog-revision` before it merges. Only a take-in keeps a catalog revision; a toolchain change reaches pipelines
|
||||
through `toolchain-agreed`. P1, P9; ADR 0682 §4.
|
||||
- **H-A-50 (Q46)** The event that wakes a held take-in is the indexer's own `room` on the seat `mesh-catalog` (the store
|
||||
is the indexer's); H-A-12 is read so. P12.
|
||||
- **H-A-51 (Q47 to Q51)** One `validate` run per take-in revision, every mover's step reading it; the runner's and
|
||||
`mesh-wants`' contracts add `validate` (P7). Every step of a mover waits for its dependency's publish (P3; ADR 0682
|
||||
§6). Tiers come from edge kinds 2, 4, 5 and 6; a cycle among movers is one tier, said in the journal (P3; ADR 0666
|
||||
§14). `widens` is per mover in its entry (P10). Lines already built (`branch` and `source` on `package-published`,
|
||||
`pipeline` on step events) are read as built (P7).
|
||||
- **H-A-52 (Q52 to Q59)** The runner consumes `version-released` in H1 and writes the version into the mover's entry
|
||||
(P1). A run on request stays per member, in the same queue (ADR 0682 §7). A hand `start` keys the newest revision's
|
||||
`<branch>.<source>` with that module as its one mover, refused when the key exists (P4). The runner asks `outdated`
|
||||
no more; kind-1 dependents come from the edges it holds (P1; ADR 0682 §6). A waiting pipeline says
|
||||
`pipeline-started` at its write, so its revision is pinned while it waits (P3). Its wait is said on
|
||||
`…wait-held.<branch>.<source>`; the enums gain `pipeline` and `pipelines-at-once` (P8). `pipelines-stalled` and
|
||||
`queue-full` have scope `delivery`, one each for the mesh; `queue-full` clears when the over-cap start is taken (P3).
|
||||
- **H-A-53 (Q61 to Q64)** One `approval` step per mover whose policy names it (P10). `runner_place` is backed by a verb
|
||||
`place` (`pipeline`, `why`) on the runner's seat (P4). A mover left in an older pipeline whose dependency was
|
||||
superseded out builds against the newest published package, said in its step's why (P3; ADR 0682 §7). "A set-aside"
|
||||
reads as `pipeline-ended` and `cancel` alone (P7).
|
||||
- **H-A-54 (Q65)** The indexer's §749 pins land with the runner's R3 and are reviewed together. The lead's order.
|
||||
- **H-A-55 (Q66, Q67)** Rule 2, rule 7, the network hold and A-428's exceptions end; the record-policy yes and the
|
||||
outside wait stay as the asker's. `assigner_release` stays for puts and outside waits, losing its acting, order and
|
||||
delivery steps. P7, P4; ADR 0682 §9.
|
||||
- **H-A-56 (Q69, Q70)** Tier progress is the assigner's state `written`, key `pipeline.<branch>.<source>` with
|
||||
`{tier, since, movers}`, one deadline timer; a tier counts placed movers only; `wanted` gains `pipeline`; `tier-late`
|
||||
clears when the late movers run or a later pipeline passes; the end is said on `…wanted.<branch>.<source>` with
|
||||
`outcome`. P4, P7, P1, P3.
|
||||
- **H-A-57 (Q71 to Q74)** `acts` stays for the builder's build seats; `bound`, `DefaultBound`, `Wait` and the other
|
||||
acting entries go (P7). The seat `mesh-delivery-checker` goes with every copy and its `check` and `recheck` kinds
|
||||
(P7). The operator channel's limit, `held-back` and `ask-again` go in H1 with their state, verb, sdk reads and the
|
||||
tool runner's row (P7; ADR 0682 §14). `indexer_unpin` is renamed to take the pin's key; one tool (P7).
|
||||
- **H-A-58 (Q75 to Q78)** "Every durable starts at the newest and refuses the old form" holds for consumers of event
|
||||
streams, not for watches of last-per-subject state; the refusal is in the shared follower; old means a
|
||||
`take-in.taken` without `call` or a pipeline value without `movers`; the gate's and the forge module's durables are
|
||||
dropped at the clean state's drop step, named there (P2, P3). The new `cancel` reads no old pipelines: they are
|
||||
dropped (ADR 0682 §12). `assigner_want_drop` deletes the key, written in the hand-act log; the next pass writes the
|
||||
new form (P4). A run's candidate graph is dropped on the `pipeline-ended` of its last member (P1).
|
||||
- **H-A-59 (Q79 to Q84)** `pipeline-failed` has scope `delivery`, its owner as today (P8). A higher rank waits for a
|
||||
lower rank of its pipeline on this machine alone, said as `wait-held` step `placing` (P3; ADR 0682 §9). When two
|
||||
pipelines' wants changed at once, the older source first (ADR 0682 §7). "Its own want last" is the node-engine's
|
||||
module; the node's composition stays first (P8). The bus module and the backup holder are found by claim
|
||||
(`mesh-broker`, `node-backup`) from the entries the composer holds (P9). A revert is a want naming a fingerprint this
|
||||
node ran before, read from the applied record (P1, with H-A-5).
|
||||
- **H-A-60 (Q85 to Q88)** The entry asked again: on `catalog-revision` and on the link's reopening, at most `entry-asks`
|
||||
times (default 5), then `unanswered` and the finding `entry-unanswered`; built in mesh-delivery's `meshcatalogclient`
|
||||
(P3, P11). The node-engine's read of every node's record stays: it feeds the composer; the plan's section 3.5 and gap
|
||||
table E row 67 are corrected (P9). Its wait on `restic.backed-up` by name is out of H1, a leftover in the gap table
|
||||
(P9). Existing timers, polls and whole reads in files H1 touches stay for H4 (§762); new runner code reads only its
|
||||
`queue` keys (ADR 0682 §11, P1).
|
||||
- **H-A-61 (Q89 to Q92)** mesh-contracts' five modules are registered at the clean state's step 5.2 (P5). The whole
|
||||
tests: the forge module's is a Go integration test running its bundle; the tool runner's `main` gains an entry; the
|
||||
request-count assertion is H4's (with H-A-17). #708's description drops the words "config candidates" before it
|
||||
merges (P8). Tests that use the checker's state as a fixture rename it to a state that stays (P7).
|
||||
- **H-A-62 (Q68, for the operator)** Until H2, a version is released only for a registration's first watched branch, so
|
||||
a placement on another branch gets no want and is said. Recommendation: accept for H1; H2 releases per branch. Asked
|
||||
of the operator 2026-11-20 02:25 CET.
|
||||
|
||||
## From H1's develop (2026-11-20 from 02:27 CET)
|
||||
|
||||
- **H-A-63 (seats developer, 02:31)** The `apply-order` row's `waits` is a list of module names the want waits on
|
||||
(strings), empty when it waits for nothing; `why` stays the one sentence. P8 (one form, named by the rows' own
|
||||
modules).
|
||||
- **H-A-64 (seats developer, 02:33)** The word `want:version` is a generated constant of the node-engine seat contract:
|
||||
the seat generator's identifier function splits on `:` as it splits on its other separators (one more rune, no
|
||||
existing output changes; a subtask of the contracts-indexer-bridge developer in `mesh-delivery-sdk/seatgen`), and the
|
||||
node-engine definition gains the enum `ManifestReadWord` with that value. P9 (every reader takes it from the generated
|
||||
package), P7.
|
||||
- **H-A-65 (tool runner developer, 02:33)** How the setting `call-timeout` reaches the tool runner: not in H1. The
|
||||
node-engine composes the tool runner's unit as a special case (two environment variables, no config file), so the
|
||||
setting's path is the generic manifest `config` with its file resource, built in H4 when that special case goes
|
||||
(principle 7, no module special-cased in shared code). In H1 the runner's own bound is a constant of 30 seconds and the
|
||||
per-verb `timeout` carries every real need (`merge-pull` 120); the manifest declares no setting it does not read
|
||||
(principle 3). Rules-are-weighed: principle 11 bent for one release, said to the operator.
|
||||
- **H-A-66 (seats developer, 02:36)** H-A-41's set is the whole of it: mesh-sdk's `go/callers.go` (`stdio.Callers`,
|
||||
`VerbCallers`, `ParseVerbCallers`, `ConfiguredVerbCallers`, `HoldVerbCallers`), the `callers` parameter of
|
||||
`seatlist.NewPart`, `Tools` and `Refusal`, of `views.FirstViewTool`, `ParseCallers`, `Refusal` and `CallersEnv`, and
|
||||
`approval.ViewCallersPrefix` go in H1, as the sdk developer's subtask `sdk-holder-callers-gone`; every gated first-view
|
||||
tool and seat-list tool is open to every caller. The holders' call sites in mesh-delivery and mesh-catalog are their
|
||||
developers' subtasks, from the signatures the sdk developer reports (the lead relays them). P6, P7 (code that gates
|
||||
callers protects nothing once every account may call every verb); ADR 0682 §10.
|
||||
- **H-A-67 (node-engine developer, 02:37)** The node-engine seat's `Wait.step` enum gains `placing` (the seats developer
|
||||
in mesh-contracts, with the sdk copy); the hold of a higher rank behind a lower one is said with it. P8.
|
||||
- **H-A-68 (node-engine developer, 02:37)** A revert is a want with no `pipeline` and no `rank` (a placement's `build`,
|
||||
H-A-37) naming a fingerprint other than the one running; the applied record keeps no history for it. "Read from the
|
||||
applied record" in H-A-59 reads so: the running fingerprint is what it compares with. P7.
|
||||
- **H-A-69 (seats developer, 02:38)** How the approval gate knows a module's own first-view tool once the callers env
|
||||
marker goes: by the tool's name, the forms `<module>_first_views` and `<module>_first_view_again` that mesh-sdk's views
|
||||
already serve; no environment marker and no tool runner change. P7 (what exists over a new side channel).
|
||||
- **H-A-70 (contracts-indexer-bridge developer, 02:40)** `acts` stays everywhere as a declaration: it is what the
|
||||
catalog graph's kind-5 edge ("B has acted for A") is built from, and H-A-51 orders the pipeline's tiers by that edge.
|
||||
So the `acts` entries of the seats mesh-catalog (take-in, validate), mesh-wants (place) and the build seats stay, as do
|
||||
`ActingRule` and `CatalogEntry.acts`; what goes is the hold and its wait: `bound` on the build seats' `acts` and every
|
||||
reader that waits or holds on an acting part (the builder's bound reader and its re-asks, the assigner's acting holds,
|
||||
the runner's acting waits), each in its own developer's subtask citing this answer (builder and assigner readers:
|
||||
the runner-and-assigner developer; the pipeline's: the same; the indexer's edge builders stay unchanged). P7 (the
|
||||
declaration serves the order; only the hold had no need left); ADR 0682 §9.
|
||||
- **H-A-71 (contracts-indexer-bridge developer, 02:49)** (1) The seat mesh-delivery's state `owed` stays in H1: the
|
||||
bridge's owed path and the client's check read it (P7 removes only what nothing reads); its stale keys of the earlier
|
||||
model go at the clean state's drop step (ADR 0682 §12), and §764's "owed (the old bucket)" reads so. (2) The call's
|
||||
kept member gains `branch`, so the forge module can say `merge-called` again after a stop (P3). (3) The step runner's
|
||||
asker judgement in `mesh-delivery-sdk/steprun` (H-A-41) is the contracts-indexer-bridge developer's subtask, since
|
||||
that package is mesh-delivery's shared code and it already writes there; the three build modules' wiring stays
|
||||
mesh-catalog's BUILD-1. The lead's order of work.
|
||||
- **H-A-72 (contracts-indexer-bridge developer, 02:53; the runner's and mesh-wants' seats)** (1) The pipeline value:
|
||||
`group` goes; `module`, `commit`, `fingerprint`, `repository`, `version`, `widens`, `tests` and `over-budget` move into
|
||||
each mover; `run`, `published`, `unlogged` and `end-count` stay on the pipeline (P7). (2) The runner's state `queue`:
|
||||
`queue.next` and one key `waiting.<sequence, 20 digits>` with value `{pipeline}`, so the lowest sequence is read by key
|
||||
order (P1). (3) `wait-held` and `wait-ended` move to the one subject form `<branch>.<source>`, the body naming the
|
||||
module for a step's wait (P8). (4) The step events and `run-started` keep `<module>.<branch>.<commit>`, the
|
||||
commit-or-group token becoming `<commit>` (P8). (5) `pipeline-ended` carries per mover its step results as a list of
|
||||
step results, each naming its module (H-A-35, P10). (6) The tier end is a second event of the seat mesh-wants,
|
||||
`pipeline-wanted.<branch>.<source>` with `outcome`; `wanted` stays per node and module (P8); H-A-56 reads so.
|
||||
- **H-A-73 (runner-and-assigner developer, 02:55; the map's Q-32)** Where §772's "held, awaits its hand placement" is
|
||||
said: in the want's own `hold` field (H-A-37 keeps `hold` and `words`), with the word `awaits-hand-placement`, written
|
||||
by the assigner for a node whose node-engine does not state `want:version`; no second event. P7.
|
||||
- **A note on placement (02:55):** a developer's `go.work` per module pointing at the H1 worktrees is the build map's
|
||||
placement, whatever small script wrote it; it is not a placement of the developer's own. The lead's reading.
|
||||
- **H-A-74 (runner-and-assigner developer, 02:59)** H-A-70's builder part is only a reader of the build seats' `bound`
|
||||
field, now absent from the contracts; the builder has none, so nothing of the builder changes in H1. G §672's
|
||||
toolchain wait (the state `waits`, its events, tools and setting) is a build's wait for its toolchain, not a want's
|
||||
hold on another delivery, and stays: §764 names no builder item, and the builder's lines are H2's. P7; ADR 0682 §9.
|
||||
- **H-A-75 (contracts-indexer-bridge developer, 03:02; the seat mesh-wants)** (1) `pipeline-wanted.<branch>.<source>` is
|
||||
said once per pipeline, at its end: `outcome` is `running` when every tier's movers run (the node-engine seat's word,
|
||||
P8) and `tier-late` when a tier passed its bound, the body `{v, pipeline, branch, source, outcome}` and, for
|
||||
`tier-late`, the movers and machines not running. (2) H-A-37's drop of `composed` is the module want's alone; the
|
||||
node's own want `want.<node>.node` `{composed, words, self}` is unchanged, and `rank` is absent from it. P7.
|
||||
- **H-A-76 (gate-and-forge developer, 03:04)** (1) `gate_source_again` says `source-moved` again with the `heads` the
|
||||
source value keeps (every watched repository's head at that source) and `start` false; the indexer finds the movers
|
||||
from the fingerprints, not from `heads` (A-476a). P7. (2) The clean state drops the source bucket (plan step 5.8)
|
||||
before the seed (5.9); the seed numbers from 1 on an empty bucket and refuses to run while a key of the earlier form
|
||||
exists, naming it, so a missed drop is loud and nothing is overwritten. P2, P3; ADR 0682 §12.
|
||||
- **H-A-77 (node-engine developer, 03:08)** With `kept-on` gone from the want (H-A-37), nothing names the build node that
|
||||
keeps a kept build, so the node-engine fetches every artifact from the artifact store; G §526's fetch through a build
|
||||
node's `kept-artifact` has no input left and retires in H1 (added to what retires). P7 (a want names a version; the
|
||||
store answers for it).
|
||||
- **H-A-78 (contracts-indexer-bridge developer, 03:10)** (1) A want counts as applied when the have's fingerprint is
|
||||
the want's (ADR 0682 §8 reads `fp` as the build's name); `motion.Want.Composed` goes from mesh-sdk (the seats
|
||||
developer's subtask), the view passes the fingerprint. P7. (2) The view's source readers, the watchman's source-moved,
|
||||
manifest-accepted and manifest-refused readers, and the grants part's readers of the removed caller invokers in
|
||||
mesh-sdk are the contracts-indexer-bridge developer's subtasks after B4, with the watchman's acting-part-late (H-A-44
|
||||
gives them the view's and watchman's readers; the grants part is mesh-delivery's shared code). The lead's order of work.
|
||||
- **H-A-79 (indexer developer, 03:13)** With the validation gone from the take-in (§745, ADR 0682 §4): the state
|
||||
`verdicts` leaves the seat mesh-catalog's contract (a small commit C1b by the contracts-indexer-bridge developer, the
|
||||
seat's one writer) and the indexer with its tools `verdicts` and `indexer_verdicts`; the grants part's invoke of
|
||||
`verdicts` and the watchman's invoke of `indexer_verdicts` go from their manifests (the contracts-indexer-bridge
|
||||
developer's readers subtasks, with H-A-49: what they need they read from the mover's entry on `take-in.taken`). The
|
||||
`oldsections` count and `indexer_old_sections` stay as they are: the validator still reads the foundation list there
|
||||
(ADR 0619 §3), no line moves it in H1. P7; ADR 0682 §4.
|
||||
- **H-A-80 (indexer developer, 03:14)** The indexer's tool `indexer_consumer` goes with the state `consumers` no ledger
|
||||
writes any more (P7). A run's ended modules are read from `movers` (C-R), as the developer did. A developer who stops
|
||||
with work in the tree commits it as "in progress: <subtask>" so the next developer starts from a commit, never from a
|
||||
dirty worktree (the lead's order of work).
|
||||
- **H-A-81 (gate-and-forge developer, 03:15)** `head-untaken` (scope delivery, id `<repository>.<branch>`): severity
|
||||
warning, resolver operator (only `gate_head_take` delivers it, §742), no owner: nothing runs wrong, something is not
|
||||
delivered. `merge-partial` (§767, keyed by the call): severity urgent, resolver operator: the repositories stand
|
||||
half-merged until the refused members land or the call is cleared. P3.
|
||||
- **H-A-82 (indexer developer, 03:16)** With `version-delivered` retired (§764, C-W), the indexer reads nothing in its
|
||||
place: the fill of delivered versions into the graph's edges (versions_edges, versions_fill_edges) served the
|
||||
assigner's holds, which are gone; the kind-2 edge stays as a declaration (H-A-51's tiers), its "delivered" fact is
|
||||
nobody's to keep. The indexer's consume of `mesh-wants.version-delivered` goes from its manifest. P7; ADR 0682 §9.
|
||||
- **H-A-83 (runner developer, 03:19)** (1) A run on request is one pipeline per run with the named commits' modules as
|
||||
its movers (one take-in, one pipeline, ADR 0682 §6; the run delivers nothing), keyed `<branch>.run.<run id>` in the
|
||||
runner's state `pipelines`: the seat gains that key form (a small commit C-R2 by the contracts-indexer-bridge
|
||||
developer); H-A-52's "per member" is corrected to this. P8. (2) Inside a pipeline, a mover's build waits on a kind-1
|
||||
edge for the From mover's `package-published`, and on a kind-3 edge (a build module, an image base, which publishes no
|
||||
package) for the From mover's build step ending passed, which the runner hears as its own step end; toolchain edges
|
||||
first. P3, P7.
|
||||
- **H-A-84 (runner developer, 03:20)** A mover's heard dependencies are kept on the mover: a list `published` of the
|
||||
artifact references whose `package-published` (and, for a kind-3 edge, whose build step's passed end) was heard at
|
||||
that pipeline's branch and source, written with the pipeline by compare-and-set, so the wait survives a restart (a
|
||||
C-R2 field, the contracts developer's). P3, P1.
|
||||
- **H-A-85 (contracts-indexer-bridge developer, 03:21)** (1) The bridge's read tool of its state `heads` is
|
||||
`bridge_heads`, in the bridge's tools, answering the state's keys with each head, read-only (H-A-48). P4. (2) A run's
|
||||
pipeline puts in `source` the newest source revision of its branch at the run's start (what the run is checked
|
||||
against), its key being `<branch>.run.<run>`. P7.
|
||||
- **H-A-86 (assigner developer, 03:22)** The assigner's pins of assignment graph revisions go whole (the state `pins`,
|
||||
the tools `assigner_pins` and `assigner_unpin`, the hearer of the gate's pin events): nothing feeds them once the gate's
|
||||
pin operations are gone (H-A-28, H-A-48). An assignment graph revision that is not current and that no want or
|
||||
running build names is removed at the same judging moments as today, pins aside. P7; §764.
|
||||
- **H-A-87 (gate-and-forge developer, 03:24)** (1) The forge module's whole test is a Go integration test that runs
|
||||
its bundle against an embedded bus (H-A-61 stands over §774's "TypeScript"; §774 is read so). (2) The gate's source
|
||||
key is read with the same escaping it is written with (the fault in `merges.go`, where `Set` escapes the branch and
|
||||
`Read` does not): fixed in GATE-9 with a test for a branch holding `/`. P3.
|
||||
- **H-A-88 (assigner developer, 03:27)** The seat mesh-wants' `StepRun` gains `asker`, the seat name of the part asking
|
||||
the step (the runner writes `mesh-pipeline-runner`), a small commit C-W2 by the contracts-indexer-bridge developer;
|
||||
the assigner names a step's progress with that asker (A11, H-A-41). P8.
|
||||
- **H-A-89 (gate-and-forge developer, 03:29; the record's pipeline families, §738)** All five as recommended: (1) each
|
||||
per-mover step result becomes one record outcome, its step the result's step, its outcome the result's own word
|
||||
(passed, failed, nothing to run, bypass), its why the result's, the entry (module, fingerprint, no node). (2)
|
||||
`wait-ended` writes over `wait-held`'s `held` under the same outcome key, the outcome the wait's `how` (answered,
|
||||
ran, superseded). (3) A `pipeline-ended` not passed (failed, refused, cancelled, superseded) ends the record `failed`
|
||||
naming the pipeline's why. (4) `pipeline-wanted` with outcome `running` ends the record (every tier's movers run on
|
||||
every present placing machine); `running` events are still written as running-healthy outcomes; `tier-late` ends it
|
||||
`failed` naming the movers and machines not running. (5) The trace's `from` is the lowest and `to` the highest
|
||||
assignment graph revision of this pipeline's `wanted` events, each want an entry (module, fingerprint, node) with
|
||||
outcome `wanted`; a removed want writes nothing. P3, P7.
|
||||
- **H-A-90 (indexer developer, 03:31)** (1) mesh-sdk gains `process.Account.NamedEventConsumer(ctx, js, stream, suffix)`,
|
||||
binding the durable `<node>_<module>_<suffix>` (the seats developer's subtask); the indexer binds one per watched
|
||||
branch with the escaped branch as the suffix (§743). (2) The indexer binds a newly watched branch's consumer on its
|
||||
own `registration-changed`, not only at its start. P1, P8.
|
||||
- **H-A-91 (bridge developer, 03:34)** (1) A newly registered branch adopted while the bridge runs says `head-moved` with
|
||||
`start` true, like the start pass: `start` means "a read of the head, not a move", so the indexer takes it in as the
|
||||
branch's first revision with no movers (§745). P8. (2) The watchman's `delivery-waits` finding goes with
|
||||
`acting-part-late` (§764), in the same pass. (3) The seat mesh-delivery's contract drops the owed act `merge`
|
||||
(OwedActMerge), a small commit C3b by the contracts developer; the bridge's refusal of it as undecodable then has
|
||||
nothing to refuse. P7.
|
||||
- **H-A-92 (indexer developer, 03:37)** A catalog revision carries its movers (option c): a redelivered `source-moved`
|
||||
whose revision is already kept says `take-in.taken` again from the kept revision's movers, recomputing nothing, so the
|
||||
pin judge may remove the revision before as today and a restart between the write and the acknowledgement loses
|
||||
nothing. P3 (an idempotent re-say), P7 (no extra kept revision, no extra record).
|
||||
- **H-A-93 (gate-and-forge developer, 03:41)** The forge module's finding `step-unread` (G §585) is one per unread
|
||||
step: scope `module`, its subject the step's module, its key `<run>.<module>.<step>`, severity warning, resolver
|
||||
operator, no owner, cleared by that step's later `step-ended` carrying its fingerprint; the body's `fingerprint`
|
||||
alone is read. P3, P8.
|
||||
- **H-A-94 (readers developer, 03:42; the watchman)** (1) The watchman learns the bus-state entries a mover's manifest
|
||||
asks for from the mover's catalog entry, read by fingerprint through the seat mesh-catalog's verb, never from a
|
||||
retired event (P1, P9); `bus-state-overdue` stays, timed from `take-in.taken`. (2) Its take-in reader is rewritten now to
|
||||
the seat's `TakeInTaken` and `TakeInPending`, seeded from `indexer_pending`'s answer in the contract's form
|
||||
`{branch, source, why}` (build against the contract, not an indexer commit); the wait's key is `<branch>.<source>` and its
|
||||
`since` the message's own time; the bound is the watchman's setting `take-in-bound`, default 60 minutes; the
|
||||
30-minute group bound goes (§764). (3) §741: the watchman learns no head; the head timing of pipelines.go goes with
|
||||
its source-moved reader's change. P3, P11.
|
||||
- **H-A-95 (readers developer, 03:44)** (1) A want with `hold` (awaiting its hand placement, §772) is not timed by the
|
||||
watchman: a hold is not progress owed (as H-A-14 reads a waiting pipeline). (2) The Owed definition's `ask` and
|
||||
`group` fields, kept "for a merge", go with the act (C3c, the contracts' writer); nothing reads them. P7.
|
||||
- **H-A-96 (runner developer, 03:48)** The runner's state `queue` gains a third key form `running.<pipeline key>` with
|
||||
value `{pipeline}`, written by compare-and-set when a pipeline is placed and deleted at its end, its cancel or its
|
||||
approval wait; `pipelines-at-once` is judged against the `running.*` keys alone (a C-R3 field, the contracts' writer).
|
||||
P1, P3; H-A-60 holds (the runner reads only its queue keys).
|
||||
- **H-A-97 (indexer developer, 03:49)** A held take-in is kept in a small indexer state `held`, one key per branch
|
||||
`{branch, source, why, since}`, written when a `source-moved` is held and deleted at its take-in or skip (option c):
|
||||
`indexer_pending` reads it, and the watchman seeds from it (H-A-94). P4 (what the module holds is read, not derived
|
||||
from a scan of events), P3 (`since` is kept for the bound). The retired state `pending` was the pending revision of
|
||||
the manifest validation (ADR 0633 §1); this is not it. `indexer_take_in_pending` and `indexer_take_in_skip` are asks in
|
||||
the state `takeins`, the existing hand-act path. P7.
|
||||
- **H-A-98 (runner developer, 03:50)** No shared follower exists, so in H1 each consumer's own handler refuses an
|
||||
old-form event: the contract's strict decode (a required field such as `call` missing) is the refusal, the handler
|
||||
writes one journal line naming the subject and ends the message. H-A-58's "shared follower" is read so for H1; a
|
||||
shared shape, if any, is H4's with the wake-up rule. P3, P7.
|
||||
- **H-A-99 (assigner developer, 03:51)** The placement's `build` is read as the want's target before the rule (option
|
||||
b): the want's `fp` is that build and its `version` the one released at it, with no pipeline, no rank and no put steps;
|
||||
`placementPuts` goes. "Read before the rule" literally, with no hold. P7.
|
||||
- **H-A-100 (gate-and-forge developer, 03:51; the forge module's merge-check machinery)** As recommended: the poll that
|
||||
goes is the pass's pull-passing half with its 60-second retry, the timer the 10-minute keep-main-rules step (it keeps
|
||||
a protection ADR 0682 §13 no longer judges); the repository poll (`repo.created`) and the start's whole read stay.
|
||||
`announceHead` goes whole with its pending status and sibling weighing; `pull.updated` is said by the webhook path
|
||||
alone; the poll of merged and closed pulls stays. The seat verb `status` writes a head's status through the client
|
||||
directly; `GateWriter` and its chain go. P7; §764.
|
||||
- **H-A-101 (runner developer, 03:52)** (1) The runner's verbs `rerun`, `accept` and `ask-again` name the mover's
|
||||
`module` beside the pipeline and step, so a pipeline of several movers is never ambiguous (a C-R4 change of the
|
||||
runner's seat by the contracts' writer); a call naming no module on a pipeline of one mover is taken as that mover.
|
||||
P8, P3. (2) A step of a mover whose dependency did not build ends with its own `step-ended`, outcome `not asked`,
|
||||
naming the dependency, so nothing ends silently. P3.
|
||||
- **H-A-102 (readers developer, 03:53)** `indexer_pending` answers `{"held": [{branch, source, why, since}]}`, `since`
|
||||
in RFC 3339, one form with the indexer's state `held` (H-A-97); the watchman reads it with a local type over the
|
||||
seat's `TakeInPending` plus `since`. P7, P8.
|
||||
- **H-A-103 (indexer developer, 03:55; two things held in memory)** (1) Between take-ins the indexer's view of a module
|
||||
change (a build's imports, a toolchain change, the reconcile) is derived state: the kept revision is the truth and a
|
||||
restart rebuilds the view from it and the events after it, so nothing kept lives only in memory. (2) A held
|
||||
message's acknowledgement handle is the bus consumer's; after a restart the bus redelivers the message and the state
|
||||
`held` says why it was held. Neither is a kept truth in memory; the review reads them so. P2, P3.
|
||||
- **H-A-104 (assigner developer, 03:57)** (1) The assigner keeps each node's words in its own state `engine-reads`
|
||||
(key the node, value `{words, at}`), written when it hears `manifest-reads-changed`, so a restart loses no node's
|
||||
words and no verb is asked; the shared client stays as it is, used for the event alone. P1, P2. (2) `RefusedCycle`
|
||||
moves into `mesh-delivery-sdk/graph` on the contracts branch (a small commit by the readers developer, the branch's
|
||||
writer of shared code), so the assigner's `validate` step and the indexer both read it from there (H-A-34). P9.
|
||||
- **H-A-105 (indexer developer, 03:59)** (a) `indexer_take_in` goes whole with the builder-log index (H-A-48, §742:
|
||||
the gate's `gate_head_take` is the one hand take of a head and nothing else delivers an untaken head; acceptance
|
||||
test 36 and G-5's restore step are corrected to name `gate_head_take` when the design is next amended). P7. (b) The
|
||||
run candidate's check of a module named twice with different manifests stays: it guards a run on request, which
|
||||
stays (H-A-58); only the pull-request candidates go. P7.
|
||||
- **H-A-106 (runner developer, 04:06; the queue)** (a) A start over the cap is written as an ordinary waiting pipeline
|
||||
(its value `waiting`, its `waiting.<seq>` key) beyond the cap; `queue-full` is raised naming it and cleared when an end
|
||||
brings the waiting count back to the cap or below; nothing is left unacknowledged (H-A-36 over §748's wording). P1,
|
||||
P3. (b) A pipeline whose approval is answered and still runs has its `running.<pipeline>` key written at once, over the
|
||||
bound, since it asks nothing new but its end; "waiting on its approval step" means every step not ended is an approval
|
||||
asked of the operator. P3. (c) `pipelines-stalled` and `queue-full` have the kind as their id, severity warning, no
|
||||
owner (the operator's), like `pipeline-failed`'s writer. P8.
|
||||
- **H-A-107 (runner developer, 04:09)** The pipeline value keeps `superseded`, the modules a newer queued take-in took out
|
||||
of it (written with the movers by compare-and-set; a C-R5 field of the seat, the contracts' writer); at the pipeline's
|
||||
placing the runner writes a mover's build-step why from it (H-A-53). P1, P4.
|
||||
- **H-A-108 (assigner developer, 04:10; the validate step)** All four as recommended: (1) the revision's validate run is
|
||||
a key `<pipeline>.validate` of the state `composition-runs` in the CompositionRun form with no machine, taken up at
|
||||
start like the composer's runs (P1, P7); (2) the validator's request carries no predefined key list and no known
|
||||
package names until a design line names the verb that gives them: the validator takes every fallback as declared and
|
||||
judges no package name (P7); (3) "a manifest the revision alters" is judged against the branch's previous revision,
|
||||
read through the seat mesh-catalog's verb `revision` (P1); (4) one run, one verdict per revision: every mover's
|
||||
validate step ends the same, failed with `manifest-refused` naming every problem of the revision (P3).
|
||||
- **H-A-109 (readers developer, 04:12; the view's held take-ins)** A held take-in names no module in the view: its
|
||||
movers are not known until it is taken in, so the view says the branch's held take-in in the tiers' pending words
|
||||
(branch, source, why, since) and holds no module for it (option b). P3 (no module named on a guess).
|
||||
- **H-A-110 (node-engine developer, 04:13)** Within one link, the node-engine asks its unanswered entries again when it
|
||||
hears the seat mesh-catalog's `catalog-revision` (one per take-in): the composer consumes that event for this alone and
|
||||
calls the entries client's `AskAgain`; and once more at each link's start. No timer. P1.
|
||||
- **H-A-111 (node-engine developer, 04:15)** With no verdict state (H-A-79, ADR 0682 §4), the node-engine's reading of
|
||||
a taken module (frombus `taken`) drops the verdict branch and decodes the manifest alone: a module in a catalog
|
||||
revision is accepted by being there; the validate step judged it before any want. P7.
|
||||
- **H-A-112 (node-engine developer, 04:18)** The composer (mesh-compose) likewise drops the verdict branch of its parse
|
||||
and its case verdict, and the request field `Case.Verdicts` goes: its one writer was the checker, which goes in H1
|
||||
(H-A-57); the assigner's composition step sets no verdicts (H-A-108: the validate step judges before the composition
|
||||
step). P7.
|
||||
- **H-A-113 (readers developer, 04:20; the grants part)** (1) `grants_callers` goes whole with the callers lists;
|
||||
`grants_why_refused` stays, answering the bus's own verdict for the account and the verb's call subject (a refusal
|
||||
is still readable, P4). (2) §752 and ADR 0682 §10 mean every verb of every seat: the grants part grants each module's
|
||||
account every seat's verbs, not only the seats its manifest invokes (acceptance test 118's case); that change is this
|
||||
developer's, in the same pass. P6.
|
||||
- **H-A-114 (indexer developer, 04:40; a held take-in across a restart)** A held take-in is acknowledged on the bus and
|
||||
kept only in the indexer's state `held` (H-A-97); the indexer takes the held ones in again from that state on its own
|
||||
`room` and at its start. No message stays unacknowledged, so the consumer's acknowledgement wait bounds nothing and a
|
||||
restart loses nothing; H-A-12's and H-A-50's "held, unacknowledged" are read so. P3 (a stuck message for the length of
|
||||
the acknowledgement wait would be a silent failure), P2.
|
||||
- **H-A-115 (indexer developer, 04:40; the movers' code dependents)** In H1 a code dependent of a mover is a module
|
||||
whose Go module requires the mover's (the go.sum reading built), which moves a module that requires the package
|
||||
without importing a changed package; the finer reading by imported package is H2's refinement of the same line
|
||||
(§743, A-476a). P7 for H1, said.
|
||||
- **H-A-116 (readers developer, 04:43; the builder's floor)** In H1 the builder's version floor wakes on every
|
||||
`take-in.taken` (it consumes the indexer's `take-in.taken` in place of the retired `manifest-accepted`, H-A-49) and
|
||||
looks at every module again as it does today; the finer wake on a mover's new entry is H2's with the builder's own
|
||||
lines. The mechanical changes SDK-C forces on the builder's seat-list calls are in scope. P1, P7.
|
||||
- **H-A-117 (build-modules developer, 04:57)** The build seats' step kinds `check` and `recheck` stay in H1: they carry
|
||||
the composer's and the validator's runs (a compose or run ask is kind `check` of the Go seat), and §753's queues are
|
||||
H2's to rename with the builder's lines; H-A-57 is narrowed to the checker's seat, its copies and its own verdict
|
||||
verb. The runs' input moves from the checker's `input` to the seat mesh-wants' `input`, which the assigner serves
|
||||
(H-A-34), not to mesh-catalog. P7; rules-are-weighed, said.
|
||||
- **H-A-118 (join developer, 05:03; the held take-in's form)** (1) The state `held`'s value carries the held
|
||||
`source-moved` whole beside H-A-97's four fields: `call`, `heads` and `start`, so a take-in after a restart reads
|
||||
nothing from any verb (P2). (2) A later `source-moved` of a held branch is held behind the earlier one: the branch's
|
||||
key holds its held events in order, each acknowledged once written there, and the indexer takes them in in that order
|
||||
on `room` and at start; no source revision ends silently (P3).
|
||||
- **H-A-119 (join developer, 05:09; the teller)** `pipeline-ended`'s per-mover entry gains `commit` and `widens`
|
||||
(a C-R6 change of the runner's seat, the runner writing them from its pipeline value), so the teller says one widening
|
||||
per mover from the event alone and reads no other module's state (P10, P1). The teller's hearing of `record-opened`
|
||||
and its consume go: the record's H1 form carries no forge-made, and §763 retires acceptance test 53's rows (P7).
|
||||
- **H-A-120 (fixer, 05:29; the build seats' queue order)** The build seats serve their kinds in turn, as lead answer
|
||||
A-440 (the operator's yes of 2026-11-15) decided and the code since 2026-11-15 does; the red test still asserting ADR
|
||||
0525 §4's deliveries first is corrected to the turns (delivery, check, delivery), citing A-440. H-A-8 and H-A-51's
|
||||
"deliveries first" were wrong: a line existed. ADR 0525 §4 gets a progressive insight in H2 with the builder's lines.
|
||||
P7 (build what the last decided line says).
|
||||
- **H-A-121 (the clean state's drop tools, 05:46; corrected 05:52)** The plan's step 5.8 needs tools no module serves
|
||||
(the reader of 05:43): (1) the bus module gains two tools beside the seat mesh-broker's verbs: `nats_drop_bucket`
|
||||
(bucket, why: drops one named bucket after a snapshot) and `nats_consumer_delete` (stream, durable, why: deletes one
|
||||
durable consumer); both written in the hand-act log. They are the operator's hand tools for one module's own kept
|
||||
data, not a need another module fills: a module tool, not a seat verb (P9; the seat's definition stays as reviewed).
|
||||
(2) `gate_record_end`, `assigner_want_drop` and `indexer_pin_drop` take an `all` form (every open record, every held
|
||||
or failed want, every stale pin) beside their one-item form, each saying what it dropped, counted. (3) The source
|
||||
bucket's old keys go by `nats_drop_bucket` of that bucket before `gate_source_seed`. Built in H1 on the H1 branches as
|
||||
the clean state's own tools. P4 (everything that goes wrong can be recovered through tools), P3.
|
||||
- **H-A-122 (the mail reader's callers list, 05:52)** Goes, like every other holder's (H-A-41, H-A-66; ADR 0682: every
|
||||
account may call every verb). The mesh has one user and is assumed not compromised (the operator, 2026-11-11); who
|
||||
inside the mesh may read mail through a verb is who-may, a design detail, not public exposure: nothing here puts mail
|
||||
outside the mesh. ADR 0459 §2's protection of mail data stays in what the verbs answer, not in who may call them. P1.
|
||||
- **H-A-123 (what `assigner_want_drop all` drops, 05:53)** There is no failed want: a want has `hold` and nothing
|
||||
else that marks a fate (the node-engine's report of a failed have is the node-engine's state, not the want's). The
|
||||
`all` form drops every want key in the wants bucket, held or not, and every value of an earlier form the decoder
|
||||
refuses; it answers the count per kind (held, current, undecodable). The clean state drops every want before the
|
||||
seed (plan step 5.8; the operator, 2026-11-20: old data may go). H-A-121 (2) is read that way. P4.
|
||||
- **H-A-124 (what `indexer_pin_drop all` drops, 05:56)** Every pin in the indexer's pins state, as H-A-123 drops every
|
||||
want: the indexer knows a running pipeline only through its own pins, so no other reading of "stale" exists without
|
||||
a read of another module's state (P9 forbids it). The `all` form is the clean state's tool, run while no pipeline
|
||||
runs (plan step 5.8, after the runner is stopped); it answers the count dropped and the pipelines they named. P4, P9.
|
||||
- **H-A-125 (the knowledge base's delivery block, 05:58)** Goes whole: the overview's delivery source, its
|
||||
`delivery-groups` block, the progress verb's groups lines, and with them the knowledge base's consumes of
|
||||
`pull-merged`, `transition` and `group-ended`; `pipeline-ended` is then not consumed by the knowledge base at all,
|
||||
which corrects H-A-44's reading. The block showed another module's state (the deliveries), which only the status view
|
||||
owns (P9: a module's state is read through its owner's view, never copied); a pipelines block belongs in the status
|
||||
view and is parked as an idea, not built in H1. Told to the operator as a change of what they see: the knowledge
|
||||
base's overview page no longer shows deliveries. P9, P5.
|
||||
- **H-A-126 (the bus module's drop tools exist; H-A-121 (1) withdrawn, 06:12)** No new tool: the bus module already
|
||||
serves them (the developer's reading of 06:11). A retired state bucket (the gate's `merges`, a seat's `asks` and
|
||||
`turns`, mesh-config's `pulls`, the indexer's `pending`) is kept data no accepted manifest asks for once H1's
|
||||
manifests are taken in, so the keeper's `nats_drop` drops it, by warrant, after its snapshot, as today. The source
|
||||
bucket's old keys go by `nats_bucket_remove` with the prefix, before `gate_source_seed`. A durable consumer goes by
|
||||
`nats_consumer_remove`; it refuses only a consumer an accepted manifest asks for, and no longer every consumer of a
|
||||
kept-data stream: one no manifest names is an orphan on that stream, removed by warrant (`why` required) and
|
||||
written in the hand-act log as the keeper's requests are. The clean state's step 5.8 names these three. P4, P7 (no
|
||||
second tool for one act).
|
||||
- **H-A-127 (`nats_consumer_remove`: what it refuses and what warrants it, 06:16)** (1) No manifest field names a
|
||||
durable; the mesh names a module's durable `<node>_<module>`. The tool refuses a durable whose name is that form for
|
||||
a module of an accepted manifest on that node (the keeper's accepted set), on any stream; every other durable is an
|
||||
orphan and goes. The judgement is by name, not by stream (H-A-126). (2) `why` is the warrant: the tool acts at once
|
||||
and writes the hand act through mesh-hand-acts as `nats_bucket_expiry` does. The clean state runs at the operator's
|
||||
terminal, so an ask of the operator would answer the operator's own call (P7). P4, P7.
|
||||
- **H-A-128 (`nats_consumer_remove`: the name rule is a prefix, 06:24)** H-A-127's rule is read as a prefix: a durable
|
||||
is a module's when its name is `<node>_<module>` or begins with `<node>_<module>_` for a module of an accepted
|
||||
manifest on any node (the keeper's accepted set holds modules, not nodes; the developer's reading of 06:23), since a
|
||||
module may name more than one durable with a suffix. The tool refuses those and removes every other. P3 (a wrong
|
||||
removal of a live consumer is a silent failure), P4.
|
||||
@@ -22,7 +22,10 @@ try in process. Four more carry playbook 07: `mesh-preparer` (the prepare step),
|
||||
`mesh-code-reviewer` (the review) and `mesh-watcher` (every wait). A tenth, `hq-design-writer`, writes one set of design amendments
|
||||
(playbook 02, *Amending an existing design*) from accepted decisions and a milestone's findings, in a worktree of its
|
||||
own, ready for the review by architectural domain. An eleventh, `hq-record-writer`, proposes one decision record or
|
||||
research effort to the knowledge base from a draft (playbooks 01 and 02) and follows its review to approve. An agent that researches, decides, designs or reviews a design starts
|
||||
research effort to the knowledge base from a draft (playbooks 01 and 02) and follows its review to approve. Two more serve a design
|
||||
delivered again part by part (design 47, milestone H): `spec-reader` writes one part's specification from the design and its
|
||||
records (no code read), and `gap-surveyor` holds main's code against that specification and writes the part's gap table
|
||||
(read-only on the mesh and every working copy). An agent that researches, decides, designs or reviews a design starts
|
||||
from the knowledge base and maps each interaction onto a mesh path. An agent that prepares, builds or reviews code
|
||||
starts from the milestone's part of its design alone, builds what its design lines say, and decides nothing: what
|
||||
the design does not answer is a design question, answered in an hq commit before any code (playbook 07). The prepare
|
||||
|
||||
Reference in New Issue
Block a user