Merge pull request 'Design 47, milestone H: the plan to deliver the build-and-delivery system properly' (#737) from plan/47-deliver-properly into main
This commit was merged in pull request #737.
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,430 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H
|
||||
updated: 2026-11-20
|
||||
decisions:
|
||||
- "ADR 0666"
|
||||
- "ADR 0667"
|
||||
- "ADR 0681"
|
||||
- "ADR 0548"
|
||||
---
|
||||
# 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.
|
||||
|
||||
## 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); the node-engine reads every node's
|
||||
record key (§459 forbids it); wants are not written from the kept assignment graph revision. Medium each, H1.
|
||||
- **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 kick-off a person forgets is a silent non-delivery) and proposed the merge through
|
||||
the mesh as the kick-off 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.
|
||||
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. **Drop the stale state** (question 2's yes): the buckets, the records, the pins, the stuck pipelines, the held and
|
||||
failed wants, through each module's tools where one exists (the surveyor found none for the bucket contents; the
|
||||
pack carries the one-off deletion and says what it deleted, counted). 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.
|
||||
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, 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), 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.
|
||||
@@ -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